Running a Validator

Metalayer validators secure messages passed between chains within the Metalayer. A quorum of validators must verify that a message was actually sent prior to being delivered. Validating is a permissioned operation, and the Metalayer mantains a validator set to secure the entire network.

What is a Metalayer Validator?

Metalayer is a cross‑chain message‑passing protocol that wraps Hyperlane-authored but Metalayer-deployed contracts and runs its own off‑chain agent network. This means that validators may run the same executable as a Hyperlane network validator, with a different config. Validators sign the latest Mailbox dispatched messages each origin chain and publish those signatures so Metalayer relayers can aggregate and forward messages.

How Metalayer Differs from Hyperlane

Topic	Hyperlane	Metalayer
Contract addresses	Public hyperlane‑registry repo	Config bundle supplied by Caldera – do not copy Hyperlane values
Agents network	Global Hyperlane mesh	Isolated Metalayer mesh
CLI, flags, binary	`hyperlane-agent`	Same binary (Abacus Works image)
Staking / PoS	Hyperlane POS contracts	N/A – no on‑chain staking for Metalayer

Operational commands and flags are otherwise identical.

Requirements

Requirement	Notes
Secure signing key	AWS KMS, Vault HSM, or raw hex. Same CLI flags as Hyperlane (`--validator.*`).
Available gas balance	The signer must hold enough native token to broadcast the on‑chain announce tx. The same signer MAY be reused across multiple chains.
Public storage (checkpoint syncer)	S3 bucket (prod).
Machine	2 vCPU / 2 GB RAM / 4 GB disk is sufficient.
RPC endpoints	Provide ≥ 2 per chain. Private RPCs ensure validator security.
Max 1 chain per validator instance	Each validator instance only supports 1 chain at most. For redundancy, operators may choose to run multiple validator instances (e.g., across different availability zones) pointing to the same S3 bucket.

Quick‑Start

# 1  Get our chain config bundle (replace link when public)
wget https://docs.metalayer.xyz/configs/<version>/ethereum.yaml -O ethereum.yaml

# 2  Pull the Abacus Works agent image
docker pull --platform linux/amd64 gcr.io/abacus-labs-dev/hyperlane-agent:agents-v1.4.0

# 3  Run the validator (example for Ethereum mainnet)
docker run -it --rm \
  -v $(pwd)/ethereum.yaml:/config/validator.yaml:ro \
  -v $(pwd)/data:/metalayer_db \
  -e AWS_ACCESS_KEY_ID=$AWS_ACCESS_KEY_ID \
  -e AWS_SECRET_ACCESS_KEY=$AWS_SECRET_ACCESS_KEY \
  gcr.io/abacus-labs-dev/hyperlane-agent:agents-v1.4.0 \
  validator --config /config/validator.yaml

If everything is wired correctly you’ll see signed‑root logs and JSON blobs appearing in your S3 bucket or local folder.

Step‑by‑Step Setup

Coordinate With Caldera (allow‑list)

Provide Caldera with:

Intended origin chain(s)
Signer address(es) – one per validator instance.

Create / Secure Signing Keys

Choose one of:

AWS KMS (recommended)

aws kms create-key --key-usage SIGN_VERIFY --customer-master-key-spec ECC_SECG_P256K1
aws kms create-alias --alias-name alias/metalayer-validator-ethereum --target-key-id <keyId>

Raw hex key – fine for testnet

Prepare Checkpoint Storage

S3 (prod) – bucket metalayer-validator-sigs-<YOU>
Local (test) – any directory; flag -checkpointSyncer.type localStorage

Fetch the Binary

Use the Abacus Works image or build from source.

Docker

docker pull gcr.io/abacus-labs-dev/hyperlane-agent:agents-v1.4.0

Source

$ git clone https://github.com/hyperlane-xyz/hyperlane-monorepo.git
$ cd hyperlane-monorepo/rust
$ cargo build --release -p validator

Write Your Config

A minimal validator.json (replace placeholders; defaults noted):

