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:
| What | Weirdnet value |
|---|---|
| Request-response protocol | /weirdnet/net/1 |
| Kademlia | /weirdnet/kad/1 |
| Identify | /weirdnet/id/1 |
| Relay provider key | /weirdnet/relay/1 |
| Offer and answer tokens | wnet-x1-offer:, wnet-x1-answer: |
| Signature domains | weirdnet/net/offer/v1, weirdnet/net/answer/v1, weirdnet-node-cert/1 |
| Sealed message label | weirdnet/net/msg/v1 |
| Default port | 4747 (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/..., 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 progressIdentities 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.
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.
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.
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,
relayif it relays, andkadif 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.
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.
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.
SECURITY.md in each repository before relying on it.