Namespace

Topics use a five-tier path hierarchy:

/{protocol}/{network}/{version}/{domain}/{stream}[/{shard}]

Examples:

  • /odoo/private.myswarm/v1/ip/heartbeat — private swarm heartbeat

  • /odoo/global.earth/v1/com/offers — global product offer feed

  • /odoo/eu-ports.consortium/v2/dir/fleet/telemetry/eu-west — sharded fleet telemetry

Tier Reference

Tier

Purpose

Examples

protocol

Software ecosystem

odoo, mycompany

network

Isolation group — who can see this traffic

private.{swarm_id}, local.{node_id}, region.{id}, global.earth

version

Schema contract — allows multiple schema versions to coexist

v1, v2

domain

Content context

ip (protocols), com (markets), dir (directories), edu (learning), deb (debate)

stream

The channel or room

/sync, /ctrl, /{uuid} for on-demand channels

shard

Optional traffic partition

Geographic (eu-west), industry (fashion), or load-based split

When to Shard

PubSub broadcasts to all subscribers. If your node’s discard ratio is high — you receive many messages but only a small fraction are relevant — it is wasting bandwidth and CPU.

  • Trigger: discard ratio above 90% and throughput above 50 messages/s

  • Action: add a geographic, industry, or category tier to the topic path, e.g. /com/offers → /com/offers/eu/fashion

Nodes that produce above roughly 10 messages/s on non-critical topics should expect peer scoring penalties and eventual mesh ejection.

Migration Pattern

You cannot abruptly switch to a new topic path without losing messages that are in transit on the old one. Use a dual-listen phase instead:

  1. Subscribe to both: configure your node to listen on the old topic and the new topic simultaneously.

  2. Publish to new only: stop writing to the old topic. Peers that have not yet migrated will still receive from it during the transition.

  3. Fade out: after at least 48 hours — or once old-topic traffic drops to zero — unsubscribe from the old path.

Announce the migration on the /ip/redirect channel so other nodes can follow along.

Tip

The version tier (v1, v2) exists precisely to support schema bumps without a hard cutover. Run old and new schema versions in parallel until all peers have upgraded, then drop the old subscription.