blobarchive.net

docs / guide · updated 2026-08-01

Attach BlobArchive to Kubo

A BlobArchive follower/replica operator can attach bloar-kubo-replica to an existing Kubo node, often beside the L2 node that will consume it. Kubo remains the block store, Peer ID, swarm host, pin database, and GC authority. The replica controller adds publication authentication, replay protection, exact generation pins, and an optional read-only local beacon gateway.

There is no second FlatFS archive. The controller never runs an indexer, writer, or ingest endpoint.

How BlobArchive uses IPFS explains which parts remain owned by Kubo and how discovery, Bitswap, pins, relays, and direct connections fit together.

It also does not require an Ethereum execution client, consensus client, validator, semi-supernode, or supernode. Complete-blob acquisition belongs to the selected writer; the controller authenticates and retains the published archive in Kubo.

Fast path: shipped Compose sample

The existing-Kubo quickstart ships a complete Compose file and a strict Arbitrum One finalized-plus-live configuration. The current sample does not use host networking: it creates one operator-owned internal bridge and binds Kubo’s bearer-authenticated RPC to that bridge gateway. Follow the quickstart’s Prepare Kubo section in full, then:

# Release source archive: compose file and starter config.
curl -fsSL -o bloar-v0.1.0.tar.gz \
  https://github.com/blobarchive/bloar/archive/refs/tags/v0.1.0.tar.gz
tar xzf bloar-v0.1.0.tar.gz
cd bloar-0.1.0/deploy/quickstart/kubo-replica

# Small text file naming the image digest, not the image itself.
curl -fsSL -O \
  https://github.com/blobarchive/bloar/releases/download/v0.1.0/bloar-v0.1.0-image.env
set -a
. ./bloar-v0.1.0-image.env
set +a
sudo install -d -m 0750 -o 65532 -g 65532 state
docker compose pull
docker compose run --rm replica \
  -config /etc/bloar/kubo-replica.yaml -check
docker compose up -d

Compose refuses to pull or start when the release’s immutable BLOAR_IMAGE_DIGEST is absent. The controller runs non-root with a read-only root filesystem, no Linux capabilities, no-new-privileges, bounded CPU/memory/PIDs/file descriptors/logs, and one documented writable state directory. It cannot enter the host loopback namespace or reach unrelated host services. Metrics remain on 127.0.0.1:9097; the read-only gateway is http://127.0.0.1:8550/live.

The remaining sections explain the Kubo-wide policy and trust choices that must be understood before starting it.

1. Check the operational fit

Use a separate Kubo instance if changing node-wide providing policy would break another workload. A selected full head can add terabytes to the repository, and the controller does not impose a quota.

The supported release line is stable Kubo 0.42.x.

ipfs version --number
ipfs config Provide.Enabled
ipfs config Provide.Strategy

Replica mode requires:

Provide.Enabled = true
Provide.Strategy = roots

Record the prior values, set them if necessary, restart Kubo with its normal service manager, and run the three checks again.

roots is load-bearing. The alternatives can periodically traverse the multi-terabyte archive to advertise every block or every recursive-pin descendant.

2. Put only Kubo RPC on the control bridge

Kubo’s RPC is an administrative API. The shipped sample’s prepare-control-network.sh creates or verifies an internal Docker bridge with a stable gateway. Kubo listens on that gateway only; the controller joins the bridge and supplies a bearer token from a read-only credential file. No host networking and no TCP 5001 host publish are involved.

Before changing Kubo, save its current Addresses.API and API.Authorizations, then follow the quickstart README’s exact provider, allowlist, listener, restart, and unauthenticated-403 checks. The runtime token deliberately omits /api/v0/config, because Kubo authorizes by path and cannot make configuration reads non-mutating. Provider-policy verification therefore runs natively on the host before the controller starts.

Never expose Kubo RPC directly to an untrusted network or attach unrelated containers to the control bridge. The bearer still permits repository-wide block, pin, provide, routing, and swarm calls needed by the controller. Use a dedicated Kubo instance when unrelated pins need an RCE-grade isolation boundary rather than application-level ownership discipline.

3. Configure the controller

Start from the shipped strict example. Preserve the controller’s state path across every restart.

A version-2 filtered finalized plus live selection has this shape:

version: 2
net: mainnet

replica:
  id: arb1-replica
  state_path: /var/lib/bloar-kubo-replica/state
  heads:
    arbitrum-one:
      kind: finalized-monotonic
    unfinalized:
      kind: unfinalized-mutable
      handoff_head: all
      max_window_slots: 128
      overlay_finalized_head: arbitrum-one

source:
  dnslink: ethereum-mainnet-arb1-live-a.blobarchive.net
  pubkey: 6698f6c8767529ffb725ce5201a86602106cc87ed7c9129a649428ca0ea6d7b5

The shipped source is a curated default, not a protocol allowlist. A follower/replica operator may instead configure any writer’s DNSLink and pinned signer, including a writer published under that operator’s or an L2 owner’s domain. No project approval is required.

The signed all entry authenticates the global live handoff but is metadata only in this selection. The generation pin retains arbitrum-one and the complete bounded unfinalized snapshot.

The shipped controller polls for a new publication once per minute. Because writers also publish authenticated generations in batches, the local live view normally adopts new blobs roughly one to two minutes after the source sees them, not once per Ethereum slot. Public DHT conditions and bounded retries can occasionally extend that delay to several minutes. These are healthy-path expectations, not a ceiling: a publication outage can keep returning valid but frozen state for much longer. Monitor the age of the last accepted generation rather than request errors. Initial recursive pinning and catch-up after downtime can take much longer.

4. Enable the optional local gateway

The gateway reads only the committed generation from Kubo’s local blockstore:

gateway:
  enabled: true
  listen: 127.0.0.1:8550
  beacon:
    genesis_time: 1606824023
    seconds_per_slot: 12
    genesis_validators_root: "0x4b363db94e286120d76eb905340fdd4e54bfe9f06bf33ff6cf5ad27f511bfe95"
    genesis_fork_version: "0x00000000"
  live_heads:
    live:
      finalized_head: arbitrum-one
      unfinalized_head: unfinalized
      require_versioned_hashes: true

This is not a Kubo proxy. A request miss does not initiate Bitswap, and every Kubo block read uses the offline local capability. Mutation routes are absent and return 404.

Keep the listener on loopback or a private network unless you deliberately add TLS, deadlines, connection caps, response-memory admission, and rate limits.

5. Check before serving

The controller’s live check verifies Kubo version, capabilities, Peer ID, provider configuration, RPC policy, source authentication, and local listeners:

bloar-kubo-replica -config /etc/bloar/kubo-replica.yaml -check

The follower/replica operator starts the service only after that passes, then monitors both the controller and Kubo. A long recursive pin is observable replication lag, not a reason to drop the previous committed generation. The selected writer operator—not the follower/replica operator—owns upstream source-schedule completeness.

Use the Kubo replica monitoring table to cover the controller, Kubo, generation transitions, cleanup, announcements, and the local read path.

Generation safety

A transition retains the candidate before retiring the old anchor:

  1. persist pending intent;
  2. add and verify the candidate recursive pin;
  3. commit checkpoint and current generation; then
  4. remove only the old pin recorded as controller-owned.

Kubo GC may run during the transition. The old generation remains serviceable until the new one is committed, and unrelated pins and MFS content are outside the controller’s ownership.

For exact configuration, backup, migration, and troubleshooting, read the standalone Kubo replica guide.