Skip to main content
Version: Next 🚧

Mithril client node

info

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

tip
info

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

Resources​

NodeSource repositoryRust documentationDocker packagesNetwork configurations
Mithril client CLI↗️↗️↗️↗️

Prerequisites​

  • 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:

cd mithril/mithril-client-cli

Development testing and building​

Run tests:

make test

Create the help menu:

make help

Generate the Rust documentation:

make doc

Run in debug mode with the default configuration:

make debug

Release the build and run the binary​

Build and run in release mode with the default configuration:

make run

Or, build only in release mode:

make build

Display the help menu:

./mithril-client-cli --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)
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)
--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
-h, --help
Print help
-V, --version
Print version

Run in release mode with the default configuration:

./mithril-client-cli

Run in release mode with a specific mode:

./mithril-client-cli --run-mode preview

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

GENESIS_VERIFICATION_KEY=$(wget -q -O - **YOUR_GENESIS_VERIFICATION_KEY**) 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:

./mithril-client-cli 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​

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.31 (compatible with Ubuntu 20.04 or Debian Bullseye).

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.

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

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

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

Proceed by creating a shell function for the Mithril client:

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 $@
}

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 $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:

make docker-build

Run a local Docker container:

make docker-run

Subcommands​

Here are the subcommands available:

Cardano DB​

SubcommandPerformed action
downloadDownloads and restores a cardano-db snapshot
helpPrints this message or the help for the given subcommand(s)
snapshot listLists available cardano-db snapshots
snapshot showShows information about a cardano-db snapshot

Mithril stake distribution​

SubcommandPerformed action
downloadDownloads and verifies Mithril stake distribution
helpPrints this message or the help for the given subcommand(s)
listLists available Mithril stake distributions

Cardano transactions​

SubcommandPerformed action
certifyCertifies that given list of transactions hashes are included in the Cardano transactions set
snapshot listLists available Cardano transactions snapshots
snapshot showShows information about a Cardano transactions snapshot
helpPrints this message or the help for the given subcommand(s)

Cardano stake distribution​

SubcommandPerformed action
downloadDownloads and verifies Cardano stake distribution
helpPrints this message or the help for the given subcommand(s)
listLists available Cardano stake distributions

Configuration parameters​

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

  1. In a configuration file, depending on the --run-mode parameter. If the runtime mode is testnet, the file is located in ./conf/testnet.json.

  2. The value can be overridden by an environment variable with the parameter name in uppercase.

Here is a list of the available parameters:

ParameterCommand line (long)Command line (short)Environment variableDescriptionDefault valueExampleMandatory
verbose--verbose-vVERBOSEVerbosity 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---
run_mode--run-mode-RUN_MODERuntime modedev-βœ”οΈ
aggregator_endpoint--aggregator-endpoint-AGGREGATOR_ENDPOINTAggregator node endpoint-https://aggregator.pre-release-preview.api.mithril.network/aggregatorβœ”οΈ
genesis_verification_key--GENESIS_VERIFICATION_KEYGenesis verification key--βœ”οΈ
log_format_json--log-format-json--Enable JSON output for logs---
log_output--log-output-o-Redirect the logs to a file-./mithril-client.log-

cardano-db snapshot show command:

ParameterCommand line (long)Command line (short)Environment variableDescriptionDefault valueExampleMandatory
digest--digest-DIGESTCardano DB digest or latest for the latest digest--βœ”οΈ
json--json--Enable JSON output for command results---

cardano-db snapshot list command:

ParameterCommand line (long)Command line (short)Environment variableDescriptionDefault valueExampleMandatory
json--json--Enable JSON output for command results---

cardano-db download command:

ParameterCommand line (long)Command line (short)Environment variableDescriptionDefault valueExampleMandatory
digest--digest-DIGESTCardano DB digest or latest for the latest digest--βœ”οΈ
download_dir--download-dir--Directory where the Cardano DB will be downloaded.--
json--json--Enable JSON output for progress logs---

mithril-stake-distribution list command:

ParameterCommand line (long)Command line (short)Environment variableDescriptionDefault valueExampleMandatory
json--json--Enable JSON output for command results---

mithril-stake-distribution download command:

ParameterCommand line (long)Command line (short)Environment variableDescriptionDefault valueExampleMandatory
artifact_hash--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.--

cardano-transaction snapshot show command:

ParameterCommand line (long)Command line (short)Environment variableDescriptionDefault valueExampleMandatory
hash--hash-HASHCardano transaction snapshot hash or latest for the latest Cardano transaction snapshot--βœ”οΈ
json--json--Enable JSON output for command results---

cardano-transaction snapshot list command:

ParameterCommand line (long)Command line (short)Environment variableDescriptionDefault valueExampleMandatory
json--json--Enable JSON output for command results---

cardano-transaction certify command:

ParameterCommand line (long)Command line (short)Environment variableDescriptionDefault valueExampleMandatory
transactions_hashes--transactions_hashes-TRANSACTIONS_HASHESCardano transactions hashes separated by commas--βœ”οΈ
json--json--Enable JSON output for progress logs---

cardano-stake-distribution list command:

ParameterCommand line (long)Command line (short)Environment variableDescriptionDefault valueExampleMandatory
json--json--Enable JSON output for command results---

cardano-stake-distribution download command:

ParameterCommand line (long)Command line (short)Environment variableDescriptionDefault valueExampleMandatory
unique_identifier--unique-identifier--Epoch or hash 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.--