Each running daemon is one libp2p peer. Its identity on the wire is a device key: an Ed25519 key pair generated the first time the daemon starts and stored in the data directory. The peer id derived from it is the 12D3Koo… string you see in the Seed app's network dialog.

The device key is separate from any account key. Account keys (identity) sign content. The device key only secures connections. One person can run several devices, and a site's server is a device that holds no account key at all. When a connection needs to prove which account is behind it, the peer signs a short-lived capability with the account key (see "Private content" below). The account_id field that the networking API still exposes on a peer is always empty today.

Every Seed peer announces the libp2p protocol id /hypermedia/0.9.2. A daemon started with a testnet name announces /hypermedia/0.9.2-<name> instead. Only that suffix isolates testnets, and the bootstrap list is the same everywhere. A remote peer whose version string does not match exactly is rejected as an incompatible protocol version, so peers on different daemon generations do not sync with each other. The same id names the stream on which the daemon serves its peer-to-peer gRPC services.

The daemon uses go-libp2p's default transports (TCP, QUIC, WebSocket, WebTransport and WebRTC-direct), TLS or Noise for the handshake, and yamux for multiplexing. It listens on four multiaddrs for one port P:

IPv6 listening is off for now. The -p2p.listen-addrs flag replaces this set, and -p2p.announce-addrs replaces what the node tells others (a site announces /dns4/<host>/tcp/56000 and /dns4/<host>/udp/56000/quic-v1). By default a desktop node also announces and stores private LAN addresses, so two laptops on one network can find each other. -p2p.no-private-ips turns that off.

Most desktop nodes sit behind NAT. The daemon enables hole punching and AutoNAT. Unless told otherwise, it assumes it is not publicly reachable. It asks one of two fixed Seed relay servers for a circuit-relay reservation, and keeps at most two relay connections. Relays are never discovered from the network. The two addresses are compiled in. The daemon itself is never a relay for others. The relay is a separate small program in the repository.

A site runs with -p2p.no-relay=true -p2p.force-reachability-public=true, so it never uses a relay and always answers direct dials. Current reachability is shown on the loopback-only /debug/p2p page.

Seed does not run a distributed hash table (DHT) today. The daemon links the code for a delegated-routing client, but the URL it would talk to is empty by default. So every provider lookup fails quietly, and the local Kademlia code has no callers. Nothing announces "I have this document" to a global index, and a node cannot find a document by its hash alone. The flag help text that promises a local DHT client is wrong.

Discovery uses these sources:

Bootstrap gateways. Every daemon dials a compiled-in list of Seed servers at startup and keeps them connected: production hyper.media, dev.hyper.media, staging.hyper.media and one community node. These are ordinary site daemons that hold nearly everything public. They form the first tier every discovery asks. The daemon also dials the public kubo bootstrap peers from IPFS, out of habit. They speak no Hypermedia protocol and are filtered out of discovery.

Peer exchange. After identifying a bootstrap peer, the daemon asks it for its recent peer list (rows updated within 30 days) and stores them in its own peers table. A tick every 60 seconds keeps about 20 non-bootstrap Hypermedia peers connected, dialing stored peers when short. Dead peers fade out because their rows stop being refreshed.

Site peer resolution. When a space declares a siteUrl in its home document metadata, the daemon fetches https://<site>/hm/api/config to learn the site server's peer id and addresses, and treats that server as the authority for the space. The answer is cached for five minutes and remembered in the domains table as a fallback.

Explicit connections. The Networking.Connect RPC takes multiaddrs, and the Seed app accepts a peer address, an hm://connect/… link or any site URL in its network dialog.

DNS names inside multiaddrs. DNS appears only in /dns4/hyper.media/… addresses and in the HTTPS hostnames of site URLs. There is no DNSLink or TXT-record lookup.

So a public document is findable only because some gateway or site server has it. The network as a whole keeps no index. A private document is findable only from its site server or from a device that authenticated as an authorized account.

A sync always asks about a scope, and never for "everything peer X has". A scope is one resource IRI such as hm://ACC/notes/foo, optionally its direct children (depth one) or all descendants (recursive), optionally restricted to some blob types. Both sides compute the same set of blobs for a scope from their own index:

the Refs, capabilities, comments, profiles and contacts anchored on the resources in scope;

every change reachable from those Refs through their heads and dependencies;

the media those blobs link to (files, images, chunks), following every link but skipping blobs the index has stashed as unauthorized;

inbound contacts naming the space's account, when the scope is a whole space;

capabilities with the AGENT role whose delegate authored anything already in the set, repeated until nothing new appears.

Because both peers derive the set with the same rules, they can compare it without listing it. The daemon keeps this set materialized per scope and patches it after every indexing commit. A background verifier recomputes a few scopes every 30 seconds and repairs drift.

