docs / walkthrough · updated 2026-08-01

How BlobArchive uses IPFS

You do not need to understand all of IPFS to run BlobArchive. IPFS is a stack of separate protocols and data structures; BlobArchive uses a deliberately small subset of them.

At a high level:

human name                     peer discovery
DNSLink -> IPNS -> document CID     auxiliary DHT hints
                    \               /
                     verified peers
                           |
                    libp2p connection
                           |
                        Bitswap
                           |
              metadata DAGs + raw blob blocks
                           |
                    local pinned store
                           |
                 local beacon blob API

DNSLink and IPNS locate a writer operator’s current publication. In a public deployment, a separate read-only edge presents that signed state to the network and serves immutable blocks. The DHT helps nodes find peers. libp2p connects those peers. Bitswap transfers exact blocks by CID. BlobArchive adds the rules that decide which publication to trust, which DAGs to retain, and which blobs an L2 may read.

Content addressing: the CID is a hash-based name

An IPFS CID identifies content rather than a server location. BlobArchive stores each 131,072-byte EIP-4844 blob as one raw IPFS block, without UnixFS files, directories, or chunking. Its index, manifests, and head structures are small DAG-CBOR blocks that link to other blocks by CID.

The practical consequences are:

the same bytes have the same CID on every node;
a received block must hash back to the CID that requested it;
one blob shared by several heads is stored once; and
immutable blocks can be fetched from any peer that has them.

A CID proves byte identity, not meaning or completeness. BlobArchive separately checks the signed publication, head structure, coverage, KZG commitment, and requested versioned hash. A malicious writer can publish an incomplete history under its own key even though every block in that history has a valid CID.

DNSLink and IPNS: a human name for a changing publication

Archive state advances, while CIDs are immutable. BlobArchive uses two pointer layers to bridge that difference:

_dnslink.ethereum-mainnet-arb1-live-a.blobarchive.net
  TXT "dnslink=/ipns/<ipns-name>"

<signed IPNS record>
  /ipfs/<publication-document-cid>

DNSLink is an ordinary DNS TXT record. It gives operators a readable, replaceable domain name and selects one IPNS authority. DNSLink does not contain the archive or point to an HTTP server.

IPNS is a signed, sequence-numbered mutable record. The private writer constructs and signs the record and the content-addressed publication document. The public edge verifies their complete binding, provides the exact document CID, and only then puts the already-signed IPNS record into the DHT. The edge cannot sign a different record or document.

This separation is intentional:

DNS controls the human-facing name;
IPNS authenticates a changing pointer;
the document signer authenticates the writer’s archive claim; and
CIDs authenticate every immutable block reached from that claim.

The provider-before-IPNS ordering is the cold-bootstrap guarantee: a new follower should not learn a document CID from a fresh IPNS record before the public edge has advertised that exact document. Periodic exact-pointer hints for the current document, root, and manifest are auxiliary discovery redundancy, not the publication authority and not proof that the primary transaction succeeded.

The shipped profiles pin the document signer as well as the DNSLink name. Changing DNS or publishing a newer IPNS record cannot silently authorize a different signer.

Peer IDs and multiaddrs: who and where

Every IPFS/libp2p node has a durable Peer ID derived from its private identity key. A multiaddr describes one way to reach that peer, including the network address, transport, port, and Peer ID:

/ip4/203.0.113.10/tcp/4001/p2p/12D3KooW...

The Peer ID answers “which cryptographic network identity?” The rest of the multiaddr answers “how can I dial it?”

BlobArchive can connect to peers from several bounded sources:

static peers in local configuration;
addresses in an authenticated publication document;
DHT provider hints for the current document, head root, or manifest; and
DHT rendezvous records for a selected network and head.

An address is only a route to try. It does not authorize a writer or prove that the peer still has a requested block.

What the DHT does—and does not do

The public Amino DHT is a distributed routing table. A node first joins it through known bootstrap peers. BlobArchive then uses it for three narrow jobs:

publish and resolve IPNS records;
advertise and find a small set of current document/root/manifest pointers;
advertise and find deterministic rendezvous keys for selected (network, head) pairs.

A provider record roughly says: “Peer X claims it can help with CID Y; here are addresses to try.” BlobArchive treats that as an untrusted lead, bounds how many results and address bytes it accepts, and then dials the peer. The later publication and CID checks remain unchanged.

The DHT does not store the blobs, choose a canonical writer, establish a majority, or prove that a peer is reachable.

The embedded follower also does not hand the DHT to Bitswap as a generic per-block search engine. It uses the DHT to find and connect useful peers, then asks only connected peers for blocks. This keeps peer selection observable and prevents every missing blob from becoming an open-ended public routing query.

Rendezvous: find nodes interested in the same head

