docs: annotate Mailbox deprecations and replacements#351
docs: annotate Mailbox deprecations and replacements#351cryptocake wants to merge 1 commit intovianetwork:mainfrom
Conversation
![gemini-code-assist[bot]](https://avatars.githubusercontent.com/in/956858?s=60&v=4){kind=small}
There was a problem hiding this comment.
Code Review
This pull request updates several documentation files to mark requestL2Transaction and finalizeEthWithdrawal as deprecated, recommending the use of Bridgehub.requestL2TransactionDirect and L1Nullifier.finalizeDeposit respectively. The review feedback suggests replacing links to a security contest repository with links to the official matter-labs/era-contracts repository for better consistency and reliability. Additionally, it is recommended to adjust the placement of a deprecation note in the smart contracts specification to ensure the technical explanation remains cohesive and readable.
| 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) |
There was a problem hiding this comment.
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).
| [`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) |
|
|
||
| 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) |
There was a problem hiding this comment.
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.
| [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) |
| 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. |
There was a problem hiding this comment.
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.
| 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`. |
|
Closing per author request. |
1 participant
Summary
Add explicit deprecation notes in docs for the two Mailbox methods announced in discussion #1147.
Changes
Updated docs to clearly mark legacy method references and point to replacements:
requestL2Transaction->Bridgehub.requestL2TransactionDirectfinalizeEthWithdrawal->L1Nullifier.finalizeDepositFiles:
docs/src/specs/l1_l2_communication/l1_to_l2.mddocs/src/specs/l1_smart_contracts.mddocs/src/guides/advanced/02_deposits.mddocs/src/guides/advanced/03_withdrawals.mdNotes
This PR is docs-only and keeps the existing historical explanations while adding migration guidance.
Linked issues