Mithril client node
Mithril client is responsible for restoring the Cardano blockchain on an empty node from a certified snapshot.
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.
Here is an updated list of all Mithril networks, including their configurations and current statuses:
Last update: 07/21/2023
- Mainnet
- Preprod
- Preview
release-mainnet
β
Information | - |
---|---|
Mithril network | release-mainnet |
Cardano network | mainnet |
Cardano magic id | - |
Supported | Yes βοΈ |
Status | Beta π’ |
Aggregator endpoint | https://aggregator.release-mainnet.api.mithril.network/aggregator βοΈ |
Genesis verification key | https://raw.githubusercontent.com/input-output-hk/mithril/main/mithril-infra/configuration/release-mainnet/genesis.vkey βοΈ |
Era reader adapter type | cardano-chain |
Era reader address | https://raw.githubusercontent.com/input-output-hk/mithril/main/mithril-infra/configuration/release-mainnet/era.addr βοΈ |
Era reader verification key | https://raw.githubusercontent.com/input-output-hk/mithril/main/mithril-infra/configuration/release-mainnet/era.vkey βοΈ |
Build from | Latest release βοΈ |
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 βοΈ |
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 βοΈ |
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β
Node | Source repository | Rust documentation | Docker 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
To display results in JSON format for the list
and show
commands, simply use the --json
(or -j
) option:
./mithril-client snapshot list --json
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β
Subcommand | Performed action |
---|---|
download | Downloads and restores a snapshot |
help | Prints this message or the help for the given subcommand(s) |
list | Lists available snapshots |
show | Shows information about a 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 |
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 istestnet
, 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 | VERBOSE | Verbosity 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_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 | - | - |
snapshot show
command:
Parameter | Command line (long) | Command line (short) | Environment variable | Description | Default value | Example | Mandatory |
---|---|---|---|---|---|---|---|
digest | --digest | - | DIGEST | Snapshot digest or latest for the latest digest | - | - | βοΈ |
snapshot download
command:
Parameter | Command line (long) | Command line (short) | Environment variable | Description | Default value | Example | Mandatory |
---|---|---|---|---|---|---|---|
digest | --digest | - | DIGEST | Snapshot digest or latest for the latest digest | - | - | βοΈ |
download_dir | --download-dir | - | - | Directory where the snapshot will be downloaded | . | - | - |
mithril-stake-distribution download
command:
Parameter | Command line (long) | Command line (short) | Environment variable | Description | Default value | Example | Mandatory |
---|---|---|---|---|---|---|---|
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 | . | - | - |