How the Swarm Works

The Gossip Protocol

The Swarm uses an epidemic (gossip) protocol to spread information. Here’s how it works:

1. Bootstrap Phase

When a new node starts, the synapsis-cron process automatically announces to seed nodes:

New Node → Seed Node (node.synapsis.social)
         ← List of known nodes
         ← Handle registry

The new node announces itself to seed nodes and receives:

A list of other known nodes in the swarm
The handle registry (mapping handles to DIDs and nodes)

This happens automatically when you start the cron process — no manual intervention needed.

2. Gossip Rounds

The synapsis-cron process runs gossip rounds every 5 minutes. Each round:

Selects random peers from its known nodes
Sends them its known nodes and handles
Receives their known nodes and handles
Merges the information

Node A ←→ Node B: Exchange known nodes + handles
Node A ←→ Node C: Exchange known nodes + handles
Node A ←→ Node D: Exchange known nodes + handles

3. Information Propagation

Through gossip, information spreads exponentially:

Round 1: Node A tells 3 peers about Node X
Round 2: Those 3 peers each tell 3 more peers
Round 3: 9 more nodes learn about Node X
…and so on

Within a few rounds, the entire network knows about any new node.

Data Structures

SwarmNode

Each discovered node is tracked with:

{
  domain: string;           // e.g., "alice.synapsis.social"
  name: string;             // Display name
  description?: string;     // Node description
  publicKey: string;        // For verification
  softwareVersion: string;  // Synapsis version
  userCount: number;        // Number of users
  postCount: number;        // Number of posts
  capabilities: string[];   // ["handles", "gossip", "relay"]
  lastSeenAt: Date;         // Last successful contact
  trustScore: number;       // 0-100, reputation score
  isActive: boolean;        // Currently reachable
}

Trust Scoring

Nodes build reputation over time:

Successful sync: +1 trust score
Failed contact: -5 trust score
Range: 0-100 (default: 50)

Low-trust nodes are deprioritized in gossip selection.

Incremental Sync

To minimize bandwidth, gossip supports incremental sync:

Node A → Node B: "Give me updates since 2024-01-15T00:00:00Z"
Node B → Node A: Only nodes/handles updated after that time

Failure Handling

The system is resilient to node failures:

Consecutive failures are tracked per node
After 5 failures, a node is marked inactive
Inactive nodes are excluded from gossip
Nodes can recover by successfully responding again

Security Considerations

Current Implementation

Domain validation before adding nodes
Rate limiting on endpoints
Admin authentication for sensitive operations

Future Enhancements

HTTP signature verification for announcements
Public key pinning for known nodes
Spam prevention via proof-of-work or stake

Configuration

Key settings in src/lib/swarm/types.ts:

SWARM_CONFIG = {
  gossipIntervalMs: 5 * 60 * 1000,    // 5 minutes
  gossipFanout: 3,                     // Peers per round
  maxNodesPerGossip: 100,              // Max nodes to share
  maxHandlesPerGossip: 500,            // Max handles to share
  inactiveThresholdMs: 24 * 60 * 60 * 1000,  // 24 hours
  maxConsecutiveFailures: 5,           // Before marking inactive
}

Overview Swarm Interactions