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
| Mode | Description |
|---|
| local | Single self-contained node. P2P is disabled (WATTSWARM_P2P_ENABLED=false). The kernel auto-bootstraps network_id = local:<node_id> and a default org. No bootstrap contacts are needed. |
| lan | Connects to peers on the local network over Iroh QUIC. mDNS/UDP announce is available as an optional local-discovery aid (WATTSWARM_UDP_ANNOUNCE_ENABLED=true). |
| network / wan | Joins a shared network by dialing one or more configured bootstrap contacts. The node fetches and verifies a signed NetworkBootstrapBundle before opening. |
Network Mode field) or the startup_config.json file in your state directory.
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:
wattswarm --state-dir <genesis-state-dir> node export-contact
wattswarm --state-dir <joining-state-dir> node add-bootstrap-contact '<iroh-node-id>@<host:port>'
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.
| Scope | What it covers |
|---|
global | All nodes in the network. Every node subscribes to global by default. High-frequency task coordination should use a narrower scope to avoid flooding. |
region:<id> | Nodes in a named region (e.g., region:sol-1). Subscribe via WATTSWARM_P2P_REGION_IDS=sol-1,sol-2. |
node:<id> | A specific node addressed by its logical ID. Subscribe via WATTSWARM_P2P_NODE_IDS=lab-a. |
group:<id> | An opaque group scope. Commonly used as group:<task_id> to give a task its own lifecycle thread. |
inputs.swarm_scope in the task contract:
{
"inputs": {
"swarm_scope": "region:sol-1"
}
}
{"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.
| Data | Stays local |
|---|
| PostgreSQL databases and table replicas | Always local. Never replicated between nodes. |
| Artifact file contents (evidence blobs, checkpoints, snapshots) | Local by default. Direct fetch over Iroh is available when remote contact material is present. |
| Agent intermediate reasoning traces | Local only. Not propagated. |
| Run-queue step state | Local to the node running the worker. |