Skip to main content

Run a Relayer

A Hyperlane Relayer delivers interchain messages to their recipients.

tip

We recommend you read through the Deploy Hyperlane Local Agents guide as well as the Run Validators documentation before trying to run a production Relayer.

Every Hyperlane message requires two transactions to be delivered, one on the origin chain to send the message, and one on the destination chain to receive the messages. A Relayer is responsible for sending the second transaction.

Hyperlane Relayers are configured to relay messages between one or more origin chains and destination chains. A Relayer has no special permissions in Hyperlane. If Relayer keys are compromised, only the tokens held by those keys are at risk.

Running a Relayer requires the following:

  • RPC nodes
    • A Relayer uses RPC nodes to read the origin chain(s), and deliver messages to the destination chain(s). The Relayer must be configured with an RPC node for all origin and destination chains.
  • One or more signing keys
    • In order to deliver messages, the Relayer must be configured with a signing key to submit transactions on each destination chain (thus need funds on those chains).
    • The Relayer uses this key to sign Mailbox.process() transactions. The Hyperlane Relayer agent currently supports configuration with AWS KMS keys that are accessed via API keys/secrets or raw hexadecimal private keys.
  • A machine to run on
    • Relayer operators can compile the Rust binary themselves, or run a Docker image provided by Abacus Works. The binary can be run using your favorite cloud service.

Guide​

We strongly encourage you to follow the local agents guide to understand how to configure and run the Relayer locally.

info

The local agent setup shows how you can run a Relayer on your local machine, which is only for testing and development purposes.

Keys​

The Relayer needs to be able to submit transactions to many destination chains, and therefore requires access to a key for signing transactions. There are two supported key types: hexadecimal private keys (for in-memory signing), and AWS KMS based keys (best practice for production environments).

Hexadecimal keys​

A hexadecimal private key used for in-memory signing can be used by your Relayer to sign transactions. This is the recommended setup for testing or development purposes.

AWS KMS keys​

An AWS KMS key can be used by your Relayer to sign transactions. This is the recommended setup for a production Relayer.

tip

See the Agent Keys page to set up your Hexadecimal or AWS KMS keys.

Configuration​

Like the local setup, there are a few base arguments you should provide when configuring your Relayer.

ArgumentDescription
--relayChainsComma separated names of the origin and destination chains to relay messages between. For example: ethereum,polygon,avalanche.
--dbThe path to where the Relayer should write persistent data to disk. Ensure this path to be persistent when using cloud setups. When using Docker, make sure to mount the persistent path/volume into the container. See config-reference for more info.
--allowLocalCheckpointSyncersIf true, this will allow the Relayer to look for Validator signatures on the Relayer's local filesystem. In a production environment, this should be false. If you're running a Validator on the same machine by following the Validator local setup instructions, set this to true so that your Relayer can access the local Validator signatures.
info

Your Relayer takes both command line arguments and environment variables as configuration. Take a look at the agent configuration page and the configuration reference for a full list of configuration possibilities.

Of course, you can also provide the path to additional configuration files as a comma separated list with the CONFIG_FILES environment variable. If you choose to run in Docker, see the docker section of agent configuration for tips on mounting your config files into your Docker container.

Setup-specific configuration​

These configurations requirements differ depending on which key setup instructions you followed.

If you created a hexadecimal key, configure the default signer like so:

ArgumentDescription
--defaultSigner.keyA hexadecimal private key used to sign transactions for all chains. For example: 1b3dead...beef.

For chain-specific signers (i.e. to customize the key to use for each chain) take a look at the configuration reference

Start Relaying​

Setup​

The recommended installation method for a production environment is using a Docker image.

First download the docker image:

docker pull gcr.io/abacus-labs-dev/hyperlane-agent:3adc0e9-20240319-152359

Running the agent​

If the Relayer's keys have been configured with AWS KMS, you will have to provide the AWS access key and secret as environment variables.

Environment variableDescription
AWS_ACCESS_KEY_IDThe access key ID of your Relayer's AWS IAM user.
AWS_SECRET_ACCESS_KEYThe secret access key of your Relayer's AWS IAM user.

For a refresher, check out the Agent Keys guide.

Then start the container with the relevant arguments. For example, your configuration for AWS:

docker run \
  -it \
  -e AWS_ACCESS_KEY_ID=ABCDEFGHIJKLMNOP \
  -e AWS_SECRET_ACCESS_KEY=xX-haha-nice-try-Xx \
  --mount ... \
  gcr.io/abacus-labs-dev/hyperlane-agent:3adc0e9-20240319-152359 \
  ./relayer \
  --db /hyperlane_db \
  --relayChains <chain_1_name>,<chain_2_name> \
  --defaultSigner.type aws \
  --defaultSigner.id alias/hyperlane-relayer-1 \
  --defaultSigner.region us-east-1 \
tip

If you're running Validators with a local setup on the same machine and running a local Relayer to access these Validator signatures, be sure to mount your local Validator's signature directory into your Relayer at the same path that you used when announcing your Validator

For example, if your local Validator is writing signatures to /tmp/hyperlane-validator-signatures-ethereum, you should mount a directory for the Docker container:

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-validator-signatures-ethereum,target=/tmp/hyperlane-validator-signatures-ethereum,readonly \
  --mount type=bind,source="$(pwd)"/hyperlane_db,target=/hyperlane_db \
  gcr.io/abacus-labs-dev/hyperlane-agent:3adc0e9-20240319-152359 \
  ./relayer \
  --db /hyperlane_db \
  --relayChains ethereum,polygon,avalanche \
  --allowLocalCheckpointSyncers true \
  --defaultSigner.key <your_relayer_key> \

Indexing​

The Relayer needs to index all historic messages for the origin chain(s). This information is stored in a local database on disk (set with db in the config). This means running a Relayer for the first time may take some extra time to catch up with the current state.