Mesh gossip (Phase 2)

How it works

1. Bootstrap — when a node starts cold (no known peers), it calls GET /api/v1/bootstrap to get an initial list of recently-active nodes from the directory. This seeds the peer list so the node can begin gossiping.
2. Peer exchange — every 30 seconds, the node submits its known peers to POST /api/v1/peers and receives a fresh list of peers it doesn't already know. This gradual exchange propagates peer knowledge across the mesh without requiring any node to maintain a full view.
3. Stale prune — peers not seen within 90 seconds are removed from the local peer table. This prevents ghost peers from accumulating and biasing gossip routes.
4. Persistence — the peer list is persisted to disk so nodes can reconnect after a restart without always falling back to bootstrap.

GET/api/v1/bootstrap

Returns a seed list of recently-active peers. No authentication required. Called by nodes on cold start before any peers are known. Returns only nodes seen within the last 90 seconds (3× the heartbeat interval).

Query parameters

curl -sf 'https://iicp.network/api/v1/bootstrap?limit=5'

{
  "peers": [
    {
      "node_id": "550e8400-e29b-41d4-a716-446655440000",
      "endpoint": "https://node.example.com:9484",
      "region": "eu-central",
      "last_seen": "2026-05-22T15:00:19Z"
    }
  ],
  "count": 1
}

POST/api/v1/peers

Directory-side peer exchange. Nodes submit their current known peers and receive new peers they don't already know. Authenticated with the node's bearer token (issued at registration). Returns up to 10 peers not in the known list.

Auth

Authorization: Bearer <node_token> — the token issued to the node at registration (the same NodeTokenAuth scheme as the other node-authenticated endpoints). Unauthenticated requests return 401.

Request body

{
  "known_peers": [
    "550e8400-e29b-41d4-a716-446655440000",
    "6ba7b810-9dad-11d1-80b4-00c04fd430c8"
  ]
}

Response 200

{
  "peers": [
    {
      "node_id": "...",
      "endpoint": "https://...",
      "region": "eu-west",
      "last_seen": "2026-05-22T15:00:19Z"
    }
  ],
  "count": 3
}