Skip to content

docs: annotate Mailbox deprecations and replacements #351

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

Closed
cryptocake wants to merge 1 commit into from
Closed

docs: annotate Mailbox deprecations and replacements #351

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
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
7 changes: 5 additions & 2 deletions docs/src/guides/advanced/02_deposits.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -103,8 +103,11 @@ Input: 0xeb672419000000000000000000000000618263ce921f7dd5f4f40c29f6c524aaf97b9bb
```

The deposit command has called the contract on address `0xa6B` (which is exactly the `CONTRACTS_DIAMOND_PROXY_ADDR` from
`deployL1.log`), and it has called the method `0xeb672419` - which is the `requestL2Transaction` from
[Mailbox.sol](https://github.com/matter-labs/era-contracts/blob/f06a58360a2b8e7129f64413998767ac169d1efd/ethereum/contracts/zksync/facets/Mailbox.sol#L220)
`deployL1.log`), and it has called the method `0xeb672419` - which is the legacy `requestL2Transaction` from
[Mailbox.sol](https://github.com/matter-labs/era-contracts/blob/f06a58360a2b8e7129f64413998767ac169d1efd/ethereum/contracts/zksync/facets/Mailbox.sol#L220).

Deprecation note: `requestL2Transaction` is deprecated. New integrations should use
`Bridgehub.requestL2TransactionDirect`.

#### Quick note on our L1 contracts

Expand Down
6 changes: 4 additions & 2 deletions docs/src/guides/advanced/03_withdrawals.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -139,8 +139,10 @@ about the withdrawal.

### Final step - finalizing withdrawal

Now we're ready to actually claim our ETH on L1. We do this by calling a `finalizeEthWithdrawal` function on the
DiamondProxy contract (Mailbox.sol to be exact).
Now we're ready to actually claim our ETH on L1.

Historically this was done by calling `finalizeEthWithdrawal` on the DiamondProxy (Mailbox). Deprecation note:
`finalizeEthWithdrawal` is deprecated; new integrations should use `L1Nullifier.finalizeDeposit`.

To prove that we actually can withdraw the money, we have to say in which L2 block the withdrawal happened, and provide
the merkle proof from our withdrawal log, to the root that is stored in the L1 contract.
13 changes: 9 additions & 4 deletions docs/src/specs/l1_l2_communication/l1_to_l2.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -18,10 +18,15 @@ between system and user logs.

### Initiation

A new priority operation can be appended by calling the
[requestL2Transaction](https://github.com/code-423n4/2023-10-zksync/blob/ef99273a8fdb19f5912ca38ba46d6bd02071363d/code/contracts/ethereum/contracts/zksync/facets/Mailbox.sol#L236)
method on L1. This method will perform several checks for the transaction, making sure that it is processable and
provides enough fee to compensate the operator for this transaction. Then, this transaction will be
Historically, a new priority operation was appended by calling
[`requestL2Transaction`](https://github.com/code-423n4/2023-10-zksync/blob/ef99273a8fdb19f5912ca38ba46d6bd02071363d/code/contracts/ethereum/contracts/zksync/facets/Mailbox.sol#L236)
Copy link
Copy Markdown

@gemini-code-assist gemini-code-assist bot Apr 1, 2026

Choose a reason for hiding this comment

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

medium

The documentation currently links to a security contest repository (code-423n4/2023-10-zksync). For official specifications, it is recommended to link to the primary matter-labs/era-contracts repository to ensure consistency and reliability, as seen in other parts of the documentation (e.g., docs/src/guides/advanced/02_deposits.md).

Suggested change
[`requestL2Transaction`](https://github.com/code-423n4/2023-10-zksync/blob/ef99273a8fdb19f5912ca38ba46d6bd02071363d/code/contracts/ethereum/contracts/zksync/facets/Mailbox.sol#L236)
[`requestL2Transaction`](https://github.com/matter-labs/era-contracts/blob/f06a58360a2b8e7129f64413998767ac169d1efd/ethereum/contracts/zksync/facets/Mailbox.sol#L220)

on Mailbox.

Deprecation note: `requestL2Transaction` is deprecated. New integrations should use
`Bridgehub.requestL2TransactionDirect`.

This flow performs several checks for the transaction, making sure that it is processable and provides enough fee to
compensate the operator. Then, this transaction is
[appended](https://github.com/code-423n4/2023-10-zksync/blob/ef99273a8fdb19f5912ca38ba46d6bd02071363d/code/contracts/ethereum/contracts/zksync/facets/Mailbox.sol#L369C1-L369C1)
Copy link
Copy Markdown

@gemini-code-assist gemini-code-assist bot Apr 1, 2026

Choose a reason for hiding this comment

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

medium

This link should also be updated to point to the official matter-labs/era-contracts repository for consistency and to avoid relying on a contest snapshot.

Suggested change
[appended](https://github.com/code-423n4/2023-10-zksync/blob/ef99273a8fdb19f5912ca38ba46d6bd02071363d/code/contracts/ethereum/contracts/zksync/facets/Mailbox.sol#L369C1-L369C1)
[appended](https://github.com/matter-labs/era-contracts/blob/f06a58360a2b8e7129f64413998767ac169d1efd/ethereum/contracts/zksync/facets/Mailbox.sol#L369)

to the priority queue.

Expand Down
9 changes: 6 additions & 3 deletions docs/src/specs/l1_smart_contracts.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -101,9 +101,12 @@ applying address aliasing leaves room for future EVM compatibility.

The L1 -> L2 communication is also used for bridging ether. The user should include a `msg.value` when initiating a
transaction request on the L1 contract. Before executing a transaction on L2, the specified address will be credited
with the funds. To withdraw funds user should call `withdraw` function on the `L2EtherToken` system contracts. This will
burn the funds on L2, allowing the user to reclaim them through the `finalizeEthWithdrawal` function on the
`MailboxFacet`.
with the funds. To withdraw funds user should call `withdraw` function on the `L2EtherToken` system contracts.

Deprecation note: `finalizeEthWithdrawal` on `MailboxFacet` is deprecated. The replacement flow is
`L1Nullifier.finalizeDeposit`.

This will burn the funds on L2, allowing the user to reclaim them on L1 through the finalize flow.
Comment on lines +104 to +109
Copy link
Copy Markdown

@gemini-code-assist gemini-code-assist bot Apr 1, 2026

Choose a reason for hiding this comment

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

medium

The insertion of the deprecation note breaks the logical connection between the withdraw function call and the explanation of its effects ("This will burn the funds..."). It is better to keep the process description continuous and place the deprecation note as a separate paragraph afterwards to maintain readability.

Suggested change
with the funds. To withdraw funds user should call `withdraw` function on the `L2EtherToken` system contracts.
Deprecation note: `finalizeEthWithdrawal` on `MailboxFacet` is deprecated. The replacement flow is
`L1Nullifier.finalizeDeposit`.
This will burn the funds on L2, allowing the user to reclaim them on L1 through the finalize flow.
with the funds. To withdraw funds user should call `withdraw` function on the `L2EtherToken` system contracts. This will burn the funds on L2, allowing the user to reclaim them on L1 through the finalize flow.\n\nDeprecation note: `finalizeEthWithdrawal` on `MailboxFacet` is deprecated. The replacement flow is `L1Nullifier.finalizeDeposit`.


More about L1->L2 operations can be found
[here](https://github.com/code-423n4/2023-10-zksync/blob/main/docs/Smart%20contract%20Section/Handling%20L1→L2%20ops%20on%20zkSync.md).
Expand Down
Loading