For every selected network and head, BlobArchive derives a stable synthetic rendezvous CID. A serving node periodically advertises itself as a provider for that CID. A joining node looks up the same CID, receives candidate Peer IDs and multiaddrs, and attempts bounded connections.

The rendezvous CID is a meeting point, not archive data. Knowing it does not grant access or trust. It only helps nodes interested in the same head find one another without a central peer registry.

BlobArchive may also advertise a bounded set of current entry points into the real archive: publication document, head root, and manifest tip. These exact-pointer hints are auxiliary to the load-bearing document provide that precedes each IPNS write. It deliberately does not walk the multi-terabyte archive and publish a provider record for every blob.

The swarm: connected peers, not one central service

The swarm is the graph of libp2p connections a node currently has. A BlobArchive node can be connected to public edges, followers, Kubo replicas, DHT bootstrap peers, and relay peers at the same time.

Joining the swarm does not mean trusting every connected node. The follower first selects a writer authority and exact head CIDs. Other peers are useful only if they can supply blocks matching those already-authenticated CIDs.

Public edges and embedded followers serve retained blocks over Bitswap by default. The edge has only read access to the writer operator’s immutable blocks and no signer. A follower can become a useful source for later followers without becoming a writer or gaining publication authority.

Bitswap: move immutable blocks

Bitswap is the IPFS block-exchange protocol. A follower traversing a selected head asks connected peers for missing CIDs. Each successful fetch is verified and written into its local block store.

Replication is therefore a DAG walk:

obtain and verify the publication document;
select an authenticated head root;
fetch its directory and segment blocks;
fetch the raw blob CIDs those segments name; and
pin the closure required by local retention policy.

The follower checks local storage first and uses Bitswap only for a miss. Once stored, the same block can be served to other peers. The local beacon API reads the committed local generation; it is not a public IPFS gateway and does not make an unauthenticated HTTP request trigger arbitrary swarm work.

NAT, relays, and hole punching

The most reliable configuration is a directly reachable swarm listener. Forward the shipped embedded node’s TCP port 4001 through the router and firewall when possible. The shipped Compose sample publishes host TCP 4001 by default; set BLOAR_P2P_PORT before starting it if that host port is already in use. BlobArchive may also request UPnP/NAT-PMP mappings, but an explicit verified forwarding rule is easier to reason about.

A node behind NAT can still dial public peers outbound. For two private peers, libp2p can use a circuit relay and DCUtR hole punching:

the private node reserves a reachable address at a relay;
peers meet through the limited relay circuit;
the relay coordinates simultaneous outbound dials; and
if the NATs permit it, the connection upgrades to a direct path.

In BlobArchive, the relay is an introduction and control plane—not the bulk archive path. The configured circuit allowance is 128 KiB, exactly one raw blob before Bitswap framing, and embedded Bitswap does not use limited relay connections for transfer. A relay reservation or successful discovery can therefore coexist with a failed blob fetch. Complete replication needs a usable direct connection.

Hole punching is helpful, not guaranteed. Carrier-grade or symmetric NATs may still prevent a direct upgrade. Port forwarding, a public peer, or a network where the private node can dial the serving peer directly remains the stronger path.

Embedded follower versus Kubo replica

Both deployment shapes speak the same content-addressed archive, but ownership differs:

Concern	Embedded follower	Kubo replica
Peer ID and libp2p host	`bloard`	Existing Kubo
Block store and Bitswap	`bloard`	Existing Kubo
Pin database and GC	BlobArchive store	Existing Kubo
Publication verification and replay floors	`bloard`	Replica controller
Local beacon API	`bloard`	Optional controller gateway

The embedded follower applies BlobArchive’s bounded DHT and peer-selection policy directly.

The Kubo replica leaves Kubo’s swarm and routing behavior intact. The controller uses Kubo’s RPC to authenticate a publication and move one controller-owned generation pin. The shipped configuration constrains Kubo’s provider strategy to roots, and the controller explicitly announces only bounded rendezvous and generation entry points rather than the entire repository.

What BlobArchive is not using

For clarity, the normal BlobArchive path is not:

uploading blobs through a public IPFS HTTP gateway;
wrapping blobs in UnixFS;
using IPFS PubSub to decide the latest head;
trusting arbitrary DHT provider results;
searching the DHT for every missing block in an embedded follower;
treating relay bandwidth as a complete-transfer fallback; or
exposing one project-operated beacon API to everyone.

The public service is the peer-to-peer block swarm. Each operator runs a local follower or replica, chooses its writer trust, retains its own archive, and serves its own L2 node locally.

Next, read discovery and trust for the authentication boundary, heads and retention for the DAG and pin model, or operate and troubleshoot for layer-by-layer diagnostics.