Skip to content

Updating the cross domain messenger overview #1663

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Draft
wants to merge 3 commits into
base: main
Choose a base branch
from
Draft

Updating the cross domain messenger overview #1663

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
f37f7c4
initial draft
sbvegan Jun 13, 2025
6a9c431
Auto-fix: Update breadcrumbs, spelling dictionary and other automated…
sbvegan Jun 13, 2025
18ffe91
referencing the specs instead
sbvegan Jun 13, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
4 changes: 2 additions & 2 deletions pages/stack/transactions/_meta.json
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -2,8 +2,8 @@
"fees": "Transaction fees",
"transaction-flow": "Transaction flow",
"transaction-finality" : "Transaction finality",
"cross-domain": "Cross domain transaction",
"deposit-flow": "Deposit flow",
"withdrawal-flow": "Withdrawal flow",
"forced-transaction": "Forced transaction",
"cross-domain": "Cross domain transaction"
"forced-transaction": "Forced transaction"
}
44 changes: 22 additions & 22 deletions pages/stack/transactions/cross-domain.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,14 +1,14 @@
---
title: Cross-Domain Overview
description: >-
An overview of the lifecycle of an OP Stack cross-chain transaction, detailing
An overview of the lifecycle of an OP Stack cross-domain transaction, detailing
the flow of transactions between Layer 2 and Layer 1.
lang: en-US
content_type: guide
content_type: reference
topic: cross-domain-overview
personas:
- protocol-developer
- chain-operator
- app-operator
categories:
- protocol
- cross-domain-messaging
Expand All @@ -27,53 +27,53 @@ import { Callout, Steps } from 'nextra/components'

This overview provides a detailed walkthrough of the lifecycle of cross-chain transactions, covering deposits, withdrawals, and transaction flows between L1 and L2. The diagram below illustrates the main components and steps involved.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

⚠️ Potential issue

Inconsistent terminology: “cross-chain” should be “cross-domain.”

The body still reads “lifecycle of cross-chain transactions.” Update this to “cross-domain transactions” to match the page title and frontmatter.

🤖 Prompt for AI Agents 
In pages/stack/transactions/cross-domain.mdx at line 28, the term "cross-chain
transactions" is used inconsistently with the page title and frontmatter which
use "cross-domain transactions." Update the phrase to "lifecycle of cross-domain
transactions" to ensure consistent terminology throughout the document.


![Lifecycle of an OP Stack Crosschain Transaction.](/img/op-stack/protocol/op-cross-chain-txn.jpeg)
_Figure 1: The Lifecycle of an OP Stack Crosschain Transaction_

Cross-domain communication in the OP Stack involves moving assets and messages between L1 and L2. Key components, such as bridges, messengers, and portals, ensure these transactions are executed securely and transparently. This page breaks down the lifecycle of a cross-chain transaction into three main flows: Deposit Flow, Transaction Flow (Tx Flow), and Withdrawal Flow.

## Deposit Flow

Depositing assets from L1 to L2 follows a structured process that ensures funds are securely transferred and credited to the user's L2 account. The steps are as follows:

1. **User Initiation (L1 Standard Bridge):**
The user initiates a deposit by sending assets (e.g., ETH or tokens) to the L1 Standard Bridge contract. This contract receives the assets and prepares a message to relay to L2.
The user initiates a deposit by sending assets (e.g., ETH or tokens) to the L1 Standard Bridge contract. This contract receives the assets and prepares a message to relay to L2.

2. **Message Relaying (L1 CrossDomain Messenger):**
The L1 Standard Bridge sends a message to the L1 CrossDomain Messenger, which is responsible for handling inter-layer communication. The messenger emits a `TransactionDeposited` event to signal the start of the deposit process.
The L1 Standard Bridge sends a message to the L1 CrossDomain Messenger, which is responsible for handling inter-layer communication. The messenger emits a `TransactionDeposited` event to signal the start of the deposit process.

3. **Processing on L2 (OptimismPortal):**
The message is received by the OptimismPortal on L2. Here, the deposited assets are held securely until the transaction is finalized. The portal initiates the deposit transaction, updating the user's balance on L2.
The message is received by the OptimismPortal. Here, the deposited assets are held securely until the transaction is finalized. The portal initiates the deposit transaction, updating the user's balance on L2.

4. **Finalization (L2 CrossDomain Messenger):**
The L2 CrossDomain Messenger processes the deposit by updating the user's account balance, and making the assets available for use on L2.
The L2 CrossDomain Messenger processes the deposit deriving the message from L1 into the L2. If this is a deposit of ETH or a token the user's account balance will be reflected in their account making the assets available for use on L2.

