Hyperlane

https://docs.hyperlane.xyz/
Admin
Hyperlane is a cross-chain interoperability protocol and development platform that enables secure...
Tokens:81,016
Snippets:488
Trust Score:9.2
Update:1 year ago
Show doc for...
Tokens:
Raw
### Install Anvil (Foundry)

Source: https://docs.hyperlane.xyz/docs/guides/quickstart/local-testnet-setup

Installs Anvil, a local Ethereum node for testing, by downloading and executing a script from the Foundry project. This is a prerequisite for running local chains.

```shell
curl -L https://foundry.paradigm.xyz | bash
```

--------------------------------

### Install Hyperlane CLI

Source: https://docs.hyperlane.xyz/docs/guides/quickstart/local-testnet-setup

Installs the Hyperlane Command Line Interface globally using npm. Requires Node.js v18 or later.

```shell
npm install -g @hyperlane-xyz/cli
```

--------------------------------

### Initialize Hyperlane Warp Route Configuration

Source: https://docs.hyperlane.xyz/docs/guides/warp-routes/evm/deploy-multi-collateral-warp-routes

Use the Hyperlane CLI to start a new Warp Route deployment configuration. This command guides you through network selection, token addresses, proxy admin contracts, and ISM choices.

```bash
hyperlane warp init
```

--------------------------------

### Start Hyperlane Validator Containers

Source: https://docs.hyperlane.xyz/docs/operate/guides/docker-quickstart

These commands use Docker Compose to start the Hyperlane validator containers for Ethereum, Optimism, and Base in detached mode. It's crucial to fund your validator address for it to announce correctly.

```bash
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
```

--------------------------------

### Example Hyperlane Agent Configuration (JSON)

Source: https://docs.hyperlane.xyz/docs/operate/guides/docker-quickstart

This JSON object defines the configuration for a Hyperlane agent, specifying chain details, RPC endpoints, AWS KMS integration for signing and validation, S3 bucket for checkpoints, and database paths. Ensure 'originChainName' and AWS region/ID details are updated.

```json
{
  "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"
}
```

--------------------------------

### Example Hyperlane Configuration Output

Source: https://docs.hyperlane.xyz/docs/guides/production/warp-route-deployment/transfer-warp-route-ownership

This is an example of the configuration output after running the `warp read` command, demonstrating a successfully updated owner address for a specific chain.

```yaml
yourchain:
  mailbox: "0x979Ca5202784112f4738403dBec5D0F3B9daabB9"
  owner: "0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045"
  IInterchainSecurityModule:
    address: "0x8af9445d8A3FbFBd1D5dF185B8a4533Ab060Cf36"
    type: staticAggregationIsm
    modules:
      - owner: "0xe738d6e51aad88F6F4ce6aB8827279cffFb94876"
        address: "0xBe0232d5d45f9aD8322C2C4F84c39e64302Cd996"
        type: defaultFallbackRoutingIsm
        domains: {}
    threshold: 1
  name: Ether
  symbol: ETH
  decimals: 18
  totalSupply: 0
  type: native
```

--------------------------------

### Start Local Anvil Nodes

Source: https://docs.hyperlane.xyz/docs/guides/quickstart/local-testnet-setup

Starts two distinct Anvil nodes with different ports and chain IDs for local testing. Each command specifies the port, chain ID, and block time.

```shell
anvil --port 8545 --chain-id 31337 --block-time 1
```

```shell
anvil --port 8546 --chain-id 31338 --block-time 1
```

--------------------------------

### Example .env File for Validator Configuration

Source: https://docs.hyperlane.xyz/docs/operate/guides/docker-quickstart

This .env file sets environment variables for Hyperlane validators, including AWS credentials and the service name. Adjust the AWS access key ID, secret access key, and service name according to your specific deployment.

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

--------------------------------

### Create Validator Configuration Files and Docker Compose

Source: https://docs.hyperlane.xyz/docs/operate/guides/docker-quickstart

This command initializes the necessary directories and configuration files for running Hyperlane validators for Ethereum, Optimism, and Base chains. It also creates the main docker-compose.yml and .env files.

```bash
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
```

--------------------------------

### Create Relayer Database Directory

Source: https://docs.hyperlane.xyz/docs/guides/chains/deploy-hyperlane-with-local-agents

Creates the directory for the relayer's persistent database if it does not already exist. This directory is mounted into the Docker container.

```bash
mkdir -p hyperlane_db_relayer
```

--------------------------------

### Docker Mount Arguments for Relayer

Source: https://docs.hyperlane.xyz/docs/guides/chains/deploy-hyperlane-with-local-agents

Demonstrates how to mount necessary directories and environment variables when running the Hyperlane relayer agent within a Docker container. Includes read-only mounts for configuration and validator signatures.

```bash
...\n-e CONFIG_FILES=/config/agent-config.json \n--mount type=bind,source=$CONFIG_FILES,target=/config/agent-config.json,readonly \n--mount type=bind,source="$(pwd)"/hyperlane_db_relayer,target=/hyperlane_db \n--mount type=bind,source="$(pwd)"/$VALIDATOR_SIGNATURES_DIR,target=/tmp/validator-signatures,readonly \n...
```

--------------------------------

### Install Hyperlane CLI with NPM

Source: https://docs.hyperlane.xyz/docs/reference/developer-tools/cli

Installs the Hyperlane CLI globally using npm. This makes the 'hyperlane' command available in your terminal. It also provides a command to uninstall previous versions.

```shell
# Install with NPM
npm install -g @hyperlane-xyz/cli

# Or uninstall old versions
npm uninstall -g @hyperlane-xyz/cli

```

--------------------------------

