# MuWire Design MuWire operates a Web-Of-Trust layer on top of a Gnutella-like topology on top of I2P. To understand the rest of this document, it is important to understand the following terms: * I2P terms: * Destination - a cryptographic abstraction which represents a destination in the I2P cryptospace. It is not possible to correlate a destination with an IP address in the clearnet. While IP addresses and I2P Destinations share a lot in common, there are some important differences. The one most crucial to the design of MuWire is that I2P Destinations are always directly reachable, i.e. they are never behind a firewall. * I2P datagram - similar to clearnet UDP datagram. Can be signed or raw; MuWire only uses signed datagrams, which are datagrams containing the sender's Destination and can be replied to. * I2P streaming - similar to clearnet TCP/IP protocol. * Gnutella terms: * Leaf - a node in the Gnutella network which indexes only content shared by the local user. Leafs do not route queries and connect only to ultrapeers * Ultrapeer - a node in the Gnutella network which listens for incoming connections from leafs, indexes (loosely) their content and routes search queries to other ultrapeers and leafs. * MuWire Persona - each MuWire node operates a single Persona. For complete definition, see the "web-of-trust" document. ### Initial Bootstrap Initial bootstrap into the MuWire network is done in a similar fashion to Gnutella. Dedicated bootstrap servers ("HostCaches") listen for incoming I2P Datagrams which contain requests for addresses of ultrapeers. The incoming signed datagram has a flag whether the requesting node is an ultrapeer or a leaf; if the node claims to be an ultrapeer it may be added to the list of known ultrapeers by the HostCache. Implementors of HostCaches are free to choose other discovery strategies such as crawling, active polling and so on. In response to the request, the HostCache sends back an I2P datagram containing Destinations of chosen ultrapeers. For ease of implementation, the response datagram is also signed and it's payload is JSON. ### Connectivity to peers Each MuWire node will create a single unique I2P Destination. Traffic to and from that destination can either be over the I2P streaming or I2P signed datagram protocols. At the moment the signed datagram protocol is only used during the bootstrap phase. Going one level up the stack, traffic to and from the node's Destination can be either the MuWire network protocol or HTTP1.1 protocols, depending on the use case. MuWire's network protocol is documented in the "wire-protocol" document. Similar to Gnutella, MuWire nodes can be either leafs or ultrapeers. ##### Leaf connectivity If the node is a leaf, it will only establish outgoing connections to a small number of ultrapeers. In Gnutella that number was between 2 and 5. The node will not accept any incoming connections over the MuWire protocol. ##### Ultrapeer connectivity Ultrapeer nodes will establish outgoing connections to other ultrapeers as well as listen to incoming connections from leafs and ultrapeers. Ultrapeers have a "quota" of allowed leaf and ultrapeer connections. The quota for ultrapeer connections is further divided into quotas for outgoing connections and one for incoming connections. Whenever any of the quotas is exhausted, the node will reject fHTTP/1.1 200 OK Last-Modified: Thu, 15 Nov 2018 19:30:44 GMT X-Content-Type-Options: nosniff Content-Length: 5498 Etag: "b44045127315fb97dbbc6e5053a8e232763b0eb6" X-Frame-Options: SAMEORIGIN Access-Control-Expose-Headers: Content-Disposition Set-Cookie: i_like_gitea=62b353f739d3cb39; Path=/; HttpOnly; Secure; SameSite=Lax Set-Cookie: _csrf=WqrPP_hisBQgzjSd441j3WyE0ZQ6MTc1MzI1OTc5ODMzNzg2MDEzOA; Path=/; Max-Age=86400; HttpOnly; Secure; SameSite=Lax Date: Wed, 23 Jul 2025 08:36:38 GMT Connection: close Cache-Control: public, max-age=21600, no-transform Content-Disposition: inline; filename="design.md"; filename*=UTF-8''design.md Content-Type: text/plain; charset=utf-8 X-Cache-Status: HIT X-Cache-Age: 0 # MuWire Design MuWire operates a Web-Of-Trust layer on top of a Gnutella-like topology on top of I2P. To understand the rest of this document, it is important to understand the following terms: * I2P terms: * Destination - a cryptographic abstraction which represents a destination in the I2P cryptospace. It is not possible to correlate a destination with an IP address in the clearnet. While IP addresses and I2P Destinations share a lot in common, there are some important differences. The one most crucial to the design of MuWire is that I2P Destinations are always directly reachable, i.e. they are never behind a firewall. * I2P datagram - similar to clearnet UDP datagram. Can be signed or raw; MuWire only uses signed datagrams, which are datagrams containing the sender's Destination and can be replied to. * I2P streaming - similar to clearnet TCP/IP protocol. * Gnutella terms: * Leaf - a node in the Gnutella network which indexes only content shared by the local user. Leafs do not route queries and connect only to ultrapeers * Ultrapeer - a node in the Gnutella network which listens for incoming connections from leafs, indexes (loosely) their content and routes search queries to other ultrapeers and leafs. * MuWire Persona - each MuWire node operates a single Persona. For complete definition, see the "web-of-trust" document.