OptimismPortal

Table of Contents

• Overview
• Definitions
  • Proof Maturity Delay
  • Proven Withdrawal
  • Finalized Withdrawal
  • Valid Withdrawal
  • Invalid Withdrawal
  • L2 Withdrawal Sender
• Assumptions
  • aOP-001: Dispute Game contracts properly report important properties
    • Mitigations
  • aOP-002: DisputeGameFactory properly reports its created games
    • Mitigations
  • aOP-003: Incorrectly resolving games will be invalidated before they have Valid Claims
    • Mitigations
• Dependencies
• Invariants
  • iOP-001: Invalid Withdrawals can never be finalized
    • Impact
  • iOP-002: Valid Withdrawals can always be finalized in bounded time
    • Impact
• Function Specification
  • constructor
  • initialize
  • paused
  • guardian
  • proofMaturityDelaySeconds
  • disputeGameFinalityDelaySeconds
  • respectedGameType
  • respectedGameTypeUpdatedAt
  • l2Sender
  • proveWithdrawalTransaction
  • checkWithdrawal
  • finalizeWithdrawalTransaction

Overview

The OptimismPortal contract is the primary interface for deposits and withdrawals between the L1 and L2 chains within an OP Stack system. The OptimismPortal contract allows users to create "deposit transactions" on the L1 chain that are automatically executed on the L2 chain within a bounded amount of time. Additionally, the OptimismPortal contract allows users to execute withdrawal transactions by proving that such a withdrawal was initiated on the L2 chain. The OptimismPortal verifies the correctness of these withdrawal transactions against Output Roots that have been declared valid by the L1 Fault Proof system.

Definitions

Proof Maturity Delay

The Proof Maturity Delay is the minimum amount of time that a withdrawal must be a Proven Withdrawal before it can be finalized.

Proven Withdrawal

A Proven Withdrawal is a withdrawal transaction that has been proven against some Output Root by a user. Users can prove withdrawals against any Dispute Game contract that meets the following conditions:

• The game is a Registered Game
• The game is not a Retired Game
• The game has a game type that matches the current Respected Game Type
• The game has not resolved in favor of the Challenger

Notably, the OptimismPortal allows users to prove withdrawals against games that are currently in progress (games that are not Resolved Games).

Users may re-prove a withdrawal at any time. User withdrawals are stored on a per-user basis such that re-proving a withdrawal cannot cause the timer for finalizing a withdrawal to be reset for another user.

Finalized Withdrawal

A Finalized Withdrawal is a withdrawal transaction that was previously a Proven Withdrawal and meets a number of additional conditions that allow the withdrawal to be executed.

Users can finalize a withdrawal if they have previously proven the withdrawal and their withdrawal meets the following conditions:

• Withdrawal is a Proven Withdrawal
• Withdrawal was proven at least Proof Maturity Delay seconds ago
• Withdrawal was proven against a game with a Valid Claim
• Withdrawal was not previously finalized

Valid Withdrawal

A Valid Withdrawal is a withdrawal transaction that was correctly executed on the L2 system as would be reported by a perfect oracle for the query.

Invalid Withdrawal

An Invalid Withdrawal is any withdrawal that is not a Valid Withdrawal.

L2 Withdrawal Sender

The L2 Withdrawal Sender is the address of the account that triggered a given withdrawal transaction on L2. The OptimismPortal is expected to expose a variable that includes this value when finalizing a withdrawal.

Assumptions

aOP-001: Dispute Game contracts properly report important properties

We assume that the FaultDisputeGame and PermissionedDisputeGame contracts properly and faithfully report the following properties:

• Game type
• L2 block number
• Root claim value
• Game extra data
• Creation timestamp
• Resolution timestamp
• Resolution result
• Whether the game was the respected game type at creation

We also specifically assume that the game creation timestamp and the resolution timestamp are not set to values in the future.

Mitigations

• Existing audit on the FaultDisputeGame contract
• Integration testing

aOP-002: DisputeGameFactory properly reports its created games

We assume that the DisputeGameFactory contract properly and faithfully reports the games it has created.

Mitigations

• Existing audit on the DisputeGameFactory contract
• Integration testing

aOP-003: Incorrectly resolving games will be invalidated before they have Valid Claims

We assume that any games that are resolved incorrectly will be invalidated either by blacklisting or by retirement BEFORE they are considered to have Valid Claims.