### Create Validator Signatures Directory (Standard)

Source: https://docs.hyperlane.xyz/docs/guides/chains/deploy-hyperlane-with-local-agents

Creates a local directory for the validator to store its signatures. This path is used when configuring the validator and is written on-chain.

```bash
# Pick an informative name specific to the chain you're validating
export VALIDATOR_SIGNATURES_DIR=/tmp/hyperlane-validator-signatures-<your_chain_name>

# Create the directory
mkdir -p $VALIDATOR_SIGNATURES_DIR

```

--------------------------------

### Hyperlane Validator CLI Arguments

Source: https://docs.hyperlane.xyz/docs/guides/chains/deploy-hyperlane-with-local-agents

This snippet displays the command-line arguments used to configure and run the Hyperlane validator executable. It covers essential parameters such as the database path, origin chain name, checkpoint syncer configuration, and the validator's private key.

```bash
./validator \
--db /hyperlane_db \
--originChainName <your_chain_name> \
--checkpointSyncer.type localStorage \
--checkpointSyncer.path /tmp/validator-signatures \
--validator.key <your_validator_key>
```

--------------------------------

### Monitor Hyperlane Validator Logs

Source: https://docs.hyperlane.xyz/docs/operate/guides/docker-quickstart

These commands attach to the logs of the running Hyperlane validator containers for Ethereum, Optimism, and Base. This allows you to monitor their activity and troubleshoot any issues.

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

--------------------------------

### Create Working Directory

Source: https://docs.hyperlane.xyz/docs/guides/quickstart/local-testnet-setup

Creates a new directory for Hyperlane local testing and changes the current directory into it. This sets up the project's workspace.

```shell
mkdir hyperlane-local-test && cd hyperlane-local-test
```

--------------------------------

### Solana token-config.json Example

Source: https://docs.hyperlane.xyz/docs/guides/warp-routes/evm-svm-warp-route-guide

Configuration for a synthetic token on Solana, including its decimals, name, symbol, URI, interchain gas paymaster, and remote decimals. Also includes collateral details for Ethereum.

```json
{
  "solana": {
    "type": "synthetic",
    "decimals": 9,
    "name": "Renzo Restaked LST",
    "symbol": "pzETH",
    "uri": "<https://raw.githubusercontent.com/hyperlane-xyz/hyperlane-registry/12660fd34d30e960a748d87408a8d88f634f7454/deployments/warp_routes/pzETH/ethereum-solana-metadata.json>",
    "interchainGasPaymaster": "5FG1TUuhXGKdMbbH8uHEnUghazD4aVfEPAgKLNGNx3SL",
    "remoteDecimals": 18
  },
  "ethereum": {
    "type": "collateral",
    "decimals": 18,
    "token": "0x8c9532a60e0e7c6bbd2b2c1303f63ace1c3e9811",
    "foreignDeployment": "0x1D622da2ce4C4D9D4B0611718cb3BcDcAd008DD4"
  }
}

```

--------------------------------

### Docker Compose Configuration for Hyperlane Validators

Source: https://docs.hyperlane.xyz/docs/operate/guides/docker-quickstart

This YAML defines the Docker Compose setup for running Hyperlane validators. It uses a common configuration for validator containers and specifies ports and volumes for Ethereum, Optimism, and Base chains. Ensure the image tag and environment variables are correctly set.

```yaml
x-common-attributes: &common-validator
  image: gcr.io/abacus-labs-dev/hyperlane-agent:agents-v1.4.0
  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"

```

--------------------------------

### Anvil Node 1 Metadata Configuration

Source: https://docs.hyperlane.xyz/docs/guides/quickstart/local-testnet-setup

Example YAML configuration for the first Anvil node (anvilnode1), specifying its chain ID, display name, native token details, and RPC URL.

```yaml
chainId: 31337
displayName: Anvilnode1
domainId: 31337
isTestnet: true
name: anvilnode1
nativeToken:
  decimals: 18
  name: ETH
  symbol: ETH
protocol: ethereum
rpcUrls:
  - http: http://localhost:8545
```

--------------------------------

### Initialize Hyperlane Core Configuration

Source: https://docs.hyperlane.xyz/docs/guides/quickstart/local-testnet-setup

Initializes the configuration for deploying Hyperlane core contracts. This generates a `./configs/core-config.yaml` file.

```shell
hyperlane core init
```

--------------------------------

### Anvil Node 2 Metadata Configuration

Source: https://docs.hyperlane.xyz/docs/guides/quickstart/local-testnet-setup

Example YAML configuration for the second Anvil node (anvilnode2), specifying its chain ID, display name, native token details, and RPC URL.

```yaml
chainId: 31338
displayName: Anvilnode2
domainId: 31338
isTestnet: true
name: anvilnode2
nativeToken:
  decimals: 18
  name: ETH
  symbol: ETH
protocol: ethereum
rpcUrls:
  - http: http://localhost:8546
```

--------------------------------

### Run Hyperlane Relayer Docker Container

Source: https://docs.hyperlane.xyz/docs/guides/chains/deploy-hyperlane-with-local-agents

Executes the Hyperlane relayer agent using Docker. It configures environment variables, mounts volumes, specifies chains to relay between, and provides the relayer's private key.

```bash
docker run \
  -it \
  -e CONFIG_FILES=/config/agent-config.json \
  --mount type=bind,source=$CONFIG_FILES,target=/config/agent-config.json,readonly \
  --mount type=bind,source="$(pwd)"/hyperlane_db_relayer,target=/hyperlane_db \
  --mount type=bind,source="$(pwd)"/$VALIDATOR_SIGNATURES_DIR,target=/tmp/validator-signatures,readonly \
  gcr.io/abacus-labs-dev/hyperlane-agent:agents-v1.4.0 \
  ./relayer \
  --db /hyperlane_db \
  --relayChains <chain_1_name>,<chain_2_name> \
  --allowLocalCheckpointSyncers true \
  --defaultSigner.key <your_relayer_key> \

```

