Quickstart: Run a Validator

tip

• This guide is for advanced users who may eventually intend to run Hyperlane agents in a production-like environment. It will cover the basics of how to manually configure and run agents but it is not a production setup guide.
• For more detailed guide, check out the Validators guide

Terminology

The "local chain" is your new chain that you want to deploy Hyperlane onto.

A "remote chain" is a chain with an existing Hyperlane deployment that you want your local chain to send & receive messages to & from.

Run a validator

Validators provide the security for messages sent from your chain to remote chains. They're only required when using a Multisig ISM. Learn more about what validators do here.

Setup directories

First, set the CONFIG_FILES environment variable to the path of the agent config generated in the deploy contracts step. For example:

export CONFIG_FILES=/full/path/to/configs/agent-config-{timestamp}.json

Next, create a local directory for your validator to write its signatures to. Remember the path, as you will need this when configuring your validator.

danger

The validator signatures path will be written on-chain as part of the validator announcement transaction. Be careful not to reveal any security-sensitive or personal information!

# Pick an informative name specific to the chain you're validating
export VALIDATOR_SIGNATURES_DIR=/tmp/hyperlane-validator-signatures-<your_chain_name>

# Create the directory
mkdir -p $VALIDATOR_SIGNATURES_DIR

warning

You will not be able to mount anything in /tmp when running the agent via Docker on Mac. To counter this, create a local tmp directory to mount instead.

# Create a local tmp directory that can be accessed by docker
mkdir tmp

# Pick an informative name specific to the chain you're validating
export VALIDATOR_SIGNATURES_DIR=tmp/hyperlane-validator-signatures-<your_chain_name>

# Create the directory
mkdir -p $VALIDATOR_SIGNATURES_DIR

Configure

There are numerous parameters that validators can be configured with. For this guide, we are concerned with just a handful:

Parameter	Description
--db	Path for writing persistent data to disk.
--originChainName	Name of the chain being validated (e.g. ethereum).
--checkpointSyncer.type	Set to localStorage for this guide.
--checkpointSyncer.path	Path to local directory where validator signatures will be written. Same path as $VALIDATOR_SIGNATURES_DIR.
--validator.key	Your validator's hexadecimal private key.

info

Make sure the validator key corresponds to the address provided when setting up your MultisigIsmConfig. Otherwise, the Multisig ISM you deployed in the previous step will not be able to verify messages sent from your chain.

To learn more about all the parameters you can change, read the agent configuration reference.

Using Docker

Update agent config

Unless you are running Docker on Linux, you will also need to update the agent configuration for your network. This is because Docker does not support the host network mode on Mac, Windows or Windows Server.

To do this, navigate to the agent-configuration at $CONFIG_FILES and replace all instances of "localhost" or "127.0.0.1" in to host.docker.internal. For example:

...
"localnet1": {
  ...
  "rpcUrls": [
    {
      // "http": "http://localhost:8545"
      // "http": "http://127.0.0.1:8545"
      "http": "http://host.docker.internal:8545"
    }
  ],
  ...
},
...

Mounting directories

Running with Docker adds an extra layer of complexity because config files need to be accessible from within the Docker container, and validator signatures need to be accessible from outside of the container for the relayer to read. This is so the relayer can construct the metadata required for the message to be successfully validated by the Multisig ISM.

To solve this issue, you can mount directories on your file system into the container. In the arguments below, we:

1. Set the $CONFIG_FILES environment variable to a fixed path within the container.
2. Mount the agent config file to this fixed path and making it readonly.
3. Mount the persistent data directory at a fixed path within the container.
4. Mount the validator signatures directory to a fixed path within the container.

...
-e CONFIG_FILES=/config/agent-config.json \
--mount type=bind,source=$CONFIG_FILES,target=/config/agent-config.json,readonly \
--mount type=bind,source="$(pwd)"/hyperlane_db_validator_<your_chain_name>,target=/hyperlane_db \
--mount type=bind,source="$(pwd)"/$VALIDATOR_SIGNATURES_DIR,target=/tmp/validator-signatures \
...

Hardcoding these paths deduplucates the configuration between docker instances running validators for different origin chains. This makes it easier to pass the right arguments when running the container. See the example below, where the only items to be configured differently for different chains are the chain name and validator key.

...
./validator \
--db /hyperlane_db \
--originChainName <your_chain_name> \
--checkpointSyncer.type localStorage \
--checkpointSyncer.path /tmp/validator-signatures \
--validator.key <your_validator_key>
...

Building from source

Clone and setup

First, clone the Hyperlane monorepo:

git clone git@github.com:hyperlane-xyz/hyperlane-monorepo.git

Then follow the setup instructions in the rust directory. This should setup rustup as well as Rosetta 2 if you are on Apple Silicon.

# install rustup
curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh

# (apple silicon only) install rosetta 2
softwareupdate --install-rosetta --agree-to-license

Run

Using Docker

Now that you understand more about configuring validator arguments, pull the latest docker image:

docker pull --platform linux/amd64 gcr.io/abacus-labs-dev/hyperlane-agent:7a8478b-20240703-113821

Before running, ensure that all directories you need to mount are present. This may involve creating hyperlane_db_validator_<your_chain_name> if it does not exist yet.

mkdir -p hyperlane_db_validator_<your_chain_name>

Finally, run the validator:

docker run \
  -it \
  -e CONFIG_FILES=/config/agent-config.json \
  --mount type=bind,source=$CONFIG_FILES,target=/config/agent-config.json,readonly \
  --mount type=bind,source="$(pwd)"/hyperlane_db_validator_<your_chain_name>,target=/hyperlane_db \
  --mount type=bind,source="$(pwd)"/$VALIDATOR_SIGNATURES_DIR,target=/tmp/validator-signatures \
  gcr.io/abacus-labs-dev/hyperlane-agent:7a8478b-20240703-113821 \
  ./validator \
  --db /hyperlane_db \
  --originChainName <your_chain_name> \
  --checkpointSyncer.type localStorage \
  --checkpointSyncer.path /tmp/validator-signatures \
  --validator.key <your_validator_key>

Building from source

After following the setup instructions, you should now be able to use cargo to run the Validator:

cargo run --release --bin validator -- \
    --db ./hyperlane_db_validator_<your_chain_name> \
    --originChainName <your_chain_name> \
    --checkpointSyncer.type localStorage \
    --checkpointSyncer.path $VALIDATOR_SIGNATURES_DIR \
    --validator.key <your_validator_key>

(optional) Run the binary directly

You can alternatively build out the agent:

cargo build --release --bin validator

And run the binary directly:

./target/release/validator \
    --db ./hyperlane_db_validator_<your_chain_name> \
    --originChainName <your_chain_name> \
    --checkpointSyncer.type localStorage \
    --checkpointSyncer.path $VALIDATOR_SIGNATURES_DIR \
    --validator.key <your_validator_key>