Skip to content

amaru-bootstrap

amaru-bootstrap builds the image and helper tools used to start relay-only Amaru nodes on custom Cardano testnets.

Current Shape

The repository used to be documented as a one-shot "bundle producer" service. That is still a useful primitive, but it is no longer the primary Antithesis integration shape.

The current Antithesis path runs the published ghcr.io/lambdasistemi/amaru-bootstrap-producer:<commit-sha> image as each long-lived amaru-relay-N container. Compose overrides the image entrypoint to amaru-relay-bootstrap. That wrapper:

  1. Writes /startup/$RELAY_NAME.started immediately for the Antithesis setup-complete gate.
  2. Copies a fresh snapshot of the paired cardano-node /live state into private scratch space.
  3. Invokes /bin/bootstrap-producer in a retry loop until the Amaru stores are complete.
  4. Promotes the produced stores into /srv/amaru.
  5. execs amaru run against the paired cardano-node peer.

There is no downstream depends_on: service_completed_successfully consumer in this relay mode. The amaru-relay-N process is the bootstrapper and the Amaru node.

Runtime Components

  • amaru-relay-bootstrap: Antithesis relay entrypoint. It owns startup marker emission, retry policy, bundle promotion, and the final amaru run command.
  • bootstrap-producer: one-shot primitive used by the relay wrapper and by local checks. It produces the Amaru ledger and chain stores from a cardano-node ChainDB.
  • db-analyser: pinned stock upstream consensus tool. The producer polls it with no analysis flag and minimum block validation for era-readiness, then runs one forward --show-slot-block-no trace to select snapshot targets. Also bundled in the image because amaru create-snapshots drives its engine internally.
  • amaru-runtime/: deployment-provided runtime files consumed by amaru run: era-history.json and global-parameters.json.

Production Pipeline

The production bootstrap pipeline is:

cardano-node ChainDB
  -> db-analyser tip poll                    (era-readiness, no analysis flag)
  -> db-analyser --show-slot-block-no        (one forward trace, targets)
  -> targets.json + snapshots.json           (from the chain's own blocks)
  -> amaru create-snapshots                  (db-analyser engine, offline)
  -> era-history sidecars                    (from genesis epochLength)
  -> amaru bootstrap                         (ledger + chain stores)
  -> amaru run

db-synthesizer is not part of this runtime path. It remains available for fixture generation and CI checks. db-analyser is bundled in the published image both because the producer invokes it directly for the readiness poll and target trace, and because amaru create-snapshots drives its engine internally.

Specs And History

The original active Spec Kit feature is specs/003-amaru-bootstrap-producer/. That spec describes the one-shot producer primitive. Later Antithesis work layered the self-bootstrap relay contract on top of that primitive; the relay wrapper's source comment names that downstream contract as spec 080.

Historical bundle-shape notes are kept under History: What Amaru needed. They explain why the project originally replaced a forked db-synthesizer, but they are not the current runtime recipe.

How To Read This Site

  • Tutorial - wire the relay bootstrap image into a Compose testnet.
  • Antithesis deployment - topology, environment variables, startup marker contract, and runtime parameter files.
  • Architecture - relay flow, producer pipeline, ChainDB contract, and state machines.
  • Bootstrap producer - lower-level one-shot producer contract and local verification commands.
  • Constitution - project principles that govern design choices.

Consumers