Version: Current

Mithril client node

info

Mithril client is responsible for restoring the Cardano blockchain on an empty node from a certified snapshot.

tip

For more information about the Mithril network, please see the architecture overview
For more information about the Mithril client node, please see this overview
Check out the Bootstrap a Cardano node guide.

info

The Mithril network configurations are available in the Network configurations section of the user manual.

Resources

Node	Source repository	Rust documentation	Docker packages	Network configurations
Mithril client CLI	↗️	↗️	↗️	↗️

Prerequisites

Linux / Mac
Windows

Install the latest stable version of the correctly configured Rust toolchain
Install build tools build-essential and m4; for example, on Ubuntu/Debian/Mint, run sudo apt install build-essential m4
Install OpenSSL development libraries; for example, on Ubuntu/Debian/Mint, run apt install libssl-dev.

Download the source file

Download the source file from GitHub (HTTPS):

git clone https://github.com/input-output-hk/mithril.git

Or (SSH):

git clone git@github.com:input-output-hk/mithril.git

Switch to the desired branch/tag:

# Replace **YOUR_BUILD_BRANCH_OR_TAG** with the appropriate branch or tag name
# Please refer to the [**Network configurations**](http://mithril.network/manual/getting-started/network-configurations) section of the user manual
git checkout **YOUR_BUILD_BRANCH_OR_TAG**

Change the directory:

Linux / Mac
Windows

cd mithril/mithril-client-cli

cd mithril\mithril-client-cli

Development testing and building

Run tests:

Linux / Mac
Windows

make test

cargo test

Create the help menu:

Linux / Mac
Windows

make help

cargo run -- -h

Generate the Rust documentation:

Linux / Mac
Windows

make doc

cargo doc --no-deps --open

Run in debug mode with the default configuration:

Linux / Mac
Windows

make debug

cargo run

Building for release and running the binary

Build and run in release mode with the default configuration:

Linux / Mac
Windows

make run

cargo build --release; copy ..\target\release\mithril-client.exe .; .\mithril-client

Or, build only in release mode:

Linux / Mac
Windows

make build

cargo build --release; copy ..\target\release\mithril-client.exe .

Display the help menu:

Linux / Mac
Windows

./mithril-client --help

.\mithril-client --help

You should see:

This program shows, downloads and verifies certified blockchain artifacts.

Usage: mithril-client [OPTIONS] <COMMAND>

Commands:
  cardano-db                  Cardano db management (alias: cdb)
  mithril-stake-distribution  Mithril stake distribution management (alias: msd)
  cardano-transaction         Cardano transactions management (alias: ctx)
  cardano-stake-distribution  Cardano stake distribution management (alias: csd)
  cardano-db-v2               Deprecated, use `cardano-db` instead
  tools                       [unstable] Tools commands
  help                        Print this message or the help of the given subcommand(s)

Options:
      --run-mode <RUN_MODE>
          Run Mode [env: RUN_MODE=] [default: dev]
  -v, --verbose...
          Verbosity level (-v=warning, -vv=info, -vvv=debug, -vvvv=trace)
      --config-directory <CONFIG_DIRECTORY>
          Directory where configuration file is located [default: ./config]
      --aggregator-endpoint <AGGREGATOR_ENDPOINT>
          Override configuration Aggregator endpoint URL [env: AGGREGATOR_ENDPOINT=]
      --log-format-json
          Enable JSON output for logs displayed according to verbosity level
      --log-output <LOG_OUTPUT>
          Redirect the logs to a file
      --unstable
          Enable unstable commands
      --origin-tag <ORIGIN_TAG>
          Request origin tag
  -h, --help
          Print help
  -V, --version
          Print version

Run in release mode with the default configuration:

Linux / Mac
Windows

./mithril-client

.\mithril-client

Run in release mode with a specific mode:

Linux / Mac
Windows

./mithril-client --run-mode preview

.\mithril-client --run-mode preview

Run in release mode with a custom configuration using environment variables:

Linux / Mac
Windows

GENESIS_VERIFICATION_KEY=$(wget -q -O - **YOUR_GENESIS_VERIFICATION_KEY**) AGGREGATOR_ENDPOINT=**YOUR_AGGREGATOR_ENDPOINT** ./mithril-client

$env:GENESIS_VERIFICATION_KEY = curl.exe --silent - **YOUR_GENESIS_VERIFICATION_KEY**; $env:AGGREGATOR_ENDPOINT=**YOUR_AGGREGATOR_ENDPOINT**; .\mithril-client

