epic: content layer — Helia in the browser, Kubo as the platform node, Boxo where needed #43

Summary

Track the content layer for distributed-quantum: Helia in the browser for content addressing, Kubo as the always-on platform node, and Boxo (Go library) only where Kubo cannot meet a need. Also tracks Stripe stablecoin work as a separate group.

Source material: the Helia integration overview (docs/HELIA_INTEGRATION.md, added separately).

Design stance

• Compute and content stay separate planes. Content-layer failures never block or discard quantum execution.
• Prefer configuring Kubo over writing Go. Custom Boxo code needs a written justification (spike).
• Provider credentials move behind a server-side broker.

Open questions

• Where does the platform node run in production (hosting, who operates it)?
• Kubo version policy and upgrade cadence.
• Is a custom Boxo service justified? (see the Boxo spike)

Child issues

Tier 1 - good starting point (small, well-scoped, builds on existing code)

• fix(vault): drain and replay the pin retry queue #44 helia fix(vault): drain and replay the pin retry queue
• refactor(vault-pinning): use the broker and remove NEXT_PUBLIC provider credentials #46 helia refactor(vault-pinning): use the broker and remove NEXT_PUBLIC provider credentials
• chore(vault-pinning): remove the legacy nft-storage alias #47 helia chore(vault-pinning): remove the legacy nft-storage alias
• feat(vault): publish circuits to the vault #49 helia feat(vault): publish circuits to the vault
• feat(vault): versioned, validated record schemas #50 helia feat(vault): versioned, validated record schemas
• feat(vault): request persistent storage and warn about eviction #51 helia feat(vault): request persistent storage and warn about eviction
• test(vault): unit tests for local-index and sync-queue #53 helia test(vault): unit tests for local-index and sync-queue
• docs(helia): post the open design questions to the IPFS community and record answers #56 helia docs(helia): post the open design questions to the IPFS community and record answers
• test(content-node): compose-based integration test for the Kubo client #68 kubo test(content-node): compose-based integration test for the Kubo client
• docs(helia): add the content node to the architecture and target diagrams #75 kubo docs(helia): add the content node to the architecture and target diagrams

Tier 2 - needs a new service, SDK or deeper design

• feat(vault): server-side pinning broker routes #45 helia feat(vault): server-side pinning broker routes
• feat(vault-pinning): pin original blocks as a CAR so the pinned CID equals the Helia CID #48 helia feat(vault-pinning): pin original blocks as a CAR so the pinned CID equals the Helia CID
• feat(vault): export and import the vault as a CAR file #52 helia feat(vault): export and import the vault as a CAR file
• feat(vault): open any CID from a link or paste, with trustless-gateway fallback #54 helia feat(vault): open any CID from a link or paste, with trustless-gateway fallback
• feat(vault): link runs to circuits with dag-json instead of a string field #58 helia feat(vault): link runs to circuits with dag-json instead of a string field
• feat(infra): run Kubo in docker-compose (server profile, pinned version) #59 kubo feat(infra): run Kubo in docker-compose (server profile, pinned version)
• feat(content-node): lock down the Kubo RPC API and gateway #60 kubo feat(content-node): lock down the Kubo RPC API and gateway
• feat(backend): async Python client for the Kubo RPC API #61 kubo feat(backend): async Python client for the Kubo RPC API
• feat(vault): platform Kubo node as a pinning provider #62 helia/kubo feat(vault): platform Kubo node as a pinning provider
• feat(content-node): delegated-routing endpoint used by Helia #64 helia/kubo feat(content-node): delegated-routing endpoint used by Helia
• feat(content-node): reprovide only pinned content #65 kubo feat(content-node): reprovide only pinned content
• feat(ops): Kubo storage limits, garbage collection and Prometheus metrics #66 kubo feat(ops): Kubo storage limits, garbage collection and Prometheus metrics
• feat(provenance): publish each provenance bundle to Kubo, best effort #67 kubo feat(provenance): publish each provenance bundle to Kubo, best effort
• feat(backend): Python gateway client that fetches by CID and verifies content #73 kubo feat(backend): Python gateway client that fetches by CID and verifies content
• feat(provenance): IPFS storage adapter for bundle verification #74 kubo feat(provenance): IPFS storage adapter for bundle verification

Tier 3 - distinct stack or research; start with a small scoped deliverable

• spike(vault): one Helia node per browser (SharedWorker vs Web Locks) #55 helia spike(vault): one Helia node per browser (SharedWorker vs Web Locks)
• spike(vault): large artefacts with UnixFS in an IndexedDB blockstore #57 helia spike(vault): large artefacts with UnixFS in an IndexedDB blockstore
• feat(content-node): browser-reachable multiaddrs for Helia nodes #63 helia/kubo feat(content-node): browser-reachable multiaddrs for Helia nodes
• spike(content-node): Kubo pubsub bridged to py-libp2p GossipSub #69 kubo spike(content-node): Kubo pubsub bridged to py-libp2p GossipSub
• spike(vault): IPNS author feeds with Kubo-held keys #70 kubo spike(vault): IPNS author feeds with Kubo-held keys
• spike(content-node): what Kubo cannot do, and whether a custom Boxo service is justified #71 boxo spike(content-node): what Kubo cannot do, and whether a custom Boxo service is justified
• feat(content-node): CID allowlist and takedown denylist for the public gateway #72 boxo feat(content-node): CID allowlist and takedown denylist for the public gateway

Ground rules: testnet-first, no secrets in the repo, tests and docs with every PR.