Range-Based Set Reconciliation (RBSR) is an algorithm that finds the differences between large sets held by different peers. Each peer recursively compares hash summaries of ordered key ranges, so the peers never exchange every item identifier. When the hash of a range differs, the peers split that range and compare smaller segments until they isolate the exact items that differ. The cost grows with the number of differences, and the total set size barely matters. Seed's implementation follows Aljoscha Meyer's paper and the Negentropy design.

In the daemon, an item is (timestamp, CID), ordered by the blob's signed timestamp and then by bytes. Each item's hash is the SHA-256 of its CID bytes, and a range's fingerprint is the first 16 bytes of the SHA-256 of the sum of those hashes followed by the item count. The initiator splits its whole range into 16 buckets and sends one fingerprint per bucket. A range of fewer than 32 items is sent as a plain list. The responder answers each fingerprint with "same" or with its own subdivision, and each list with its own list. Messages are capped at 1 MiB, a round at 15 seconds, and a session at 1,000 rounds. The result is one-directional: the initiator learns which CIDs the peer has that it lacks. The daemon also computes what the responder would need from the initiator, but does not use it. Seed pulls, and never lets a stranger push.

Once the wanted CIDs are known, the blobs themselves travel over Bitswap, the IPFS block exchange. In Bitswap each peer keeps a wantlist of the blocks it needs, exchanges wantlists on connect, and serves what it has. Seed opens one Bitswap session per discovery and fetches in render order: signed DAG-CBOR blobs first, then "chrome" media (icons, covers), then inline images, and finally bulk files. Bulk downloads share a single daemon-wide slot, so a large PDF never starves a page's text. Every block is verified against its CID on arrival and indexed like any other blob. Files covers the media side.

Bitswap has no built-in access control. It accepts a callback that runs for every (peer, CID) request. Seed uses that callback to keep private blobs from unauthorized peers (below).

DiscoverEntity is the single entry point that the Seed app, a site server and subscriptions all use. It takes an hm:// discovery URL:

A discovery run has a ten-minute budget and proceeds in tiers:

Authority. The space's site server, if its siteUrl is known, plus the bootstrap gateways. If the space has a site and you already hold the content, the gateways are dropped.

Connected. A sample of already-connected Hypermedia peers, up to 20.

Cold. Peers from the stored table that need a dial.

A later tier runs only if the previous one left something owed. The exception is an exhaustive wave. Every recursive scope gets one every ten minutes, and a user's fresh interest can force one at most once every two minutes. Within a tier the node talks to up to 20 peers at once. It cuts stragglers once 70 percent are done and downloads have been idle for five seconds. A peer whose dial fails is benched for 30 seconds, doubling up to ten minutes. This only filters eligibility and keeps no reputation.

For recursive scopes a quick structure-only pass (Refs and changes, depth one, no media) runs first so a directory listing appears before its files. Once the target resolves locally the run ends with outcome connected. If nothing resolved, the run ends with the leftover "DHT" phase, which finds nothing and reports no error. The caller keeps polling.

The daemon runs discovery through one scheduler with -syncing.max-workers slots (default six) and one slot always reserved for interactive work.

Hot tasks come from a client that is looking at something. The Seed app calls DiscoverEntity for the document on screen every few seconds. Each call is a heartbeat that keeps the task alive for 40 seconds and reruns it every 10 seconds. Hot tasks are last-in-first-out and may preempt an idle background run.

Cold tasks are subscriptions. They rerun every -syncing.interval (default one minute) after completing, clumped a few seconds together to save battery.

As a scope settles, the fan-out narrows and the frequency stays the same. A scope you already hold, or a recursive scope whose last two waves fetched nothing, adds no random sample at all. It asks only the site server, or the gateways when there is no site server. A scope you lack whose site server is known samples two extra peers, and only a scope with no known host samples twenty.

A subscription is a row (iri, recursive) and a standing cold task for it. Subscriptions.Subscribe stores the row, schedules the task and runs one discovery right away (synchronously, unless asked to run in the background or the resource is already local). A site server subscribes recursively to every account registered on it. That keeps a whole space current on the site. The Seed app subscribes to the spaces you join or follow. There is no "mirror everything from peer X" mode any more. The older -syncing.smart and -syncing.no-sync-back flags are accepted and ignored, and Daemon.ForceSync returns Unimplemented.

Pull is the default, but a publisher should not have to wait for its site to poll. Resources.PushResourcesToPeer takes a peer's addresses and a list of resources, computes the related material (changes, Refs, the authors' root Refs and profiles, link targets, citations, comment links, and media), and calls the peer's AnnounceBlobs RPC with the CIDs. The receiving daemon checks which CIDs it lacks, fetches them over Bitswap from the announcer, and indexes them. Progress streams back to the caller.

