Swarm Interactions

Synapsis uses the Swarm for all social interactions between nodes. When you like, repost, follow, or mention someone on another Synapsis node, the interaction is delivered directly via the swarm protocol — instant and real-time.

How It Works

When you interact with content from another node, Synapsis delivers the interaction directly via the Swarm API:

Your Node → Swarm API → Target Node
         ← { success: true }

All interactions are delivered in real-time with no queuing or delays.

Supported Interactions

Likes

When you like a post from another Synapsis node:

Your Node → POST /api/swarm/interactions/like → Target Node
         ← { success: true }

The target node:

Increments the post’s like count
Creates a notification for the post author
Stores a reference to your user profile

Reposts (Boosts)

Reposts work the same way:

Your Node → POST /api/swarm/interactions/repost → Target Node
         ← { success: true }

The target node receives the repost notification and updates counts in real-time.

Follows

Following a user on another Synapsis node uses swarm-first delivery:

Your Node → POST /api/swarm/interactions/follow → Target Node
         ← { success: true }

The target node:

Adds you to the user’s followers
Updates follower counts
Creates a follow notification

Swarm follows are stored with a swarm:// actor URL, making them easy to identify and manage.

Mentions

When you mention someone from another Synapsis node (e.g., @alice@other-node.com), the mention is delivered directly:

Your Node → POST /api/swarm/interactions/mention → Target Node
         ← { success: true }

The mentioned user receives a notification with your post content.

Replies

Replies to swarm posts are delivered via the existing /api/swarm/replies endpoint:

Your Node → POST /api/swarm/replies → Target Node
         ← { success: true, replyId: "..." }

Interaction Payloads

Like Payload

{
  "postId": "uuid-of-target-post",
  "like": {
    "actorHandle": "yourhandle",
    "actorDisplayName": "Your Name",
    "actorAvatarUrl": "https://your-node.com/avatar.jpg",
    "actorNodeDomain": "your-node.com",
    "interactionId": "unique-id-for-deduplication",
    "timestamp": "2024-01-20T15:30:00Z"
  }
}

Follow Payload

{
  "targetHandle": "alice",
  "follow": {
    "followerHandle": "yourhandle",
    "followerDisplayName": "Your Name",
    "followerAvatarUrl": "https://your-node.com/avatar.jpg",
    "followerBio": "Your bio",
    "followerNodeDomain": "your-node.com",
    "interactionId": "unique-id",
    "timestamp": "2024-01-20T15:30:00Z"
  }
}

Mention Payload

{
  "mentionedHandle": "alice",
  "mention": {
    "actorHandle": "yourhandle",
    "actorDisplayName": "Your Name",
    "actorAvatarUrl": "https://your-node.com/avatar.jpg",
    "actorNodeDomain": "your-node.com",
    "postId": "your-post-id",
    "postContent": "Hey @alice@other-node.com check this out!",
    "interactionId": "unique-id",
    "timestamp": "2024-01-20T15:30:00Z"
  }
}

Identifying Swarm Content

Swarm posts and users are identified by special prefixes:

Swarm Posts

Posts from swarm nodes have an apId with the format:

swarm:{nodeDomain}:{postId}

For example: swarm:other-node.com:abc123-def456

Swarm Users

Remote users from swarm nodes have actor URLs with the format:

swarm://{nodeDomain}/{handle}

For example: swarm://other-node.com/alice

Capabilities

Nodes advertise their interaction support via the interactions capability:

{
  "capabilities": ["handles", "gossip", "interactions"]
}

When a node has the interactions capability, other nodes know they can use the swarm interaction endpoints.

Security

All swarm communication uses HTTPS in production. HTTP is only used for localhost development.

Every swarm interaction must be cryptographically signed by the acting user. This prevents forgery and ensures that a node cannot perform actions on behalf of its users without their explicit authorization (via client-side signing).

Nodes are identified by their domain, and the swarm registry tracks trust scores based on successful interactions.

Benefits

Aspect	Swarm Interactions
Latency	~50-200ms
Reliability	Direct delivery
Data format	Simple JSON
Real-time	Yes
Notifications	Instant

Implementation Details

The swarm interaction system is implemented in:

src/lib/swarm/interactions.ts — Core delivery functions
src/app/api/swarm/interactions/* — Receiving endpoints
src/app/api/posts/[id]/like/route.ts — Like with swarm-first
src/app/api/posts/[id]/repost/route.ts — Repost with swarm-first
src/app/api/users/[handle]/follow/route.ts — Follow via swarm

Each interaction route delivers directly via the Swarm API.

How It Works User Profiles