Skip to main content

Validators

Everything you need to start running a Validator.

tip

Experienced operators may prefer to deploy agents with terraform instead. This process will automatically create agent keys, Validator buckets, permissions and any other auxiliary setup required to run a Validator cluster on AWS.

Hyperlane Validators are not networked with other Validators and do not regularly submit transactions. Hyperlane Validators are run on a per-origin-chain basis, and these instructions are written for a single chain.

Running a Validator requires the following:

  • An RPC node
    • Validators make simple view calls to read merkle roots from the Mailbox contract on the chain they are validating for.
caution

Operating a Validator for Polygon mainnet requires access to an archive node. This is because Validators should only sign roots once they've been finalized, and Polygon requires 256 block confirmations to achieve finality.

  • A secure signing key

    • Validators use this key to sign the Mailbox's latest merkle root. Securing this key is important. If it is compromised, attackers can attempt to falsify messages, causing the Validator to be slashed.
    • The Hyperlane Validator agent currently supports signing with AWS KMS keys that are accessed via API keys/secrets as well as hexadecimal plaintext keys for testing. See more under agent keys.

  • Publicly readable storage

    • Validators write their signatures off-chain to publicly accessible, highly available, storage, so that they can be aggregated by the Relayer.
    • The Hyperlane Validator agent currently supports storing signatures on AWS S3 using the same AWS API key above, as well as storing signatures in the local filesystem for testing.

  • A machine to run on

    • Validators 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. You can even run multiple instances of them in different regions for high availability, as Hyperlane has no notion of "double signing".

Guide​

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

info

The local agent setup shows how you can run a Validator on your local machine, which is only for testing and development purposes. This also means that signatures from local Validators are only able to be accessed by a locally run Relayer.

For a production environment, you should post signatures to a publicly accessible bucket. See the AWS bucket setup guide.

As a recap - before running a production Validator you need to ensure you have:

  1. Created a key for your Validator to sign with, see the Agent Keys documentation.
  2. Set up the desination for your Validator signatures to be posted, see the AWS Signatures Bucket Setup guide.

Configuration​

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

ParameterDescription
--dbPath for writing persistent data to disk.
--originChainNameName of the chain being validated. For example: ethereum.
--chains.[originChainName].customRpcUrlsOverride the default RPC URLs used by the Validator for your origin chain.
--chains.[originChainName].blocks.reorgPeriodNumber of block confirmations the Validator needs to wait for before signing the Mailbox merkle root.
info

Your Validator 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 environment you are setting up.

Base Validator configuration

ArgumentDescription
--validator.keyYour Validator's private key, which is used to sign merkle roots.
--chains.${localChainName}.signer.keyYour Validator's private key, which will be used to submit a transaction on chain that publicly announce your Validator's checkpoint syncer.

Checkpoint syncer configuration

ArgumentDescription
--checkpointSyncer.typeSet to localStorage.
--checkpointSyncer.pathThe path to your local directory where Validator signatures will be written. This should be the value of $MY_VALIDATOR_SIGNATURES_DIRECTORY from the local setup. For example: --checkpointSyncer.path='/tmp/hyperlane-validator-signatures-ethereum'.
warning

Note that the Relayer must be configured with --allowLocalCheckpointSyncers to be able to read signatures from this Validator.

Start Validating​

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

For production Validators that write their signatures to an S3 bucket and have their keys 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 Validator's AWS IAM user.
AWS_SECRET_ACCESS_KEYThe secret access key of your Validator'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 \
  ./validator \
  --db /hyperlane_db \
  --originChainName <your_chain_name> \
  --reorgPeriod 1 \
  --validator.region us-east-1 \
  --checkpointSyncer.region us-east-1 \
  --validator.type aws \
  --chains.<your_chain_name>.signer.type aws \
  --validator.id alias/hyperlane-validator-signer-<your_chain_name> \
  --chains.<your_chain_name>.signer.id alias/hyperlane-validator-signer-<your_chain_name> \
  --checkpointSyncer.type s3 \
  --checkpointSyncer.bucket hyperlane-validator-signatures-<your_chain_name> \

Announcing your Validator​

The Relayer needs to know where to find your Validator's signatures. Your Validator will automatically attempt to announce itself by writing to the ValidatorAnnounce contract on the chain that you're validating.

To do this, your Validator must have a small amount of tokens to pay for the gas for this transaction.

If your Validator has not yet announced itself, and does not have enough tokens to pay for gas, it will log a message specifying how many tokens are needed.

Success!​

The Validator will index the origin Mailbox contract for messages. If a message has been sent, you should see log messages that the Validator has signed them. If everything is configured correctly, you should see json files being written to your S3 bucket (if you followed the AWS setup) or to your local signatures directory if you followed the local setup. New json files get written every time a new outbound message is inserted into the mailbox.

Running multiple Validators​

We encourage folks to validate on as many chains as they are interested in supporting. We recommend that resources are not shared between Validator instances.