Version: Next 🚧

Mithril Client Node

info

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

tip

For more information about the Mithril Network, please refer to the Architecture page.
For more information about the Mithril Client, please refer to the Client Node page.
Checkout the Bootstrap a Cardano Node guide.

Mithril Networks

Here is an up to date list of all the Mithril Networks, their configurations and their status:

Last update: 02/28/2023

Preview
Preprod
Mainnet

`pre-release-preview`

Information	-
Mithril Network	`pre-release-preview` 🔎
Cardano Network	`preview`
Cardano Magic Id	`2`
Supported	Yes ✔️
Status	Pre-Release 🟠
Aggregator Endpoint	`https://aggregator.pre-release-preview.api.mithril.network/aggregator` ↗️
Genesis Verification Key	`https://raw.githubusercontent.com/input-output-hk/mithril/main/mithril-infra/configuration/pre-release-preview/genesis.vkey` ↗️
Era Reader Adapter Type	`cardano-chain`
Era Reader Address	`https://raw.githubusercontent.com/input-output-hk/mithril/main/mithril-infra/configuration/pre-release-preview/era.addr` ↗️
Era Reader Verification Key	`https://raw.githubusercontent.com/input-output-hk/mithril/main/mithril-infra/configuration/pre-release-preview/era.vkey` ↗️
Build From	Latest Pre-Release ↗️

`testing-preview`

⚠️ For devs only

Information	-
Mithril Network	`testing-preview` 🔎
Cardano Network	`preview`
Cardano Magic Id	`2`
Supported	Yes ✔️
Status	Unstable 🔴
Aggregator Endpoint	`https://aggregator.testing-preview.api.mithril.network/aggregator` ↗️
Genesis Verification Key	`https://raw.githubusercontent.com/input-output-hk/mithril/main/mithril-infra/configuration/testing-preview/genesis.vkey` ↗️
Era Reader Adapter Type	`cardano-chain`
Era Reader Address	`https://raw.githubusercontent.com/input-output-hk/mithril/main/mithril-infra/configuration/testing-preview/era.addr` ↗️
Era Reader Verification Key	`https://raw.githubusercontent.com/input-output-hk/mithril/main/mithril-infra/configuration/testing-preview/era.vkey` ↗️
Build From	Main Branch ↗️

`release-preprod`

Information	-
Mithril Network	`release-preprod` 🔎
Cardano Network	`preprod`
Cardano Magic Id	`1`
Supported	Yes ✔️
Status	Release 🟢
Aggregator Endpoint	`https://aggregator.release-preprod.api.mithril.network/aggregator` ↗️
Genesis Verification Key	`https://raw.githubusercontent.com/input-output-hk/mithril/main/mithril-infra/configuration/release-preprod/genesis.vkey` ↗️
Era Reader Adapter Type	`cardano-chain`
Era Reader Address	`https://raw.githubusercontent.com/input-output-hk/mithril/main/mithril-infra/configuration/release-preprod/era.addr` ↗️
Era Reader Verification Key	`https://raw.githubusercontent.com/input-output-hk/mithril/main/mithril-infra/configuration/release-preprod/era.vkey` ↗️
Build From	Latest Release ↗️

`release-mainnet`

Information	-
Mithril Network	`release-mainnet`
Cardano Network	`mainnet`
Cardano Magic Id	`-`
Supported	No ❌
Status	-
Aggregator Endpoint	-
Genesis Verification Key	-
Era Reader Adapter Type	-
Era Reader Address	-
Era Reader Verification Key	-
Build From	-

caution

In this documentation, we use the generic:

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

Resources

Node	Source Repository	Rust Documentation	Docker Packages
Mithril Client	↗️	↗️	↗️

Pre-requisites

Install a correctly configured Rust toolchain (latest stable version)
Install OpenSSL development libraries, for example on Ubuntu/Debian/Mint run apt install libssl-dev

Download source

Download 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 build branch / tag

# **YOUR_BUILD_BRANCH_OR_TAG** depends on the Mithril network you target, 
# please refer to the **Build From** column of the above **Mithril Networks** table
git switch **YOUR_BUILD_BRANCH_OR_TAG**

Change directory

cd mithril/mithril-client

Development test and build

Run tests

make test

Create the help menu

make help

Generate the Rust documentation

make doc

Run in debug mode with default configuration

make debug

Release build and run binary

Build and run in release with default configuration

make run

Or, build only in release

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
  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
  -h, --help
          Print help
  -V, --version
          Print version

Run in release with default configuration

./mithril-client

Run in release with a specific mode

./mithril-client --run-mode preview

Run in release with a custom configuration via env vars

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

tip

You can use the --json (or -j) option in order to display results in JSON format for the list and show commands:

./mithril-client list --json

tip

If you want to dig deeper, you can get access to several level of logs from the Mithril Client:

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 compiled binary

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

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.

Run Docker container

Registry Image

The list of available images on the registry is listed here

Prepare environment variables (values can be retrieved on 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=$(curl -sL $AGGREGATOR_ENDPOINT/artifact/snapshots | jq -r '.[0].digest')

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=$(curl -sL $AGGREGATOR_ENDPOINT/artifact/snapshots | jq -r '.[0].digest')

Then create 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 function:

# 1- Help
mithril_client help

# 2- List snapshots
mithril_client list

# 3- Download latest snapshot
mithril_client download $SNAPSHOT_DIGEST

# 4- Restore latest snapshot
mithril_client restore $SNAPSHOT_DIGEST

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

Subcommand	Performed action
download	Download and restore a snapshot
help	Print this message or the help of the given subcommand(s)
list	List available snapshots
show	Informations about a snapshot

Configuration parameters

The configuration parameters are set either:

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

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`	`VERBOSE`	Verbosity level	-	Parsed from number of occurrences: `-v` for `Warning`, `-vv` for `Info`, `-vvv` for `Debug` and `-vvvv` for `Trace`	✔️
`run_mode`	`--run-mode`	-	`RUN_MODE`	Runtime mode	`dev`	-	✔️
`network`	-	-	`NETWORK`	Cardano network	-	`testnet` or `mainnet` or `devnet`	✔️
`aggregator_endpoint`	`--aggregator-endpoint`	-	`AGGREGATOR_ENDPOINT`	Aggregator node endpoint	-	`https://aggregator.pre-release-preview.api.mithril.network/aggregator`	✔️
`genesis_verification_key`	-	-	`GENESIS_VERIFICATION_KEY`	Genesis verification key	-	-	✔️
`json_output`	`--json`	`-j`	-	Enable JSON output	no	-	-

Mithril Client Node

pre-release-preview​

testing-preview​

release-preprod​

release-mainnet​

Resources​

Pre-requisites​

Download source​

Development test and build​

Release build and run binary​

Download compiled binary​

Run Docker container​

Registry Image​

Local Image​

Subcommands​

snapshot​

Configuration parameters​