Quickstart: Run a Relayer

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 Relayer 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 relayer

Relayers deliver interchain messages sent between the local and remote chains. Learn more about what relayers do here.

You should already have set the CONFIG_FILES environment variable to the path of the agent config generated in the agent configs step. If not, do so now.

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

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.
--relayChains	Comma separated names of the chains to relay between. E.g. ethereum,polygon,avalanche.
--allowLocalCheckpointSyncers	Allows the relayer to look for validator signatures on the local filesystem.
--defaultSigner.key	A hexadecimal private key used to sign transactions for all chains.
--metrics-port	Optional. The port to expose prometheus metrics on, defaults to 9090.

tip

Your set of relay chains should include both the origin chain and destination chain.

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

Using Docker

Mounting directories

For the relayer, we provide almost the same arguments to Docker as the validator:

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 and making it readonly.

...
-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_relayer,target=/hyperlane_db \
--mount type=bind,source="$(pwd)"/$VALIDATOR_SIGNATURES_DIR,target=/tmp/validator-signatures,readonly \
...

Hardcoding these paths deduplicates the configuration between docker instances running relayers for different sets of 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 list of chains to relay between and the relayer key.

Building from source

Clone and setup

If you haven't already done so, clone the Hyperlane monorepo and follow the setup instructions in the rust directory.

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

# 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

If you haven't already pulled the Docker image, do this now by running:

docker pull --platform linux/amd64 gcr.io/abacus-labs-dev/hyperlane-agent:agents-v1.0.0

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

mkdir -p hyperlane_db_validator_<your_chain_name>

Finally, run the relayer:

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_relayer,target=/hyperlane_db \
  --mount type=bind,source="$(pwd)"/$VALIDATOR_SIGNATURES_DIR,target=/tmp/validator-signatures,readonly \
  gcr.io/abacus-labs-dev/hyperlane-agent:agents-v1.0.0 \
  ./relayer \
  --db /hyperlane_db \
  --relayChains <chain_1_name>,<chain_2_name> \
  --allowLocalCheckpointSyncers true \
  --defaultSigner.key <your_relayer_key> \

Building from source

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

cargo run --release --bin relayer -- \
    --db ./hyperlane_db_relayer \
    --relayChains <chain_1_name>,<chain_2_name> \
    --allowLocalCheckpointSyncers true \
    --defaultSigner.key <your_relayer_key> \
    --metrics-port 9091

The metrics port is overridden to avoid clashing with the validator.

(optional) Run the binary directly

You can alternatively build out the agent:

cargo build --release --bin relayer

And run the binary directly:

./target/release/relayer \
    --db ./hyperlane_db_relayer \
    --relayChains <chain_1_name>,<chain_2_name> \
    --allowLocalCheckpointSyncers true \
    --defaultSigner.key <your_relayer_key> \
    --metrics-port 9091