WattSwarm is built around a clean separation of concerns: the kernel coordinates, executors do the work, and a peer-to-peer network keeps every node in sync. Understanding how these three layers relate helps you design integrations that stay durable across deployments, from a single developer machine all the way to a wide-area multi-node swarm.
How the pieces relate
When you run WattSwarm, you start one or more nodes. Each node owns a local PostgreSQL database and an artifact store. The node publishes and receives signed events over an Iroh-backed P2P network. Your executor — an HTTP service you build and register — receives task requests from the kernel and returns candidates and verification results.
┌──────────────────────────────────────────────────┐
│ WattSwarm Node │
│ │
│ ┌──────────────┐ ┌────────────────────────┐ │
│ │ node-core │ │ Structured Event Log │ │
│ │ (kernel) │──▶│ (append-only, SEL) │ │
│ └──────┬───────┘ └────────────────────────┘ │
│ │ │
│ ┌──────▼───────┐ ┌────────────────────────┐ │
│ │ PostgreSQL │ │ Artifact Store │ │
│ │ (local SoT) │ │ (filesystem / blobs) │ │
│ └──────────────┘ └────────────────────────┘ │
│ │
│ ┌──────────────────────────────────────────┐ │
│ │ Iroh P2P Bridge │ │
│ │ gossip ▸ backfill ▸ anti-entropy │ │
│ └──────────────────────────────────────────┘ │
└──────────────────────┬───────────────────────────┘
│ HTTP
┌───────▼────────┐
│ Executor │
│ /health │
│ /capabilities │
│ /execute │
│ /verify │
└────────────────┘
The three-layer model
WattSwarm organises itself into three logical layers that work in concert.
| Layer | What it does |
|---|
| Kernel (coordination) | Manages task lifecycle, evidence, voting, finality, knowledge, and reputation. Lives entirely inside the node process. |
| Executor (agent work) | Executes tasks and verifies candidate outputs. An HTTP service you implement; the kernel calls it over a registered base URL. |
| Network (sync) | Propagates signed events between nodes using Iroh gossip, backfill, and anti-entropy. Keeps every node eventually consistent with the swarm. |
What a node is
A node is a running WattSwarm process with its own persistent identity and local storage. When you start a node for the first time, WattSwarm generates an Ed25519 keypair and derives a node_id from the public key. That identity signs every event the node authors, so the rest of the network can verify authorship without a central authority.
Each node maintains:
- A local PostgreSQL database — the node’s source of truth for the SEL, task projections, leases, votes, reputation, knowledge, and run-queue state.
- A local artifact store — a filesystem layout for candidate outputs, evidence blobs, checkpoints, snapshots, and event batch archives.
- An Iroh endpoint — the QUIC-based P2P transport used for gossip notifications, control-stream backfill, and direct data fetch.
Two nodes that share the same node_seed.hex file will produce a duplicate-identity conflict on bootstrap. Each node must have its own unique seed.
What an executor is
An executor is an HTTP service you implement and register with the kernel. The kernel sends tasks to it and reads back candidate outputs and verification decisions. Every executor must expose four endpoints:
| Endpoint | Purpose |
|---|
GET /health | Liveness check; the kernel calls this before routing work. |
GET /capabilities | Declares what task types the executor handles. |
POST /execute | Accepts a task contract and returns a candidate output. |
POST /verify | Accepts a candidate and returns a verification result. |
wattswarm --state-dir ./.ws-dev executors add rt http://127.0.0.1:8787
Local, LAN, and network mode
WattSwarm supports three deployment modes that determine how the node discovers peers and joins a network.
| Mode | Description |
|---|
| local | Single self-contained node. No P2P connections are opened. The network is auto-bootstrapped as local:<node_id> with a default org of local:<node_id>:bootstrap. Ideal for development and single-machine orchestration. |
| lan | Connects to peers on the local network. mDNS/UDP announce is available as a discovery aid. Nodes exchange Iroh contact material and sync over QUIC. |
| network / wan | Joins a shared network by connecting to one or more bootstrap contacts. The joining node fetches a signed NetworkBootstrapBundle to obtain network topology and protocol parameters. |
WATTSWARM_P2P_ENABLED=false to force local-only mode regardless of the configured node mode.
The Structured Event Log (SEL)
Every state change in WattSwarm is recorded as a signed event appended to the Structured Event Log. The SEL is:
- Append-only — events are never edited or deleted. Invalid events are invalidated by a subsequent
EventRevoked or NodePenalized event.
- Replayable — you can replay the full event stream from the beginning to reconstruct any projection, task state, or reputation score.
- The source of truth — if a projection table and the SEL disagree, the SEL wins.
Each event carries a protocol_version, an author_node_id, an epoch, a created_at timestamp, and an event_kind. The kernel uses these fields to validate ordering, detect duplicates, and enforce finality rules.
PostgreSQL as node-local source of truth
Each node stores its SEL, projections, leases, votes, knowledge, reputation, and run-queue state in a local PostgreSQL database. This database is never replicated to other nodes.
Nodes do not share a database. Copying a PostgreSQL database between nodes is not a supported sync method. Use the P2P event pipeline instead.
public. Override it with WATTSWARM_PG_SCHEMA=<schema> if you need multiple isolated WattSwarm instances on the same PostgreSQL server.
How nodes sync
Nodes stay consistent by exchanging signed events, not database rows. The sync flow works like this:
- A node authors a local event and writes it to its SEL.
- The Iroh bridge publishes that event as a gossip notification on the appropriate scope topic.
- Connected peers that subscribe to that topic receive the notification.
- Each peer ingests the event into its own local event log and rebuilds the affected projections.
- Peers that were offline or missed messages request missing event pages through backfill over Iroh control streams.
- Anti-entropy runs periodically, so gaps from partitions or late joins are repaired automatically.
Large content bodies (candidate outputs, evidence blobs, topic message bodies) travel separately over Iroh’s BLAKE3-addressed transfer layer. Control-plane events carry a content reference; the receiving node fetches the body on demand.
Kernel crate boundary
The following crates form the kernel boundary. Everything inside this boundary is coordination logic; everything outside is transport, storage, or UI.
| Crate | Role |
|---|
node-core | Core node process: task lifecycle, evidence, voting, finality, knowledge, and SEL ingestion. |
storage-core | PostgreSQL schema, projections, and query helpers. |
policy-engine | Built-in verification policies (vp.schema_only.v1, vp.schema_thresholds.v1, vp.crosscheck.v1). |
protocol | Canonical event types, task contract types, and payload definitions. |
crypto | Ed25519 identity, event signing, candidate hashing, and vote commit hashing. |
runtime-client | HTTP client the kernel uses to call executor /execute and /verify endpoints. |
You can run the kernel fully without the UI. Remove or ignore ui/* and drive everything through the CLI or the kernel’s HTTP API.