| description |
|---|
Required setup instructions |
{% hint style="warning" %} The local setup is only intended for testing or development purposes.
This is intended to show 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 locally ran relayers.
For running a validator in a production environment, see the aws-setup.md guide. {% endhint %}
{% content-ref url="../agent-keys/hexadecimal-key-setup.md" %} hexadecimal-key-setup.md {% endcontent-ref %}
When running a validator locally, your validator will write its signatures to a local directory. This directory can be named whatever you like, just remember to use this directory when setting your #configuration.
# Pick an informative name specific to the chain you're validating
MY_VALIDATOR_SIGNATURES_DIRECTORY=/tmp/hyperlane-validator-signatures-ethereum
# Create the directory
mkdir $MY_VALIDATOR_SIGNATURES_DIRECTORYFor running a validator in a production environment, see the AWS setup guide.
{% content-ref url="aws-setup.md" %} aws-setup.md {% endcontent-ref %}
{% hint style="info" %} 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. {% endhint %}
Your validator takes arguments and environment variables as configuration. See below for both the general configurations and those that are specific to the setup instructions you followed.
| Argument | Description |
|---|---|
--reorgPeriod |
The number of block confirmations a validator should wait before signing the |
--originChainName |
The name of the chain being validated (e.g. ethereum) |
--chains.[origin chain name].connection.url |
The RPC URL of the node for the chain you are validating. Note Polygon mainnet requires an RPC URL of an archive node (see #an-rpc-nodefor details). |
--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. |
| 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 required environment variables differ based on which of the #environments you set up.
{% tabs %} {% tab title="Local setup" %} These are required for the #local-setup.
| 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 on chain that publicly announce your validator's checkpoint syncer. |
--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 Example: |
{% hint style="warning" %}
Note that relayers must be configured with
--allowLocalCheckpointSyncers
to be able to read signatures from this validator.
{% endhint %}
{% endtab %}
{% tab title="Production Setup (AWS)" %} These are required variables that are specific to the aws-setup.md.
| Argument | Description |
|---|---|
--validator.type |
Set to the aws literal. |
--validator.id |
The alias of your validator's AWS KMS key, prefixed with |
--chains.${localchainname}.signer.type |
Set to the aws literal. |
--chains.${localchainname}.signer.id |
The alias of your validator's AWS KMS key, prefixed with |
--validator.region |
The region of your AWS KMS key. |
--checkpointSyncer.type |
Set to s3. |
--checkpointSyncer.bucket |
The AWS S3 bucket name. |
--checkpointSyncer.region |
The region of your AWS S3 bucket. |
| 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. |
| {% endtab %} | |
| {% endtabs %} |
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 git@github.com:hyperlane-xyz/hyperlane-monorepo.gitAnd then follow the setup instructions in the rust directory
{% endtab %}
{% endtabs %}
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.
Refer to the #installation instructions to access the validator binary.
#configuration can be placed in a validator.env file, for example:
{% code title="validator.env" overflow="wrap" %}
# These are example values to roughly illustrate
# what a .env file should look like
HYP_BASE_ORIGINCHAINNAME=ethereum
HYP_BASE_REORGPERIOD=20
# ...
# ...{% endcode %}
To run the validator binary with the environment variables specified in validator.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 validator:
{% code overflow="wrap" %}
docker run -it --env-file validator.env $DOCKER_IMAGE ./validator{% endcode %}
{% hint style="info" %}
If you're specifying a path to your own config file in the CONFIG_FILES environment variable, check out the #config-files-with-docker section.
{% endhint %}
{% hint style="info" %} If you're running with a #local-setup validator on the same machine, which requires a locally ran relayer to be able to access these validator signatures, be sure to mount your local validator's signature directory on your host machine into your Docker container.
For example, if your local validator is writing signatures to /tmp/hyperlane-validator-signatures-ethereum, you should mount a directory for the Docker container. This is the same directory set in the $HYP_BASE_CHECKPOINTSYNCER_PATH environment variable.
If the command below fails with docker: invalid reference format, the whitespaces may have been malformed and you should remove them from the command.
{% code overflow="wrap" %}
docker run \
-it \
--env-file validator.env \
--mount type=bind,source="$(pwd)"/hyperlane-validator-signatures-ethereum,target=/tmp/hyperlane-validator-signatures-ethereum \
# you can pass multiple `--mount` flags to mount several directories
$DOCKER_IMAGE \
./validator{% endcode %} {% endhint %} {% endtab %}
{% tab title="Without Docker" %} See these instructions for building from source.
Using env and xargs, we can run the built binary from within the hyperlane-monorepo/rust directory with the environment variables found in validator.env:
{% code overflow="wrap" %}
env $(cat validator.env | grep -v "#" | xargs) ./target/release/validator{% endcode %} {% endtab %} {% endtabs %}
If everything is configured correctly, you should see json files being written to your S3 bucket (if you followed the aws-setup.md) 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 messaging.md.
relayer.md need 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.