Mithril-relay

Warning

Do not use in production 🔥

Note

This is a work in progress 🛠

The Mithril relay is an experimental implementation of a relay for Mithril signer and aggregator which supports partial P2P network layer for a Mithril network.

Pre-requisites

• Install the latest stable version of the correctly configured Rust toolchain.

• Install Build Tools build-essential and m4. For example, on Ubuntu/Debian/Mint, run sudo 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 **Build from** column of the **Mithril networks** table above
git checkout **YOUR_BUILD_BRANCH_OR_TAG**

Change the directory:

cd mithril/mithril-relay

Development testing and building

Run tests:

make test

Create the help menu:

make help

Generate the Rust documentation:

make doc

Release the build and run the binary

Build only in release mode:

make build

Display the help menu:

./mithril-relay --help

You should see:

This program is a relay for Mithril nodes.

Usage: mithril-relay [OPTIONS] <COMMAND>

Commands:
  aggregator  Run a relay for a Mithril aggregator
  signer      Run a relay for a Mithril signer
  passive     Run a passive relay (just a peer in the P2P network)
  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]
  -h, --help
          Print help
  -V, --version
          Print version

Run a relay for an aggregator:

./mithril-relay aggregator --listen-port **P2P_LISTEN_PORT** --aggregator-endpoint **AGGREGATOR_ENDPOINT** --dial-to **OTHER_P2P_PEER_TO_CONNECT_TO**

Run a relay for a signer:

./mithril-relay signer --server-port **HTTP_SERVER_LISTENING_PORT** --listen-port **P2P_LISTEN_PORT** --aggregator-endpoint **AGGREGATOR_ENDPOINT** --dial-to **OTHER_P2P_PEER_TO_CONNECT_TO**

Run a passive relay:

./mithril-relay passive --dial-to **OTHER_P2P_PEER_TO_CONNECT_TO**

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)

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 AGGREGATOR_ENDPOINT=**YOUR_AGGREGATOR_ENDPOINT**

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

Proceed by creating a shell function for the Mithril relay:

mithril_relay () {
  docker run --rm -e NETWORK=$NETWORK -e GENESIS_VERIFICATION_KEY=$GENESIS_VERIFICATION_KEY -e AGGREGATOR_ENDPOINT=$AGGREGATOR_ENDPOINT --name='mithril-relay' -v $(pwd):/app/data -u $(id -u) ghcr.io/input-output-hk/mithril-relay:$MITHRIL_IMAGE_ID $@
}

Now you can use the mithril_relay functions:

# 1- Help
mithril_relay --help

# 2- Aggregator
mithril_relay aggregator

# 3- Signer
mithril_relay signer

# 4- Passive
mithril_relay passive

Local image

Build a local Docker image:

make docker-build

Run a local Docker container:

make docker-run

Subcommands

Here are the subcommands available:

Subcommand	Performed action
aggregator	Runs a relay for a Mithril aggregator
signer	Runs a relay for a Mithril signer
passive	Runs a passive relay (just a peer in the P2P network)

Configuration parameters

The configuration parameters can be set in either of the following ways:

1. In a configuration file, depending on the --run-mode parameter. If the runtime mode is testnet, the file is located in ./conf/testnet.json.

2. 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	-	✔️

aggregator command:

Parameter	Command line (long)	Command line (short)	Environment variable	Description	Default value	Example	Mandatory
listen_port	--listen-port	-	LISTEN_PORT	P2P peer listening port	0	9090	✔️
dial_to	--dial-to	-	DIAL_TO	P2P peer address to connect to (not needed for first peer)	-	/ip4/0.0.0.0/tcp/1234	-
aggregator_endpoint	--aggregator-endpoint	-	AGGREGATOR_ENDPOINT	Aggregator node endpoint	-	https://aggregator.pre-release-preview.api.mithril.network/aggregator	✔️

signer command:

Parameter	Command line (long)	Command line (short)	Environment variable	Description	Default value	Example	Mandatory
listen_port	--listen-port	-	LISTEN_PORT	P2P peer listening port	0	9090	✔️
dial_to	--dial-to	-	DIAL_TO	P2P peer address to connect to (not needed for first peer)	-	/ip4/0.0.0.0/tcp/1234	-
server_port	--server-port	-	SERVER_PORT	HTTP server listening port	3132	8181	✔️
aggregator_endpoint	--aggregator-endpoint	-	AGGREGATOR_ENDPOINT	Aggregator node endpoint	-	https://aggregator.pre-release-preview.api.mithril.network/aggregator	✔️

passive command:

Parameter	Command line (long)	Command line (short)	Environment variable	Description	Default value	Example	Mandatory
listen_port	--listen-port	-	LISTEN_PORT	P2P peer listening port	0	9090	✔️
dial_to	--dial-to	-	DIAL_TO	P2P peer address to connect to (not needed for first peer)	-	/ip4/0.0.0.0/tcp/1234	-