Skip to main content

Run a Relayer

A Hyperlane relayer deliver interchain messages to their recipients.

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. Relayers are responsible for sending the second transaction.

Hyperlane relayers are configured to relay messages between one or more origin chains and destination chains. Relayers have 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
    • Relayers use RPC nodes to read the origin chain(s), and deliver messages to the destination chain(s). Relayers must be configured with an RPC node for all origin and destination chains.
  • One or more signing keys
    • In order to deliver messages, relayers 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
    • Relayers 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​

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 production relayers.

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

Configuration​

Also take a look at the agent configuration page and the configuration reference for a full list of configuration possibilities. The list below is not complete, however it should be enough to get started.

Your relayer takes as configuration the following:

ArgumentDescription
--relayChainsComma separated names of the origin and destination chains to relay messages between. 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.
Environment variableDescription
CONFIG_FILESIf you want to add additional configuration files you can add additional paths here as a comma separated list. These files must be accessible within the filesystem your agent has access to. If you're running 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, use these configs.

ArgumentDescription
--defaultSigner.keyA hexadecimal private key used to sign transactions for all chains. Example: --defaultSigner.key=123...def

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

Installation​

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

To download the docker image, run:

docker pull gcr.io/abacus-labs-dev/hyperlane-agent:f44589e-20231130-114734

Start Relaying​

To run the relayer binary with the environment variables specified in relayer.env:

Find the latest docker image and set it to the environment variable $DOCKER_IMAGE.

docker run \
  -it \
  --mount type=bind,source="$(pwd)"/hyperlane_db,target=/hyperlane_db \
  $DOCKER_IMAGE \
  ./relayer --db /hyperlane_db --relayChains ethereum,polygon,avalanche
info

If you have followed the instructions to deploy hyperlane and are specifying a path to your own config file in the CONFIG_FILES environment variable, check out the config files with docker section of agent configuration.

tip

If you're running validators with a local setup on the same machine and want the 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=/path/to/file/inside/container
  --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 \
  $DOCKER_IMAGE \
  ./relayer --db /hyperlane_db --relayChains ethereum,polygon,avalanche

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