Quickstart with Docker Compose and AWS

Sometimes it is nice to not rely on long docker commands. Running with Docker compose is very similar to using raw Docker and you can find a full specification of the format in the Docker docs.

1. Setup validator key

Follow the guide here for creating agent keys with AWS KMS.

2. Create S3 bucket for signatures

Follow the guide here for creating and configuring an S3 bucket for your validator to write signatures to.

3. (AVS Operators Only) Register with Hyperlane AVS

If you are an AVS operator, follow the guide here to register with the Hyperlane AVS.

4. Setup validator environment

Create config files

In this example, we will run three chains.

mkdir -p ethereum/hyperlane_db optimism/hyperlane_db base/hyperlane_db && \
touch ethereum/config.json optimism/config.json base/config.json docker-compose.yml .env.ethereum .env.optimism .env.base

Edit each config.json

You can read more about Agent Configs here.

Parameter	Description
customRpcUrls	A comma-separated list of performant RPC endpoints for the chain you wish to support. We recommend using paid providers to avoid rate limiting.
chains.ethereum	Should be changed to chains.base in the base/config.json, and chains.optimism in optimism/config.json.
signer.region	Should be adjusted to your AWS region.
validator.region	Should be adjusted to your AWS region.
signer.id	Should be adjusted to your AWS KMS id you configured in step 3, prefixed with alias/.
validator.id	Should be adjusted to your AWS KMS id you configured in step 3, prefixed with alias/.
originChainName	Should be the chain you are validating.
checkpointSyncer.bucket	Should reflect the name of the S3 bucket.
checkpointSyncer.folder	The name of the folder the validator will use within the bucket. You may use the same bucket for multiple validators, but ensure each folder name is unique per validator.
reorgPeriod	May be different for each chain. Find the reorgPeriods.

Here is an example agent config.

{
  "chains": {
    "ethereum": {
      "customRpcUrls": "https://eth.llamarpc.com,https://rpc.mevblocker.io",
      "signer": {
        "region": "us-east-1",
        "type": "aws",
        "id": "alias/hyperlane-validator-signer"
      }
    }
  },
  "originChainName": "ethereum",
  "db": "/mnt/hyperlane_db",
  "validator": {
    "id": "alias/hyperlane-validator",
    "type": "aws",
    "region": "us-east-1"
  },
  "checkpointSyncer": {
    "bucket": "hyperlane-validator-signatures",
    "region": "us-east-1",
    "type": "s3",
    "folder": "ethereum"
  },
  "reorgPeriod": 14,
  "metricsPort": "9090"
}

Edit each .env file

You should change the service name, aws credentials for each chain

AWS_ACCESS_KEY_ID=<Your AWS access key ID>
AWS_SECRET_ACCESS_KEY=<Your AWS secret access key>
SERVICE_NAME=ethereum

5. Configure Docker Compose (docker-compose.yml)

x-common-attributes: &common-validator
  image: gcr.io/abacus-labs-dev/hyperlane-agent:7a8478b-20240703-113821
  command: ./validator
  container_name: ${SERVICE_NAME}-validator
  environment:
    CONFIG_FILES: /config.json
    AWS_ACCESS_KEY_ID: ${AWS_ACCESS_KEY_ID}
    AWS_SECRET_ACCESS_KEY: ${AWS_SECRET_ACCESS_KEY}
  volumes:
    - ./${SERVICE_NAME}/hyperlane_db:/mnt/hyperlane_db
    - ./${SERVICE_NAME}/config.json:/config.json
  restart: unless-stopped

services:
  ethereum-validator:
    <<: *common-validator
    ports:
      - "9091:9090/tcp"

  optimism-validator:
    <<: *common-validator
    ports:
      - "9092:9090/tcp"

  base-validator:
    <<: *common-validator
    ports:
      - "9093:9090/tcp"

Your directory structure should look similar to this:

.
├── base
│   ├── config.json
│   └── hyperlane_db
├── docker-compose.yml
├── ethereum
│   ├── config.json
│   └── hyperlane_db
├── .env.base
├── .env.ethereum
├── .env.optimism
└── optimism
    ├── config.json
    └── hyperlane_db

6. Run the Hyperlane validators

Bring the containers up:

Remember to fund your validator address so the validator can announce.

docker compose --env-file .env.ethereum up ethereum-validator -d
docker compose --env-file .env.optimism up optimism-validator -d
docker compose --env-file .env.base up base-validator -d

Ensure there are no errors:

docker logs -f ethereum-validator
docker logs -f optimism-validator
docker logs -f base-validator