How it works

How the network works

Nodes, profiles, identities, invitations, sealed messages, discovery and relays: what each piece does on the wire, from the weirdnet-net source.

Nodes

A Weirdnet node is a weirdnet_net::Node<Q, R>: a libp2p swarm over TCP and QUIC, IPv4 and IPv6, with Noise for encryption and authentication and Yamux for multiplexing. Each node runs identify, ping, Kademlia, mDNS (optional), AutoNAT, a relay client, DCUtR hole punching and, when asked, a relay server.

The application brings its own request and response types. They travel as CBOR over request-response on the profile’s protocol id, and a Handler answers requests on a blocking pool. The peer id a handler sees is the one Noise authenticated, so an answer always knows who asked. Requests may be up to 8 MiB and answers up to 256 MiB, with a 60-second timeout.

let cfg = NodeConfig { listen: NodeConfig::default_listen(4747), mdns: true, ..Default::default() };
          let node = Node::start(&WEIRDNET, keypair, cfg, Arc::new(MyHandler))?;
          let answer = node.request(peer, &addrs, MyRequest::Hello)?;

Profiles

Every identifier a node puts on the wire or under a signature comes from a Profile: protocol ids, token prefixes, link schemes, signature domains and derivation labels. WEIRDNET is the default:

WhatWeirdnet value
Request-response protocol/weirdnet/net/1
Kademlia/weirdnet/kad/1
Identify/weirdnet/id/1
Relay provider key/weirdnet/relay/1
Offer and answer tokenswnet-x1-offer:, wnet-x1-answer:
Signature domainsweirdnet/net/offer/v1, weirdnet/net/answer/v1, weirdnet-node-cert/1
Sealed message labelweirdnet/net/msg/v1
Default port4747 (TCP and QUIC)

Profiles never mix: tokens, signatures, sealed messages, certificates and sync keys made under one profile don’t verify or open under another, and nodes on different protocol ids don’t talk at all. Apps share one network on the default profile and keep their own traffic on their own protocol names (Morph uses /morph/...), so a node ignores traffic it doesn’t understand. Invitation links use each app’s own scheme, such as weirdnet-morph://join/.

Muninn shipped on its own profile (/muninn/..., port 4741) and is moving onto Weirdnet as weirdnet-muninn: its links use weirdnet-muninn://, and it shares the /weirdnet/... base protocols, port 4747, the DHT and the same relays as Morph. in progress

Identities and certificates

There are two kinds of key. A node key is an Ed25519 keypair per device, made on first use; its public key is the libp2p peer id. The application keeps it wherever it keeps secrets, through the IdentityStore trait. A user key is the person’s Ed25519 signing key, separate from node keys, and the same across Weirdnet apps.

The user key signs a NodeCert for each node it links (a signature over the node’s peer id) and can revoke it later. A Card is what a node says about its user: the user’s public key and the node certificates and revocations, never a secret. Peers check cards before treating a node as acting for a user.

User keyEd25519 · the person · 24 wordsDesktop nodenode key = PeerIdPhone nodenode key = PeerIdOld laptoprevokedNodeCertNodeCertrevocationA Card = user public key + its node certificates; peers check it before treating a node as acting for a user.
Identities: one user key across apps, one node key per device, certificates and revocations signed by the user key.

Linking a new device uses a link-scope exchange and a link grant that hands the user key to the new node, sealed under that exchange. Linked nodes sync their data under a sync_key derived from the user key, which only the user’s own nodes hold.

Offers and invitations

Two nodes become peers through a key exchange. The offering node signs an offer with its node key: its peer id, a fresh X25519 public key, its addresses, a label, a scope (what the exchange is for: node, link, or an invite into something the app names, with a role) and an expiry, a week unless asked otherwise.

The offer travels as a token (wnet-x1-offer: plus base64url JSON, holding only public keys and signatures) or as an invitation link. The other node verifies the signature, the scope and the expiry, and signs an answer with its own fresh X25519 key, bound to the SHA-256 of the signed offer. The node that made an offer can’t answer it.

Anna’s nodeBen’s nodeoffer: node key + fresh X25519 + scope + expirysigned (Ed25519)invitation link weirdnet://join/… (or connect over the node)verify signature, scope, expirysigned answer, bound to SHA-256 of the offerboth derive: exchange key = HKDF(X25519 secret, transcript)12345-67890short code, compared out of band
A key exchange: a signed offer (the invitation), a signed answer bound to it, the same key and short code on both sides.

Both sides then derive the same exchange key with HKDF over the X25519 shared secret and the transcript of both signed messages, plus a ten-digit short code (12345-67890) and a fingerprint. Comparing the short code out of band, in person or over a call, is what rules out a man in the middle; the crate can’t do that for you.

Invitation automation

