The Sovereign Network

1The idea

Most messages pass through a company's servers. The company sees who talks to whom, keeps what was sent, and can be compelled, breached or shut down. The sovereign network has no such middle. Its one job is to carry bytes from a device to the person they are for, using only the devices of the people involved and the people they know.

It is built for four things.

• Privacy. Bytes are encrypted end to end. Only the devices they are for can read them.
• Sovereignty. You are a key your own devices make. There is no account, no phone number and no directory, and nobody can take your key away.
• Reliability. When there is no direct path, your own devices and your friends' relay sealed bytes, or hold them until the recipient is back.
• Speed. Devices connect to each other directly whenever routers allow. Bytes take no detour through a data centre.

It rests on four ideas, each a section below: handshake identity (2, 3), decentralized addressing (4), end-to-end encryption (5) and trusted relays (6). There is no global user ID, no certificate authority, no central relay or addressing server, and no phone number or email.

The code holds itself to this with a test: a fresh node knows no host but its peers, and names no public relay, DNS lookup or discovery service.

2Keys

Each install of an app is a device. On first run it makes an Ed25519 key pair and keeps the private half in the system keychain. The public half is the device's address on the network, and the only thing anyone dials.

A person is a second key, shared by all of their devices. It signs the person's card: their name, their picture, their devices, and the devices they removed. A card never holds an IP address, and a newer card replaces an older one.

Adding a device. One of your devices shows a code that works once, for ten minutes. The new device opens it, both screens show the same six digits, and you confirm. The new device receives the person key, the card and your contacts. From then on a change on one of your devices reaches the others within about a second of them connecting.

Removing a device revokes it in the card. Every contact who receives the new card refuses that device's key.

3The handshake

Two people become contacts in a handshake: each gives the other their public keys and a way to reach them. Private keys never leave their devices.

A handshake starts with a link, shown as a QR code or sent as a message. It works once and expires after an hour. It carries the inviter's name, their person key, where to reach them and a random secret, all after the #, so a web page that opens the link never sends any of it to a server.

The person who opens the link dials the place it names and presents the secret with their own card. The inviter answers with theirs, which the opener accepts only if it matches the person key in the link. The secret is then spent, and each side holds the other's card.

Where to reach the inviter. The link names a meeting device: one of the inviter's devices that can be reached from the internet, or a reachable device of one of their friends, with a short token, signed by the inviter, that lets the holder in until the link expires. The inviter's own IP addresses stay out of the link unless no meeting device exists.

Safety numbers. Every person key has a 60-digit safety number. Two people who compare theirs in person or on a call know nobody swapped the link on the way.

4The address book

There is no directory. Each device keeps an address book: the latest address record of every device it knows. An address record is a device's own signed description of where it is: its IP addresses and ports, whether it can be reached from outside, its relay, and whether the app is open. A newer record replaces an older one.

Records go only to mutuals: your own devices, your contacts' devices, and the members of a space you joined. They spread four ways.

• Cache. The last record of each mutual is kept across restarts and dialed first.
• Push. When a device's network changes, it signs a new record and sends it to every mutual it is connected to. They pass it on to others who know that device, up to three hops.
• Exchange. Two devices that connect swap their own records and the freshest ones they hold for the devices they both know.
• Nearby. On the same Wi-Fi, devices also find each other with mDNS.

A device keeps dialing every mutual it holds a record for, backing off from one second to a minute, and starts again the moment a fresh record arrives or its network changes. A device is online to you exactly when you hold a live connection to it: a friend who comes online is seen within seconds, and one who leaves is marked offline within thirty.

5Connecting

Devices talk over QUIC, using iroh. Every connection is encrypted with TLS 1.3 between the two devices' keys, so it is end to end even when a relay forwards it. A device accepts a connection only from a device listed, and not revoked, in a card it holds, or from someone holding a live invite. Anyone else is turned away as soon as they identify themselves.