The Seed app pushes when you publish a document, when you register a site, and when you push a document to a site explicitly. It pushes to the space's site server and to the site servers of the documents you referenced, so that citations and backlinks appear on the self-hosted sites of the people you cite. Private blobs are included in a push only when the target is the space's own site server. A receiving node accepts any announcement (the -syncing.allow-push flag exists but nothing reads it). It can only fetch what the announcer is willing to serve it. Push only speeds up sync. Publishing happens when you sign: your blobs exist in your local daemon from that moment, even if the push announces nothing.

Seed's peer-to-peer sync is built around identity, trust and relevance. So it works very differently from gossip protocols, although both run in distributed peer-to-peer networks.

Seed sync is narrowly scoped. Gossip protocols spread messages across a broad set of peers with mesh fan-out and probabilistic forwarding. They do not know who should receive a message, only that it should spread, and spam spreads the same way. Seed sync replicates resources only to peers with explicit trust or relevance relationships. It does no broadcast and no fan-out.

Identity defines Seed's propagation graph. Eligible recipients are known in advance: verified owners of sites, trusted contacts (and so their peers, including identity delegation), and explicit subscriptions. The graph is directed, bounded and controlled by users. A node should never push content to uninterested or random peers.

Seed does not use epidemic convergence. Gossip repeats spreading until coverage is highly probable. Seed does no mesh spreading, no redundant forwarding of blobs, and no probabilistic delivery across the network. Sync delivers to targets.

Discovery does contact up to 20 peers per tier. That fan-out is a pull asking "do you have this?", scoped to one resource. It never pushes your content to strangers. Seed's design direction is to keep narrowing that pull as trust relationships become explicit.

Public blobs are served to anyone who asks. A private blob (visibility) is served to a peer only if one of these holds:

the peer authenticated as the account that owns the space, or as an account holding a WRITER capability for it;

the peer is the space's site server, as reported by https://<siteUrl>/hm/api/config;

the blob is allow-listed for that peer for the duration of a push.

Authentication is the P2P.Authenticate RPC: the caller sends its account, a millisecond timestamp and a signature over an ephemeral capability blob that delegates from the account to the caller's peer id with the server's peer id as audience. The server accepts a one-minute clock skew and remembers the binding until the connection closes. A desktop node authenticates automatically toward the site servers of every space its keys can write to, and only there.

The same rule shapes reconciliation. Before answering, a peer filters its scope set to what the caller may see and folds private items out of the fingerprints. So an unauthorized peer never learns that a private blob exists. Privacy has the full HTTP-side rules.

You open hm://ACC/notes/foo in the Seed app and nothing about ACC is on your machine yet.

The app calls DiscoverEntity with that URL and keeps calling it every few seconds while the view is open. The daemon creates a hot task and, because you just showed interest, arms one exhaustive wave.

The scheduler dispatches the task at once in the reserved hot slot.

The daemon looks for ACC's siteUrl. It knows nothing, so there is no site server. The wave is a full search: every bootstrap gateway plus a sample of 20 peers.

A local reconciliation store for the scope is built. It is empty.

Tier authority runs first. For each gateway the daemon opens (or reuses) a gRPC stream over libp2p, asks which spaces it may see (public only, since it did not authenticate), and runs ReconcileBlobs rounds for the filter hm://ACC/notes/foo until the ranges agree.

The wanted CIDs go to Bitswap: DAG-CBOR blobs first, then icons and inline images, then bulk files if the media slot is free. Blocks stream through one writer into the index, which also patches the maintained scope sets.

The authority tier is satisfied, so the connected and cold tiers are skipped unless this is the exhaustive wave.

GetResource now resolves. The task completes with the version, and reruns on the ten-second cooldown while you keep looking.

Later, once ACC's home document (and its siteUrl) has arrived and you have subscribed, a settled run asks only the site server. It makes one reconciliation round trip every ten seconds while viewed and once a minute otherwise, plus one full-width probe every ten minutes.

If step 5 finds nothing anywhere, the run ends with an empty version and no error. The page keeps showing its "looking for this document" state, and the task retries with the same peer set every ten seconds.

Ports

Flags that matter to operators

Constants

Debug pages and metrics

In the Seed app

CLI

SDK

Web API

grpcurl -plaintext localhost:56002 com.seed.networking.v1alpha.Networking/ListPeers
grpcurl -plaintext -d '{"id":"hm://ACC/notes/foo"}' localhost:56002 \
  com.seed.entities.v1alpha.Entities/DiscoverEntity

Agents

As of September 2026 the network layer is stable, and two things are open. First, routing. With no DHT, a fresh install can only reach content held by a gateway, a site server or a peer it was told about. A delegated-routing server or a real provider system is the next step, and unused code hooks exist for both. Second, the team wants to narrow discovery toward explicit trust relationships (sites you joined, contacts, subscriptions) and stop sampling twenty peers. The team also wants to expose subscriptions through the public API as well as gRPC. The HM26 redesign notes on the roadmap touch both.