tip

To display results in JSON format for the list and show commands, simply use the --json (or -j) option:

Linux / Mac
Windows

./mithril-client cardano-db snapshot list --json

.\mithril-client cardano-db snapshot list --json

tip

If you wish to delve deeper and access several levels of logs from the Mithril client, use the following:

Add -v for some logs (WARN)
Add -vv for more logs (INFO)
Add -vvv for even more logs (DEBUG)
Add -vvvv for all logs (TRACE).

Download the pre-built binary

Linux / Mac
Windows

You can install a the latest released binary of the mithril-client by running this one line command (replace YOUR_PATH with your installation path):

curl --proto '=https' --tlsv1.2 -sSf
https://raw.githubusercontent.com/input-output-hk/mithril/refs/heads/main/mithril-install.sh
| sh -s -- -c mithril-client -d latest -p YOUR_PATH

tip

You can also install the mithril-client binary for other distributions:

use -d unstable for the unstable version
use -d **DISTRIBUTION_VERSION** for a specific distribution (e.g. -d 2445.0)

info

The Linux binaries target glibc, and have a minimum requirement of glibc 2.35 (compatible with Ubuntu 22.04 or Debian 12 - Bookworm).

Run a Docker container

Registry image

A list of available images on the registry can be found here.

To prepare the environment variables, retrieve the values from the Mithril networks section.

Linux / Mac
Windows

export MITHRIL_IMAGE_ID=**YOUR_MITHRIL_IMAGE_ID**
export AGGREGATOR_ENDPOINT=**YOUR_AGGREGATOR_ENDPOINT**
export GENESIS_VERIFICATION_KEY=$(wget -q -O - **YOUR_GENESIS_VERIFICATION_KEY**)
export SNAPSHOT_DIGEST=latest

$env:MITHRIL_IMAGE_ID="**YOUR_MITHRIL_IMAGE_ID**"
$env:AGGREGATOR_ENDPOINT="**YOUR_AGGREGATOR_ENDPOINT**"
$env:GENESIS_VERIFICATION_KEY = curl.exe --silent - **YOUR_GENESIS_VERIFICATION_KEY**
$env:SNAPSHOT_DIGEST="latest"

Here is an example configuration for the release-preprod network and the latest stable Docker image:

Linux / Mac
Windows

