Set Up Federation Trust Modes for ServiceNet Nodes

Configure open or trusted federation to control which peers your ServiceNet node accepts gossip and backfill records from in the P2P network.

Federation trust controls which P2P peers your node accepts provider and agent records from. In open mode, any connected peer can contribute records to your local registry. In trusted mode, only peers you explicitly list are allowed to push registry data — all others are silently ignored for gossip and backfill, while still remaining reachable for direct agent invocations.

Open Federation (Default)

In open mode, any peer that connects to your node can gossip and backfill provider and published agent records. Records are still validated against your local registry rules before being accepted.

SERVICENET_P2P_ENABLED=1 \
SERVICENET_FEDERATION_MODE=open \
cargo run -p watt-servicenet-node

Open mode is the default. If you omit SERVICENET_FEDERATION_MODE, your node behaves as if it is set to open.

Trusted Federation

In trusted mode, your node only merges registry data from peers listed in SERVICENET_FEDERATION_TRUSTED_PEERS. Peers not on the list can still connect, but your node ignores their provider and agent records.

SERVICENET_P2P_ENABLED=1 \
SERVICENET_FEDERATION_MODE=trusted \
SERVICENET_FEDERATION_TRUSTED_PEERS=<peer-endpoint-id-1>,<peer-endpoint-id-2> \
cargo run -p watt-servicenet-node

Provide each peer as an Iroh EndpointId (the same ID printed in the peer’s startup logs). Separate multiple entries with commas — no spaces.

In trusted mode, peers not in the trusted list are still reachable for direct agent invocations through the HTTP API. Only their inbound gossip and backfill records are ignored — your node will not merge their provider or agent data into the local registry.

Choosing a Federation Mode

Use this table to pick the right mode for your deployment:

Use case	Recommended mode
Open public network node	open
Curated or consortium network	trusted
Official registry / entry node	trusted
Development / testing	open

Open mode

Best for nodes that want to participate fully in the public ServiceNet — accepting records from all verified peers and contributing to the shared registry.

Trusted mode

Best for official entry nodes, consortium deployments, or any operator who needs explicit control over which peers can influence their local registry state.

Federation Environment Variables

Variable	Values	Description
SERVICENET_FEDERATION_MODE	open (default) / trusted	Trust policy applied to all inbound P2P gossip and backfill data. allowlist and allow-list are accepted as aliases for trusted.
SERVICENET_FEDERATION_TRUSTED_PEERS	Comma-separated EndpointId values	The set of peers allowed to contribute registry records in trusted mode

In trusted mode, if you leave SERVICENET_FEDERATION_TRUSTED_PEERS empty, your node will reject registry data from every peer — effectively running in read-only P2P mode for the registry. Ensure you list at least one trusted peer before enabling trusted federation in production.

Combining Federation with P2P Setup

Federation mode is enforced on top of the P2P transport layer. Set up P2P connectivity first, then layer in federation policy:

SERVICENET_P2P_ENABLED=1 \
SERVICENET_P2P_NETWORK_ID=mainnet \
SERVICENET_P2P_LISTEN_ADDRS=0.0.0.0:4101 \
SERVICENET_P2P_BOOTSTRAP_PEERS=<bootstrap-peer-id>@203.0.113.5:4101 \
SERVICENET_FEDERATION_MODE=trusted \
SERVICENET_FEDERATION_TRUSTED_PEERS=<bootstrap-peer-id> \
cargo run -p watt-servicenet-node

See P2P Setup for details on bootstrap peers, listen addresses, and relay fallback.