> ## Documentation Index
> Fetch the complete documentation index at: https://docs.caldera.xyz/llms.txt
> Use this file to discover all available pages before exploring further.

# Metalayer Protocol

> Core protocol specifications and architecture

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`](../resources/contract-deployments.mdx). 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.

```solidity theme={null}
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:

```solidity theme={null}
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:

| Role                  | Purpose                                                                 |
| --------------------- | ----------------------------------------------------------------------- |
| `DEFAULT_ADMIN_ROLE`  | Owns upgrade and role management permissions. Held by Caldera multisig. |
| `ISM_MANAGER_ROLE`    | Updates ISM addresses or switches finality policies.                    |
| `ROUTER_MANAGER_ROLE` | Manages the domain → router address mapping.                            |
| `IGP_MANAGER_ROLE`    | Sets 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.