Proper Games that resolve in favor the Defender will be considered to have Valid Claims after the Dispute Game Finality Delay has elapsed UNLESS the Superchain-wide pause mechanism is active. Therefore, in the absence of the Superchain-wide pause mechanism, parties responsible for game invalidation have exactly the Dispute Game Finality Delay to invalidate a withdrawal after it resolves incorrectly. If the Superchain-wide pause is active, then any incorrectly resolving games must be invalidated before the pause is deactivated.

Mitigations

• Stakeholder incentives / processes
• Incident response plan
• Monitoring

Dependencies

• iASR-001
• iASR-002

Invariants

iOP-001: Invalid Withdrawals can never be finalized

We require that Invalid Withdrawals can never be finalized for any reason.

Impact

Severity: Critical

If this invariant is broken, any number of arbitrarily bad outcomes could happen. Most obviously, we would expect all bridge systems relying on the OptimismPortal to be immediately compromised.

iOP-002: Valid Withdrawals can always be finalized in bounded time

We require that Valid Withdrawals can always be finalized within some reasonable, bounded amount of time.

Impact

Severity: Critical

If this invariant is broken, we would expect that users are unable to withdraw bridged assets. We see this as a critical system risk.

Function Specification

constructor

• MUST set the value of the Proof Maturity Delay.

initialize

• MUST only be triggerable once.
• MUST set the value of the DisputeGameFactory contract.
• MUST set the value of the SystemConfig contract.
• MUST set the value of the SuperchainConfig contract.
• MUST set the value of the AnchorStateRegistry contract.
• MUST set the value of the L2 Withdrawal Sender variable to the default value if the value is not set already.
• MUST initialize the resource metering configuration.

paused

Returns the current state of the SuperchainConfig.paused() function.

guardian

Returns the address of the Guardian as per SuperchainConfig.guardian().

proofMaturityDelaySeconds

Returns the value of the Proof Maturity Delay.

disputeGameFinalityDelaySeconds

Legacy Function

Returns the value of the Dispute Game Finality Delay as per a call to AnchorStateRegistry.disputeGameFinalityDelaySeconds().

respectedGameType

Legacy Function

Returns the value of the current Respected Game Type as per a call to AnchorStateRegistry.respectedGameType.

respectedGameTypeUpdatedAt

Legacy Function

Returns the value of the current Retirement Timestamp as per a call to `AnchorStateRegistry.retirementTimestamp.

l2Sender

Returns the address of the L2 Withdrawal Sender. If the OptimismPortal has not been initialized then this value will be address(0) and should not be used. If the OptimismPortal is not currently executing an withdrawal transaction then this value will be 0x000000000000000000000000000000000000dEaD and should not be used.

proveWithdrawalTransaction

Allows a user to prove a withdrawal transaction.

• MUST revert if the withdrawal target is the address of the OptimismPortal itself.
• MUST revert if the withdrawal is being proven against a game that is not a Proper Game.
• MUST revert if the withdrawal is being proven against a game that is not a Respected Game.
• MUST revert if the withdrawal is being proven against a game that has resolved in favor of the Challenger.
• MUST revert if the provided merkle trie proof that the withdrawal was included within the root claim of the provided dispute game is invalid.
• MUST otherwise store a record of the withdrawal proof that includes the hash of the proven
  withdrawal, the address of the game against which it was proven, and the block timestamp at which the proof transaction was submitted.

checkWithdrawal

Checks that a withdrawal transaction can be finalized.

• MUST revert if the withdrawal being finalized has already been finalized.
• MUST revert if the withdrawal being finalized has not been proven.
• MUST revert if the withdrawal was proven at a timestamp less than the creation timestamp of the dispute game it was proven against, which would signal an unexpected proving bug.
• MUST revert if the withdrawal being finalized has been proven less than Proof Maturity Delay seconds ago.
• MUST revert if the withdrawal being finalized was proven against a game that does not have a Valid Claim.

finalizeWithdrawalTransaction

Allows a user to finalize a withdrawal transaction.

• MUST revert if the function is called while a previous withdrawal is being executed.
• MUST revert if the withdrawal being finalized does not pass checkWithdrawal.
• MUST mark the withdrawal as finalized.
• MUST set the L2 Withdrawal Sender variable correctly.
• MUST execute the withdrawal transaction by executing a contract call to the target address with the data and ETH value specified within the withdrawal using AT LEAST the minimum amount of gas specified by the withdrawal.
• MUST unset the L2 Withdrawal Sender after the withdrawal call.