Skip to main content
Version: Current

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↗️↗️↗️

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

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 --help

You should see:

This program shows, downloads, and verifies certified blockchain artifacts.

Usage: mithril-client [OPTIONS] <COMMAND>

Commands:
  snapshot                    Snapshot commands
  mithril-stake-distribution  Mithril stake distribution management (alias: msd)
  help                        Print this message or the help for 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
  -h, --help
          Print help
  -V, --version
          Print version


Run in release mode with the default configuration:

./mithril-client

Run in release mode with a specific mode:

./mithril-client --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 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 snapshots
mithril_client snapshot list

# 3- Show detailed information about a snapshot
mithril_client snapshot show $SNAPSHOT_DIGEST

# 4- Download the given snapshot and verify the certificate
mithril_client snapshot download $SNAPSHOT_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

Local image​

Build a local Docker image:

make docker-build

Run a local Docker container:

make docker-run

Subcommands​

Here are the subcommands available:

Snapshot​

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

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✔️
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--✔️
json_output--json-j-Enable JSON outputno--

snapshot show command:

ParameterCommand line (long)Command line (short)Environment variableDescriptionDefault valueExampleMandatory
digest--digest-DIGESTSnapshot digest or latest for the latest digest--✔️

snapshot download command:

ParameterCommand line (long)Command line (short)Environment variableDescriptionDefault valueExampleMandatory
digest--digest-DIGESTSnapshot digest or latest for the latest digest--✔️
download_dir--download-dir--Directory where the snapshot will be downloaded.--

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.--