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.
The Mithril network configurations are available in the Network configurations section of the user manual.
Resources
Node | Source repository | Rust documentation | Docker packages | Network configurations |
---|---|---|---|---|
Mithril client CLI | ↗️ | ↗️ | ↗️ | ↗️ |
Prerequisites
-
Install the latest stable version of the correctly configured Rust toolchain
-
Install build tools
build-essential
andm4
; for example, on Ubuntu/Debian/Mint, runsudo 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
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
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 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
Subcommand | Performed action |
---|---|
download | Downloads and restores a cardano-db snapshot |
help | Prints this message or the help for the given subcommand(s) |
snapshot list | Lists available cardano-db snapshots |
snapshot show | Shows information about a cardano-db 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 |
Cardano transactions
Subcommand | Performed action |
---|---|
certify | Certifies that given list of transactions hashes are included in the Cardano transactions set |
snapshot list | Lists available Cardano transactions snapshots |
snapshot show | Shows information about a Cardano transactions snapshot |
help | Prints this message or the help for the given subcommand(s) |
Cardano stake distribution
Subcommand | Performed action |
---|---|
download | Downloads and verifies Cardano stake distribution |
help | Prints this message or the help for the given subcommand(s) |
list | Lists available Cardano 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 | ✔️ |
unstable | --unstable | - | - | Enable unstable commands | - | - | - |
run_mode | --run-mode | - | RUN_MODE | Runtime mode | dev | - | ✔️ |
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 | - | - | ✔️ |
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:
Parameter | Command line (long) | Command line (short) | Environment variable | Description | Default value | Example | Mandatory |
---|---|---|---|---|---|---|---|
digest | --digest | - | DIGEST | Cardano DB digest or latest for the latest digest | - | - | ✔️ |
json | --json | - | - | Enable JSON output for command results | - | - | - |
cardano-db snapshot list
command:
Parameter | Command line (long) | Command line (short) | Environment variable | Description | Default value | Example | Mandatory |
---|---|---|---|---|---|---|---|
json | --json | - | - | Enable JSON output for command results | - | - | - |
cardano-db download
command:
Parameter | Command line (long) | Command line (short) | Environment variable | Description | Default value | Example | Mandatory |
---|---|---|---|---|---|---|---|
digest | --digest | - | DIGEST | Cardano 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:
Parameter | Command line (long) | Command line (short) | Environment variable | Description | Default value | Example | Mandatory |
---|---|---|---|---|---|---|---|
json | --json | - | - | Enable JSON output for command results | - | - | - |
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 | . | - | - |
cardano-transaction snapshot show
command:
Parameter | Command line (long) | Command line (short) | Environment variable | Description | Default value | Example | Mandatory |
---|---|---|---|---|---|---|---|
hash | --hash | - | HASH | Cardano transaction snapshot hash or latest for the latest Cardano transaction snapshot | - | - | ✔️ |
json | --json | - | - | Enable JSON output for command results | - | - | - |
cardano-transaction snapshot list
command:
Parameter | Command line (long) | Command line (short) | Environment variable | Description | Default value | Example | Mandatory |
---|---|---|---|---|---|---|---|
json | --json | - | - | Enable JSON output for command results | - | - | - |
cardano-transaction certify
command:
Parameter | Command line (long) | Command line (short) | Environment variable | Description | Default value | Example | Mandatory |
---|---|---|---|---|---|---|---|
transactions_hashes | --transactions_hashes | - | TRANSACTIONS_HASHES | Cardano transactions hashes separated by commas | - | - | ✔️ |
json | --json | - | - | Enable JSON output for progress logs | - | - | - |
cardano-stake-distribution list
command:
Parameter | Command line (long) | Command line (short) | Environment variable | Description | Default value | Example | Mandatory |
---|---|---|---|---|---|---|---|
json | --json | - | - | Enable JSON output for command results | - | - | - |
cardano-stake-distribution download
command:
Parameter | Command line (long) | Command line (short) | Environment variable | Description | Default value | Example | Mandatory |
---|---|---|---|---|---|---|---|
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 | . | - | - |