Scroll's canonical bridge is more than a token transfer mechanism; it provides a general-purpose message-passing protocol that allows contracts on Ethereum L1 and Scroll L2 to communicate directly. The core primitives—sendMessage on one layer and relayMessage on the other—enable developers to build sophisticated cross-layer applications, from governance bridges and yield aggregators to custom oracle systems. Unlike simple asset transfers, arbitrary message passing requires careful handling of calldata encoding, gas specification, and failure modes to ensure reliable execution across the asynchronous boundary between layers.
Protocols
Canonical Bridge Message Passing: A Developer's Guide
Code-focused guide on sending arbitrary messages between L1 and L2 using Scroll's canonical bridge. Covers the sendMessage and relayMessage interface, calldata encoding, gas costs, and failure handling for cross-chain application developers.
introduction
CROSS-LAYER MESSAGING PRIMITIVES
Introduction
Understanding the canonical bridge's arbitrary message-passing interface is essential for any developer building cross-layer applications on Scroll.
The message-passing flow is inherently asynchronous and relies on Scroll's proving system for finality. A message initiated on L2 is not immediately executable on L1; it must wait for the batch containing the sending transaction to be committed and proven on L1, introducing a delay measured in hours. Conversely, messages from L1 to L2 are included in L2 blocks by the sequencer with lower latency. Developers must design their applications to accommodate these asymmetric latency profiles, implement replay protection, and handle scenarios where relayed messages fail on the destination chain. The xDomainCalldataGasLimit parameter is a critical but often misconfigured value that determines whether a cross-layer call succeeds or silently fails.
For teams building cross-chain protocols, governance systems, or complex DeFi applications on Scroll, a rigorous review of message-passing logic is a prerequisite for security. Chainscore Labs provides specialized audits of bridge message security, including calldata encoding validation, failure-handling correctness, and cross-layer integration testing, ensuring that your application's asynchronous communication is resilient against edge cases and adversarial conditions.
CANONICAL BRIDGE MESSAGE PASSING
Quick Facts
Key operational facts for developers integrating with the Scroll canonical bridge's arbitrary message-passing interface.
| Field | Value | Why it matters |
|---|---|---|
Core Functions | sendMessage (L1/L2) and relayMessageWithProof (L2) | Defines the exact interface for initiating and finalizing cross-layer messages; incorrect calldata encoding leads to permanent message failure. |
Message Finality | Soft confirmation on L2; final after batch proof is verified on L1 and challenge window passes | Integrators must not treat L2 soft confirmations as irreversible; premature crediting creates reorg and fraud-proof risk. |
Fee Model | L1->L2: L1 gas + calldata cost. L2->L1: L2 gas + L1 execution subsidy | Underestimating L1 data costs for L2->L1 messages can cause relay transactions to stall or fail. |
Failure Mode | Silent revert in relayMessageWithProof if proof or Merkle path is invalid | Failed relays do not emit a distinct error event; off-chain relayers must simulate and verify success to avoid stuck messages. |
Calldata Encoding | abi.encodeWithSignature for target + value + data; must match L1/L2 ABI | Mismatched encoding between initiating and receiving contracts is the most common cause of non-recoverable message failure. |
Relayer Dependency | Messages are not auto-executed; a relayer must call relayMessageWithProof | Application teams must run or incentivize a relayer; unrelayed messages are stuck until the proof is submitted. |
Security Model | Inherits full security of the canonical bridge and Scroll's zkEVM proofs | A bug in the bridge contract or prover circuit can invalidate all message-passing security; no independent trust assumptions exist. |
Integration Review | Chainscore Labs offers bridge message security review | Pre-deployment review of calldata encoding, relayer logic, and failure handling prevents unrecoverable fund loss. |
technical-context
CROSS-LAYER COMMUNICATION
Message-Passing Architecture
How Scroll's canonical bridge uses `sendMessage` and `relayMessage` to enable arbitrary cross-layer contract calls.
Scroll's canonical bridge is not just a token gateway; it is a general-purpose message-passing system that allows L1 contracts to call L2 contracts and vice versa. This architecture is the foundation for cross-chain application logic, enabling developers to build protocols where state changes on one layer trigger deterministic actions on the other. The core functions, sendMessage on the origin chain and relayMessageWithProof on the destination chain, form a trusted relay mechanism secured by the zkEVM's validity proofs.
For a developer, sending a message means calling the sendMessage function on the appropriate L1MessageQueue or L2MessageQueue contract, passing the target address, calldata, and a gas limit. The message is not executed immediately. On L1, it is enqueued and must be included in a batch proven by the zkEVM; on L2, it is enqueued and must be included in a finalization transaction on L1. The destination contract receives the call via an onScrollMessage callback, which it must implement to handle the arbitrary calldata. This asynchronous model means developers must design for latency measured in hours, not seconds, and handle failure cases where the destination call reverts due to insufficient gas or logic errors.
The operational risk model shifts from a 1-of-N validator honesty assumption to a 1-of-N prover liveness assumption. A message's security relies on the correctness of the zkEVM circuit, not an external validator set. However, the liveness of the system depends on a prover generating a validity proof for the batch containing the message. If the prover halts, messages are stuck. Integrators must monitor the MessageQueue contracts for their sent messages and understand the finality stages: soft confirmation on L2, batch inclusion, proof generation, and L1 finalization. A failure in the destination call does not revert the source transaction; it simply fails silently on the destination, requiring a replay or recovery mechanism.
Chainscore Labs reviews cross-layer message flows for security and liveness risks, auditing the calldata encoding, gas provisioning, and failure recovery logic in both the sending and receiving contracts. For teams building complex cross-chain applications, a formal review of the message-passing integration against Scroll's finality model is essential to prevent stuck funds or broken state synchronization.
CROSS-LAYER MESSAGE INTEGRATION
Affected Actors
Cross-Chain dApp Builders
Teams building cross-chain applications must handle the asynchronous nature of sendMessage and relayMessageWithProof. The primary integration risk is incorrect calldata encoding and failure to handle the mandatory 21-block finality delay on L1 before relay.
Action Items:
- Implement robust retry logic for
relayMessageWithProofcalls that may revert due to invalid proofs or gas constraints. - Ensure your L1 receiver contract correctly decodes the
_senderand_valuefrom the L2 transaction context to prevent cross-chain identity spoofing. - Test failure modes where the L2 transaction succeeds but the L1 relay fails; design a recovery path for users.
Chainscore Labs reviews cross-chain application logic for replay risks, message ordering assumptions, and failure recovery gaps.
implementation-impact
BRIDGE MESSAGE SECURITY
Implementation Impact Areas
Sending arbitrary messages through the canonical bridge introduces distinct security and operational considerations that differ from standard token transfers. Teams must address these areas to ensure reliable cross-layer execution.
01
Message Failure and Retry Logic
Unlike token transfers, arbitrary message relay on Scroll can fail silently on the destination layer if the target contract reverts. Developers must implement explicit failure handling in their relayMessage call, including gas limit specification and a retry mechanism. A failed message can permanently lock state on the source chain if not accounted for. Integrators should design idempotent message execution and monitor for failed relay transactions to trigger manual replays.
02
Calldata Encoding and Decoding Consistency
The sendMessage function passes raw calldata between layers. A mismatch between the ABI-encoded payload on L1 and the decoding logic in the L2 receiver contract is a common source of stuck messages. Teams must enforce strict, versioned encoding schemas and test with mainnet-equivalent calldata. A pre-deployment audit of the encoding/decoding path prevents silent logic errors that are difficult to recover from once a message is enqueued.
03
Cross-Layer Dependency Mapping
A dApp on Scroll may depend on state changes initiated by an L1 message. If the L1 transaction reorgs or the message relay is delayed past the challenge period, the L2 application state can become inconsistent. Developers must map all cross-layer dependencies and define acceptable finality thresholds. For high-value messages, waiting for L1 finality plus the Scroll challenge window is a critical safety control before releasing assets or updating state on L2.
04
Gas Accounting and Fee Volatility
The cost to relay a message on Scroll is paid by the relayer in L2 gas, which includes an L1 data fee component. During periods of high L1 blob or calldata costs, relay transactions can become economically unviable, delaying message execution. Application teams should monitor the l1BaseFee and design contracts that can gracefully handle extended delays without creating arbitrage opportunities or locked positions.
05
Permissioned Relayer Trust Model
In many canonical bridge designs, only a designated relayer address can call relayMessage with a valid Merkle proof. This creates a liveness dependency: if the relayer halts, all cross-layer messages are paused. Integrators must verify the relayer's operational status and decentralization roadmap. For mission-critical applications, understanding the relayer's failure mode and having a contingency plan is essential for risk management.
CANONICAL BRIDGE MESSAGE PASSING
Risk Matrix
Operational and security risks for developers sending arbitrary messages between L1 and L2 using Scroll's canonical bridge
| Risk | Failure mode | Severity | Mitigation |
|---|---|---|---|
Message replay | relayMessage called multiple times for the same L1-to-L2 message due to frontend or relayer logic error | High | Implement nonce-based replay protection in the receiving contract; verify canonical bridge enforces single execution per message hash |
Incorrect calldata encoding | Mismatch between sendMessage calldata and the receiving contract's expected function signature or parameter types | High | Use strict ABI encoding; perform integration tests on Scroll Sepolia with exact calldata payloads; Chainscore can audit cross-layer calldata paths |
L2-to-L1 message censorship | Sequencer or prover delays or drops L2-to-L1 messages before inclusion in a batch submitted to L1 | Medium | Monitor message inclusion windows; implement timeout fallbacks; do not rely on L2-to-L1 messages for time-critical liquidations |
Relayer liveness failure | Off-chain relayer responsible for calling relayMessage on the destination chain goes offline or runs out of gas funding | High | Run redundant relayers; monitor relayer balance and liveness; design applications to allow permissionless relay by any party |
Finality mismatch | Application treats L2 soft confirmation as final before the batch is proven and finalized on L1, leading to state rollback risk | Critical | Wait for L1 finality plus challenge period before treating cross-chain state as irreversible; reference Finality and Challenge Periods guide |
Bridge contract upgrade risk | Scroll governance or security council upgrades bridge contracts, potentially altering message format, fee structure, or execution guarantees | Medium | Monitor Scroll governance proposals and SIPs; implement upgrade pause mechanisms in dependent contracts; Chainscore provides governance monitoring |
Gas griefing on L2 | Attacker crafts L1-to-L2 messages with calldata that causes excessive L2 gas consumption, draining relayer funds or causing denial of service | Medium | Set gas limits on message execution; require message senders to prepay estimated L2 execution gas; audit receiving contract gas consumption |
Cross-layer reentrancy | L1-to-L2 message triggers callback to L1 before L2 state is settled, or L2-to-L1 message re-enters L2 contract during execution | Critical | Implement cross-layer reentrancy guards; follow checks-effects-interactions pattern across domains; Chainscore offers cross-layer security review |
CANONICAL BRIDGE MESSAGE PASSING
Developer Integration Checklist
A step-by-step verification checklist for developers integrating arbitrary message passing via Scroll's canonical bridge. Each item identifies a critical integration point, explains the risk of getting it wrong, and specifies the signal that confirms correct implementation.
What to check: Confirm that your L2 contract correctly identifies the originating L1 sender using the xDomainMessageSender context variable, not msg.sender.
Why it matters: The relayMessage function on L2 sets xDomainMessageSender to the L1 caller's address. Using msg.sender will incorrectly identify the bridge contract as the sender, breaking access control and enabling cross-layer impersonation attacks.
Readiness signal: Your L2 receiver contract uses require(msg.sender == MESSENGER_ADDRESS && xDomainMessageSender == EXPECTED_L1_CALLER) or the onlyFromCrossDomainAccount modifier pattern. Unit tests on testnet confirm that messages from unauthorized L1 addresses revert.
resource-links
SCROLL CANONICAL BRIDGE REFERENCES
Source Resources
Use these primary sources to verify Scroll canonical bridge message formats, deployed contracts, ABI encoding, and operational status before shipping cross-layer integrations.
Chains We Build On
Looking to build on a specific blockchain?
We build smart contracts, DeFi applications, wallets, tokenization platforms, and blockchain infrastructure across the major ecosystems teams choose today. That includes Ethereum, Arbitrum, Optimism, Polygon, Avalanche, Solana, Sui, Aptos, Hedera, Stellar, and NEAR, with support for additional EVM and non-EVM networks based on your product requirements.
EVM ecosystems
- Ethereum
- Arbitrum
- Optimism
- Polygon
- Avalanche
- Cronos
Non-EVM ecosystems
- Solana
- Sui
- Aptos
- Hedera
- Stellar
- NEAR
Additional ecosystems
- Polkadot
- Cosmos
- TON
- Cardano
- Algorand
- Tempo
Also available for Base, appchains, custom EVM networks, and cross-chain product architecture.
CANONICAL BRIDGE MESSAGE PASSING
Frequently Asked Questions
Common questions from developers integrating arbitrary message passing with Scroll's canonical bridge, covering calldata encoding, failure modes, and security boundaries.
sendMessage is the general-purpose function for passing arbitrary calldata from L1 to L2, while depositETH is a specialized wrapper that sends ETH alongside a message.
Key distinctions:
sendMessagedoes not transfer value; it only emits a message event that the bridge relayer picks up.depositETHcombines an ETH transfer with a message, requiring the L1 caller to sendmsg.value.- On the L2 side,
relayMessagehandles both, but the receiving contract must checkmsg.valueif it expects ETH.
Why it matters: Using the wrong function can result in lost ETH or messages that fail to relay. Always audit the value path when mixing ETH and arbitrary data.
Trusted by Industry Leaders
Delivering blockchain solutions for 5+ years.
We have partnered with 50+ leading DeFi protocols, NFT ecosystems, and fintech innovators to build secure, scalable, and capital-efficient blockchain products.
Selected Partners & Clients
“I've been working with Chainscore Labs for last 3+ years, they've consistently delivered with strong ownership across multiple projects. The team is reliable and detail-oriented.”
L
Lee Erswell
CEO, Telos Foundation
how to get started
How to get started?
If you're looking for blockchain integration, ChainScore Labs has 5+ years of experience helping teams build and integrate exchanges, wallets, smart contracts, tokenization solutions, and protocol-connected products, we can help you choose the right path, integrate securely, and get to production faster. Our team consists of experienced blockchain developers and architects who can help you with your blockchain integration needs.
01
Exploration & Strategy
Define your product goals and choose the right blockchain architecture for your use case.
02
Architecture & Design
Design the smart contracts, tokenomics, and security parameters of your system.
03
Development & Integration
Build and integrate with wallets, oracles, and front-end dApps for a seamless experience.
04
Security & Launch
Comprehensive audits followed by a risk-managed mainnet deployment to protect your users.
Explore More Solutions
Discover our
blockchain development services.
We build production-grade blockchain solutions for top-tier projects across DeFi and Web3.
Book a Call
Start a build
Need a blockchain engineering team?
Send the project context and we will respond with next steps, scope questions, and a practical path to delivery.