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
Mithril networks

Here is an updated list of all Mithril networks, including their configurations and current statuses:

Last update: 07/21/2023

release-mainnet​

Information-
Mithril networkrelease-mainnet
Cardano networkmainnet
Cardano magic Id-
SupportedYes βœ”οΈ
StatusBeta 🟒
Aggregator endpointhttps://aggregator.release-mainnet.api.mithril.network/aggregator ↗️
Genesis verification keyhttps://raw.githubusercontent.com/input-output-hk/mithril/main/mithril-infra/configuration/release-mainnet/genesis.vkey ↗️
Era reader adapter typecardano-chain
Era reader addresshttps://raw.githubusercontent.com/input-output-hk/mithril/main/mithril-infra/configuration/release-mainnet/era.addr ↗️
Era reader verification keyhttps://raw.githubusercontent.com/input-output-hk/mithril/main/mithril-infra/configuration/release-mainnet/era.vkey ↗️
Build fromLatest release ↗️
caution

In this documentation, we use the following generic identifiers:

  • YOUR_CARDANO_NETWORK You need to replace this with the name of the network that runs on your Cardano node (eg, preprod)
  • YOUR_AGGREGATOR_ENDPOINT You need to replace this with the endpoint of an aggregator that runs on the Cardano network you are targeting (eg, https://aggregator.release-preprod.api.mithril.network/aggregator)
  • YOUR_GENESIS_VERIFICATION_KEY You need to replace this with the genesis verification key URL that runs on the Cardano network you are targeting (eg, https://raw.githubusercontent.com/input-output-hk/mithril/main/mithril-infra/configuration/release-preprod/genesis.vkey)
  • YOUR_ERA_READER_ADAPTER_TYPE You need to replace this with the era reader adapter type used by the Mithril network you are targeting (eg, cardano-chain)
  • YOUR_ERA_READER_ADDRESS You need to replace this with the era reader address URL used by the Mithril network you are targeting (eg, https://raw.githubusercontent.com/input-output-hk/mithril/main/address.addr)
  • YOUR_ERA_READER_VERIFICATION_KEY You need to replace this with the era reader verification key URL used by the Mithril network you are targeting (eg, https://raw.githubusercontent.com/input-output-hk/mithril/main/TEST_ONLY_era.vkey)

Resources​

NodeSource repositoryRust documentationDocker packages
Mithril client CLI↗️↗️↗️

Pre-requisites​

  • Install the latest stable version of the correctly configured Rust toolchain.

  • 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 **Build from** column of the **Mithril networks** table above
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:
snapshot Deprecated, use `cardano-db` instead
cardano-db Cardano db management (alias: cdb)
mithril-stake-distribution Mithril Stake Distribution management (alias: msd)
cardano-transaction [unstable] Cardano transactions management (alias: ctx)
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 (such as Cardano Transactions)
-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**) NETWORK=**YOUR_CARDANO_NETWORK** 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 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​

Each Release / Pre-Release distribution comes with pre compiled binaries ready to use or wrapped in a debian package for linuxΒΉ.

You can download them from the Release / Pre-Release distribution page that depends on the Mithril Network you are targeting.

These links are available in the Build From column of the above Mithril Networks table.

ΒΉ 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 above Mithril networks table.

export MITHRIL_IMAGE_ID=**YOUR_MITHRIL_IMAGE_ID**
export NETWORK=**YOUR_CARDANO_NETWORK**
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 NETWORK=preprod
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 NETWORK=$NETWORK -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 --unstable cardano-transaction snapshot list

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

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

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 (previously: Snapshot)​

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

Snapshot​

warning

The snapshot commands are now deprecated and has been superseded by the cardano-db commands. The snapshot commands will be removed in the near future.

SubcommandPerformed action
downloadDownloads and restores a cardano-db snapshot
helpPrints this message or the help for the given subcommand(s)
listLists available cardano-db snapshots
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)

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-βœ”οΈ
network--NETWORKCardano network-testnet or mainnet or devnetβœ”οΈ
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 or 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 or snapshot list command:

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

cardano-db download or snapshot 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---