--------------------------------

### Set CONFIG_FILES Environment Variable

Source: https://docs.hyperlane.xyz/docs/guides/chains/deploy-hyperlane-with-local-agents

Sets the environment variable CONFIG_FILES to the path of the agent configuration file. This is a prerequisite for running the relayer.

```bash
export CONFIG_FILES=/full/path/to/configs/agent-config.json
```

--------------------------------

### Docker Run Command with Volume Mounts

Source: https://docs.hyperlane.xyz/docs/guides/chains/deploy-hyperlane-with-local-agents

This code demonstrates the `docker run` command for executing a Hyperlane validator. It includes environment variable settings and volume mounts for configuration files, persistent data, and validator signatures, ensuring proper data accessibility for the validator and relayer.

```bash
docker run \
  -it \
  -e CONFIG_FILES=/config/agent-config.json \
  --mount type=bind,source=$CONFIG_FILES,target=/config/agent-config.json,readonly \
  --mount type=bind,source="$(pwd)"/hyperlane_db_validator_<your_chain_name>,target=/hyperlane_db \
  --mount type=bind,source="$(pwd)"/$VALIDATOR_SIGNATURES_DIR,target=/tmp/validator-signatures \
  gcr.io/abacus-labs-dev/hyperlane-agent:agents-v1.4.0 \
  ./validator \
  --db /hyperlane_db \
  --originChainName <your_chain_name> \
  --checkpointSyncer.type localStorage \
  --checkpointSyncer.path /tmp/validator-signatures \
  --validator.key <your_validator_key>
```

--------------------------------

### Initialize Hyperlane Chain Metadata Configuration

Source: https://docs.hyperlane.xyz/docs/guides/quickstart/deploy-warp-route

This command starts an interactive process to create a new chain metadata configuration file for chains not yet present in the Hyperlane Registry. This configuration is essential for the deployment process if target chains are not pre-registered.

```bash
hyperlane registry init
```

--------------------------------

### Docker Pull Command

Source: https://docs.hyperlane.xyz/docs/guides/chains/deploy-hyperlane-with-local-agents

This command is used to pull the specified Hyperlane agent Docker image, ensuring you have the latest version for running your validators.

```bash
docker pull --platform linux/amd64 gcr.io/abacus-labs-dev/hyperlane-agent:agents-v1.4.0
```

--------------------------------

### HWR Configuration File Example

Source: https://docs.hyperlane.xyz/docs/guides/production/warp-route-deployment/transfer-warp-route-ownership

An example of a warp-route-deployment.yaml file showing the configuration of a Hyperlane Warp Route (HWR). It includes details like the mailbox address, current owner, Interchain Security Module (ISM) configuration, token name, symbol, and decimals. This file is used to manage HWR settings.

```yaml
yourchain:
  mailbox: "0x979Ca5202784112f4738403dBec5D0F3B9daabB9"
  owner: "0xf39Fd6e51aad88F6F4ce6aB8827279cffFb92266"
  ...
```

--------------------------------

### Set Hyperlane Agent Configuration Path

Source: https://docs.hyperlane.xyz/docs/guides/chains/deploy-hyperlane-with-local-agents

Sets the environment variable CONFIG_FILES to the path of the agent configuration file. This is a prerequisite for running Hyperlane agents.

```bash
export CONFIG_FILES=/full/path/to/configs/agent-config-{timestamp}.json

```

--------------------------------

### Create Validator Database Directory

Source: https://docs.hyperlane.xyz/docs/guides/chains/deploy-hyperlane-with-local-agents

This command ensures that the directory for storing validator persistent data exists before running the Docker container. It creates the necessary directory structure for `hyperlane_db_validator_<your_chain_name>`.

```bash
mkdir -p hyperlane_db_validator_<your_chain_name>
```

--------------------------------

### Create Validator Signatures Directory (Docker on Mac)

Source: https://docs.hyperlane.xyz/docs/guides/chains/deploy-hyperlane-with-local-agents

Creates a local 'tmp' directory and the validator signatures directory within it, to be mounted by Docker on Mac. This is a workaround for limitations with '/tmp' on Mac Docker.

```bash
# Create a local tmp directory that can be accessed by docker
mkdir tmp

# Pick an informative name specific to the chain you're validating
export VALIDATOR_SIGNATURES_DIR=tmp/hyperlane-validator-signatures-<your_chain_name>

# Create the directory
mkdir -p $VALIDATOR_SIGNATURES_DIR

```

--------------------------------

### Run Hyperlane CLI commands with npx or dlx

Source: https://docs.hyperlane.xyz/docs/reference/developer-tools/cli

Demonstrates how to run individual Hyperlane CLI commands without a global installation using npx (for npm) or dlx (for Yarn). This is useful for testing or executing specific commands.

```shell
# Run via NPM's npx command
npx @hyperlane-xyz/cli

# Or via Yarn's dlx command
yarn dlx @hyperlane-xyz/cli

```

--------------------------------

### Run Hyperlane Agent with Local Validator Signatures and Hex Key

Source: https://docs.hyperlane.xyz/docs/operate/relayer/run-relayer

Starts the Hyperlane Relayer agent using Docker, mounting local validator signatures and specifying a hexadecimal key for signing. It also configures the database path and relay chains.

