Hyperlane

Skill based on Hyperlane monorepo, generated from sources/hyperlane. Doc path: sources/hyperlane/AGENTS.md, sources/hyperlane/CLAUDE.md, sources/hyperlane/typescript/sdk/README.md, sources/hyperlane/typescript/cli/README.md, sources/hyperlane/typescript/relayer/README.md, and Solidity contracts under sources/hyperlane/solidity/contracts/.

Hyperlane is an interchain messaging protocol. Apps dispatch messages via the Mailbox on the origin chain; relayers index and deliver them to the destination chain. The stack includes Solidity core contracts (Mailbox, ISMs, hooks, Warp token routes), a TypeScript SDK and CLI, and Rust relayer/validator agents.

Core References

Features

CLI and deployment

Protocol features

Best Practices

Hyperlane Core Architecture

Hyperlane is an interchain messaging protocol. Applications dispatch messages from an origin chain; off-chain relayers index and deliver them to the destination chain. Use this when implementing or debugging cross-chain flows.

Message flow

1. Dispatch – App calls Mailbox.dispatch(destinationDomain, recipientAddress, messageBody) on the origin chain (optionally with hook metadata and custom hook). 2. Index – Relayer agents index Dispatch / DispatchId events. 3. Security – Relayer fetches verification metadata from validators / ISMs. 4. Delivery – Relayer calls Mailbox.process(metadata, message) on the destination chain. 5. Handle – Recipient contract's handle(origin, sender, message) is invoked by the Mailbox.

Domains

• Domain is the unique identifier for a chain (not EVM chain ID). Used in dispatch, process, and message fields.
• localDomain – The domain of the chain where the Mailbox is deployed (mailbox.localDomain()).

Message format

Messages are packed bytes used by the Mailbox and Message library:

• version (1 byte), nonce (4), origin (4), sender (32), destination (4), recipient (32), body (variable).
• Message.id(message) = keccak256(message).
• Use Message.sender(), Message.recipient(), Message.body(), etc. to parse. Use TypeCasts for bytes32 ↔ address.

Recipient interface

Contracts that receive interchain messages must implement:

interface IMessageRecipient {
    function handle(
        uint32 _origin,
        bytes32 _sender,
        bytes calldata _message
    ) external payable;
}

Only the Mailbox can call handle; enforce onlyMailbox (e.g. msg.sender == address(mailbox)) in your recipient.

Key types

<!-- Source references:

• sources/hyperlane/AGENTS.md (Architecture, Message Flow, Key Concepts)
• sources/hyperlane/solidity/contracts/interfaces/IMailbox.sol, IMessageRecipient.sol
• sources/hyperlane/solidity/contracts/libs/Message.sol

-->

Hyperlane SDK (TypeScript)

The SDK (@hyperlane-xyz/sdk) provides multi-chain provider management and core contract interactions for building and deploying interchain apps.

MultiProvider and ChainMap

• MultiProvider – Manages chain metadata and RPC providers for many chains. Use for reads/writes across chains.
• ChainMap&lt;T&gt; – Type-safe per-chain configuration (e.g. ChainMap<{ mailbox: string }>). Use for addresses and config, not for provider instances.

import { MultiProvider } from '@hyperlane-xyz/sdk';

const multiProvider = new MultiProvider(chainMetadata); // or from registry
const provider = multiProvider.getProvider(chainName);
const signer = multiProvider.getSignerOrProvider(chainName);

HyperlaneCore / MultiProtocolCore

• HyperlaneCore – Common interactions with core deployments (Mailbox, IGP, ISMs, etc.) on EVM chains.
• MultiProtocolCore – Unified interface across VMs (EVM, Cosmos, Sealevel, etc.) when working with multiple VMs.

import { HyperlaneCore } from '@hyperlane-xyz/sdk';

const core = HyperlaneCore.fromAddressesMap(addressesMap, multiProvider);
// Use core for contract instances, message verification, gas estimation, etc.

Apps and deployment

