You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Interop is currently in active development and not yet ready for production use. The information provided here may change. Check back regularly for the most up-to-date information.
13
-
</Callout>
11
+
<InteropCallout />
14
12
15
-
This guide provides an overview of cross-chain message passing in the Superchain.
13
+
# Interop message passing overview
16
14
17
-
## Overview
15
+
The low-level [`CrossL2Inbox`](https://github.com/ethereum-optimism/optimism/blob/develop/packages/contracts-bedrock/src/L2/CrossL2Inbox.sol) contract handles basic message execution. It verifies whether an initiating message exists but does not check the message's destination, processing status, or other attributes.
18
16
19
-
The Superchain uses a pull-based event system for cross-chain communication. Messages are sent through the `L2ToL2CrossDomainMessenger` contract, which provides a secure and standardized way to pass information between chains.
17
+
The [`L2ToL2CrossDomainMessenger`](https://github.com/ethereum-optimism/optimism/blob/develop/packages/contracts-bedrock/src/L2/L2ToL2CrossDomainMessenger.sol) contract extends `CrossL2Inbox` by providing complete cross-domain messaging functionality.
20
18
21
-
## How it works
19
+
For high-level interoperability, both messages use the `L2ToL2CrossDomainMessenger` contract on their respective chains.
22
20
23
-
The following diagram illustrates how messages flow between chains through the `L2ToL2CrossDomainMessenger` contract, which acts as a bridge for cross-chain communication. When a contract on the source chain initiates a message, it's processed through several stages before reaching its destination, ensuring secure and reliable message delivery.
21
+
## Initiating message
24
22
25
23
```mermaid
24
+
26
25
sequenceDiagram
27
-
participant Source as Source Chain
28
-
participant Messenger as L2ToL2CrossDomainMessenger
29
-
participant Dest as Destination Chain
26
+
participant app as Application
27
+
box rgba(0,0,0,0.1) Source Chain
28
+
participant srcContract as Source Contract
29
+
participant srcXdom as L2ToL2CrossDomainMessenger
30
+
participant log as Event Log
31
+
end
32
+
app->>srcContract: 1. Send a message
33
+
srcContract->>srcXdom: 2. Call contract A<br/>in chainId B<br/>with calldata C
34
+
note over srcXdom: 3. Sanity checks
35
+
srcXdom->>log: 4. Log event SentMessage
30
36
31
-
Note over Source,Dest: Message Creation
32
-
Source->>Messenger: Emit message event
33
-
Note over Source,Dest: Message Serialization
34
-
Messenger-->>Messenger: Convert to standard format
35
-
Note over Source,Dest: Identifier Creation
36
-
Messenger-->>Messenger: Generate unique ID
37
-
Note over Source,Dest: Message Execution
38
-
Messenger->>Dest: Process message
39
37
```
40
38
41
-
Cross-chain messaging involves four main phases:
39
+
1. The application sends a transaction to a contract on the source chain.
40
+
41
+
2. The contract calls [`L2ToL2CrossDomainMessenger.SendMessage`](https://github.com/ethereum-optimism/optimism/blob/develop/packages/contracts-bedrock/src/L2/L2ToL2CrossDomainMessenger.sol#L127-L154).
42
+
The call requires these parameters:
43
+
44
+
*`_destination`: The chain ID of the destination blockchain.
45
+
*`_target`: The address of the contract on that blockchain.
46
+
*`_message`: The actual message.
47
+
This message is provided to `_target` as calldata, which means it includes a function selector and the parameters for that function call.
48
+
49
+
3.`L2ToL2CrossDomainMessenger` on the source chain verifies the message is legitimate:
50
+
* The destination chain is one to which this chain can send messages.
51
+
* The destination chain is *not* the source chain.
52
+
* The target is neither `CrossL2Inbox` nor `L2ToL2CrossDomainMessenger`.
53
+
54
+
4.`L2ToL2CrossDomainMessenger` emits a log entry.
55
+
In addition to the parameters, the log entry also includes:
42
56
43
-
1.**Message Creation**: The source chain contract emits an event containing the message data and destination information. This event serves as the initiating message that will be relayed across chains.
57
+
*`_nonce`: A [nonce](https://en.wikipedia.org/wiki/Cryptographic_nonce) value to ensure the message is only executed once.
44
58
45
-
2.**Message Serialization**: The messenger contract converts the event data into a standardized format that can be consistently processed across different chains in the Superchain.
59
+
*`_sender`: The contract that sent the cross domain message.
46
60
47
-
3.**Identifier Creation**: A unique identifier is generated for the message, containing information about its `origin`, `timestamp`, and other `metadata`. This identifier helps track and verify the message.
61
+
## Executing message
48
62
49
-
4.**Message Execution**: The destination chain receives and processes the message, executing any associated actions or state changes specified in the original message.
63
+
```mermaid
64
+
65
+
sequenceDiagram
66
+
participant app as Application
67
+
box rgba(0,0,0,0.1) Source Chain
68
+
participant log as Event Log
69
+
end
70
+
participant super as OP-Supervisor<br/>(destination chain<br/>node)
71
+
box rgba(0,0,0,0.1) Destination Chain
72
+
participant dstXdom as L2ToL2CrossDomainMessenger
73
+
participant Xinbox as CrossL2Inbox
74
+
participant dstContract as Destination Contract
75
+
end
76
+
log->>super: 1. Initiating message log event
77
+
app->>dstXdom: 2. Send an executing message
78
+
dstXdom->>Xinbox: 3. Verify the initiating message is real
79
+
note over dstXdom: 4. Sanity checks
80
+
dstXdom->>dstContract: 5. Call with provided calldata
81
+
```
50
82
51
-
For detailed implementation steps and code examples, see our [message passing implementation guide](https://supersim.pages.dev/guides/interop/viem).
83
+
1. Before the executing message is processed, the log event of the initiating message has to get to `op-proposer` on the destination chain.
52
84
53
-
## Common Use Cases
85
+
2. The application (or a contract calling on the application's behalf) calls [`L2ToL2CrossDomainMessenger.SendMessage.relayMessage`](https://github.com/ethereum-optimism/optimism/blob/develop/packages/contracts-bedrock/src/L2/L2ToL2CrossDomainMessenger.sol#L156-L216).
86
+
This call includes the message that was sent (`_sendMessage`), as well as the [fields required to find that message (`_id`)](https://github.com/ethereum-optimism/optimism/blob/develop/packages/contracts-bedrock/interfaces/L2/ICrossL2Inbox.sol#L4-L10).
54
87
55
-
* Simple messages between identical contracts
56
-
* Complex multi-contract interactions
57
-
* Cross-chain state synchronization
58
-
* Token transfers and bridging
88
+
3. The `L2ToL2CrossDomainMessenger` uses `CrossL2Inbox` to verify the message was sent from the source.
59
89
60
-
For a practical example, see our [cross-chain ping pong tutorial](https://supersim.pages.dev/guides/interop/cross-chain-contract-calls-pingpong).
90
+
4.`L2ToL2CrossDomainMessenger` on the destination chain verifies the message is legitimate:
91
+
92
+
* The origin (of the log entry) is `L2ToL2CrossDomainMessenger` on the other side.
93
+
* The destination chain ID is correct.
94
+
* The target is neither `CrossL2Inbox` nor `L2ToL2CrossDomainMessenger`.
95
+
* This message has not been relayed before.
96
+
This is the reason we need the nonce value, to enable us to send multiple messages that would be otherwise identical.
97
+
98
+
5. If everything checks out, `L2ToL2CrossDomainMessenger` calls the destination contract with the calldata provided in the message.
61
99
62
100
## Next steps
63
101
64
-
* Read about the [anatomy of a cross-chain message](/stack/interop/explainer#how-messages-get-from-one-chain-to-the-other)
65
-
* Try [Supersim](supersim) for testing cross-chain messages locally
66
-
* Learn about [manually relaying messages](https://supersim.pages.dev/guides/interop/viem?#viem-to-send-and-relay-interop-messages)
102
+
* Read how [messages get from one blockchain to another (`CrossL2Inbox`)](explainer#how-messages-get-from-one-chain-to-the-other).
103
+
* Try [Supersim](tools/supersim) for testing cross-chain messages locally.
104
+
* Learn about [manually relaying messages](https://supersim.pages.dev/guides/interop/viem?#viem-to-send-and-relay-interop-messages).
105
+
106
+
{/* After the tutorial for L2ToL2CrossDomainMessenger is written, need to add a link here */}
0 commit comments