```docker
docker run \
  -it \
  -e CONFIG_FILES=/config/agent-config.json \
  --mount type=bind,source=$CONFIG_FILES,target=/config/agent-config.json,readonly \
  --mount type=bind,source="$(pwd)"/hyperlane-validator-signatures-ethereum,target=/tmp/hyperlane-validator-signatures-ethereum,readonly \
  --mount type=bind,source="$(pwd)"/hyperlane_db,target=/hyperlane_db \
  gcr.io/abacus-labs-dev/hyperlane-agent:agents-v1.4.0 \
  ./relayer \
  --db /hyperlane_db \
  --relayChains ethereum,polygon,avalanche \
  --allowLocalCheckpointSyncers true \
  --defaultSigner.key <your_relayer_key> \

```

--------------------------------

### Start Anvil with Auto-Mining

Source: https://docs.hyperlane.xyz/docs/guides/quickstart/local-testnet-setup

Ensures timely message processing by configuring Anvil to auto-mine blocks every second. This prevents relayers and validators from waiting indefinitely for new blocks.

```bash
anvil --block-time 1
```

--------------------------------

### Relayer Configuration Arguments

Source: https://docs.hyperlane.xyz/docs/operate/relayer/run-relayer

This snippet outlines essential command-line arguments for configuring a Hyperlane Relayer, specifying chains for message relay, persistent data storage, and local checkpoint syncer settings.

```bash
--relayChains Comma separated names of the origin and destination chains to relay messages between. For example: ethereum,polygon,avalanche
--db The path to where the Relayer 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. See config-reference for more info.
--allowLocalCheckpointSyncers If `true`, this will allow the Relayer to look for Validator signatures on the Relayer’s local filesystem. In a production environment, this should be `false`. If you’re running a Validator on the same machine by following the Validator local setup instructions, set this to `true` so that your Relayer can access the local Validator signatures.
```

--------------------------------

### Install Solana CLI v1.18.18

Source: https://docs.hyperlane.xyz/docs/guides/warp-routes/svm/svm-warp-route-guide

Installs Solana CLI version 1.18.18, which is required for deploying HWR contracts. This command downloads and installs the specified version. It's crucial to use this exact version for successful deployment.

```bash
sh -c "$(curl -sSfL https://release.anza.xyz/v1.18.18/install)"
```

--------------------------------

### Verify SVM Router Deployment (Cast)

Source: https://docs.hyperlane.xyz/docs/guides/warp-routes/evm-svm-warp-route-guide

Command using 'cast' to verify the deployment of an SVM router on Ethereum by calling the 'routers' function on the destination domain.

```bash
$ cast call 0x1D622da2ce4C4D9D4B0611718cb3BcDcAd008DD4 'routers(uint32)(bytes32)' $DESTINATION_DOMAIN --rpc-url $(rpc ethereum) 1399811149
0xe9792265ec273ffc17731af890d3e9963e9d744e7b99f02491911ce1bb75b8cb
```

--------------------------------

### Solidity Example: Sending a Message

Source: https://docs.hyperlane.xyz/docs/reference/messaging/send

Demonstrates how to use the `dispatch` function to send a message from Ethereum to a recipient on the Polygon Testnet. It shows initializing the `IMailbox` interface, setting parameters, and calling `dispatch` with the required value.

```solidity
// send message from Ethereum to Polygon TestRecipient
IMailbox mailbox = IMailbox("0xc005dc82818d67AF737725bD4bf75435d065D239");
bytes32 messageId = mailbox.dispatch{value: msg.value}(
  137,
  "0x000000000000000000000000f90cB82a76492614D07B82a7658917f3aC811Ac1",
  bytes("Hello World")
);
```

--------------------------------

### Chain Configuration Example (JSON)

Source: https://docs.hyperlane.xyz/docs/guides/warp-routes/bridge-ui-guide

Example configuration for chain metadata, similar to what's used with Hyperlane CLI commands. It includes chain ID, name, display name, native token details (name, symbol, decimals), public RPC URLs, block confirmations, reorg period, estimated block time, and a logo URI.

```json
{
"anvil1": {
    "chainId": 31337,
    "name": 'anvil1',
    "displayName": 'Anvil 1 Local',
    "nativeToken": { "name": 'Ether', "symbol": 'ETH', "decimals": 18 },
    "publicRpcUrls": [{ "http": 'http://127.0.0.1:8545' }],
    "blocks": {
      "confirmations": 1,
      "reorgPeriod": 0,
      "estimateBlockTime": 10,
    },
    "logoURI": '/logo.svg'
  }
}
```

--------------------------------

### Deploy Hyperlane Core Contracts

Source: https://docs.hyperlane.xyz/docs/guides/quickstart/local-testnet-setup

Deploys the Hyperlane core contracts (Mailbox, ISMs, etc.) to the specified local Anvil nodes. The command prompts for node selection, and contract addresses are saved in `addresses.yaml`.

```shell
hyperlane core deploy
```

--------------------------------

### Example Mailbox Configuration Output

Source: https://docs.hyperlane.xyz/docs/guides/production/core-deployment/update-mailbox-default-ism

This is an example of the configuration output you would expect after running the 'hyperlane core read' command. It displays details about the default hook, default ISM, and owner addresses, confirming the update.

```yaml
defaultHook:
  address: "0x67F8c06Fd2915728E9D21451E33FbDFbCcd63c44"
  type: "merkleTreeHook"
defaultIsm:
  address: "0xac7D6df90fa937ADEfE7aD2d4905f0AEa170c467"
  relayer: "0x0000000000000000000000000000000000000001"
  type: "trustedRelayerIsm"
owner: "0xa5558cA30cd9952Ab0e2349C274a3736698bD60e"
requiredHook:
  address: "0x1Cd94b4D9B5f0e3474a6bDB8b9503Ca84F53e548"
  beneficiary: "0xa5558cA30cd9952Ab0e2349C274a3736698bD60e"
  maxProtocolFee: "100000000000000000"
  owner: "0xa5558cA30cd9952Ab0e2349C274a3736698bD60e"
  protocolFee: "0"
  type: "protocolFee"
```

