How hyperlane-xyz/hyperlane-monorepo works
1. This is a multi-language protocol monorepo, not a single app.
Hyperlane v3 is an interchain messaging system. The repo is split into four major runtime surfaces: Solidity contracts, Rust agents, TypeScript SDK/ops tooling, and chain-specific program crates for non-EVM ecosystems. The architecture is centered on moving messages and token state across chains, with shared config and deployment tooling tying everything together.
2. The on-chain core is the protocol boundary.
The Solidity workspace contains the main protocol contracts for EVM-style chains: Mailbox, hooks, ISMs, interchain gas payment, validator announce, and warp-route token contracts. These contracts are the canonical source of truth for dispatching messages, verifying remote messages, and handling token bridge flows. Similar contract/program implementations exist for Tron, Starknet, Cosmos, Solana/Sealevel, Radix, Aleo, Fuel, and others via their respective chain packages.
3. Off-chain agents provide the protocol’s operational layer.
The Rust agents workspace contains the long-running services that observe chains and submit transactions:
- scraper indexes on-chain events into a database
- relayer reconstructs message context and submits deliveries
- validator observes checkpoints / Merkle data and publishes validator attestations
These agents are the main off-chain executors that turn on-chain state transitions into cross-chain delivery actions.
4. Message flow is event-driven: dispatch → index → relay → deliver.
A sender dispatches a message on an origin chain through a mailbox. The scraper indexes dispatches, deliveries, gas payments, and related metadata into persistent storage. The relayer reads that indexed state, fetches any required proofs / metadata from chain-specific providers, then submits the message on the destination chain. The destination mailbox and ISM verify the message before it is processed by the recipient application.
5. Validators and Merkle state are a separate trust/attestation lane.
The validator subsystem tracks checkpoints and Merkle tree insertions, and the repo includes tooling and server endpoints around proof generation and insertion queries. This supports the protocol’s authentication path: validators announce state, relayers assemble proofs, and destination chains verify them via ISMs.
6. Warp routes are the token-bridge specialization of the same protocol.
“Warp” is Hyperlane’s token transfer layer. The repo has dedicated token modules, route readers/writers, and deployment/config logic for native, collateral, synthetic, and cross-collateral flows. Warp route state depends on the same core primitives as messaging—mailbox, gas payment, ISM, validator announce—but adds token-specific balance, fee, and rebalancing behavior.
7. The TypeScript SDK family is the control plane for deployments and chain integration.
The typescript/sdk family and chain-specific SDKs expose reusable abstractions for reading, deploying, and interacting with Hyperlane modules. These packages adapt the same protocol concepts to different chains and execution models. They are used by CLIs, infra scripts, deployment flows, tests, and application code to generate artifacts, build transactions, and resolve chain metadata.
8. The CLI and deployment tooling are the human/operator interface.
typescript/cli and typescript/infra provide command-line workflows for deploying core contracts, ISMs, hooks, warp routes, validators, and relayer configs. They also cover reading state, submitting governance changes, generating configs, and performing checks. These tools consume the shared config model and emit chain-specific deployment actions.
9. Infrastructure is config-driven and environment-specific.
The repo includes extensive environment definitions, Helm charts, Terraform, and external-secret integration. This layer defines how agents and services are deployed to Kubernetes, how secrets and RPC URLs are supplied, and how chain/route/validator inventories differ between testnet and mainnet. In practice, infra is the bridge between protocol code and production operations.
10. Monitoring and observability are first-class subsystems.
Metrics are implemented across Rust and TypeScript packages and exported to Prometheus/Grafana. There are dedicated services for fee quoting, HTTP registry, warp monitoring, and CCIP-related server functionality. These are not just ancillary utilities; they are part of the operational feedback loop used to detect liveness, balance health, relayer state, and deployment correctness.
11. Persistent state is split by responsibility.
The scraper uses a relational database with migrations for canonical indexed protocol data. Agents also use local durable state and caches for runtime coordination and recovery. This separation matters architecturally: indexed protocol history lives in the scraper DB, while agent-local runtime state supports retry, nonce management, and submission orchestration.
12. The repo is intentionally chain-abstracted but chain-specialized at the edges.
Shared Hyperlane concepts live in common crates/packages: message types, metadata builders, provider abstractions, and protocol traits. Each chain family then implements adapters for its own RPC model, signing model, transaction format, and account layout. That means the diagram should show a shared protocol core in the middle, with per-chain adapter layers fanning out to EVM, Cosmos, Solana/Sealevel, Starknet, Tron, Aleo, Radix, Fuel, and others.
13. Tests and fixtures validate both protocol semantics and chain-specific behavior.
The repository is heavily fixture-driven, with end-to-end suites across chain families plus mock responses and local environments. This indicates the architecture relies on realistic chain emulation and deployment harnesses, not just unit tests. For a diagram, that means test/harness infrastructure should be shown as a parallel validation plane alongside the production runtime.
Main entry points: hyperlane-core Core types · contracts Core contracts · main Agents workspace · sdk SDK family
Components 22
Solidity protocol
EVM-facing on-chain contracts and token bridge modules.
- Core contracts · Mailbox, hooks, ISMs, IGP, and validator announce for EVM chains.
solidity/contracts - Warp token contracts · Token bridge specialization built on the core messaging primitives.
solidity/contracts/token - Protocol interfaces · Shared contract and interface surface used by SDKs and chain adapters.
solidity/contracts/interfaces
Rust runtime
Long-running agents and chain adapters in Rust.
- Agents workspace · Top-level Rust workspace for protocol agents and shared runtime crates.
rust/main - Scraper · Indexes chain events into relational storage for downstream consumers.
rust/main/agents/scraper - Relayer · Builds message context, proofs, and submits cross-chain deliveries.
rust/main/agents/relayer - Validator · Observes checkpoints and publishes validator attestations and queries.
rust/main/agents/validator - Base runtime · Shared agent/server/settings/cache foundations used across Rust binaries.
rust/main/hyperlane-base - Core types · Shared protocol types, Merkle/accumulator logic, RPC traits, and config primitives.
rust/main/hyperlane-core - EVM adapter · Ethereum/EVM contract bindings, RPC clients, signers, and tx submission.
rust/main/chains/hyperlane-ethereum - Cosmos adapter · CosmWasm and native Cosmos implementations for mailbox, ISM, and IGP.
rust/main/chains/hyperlane-cosmos - Sealevel adapter · Solana/SVM chain support, indexers, providers, and transaction plumbing.
rust/main/chains/hyperlane-sealevel
TypeScript control plane
SDKs, CLIs, deployment tooling, and operator services.
- SDK family · Protocol clients, adapters, signers, providers, and deployment abstractions.
typescript/sdk - CLI · Human-facing workflows for deploy, read, check, relay, and warp operations.
typescript/cli - Infra · Environment config, deployment scripts, Helm, secrets, funding, and governance tooling.
typescript/infra - Operator services · Fee quoting, registry, CCIP server, relayer tooling, and monitoring services.
typescript/fee-quoting - Rebalancer · Inventory balancing orchestration, strategy selection, and bridge execution.
typescript/rebalancer - Metrics stack · Shared metrics, warp monitoring, key funding, and dashboards.
typescript/metrics
Sealevel programs
Solana/SVM programs, clients, and environments.
Infra and observability
Deployment, configuration, monitoring, and environment management.
- Environments · Chain inventories, validator sets, warp routes, and deployment environments.
typescript/infra/config/environments - Monitoring infra · Helm charts and dashboards for agents, fee quoting, warp monitoring, and registry services.
typescript/infra/helm
Connections 29
- Core contracts → Protocol interfaces: exposes · Core contracts define the canonical protocol ABI surface.
- Core contracts → Warp token contracts: primitives for · Warp routes reuse mailbox, ISM, and gas payment primitives.
- Agents workspace → Base runtime: uses · Agents share the common runtime, settings, server, and cache foundations.
- Agents workspace → Scraper: contains · The scraper is the indexing and persistence surface.
- Agents workspace → Relayer: contains · The relayer is the delivery orchestration surface.
- Agents workspace → Validator: contains · The validator is the attestation surface.
- Relayer → Core types: depends on · Relaying depends on shared message, proof, and Merkle primitives.
- Scraper → Core types: indexes via · Scraper models protocol data with shared core types.
- Validator → Core types: attests via · Validator checkpoint and Merkle handling uses shared core primitives.
- EVM adapter → Core types: implements · EVM chain support is built on the shared protocol core.
- Cosmos adapter → Core types: implements · Cosmos and CosmWasm chain support is built on the shared protocol core.
- Sealevel adapter → Core types: implements · SVM chain support is built on the shared protocol core.
- SDK family → Protocol interfaces: binds · SDKs read and write protocol contracts through generated bindings and readers.
- SDK family → Core types: shares types · SDKs mirror protocol concepts, messages, and metadata across runtimes.
- CLI → SDK family: uses · CLI workflows are composed from SDK deployment and interaction abstractions.
- Infra → CLI: drives · Infra scripts invoke CLI-like deployment and validation workflows.
- Infra → Environments: loads · Operational behavior is driven by environment-specific config inventories.
- Operator services → SDK family: uses · Services rely on SDK primitives for chain access and protocol operations.
- Rebalancer → SDK family: uses · Rebalancing logic uses SDKs for chain reads, bridge actions, and token abstractions.
- Metrics stack → Operator services: observes · Metrics and dashboards cover operator services and their liveness.
- Programs → SVM SDK: served by · Programs are deployed and interacted with through the SVM SDK.
- SVM SDK → CLI: integrates with · CLI supports SVM-specific deployment, read, and warp workflows through the SDK.
- Monitoring infra → Metrics stack: deploys · Helm and observability templates deploy metrics and monitoring services.
- Environments → Core contracts: configures · Environment inventories point at chain deployments and owners.
- Environments → Agents workspace: configures · Agent environments define runtime settings, RPCs, and inventories.
- Environments → Programs: configures · Sealevel environments define program IDs, warp routes, and validator settings.
- Core contracts → Relayer: verifies messages for · Destination-side contracts verify the messages relayed by off-chain agents.
- Core contracts → Validator: consumes attestations from · Core verification paths consume validator announcements and checkpoint data.
- Warp token contracts → Rebalancer: token flows for · Warp routes feed inventory management and rebalancing workflows.