A direct connection is the goal: it is the fastest path, and nobody else is involved. Every device listens on IPv4 and IPv6 on the same port, so an address a friend saved stays good across restarts, and a dial tries every address at once: the same Wi-Fi, IPv6, IPv4. Whichever answers first and fastest is kept. Most devices sit behind a router or a firewall, so a device has three more ways through.

• Open a port. It asks its own router for a port mapping with UPnP, NAT-PMP or PCP, and trusts the mapping only once the router confirms it. A device with a mapping can be reached from anywhere.
• Ask what others see. It asks up to four devices it is connected to, its own first, where its packets arrive from. Each address family is judged on its own terms. Over IPv4, if they all see the same port, its router keeps a stable mapping. Over IPv6, if they see one of its own addresses unchanged, nothing translates it. Either way others can reach it with a punch. No outside server is asked.
• Be introduced. When a device dials someone it is not connected to, it asks up to four devices it is connected to, its own first, to introduce them. It names the person's device only by a salted hash, so a device that doesn't already know them learns nothing. One that is connected to both, and holds both cards, asks the other side first. If it agrees, it tells that device where it sees the caller and to dial back now, and tells the caller where it sees that device. Both then send at once, and each router or firewall lets the other's packets in. Introductions happen only between mutuals, never toward a contact kept relay only, and each step is spaced so a busy dial loop can't turn them into traffic.

When none of these works, the bytes go through a trusted relay. A punch fails where both sides sit behind a router that picks a new port for every destination, as many cellular networks do over IPv4, or where a network blocks UDP.

6Trusted relays

A trusted relay is always a device of yours or of someone you know, never a public server. Your own devices help first, then your friends'. A relay helps in two ways.

Forward. A device that can be reached from outside, usually a computer at home with a port open, admits only devices it knows and people holding an invite that names it. It forwards the encrypted packets of two devices that couldn't punch through to each other. It forwards up to 1 GB a day for each friend, and without limit for its own person's devices.

Carry. When the recipient is offline, the sender seals the bytes to the recipient device's key, with X25519, HKDF-SHA256 and ChaCha20-Poly1305, and hands copies to connected devices that know the recipient. A carrier holds the envelope for up to fourteen days, within a 200 MB budget, and passes it at most three hops. When the recipient connects to any carrier, it takes the envelope and acknowledges it. Every carrier then drops its copy, and the sender learns it was delivered.

Every connection also declares a class, and the network enforces it, so nobody's bandwidth is spent on someone else's heavy traffic.

You can also mark a friend relay only. Their copy of your record then names a relay and no addresses, so they never learn your IP.

7What others can see

8On your device

Three keys live in the system keychain: the device key, the person key, and a key for the local store. On iPhone they stay on that phone: they don't sync to iCloud and can't be restored onto another phone. Everything else, including contacts, records and envelopes held for others, is kept in a database encrypted with SQLCipher under the store key.

9Limits

• No independent audit yet. Neither the cryptography nor the code has been reviewed by an outside party.
• Records are signed, not sealed. A record goes only to mutuals, over encrypted connections, but is not encrypted to each recipient, so a dishonest mutual could pass yours on.
• Relays see who talks to whom. Never what is said, but which devices, how much and when.
• Two phones alone may not meet. Two phones on cellular data, with no device that both are connected to and none that can be reached, have nobody to time a punch. A computer at home that stays on fixes it.
• Some networks defeat every punch. A router that picks a new port for every destination on both sides, or a network that blocks UDP. A trusted relay carries the bytes then.
• Phones help only while open. iOS pauses an app's network in the background, so a phone relays and carries only while the app is open.
• Stale addresses mean meeting again. If every address you hold for someone is out of date and nobody in your circle can reach them, you need a new link.

10Apps

The network carries opaque bytes, and apps give them meaning. baud, a messenger, seals each conversation with its own key before handing it to the network. Darkroom, Computer and Health OS run on the same network as separate nodes with their own keys, so removing one changes nothing for the others.

The implementation is peer, a Rust library built on iroh, with bindings for Swift and JavaScript and a command-line node for a computer that stays on.