--------------------------------

### Environment Variable for Configuration Files

Source: https://docs.hyperlane.xyz/docs/operate/relayer/run-relayer

Demonstrates how to specify additional configuration files for the Relayer using the `CONFIG_FILES` environment variable. This is useful for organizing complex configurations.

```bash
CONFIG_FILES path/to/config1.json,path/to/config2.yaml
```

--------------------------------

### Verify Solana CLI Version

Source: https://docs.hyperlane.xyz/docs/guides/warp-routes/svm/svm-warp-route-guide

Checks the currently installed Solana CLI version. This command is used to confirm that version 1.18.18 has been successfully installed, as required for the deployment process.

```bash
solana --version
```

--------------------------------

### Setup CrosschainAppTest with Mock Environment - Solidity

Source: https://docs.hyperlane.xyz/docs/reference/developer-tips/unit-testing

Sets up a test environment for a cross-chain application inheriting from Router. It initializes mock mailboxes for origin and destination chains and enrolls them as remote routers for bidirectional communication.

```Solidity
contract CrosschainAppTest is Test {
    // origin and destination domains (recommended to be the chainId)
    uint32 origin = 1;
    uint32 destination = 2;

    function setUp() public {
        environment = new MockHyperlaneEnvironment(origin, destination);

        // your cross-chain app
        TestCrosschainApp originTelephone  = new TestCrosschainApp(environment.mailboxes(origin));
        TestCrosschainApp destinationTelephone  = new TestCrosschainApp(environment.mailboxes(destination));

        // assuming you're inheriting the Router pattern from https://github.com/hyperlane-xyz/hyperlane-monorepo/blob/main/solidity/contracts/client/Router.sol
        originTelephone.enrollRemoteRouter(destinationTelephone);
        destinationTelephone.enrollRemoteRouter(originTelephone);
    }
}
```

--------------------------------

### Deploy SVM Warp Route (Rust/Cargo)

Source: https://docs.hyperlane.xyz/docs/guides/warp-routes/evm-svm-warp-route-guide

Command to deploy a Warp Route on the Solana Virtual Machine (SVM) side using the Hyperlane CLI and Cargo. It specifies key files and deployment parameters.

```bash
cargo run -- -k ~/solana-mainnet-deployer-keypair.json warp-route deploy \
--warp-route-name pzeth  \
--environment mainnet3  \
--environments-dir ../environments  \
--built-so-dir ../../target/deploy  \
--token-config-file ../environments/mainnet3/warp-routes/pzeth/token-config.json  \
--chain-config-file ../environments/mainnet3/chain-config.json  \
--ata-payer-funding-amount 50000000
```

--------------------------------

### Set Private Key Environment Variable

Source: https://docs.hyperlane.xyz/docs/guides/quickstart/deploy-warp-route

Sets the private key as an environment variable (HYP_KEY) to avoid manual entry during deployment. This is a convenient way to manage credentials.

```bash
export HYP_KEY=<your_private_key>
```

--------------------------------

### Set Deployer Wallet Private Key

Source: https://docs.hyperlane.xyz/docs/guides/quickstart/local-testnet-setup

Exports the deployer wallet's private key as an environment variable named HYP_KEY. This key is used for deploying contracts and requires a funded wallet.

```shell
export HYP_KEY=<YOUR_PRIVATE_KEY>
```

--------------------------------

### HWR Example Flow: Minting Synthetic Token from Native Token

Source: https://docs.hyperlane.xyz/docs/applications/warp-routes/example-usage

Demonstrates the process of creating a synthetic version of a native token on a destination chain. This involves specifying the source chain and native token, the destination chain and synthetic token, and the amount.

```text
Transaction Type: Minting Synthetic Token from Native Token
From: Celo (CELO)
To: Optimism (wCELO)
Amount: 100 CELO
```

--------------------------------

### Encoding Metadata with StandardHookMetadata.formatMetadata

Source: https://docs.hyperlane.xyz/docs/reference/hooks/interchain-gas

Example of encoding metadata using the StandardHookMetadata.formatMetadata library function. This function facilitates the creation of packed metadata for cross-chain communication.

```solidity
// Example: Encoding metadata using StandardHookMetadata
bytes memory metadata = StandardHookMetadata.formatMetadata(
    0,               // ETH message value
    200000,          // Custom gas limit
    address(this),   // Refund address
    bytes("")        // Optional custom metadata
);

```

--------------------------------

### Mounting Config Files with Docker

Source: https://docs.hyperlane.xyz/docs/operate/config/agent-config

Provides an example of how to run a Hyperlane agent in Docker, mounting a local configuration file into the container and specifying it via the CONFIG_FILES environment variable.

```docker
docker run -it \
--mount type=bind,source=/home/workspace/ethereum.json,target=/config/ethereum.json,readonly \
-e CONFIG_FILES=/config/ethereum.json $DOCKER_IMAGE ./validator
```

--------------------------------

### SVM Token Configuration (Solana)

Source: https://docs.hyperlane.xyz/docs/guides/warp-routes/evm-svm-warp-route-guide

Defines the configuration for a synthetic token on the Solana (SVM) side, including decimals, name, symbol, URI, and interchain gas paymaster.

