L2ToL2CrossDomainMessenger
This guide walks through the CrossChainPingPong.sol contract, focusing on high level design and steps on integrating the L2ToL2CrossChainMessenger contract. The source code can be found here.
CrossChainPingPong.sol
L2ToL2CrossChainMessenger
receiveBall
msg.sender
CrossChainPingPong.sol implements a cross-chain ping-pong game using the L2ToL2CrossDomainMessenger.
sequenceDiagram + participant Chain1 as Chain 1 (First serve) + participant Chain2 as Chain 2 + + Note over Chain1: 🚀 Game Starts + Note over Chain1: 🏓 Serve Ball + Chain1->>Chain2: 📤 Send PingPongBall {rallyCount: 1, lastHitter: Chain1} + Chain1-->>Chain1: Emit BallSent event + activate Chain2 + Note over Chain2: 📥 Receive Ball + Chain2-->>Chain2: Emit BallReceived event + + Note over Chain2: 🏓 Hit Ball + Chain2->>Chain1: 📤 Send PingPongBall {rallyCount: 2, lastHitter: Chain2} + Chain2-->>Chain2: Emit BallSent event + deactivate Chain2 + activate Chain1 + Note over Chain1: 📥 Receive Ball + Chain1-->>Chain1: Emit BallReceived event + Note over Chain1: 🏓 Hit Ball + Chain1->>Chain2: 📤 Send PingPongBall {rallyCount: 3, lastHitter: Chain1} + Chain1-->>Chain1: Emit BallSent event + deactivate Chain1 + Note over Chain1,Chain2: Game continues... +
_allowedChainIds
_serverChainId
serveBallTo
PingPongBall
hitBallTo
Here's an explanation of the functions in the contract, with a focus on how it interacts with L2ToL2CrossChainMessenger.
constructor(uint256[] memory _allowedChainIds, uint256 _serverChainId) { + for (uint256 i = 0; i < _allowedChainIds.length; i++) { + _isChainIdAllowed[_allowedChainIds[i]] = true; + } + + if (!_isChainIdAllowed[_serverChainId]) { + revert InvalidDestinationChain(_serverChainId); + } + + SERVER_CHAIN_ID = _serverChainId; +} +
This constructor initializes the contract with two crucial pieces of information:
_isChainIdAllowed
SERVER_CHAIN_ID
The contract uses a simple mechanism to ensure the game starts correctly across all chains:
Designate the server chain:
if (SERVER_CHAIN_ID != block.chainid) { + revert UnauthorizedServer(block.chainid, SERVER_CHAIN_ID); +} +
Only the designated server chain can initiate the game.
Only be able to serve once
if (_hasServerAlreadyServed) { + revert BallAlreadyServed(); +} +_hasServerAlreadyServed = true; +
This ensures the ball is served only once, preventing multiple game initiations.
By using these checks in the serveBallTo function, the contract ensures that:
Because this contract is simple, it doesn't require complex time-based coordination or post-deployment setup. The game naturally begins when the server chain calls serveBallTo, and other chains join the game as they receive the ball.
While not explicitly mentioned in the code, this contract's design implicitly assumes the use of CREATE2 for deployment. Here's why CREATE2 is crucial for this setup:
Predictable Addresses: +CREATE2 enables deployment at the same address on all chains, crucial for cross-chain message verification:
if (IL2ToL2CrossDomainMessenger(MESSENGER).crossDomainMessageSender() != address(this)) { + revert InvalidCrossDomainSender(); +} +
Self-referential Messaging: +The contract sends messages to itself on other chains:
IL2ToL2CrossDomainMessenger(MESSENGER).sendMessage(_toChainId, address(this), _message); +
This requires address(this) to be consistent across chains.
address(this)
Initialization State Considerations: +The constructor parameters (_allowedChainIds and _serverChainId) affect the contract's initialization state. Different values will result in different contract addresses when using CREATE2. To maintain address consistency:
Without CREATE2, you would need to:
Two functions initiate a message send
serveBallTo: This function initiates the game by serving the ball from the designated server chain to another chain.
hitBallTo: This function is used to hit the ball to another chain after receiving it.
Both functions create a new PingPongBall struct with updated information and then call _sendCrossDomainMessage to transmit this ball data to the specified destination chain.
_sendCrossDomainMessage
Now, let's look at how _sendCrossDomainMessage works:
function _sendCrossDomainMessage(PingPongBall memory _ball, uint256 _toChainId) internal { + bytes memory _message = abi.encodeCall(this.receiveBall, (_ball)); + IL2ToL2CrossDomainMessenger(MESSENGER).sendMessage(_toChainId, address(this), _message); +} +
bytes memory _message = abi.encodeCall(this.receiveBall, (_ball)); +
_ball
sendMessage
_toChainId
CrossChainPingPong
_message
function receiveBall(PingPongBall memory _ball) external { + if (msg.sender != MESSENGER) { + revert CallerNotL2ToL2CrossDomainMessenger(); + } + + if (IL2ToL2CrossDomainMessenger(MESSENGER).crossDomainMessageSender() != address(this)) { + revert InvalidCrossDomainSender(); + } + + _receivedBall = _ball; + _isBallPresent = true; + + emit BallReceived(IL2ToL2CrossDomainMessenger(MESSENGER).crossDomainMessageSource(), block.chainid, _ball); +} +
if (msg.sender != MESSENGER) { + revert CallerNotL2ToL2CrossDomainMessenger(); + } +
if (IL2ToL2CrossDomainMessenger(MESSENGER).crossDomainMessageSender() != address(this)) { + revert InvalidCrossDomainSender(); + } +
_receivedBall = _ball; + _isBallPresent = true; + + emit BallReceived(IL2ToL2CrossDomainMessenger(MESSENGER).crossDomainMessageSource(), block.chainid, _ball); +
Updates the contract on this chain to keep the state of the ball and mark that it's present on this chain.
This is just one of many patterns to use the L2ToL2CrossDomainMessenger in your contract to power cross-chain calls. Key points to remember:
Simple Message Passing: This design sends simple messages between identical contracts on different chains. Each message contains only the essential game state (rally count, last hitter). More complex systems might involve multiple contracts, intermediary relayers.
Cross-Chain Sender Verification: Always verify the sender of cross-chain messages. This includes checking both the immediate caller (the messenger) and the original sender on the source chain.
Cross-Chain Contract Coordination: This design uses CREATE2 for consistent contract addresses across chains, simplifying cross-chain verification. Alternative approaches include:
'+(n?a:ro(a,!0))+`
"+(n?a:ro(a,!0))+`
+${this.parser.parse(e)}
${this.parser.parseInline(e)}
${e}
An error occurred:
"+ro(n.message+"",!0)+"
${i.tokens?.map(n).join("")}