Skip to main content
The Metalayer protocol is an upgradeable Hyperlane deployment operated by Caldera. It standardizes how intents (for intent-based routes), bridge operations, and arbitrary messages move between Metalayer-connected chains. This page documents the on-chain contracts and data structures developers interact with directly.

​
Core Components

  • MetalayerRouter (IMetalayerRouter): primary entry point for dispatching and receiving cross-chain messages. Maintains the router registry for every Metalayer domain and forwards deliveries to application contracts.
  • Metalayer ISMs: three Interchain Security Module (ISM) variants are deployed per domain. multisigIsm validates instant finality messages, multisigIsmFinalized waits for L1 finality, and espressoIsm is reserved for the Espresso restaking integration.
  • Interchain Gas Paymaster (IGP): default Hyperlane hook that collects source-chain gas payments and funds execution on the destination chain.
  • MetalayerMessage library: encodes message metadata, read operations, and finality flags. All router dispatches use this format.

​
Domains & Contract Addresses

Each supported blockchain is assigned a Metalayer domain ID. Router and ISM addresses are published in /metalayer/resources/contract-deployments. Applications should fetch addresses dynamically instead of inlining them.

​
Dispatch Lifecycle

  1. Quote the fee – call quoteDispatch with the destination domain, recipient, optional read operations, write calldata, desired FinalityState, and destination gas limit. The function returns the required source-chain payment.
  2. Dispatch – call dispatch with the same parameters and send the quoted fee as msg.value. The router stores the Metalayer message, emits MetalayerDispatch, and enqueues the payload in the Hyperlane mailbox.
  3. Relay & Verification – Metalayer validators relay the message. The destination router verifies the proof using the appropriate ISM (instant, finalized, or espresso) before invoking the recipient’s handle function.
  4. Read Results – if read operations were requested, the relayer includes their results in the delivery so the recipient contract can act on consistent cross-chain state.
import {IMetalayerRouter, ReadOperation} from "@metalayer/contracts/interfaces/IMetalayerRouter.sol";
import {FinalityState} from "@metalayer/contracts/lib/MetalayerMessage.sol";

IMetalayerRouter router = IMetalayerRouter(routerAddress);
ReadOperation[] memory reads;
uint256 fee = router.quoteDispatch(
  destinationDomain,
  recipient,
  reads,
  callData,
  FinalityState.INSTANT,
  500_000
);

router.dispatch{value: fee}(
  destinationDomain,
  recipient,
  reads,
  callData,
  FinalityState.INSTANT,
  500_000
);

​
Read Operations

ReadOperation requests the relayer to execute static calls on other chains before the destination write executes: 
struct ReadOperation {
  uint32 domain;   // chain domain to query
  address target;  // contract to call
  bytes callData;  // ABI-encoded function call
}
The destination recipient receives the original array alongside bytes[] readResults, ensuring writes can make decisions with fresh, cross-chain state.

​
Finality States

FinalityState is encoded in every Metalayer message:
  • INSTANT – rely on rollup sequencer commitments (default, ~10s latency).
  • FINALIZED – wait for L1 finality and dispute windows before delivery.
  • ESPRESSO – reserved for the upcoming Espresso-integrated security tier.
Select the finality tier that matches your protocol’s risk tolerance. The same dispatch/quote functions are used for all tiers; only the enum differs.

​
Roles & Governance

MetalayerRouter uses AccessControlDefaultAdminRulesUpgradeable with the following roles:
RolePurpose
DEFAULT_ADMIN_ROLEOwns upgrade and role management permissions. Held by Caldera multisig.
ISM_MANAGER_ROLEUpdates ISM addresses or switches finality policies.
ROUTER_MANAGER_ROLEManages the domain → router address mapping.
IGP_MANAGER_ROLESets or replaces the default interchain gas paymaster hook.
Applications never require these roles; integration is limited to dispatching messages and implementing the recipient interface.

​
Key Events

  • MetalayerDispatch(sender, destinationDomain, recipient, nonce) – emitted for every outbound message; useful for off-chain indexing.
  • RouterSet(chainId, router) – recorded whenever a domain mapping changes.
  • MetalayerIsmSet, MultisigIsmSet, EspressoIsmSet – governance events for ISM upgrades.

​
Upgrade Notes

  • Routers are deployed behind proxies and follow OpenZeppelin upgrade safety rules. Caldera publishes upgrade notices prior to any contract changes.
  • Downstream contracts should treat router addresses as immutable within a deployment epoch but always reference them via configuration, not constants, to accommodate upgrades or emergency rotations.
  • Gas payments and ISM configurations are chain-specific; fetch configuration from the SDK or JSON context files before submitting transactions.