Kubo / IPFS Transport¶

Decentralised exchange via a Python gateway sidecar and the Kubo IPFS daemon.

When to Use Kubo¶

Large networks — or small networks exchanging large binary payloads — where HTTP fan-out is expensive
Offline-first networks where nodes may be temporarily unreachable
Public networks that need to admit new nodes without API key exchange
Deployments that already run an IPFS infrastructure
LAN environments where mDNS peer discovery is preferable to static URLs

For simpler deployments that do not need those benefits, HTTP Transport is easier to set up and operate.

Setup Checklist¶

With demo data installed, a swarm, local node, API user, and foreign node placeholders are already created. The checklist below covers a manual setup from scratch (or filling in the demo placeholders).

After docker compose up, retrieve the Kubo node’s PeerID:

docker compose exec ipfs ipfs id

Copy the ID field and open the “Kubo Local Gateway” peer record in Odoo (Sync ▸ Network ▸ Peers). Paste the PeerID into PeerID and save. Then open the matching node record (Sync ▸ Network ▸ Nodes → “Kubo Local Gateway”) and set:

Kubo URL — to match IPFS_URL from your .env (e.g. http://ipfs:5001)
Gate URL — to match GATEWAY_URL from your .env (e.g. http://gateway:8000)

The node will appear in the Nodes tab of the Kubo swarm and is_online will become True once the first heartbeat arrives.

The following fields are set on each Kubo node:

Field	Description
`ip.node.kubo_url`	Kubo/Sync sidecar API endpoint, used for direct CID management (add / cat).
`ip.node.gate_url`	Gateway API endpoint, used for express requests (send events / fetch CIDs).

Transport Specifics¶

Event Routing: Kubo leverages Libp2p’s Gossipsub for broadcasts and direct P2P tunnels for direct events. It is designed for high-churn networks and environments where Odoo instances may experience intermittent connectivity. Events are dispatched via ip.swarm._dispatch_events(); the gateway calls ip.node._gate_request() to forward them to the Python sidecar.
CID Resolution: Kubo resolves CIDs asynchronously via the local IPFS daemon. It employs a multi-tiered priority queue:
- Priority 0: Direct P2P deliveries (sub-second retrieval, bypasses verifier).
- Priority 1: Trusted peers (direct fetch).
- Priority 2: Unknown peers (passes through the DHT verifier first to check blob size/existence).
Constraints: Gossipsub topics are optimized for signaling and small control packets. Keep payload sizes small (max 256 KB) and offload all bulk binary data to CID references to avoid network congestion and peer scoring penalties.