Skip to main content
Version: Next 🚧

Run a Mithril Signer node (SPO)

info

In this guide, you will learn how to setup a Mithril Signer on top of a Cardano SPO Node for the testnet.

Mithril Networks

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

Last update: 02/28/2023

pre-release-preview​

Information-
Mithril Networkpre-release-preview 🔎
Cardano Networkpreview
Cardano Magic Id2
SupportedYes ✔️
StatusPre-Release 🟠
Aggregator Endpointhttps://aggregator.pre-release-preview.api.mithril.network/aggregator ↗️
Genesis Verification Keyhttps://raw.githubusercontent.com/input-output-hk/mithril/main/mithril-infra/configuration/pre-release-preview/genesis.vkey ↗️
Era Reader Adapter Typecardano-chain
Era Reader Addresshttps://raw.githubusercontent.com/input-output-hk/mithril/main/mithril-infra/configuration/pre-release-preview/era.addr ↗️
Era Reader Verification Keyhttps://raw.githubusercontent.com/input-output-hk/mithril/main/mithril-infra/configuration/pre-release-preview/era.vkey ↗️
Build FromLatest Pre-Release ↗️

testing-preview​

⚠️ For devs only

Information-
Mithril Networktesting-preview 🔎
Cardano Networkpreview
Cardano Magic Id2
SupportedYes ✔️
StatusUnstable 🔴
Aggregator Endpointhttps://aggregator.testing-preview.api.mithril.network/aggregator ↗️
Genesis Verification Keyhttps://raw.githubusercontent.com/input-output-hk/mithril/main/mithril-infra/configuration/testing-preview/genesis.vkey ↗️
Era Reader Adapter Typecardano-chain
Era Reader Addresshttps://raw.githubusercontent.com/input-output-hk/mithril/main/mithril-infra/configuration/testing-preview/era.addr ↗️
Era Reader Verification Keyhttps://raw.githubusercontent.com/input-output-hk/mithril/main/mithril-infra/configuration/testing-preview/era.vkey ↗️
Build FromMain Branch ↗️
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)
danger

This guide is working only on a Linux machine.

tip

For more information about the Mithril Protocol, please refer to the About Mithril section.

Pre-requisites​

What you'll need​

  • Operating a Cardano Node as a Stake Pool:

    • The Cardano Operational Certificate file of the pool
    • The Cardano KES Secret Key file of the pool

  • Access to the file system of a relay Cardano Node running on the testnet:

    • Read rights on the Database folder (--database-path setting of the Cardano Node)
    • Read/Write rights on the Inter Process Communication file (usually CARDANO_NODE_SOCKET_PATH env var used to launch the Cardano Node)

  • Install a recent version of the cardano-cli (version 8.0.0+)

  • Install a correctly configured Rust toolchain (latest stable version).

  • Install OpenSSL development libraries, for example on Ubuntu/Debian/Mint run apt install libssl-dev

  • Ensure the SQLite3 version is at least 3.35 (released Apr. 2021)

  • Install a recent version of jq (version 1.6+) apt install jq

Mithril Keys Certification​

Certify your Pool Id​

You must declare your Cardano Operational Certificate file and KES Secret Key file which allows to:

  • Compute automatically the PoolId
  • Verify that you are the owner of the PoolId, and thus of the associated stakes used by Mithril protocol
  • Verify that you are the owner of the Mithril Signer Secret Key, and thus allowed to contribute to the multi-signatures and certificate production of the Mithril network

Building your own executable​

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

Build Mithril Signer binary​

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

Run tests (Optional)

make test

Build executable

make build

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.

Verify binary​

Verify version​

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

⚠️ Verify that the version displayed is the version described in the content of the Release / Pre-Release note (see the Build From column of the above Mithril Networks table)

Verify build​

Check that the Mithril Signer binary is working fine by running its help

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

If you want to dig deeper, you can get access to several level of logs 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)

Install the service​

Move executable​

Move executable to /opt/mithril

sudo mkdir -p /opt/mithril
sudo mv mithril-signer /opt/mithril

