| description |
|---|
Required setup instructions |
The relayer is responsible for watching for new messages on the origin chain(s) and delivering them to their destination chains. This involves being 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).
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.
{% content-ref url="../agent-keys/hexadecimal-key-setup.md" %} hexadecimal-key-setup.md {% endcontent-ref %}
An AWS KMS key can be used by your relayer to sign transactions. This is the recommended setup for production relayers.
{% content-ref url="../agent-keys/aws-setup.md" %} aws-setup.md {% endcontent-ref %}
Also take a look at the agent-configuration page and the configuration-reference.md 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:
| Argument | Description |
|---|---|
--relayChains |
Comma separated names of the origin and destination chains to relay messages between. |
--chains.[chain_name].connection.url |
An RPC url for |
--whitelist |
An optional whitelist. The relayer will only relay messages that match this whitelist. |
--blacklist |
An optional blacklist. The relayer will not relay messages that match this blacklist. |
--db |
The path to where the validator 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. |
--allowLocalCheckpointSyncers |
If |
| Environment variable | Description |
|---|---|
CONFIG_FILES |
If 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 #config-files-with-docker for tips on mounting your config files into your Docker container. |
These configurations requirements differ depending on which setup.md instructions you followed.
{% tabs %} {% tab title="Hexadecimal keys" %} If you created hexadecimal-key-setup.md, use these configs.
| Argument | Description |
|---|---|
--defaultSigner.key |
A hexadecimal private key used to sign transactions for all chains. |
| {% endtab %} |
{% tab title="AWS KMS keys" %} If you created aws-setup.md, use these configs.
| Argument | Description |
|---|---|
--defaultSigner.type |
Set to
|
--defaultSigner.id |
The alias of your validator's AWS KMS key, prefixed with
|
--defaultSigner.region |
The region of your AWS KMS key. |
| Environment variable | Description |
|---|---|
AWS_ACCESS_KEY_ID |
The access key ID of your relayer's AWS IAM user. |
AWS_SECRET_ACCESS_KEY |
The secret access key of your relayer's AWS IAM user. |
| {% endtab %} | |
| {% endtabs %} |
For chain-specific signers take a look at the configuration-reference.md
The recommended installation method for a production environment is using a Docker image.
{% tabs %} {% tab title="Docker" %}
To download the docker image, run:
{% code overflow="wrap" %}
docker pull gcr.io/abacus-labs-dev/hyperlane-agent:8127fa5-20230823-161309{% endcode %} {% endtab %}
{% tab title="Source" %}
First, clone the repo
git clone [email protected]:hyperlane-xyz/hyperlane-monorepo.gitAnd then follow the setup instructions in the rust directory
{% endtab %}
{% endtabs %}
Refer to the #installation instructions to access the relayer binary.
#configuration can be placed in a relayer.env file, for example:
{% code title="relayer.env" overflow="wrap" %}
# These are example values to roughly illustrate
# what a .env file should look like
HYP_BASE_RELAYCHAINS=ethereum,polygon,avalanche
HYP_BASE_DB="/hyperlane_db"
# ...
# ...{% endcode %}
To run the relayer binary with the environment variables specified in relayer.env:
{% tabs %}
{% tab title="Using Docker" %}
Find the latest #docker-image and set it to the environment variable $DOCKER_IMAGE.
Using the --env-file flag, we can pass in the environment variables to the relayer:
{% code overflow="wrap" %}
docker run \
-it \
--env-file relayer.env \
--mount type=bind,source="$(pwd)"/hyperlane_db,target=/hyperlane_db \
$DOCKER_IMAGE \
./relayer{% endcode %}
{% hint style="info" %}
If you have followed the instructions to deploy-hyperlane.md and are specifying a path to your own config file in the CONFIG_FILES environment variable, check out #config-files-with-docker.
{% endhint %}
{% hint style="info" %} If you're running validator with #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:
{% code overflow="wrap" %}
docker run \
-it \
--env-file relayer.env \
--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{% endcode %} {% endhint %} {% endtab %}
{% tab title="Without Docker" %} See these instructions for #building-from-source.
We can run the built binary from within the hyperlane-monorepo/rust directory with the environment variables found in relayer.env:
{% code overflow="wrap" %}
env $(cat relayer.env | grep -v "#" | xargs) ./target/release/relayer{% endcode %} {% endtab %} {% endtabs %}
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.