The invite module lets nodes run exchanges themselves. connect sends a hello, then delivers a signed offer over the node; the other side answers on the spot when the application’s decide says so, or keeps the offer for its owner (only after the host’s admit, and only a bounded number wait). The offerer can poll for the answer later, and an answerer can deliver an answer it made while the offerer was away (settle).

Two nodes that offer to each other at once settle on one exchange. A node is its key: the first completed exchange pins it (trust on first use), a name shared by several nodes resolves to the pinned one, and a node using a pinned node’s name is flagged as a possible impostor for the app to show.

Sealed messaging

Once an exchange is complete, requests between the two nodes can travel sealed: XChaCha20-Poly1305 under the exchange key, with the profile’s message label, the exchange id and both peer ids, in order, as associated data. A message can’t be moved to another exchange or turned around.

plaintextapp requestseal (XChaCha20-Poly1305)key: exchange keyAAD: msg|exchange|from|toserve() on the peeropens only for the exchange’s own peerapp envelopeThe answer is sealed the other way. Moving a message to another exchange or turning it around fails to open.
Sealed messaging over an exchange: the exchange id, both peer ids and the direction are bound as associated data.

sealed::call seals a request into the application’s own envelope and opens the sealed answer. sealed::serve opens a request only when the exchange is known, active (complete and not revoked) and belongs to the Noise-authenticated sender. What is inside, and what each request may reach, stays the application’s.

Peer discovery

  • Local network: with mDNS on, nodes announce themselves and dial the peers they find.
  • Kademlia: nodes start from bootstrap addresses (/ip4/…/tcp/…/p2p/…) and keep a routing table; relays run Kademlia in server mode.
  • Identify: every connection exchanges the protocols a peer speaks. A peer is listed with the profile’s capability, relay if it relays, and kad if it serves the DHT.
  • Relays by provider key: relays provide the profile’s relay key (/weirdnet/relay/1) in the DHT, and nodes look it up every minute, so they find relays they were not configured with.
local networkDesktopmDNS onLaptopmDNS onmDNS: found, dialBootstrap / relayKademlia serverRelayprovides /weirdnet/relay/1Phonebehind NATbootstrapprovider recordget_providersreserve
Finding peers: mDNS on the local network, Kademlia from bootstrap nodes, and relays announced under a provider key.

Relays and hole punching

Phones on cellular sit behind carrier NAT and can only dial out. AutoNAT tells a node whether it is publicly reachable. A node that is not reserves a slot on a relay (libp2p circuit relay v2) and becomes reachable at /…/p2p/RELAY/p2p-circuit/p2p/NODE. A node behind NAT that meets a relay through identify reserves on it by itself.

When a peer connects through the circuit, DCUtR coordinates a simultaneous dial so the two can switch to a direct connection. That works most of the time, not always; when it fails, the relayed connection stays. Relays are the fallback that always works, as long as the device can make one outbound connection.

Phonecarrier NAT, dial-out onlyHome relayweirdnet-relayDesktopanywhere1 · reservation2 · dial …/p2p-circuit/p2p/PHONE3 · DCUtR hole punch: a direct connection when NAT allowsIf punching fails the circuit stays: relays are the fallback that always works.
Relays and hole punching: reserve a slot, get dialed through the circuit, upgrade to a direct path when possible.

Anyone can run a relay with weirdnet-relay. WeirdBrains runs public relays and bootstrap nodes; running your own is optional and needs a domain tied to the machine through Grindvakt dynamic DNS.

Being built now in progress

These pieces are being built into Weirdnet now, following the design in Morph’s architecture:

  • Data-carrying relays: relay limits become configurable in weirdnet-net (RelayLimits), and weirdnet-relay runs with no circuit time or data caps by default.
  • Names and rendezvous: signed, versioned peer records (current addresses plus the home relay) pushed to trusted peers, registered at the home relay’s rendezvous point, and put in the DHT only while a site is hosted, with signed withdrawal tombstones.
  • Key-only dialing: dial a peer id and let the node resolve where it is.
  • Path switching: app streams that survive moving between the relay and a direct path.
  • WebSocket over TLS on 443 for networks that block UDP and odd ports.
  • Public HTTPS forwarding by SNI passthrough: TLS ends at the host, the relay never holds a key, each name needs the owner’s signed grant, and forwarding can be revoked per site.
  • Push wake-up, update announcements, access policy (weirdnet-access), device linking, TLS certificates and URL schemes as their own crates.

Security boundaries

From weirdnet-net’s security notes. The crate enforces: signatures on offers, answers, certificates and revocations; answers bound to their offer; sealed messages bound to their exchange, peers and direction; offers kept only from the node that signed them; and profiles that don’t mix.

It leaves to the application: whether to answer an offer, who may do what over an exchange, which users are trusted, what an invitation grants, every limit on what peers may store or ask for, and keeping secrets encrypted at rest.

Nobody has audited weirdnet-net yet. Read SECURITY.md in each repository before relying on it.