Run a Mithril signer node
For more information about the Mithril protocol, see the About Mithril section.
Mithril signer deployment modelβ
In this guide, you will learn how to set up a Mithril signer within the stake pool operator (SPO) infrastructure both on Cardano mainnet
and testnet
environments:
- On
mainnet
, you must run the production deployment where the Mithril signer runs on the Cardano block producer machine and the Mithril relay runs on the Cardano relay machine. Note that you can run the production deployment ontestnet
. - You can also run naive deployment, where the Mithril signer runs on the Cardano relay machine. This is possible in the testnet environment only, and does not require setting up a Mithril relay.
In the current setup, you don't need to install a Mithril aggregator.
The production deployment model is currently in the beta version.
Here is the schema of the production deployment on mainnet:
and the schema of the naive deployment specifically for testnets
:
On mainnet
, you must never copy the KES secret key
from the Cardano block producer machine!
Mithril keys certificationβ
The Mithril signer uses your Cardano operational certificate
and KES secret key
files which enable:
- Automatic computation of the
PoolId
- Verification of your
PoolId
ownership and the associated stake used by the Mithril protocol - Verification of your Mithril
signer secret key
ownership, which allows you to participate in the multi-signature process for certificate production on the Mithril network.
Mithril signer footprintβ
The Mithril signer has been designed to have the lowest footprint possible in terms of CPU, memory, disk i/o and storage. Thus, there are no extra requirements on the recommended hardware for running a Cardano stake pool, as detailed in this guide.
Here are some figures about the Mithril signer node running on Cardano mainnet
:
- It is idle most of the time with a very low CPU usage of less than
5%
- It uses less than
200 MB
of resident memory - It sends a new signature to the aggregator roughly every
10 minutes
and a new registration every5 days
(<1 MB
per day) When launched for the first time, a pre-loading phase occurs, during which the Cardano transactions are imported with a spike of50-70%
CPU on one core for~5 hours
- When signing for the first time, the Cardano database digest cache needs to be built with a spike of
50-70%
CPU on one core for~1 hour
- Also, the full Cardano database files will be read from disk once during this cache building process
- Only stake distributions, Mithril keys, and some cache (for the Cardano database and Cardano transactions) are stored on the disk (
<200 MB
).
Cardano transactions certification footprintβ
Here is a detailed view of the impact of the signature of the Cardano transactions (the most resource-intensive part of Mithril) on the SPO infrastructure on the mainnet
:
CPUβ
Memoryβ
Diskβ
Prerequisitesβ
Note that this guide works on a Linux machine only.
-
To operate a Cardano node as a stake pool, you need:
- The pool's
operational certificate
- The pool's
KES secret key
- The pool's
-
To access the file system of the Cardano block producer node for production deployment (or of the Cardano relay node for naive deployment), you will need the following permissions:
- Read rights on the
Database
folder (specified by the--database-path
setting of the Cardano node) - Read and write rights on the
Inter Process Communication
file (typically defined by theCARDANO_NODE_SOCKET_PATH
environment variable used to launch the Cardano node)
- Read rights on the
-
Install a recent version of
cardano-cli
(version 8.9.1+) -
Install a correctly configured Rust toolchain (latest stable version); you can follow the instructions provided here
-
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
-
Install a recent version of
jq
(version 1.6+) by runningapt install jq
-
Only for the production deployment, install a recent version of
squid-cache
(version 6.12+).
Set up the Mithril signer nodeβ
-
For production deployment, the Mithril signer setup is performed on the Cardano block producer machine
-
For naive deployment, the Mithril signer setup is performed on the Cardano relay machine.
Compare the version of your Cardano node with the minimum supported versions listed in the networks.json
file to verify its compatibility with the Mithril signer.
First, check the version of your Cardano node by running the following command:
cardano-node --version
Then, refer to the minimum supported versions listed in the the networks.json
file.
You can also fetch the minimum supported version for your network using the command below:
wget -q -O - https://raw.githubusercontent.com/input-output-hk/mithril/main/networks.json | jq -r '."**YOUR_CARDANO_NETWORK**"."cardano-minimum-version"."mithril-signer"'
Here is an example for preprod
:
wget -q -O - https://raw.githubusercontent.com/input-output-hk/mithril/main/networks.json | jq -r '."preprod"."cardano-minimum-version"."mithril-signer"'
Building your own executableβ
Download the source fileβ
To download the source from GitHub (HTTPS), run:
git clone https://github.com/input-output-hk/mithril.git
Or (SSH):
git clone git@github.com:input-output-hk/mithril.git
Build the Mithril signer binaryβ
First, switch to build a branch/tag:
# **YOUR_BUILD_BRANCH_OR_TAG** depends on the Mithril network you target,
# please refer to the **Build from** column of the **Mithril networks** section
git checkout **YOUR_BUILD_BRANCH_OR_TAG**
Then, change the directory:
cd mithril/mithril-signer
Run tests (optional):
make test
Finally, build the executable:
make build
Download the pre-built binaryβ
You can install a the latest released binary of the mithril-signer by running this one line command (replace YOUR_PATH with your installation path):
curl --proto '=https' --tlsv1.2 -sSf
https://raw.githubusercontent.com/input-output-hk/mithril/refs/heads/main/mithril-install.sh
| sh -s -- -c mithril-signer -d latest -p YOUR_PATH
You can also install the mithril-signer binary for other distributions:
- use
-d unstable
for the unstable version - use
-d **DISTRIBUTION_VERSION**
for a specific distribution (e.g.-d 2445.0
)
The Linux binaries target glibc
, and have a minimum requirement of glibc 2.35
(compatible with Ubuntu 22.04
or Debian 12 - Bookworm
).
Verifying the binaryβ
Verify the version of the binaryβ
You can check that the Mithril signer binary is running the correct version by running:
./mithril-signer -V
You should see something like:
mithril-signer 0.2.0
β οΈ Please verify that the displayed version matches the version described in the release/pre-release notes (refer to the Build from column in the Mithril networks section).
Verify the buildβ
Check that the Mithril signer binary is working correctly by running the help function:
./mithril-signer -h
You should see:
An implementation of a Mithril signer
Usage: mithril-signer [OPTIONS]
Options:
-r, --run-mode <RUN_MODE>
Run Mode [env: RUN_MODE=] [default: dev]
-v, --verbose...
Verbosity level, add more v to increase
-c, --configuration-dir <CONFIGURATION_DIR>
Directory where the configuration file is located [default: ./config]
--disable-digests-cache
Disable immutables digests cache
--reset-digests-cache
If set the existing immutables digests cache will be reset
-h, --help
Print help information (use `--help` for more detail)
-V, --version
Print version information
If you wish to delve deeper, you can access logs at various levels from the Mithril signer:
- 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).