{
  "db": "/metalayer_db",
  "validator": {
    "type": "aws",
    "region": "us-east-1",
    "id": "alias/metalayer-validator-ethereum"
  },
  "checkpointSyncer": {
    "type": "s3",
    "bucket": "metalayer-validator-sigs-you",
    "region": "us-east-1",
    "folder": "ethereum"
  },
  "originChainName": "ethereum",
  "chains": {
    "ethereum": {
      "domainId": 1,
      "name": "ethereum",
      "chainId": 1,
      "protocol": "ethereum",
      "rpcUrls": [
        {
          "http": "https://eth-mainnet.g.alchemy.com/v2/demo"
        },
        {
          "http": "https://rpc.ankr.com/eth"
        }
      ],
      "nativeToken": {
        "name": "Ether",
        "symbol": "ETH",
        "decimals": 18
      },
      "blocks": {
        "reorgPeriod": "0"
      },
      "index": {
        "from": 0
      },
      "mailbox": "0x0000000000000000000000000000000000000000",
      "validatorAnnounce": "0x0000000000000000000000000000000000000000",
      "merkleTreeHook": "0x0000000000000000000000000000000000000000",
      "interchainGasPaymaster": "0x0000000000000000000000000000000000000000",
      "signer": {
        "type": "aws",
        "region": "<your region>",
        "id": "<your key>"
      }
    }
  }
}

Start & Verify Announcement

Run the Docker command from Quick‑Start. The agent will automatically broadcast announce(); fund the signer with a small amount of native token first.

Deployment Recipes

docker‑compose

version: "3.9"
services:
  validator:
    image: gcr.io/abacus-labs-dev/hyperlane-agent:agents-v1.4.0
    platform: linux/amd64
    command: ./validator
    volumes:
      - /config/validator.json:/config/validator.json
      - ./data:/metalayer_db
    environment:
      CONFIG_FILES: /config/validator.json
      AWS_ACCESS_KEY_ID: ${AWS_ACCESS_KEY_ID}
      AWS_SECRET_ACCESS_KEY: ${AWS_SECRET_ACCESS_KEY}
    restart: unless-stopped

Helm (values snippet – sample only)

validator:
  image:
    repository: gcr.io/abacus-labs-dev/hyperlane-agent
    tag: agents-v1.4.0
  args: ["./validator"]
  env:
    CONFIG_FILES: "/config/validator.json" # needs to be mounted as a volume
    AWS_ACCESS_KEY_ID: ""
    AWS_SECRET_ACCESS_KEY: ""
  persistence:
    size: 5Gi
  resources:
    requests:
      cpu: "200m"     
      memory: "256Mi"
    limits:
      cpu: "500m"
      memory: "512Mi"

Running Multiple Validators

Reuse the same signing key or create one per instance – both valid.
Each validator needs a unique checkpointSyncer.folder (S3 prefix) and -db path.
Expose metrics on unique ports.

Monitoring & Troubleshooting

Symptom	Likely Cause	Fix
`not enough gas`	Signer wallet unfunded	Top‑up with native token
No signatures in S3	Bad bucket policy / wrong region	Check IAM & `checkpointSyncer` section
High `db: prune required`	Disk too small	Give ≥ 5 GB or mount volume

Prometheus metrics exposed on :9090/metrics by default. We suggest implementing Hyperlane’s Grafana dashboard.

Developers

Intents

Message Passing

.era Domains

What is a Metalayer Validator?

How Metalayer Differs from Hyperlane

Requirements

Quick‑Start

Step‑by‑Step Setup

Coordinate With Caldera (allow‑list)

Create / Secure Signing Keys

Prepare Checkpoint Storage

Fetch the Binary

Docker

Source

Write Your Config

Start & Verify Announcement

Deployment Recipes

docker‑compose

Helm (values snippet – sample only)

Running Multiple Validators

Monitoring & Troubleshooting

Developers

Intents

Message Passing

.era Domains

​What is a Metalayer Validator?

​How Metalayer Differs from Hyperlane

​Requirements

​Quick‑Start

​Step‑by‑Step Setup

​Coordinate With Caldera (allow‑list)

​Create / Secure Signing Keys

​Prepare Checkpoint Storage

​Fetch the Binary

​Docker

​Source

​Write Your Config

​Start & Verify Announcement

​Deployment Recipes

​docker‑compose

​Helm (values snippet – sample only)

​Running Multiple Validators

​Monitoring & Troubleshooting

What is a Metalayer Validator?

How Metalayer Differs from Hyperlane

Requirements

Quick‑Start

Step‑by‑Step Setup

Coordinate With Caldera (allow‑list)

Create / Secure Signing Keys

Prepare Checkpoint Storage

Fetch the Binary

Docker

Source

Write Your Config

Start & Verify Announcement

Deployment Recipes

docker‑compose

Helm (values snippet – sample only)

Running Multiple Validators

Monitoring & Troubleshooting