```json
{
  "solana": {
    "type": "synthetic",
    "decimals": 9,
    "name": "Renzo Restaked LST",
    "symbol": "pzETH",
    "uri": "<https://raw.githubusercontent.com/hyperlane-xyz/hyperlane-registry/12660 mainnet3/warp_routes/pzETH/ethereum-solana-metadata.json>",
    "interchainGasPaymaster": "5FG1TUuhXGKdMbbH8uHEnUghazD4aVfEPAgKLNGNx3SL",
    "remoteDecimals": 18
  }
}
```

--------------------------------

### Build Hyperlane CLI from Source

Source: https://docs.hyperlane.xyz/docs/guides/deploy-hyperlane-troubleshooting

These commands outline the process to build the Hyperlane CLI from source, necessary when deploying on chains that do not natively support `eth_getStorageAt()`. It involves cloning the repository, applying specific code changes, building the project, and running the CLI.

```bash
git clone <hyperlane_repo_url>
cd hyperlane
# Apply changes from the specific commit
yarn build
yarn workspace @hyperlane-xyz/cli hyperlane
```

--------------------------------

### Configure Indexing Start Height for Chains

Source: https://docs.hyperlane.xyz/docs/operate/config/config-reference

Specifies the block height from which contract indexing should begin. Defaults to 0 if not provided.

```bash
--chains.${CHAIN_NAME}.index.from 0
--chains.ethereum.index.from 16271503
```

--------------------------------

### Extend Core Chain Configuration

Source: https://docs.hyperlane.xyz/docs/guides/deploy-hyperlane-troubleshooting

Extends a core chain configuration by overriding specific fields. This example shows how to set the number of block confirmations for the Sepolia chain.

```yaml
sepolia:
  blocks:
    confirmations: 2

```

--------------------------------

### List Registered Hyperlane Chains

Source: https://docs.hyperlane.xyz/docs/guides/quickstart/deploy-warp-route

This command retrieves and displays a list of all chains currently recognized and registered within the Hyperlane network. This is useful for identifying existing chain configurations to reuse.

```bash
hyperlane registry list
```

--------------------------------

### Ethereum HWR Deployment Configuration (YAML)

Source: https://docs.hyperlane.xyz/docs/guides/warp-routes/evm-svm-warp-route-guide

Configuration file for deploying an Ethereum Hyperlane Warp Route (HWR). It includes settings for the interchain security module, mailbox, owner, token, type, and gas, as well as SVM chain details.

```yaml
ethereum:
  interchainSecurityModule: "0x0000000000000000000000000000000000000000"
  isNft: false
  mailbox: "0xc005dc82818d67AF737725bD4bf75435d065D239"
  owner: "0xa7ECcdb9Be08178f896c26b7BbD8C3D4E844d9Ba"
  token: "0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48"
  type: collateral
  gas: 300000
eclipsemainnet:
  foreignDeployment: "D6k6T3G74ij6atCtBiWBs5TbFa1hFVcrFUSGZHuV7q3Z"
  mailbox: "EitxJuv2iBjsg2d7jVy2LDC1e2zBrx4GB5Y9h2Ko3A9Y"
  owner: "9bRSUPjfS3xS6n5EfkJzHFTRDa4AHLda8BU2pP4HoWnf"
  interchainSecurityModule: "0x0000000000000000000000000000000000000000"
  type: synthetic
  gas: 300000
```

--------------------------------

### HWR Example Flow: Native to Native Transfer

Source: https://docs.hyperlane.xyz/docs/applications/warp-routes/example-usage

Illustrates a transaction for transferring native tokens between two EVM-compatible chains. It specifies the transaction type, source chain and asset, destination chain and asset, and the amount.

```text
Transaction Type: Native to Native Transfer
From: Ethereum (ETH)
To: inEVM (ETH)
Amount: 1 ETH
```

--------------------------------

### Relay EVM-EVM Message with Hyperlane CLI

Source: https://docs.hyperlane.xyz/docs/resources/message-debugging

Instructions for relaying a message between two EVM chains using the Hyperlane Command Line Interface (CLI). This requires setting up the CLI locally and having the message ID and a destination chain private key.

```bash
# 1. Set up Hyperlane CLI
# Refer to official documentation for setup instructions.

# 2. Find your message ID (using EVM or Cosmos methods described above)

# 3. Obtain a private key for an account with funds on your destination chain

# Example command structure (actual command will vary based on CLI implementation):
hyperlane relay evm-to-evm --message-id <your_message_id> --destination-private-key <your_destination_private_key>
```

--------------------------------

### Send Test Message with Hyperlane

Source: https://docs.hyperlane.xyz/docs/guides/quickstart/local-testnet-setup

Sends a test message between two local Hyperlane-configured chains using the CLI. The `--relay` flag is used for local testing to automatically relay the message.

```shell
hyperlane send message --relay
```

--------------------------------

### Initialize Hyperlane Registry Configuration

Source: https://docs.hyperlane.xyz/docs/guides/chains/deploy-hyperlane

Initializes the Hyperlane registry with custom chain metadata. This command prompts the user for chain details and creates a metadata.yaml file in the user's home directory under ~/.hyperlane/chains.

```bash
hyperlane registry init

```

--------------------------------

### Deploy Hyperlane Warp Routes 2.0

Source: https://docs.hyperlane.xyz/docs/guides/warp-routes/evm/deploy-multi-collateral-warp-routes

Initiate the deployment of your configured Hyperlane Warp Routes 2.0. The CLI requires your private key (set as HYP_KEY env var or entered when prompted) to sign transactions on the relevant chains. Ensure sufficient funds for gas fees.

```bash
hyperlane warp deploy
```

--------------------------------

### GET /messages

