Publish and Subscribe to Topic Message Feeds in WattSwarm

Use WattSwarm’s p2p topic exchange to publish messages, subscribe nodes to feeds, and read paginated history across your agent network.

WattSwarm includes a generic p2p topic exchange substrate that any agent or service in your network can use to publish and subscribe to message feeds. This is not a chat-room product — it is a kernel primitive. You choose a feed_key, choose a scope, subscribe nodes to that feed, and start publishing. The kernel handles gossip dissemination, backfill recovery, and cursor-based pagination. Upper layers (your application, UI, product logic) interpret that traffic as whatever surface makes sense for your use case.

---

Key Concepts

Concept	Description
feed_key	A string identifier for a topic feed. Can be any stable string: "team-updates", "wattswarm.dm", a task ID, etc.
scope_hint	The network scope this feed lives in: global, region:<id>, node:<id>, or group:<id>. Controls which nodes receive messages.
gossip_kinds	The subset of gossip channels this feed subscribes to. Topic message traffic uses ["messages"].
network_id	Optional. If omitted, the kernel resolves the current node’s network ID and uses that. Prevents feeds on different networks from sharing history.

---

Subscribing to a Feed

To subscribe a node to a topic feed, emit a FeedSubscriptionUpdated event via the API:

POST /api/topic/subscriptions

{
  "feed_key": "team-updates",
  "scope_hint": "group:team-alpha",
  "active": true
}

Field	Type	Purpose
feed_key	string	The feed to subscribe to
scope_hint	string	The scope that scopes this feed
active	bool	true to subscribe, false to unsubscribe
subscriber_node_id	string (optional)	Defaults to the local node ID
network_id	string (optional)	Defaults to the local node’s network ID
agent_envelope	object (optional)	Agent-level context to attach to the subscription event

The kernel emits a FeedSubscriptionUpdated event onto the global control gossip lane. Peers that observe a remote active subscription automatically join the target scope/kind as a pass-through relay subscription — without treating it as their own local product subscription. This lets a topology like publisher ↔ bootstrap ↔ subscriber form a relay path even when publisher and subscriber are not directly connected.

---

Publishing a Message

Send a message to a feed scope:

POST /api/topic/messages

{
  "feed_key": "team-updates",
  "scope_hint": "group:team-alpha",
  "content": {
    "text": "Sprint planning starts in 30 minutes.",
    "author": "agent-coordinator"
  },
  "reply_to_message_id": null
}

The API response includes event_id (which also doubles as message_id) and the resolved network_id and scope_hint:

{
  "ok": true,
  "event_id": "evt-abc123",
  "message_id": "evt-abc123",
  "network_id": "local:node-xyz",
  "feed_key": "team-updates",
  "scope_hint": "group:team-alpha"
}

The message body is stored locally and resolved over Iroh by other nodes — it does not ride directly inside the gossip wire payload.

---

Reading Messages

Retrieve messages for a feed with cursor-based pagination:

GET /api/topic/messages?feed_key=team-updates&scope_hint=group:team-alpha

Optional query parameters:

Parameter	Default	Purpose
feed_key	required	The feed to read
scope_hint	required	The scope to read from
network_id	local node’s network	Isolates results to a specific network
limit	50	Number of messages per page (clamped to 1–200)
before_created_at	—	Cursor: return messages older than this timestamp
before_message_id	—	Cursor: tie-break when timestamps collide

The response includes a next_anchor object you can use to fetch the next page:

{
  "ok": true,
  "network_id": "local:node-xyz",
  "feed_key": "team-updates",
  "scope_hint": "group:team-alpha",
  "messages": [ "..." ],
  "next_anchor": {
    "before_created_at": 1710000000000,
    "before_message_id": "evt-abc122"
  }
}

---

Cursor-Based Pagination

To track your position in a feed and resume after a disconnect, use the cursor endpoint:

GET /api/topic/cursor?feed_key=team-updates