• HyperlaneApp / MultiProtocolApp – Base to extend for a multi-chain app (contract addresses, helpers).
• HyperlaneDeployer – Base for running multi-chain contract deployments (config-driven, per-chain deploy).

Token and Warp

• Token – Interact with existing Warp Route token contracts.
• WarpCore – Deploy and manage Warp Route deployments (canonical/collateral, config).

Multi-VM (AltVM)

For Cosmos, Sealevel, Starknet, Radix:

• @hyperlane-xyz/provider-sdk – Protocol-agnostic provider abstractions.
• @hyperlane-xyz/deploy-sdk – Deployment modules for all VM types.
• MultiProtocolProvider – Unified provider interface across VMs.

Prefer these when the app spans non-EVM chains; use MultiProtocolCore / MultiProtocolApp for core interactions.

Usage tips

• Import types and classes from @hyperlane-xyz/sdk instead of redefining.
• Chain metadata is often loaded from @hyperlane-xyz/registry; use .registryrc or env to point to registry version/path.
• Validate config at boundaries (e.g. Zod schemas); use assert() for invariants.

<!-- Source references:

• sources/hyperlane/AGENTS.md (TypeScript SDK, Multi-VM Package Structure)
• sources/hyperlane/typescript/sdk/README.md

-->

Hyperlane CLI

The Hyperlane CLI (@hyperlane-xyz/cli) is a TypeScript CLI for core and warp deployments and common operations. Use it for deploying to new chains and sending test messages.

Setup

• Node 18+.
• Install: npm install -g @hyperlane-xyz/cli or run via npx @hyperlane-xyz/cli / pnpm dlx @hyperlane-xyz/cli.
• From source: build from monorepo then pnpm hyperlane in typescript/cli.

Common commands

Use --help on subcommands (e.g. hyperlane core deploy --help, hyperlane warp deploy --help) for options and required config.

Logging

• Format: LOG_FORMAT=pretty|json or --log <pretty|json>.
• Verbosity: LOG_LEVEL or --verbosity <trace|debug|info|warn|error|off>.
• If colors don’t show, try FORCE_COLOR=true.

E2E tests (development)

CLI e2e tests run against local chains and agents:

pnpm -C typescript/cli test:ethereum:e2e
pnpm -C typescript/cli test:cosmosnative:e2e
pnpm -C typescript/cli test:radix:e2e

Use these to validate core and warp deploy flows.

<!-- Source references:

• sources/hyperlane/typescript/cli/README.md
• sources/hyperlane/AGENTS.md (CLI Development, E2E)

-->

ISMs and Hooks

ISMs verify incoming messages; hooks run post-dispatch (e.g. gas payment). Use when configuring security or gas for your app.

Interchain Security Modules (ISMs)

• Purpose: Pluggable verification for messages at Mailbox.process(). Relayer fetches metadata; Mailbox uses recipient’s ISM or defaultIsm.
• Recipient ISM: Set via recipientIsm(recipient); apps can set a custom ISM via MailboxClient’s setInterchainSecurityModule(module).
• Types: MultisigIsm (validator signatures), AggregationIsm (combine multiple ISMs), routing/fallback ISMs, CCIP-read, hook-based ISMs. Validator set and thresholds are configured on the ISM contracts.

When debugging delivery failures, check that the relayer can obtain valid metadata for the recipient’s ISM (e.g. validator checkpoints).

Post-dispatch hooks

• Required hook: Runs on every dispatch (e.g. MerkleTreeHook). Set at Mailbox as requiredHook.
• Default hook: Used when the sender doesn’t specify a custom hook (e.g. InterchainGasPaymaster). Set at Mailbox as defaultHook.
• Custom hook: Apps can pass a custom hook and metadata in dispatch(..., customHookMetadata, customHook) or set a default via MailboxClient’s setHook(hook).

Dispatch overloads