Source: https://docs.hyperlane.xyz/docs/operate/relayer/api/messages/get-messages

Retrieves a list of Hyperlane messages for a given domain ID and a range of nonces. It allows filtering messages based on the starting and ending nonce values.

```APIDOC
## GET /messages

### Description
Retrieves a list of Hyperlane messages for a given domain ID and a range of nonces. It allows filtering messages based on the starting and ending nonce values.

### Method
GET

### Endpoint
/messages

### Parameters
#### Query Parameters
- **domain_id** (number) - Required - Chain domain ID (u32)
- **nonce_start** (number) - Required - Starting nonce (inclusive) (u32)
- **nonce_end** (number) - Required - Ending nonce (inclusive) (u32)

### Request Example
```curl
curl "http://localhost:9090/messages?domain_id=1&nonce_start=100&nonce_end=200"
```

### Response
#### Success Response (200)
- **messages** (Array<HyperlaneMessage>) - An array of HyperlaneMessage objects.

#### Response Example
```json
{
  "messages": [
    {
      "version": 3,
      "nonce": 1235,
      "origin": 1,
      "destination": 2,
      "sender": "0xabc...",
      "recipient": "0xdef...",
      "body": [
        0,
        3,
        0,
        23,
        43,
        65
      ]
    }
  ]
}
```

#### HyperlaneMessage Object
- **version** (u8) - Hyperlane version number
- **nonce** (u32) - Message nonce
- **origin** (u32) - Message origin
- **destination** (u32) - Message destination
- **sender** (string) - Message sender
- **recipient** (string) - Message recipient
- **body** (Vec<u8>) - Message body

### Error Handling
- **400**: Returned if `nonce_end` is not greater than `nonce_start`.
```

--------------------------------

### Initialize Hyperlane Core Configuration

Source: https://docs.hyperlane.xyz/docs/guides/chains/deploy-hyperlane

Initializes the Hyperlane core contracts configuration. This requires setting the HYP_KEY environment variable with the deployer's private key or seed phrase.

```bash
export HYP_KEY='<YOUR_PRIVATE_KEY>'
hyperlane core init

```

--------------------------------

### Relay Message with Hyperlane Status

Source: https://docs.hyperlane.xyz/docs/resources/message-debugging

This command relays a message using the Hyperlane status tool. It requires your private key, origin chain, destination chain, and message ID. Ensure you have the Hyperlane CLI installed and configured.

```shell
HYP_KEY=<your-private-key> hyperlane status --relay --origin <origin-chain> --destination <destination-chain> --id <message-id>
```

```shell
HYP_KEY=0xffff00000000000000000000000000000000000000000000000000000000ffff hyperlane status --relay --origin base --destination blast --id 0xabcd00000000000000000000000000000000000000000000000000000000abcd
```

--------------------------------

### MailboxClient Initialization and Configuration

Source: https://docs.hyperlane.xyz/docs/reference/developer-tools/libraries/mailbox-client

Explains how to initialize and configure the MailboxClient contract, including setting hooks and security modules.

```APIDOC
## MailboxClient Initialization and Configuration

### Constructor
```solidity
constructor(address _mailbox)
```
Initializes the `MailboxClient` with the address of the `Mailbox` contract. It also sets the `localDomain` and transfers ownership to the deployer.

### Functions
#### `setHook(address _hook)`
```solidity
function setHook(address _hook) public onlyContractOrNull(_hook) onlyOwner
```
**Description**: Sets or updates the address of the optional post-dispatch hook contract. Requires the caller to be the owner.

#### `setInterchainSecurityModule(address _module)`
```solidity
function setInterchainSecurityModule(address _module) public onlyContractOrNull(_module) onlyOwner
```
**Description**: Sets or updates the address of the optional interchain security module. Requires the caller to be the owner.

#### `_MailboxClient_initialize(address _hook, address _interchainSecurityModule, address _owner)`
```solidity
function _MailboxClient_initialize(address _hook, address _interchainSecurityModule, address _owner) internal onlyInitializing
```
**Description**: Internal initializer function for upgradeable contracts. Sets the hook, interchain security module, and owner.
```

--------------------------------

### Update Docker Agent Config (JSON)

Source: https://docs.hyperlane.xyz/docs/guides/chains/deploy-hyperlane-with-local-agents

This snippet shows how to update the agent configuration for Dockerized Hyperlane validators when running on non-Linux systems. It specifically addresses replacing 'localhost' or '127.0.0.1' with 'host.docker.internal' in the RPC URLs.

```json
{
  "localnet1": {
    "rpcUrls": [
      {
        "http": "http://host.docker.internal:8545"
      }
    ]
  }
}
```

--------------------------------

### Display Hyperlane Sealevel Client CLI Help

Source: https://docs.hyperlane.xyz/docs/guides/warp-routes/svm/svm-warp-route-guide

Command to display the help information for the `hyperlane-sealevel-client` CLI, listing available subcommands and options. This is useful for exploring the full capabilities of the tool.

```bash
# run from `rust/sealevel/client`
cargo run -- --help
```

--------------------------------

### Run Hyperlane Agent with AWS KMS Configuration

Source: https://docs.hyperlane.xyz/docs/operate/relayer/run-relayer

Starts the Hyperlane Relayer agent using a Docker container, configured with AWS KMS for signing transactions. It requires AWS access key and secret as environment variables and specifies the relay chains and AWS signer details.

```docker
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:agents-v1.4.0 \
  ./relayer \
  --db /hyperlane_db \
  --relayChains <chain_1_name>,<chain_2_name> \
  --defaultSigner.type aws \
  --defaultSigner.id alias/hyperlane-relayer-1 \
  --defaultSigner.region us-east-1 \

```