Setup the service​

caution

  • User=cardano: Replace this value with the correct user. We assume that the user used to run the Cardano Node is cardano. The Mithril Signer must imperatively run with the same user.

  • In the /opt/mithril/mithril-signer/service.env env file:

    • KES_SECRET_KEY_PATH=/cardano/keys/kes.skey: replace /cardano/keys/kes.skey with the path to your Cardano KES Secret Key file
    • OPERATIONAL_CERTIFICATE_PATH=/cardano/cert/opcert.cert: replace /cardano/cert/opcert.cert with the path to your Cardano Operational Certificate file
    • DB_DIRECTORY=/cardano/db: replace /cardano/db with the path to the database folder of the Cardano Node (the one in --database-path)
    • CARDANO_NODE_SOCKET_PATH=/cardano/ipc/node.socket: replace with the path to the IPC file (CARDANO_NODE_SOCKET_PATH env var)
    • CARDANO_CLI_PATH=/app/bin/cardano-cli: replace with the path to the cardano-cli executable
    • DATA_STORES_DIRECTORY=/opt/mithril/stores: replace with the path to a folder where the Mithril Signer will store its data (/opt/mithril/stores e.g.)
    • STORE_RETENTION_LIMIT: if set, this will limit the number of records in some internal stores (5 is a good fit).
    • ERA_READER_ADAPTER_TYPE=cardano-chain: replace cardano-chain with the era reader adapter type used in your Mithril network
    • ERA_READER_ADAPTER_PARAMS={"address": "...", "verification_key": "..."}: replace {"address": "...", "verification_key": "..."} with the era reader params that you need to compute by running the command jq -nc --arg address $(wget -q -O - **YOUR_ERA_READER_ADDRESS**) --arg verification_key $(wget -q -O - **YOUR_ERA_READER_VERIFICATION_KEY**) '{"address": $address, "verification_key": $verification_key}'

First create an env file that will be used by the service:

sudo bash -c 'cat > /opt/mithril/mithril-signer.env << EOF
KES_SECRET_KEY_PATH=**YOUR_KES_SECRET_KEY_PATH**
OPERATIONAL_CERTIFICATE_PATH=**YOUR_OPERATIONAL_CERTIFICATE_PATH**
NETWORK=**YOUR_CARDANO_NETWORK**
AGGREGATOR_ENDPOINT=**YOUR_AGGREGATOR_ENDPOINT**
RUN_INTERVAL=60000
DB_DIRECTORY=/cardano/db
CARDANO_NODE_SOCKET_PATH=/cardano/ipc/node.socket
CARDANO_CLI_PATH=/app/bin/cardano-cli
DATA_STORES_DIRECTORY=/opt/mithril/stores
STORE_RETENTION_LIMIT=5
ERA_READER_ADAPTER_TYPE=**YOUR_ERA_READER_ADAPTER_TYPE**
ERA_READER_ADAPTER_PARAMS=**YOUR_ERA_READER_ADAPTER_PARAMS**
EOF'

Then we will create a /etc/systemd/system/mithril-signer.service description file for our service

sudo bash -c 'cat > /etc/systemd/system/mithril-signer.service << EOF
[Unit]
Description=Mithril Signer service
StartLimitIntervalSec=0

[Service]
Type=simple
Restart=always
RestartSec=1
User=cardano
EnvironmentFile=/opt/mithril/mithril-signer.env
ExecStart=/opt/mithril/mithril-signer -vvv

[Install]
WantedBy=multi-user.target
EOF'

Reload the service configuration (Optional)

sudo systemctl daemon-reload

Then start the service

sudo systemctl start mithril-signer

Then register the service to start on boot

sudo systemctl enable mithril-signer

Then monitor status of the service

systemctl status mithril-signer.service

And monitor the logs of the service

tail /var/log/syslog
tip

There is a 2 epochs delay between the signer node registration and its ability to create individual signatures, as explained in the Mithril Certificate Chain in depth. After this delay, you should be able to see your PoolId listed in some of the certificates available on the Mithril Explorer