{"id":15448557,"url":"https://github.com/w3f/messaging","last_synced_at":"2025-10-11T12:31:31.122Z","repository":{"id":66120238,"uuid":"146450514","full_name":"w3f/messaging","owner":"w3f","description":"Messaging for Web3","archived":false,"fork":false,"pushed_at":"2022-09-28T09:57:24.000Z","size":25867,"stargazers_count":169,"open_issues_count":20,"forks_count":12,"subscribers_count":35,"default_branch":"master","last_synced_at":"2025-01-28T21:38:59.094Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"TeX","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/w3f.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2018-08-28T13:19:10.000Z","updated_at":"2024-09-11T09:15:42.000Z","dependencies_parsed_at":"2023-11-14T08:00:17.870Z","dependency_job_id":null,"html_url":"https://github.com/w3f/messaging","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/w3f/messaging","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/w3f%2Fmessaging","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/w3f%2Fmessaging/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/w3f%2Fmessaging/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/w3f%2Fmessaging/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/w3f","download_url":"https://codeload.github.com/w3f/messaging/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/w3f%2Fmessaging/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":279007167,"owners_count":26084247,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-10-11T02:00:06.511Z","response_time":55,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2024-10-01T20:29:11.012Z","updated_at":"2025-10-11T12:31:29.224Z","avatar_url":"https://github.com/w3f.png","language":"TeX","readme":"# A Decentralised Privacy-Preserving Communication Protocol\n\n\u003e Messaging for Web3.\n\n## Motivation\n\nWe need communications protocols that protect metadata, partially as an ethical end goal and partially for business reasons, but also as a fundamental building block of decentralised applications.  \n\nWe cannot control all information asymmetries, especially the metadata observed by large infrastructure providers.  Yet, information asymmetry or symmetry are an extremely important assumption in economics models.  We thus consider increasing our control over information asymmetry to be an essential building block, which makes privacy a crucial tool, including metadata protection. \n\nWe have witnessed adoption of centralised messaging solutions being influenced by users' perceptions of privacy, at least at a personal level.  We thus believe providing real metadata protections should help establish a stable user base, which may help solidify or stabilise other services provided by the protocol, including associated financial services.\n\nWe also consider privacy to be a fundamental human right.  Article 12 of the Universal Declaration of Human Rights names \"privacy\" and \"correspondence\" for protection, which logically covers metadata.  \n\n\n\n\n\u003e No one shall be subjected to arbitrary interference with his privacy, family, home or correspondence, nor to attacks upon his honour and reputation. Everyone has the right to the protection of the law against such interference or attacks.\n\n\nWe also believe that user anonimity and stronger privacy protections aid adoption. \n\nIf we lack metadata protections, then infrastructure providers will act as adversaries who collect and abuse user data in a myriad of ways, such as by adjusting prices, employing strategic voting, front running, etc.  \n\n### Whisper\n\n\nIn the current decentralised application landscape, we are seeing projects\nstruggle to achieve mainstream adoption. We believe that the underlying\nprotocols do not have sufficient capability to enable the necessary level of\nadoption. Part of the problem is that these applications often require the\nexchange of transient messages; however, it does not make sense to transmit\nthese messages via a blockchain. Gavin Wood realised this problem in the early\ndays of Ethereum, and suggested that DApps would require a decentralised\nmessaging protocol that would provide this capability. This protocol is called\n[Whisper](https://github.com/ethereum/wiki/wiki/Whisper).\n\nUnfortunately, the evolution and adoption of Whisper has been stunted, which is\ndespite the rapid advancement of applications. The lack of development means\nthat Whisper is not able to provide the scaling that we need, nor is it feasible\nfor projects to create their own bespoke messaging protocol. What we really need\nis a new protocol to handle transient messaging at scale. We believe this is a\nnecessary cornerstone for enabling the mainstream adoption of DApps.\n\n## Project\n\nWe would like to gather a number of projects together to align and support this protocol:\n- Researchers\n   - Academia\n   - Web 3 projects\n- Protocol implementers\n   - Core dev teams from Web 3 space\n- Application builders\n  - User messaging application\n  - State channels\n  - Latency-agnostic streaming protocols\n  - Other applications requiring transient messaging\n  \n**The goal is to end up with at least one viable implementation, spec and a theoretical\nanalysis of the protocol properties.**\n\nThe idea is to start with gathering requirements and aligning on goals, the Web3\nFoundation (W3F) has discussed with a number of projects to better understand\nwhat the needs are. W3F has also started to do an initial exploration of\npotential components to be used in the protocol.\n\n### Plan (to be evolved)\n\n1. Refine this document to reflect the motivation, requirements for the\nproject and initial mapping of the space until initial contributors are happy with it.\n2. W3F to organise a workshop with all the relevant parties\n3. Come up with clear work packages to be done by all contributors.\n4. Readjust the plan together with the project contributors.\n5. Achieve the goal.\n\n### Project contributors (in alphabetical order)\n- [Status](https://status.im)\n- [Validity Labs](https://validitylabs.org) - [HOPR](https://github.com/validitylabs/hopr)\n- [Web3 Foundation](https://web3.foundation)\n\n\nTo contribute your project will need to commit some time to help specifying the motivation, requirements and mapping of the solution space. Following that contributors will be invited to participate in a joint workshop.\n\n## Role of the protocol\n\n| Layer | Purpose | Examples |\n| ----- | ------- | -------- |\n| Application | Application logic | Chat app |\n| Storage / Sync | Sync data, make messages persistent | |\n| -\u003e **Protocol**, **DHT** \u003c- | Scalable, decentralised metadata protection | |\n| P2P | Overlay routing, NAT traversal | [libp2p](https://libp2p.io), [WebRTC](https://webrtc.org) |\n| Network | Underlay routing | [TCP / IP](https://en.wikipedia.org/wiki/Internet_protocol_suite) |\n\n## Adversary model\nFor the adversary model, see [a detailed description](./ADVERSARY.md)\n\n## Protocol requirements\nFor a more detailed description, see [a detailed description](./REQUIREMENTS.md) of the below listed requirements.\n\nMetadata protection:\n\n**1. Sender Anonymity** (who sent a message?)\n\n**2. Receiver Anonymity** (who read a message?)\n\n**3. Sender-Receiver Unlinkability** (who is talking to whom?)\n\nConvenience, Usability:\n\n**4. Reasonable Latency** (\u003c5s, to allow for IM [XXX])\n\n**5. Reasonable Bandwidth** (not specified, mobile data plan in undeveloped countries)\n\n**6. Adaptable Anonymity** (adjustable resource consumption)\n\nDecentralization:\n\n**7. Scalable** (up to, say, ~1M active nodes)\n\n**8. No Specialized Services** (pure p2p)\n\nIncentives to achieve mass adoption:\n\n**9. Incentivisation for relayers** (not necessarily economical)\n\n\n### Things that are explicitly out of scope\n- Trust Establishment - provenance of long term keys to some known identity\n- Conversational Security - authentication, confidentiality, integrity, perfect\n  forward secrecy, accountability.\n\nAdditionally, see below for other things that may be out of scope at this layer.\n\n## Questions\n\n### What about Incentives?\nThe Protocol will be used in conjunction with Ethereum and similar technologies.\nThere's also a strong need for incentive-compatible designs. This means it is\nuseful to consider incentives and payment mechanisms as the protocol layer.\nHowever, an ideal protocol suite should be layered and have a clear separation\nof concern. This means there's a simple design with minimal dependencies. As\ninspiration,\nsee\n[Bittorrent economics paper (pdf)](http://users.eecs.northwestern.edu/~hq/papers/communities.pdf),\nwhich is a separate protocol layer that people can choose to use or not to get\nbetter quality of service (request and choking).\n\n### What about Message Reliability?\nThe protocol should do Best Effort Delivery. Reliable Delivery can be provided\non top, similar to TCP/IP (or BSP/BTP for Briar), to accommodate things like:\n\n- Guaranteed Message Delivery\n- Message Ordering\n- And possibly: Asynchronous Messaging (some protocols deal with it at this\n  layer, so this may or may not be desirable)\n\nDepending on the specifics of the reliability mechanism, throughput etc, this\nmay have consequences for the above Reasonable Latency requirement. The\nReasonable Latency requirement outlined above is for End to End messaging.\n\n### How to deal with Network Spam?\n- One approach is to use a Friend-to-Friend (F2F) network. This is what Briar\n  and Secure Scuttlebutt (SSB) does.\n- For open DHT-based, another approach is to rely on proof of work like Whisper.\n  This isn't very practical for mobile / resource restricted devices, and\n  appears to have limited usability.\n- More approaches are likely possible, such as traditional rate limiting, basic\n  peer reputation, payments, etc.\n- Global network attacks more relevant here than a specific node. What does this\n  imply for a DHT?\n\n### How to deal with Asynchronous Messaging?\n- One approach is to punt this problem to data sync layer.\n- Another example is Briar requiring two entities to both be online\n- Not clear that it is a necessary component of AC layer.\n- One idea is to use Aggregation Points (Xolotl, lake mixnet) as providers\n  similar to Loopix, but presumably with less HA guarantees.\n\n## Initial work\n\n###  Network\nWe would like to develop a protocol that leverages the best research and\nprotocols from the past in order to create something for the future of\ndecentralised applications. We want a “roadmap without potholes” for providing\nstronger privacy assurances than Tor for both senders and receivers, while also\nscaling well and providing short-term message storage for offline users. In\nother words, we accept that a project this large requires a piecemeal approach\nbut we shall understand and avoid design dead ends that prevent either scaling\nor rigorous analysis of anonymity properties.\n\nWe think mix networks occupy a sweet spot in which nodes run extremely efficiently but rigorous analysis remains possible, if challenging.  There are designs like Tor with more efficient designs, but they cannot provide rigorous anonymity properties.  There are also numerous academic schemes designed to support rigorous analysis, but at extreme sacrifices in efficiency.  We choose a Sphinx-like packet format because it’s efficient, adaptable enough, and has good security proofs.  \n\nWe leave actually analyzing our scheme for future work in collaboration with academics.  We shall however use Poison mixing and cover traffic strategy similar to Loopix, which appears analyzable although academic work to do so remains ongoing.  We concede that mix networks impose latency on users, but any faster design would definitely not admit rigorous analysis of anonymity properties, and could not credibly claim to be stronger than Tor.  \n\nWe shall tweak Sphinx slightly to accommodate both receiver anonymity and\nshort-term message storage simultaneously, which may require updating its\nsecurity proofs eventually. We consider short-term message storage essential to\nuser experience and advise against doing it via a second layer protocol.\n\nWe foresee the public key infrastructure (PKI) being the ultimate scaling\nbottleneck for all existing anonymity scheme designs. We could avoid this with\ngossip protocols but these enable epistemic attacks. We largely leave this to\nfuture work, but suggest investigating a verifiable gossip based protocol. We\nshall therefore use an insecure gossip based protocol initially with the hope\nthat it meshes best with later designs. If we used a more secure design inspired\nby the Tor consensus, then we might make assumptions elsewhere that limit scalability\nlater.\n\nWe know rewards for node operators remains a contentious question in the\nanonymity community with seemingly unforeseeable consequences. We nevertheless\nthink rewards represents our best hope for a network large enough to challenge\ntoday’s centralized providers that operate on surveillance capitalism. We do not\nimagine rewards obliviate the need to steward relay operator culture, possibly\nquite the opposite.\n\n### Messaging types\nWe’re focusing on one-to-one messaging for now.  We actually do require messaging layer crypto, even after all the mix net layers, so expect an Axolotl-like ratchet for this.  \n\nWe can adapt our short-term message storage plans for small group messaging, but\nnot with exactly the same privacy assurances. We leave designing this to future\nwork.\n\nWe think one-to-mass messaging should be done by using the mix network to send\nto a broadcast protocol like Whisper v1 or perhaps a blockchain.\n\n### Payment\nWe’re designing an accounting scheme to prevent abuse and reward nodes, without\ndamaging users’ anonymity. We’re currently working on several designs based on\nfundamentally different methodologies, primarily payment channels, blind\nsignatures, and secret shopper, so as to more fairly evaluate them. We’re\nkeeping these designs as agnostic as possible to questions like if the users\nactually pay anything ever.\n\n### Implementation\nIn order to leverage existing work done in the space we would like to leverage\nlibp2p for networking and make sure that at least one implementation is fully\nrunnable in the browser leveraging Javascript and Wasm.\n\n## Copyright\n\nCopyright and related rights waived via [CC0](https://creativecommons.org/publicdomain/zero/1.0/).\n","funding_links":[],"categories":["Repositories"],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fw3f%2Fmessaging","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fw3f%2Fmessaging","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fw3f%2Fmessaging/lists"}