Preparing for Fault Proofs Breaking Changes
OP Labs has submitted a proposal to governance (opens in a new tab) to upgrade OP Mainnet to support Fault Proofs. If this proposal passes, fault proofs would launch on OP Mainnet approximately June 2024. This document details changes that apply to users, bridges, and centralized exchanges, as well as any custom solutions that use withdrawals. This page outlines changes for OP Mainnet and OP Sepolia only. Details for other OP Chains are forthcoming.
If you experience difficulty at any stage of this process, please reach out to OP Labs Developer Support (opens in a new tab).
Important Notice for Bridges and Users
ALL withdrawals that are not finalized before the Fault Proofs upgrade executes will need to be reproven after the upgrade is complete.
- Reproving simply requires that you execute the withdrawal proving flow (opens in a new tab) again.
- Withdrawals prior to the Fault Proofs upgrade must wait a 7-day challenge period before finalization. As a result, any withdrawal initiated less than 7 days before the upgrade cannot be finalized before the upgrade is executed. You may want to consider waiting until after the upgrade is complete to begin a withdrawal during this 7-day window.
Important Notice for Bridges and Users
Maximum withdrawal delay times are increasing with the Fault Proofs upgrade.
- Withdrawals will generally take 7 days to finalize (unchanged from before Fault Proofs).
- Withdrawals that are proven against an output proposal that receives a validity challenge are delayed by an additional 3.5 days. Valid proposals that are challenged maliciously can be delayed by up to an additional 9 days at a very high cost to the malicious actor. Additional delays of this type are expected to be infrequent.
As of the Fault Proofs update to OP Sepolia in March 2024, OP Sepolia withdrawals are no longer instant. This is because the Fault Proof mechanism now applies to OP Sepolia transactions.
Overview of Changes
If you are operating a custom bridge, review this section for changes you need to make. If you are using Optimism SDK or Viem for your bridging, you can skip to the next section.
The L2OutputOracle is being entirely removed and replaced by the OptimismPortal and DisputeGameFactory. The L2OutputOracle smart contract is currently used by the trusted Proposer role to store L2 state output proposals.
Presently, developers use these outputs to prove that their withdrawals actually happened on L2. But with fault proofs, developers will have to change how their client software proves withdrawals in the first step of the two-step withdrawal process.
L2OutputOracle
The OptimismPortal is changing slightly with Fault Proof Mainnet because it now points to the DisputeGameFactory contract instead of the L2OutputOracle contract.
Most notable change for developers is that withdrawals will have to be proven against the rootClaim of some dispute game rather than referencing an output in the L2OutputOracle contract.
OptimismPortal
The OptimismPortal smart contract is the low-level contract on L1 used to execute deposits and withdrawals.
Previously, developers would look at the L2OutputOracle to find the exact next output that included their withdrawal.
Now, developers must look at the OptimismPortal contract to determine the respectedGameType and then use this information to query the DisputeGameFactory for a list of recent DisputeGame contracts with the correct game type.
DisputeGameFactory
It is recommended that developers search for a reasonable number of recent games, say 100 games, and pick the first proposal with a sufficient block number. Developers should then verify this proposal locally as the default game type will allow for permissionless proposals and there is no longer a strong guarantee that proposals will be valid.
For Bridges and Centralized Exchanges
The proposed Fault Proof upgrade requires developers to enable Fault Proof changes before the Op Mainnet release. This impacts bridges, centralized exchanges, and custom solutions that use withdrawals.
Withdrawals that haven't finalized before the upgrade occurs will be unable to be finalized post-upgrade without reproving. This means these withdrawals will need to go through a new 7-day period. The time accrued before the upgrade will not count. This means the withdrawal time could be as long as 13-14 days during the upgrade window. (If you submit it ~6 days before the upgrade, then must re-prove after the upgrade, you will have to wait a new seven days.)
Update Logic to Support Fault Proofs
Most teams use the Optimism SDK or Viem to handle this logic under the hood and will simply need to update their software version ahead of the upgrade. However, any project performing withdrawals programmatically will need to update their client code (see OptimismPortal for details).
- Option 1: Optimism SDK Update. If you use OptimismSDK for bridging, simply update to version 3.2.0 or higher.
The Optimism SDK changes do not break the API and require no changes other than updating to the correct software version to support the new
OptimismPortallogic. The Optimism SDK will automatically begin to use the new logic once it detects that the FPM update has gone live. - Option 2: Viem Update. Update to the latest version of Viem (version of >=2.9.0). Viem will automatically begin to use the new logic once it detects that the FPM update has gone live.
Update Withdrawal Monitor
The Withdrawal Monitor service is an important part of the two-step withdrawal system that checks if anyone has been able to prove withdrawals that do not actually appear on L2. The Withdrawal Monitor is now slightly slower at startup time but is more reliable, simpler, and compatible with more infrastructure to more easily support any OP Stack chain. Changes to the Withdrawal Monitor are entirely backwards compatible.
- Option 1: Withdrawal from source. If building or using withdrawal-monitor from source, make sure that you are using the latest develop branch. All withdrawal monitor changes are fully backwards compatible.
- Option 2: Docker image. If using docker, use the latest chain-mon docker image.
Update Dispute Monitor
The Dispute Monitor service detects when invalid outputs have been proposed. Given the large number of changes to the output proposal system, the current Fault Monitor is being replaced in favor of a new Dispute Monitor purposely built for the fault proof monitor system.
Any team running the current Fault Monitor will see the monitor stop functioning when the Fault Proof Monitor upgrade goes live. These teams should run the new service and update their alerting accordingly.
Next Steps
- See the Fault Proofs Explainer to learn more about the three main components of the Fault Proof System.
- You can also read more about Cannon FPVM and Mips.sol, the onchain smart contract implementation of Cannon.