Validators
Overview
Hyperlane validators are light offchain agents responsible for security - they observe messages on an origin chain's Mailbox and if needed sign a merkle root that attests the current state of the mailbox.
This signature is stored and made publicly available (e.g. in a S3 bucket), which is then used by the offchain Relayer and Interchain Security Modules onchain. Validators are not networked together and do not need to reach consensus; they also do not regularly submit onchain transactions.
As you follow this guide, you can run a Hyperlane validator on any of the existing chains the protocol is live on. Hyperlane Validators are run on a per-origin-chain basis, and these instructions are written for a single chain.
Requirements
-
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. See more under agent keys.
- Validators use this key to sign the
-
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.
-
The design is open source and generalizable to other storage and key solutions. There is a community-submitted work-in-progress PR for GCS.
-
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"
- Hardware requirements & costs are minimal - validators often start with a 2-Core / 2GB RAM / 4GB Storage setup with typical costs around $75/mo
-
RPC Node
- Validators make simple view calls to read merkle roots from the Mailbox contract on the chain they are validating for. You must use your own RPC urls not any public ones.
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.
Guide
As a recap - before running a production Validator you need to have:
- Created a key for your Validator to sign with, see the Agent Keys documentation.
- Set up the destination for your Validator signatures to be posted, see the AWS Signatures Bucket Setup guide.
Configuration
Experienced operators may prefer to deploy agents with Terraform or a community-submitted Ansible playbook instead. This process will automatically create agent keys, Validator buckets, permissions and any other auxiliary setup required to run a Validator cluster on AWS.
Like the local setup, there are a few base arguments you should provide when configuring your Validator.
Parameter | Description |
---|---|
--db | Path for writing persistent data to disk. |
--originChainName | Name of the chain being validated. For example: ethereum . |
--chains.[originChainName].customRpcUrls | Override the default RPC URLs used by the Validator for your origin chain. |
--chains.[originChainName].blocks.reorgPeriod | Number of block confirmations the Validator needs to wait for before signing the Mailbox merkle root. |
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.
Checkpoint signer configuration
- Hex Key
- AWS KMS
Argument | Description |
---|---|
--validator.key | Your Validator's private key, which is used to sign merkle roots. |
--chains.${localChainName}.signer.key | Your Validator's private key, which will be used to submit a transaction onchain that publicly announces your Validator's checkpoint syncer. |
Argument | Description |
---|---|
--validator.region | The region of your AWS KMS key. For example: us-east-1 . |
--validator.type | Set to the aws literal. |
--validator.id | The alias of your Validator's AWS KMS key, prefixed with alias/ . For example: alias/hyperlane-validator-signer-${originChainName} . |
Transaction signer configuration
The key configured in this step needs a small amount of funds to send the initial announcement transaction.
- Hex Key (EVM)
- AWS KMS (EVM)
- Hex Key (Cosmos)
This is the same as the local configuration for the checkpoint signer.
Argument | Description |
---|---|
--chains.${localChainName}.signer.key | Your Validator's private key, which will be used to submit a transaction onchain that publicly announces your Validator's checkpoint syncer. |
Argument | Description |
---|---|
--chains.${originChainName}.signer.type | Set to the aws literal. |
--chains.${originChainName}.signer.region | The region of your AWS KMS key. For example: us-east-1 . |
--chains.${originChainName}.signer.id | The alias of your Validator's AWS KMS key, prefixed with alias/ . For example: alias/hyperlane-validator-signer-${originChainName} . |
Argument | Description |
---|---|
--chains.${originChainName}.signer.type | Set to the cosmosKey literal. |
--chains.${originChainName}.signer.prefix | Set to the prefix literal associated with the chain's address format. Example: osmo . |
--chains.${originChainName}.key | Your Validator's hex private key, which will be used to submit a transaction onchain that publicly announces your Validator's checkpoint syncer. |
Checkpoint syncer configuration
- Local Setup
- Production Setup (AWS)
Argument | Description |
---|---|
--checkpointSyncer.type | Set to localStorage . |
--checkpointSyncer.path | The 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' . |
Note that the Relayer must be configured with --allowLocalCheckpointSyncers
to be able to read signatures from this Validator.
Argument | Description |
---|---|
--checkpointSyncer.type | Set to s3 . |
--checkpointSyncer.bucket | The AWS S3 bucket name. |
--checkpointSyncer.region | The region of your AWS S3 bucket. For example: us-east-1 . |
--checkpointSyncer.folder | A folder name to use for this validator, can be the name of the chain |
Start Validating
Setup
The recommended installation method for a production environment is using a Docker image.
- Docker image
- Building from source
First download the docker image:
docker pull --platform linux/amd64 gcr.io/abacus-labs-dev/hyperlane-agent:74a592e-20240906-191210
Clone and setup
First, clone the Hyperlane monorepo:
git clone git@github.com:hyperlane-xyz/hyperlane-monorepo.git
Then follow the setup instructions in the rust
directory. This should setup rustup
as well as Rosetta 2 if you are on Apple Silicon.
# install rustup
curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
# (apple silicon only) install rosetta 2
softwareupdate --install-rosetta --agree-to-license
Build the Validator:
cargo build --release bin validator
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 variable | Description |
---|---|
AWS_ACCESS_KEY_ID | The access key ID of your Validator's AWS IAM user. |
AWS_SECRET_ACCESS_KEY | The secret access key of your Validator's AWS IAM user. |
For a refresher, check out the Agent Keys guide.
- Using Docker
- Building from source
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:74a592e-20240906-191210 \
./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_name> \
--checkpointSyncer.folder <your_chain_name> \
See these instructions for building from source without Docker.
We can run the built binary from within the hyperlane-monorepo/rust
directory:
# set AWS environment variables
export AWS_ACCESS_KEY_ID=ABCDEFGHIJKLMNOP
export AWS_SECRET_ACCESS_KEY=xX-haha-nice-try-Xx
# run the Validator
./target/release/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 \
--chains.<your_chain_name>.signer.region<region_name> \
--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.
Next: Running multiple Validators
We encourage folks to validate on as many chains as they are interested in supporting.
Some tips for easily running multiple validators:
- The same key can be used by multiple validators.
- The same AWS account can be used by multiple validators.
- The same checkpoint syncer S3 bucket can by used by multiple validators, however they must use different folders, e.g. using the
--checkpointSyncer.folder
flag.