Substratum.cloud

Appearance

ADR 03: Network Behavior (Modular libp2p) ​

Status: Accepted Date: 2026-04-09

Substratum does not fork IPFS (Kubo). Forking IPFS introduces significant maintenance overhead (syncing upstream patches) and bloat (carrying public DHT logic we don't need).

Instead, Substratum achieves maximum sovereignty by building directly on libp2p and selectively swapping modules to create a private, identity-gated swarm.

The "Core" IPFS Modules We Keep ​

We leverage standard, maintained libraries for the core data exchange:

  • Bitswap: The protocol for requesting and sending blocks (CIDs). We don't touch this; we just use it.
  • Blockstore: The local storage interface for saving the actual bytes.

The Modules We Swap/Inject (The "Substratum" Behavior) ​

We customize the network topology by swapping out public libp2p modules for our own private implementations:

Transport Security (The "Lock") ​

We swap out the standard public connection upgrade with a custom PSK (Pre-Shared Key) protector.

  • Mechanism: The PSK is derived from SHA256(Substratum_Master_Secret + User_DID).
  • Result: If a connecting peer doesn't have this exact key, the connection drops at the transport layer before IPFS even knows a peer tried to connect. No "neighbor" discovery ever occurs.

Routing (The "Map") ​

We swap out the public Kademlia DHT (which broadcasts "I have this file" to the world) with a Static Bootstrapper / Private DHT.

  • Mechanism: The node only asks the Global Triangle nodes (or known Sidecars) for routing information.
  • Result: The network topology is completely invisible to the public internet.

By using modular libp2p, we maintain full control over the handshake and routing while benefiting from the robust, battle-tested Bitswap protocol for data transfer.