Mithril Snapshot

Mithril is a signature scheme that generates a certificate to convince verifiers that a portion of the stake of a system has signed a message. There’s currently a network of Cardano SPOs continuously verifying snapshots of the history of the chain and making them available for consumption by client applications, such as Dolos.

Dolos uses the Mithril Cardano Database v2 snapshot format, which certifies immutable files via a Merkle tree. This allows Dolos to download and verify individual immutable file chunks incrementally rather than requiring a single monolithic archive. Ancillary files (ledger state) are not downloaded; Dolos rebuilds ledger state from block history.

From Dolos’ perspective, the process of bootstrapping with Mithril involves the following steps (which are executed automatically):

1. Downloading a snapshot from a cloud server
2. Verifying that the Mithril signature is valid
3. Importing block data into Dolos’ internal representation
4. Re-creating the ledger state from the chain history

Configuration

To use Mithril snapshots, Dolos requires a few configuration values to download and verify data:

property	type	example
aggregator	string	”https://aggregator.release-preprod.api.mithril.network/aggregator”
genesis_key	string	”5b3…45d” (redacted)
ancillary_key	string	”5b3…36d” (redacted)

• aggregator: url of the Mithril aggregator
• genesis_key: hex-encoded value of the Mithril genesis key
• ancillary_key: optional hex-encoded value of the Mithril ancillary verification key

This is how the configuration fragment would look like inside a dolos.toml file:

[mithril]
aggregator = "https://aggregator.release-preprod.api.mithril.network/aggregator"
genesis_key = "5b3132372c37332c3132342c3136312c362c3133372c3133312c3231332c3230372c3131372c3139382c38352c3137362c3139392c3136322c3234312c36382c3132332c3131392c3134352c31332c3233322c3234332c34392c3232392c322c3234392c3230352c3230352c33392c3233352c34345d"
ancillary_key = "5b3138392c3139322c3231362c3135302c3131342c3231362c3233372c3231302c34352c31382c32312c3139362c3230382c3234362c3134362c322c3235322c3234332c3235312c3139372c32382c3135372c3230342c3134352c33302c31342c3232382c3136382c3132392c38332c3133362c33365d"

Note

If you use the dolos init command to initialize your configuration, these values will be already populated with their defaults for each of the known networks.

Execution

To execute the Mithril bootstrap procedure, you need to run the following command line:

dolos bootstrap mithril

The process will take from several minutes to a few hours depending on the network. You’ll see a sequence of progress bars describing each of the steps of the process.

Note

If you use the dolos init command, bootstrap is triggered automatically after configuration so you don’t need to run this manually.

Note

The process supports resuming from previous runs (use the global --continue flag to allow bootstrap to proceed when Dolos storage already has data). The download step resumes automatically: if immutable files already exist in the download directory, only the missing ones are fetched.

In addition to the global bootstrap flags, the mithril subcommand accepts the following flags:

arg	description	default
--download-dir <DIR>	Directory to store the downloaded snapshot	./snapshot
--skip-validation	Skip the Mithril certificate validation	false
--skip-download	Assume the snapshot is already available in the download dir	false
--retain-snapshot	Retain downloaded snapshot instead of deleting it	false
--chunk-size <N>	Number of blocks to process per chunk (more is faster but uses more memory)	500
--start-from <POINT>	Resume import from a specific chain point	none
--download-start <N>	Start downloading from this immutable file number (inclusive)	none
--download-end <N>	Download up to this immutable file number (inclusive)	none

When --download-start and --download-end are not specified, the full range of immutable files is downloaded and verified. If immutable files already exist in the download directory, the download resumes from the highest file present (which is re-fetched in case a previous run left it incomplete); certificate verification still covers the full set of immutable files. When an explicit range is given, verification is scoped to that range.