export MITHRIL_IMAGE_ID=latest
export AGGREGATOR_ENDPOINT=https://aggregator.release-preprod.api.mithril.network/aggregator
export GENESIS_VERIFICATION_KEY=$(wget -q -O - https://raw.githubusercontent.com/input-output-hk/mithril/main/mithril-infra/configuration/release-preprod/genesis.vkey)
export SNAPSHOT_DIGEST=latest

$env:MITHRIL_IMAGE_ID="latest"
$env:AGGREGATOR_ENDPOINT="https://aggregator.release-preprod.api.mithril.network/aggregator"
$env:GENESIS_VERIFICATION_KEY = curl.exe --silent - https://raw.githubusercontent.com/input-output-hk/mithril/main/mithril-infra/configuration/release-preprod/genesis.vkey
$env:SNAPSHOT_DIGEST="latest"

Proceed by creating a shell function for the Mithril client:

Linux / Mac
Windows

mithril_client () {
  docker run --rm -e GENESIS_VERIFICATION_KEY=$GENESIS_VERIFICATION_KEY -e AGGREGATOR_ENDPOINT=$AGGREGATOR_ENDPOINT --name='mithril-client' -v $(pwd):/app/data -u $(id -u) ghcr.io/input-output-hk/mithril-client:$MITHRIL_IMAGE_ID $@
}

function mithril_client {
  docker run --rm -e GENESIS_VERIFICATION_KEY=$env:GENESIS_VERIFICATION_KEY -e AGGREGATOR_ENDPOINT=$env:AGGREGATOR_ENDPOINT --name='mithril-client' -v ${PWD}:/app/data ghcr.io/input-output-hk/mithril-client:$env:MITHRIL_IMAGE_ID $args
}

Now you can use the mithril_client functions:

# 1- Help
mithril_client help

# 2- List Cardano db snapshots
mithril_client cardano-db snapshot list

# 3- Show detailed information about a Cardano db snapshot
mithril_client cardano-db snapshot show $CARDANO_DB_DIGEST

# 4- Download the given Cardano db and verify the certificate
mithril_client cardano-db download --include-ancillary --ancillary-verification-key $ANCILLARY_VERIFICATION_KEY $CARDANO_DB_DIGEST

# 5- List Mithril stake distributions
mithril_client mithril-stake-distribution list

# 6- Download and verify the given Mithril stake distribution
mithril_client mithril-stake-distribution download $MITHRIL_STAKE_DISTRIBUTION_ARTIFACT_HASH

# 7- List Cardano transaction snapshots
mithril_client cardano-transaction snapshot list

# 8- Show detailed information about a Cardano transaction snapshot
mithril_client cardano-transaction snapshot show $CARDANO_TRANSACTION_SNAPSHOT_HASH

# 9- Certify that the given list of transactions hashes are included in the Cardano transactions set
mithril_client cardano-transaction certify $TRANSACTION_HASH_1,$TRANSACTION_HASH_2

# 10- List Cardano stake distributions
mithril_client cardano-stake-distribution list

# 11 - Download and verify the given Cardano stake distribution from its hash or epoch
mithril_client cardano-stake-distribution download $UNIQUE_IDENTIFIER

Local image

Build a local Docker image:

Linux / Mac
Windows

make docker-build

pushd ..\; docker build -t mithril/mithril-client -f mithril-client-cli\Dockerfile . ; popd

Run a local Docker container:

Linux / Mac
Windows

make docker-run

docker run --rm --name='mithril-client' mithril/mithril-client

Subcommands

Here are the subcommands available:

Cardano DB

Subcommand	Performed action
download	Downloads and restores a cardano-db snapshot
help	Prints this message or the help for the given subcommand(s)
snapshot list	Lists available cardano-db snapshots
snapshot show	Shows information about a cardano-db snapshot

Mithril stake distribution

Subcommand	Performed action
download	Downloads and verifies Mithril stake distribution
help	Prints this message or the help for the given subcommand(s)
list	Lists available Mithril stake distributions

Cardano transactions

Subcommand	Performed action
certify	Certifies that given list of transactions hashes are included in the Cardano transactions set
snapshot list	Lists available Cardano transactions snapshots
snapshot show	Shows information about a Cardano transactions snapshot
help	Prints this message or the help for the given subcommand(s)

Cardano stake distribution

Subcommand	Performed action
download	Downloads and verifies Cardano stake distribution
help	Prints this message or the help for the given subcommand(s)
list	Lists available Cardano stake distributions

Cardano DB V2 (Deprecated, use `cardano-db` with option `--backend v2` instead)

Subcommand	Performed action
download	Downloads and restores a cardano-db v2 snapshot
help	Prints this message or the help for the given subcommand(s)
snapshot list	Lists available cardano-db v2 snapshots
snapshot show	Shows information about a cardano-db v2 snapshot

Tools (`unstable`)

Subcommand	Performed action
utxo-hd	UTxO-HD related commands (e.g., converting a ledger state snapshot to another flavor)
help	Prints this message or the help for the given subcommand(s)

Configuration parameters

The configuration parameters can be set in either of the following ways:

In a configuration file, depending on the --run-mode parameter. If the runtime mode is testnet, the file is located in ./conf/testnet.json.
The value can be overridden by an environment variable with the parameter name in uppercase.

Here is a list of the available parameters:

Parameter	Command line (long)	Command line (short)	Environment variable	Description	Default value	Example	Mandatory
`verbose`	`--verbose`	`-v`	-	Verbosity level	-	Parsed from the number of occurrences: `-v` for `Warning`, `-vv` for `Info`, `-vvv` for `Debug` and `-vvvv` for `Trace`	✔️
`unstable`	`--unstable`	-	-	Enable unstable commands	`false`	-	-
`run_mode`	`--run-mode`	-	`RUN_MODE`	Run Mode	`dev`	-	✔️
`aggregator_endpoint`	`--aggregator-endpoint`	-	`AGGREGATOR_ENDPOINT`	Override configuration Aggregator endpoint URL	-	`https://aggregator.pre-release-preview.api.mithril.network/aggregator`	✔️
`log_format_json`	`--log-format-json`	-	-	Enable JSON output for logs displayed according to verbosity level	`false`	-	-
`log_output`	`--log-output`	-	-	Redirect the logs to a file	-	-	-
`origin_tag`	`--origin-tag`	-	-	Request origin tag	-	-	-
`version`	`--version`	`-V`	-	Print version	-	`./mithril-client.log`	-

cardano-db snapshot show command:

Parameter	Command line (long)	Command line (short)	Environment variable	Description	Default value	Example	Mandatory
`json`	`--json`	-	-	Enable JSON output for command results	`false`	-	-
`backend`	`--backend`	`-b`	-	Backend to use, either: `v1` (default, full database restoration only) or `v2` (unstable, full or partial database restoration)	`v1`	-	-
`digest`	-	-	-	Digest of the Cardano db snapshot to show or `latest` for the latest artifact	-	-	✔️

cardano-db snapshot list command:

Parameter	Command line (long)	Command line (short)	Environment variable	Description	Default value	Example	Mandatory
`json`	`--json`	-	-	Enable JSON output for command results	`false`	-	-
`backend`	`--backend`	`-b`	-	Backend to use, either: `v1` (default, full database restoration only) or `v2` (unstable, full or partial database restoration)	`v1`	-	-

cardano-db download command:

Parameter	Command line (long)	Command line (short)	Environment variable	Description	Default value	Example	Mandatory
`json`	`--json`	-	-	Enable JSON output for command results	`false`	-	-
`backend`	`--backend`	`-b`	-	Backend to use, either: `v1` (default, full database restoration only) or `v2` (unstable, full or partial database restoration)	`v1`	-	-
`digest`	-	-	-	Digest of the Cardano db snapshot to download or `latest` for the latest artifact	-	-	✔️
`download_dir`	`--download-dir`	-	-	Directory where the immutable and ancillary files will be downloaded	-	-	-
`genesis_verification_key`	`--genesis-verification-key`	-	`GENESIS_VERIFICATION_KEY`	Genesis verification key to check the certificate chain	-	-	✔️
`include_ancillary`	`--include-ancillary`	-	-	Include ancillary files in the download, if set the `ancillary_verification_key` is required in order to verify the ancillary files	`false`	-	-
`ancillary_verification_key`	`--ancillary-verification-key`	-	`ANCILLARY_VERIFICATION_KEY`	Ancillary verification key to verify the ancillary files	-	-	-
`start`	`--start`	-	-	[backend `v2` only] The first immutable file number to download	-	-	-
`end`	`--end`	-	-	[backend `v2` only] The last immutable file number to download	-	-	-
`allow_override`	`--allow-override`	-	-	[backend `v2` only] Allow existing files in the download directory to be overridden	`false`	-	-

mithril-stake-distribution list command:

Parameter	Command line (long)	Command line (short)	Environment variable	Description	Default value	Example	Mandatory
`json`	`--json`	-	-	Enable JSON output for command results	`false`	-	-

mithril-stake-distribution download command:

Parameter	Command line (long)	Command line (short)	Environment variable	Description	Default value	Example	Mandatory
`json`	`--json`	-	-	Enable JSON output for command results	`false`	-	-
`artifact_hash`	-	-	-	Hash of the Mithril stake distribution artifact, or `latest` for the latest artifact	-	-	✔️
`download_dir`	`--download-dir`	-	-	Directory where the Mithril stake distribution will be downloaded	-	-	-
`genesis_verification_key`	`--genesis-verification-key`	-	`GENESIS_VERIFICATION_KEY`	Genesis verification key to check the certificate chain	-	-	✔️

cardano-transaction snapshot show command:

Parameter	Command line (long)	Command line (short)	Environment variable	Description	Default value	Example	Mandatory
`json`	`--json`	-	-	Enable JSON output for command results	`false`	-	-
`hash`	-	-	-	Hash of the Cardano transaction snapshot to show or `latest` for the latest artifact	-	-	✔️

cardano-transaction snapshot list command:

Parameter	Command line (long)	Command line (short)	Environment variable	Description	Default value	Example	Mandatory
`json`	`--json`	-	-	Enable JSON output for command results	`false`	-	-

cardano-transaction certify command:

Parameter	Command line (long)	Command line (short)	Environment variable	Description	Default value	Example	Mandatory
`json`	`--json`	-	-	Enable JSON output for command results	`false`	-	-
`genesis_verification_key`	`--genesis-verification-key`	-	`GENESIS_VERIFICATION_KEY`	Genesis verification key to check the certificate chain	-	-	✔️
`transactions_hashes`	-	-	-	Hashes of the transactions to certify	-	-	✔️

cardano-stake-distribution list command:

Parameter	Command line (long)	Command line (short)	Environment variable	Description	Default value	Example	Mandatory
`json`	`--json`	-	-	Enable JSON output for command results	`false`	-	-

cardano-stake-distribution download command:

Parameter	Command line (long)	Command line (short)	Environment variable	Description	Default value	Example	Mandatory
`json`	`--json`	-	-	Enable JSON output for command results	`false`	-	-
`unique_identifier`	-	-	-	Hash or Epoch of the Cardano stake distribution artifact, or `latest` for the latest artifact	-	-	✔️
`download_dir`	`--download-dir`	-	-	Directory where the Cardano stake distribution will be downloaded	-	-	-
`genesis_verification_key`	`--genesis-verification-key`	-	`GENESIS_VERIFICATION_KEY`	Genesis verification key to check the certificate chain	-	-	✔️

cardano-db-v2 snapshot show command:

warning

Deprecated, use cardano-db snapshot show with option --backend v2 instead

Parameter	Command line (long)	Command line (short)	Environment variable	Description	Default value	Example	Mandatory
`json`	`--json`	-	-	Enable JSON output for command results	`false`	-	-
`hash`	-	-	-	Hash of the Cardano db snapshot to show or `latest` for the latest artifact	-	-	✔️

cardano-db-v2 snapshot list command:

warning

Deprecated, use cardano-db snapshot list with option --backend v2 instead

Parameter	Command line (long)	Command line (short)	Environment variable	Description	Default value	Example	Mandatory
`json`	`--json`	-	-	Enable JSON output for command results	`false`	-	-

cardano-db-v2 download command:

warning

Deprecated, use cardano-db download with option --backend v2 instead

Parameter	Command line (long)	Command line (short)	Environment variable	Description	Default value	Example	Mandatory
`json`	`--json`	-	-	Enable JSON output for command results	`false`	-	-
`hash`	-	-	-	Hash of the Cardano db snapshot to download or `latest` for the latest artifact	-	-	✔️
`download_dir`	`--download-dir`	-	-	Directory where the immutable and ancillary files will be downloaded	-	-	-
`genesis_verification_key`	`--genesis-verification-key`	-	`GENESIS_VERIFICATION_KEY`	Genesis verification key to check the certificate chain	-	-	✔️
`start`	`--start`	-	-	The first immutable file number to download	-	-	-
`end`	`--end`	-	-	The last immutable file number to download	-	-	-
`include_ancillary`	`--include-ancillary`	-	-	Include ancillary files in the download, if set the `ancillary_verification_key` is required in order to verify the ancillary files	`false`	-	-
`ancillary_verification_key`	`--ancillary-verification-key`	-	`ANCILLARY_VERIFICATION_KEY`	Ancillary verification key to verify the ancillary files	-	-	-
`allow_override`	`--allow-override`	-	-	Allow existing files in the download directory to be overridden	`false`	-	-

tools utxo-hd snapshot-converter command:

Parameter	Command line (long)	Command line (short)	Environment variable	Description	Default value	Example	Mandatory
`db_directory`	`--db-directory`	-	-	Path to the Cardano node database directory	-	-	✔️
`cardano_node_version`	`--cardano-node-version`	-	-	Cardano node version of the Mithril signed snapshot (`latest` and `pre-release` are also supported to download the latest or pre-release distribution.)	-	`10.4.1`	✔️
`cardano_network`	`--cardano-network`	-	-	Cardano network	-	-	✔️
`utxo_hd_flavor`	`--utxo-hd-flavor`	-	-	UTxO-HD flavor to convert the ledger snapshot to (`Legacy` or `LMDB`)	-	`LMDB`	✔️
`commit`	`--commit`	-	-	Replaces the current ledger state in the `db_directory`	`false`	-	-
`github_token`	`--github-token`	-	`GITHUB_TOKEN`	GitHub token for authenticated API calls	-	-	-

Resources​

Prerequisites​

Download the source file​

Development testing and building​

Building for release and running the binary​

Download the pre-built binary​

Run a Docker container​

Registry image​

Local image​

Subcommands​

Cardano DB​

Mithril stake distribution​

Cardano transactions​

Cardano stake distribution​

Cardano DB V2 (Deprecated, use cardano-db with option --backend v2 instead)​

Tools (unstable)​

Configuration parameters​

Resources

Prerequisites

Download the source file

Development testing and building

Building for release and running the binary

Download the pre-built binary

Run a Docker container

Registry image

Local image

Subcommands

Cardano DB

Mithril stake distribution

Cardano transactions

Cardano stake distribution

Cardano DB V2 (Deprecated, use `cardano-db` with option `--backend v2` instead)

Tools (`unstable`)

Configuration parameters