Swarm, Node, Peer

Swarm (ip.swarm)

A swarm is an isolated, named sync network. Nodes that share a swarm can exchange events over a common transport; nodes in different swarms never interact.

network_type is set once on creation (http or kubo) and is immutable — the transport encoding and dispatch logic are fundamentally different between the two, so changing it in place is not supported.

Important

To switch a swarm from HTTP to Kubo, create a new swarm with the desired transport and migrate your topics to it. The old swarm can remain active during the transition.

The same Odoo instance can join multiple swarms simultaneously. Each swarm has its own network_type and its own set of peer nodes. Topics are linked to swarms via a Many2many field, so a single topic can publish to swarms with different transports simultaneously — for example one HTTP swarm for low-latency sync and one Kubo swarm for large-binary replication.

See also

Technical references — sync_base.ip.swarm, sync_http.ip.swarm, sync_kubo.ip.swarm.

Node (ip.node)

A node is an authenticated participant in a swarm. Each node has:

• a peer identity (ip.peer) — an Ed25519 keypair identified by a Base58btc PeerID derived from the public key.

• optional transport-specific credentials — an Odoo URL + API key (sync_http) or Kubo/gateway endpoints (sync_kubo).

• a liveness timestamp (ip.node.last_seen) used to compute ip.node.is_online.

Every swarm has exactly one local node — the managed Odoo instance or Kubo gateway that talks to the swarm. The local node is created automatically when the swarm is saved (ip.node.is_gateway = True); it cannot be deleted without deleting the swarm.

All other nodes are foreign nodes — remote Odoo instances or Kubo gateway endpoints registered in the swarm’s Nodes tab.

One key difference between HTTP and Kubo swarms lies in the API key management:

• For HTTP, each foreign node must provide an API key, which is set on that node. New nodes must exchange API keys with ALL existing nodes.

• For Kubo, a single API key gives access to the Gateway, and is set on the local node. No key exchange needed !

To add a peer node see HTTP Transport (HTTP transport) or Kubo / IPFS Transport (Kubo/IPFS transport).

See also

Technical references — sync_base.ip.node, sync_http.ip.node, sync_kubo.ip.node.

Peer (ip.peer)

A peer holds the cryptographic identity. The same peer can be associated with a contact (res.partner.peer_id) and a user (own_peer_id).

Key operations:

• Generate: ip.peer.action_generate_keys() creates an Ed25519 keypair and derives the PeerID.

• Sign: ip.peer._sign_payload() signs arbitrary bytes with the private key.

• Verify: ip.peer._verify_signature() checks a signature against a payload and public key.

Danger

The ip.peer.private_key field stores the raw PEM-encoded Ed25519 private key. It is readable only to users in the sync_manager group. Never expose it via a public controller, store it in logs, or include it in database dumps shared outside your organisation.

A peer is said to be a host peer if it holds a node’s identity, and a guest peer if it does not. Host peers have a ip.node.peer_id which is the inverse Many2one relation of peer_id. All peers have a host_node_id — the node where that identity lives and communicates from (equal to node_id for hosts). For your own users or contacts this is the local node. For remote contacts it is their own local node (foreign to you) registered in the swarm.

See also

sync_base.ip.peer — technical reference. Security — Ed25519 identity, trust levels, bearer tokens, and defense-in-depth model.