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.
Overview
There are six steps in this guide:- Set up keys that you will use to deploy contracts and run validators and relayers
- Deploy contracts to the local chain and to every remote chain with which the local chain will be able to send and receive messages
- Run a validator to provide the signatures needed for the Interchain Security Modules you deployed
- Run a relayer to send and receive messages between the chains you deployed contracts to
- Send a test message to confirm that your relayer is able to deliver messages to and from each pair of chains
- Deploy a Hyperlane Warp Route (HWR) to send token value, not just messages, across chains
Getting Started
1. Set up keys
Set up your keys for deploying contracts and running agents.2. Deploy contracts
Deploy Hyperlane contracts to your chains.3. 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 theCONFIG_FILES
environment variable to the path of the agent config generated in the deploy contracts step. For example:
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!
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.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. |
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.
Update agent configUnless 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 Mounting directoriesRunning 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:Hardcoding these paths deduplicates 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.
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:- Set the
$CONFIG_FILES
environment variable to a fixed path within the container. - Mount the agent config file to this fixed path and making it readonly.
- Mount the persistent data directory at a fixed path within the container.
- Mount the validator signatures directory to a fixed path within the container.
Run
Now that you understand more about configuring validator arguments, pull the latest docker image:Before running, ensure that all directories you need to mount are present. This may involve creating Finally, run the validator:
hyperlane_db_validator_<your_chain_name>
if it does not exist yet.For further information, check out the Validators
guide. To learn about running
multiple validators, see this
section.
4. Run a relayer
- Single Relayer Recommendation: 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 actually increases operational complexity without providing performance benefits.
- Trusted Relayer ISM Key Management: If you’re using a trusted relayer ISM (which is not recommended for production), avoid using the same relayer key across multiple relayer instances as this can cause nonce conflicts and transaction failures. Either run a single relayer or use different keys for each relayer.
- For production deployments, use a multisig ISM instead of trusted relayer ISM.
CONFIG_FILES
environment variable to the path of the agent config generated in the agent configs step. If not, do so now.
Configure
There are numerous parameters that relayers 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 . |
Your set of relay chains should include both the origin chain and the
destination chain.
Mounting directoriesFor the relayer, we provide almost the same arguments to Docker as the validator: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.
- Set the
$CONFIG_FILES
environment variable to a fixed path within the container. - Mount the agent config file to this fixed path and making it readonly.
- Mount the persistent data directory at a fixed path within the container.
- Mount the validator signatures directory to a fixed path within the container and making it readonly.
Run
If you haven’t already pulled the Docker image, do this now by running:Before running, ensure that all directories you need to mount are present. This may involve creating Finally, run the relayer:
hyperlane_db_relayer
if it does not exist yet.For further information, check out the Relayer
guide.