Integrating with the Metalayer

​

Key Concepts

​

Domains

Each blockchain network is identified by a unique domain number in the Metalayer protocol. This domain identifier is used when specifying the destination chain for cross-chain messages.

​

Cross-Chain Operations

Metalayer supports two types of cross-chain operations:

• Writes: Send messages and execute functions across chains
• Reads: Query data from contracts on other chains

​

Message Components

• Destination Domain: The target blockchain network
• Recipient Address: The contract address that will receive the message
• Read Operations: Optional queries to execute on other chains
• Write Call Data: The function call to execute on the destination chain
• Finality Flag: Whether to wait for source chain finality before relay

​

Gas Abstraction

Metalayer handles cross-chain gas payments, allowing developers to pay for destination chain execution using the source chain’s native token.

​

System Architecture

​

Component Architecture

The diagram below shows the main components of the Metalayer system and how they interact:

​

Message Flow

The sequence diagram below illustrates the step-by-step process of sending a cross-chain message:

​

Integration Requirements

​

Source Chain

• Implement a protocol contract that calls the MetalayerRouter
• Calculate and include appropriate gas payment
• Properly encode message data and read operations

​

Destination Chain

• Implement the IMetalayerRecipient interface
• Handle incoming messages and read results
• Process cross-chain operations securely

​

Security Considerations

• The MetalayerRouter must be configured to be trusted on the destination chain. Do not allow the deliver function in your protocol to be called by any address other than the local MetalayerRouter.
• Consider finality requirements for your use case. If your contract needs to wait for finality on the source chain before processing a message, set the _useFinalized flag to true in the dispatch function. This significantly reduces the risk of a reorg in your contract.