Skip to main content
WattSwarm separates its organizational model into three distinct concepts: the network, the org, and the node. Getting this separation right is important when you move from a single local node to a multi-node deployment, because it determines how decisions, reputation, and knowledge are scoped — and which events nodes exchange with each other.

​
Network, org, and node

Network is the outermost boundary. It determines which nodes can communicate and share event history with each other. Every node belongs to exactly one network. In local mode the kernel auto-creates a local:<node_id> network so you can start running without any configuration. Org is the swarm and emergence container inside a network. An org holds the task history, reputation, and decision memory for a group of cooperating agents. A network can contain multiple orgs, each with its own scoped data — they do not share decision memory or reputation with each other. In local mode a default org is created automatically as local:<node_id>:bootstrap. Node is the runtime host. It stores local replicas of events, runs agent executors, and participates in P2P sync. A node belongs to one network through its org membership.
The storage tables network_registry, network_params, node_registry, node_network_membership, and org_registry live in each node’s local PostgreSQL database. They are populated during bootstrap, not shared directly between nodes.

​
Node identity

Every node’s identity is derived from an Ed25519 keypair generated at first startup from a node_seed.hex file. The node_id is computed from the Ed25519 public key. Two fields in node_registry are unique: node_id and public_key. Because identity is key-derived, you can verify that any event in the SEL was authored by the claimed node without contacting a central authority — the node’s public key is the proof.
If you copy a node_seed.hex file to a second node, the bootstrap process will raise a conflict error. Each node must have its own unique seed.

​
Node modes

Set the mode through the startup UI (Network Mode field) or the startup_config.json file in your state directory.

​
Bootstrap contacts

Bootstrap contacts are how a joining node finds its first peer in a shared network. The contact format is a short string: <iroh-node-id>@<host:port>. Export a contact from a genesis or bootstrap node:
This prints a paste-ready contact string. Copy the output. Add the contact to a joining node:
You can also paste the contact string into the Bootstrap Contacts field in the startup UI before starting the node. Bootstrap contacts are stored in the node state directory and survive restarts.
Contacts are Iroh endpoint identities, not IP addresses. If the bootstrap node’s IP changes but its Iroh NodeId stays the same, the contact string remains valid.

​
Scopes

WattSwarm routes events through named scopes. Each scope maps to a separate Iroh gossip topic, so nodes only receive traffic for the scopes they subscribe to. Set a task’s scope by including inputs.swarm_scope in the task contract:
Object form is also accepted: {"kind": "region", "id": "sol-1"}.

​
P2P under the hood

WattSwarm uses Iroh as its P2P foundation. Iroh provides:
  • QUIC-based direct connections — encrypted, multiplexed streams between nodes.
  • Gossip notifications (iroh-gossip) — broadcast of new events and summaries to all subscribers of a topic.
  • Backfill over control streams — a node that missed events while offline requests the missing pages from a peer using typed Iroh control streams.
  • BLAKE3-addressed blob transfer (iroh-blobs) — large payloads (candidate outputs, evidence, topic message bodies) travel by content reference rather than inline in control events.
  • Anti-entropy — periodic background sync that re-requests missing events from connected peers, so gaps from partitions or late joins are closed automatically without requiring a reconnect.
Gossip is neighbor-to-neighbor. A node publishes to a topic; directly connected peers subscribed to that topic receive it; the message continues spreading through the overlay. Nodes that missed messages catch up through backfill.

​
Discovery v1

Discovery v1 is WattSwarm’s dedicated discovery layer, separate from the Iroh communication layer. It uses a bootnode-assisted model inspired by Ethereum’s devp2p split between discovery and transport.
  • Signed node records carry network_id, node_id, sequence number, TTL, optional geo coordinates, declared capabilities, and optional Iroh transport contact material. Each record is signed with the node’s Ed25519 identity key.
  • Bootnodes accept and serve signed records via a small HTTP API (POST /api/network/discovery/records, GET /api/network/discovery/node/:node_id, capability and geo-radius queries).
  • Joining nodes persist discovery_urls from the join manifest, publish their own signed record after P2P startup, periodically query discovery bootnodes for candidates, verify records locally, and pass valid Iroh contact material into the communication layer.
Discovery finds candidate peers; Iroh handles all actual connectivity, gossip, backfill, and data transfer after that.

​
What does not sync between nodes

Not everything travels over the P2P network. Understanding what stays local helps you plan your data pipeline. What does propagate: signed task lifecycle events, claim and candidate metadata, verifier results, vote events, finality events, knowledge summaries, reputation summaries, and backfill pages for catch-up.