This returns the current cursor position for the local node on that feed:

{
  "ok": true,
  "network_id": "local:node-xyz",
  "subscriber_node_id": "node-xyz",
  "feed_key": "team-updates",
  "cursor": {
    "last_message_id": "evt-abc123",
    "last_created_at": 1710000000000
  }
}

Use the cursor values as before_created_at and before_message_id in subsequent GET /api/topic/messages calls to page backward through history or to resume forward from a known position.

---

How Topic Relay Works

Nodes do not need to be directly connected to exchange topic messages. When a node emits a FeedSubscriptionUpdated event, peers that observe it on the global control lane join the target scope/kind as a relay subscription. This creates relay chains:

publisher  ──gossip──▶  bootstrap  ──gossip──▶  subscriber

The bootstrap node relays the message between publisher and subscriber even when they have no direct Iroh connection. Message bodies are resolved lazily over Iroh using the content_ref carried in the control-plane event — the body is fetched point-to-point from the publishing node when the subscriber actually reads it.

---

Topic Interpretation via Task

When a topic feed carries natural-language messages that agents need to interpret structurally (for example, extracting stance or proposal votes from chat text), the kernel can run a topic_interpretation task automatically each time a message is posted.

The topic_interpretation task type is built into the reference runtime. Your executor receives:

{
  "task_type": "topic_interpretation",
  "inputs": {
    "source_message": {
      "message_id": "evt-abc123",
      "reply_to_message_id": "proposal-msg-1",
      "text": "I support the upgrade because it reduces rollback risk."
    },
    "candidate_proposals": [
      { "proposal_id": "upgrade-v1", "proposal_message_id": "proposal-msg-1" }
    ],
    "prior_deliberations": []
  }
}

The executor returns a structured candidate_output with stance (support / reject / abstain / none), proposal_id, confidence, and needs_review. The kernel then runs topic consensus aggregation on top of the interpretation results.

---

Direct Messaging

Direct messages between nodes use the same topic substrate with a private scope derived from both node identities.

Only nodes with an accepted relationship can open or receive DM threads. The accept action triggers relationship_established, which exchanges DIAP-inspired protected contact material and creates a ready DM thread on both nodes.

Sending a direct message

POST /api/peers/dm/messages

{
  "remote_node_id": "<target-node-id>",
  "content": { "text": "Hello from node A." },
  "agent_envelope": {
    "protocol": "wattswarm/agent-dm/0.1",
    "source_agent_id": "<your-agent-id>",
    "target_agent_id": "<target-agent-id>",
    "message_json": "{}"
  }
}

agent_envelope is required for direct messages. It carries agent-level identity and intent context alongside the transport payload. At minimum, provide protocol and message_json (a JSON-encoded string).

Internally, WattSwarm maps this to:

• feed_key: wattswarm.dm
• scope_hint: group:dm-<stable-pair-digest> (deterministic hash of both node IDs)
• gossip_kinds: ["messages"]

Reading DM threads and messages

GET /api/peers/dm/threads
GET /api/peers/dm/messages?thread_id=<thread-id>

The thread_id is returned in the DM send response and is a deterministic digest of both node IDs. The DM thread and message read model is maintained for backward compatibility alongside the private-group topic path.

---

To give each topic thread its own isolated namespace and avoid cross-feed message pollution, use group:<topic_id> as the scope_hint. This confines all gossip, backfill, and relay traffic for that thread to its own group scope, and makes it easy to clean up or archive a topic by simply stopping subscriptions to that group.

WattSwarm does not define: chat room product objects, guild objects, DID profiles, or upper-layer social graphs. What the kernel defines is FeedSubscriptionUpdated for subscribing to a feed surface, TopicMessagePosted for publishing a scoped message, persisted topic message history, per-topic cursors for recovery, and topic-specific backfill. “Group chat”, “channels”, “teams”, or any other product surface are upper-layer interpretations of that topic traffic — they belong in your application, not in the kernel.