• For an introduction on Relayers in Hyperlane, you can check out the Overview section.
  • We recommend you read through the Deploy Hyperlane Local Agents guide to understand how to configure and run the Relayer locally, as well as the Run Validators documentation before trying to run a production Relayer.

​
Requirements

  • 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.

Running a Single Relayer: A single relayer is generally sufficient and can handle message delivery across 100+ chains efficiently. You don’t need to run separate relayers for each network - this approach can increase operational complexity without providing performance benefits.

​
Guide

  • The local agent setup shows how you can run a Relayer on your local machine, which is only for testing and development purposes.
  • We strongly encourage you to follow the local agents guide to understand how to configure and run the Relayer locally.

​
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, but may also be used in production.

​
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.

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

​
Configuration

​
RPC Configuration

Hyperlane Validators and Relayers can use multiple RPC URLs to improve reliability and redundancy. The setup varies based on the chain type.

EVM-based chains support configuring multiple RPC endpoints for redundancy and can specify how they are used.

  • Configure multiple RPCs: Use customRpcUrls.
  • RPC Selection Mode (rpcConsensusType):
    • Fallback: The agent tries the first URL and switches to the next if needed.
    • Quorum: Requires a majority of the URLs to agree with the exception of submitting transactions.

​
Configuration Settings

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.

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.

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 --platform linux/amd64 gcr.io/abacus-labs-dev/hyperlane-agent:agents-v1.4.0

​
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:agents-v1.4.0 \
  ./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 \

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:agents-v1.4.0 \
  ./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.