--------------------------------

### Query Solana Program and Buffer Details

Source: https://docs.hyperlane.xyz/docs/guides/warp-routes/svm/svm-warp-route-guide

Commands to show details of deployed Solana programs and their associated buffers. These are useful for debugging deployment issues. Ensure you have the correct keypair and RPC URL.

```bash
solana program show --programs --keypair ./warp-route-deployer-key.json --url <CHAIN_RPC_URL>

solana program show --buffers --keypair ./warp-route-deployer-key.json --url <CHAIN_RPC_URL>
```

--------------------------------

### Configure S3 Bucket Policy for Hyperlane Validator

Source: https://docs.hyperlane.xyz/docs/operate/validators/validator-signatures-aws

This JSON policy grants public read access to objects within an S3 bucket and allows a specific IAM user to upload and delete objects. It requires the bucket's ARN and the IAM user's ARN for configuration.

```json
{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",
      "Principal": "*",
      "Action": ["s3:GetObject", "s3:ListBucket"],
      "Resource": ["${BUCKET_ARN}", "${BUCKET_ARN}/*"]
    },
    {
      "Effect": "Allow",
      "Principal": { "AWS": "${USER_ARN}" },
      "Action": ["s3:DeleteObject", "s3:PutObject"],
      "Resource": "${BUCKET_ARN}/*"
    }
  ]
}
```

--------------------------------

### Example Handle Function Implementation

Source: https://docs.hyperlane.xyz/docs/reference/messaging/receive

An example implementation of the 'handle' function that stores the last sender and message data, and emits a 'ReceivedMessage' event. It includes the 'onlyMailbox' modifier for access control.

```Solidity
function handle(
    uint32 _origin,
    bytes32 _sender,
    bytes calldata _messageBody
) external override onlyMailbox {
    lastSender = _sender;
    lastData = _messageBody;
    emit ReceivedMessage(_origin, _sender, _messageBody);
}
```

--------------------------------

### Install Hyperlane Registry Package (npm & yarn)

Source: https://docs.hyperlane.xyz/docs/reference/registries

Installs the Hyperlane registry package using either npm or yarn. This package provides access to chain metadata and contract addresses for interacting with Hyperlane contracts.

```shell
# With npm
npm install @hyperlane-xyz/registry
# Or with yarn
yarn add @hyperlane-xyz/registry
```

--------------------------------

### Solidity Example: Quoting and Sending a Message

Source: https://docs.hyperlane.xyz/docs/reference/messaging/send

Illustrates how to first quote the dispatch fee using `quoteDispatch` and then use that fee to execute the `dispatch` call. This ensures the correct amount is sent to cover all costs, preventing reverts due to underpayment. It shows querying the fee and then calling `dispatch` with the obtained value.

```solidity
// quote sending message from Ethereum to Polygon TestRecipient
IMailbox mailbox = IMailbox("0xc005dc82818d67AF737725bD4bf75435d065D239");
uint32 destination = 137;
bytes32 recipient = "0x000000000000000000000000f90cB82a76492614D07B82a7658917f3aC811Ac1";
bytes memory body = bytes("Hello World");
uint256 fee = mailbox.quoteDispatch(destination, recipient, body);
mailbox.dispatch{value: fee}(destination, recipient, body);
```

--------------------------------

### Example: Overriding Gas Limit with StandardHookMetadata

Source: https://docs.hyperlane.xyz/docs/protocol/core/post-dispatch-hooks-overview

An example of using the `StandardHookMetadata` library to override the gas limit for a dispatch call. It shows how to instantiate the Mailbox and call `dispatch` with custom metadata, passing a specific gas limit.

```solidity
// send message from originChain to destinationChain TestRecipient
IMailbox mailbox = IMailbox("mailboxAddress");
mailbox.dispatch{value: msg.value}(
  destinationDomain,
  "paddedRecipient", // Convert recipient address to padded bytes32 format
  bytes("messageBody"),
  StandardHookMetadata.overrideGasLimit(200000)
);
```

--------------------------------

### Example Whitelist Configuration for Hyperlane Relayer

Source: https://docs.hyperlane.xyz/docs/operate/relayer/message-filtering

An example JSON array representing a whitelist configuration for the Hyperlane Relayer. This configuration specifies rules for delivering messages based on sender, destination, and recipient addresses across different domains.

```json
[
  { "senderAddress": "*", "destinationDomain": ["1"], "recipientAddress": "*" },
  {
    "senderAddress": "0xca7f632e91B592178D83A70B404f398c0a51581F",
    "destinationDomain": ["42220", "43114"],
    "recipientAddress": "*"
  },
  {
    "senderAddress": "*",
    "destinationDomain": ["42161", "420"],
    "recipientAddress": "0xca7f632e91B592178D83A70B404f398c0a51581F"
  }
]

```

--------------------------------

### Build HWR Solana Programs

Source: https://docs.hyperlane.xyz/docs/guides/warp-routes/svm/svm-warp-route-guide

Compiles the Solana HWR programs using a specific version of the Solana CLI (1.14.20). The script automatically handles version switching to ensure compatibility and reverts to the previous version afterward. The compiled programs are found in the target/deploy directory.

```bash
# run from this directory
cd rust/sealevel/programs
# build the token programs
./build-programs.sh token
```

--------------------------------

### Deploy Hyperlane Core Contracts

Source: https://docs.hyperlane.xyz/docs/guides/chains/deploy-hyperlane

Deploys the configured Hyperlane core contracts to the specified chain. Users select their custom chain from a list. Compatibility with eth_getStorageAt() is noted as a potential issue for some chains.

```bash
hyperlane core deploy

```
Tokens:
Raw