• dispatch(destinationDomain, recipientAddress, messageBody) – uses default hook and empty metadata.
• dispatch(destinationDomain, recipientAddress, body, defaultHookMetadata) – default hook with metadata (e.g. gas limit).
• dispatch(destinationDomain, recipientAddress, body, customHookMetadata, customHook) – full control.
• Use quoteDispatch(...) for the same overloads to get the fee before sending.

Gas payment

• InterchainGasPaymaster (IGP) is typically used as the default hook. Apps pay for destination gas when dispatching; hook metadata specifies gas limit (e.g. via StandardHookMetadata.overrideGasLimit(gas)).
• GasRouter in contracts uses destinationGas[domain] and quoteGasPayment(domain); Router base builds hook metadata accordingly.

<!-- Source references:

• sources/hyperlane/AGENTS.md (Core Contracts, Message Flow)
• sources/hyperlane/solidity/contracts/interfaces/IMailbox.sol, hooks/libs/StandardHookMetadata
• sources/hyperlane/solidity/contracts/client/GasRouter.sol

-->

Hyperlane Relayer

The relayer indexes dispatched messages and delivers them to destination chains. Use when building or operating relayers or when debugging message delivery.

Library usage (browser-safe)

import { HyperlaneRelayer } from '@hyperlane-xyz/relayer';
import { HyperlaneCore } from '@hyperlane-xyz/sdk';

const core = HyperlaneCore.fromAddressesMap(addresses, multiProvider);
const relayer = new HyperlaneRelayer({ core });

// Relay a single message (e.g. from dispatch tx)
await relayer.relayMessage(dispatchTx);

// Or run continuous relaying
relayer.start();

Node.js daemon (with filesystem)

import { RelayerService, loadConfig } from '@hyperlane-xyz/relayer/fs';

const relayerConfig = loadConfig('./config.yaml');
const service = await RelayerService.create(multiProvider, registry, {
  enableMetrics: true,
  relayerConfig,
});
await service.start();

CLI

hyperlane relayer --chains ethereum,arbitrum

Environment and config

Example YAML:

chains: [ethereum, arbitrum, optimism]
whitelist:
  ethereum: ['0x...']
  arbitrum: ['0x...']
retryTimeout: 1000
cacheFile: ./relayer-cache.json

Metrics

Prometheus metrics at http://localhost:9090/metrics (configurable): hyperlane_relayer_messages_total, hyperlane_relayer_retries_total, hyperlane_relayer_backlog_size, hyperlane_relayer_relay_duration_seconds, etc.

<!-- Source references:

• sources/hyperlane/typescript/relayer/README.md
• sources/hyperlane/AGENTS.md (Rust Agents – relayer)

-->

Warp Routes

Warp routes are token bridge deployments across Hyperlane-connected chains. Use the SDK’s WarpCore and Token utilities to deploy and interact with them.

Contract types

• HypERC20 – Canonical (mint/burn) ERC20 warp route.
• HypERC20Collateral – Collateral-backed: lock on origin, mint representation on destination (or lock on destination and burn on origin).
• HypNative – Wrapped native asset (e.g. WETH) as a warp route.
• HypERC721 / HypERC721Collateral – NFT bridges.
• Extensions: HypXERC20, HypERC4626Collateral, HypERC721URICollateral, etc. in token/extensions/.

Contracts live under solidity/contracts/token/; deployment and config are typically driven by the CLI and SDK (WarpCore).

SDK usage

• WarpCore – Deploy and manage Warp Route deployments (config-driven, per-chain).
• Token – Read/write existing Warp Route contracts (balances, transfer, admin).

Deploy via CLI: hyperlane deploy warp with the appropriate config (see hyperlane warp deploy --help).

Routing and ISMs

• Token routes use a router pattern; rate limiting or custom ISMs (e.g. RateLimitedIsm) may be used. See isms/warp-route/ and hooks/warp-route/ when configuring security or rate limits for warp routes.

<!-- Source references:

• sources/hyperlane/AGENTS.md (Core Contracts – token/*)
• sources/hyperlane/typescript/sdk/README.md (WarpCore, Token)
• sources/hyperlane/solidity/contracts/token/

-->