For a more detailed breakdown of the deposit process, refer to the [deposit](https://specs.optimism.io/protocol/deposits.html) specs.

## Transaction (Tx) Flow

The transaction flow covers the steps involved in cross-domain message passing and state updates between L1 and L2:

1. **Message Queuing (L2ToL1MessagePasser):**
During cross-layer communication, certain messages are queued for processing. The `L2ToL1MessagePasser` prepares these messages for state updates or withdrawals, ensuring they are available for proving and relaying.
During cross-layer communication, certain messages are queued for processing. The `L2ToL1MessagePasser` prepares these messages for state updates or withdrawals, ensuring they are available for proving and relaying.

2. **State Reading and Proving (L2OutputOracle):**
The `L2OutputOracle` plays a critical role in validating state changes between L1 and L2. It reads the current state and submits a proposal using `proposeL2Output()`. This proposal includes information about queued messages or state changes that need to be relayed to L1.
2. **State Reading and Proving (DisputeGameFactory and OptimismPortal):**
The `DisputeGameFactory` and `OptimismPortal` play a critical role in validating L2 state changes on L1. New state proposals are created when someone creates a new dispute game through the `DisputeGameFactory`. This proposal includes information about queued messages or state changes that need to be relayed to L1. Users can prove their withdrawals through the `OptimismPortal` and then finalize on the `OptimismPortal` once the challenge period has passed.

3. **Message Relay (CrossDomain Messengers):**
Messages are relayed between the L1 and L2 CrossDomain Messengers as part of transaction execution. This includes updating state or finalizing transactions on the target layer.

Messages are relayed between the L1 and L2 CrossDomain Messengers as part of transaction execution. This includes updating state or finalizing transactions on the target layer.

## Withdrawal Flow

Withdrawing assets from L2 back to L1 involves a multi-step process to ensure the transaction is validated and executed correctly:

1. **User Initiation (L2 Standard Bridge):**
The withdrawal process starts when the user calls the `withdraw()` function on the L2 Standard Bridge, specifying the amount and asset to be withdrawn.
1. **User Initiation:**
The withdrawal process starts when the user calls the `withdraw()` function on the L2 Standard Bridge, specifying the amount and asset to be withdrawn.

2. **Message Relay (L2 CrossDomain Messenger):**
The L2 CrossDomain Messenger receives the withdrawal request and relays the message for processing. It may involve queuing the message in the `L2ToL1MessagePasser` for further steps.
2. **Message Relay:**
The L2 CrossDomain Messenger receives the withdrawal request and relays the message for processing. It may involve queuing the message in the `L2ToL1MessagePasser` for further steps.

3. **Proving and Finalization (L2OutputOracle):**
The withdrawal message is proven using the `L2OutputOracle`, which submits a state output proving that the withdrawal is legitimate. This step involves reading the state and generating the required proofs during the proving time.
3. **Proving:**
The withdrawal message is proven using the `DisputeGameFactory` and `OptimismPortal`. New state outputs are created as dispute games through the `DisputeGameFactory`. The `OptimismPortal` references those dispute games. The user proves the withdrawal on the `OptimismPortal`. This step involves reading the state and generating the required proofs during the proving time.

4. **Finalization (L1 CrossDomain Messenger and L1 Standard Bridge):**
Once the withdrawal is proven, the message is finalized by the L1 CrossDomain Messenger. The L1 Standard Bridge completes the process by releasing the withdrawn assets to the user's L1 account.
Once the withdrawal is proven, the user waits for the challenge period to pass. Then they finalize it on the `OptimismPortal` and the message is finalized by the L1 CrossDomain Messenger. The L1 Standard Bridge completes the process by releasing the withdrawn assets to the user's L1 account.

For a more detailed breakdown of the withdrawal process, refer to the [withdrawal](https://specs.optimism.io/protocol/withdrawals.html) specs.
4 changes: 4 additions & 0 deletions pages/stack/transactions/deposit-flow.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -31,6 +31,10 @@ This guide explains the deposit flow process for L2 deposit transactions, trigge
The process is somewhat similar to the way [most networking stacks work](https://en.wikipedia.org/wiki/Encapsulation_\(networking\)).
Information is encapsulated in lower layer packets on the sending side and then retrieved and used by those layers on the receiving side while going up the stack to the receiving application.

<Callout type="info">
If the sequencer is down, deposits will still be processed through [forced inclusion](/stack/transactions/forced-transaction).
</Callout>

![Deposit Flow Diagram.](/img/op-stack/protocol/deposit-flow-dark-mode.svg)

## L1 processing
Expand Down
4 changes: 2 additions & 2 deletions pages/stack/transactions/withdrawal-flow.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -38,7 +38,7 @@ Withdrawals require the user to submit three transactions:

## Withdrawal initiating transaction

1. On L2, a user, either an externally owned account (EOA) directly or a contract acting on behalf of an EOA, calls the [`sendMessage`](https://github.com/ethereum-optimism/optimism/blob/1a8fe18c4989bfd0852a8873f30422542ad4f44d/packages/contracts-bedrock/src/universal/CrossDomainMessenger.sol#L191) function of the [`L2CrossDomainMessenger`](https://github.com/ethereum-optimism/optimism/blob/1a8fe18c4989bfd0852a8873f30422542ad4f44d/packages/contracts-bedrock/src/L2/L2CrossDomainMessenger.sol#L21) contract.
1. On L2, a user, either an externally owned account (EOA) directly or a contract acting on behalf of an EOA, calls the [`sendMessage`](https://github.com/ethereum-optimism/optimism/blob/ef7a933ca7f3d27ac40406f87fea25e0c3ba2016/packages/contracts-bedrock/src/universal/CrossDomainMessenger.sol#L191) function of the [`L2CrossDomainMessenger`](https://github.com/ethereum-optimism/optimism/blob/ef7a933ca7f3d27ac40406f87fea25e0c3ba2016/packages/contracts-bedrock/src/L2/L2CrossDomainMessenger.sol#L21) contract.

This function accepts three parameters:

Expand All @@ -64,7 +64,7 @@ Withdrawals require the user to submit three transactions:

## Withdrawal proving transaction

Once an output root that includes the `MessagePassed` event is published to L1, the next step is to prove that the message hash really is in L2. Typically this is done by viem.
Once an output root that includes the `MessagePassed` event is published to L1, the next step is to prove that the message hash really is in L2. Typically this is abstracted away using tools like viem.

### Offchain processing

Expand Down
Binary file removed public/img/op-stack/protocol/op-cross-chain-txn.jpeg
View file
Open in desktop
Binary file not shown.
Loading