From e896799d3cae614a67ac9803c64a5577ce6ae897 Mon Sep 17 00:00:00 2001 From: wildmolasses Date: Fri, 8 Nov 2024 15:12:46 +0700 Subject: [PATCH 01/19] proofs-iri-asr --- .../stage-one/anchor-state-registry.md | 134 ++++++++++++++++++ .../fault-proof/stage-one/bond-incentives.md | 59 ++++---- .../fault-proof/stage-one/optimism-portal.md | 9 ++ 3 files changed, 173 insertions(+), 29 deletions(-) create mode 100644 specs/fault-proof/stage-one/anchor-state-registry.md create mode 100644 specs/fault-proof/stage-one/optimism-portal.md diff --git a/specs/fault-proof/stage-one/anchor-state-registry.md b/specs/fault-proof/stage-one/anchor-state-registry.md new file mode 100644 index 000000000..25e1106f5 --- /dev/null +++ b/specs/fault-proof/stage-one/anchor-state-registry.md @@ -0,0 +1,134 @@ +# Anchor State Registry + +## Overview (What this contract is actually supposed to do) + +This contract manages and communicates properties of dispute game validity to other contracts in order to facilitate withdrawals and future dispute games. + +- This contract is the source of truth for the validity of an **anchor state**. + - [FaultDisputeGame](fault-dispute-game.md) and PermissionedDisputeGame depend on this contract for a valid **anchor state** against which to resolve a claim. These contracts assume the state is valid. + - The valid anchor state needs to be recent enough so that the game doesn't break (run out of memory) in op-challenger. +- This contract is the source of truth for the validity of a particular fault dispute game result. + - This property is used by the [OptimismPortal](optimism-portal.md). The Portal asks two things of the Registry: + - Can this dispute game can be used to prove a withdrawal? + - Can this dispute game can be used to finalize a withdrawal? + +## Definitions + +- **Anchor state** + - See [Fault Dispute Game -> Anchor State](fault-dispute-game.md#anchor-state). +- **Authorized input** + - An input for which there is social consensus, i.e. coming from governance. +- **Invalid game** + - A dispute game is invalid if any of the following are true: + - Game was not created by the dispute game factory. + - Game was not created while it was the respected game type. + - Game is blacklisted. + - Game was created before the validity timestamp. + - Game status is `CHALLENGER_WINS`. +- **Finalized game** + - A dispute game is finalized if all of the following are true: + - Game status is `CHALLENGER_WINS` or `DEFENDER_WINS`. + - Game `resolvedAt` timestamp is not zero. + - Game `resolvedAt` timestamp is more than `dispute game finality seconds` seconds ago. +- **Valid game** + - A game is a **Valid game** if it is not an **Invalid game**, and is a **Finalized game**. +- **Latest valid game** + - The latest valid game is a **valid game** whose anchor state will be used to initialize new FaultDisputeGames and PermissionedDisputeGames. It represents the most recent valid representation of L2 state. + +## Top-Level Invariants + +- The Validity timestamp starts at zero. + +## Function-Level Invariants + +### `initialize` + +Initialize the thing somehow. + +- Initial anchor state is **authorized**. +- Need an **authorized** reference to the dispute game factory. +- Need **authorized** input for `dispute game finality seconds`. +- Need **authorized** reference to superchain config. + +### `getLatestValidGame` + +Get latest **valid game**. + +- Throws an error if the game is not valid. + - Depends on the condition that `update latest valid game` is the only method to update the “latest valid game” state variable and that it will only update the state variable with a **valid game**. Still, it is possible for the once valid game to become invalid. + +### Update latest **valid game** + +- Game must be **valid** +- Block number for latest valid game must be higher than current latest valid game +- This function is the ONLY way to update the latest valid game (after initialization) + +### Get latest valid root claim + +- Returns the root claim of the result of `get latest valid game` or an **authorized** anchor state if no such game exists + +### Get anchor state + +- Returns the root claim of the result of `get latest valid game` or an **authorized** anchor state if no such game exists +- Must maintain the property that the timestamp of the game is not too old + +### Register game result + +- Callable only by a game itself +- Game must not be invalid +- If game is not invalid, stores the address of the game in some array + +### Try update latest valid game based on previous game results + +- Callable by anyone +- Find the latest (comparing on l2BlockNumber) valid game you can find in the register within a fixed amount of gas +- Use this as input to `update latest valid game` +- Make sure this doesn’t get more expensive as time goes on + +### Is this game invalid? + +### Is this game finalized? + +### Is this game valid? + +- `return !isGameInvalid(game) && isGameFinalized(game)` +- Definition of **valid** is this condition passing + +### Set respected game type + +- Can only be set by + +### Update validity timestamp + +- Can only be set by +- Must be greater than previous validity timestamp +- Cannot be greater than current block timestamp + +### Blacklist game + +- Can only be set by + +--- + +- Definition of valid is NOT invalid AND finalized +- Airgap is a condition of finalization +- Therefore airgap is a condition of validity +- Games can be blacklisted after they are valid + +--- + +- Change respected game type +- Observe that change to respected game type is finalized +- Then change the validation timestamp +- Or just do both but make sure that respected game type change doesn’t get reorged to be after the timestamp change + +### Get dispute game finality delay + +- Returns **authorized** finality delay duration. + +# FaultDisputeGame + +- Only sets that special boolean if it actually is the respected game type +- And the boolean never changes after it’s been set +- Reports its game type correctly +- Reports its l2BlockNumber correctly diff --git a/specs/fault-proof/stage-one/bond-incentives.md b/specs/fault-proof/stage-one/bond-incentives.md index bb2a3f204..802bc1aae 100644 --- a/specs/fault-proof/stage-one/bond-incentives.md +++ b/specs/fault-proof/stage-one/bond-incentives.md @@ -2,22 +2,24 @@ + **Table of Contents** -- [Overview](#overview) -- [Moves](#moves) -- [Subgame Resolution](#subgame-resolution) - - [Leftmost Claim Incentives](#leftmost-claim-incentives) -- [Fault Proof Mainnet Incentives](#fault-proof-mainnet-incentives) - - [Authenticated Roles](#authenticated-roles) - - [Base Fee Assumption](#base-fee-assumption) - - [Bond Scaling](#bond-scaling) - - [Required Bond Formula](#required-bond-formula) - - [Other Incentives](#other-incentives) - - [DelayedWETH](#delayedweth) - - [Sub-Account Model](#sub-account-model) - - [Delay Period](#delay-period) - - [Integration](#integration) +- [Bond Incentives](#bond-incentives) + - [Overview](#overview) + - [Moves](#moves) + - [Subgame Resolution](#subgame-resolution) + - [Leftmost Claim Incentives](#leftmost-claim-incentives) + - [Fault Proof Mainnet Incentives](#fault-proof-mainnet-incentives) + - [Authenticated Roles](#authenticated-roles) + - [Base Fee Assumption](#base-fee-assumption) + - [Bond Scaling](#bond-scaling) + - [Required Bond Formula](#required-bond-formula) + - [Other Incentives](#other-incentives) + - [DelayedWETH](#delayedweth) + - [Sub-Account Model](#sub-account-model) + - [Delay Period](#delay-period) + - [Integration](#integration) @@ -76,9 +78,9 @@ proof system. ### Authenticated Roles -| Name | Description | -| ---- | ----------- | -| Guardian | Role responsible for blacklisting dispute game contracts and changing the respected dispute game type | +| Name | Description | +| ------------ | ----------------------------------------------------------------------------------------------------- | +| Guardian | Role responsible for blacklisting dispute game contracts and changing the respected dispute game type | | System Owner | Role that owns the `ProxyAdmin` contract that in turn owns most `Proxy` contracts within the OP Stack | ### Base Fee Assumption @@ -139,19 +141,18 @@ incorrectly distribute bonds. - `DelayedWETH` has an `owner()` address. We typically expect this to be set to the `System Owner` address. - `DelayedWETH` has a `delay()` function that returns a period of time that withdrawals will be delayed. - `DelayedWETH` has an `unlock(guy,wad)` function that modifies a mapping called `withdrawals` keyed as -`withdrawals[msg.sender][guy] => WithdrawalRequest` where `WithdrawalRequest` is -`struct Withdrawal Request { uint256 amount, uint256 timestamp }`. When `unlock` is called, the timestamp for -`withdrawals[msg.sender][guy]` is set to the current timestamp and the amount is increased by the given amount. -- `DelayedWETH` modifies the `WETH.withdraw` function such that an address *must* provide a "sub-account" to withdraw -from. The function signature becomes `withdraw(guy,wad)`. The function retrieves `withdrawals[msg.sender][guy]` and -checks that the current `block.timestamp` is greater than the timestamp on the withdrawal request plus the `delay()` -seconds and reverts if not. It also confirms that the amount being withdrawn is less than the amount in the withdrawal -request. Before completing the withdrawal, it reduces the amount contained within the withdrawal request. The original -`withdraw(wad)` function becomes an alias for `withdraw(msg.sender, wad)`. -`withdraw(guy,wad)` will not be callable when `SuperchainConfig.paused()` is `true`. + `withdrawals[msg.sender][guy] => WithdrawalRequest` where `WithdrawalRequest` is + `struct Withdrawal Request { uint256 amount, uint256 timestamp }`. When `unlock` is called, the timestamp for + `withdrawals[msg.sender][guy]` is set to the current timestamp and the amount is increased by the given amount. +- `DelayedWETH` modifies the `WETH.withdraw` function such that an address _must_ provide a "sub-account" to withdraw + from. The function signature becomes `withdraw(guy,wad)`. The function retrieves `withdrawals[msg.sender][guy]` and + checks that the current `block.timestamp` is greater than the timestamp on the withdrawal request plus the `delay()` + seconds and reverts if not. It also confirms that the amount being withdrawn is less than the amount in the withdrawal + request. Before completing the withdrawal, it reduces the amount contained within the withdrawal request. The original + `withdraw(wad)` function becomes an alias for `withdraw(msg.sender, wad)`. + `withdraw(guy,wad)` will not be callable when `SuperchainConfig.paused()` is `true`. - `DelayedWETH` has a `hold()` function that allows the `owner()` address to give itself an allowance from any address. -- `DelayedWETH` has a `recover()` function that allows the `owner()` address to recover any amount of ETH from the -contract. +- `DelayedWETH` has a `recover()` function that allows the `owner()` address to recover any amount of ETH from the contract. #### Sub-Account Model diff --git a/specs/fault-proof/stage-one/optimism-portal.md b/specs/fault-proof/stage-one/optimism-portal.md new file mode 100644 index 000000000..eeb2a38c2 --- /dev/null +++ b/specs/fault-proof/stage-one/optimism-portal.md @@ -0,0 +1,9 @@ +# Optimism Portal + +## Overview (What this contract is actually supposed to do) + +## Definitions + +## Top-Level Invariants + +## Function-Level Invariants From 5841241027ae6d794ba021b32831a11c40d0d01f Mon Sep 17 00:00:00 2001 From: wildmolasses Date: Wed, 4 Dec 2024 19:48:05 -0500 Subject: [PATCH 02/19] wip: ASR, portal --- .../stage-one/anchor-state-registry.md | 194 ++++++++++++------ .../fault-proof/stage-one/bond-incentives.md | 30 ++- .../fault-proof/stage-one/optimism-portal.md | 36 +++- 3 files changed, 175 insertions(+), 85 deletions(-) diff --git a/specs/fault-proof/stage-one/anchor-state-registry.md b/specs/fault-proof/stage-one/anchor-state-registry.md index 25e1106f5..580ca960f 100644 --- a/specs/fault-proof/stage-one/anchor-state-registry.md +++ b/specs/fault-proof/stage-one/anchor-state-registry.md @@ -1,16 +1,52 @@ + + + +**Table of Contents** + +- [Anchor State Registry](#anchor-state-registry) + - [Overview](#overview) + - [Perspective](#perspective) + - [Definitions](#definitions) + - [Top-Level Invariants](#top-level-invariants) + - [Contract Dependents](#contract-dependents) + - [Contract Dependencies](#contract-dependencies) + - [FaultDisputeGame](#faultdisputegame) + - [Function-Level Invariants](#function-level-invariants) + - [Initialize](#initialize) + - [Get **latest valid game**](#get-latest-valid-game) + - [Update **latest valid game**](#update-latest-valid-game) + - [Get latest anchor state](#get-latest-anchor-state) + - [Register game result](#register-game-result) + - [Try update latest valid game based on previous game results](#try-update-latest-valid-game-based-on-previous-game-results) + - [Is this game invalid?](#is-this-game-invalid) + - [Is this game finalized?](#is-this-game-finalized) + - [Is this game valid?](#is-this-game-valid) + - [Is this game blacklisted?](#is-this-game-blacklisted) + - [Set respected game type](#set-respected-game-type) + - [Update validity timestamp](#update-validity-timestamp) + - [Blacklist game](#blacklist-game) + - [Get dispute game finality delay](#get-dispute-game-finality-delay) + - [Implementation](#implementation) + - [`constructor`](#constructor) + - [`initialize`](#initialize-1) + + + # Anchor State Registry -## Overview (What this contract is actually supposed to do) +## Overview -This contract manages and communicates properties of dispute game validity to other contracts in order to facilitate withdrawals and future dispute games. +### Perspective -- This contract is the source of truth for the validity of an **anchor state**. - - [FaultDisputeGame](fault-dispute-game.md) and PermissionedDisputeGame depend on this contract for a valid **anchor state** against which to resolve a claim. These contracts assume the state is valid. - - The valid anchor state needs to be recent enough so that the game doesn't break (run out of memory) in op-challenger. -- This contract is the source of truth for the validity of a particular fault dispute game result. - - This property is used by the [OptimismPortal](optimism-portal.md). The Portal asks two things of the Registry: - - Can this dispute game can be used to prove a withdrawal? - - Can this dispute game can be used to finalize a withdrawal? +Multiple contracts in the fault proof system have hard dependencies on things outside them: + +- The Portal needs to know whether a withdrawal's proof is based on a **valid** dispute game. +- A new dispute game needs to initialize with a **valid** anchor state. +- An existing dispute game needs to know whether it is **invalid**, so it can refund its bonds. + +The AnchorStateRegistry is these contracts' source of truth, managing and exposing dispute game and anchor state validity to moderate dispute games and withdrawals. + +Furthermore, the AnchorStateRegistry is a crucial player in incident response. It can invalidate dispute games and withdrawals, effectively mitigating consequences from dispute games that resolve incorrectly. ## Definitions @@ -18,117 +54,139 @@ This contract manages and communicates properties of dispute game validity to ot - See [Fault Dispute Game -> Anchor State](fault-dispute-game.md#anchor-state). - **Authorized input** - An input for which there is social consensus, i.e. coming from governance. +- **Blacklisted game** + - A dispute game is blacklisted if it is set as blacklisted via **authorized input**. +- **Validity timestamp** + - The validity timestamp is an **authorized input** that partly determines game validity. - **Invalid game** - A dispute game is invalid if any of the following are true: - Game was not created by the dispute game factory. - Game was not created while it was the respected game type. - - Game is blacklisted. - - Game was created before the validity timestamp. + - Game is **blacklisted**. + - Game was created before the **validity timestamp**. - Game status is `CHALLENGER_WINS`. - **Finalized game** - A dispute game is finalized if all of the following are true: - Game status is `CHALLENGER_WINS` or `DEFENDER_WINS`. - Game `resolvedAt` timestamp is not zero. - - Game `resolvedAt` timestamp is more than `dispute game finality seconds` seconds ago. + - Game `resolvedAt` timestamp is more than `dispute game finality delay` seconds ago. - **Valid game** - A game is a **Valid game** if it is not an **Invalid game**, and is a **Finalized game**. - **Latest valid game** - - The latest valid game is a **valid game** whose anchor state will be used to initialize new FaultDisputeGames and PermissionedDisputeGames. It represents the most recent valid representation of L2 state. + - The latest valid game is a game whose anchor state is used to initialize new Fault Dispute Games. It was known to be a **valid game** when set. It will continue to be the latest valid game until updated with a more recent valid game, or blacklisted. +- **Latest valid anchor state** + - The latest valid anchor state is the output root of the latest valid game. ## Top-Level Invariants -- The Validity timestamp starts at zero. +- The contract will only assert **valid games** are valid. +- The latest valid anchor state must never serve the output root of a blacklisted game. +- The latest valid anchor state must be recent enough so that the game doesn't break (run out of memory) in op-challenger. +- The validity timestamp must start at zero. -## Function-Level Invariants +### Contract Dependents -### `initialize` +This contract manages and exposes dispute game validity so that other contracts can do things like validate withdrawals and initialize dispute games correctly. -Initialize the thing somehow. +- This contract is the source of truth for the validity of an **anchor state**. + - [FaultDisputeGame](fault-dispute-game.md) and PermissionedDisputeGame depend on this contract for a **latest valid anchor state** against which to resolve a claim. These contracts assume the state is valid. +- Optimism Portal depends on this contract for accurate fault dispute game results. + - Can this dispute game can be used to prove a withdrawal? (Is the dispute game not an **invalid game**?) + - Can this dispute game can be used to finalize a withdrawal? (Is the dispute game a **valid game**?) -- Initial anchor state is **authorized**. -- Need an **authorized** reference to the dispute game factory. -- Need **authorized** input for `dispute game finality seconds`. -- Need **authorized** reference to superchain config. +### Contract Dependencies -### `getLatestValidGame` +#### FaultDisputeGame -Get latest **valid game**. +- Only sets that special boolean if it actually is the respected game type. +- And the boolean never changes after it’s been set. +- Reports its game type correctly. +- Reports its l2BlockNumber correctly. +- Reports its createdAt timestamp correctly. -- Throws an error if the game is not valid. - - Depends on the condition that `update latest valid game` is the only method to update the “latest valid game” state variable and that it will only update the state variable with a **valid game**. Still, it is possible for the once valid game to become invalid. +## Function-Level Invariants + +### Initialize + +- Initial anchor state must be an **authorized input**. +- Dispute game factory must be an **authorized input**. +- `dispute game finality delay` must be an **authorized input**. +- Superchain config must be an **authorized input**. + +### Get **latest valid game** -### Update latest **valid game** +Gets **latest valid game**. -- Game must be **valid** -- Block number for latest valid game must be higher than current latest valid game -- This function is the ONLY way to update the latest valid game (after initialization) +- Throws an error if the game is not valid. + - Depends on the condition that `update latest valid game` is the only method to update the “latest valid game” state variable and that it will only update the state variable with a **valid game**. Still, it is possible for the once valid game to become invalid (via blacklisting or `update validity timestamp`). -### Get latest valid root claim +### Update **latest valid game** -- Returns the root claim of the result of `get latest valid game` or an **authorized** anchor state if no such game exists +- Game must be **valid**. +- Block number for latest valid game must be higher than current latest valid game. +- This function is the ONLY way to update the latest valid game (after initialization). -### Get anchor state +### Get latest anchor state -- Returns the root claim of the result of `get latest valid game` or an **authorized** anchor state if no such game exists -- Must maintain the property that the timestamp of the game is not too old +- If the **latest valid game** is not blacklisted, return its root claim and l2 block number. +- If the **latest valid game** is blacklisted, throw an error. +- Must maintain the property that the timestamp of the game is not too old. + - TODO: How old is too old? ### Register game result -- Callable only by a game itself -- Game must not be invalid -- If game is not invalid, stores the address of the game in some array +Stores the address of a not invalid dispute game in an array as a candidate for `latestValidGame`. + +- Callable only by a not invalid game. +- Calling game must only register itself. +- TODO: ### Try update latest valid game based on previous game results -- Callable by anyone -- Find the latest (comparing on l2BlockNumber) valid game you can find in the register within a fixed amount of gas -- Use this as input to `update latest valid game` -- Make sure this doesn’t get more expensive as time goes on +- Callable by anyone. +- Find the latest (comparing on l2BlockNumber) valid game you can find in the register within a fixed amount of gas. + - Fixed gas amount ensures that this function does not get more expensive to call as time goes on. +- Use this as input to `update latest valid game`. ### Is this game invalid? +Returns whether the game is an **invalid game**. + ### Is this game finalized? -### Is this game valid? +Returns whether the game is a **finalized game**. -- `return !isGameInvalid(game) && isGameFinalized(game)` -- Definition of **valid** is this condition passing +### Is this game valid? -### Set respected game type +`return !isGameInvalid(game) && isGameFinalized(game)` -- Can only be set by +- Definition of **valid** is this condition passing. -### Update validity timestamp +### Is this game blacklisted? -- Can only be set by -- Must be greater than previous validity timestamp -- Cannot be greater than current block timestamp +Returns whether the game is a **blacklisted game**. -### Blacklist game +### Set respected game type -- Can only be set by +- Must be **authorized** by . ---- +### Update validity timestamp -- Definition of valid is NOT invalid AND finalized -- Airgap is a condition of finalization -- Therefore airgap is a condition of validity -- Games can be blacklisted after they are valid +- Must be **authorized** by . +- Must be greater than previous validity timestamp. +- Cannot be greater than current block timestamp. ---- +### Blacklist game -- Change respected game type -- Observe that change to respected game type is finalized -- Then change the validation timestamp -- Or just do both but make sure that respected game type change doesn’t get reorged to be after the timestamp change +- Must be **authorized** by . ### Get dispute game finality delay -- Returns **authorized** finality delay duration. +- Returns **authorized** finality delay duration in seconds. +- No external dependent; public getter for convenience. + +## Implementation -# FaultDisputeGame +### `constructor` -- Only sets that special boolean if it actually is the respected game type -- And the boolean never changes after it’s been set -- Reports its game type correctly -- Reports its l2BlockNumber correctly +### `initialize` diff --git a/specs/fault-proof/stage-one/bond-incentives.md b/specs/fault-proof/stage-one/bond-incentives.md index 802bc1aae..0fdd5c4c5 100644 --- a/specs/fault-proof/stage-one/bond-incentives.md +++ b/specs/fault-proof/stage-one/bond-incentives.md @@ -2,24 +2,22 @@ - **Table of Contents** -- [Bond Incentives](#bond-incentives) - - [Overview](#overview) - - [Moves](#moves) - - [Subgame Resolution](#subgame-resolution) - - [Leftmost Claim Incentives](#leftmost-claim-incentives) - - [Fault Proof Mainnet Incentives](#fault-proof-mainnet-incentives) - - [Authenticated Roles](#authenticated-roles) - - [Base Fee Assumption](#base-fee-assumption) - - [Bond Scaling](#bond-scaling) - - [Required Bond Formula](#required-bond-formula) - - [Other Incentives](#other-incentives) - - [DelayedWETH](#delayedweth) - - [Sub-Account Model](#sub-account-model) - - [Delay Period](#delay-period) - - [Integration](#integration) +- [Overview](#overview) +- [Moves](#moves) +- [Subgame Resolution](#subgame-resolution) + - [Leftmost Claim Incentives](#leftmost-claim-incentives) +- [Fault Proof Mainnet Incentives](#fault-proof-mainnet-incentives) + - [Authenticated Roles](#authenticated-roles) + - [Base Fee Assumption](#base-fee-assumption) + - [Bond Scaling](#bond-scaling) + - [Required Bond Formula](#required-bond-formula) + - [Other Incentives](#other-incentives) + - [DelayedWETH](#delayedweth) + - [Sub-Account Model](#sub-account-model) + - [Delay Period](#delay-period) + - [Integration](#integration) diff --git a/specs/fault-proof/stage-one/optimism-portal.md b/specs/fault-proof/stage-one/optimism-portal.md index eeb2a38c2..2865f600d 100644 --- a/specs/fault-proof/stage-one/optimism-portal.md +++ b/specs/fault-proof/stage-one/optimism-portal.md @@ -1,3 +1,19 @@ + + + +**Table of Contents** + +- [Optimism Portal](#optimism-portal) + - [Overview (What this contract is actually supposed to do)](#overview-what-this-contract-is-actually-supposed-to-do) + - [Definitions](#definitions) + - [Top-Level Invariants](#top-level-invariants) +- [Function-Level Invariants](#function-level-invariants) + - [Initialize the thing somehow](#initialize-the-thing-somehow) + - [Prove a withdrawal transaction](#prove-a-withdrawal-transaction) + - [Finalize a withdrawal transaction](#finalize-a-withdrawal-transaction) + + + # Optimism Portal ## Overview (What this contract is actually supposed to do) @@ -6,4 +22,22 @@ ## Top-Level Invariants -## Function-Level Invariants +- A withdrawal transaction must be proven against a game that is not `invalid`. +- A withdrawal transaction must be finalized against a game that is `valid`. +- A withdrawal transaction must be used only once to finalize a withdrawal. +- A withdrawal can only be finalized if it has been proven. +- A withdrawal transaction that is finalized must attempt execution. + +# Function-Level Invariants + +## Initialize the thing somehow + +- Need an **authorized** input for proof maturity delay seconds. +- Need an **authorized** reference to the anchor state registry. +- Need an **authorized** reference to the dispute game factory. +- Need an **authorized** input to system config. +- Need an **authorized** reference to superchain config. + +## Prove a withdrawal transaction + +## Finalize a withdrawal transaction From 13d66abef08a2acb3a6517c3b05ba0ce59b38d66 Mon Sep 17 00:00:00 2001 From: wildmolasses Date: Wed, 4 Dec 2024 20:34:16 -0500 Subject: [PATCH 03/19] wip: more ASR --- .../stage-one/anchor-state-registry.md | 95 +++++++++++++------ 1 file changed, 64 insertions(+), 31 deletions(-) diff --git a/specs/fault-proof/stage-one/anchor-state-registry.md b/specs/fault-proof/stage-one/anchor-state-registry.md index 580ca960f..01509121f 100644 --- a/specs/fault-proof/stage-one/anchor-state-registry.md +++ b/specs/fault-proof/stage-one/anchor-state-registry.md @@ -12,23 +12,33 @@ - [Contract Dependencies](#contract-dependencies) - [FaultDisputeGame](#faultdisputegame) - [Function-Level Invariants](#function-level-invariants) - - [Initialize](#initialize) - - [Get **latest valid game**](#get-latest-valid-game) - - [Update **latest valid game**](#update-latest-valid-game) - - [Get latest anchor state](#get-latest-anchor-state) - - [Register game result](#register-game-result) - - [Try update latest valid game based on previous game results](#try-update-latest-valid-game-based-on-previous-game-results) - - [Is this game invalid?](#is-this-game-invalid) - - [Is this game finalized?](#is-this-game-finalized) - - [Is this game valid?](#is-this-game-valid) - - [Is this game blacklisted?](#is-this-game-blacklisted) - - [Set respected game type](#set-respected-game-type) - - [Update validity timestamp](#update-validity-timestamp) - - [Blacklist game](#blacklist-game) - - [Get dispute game finality delay](#get-dispute-game-finality-delay) + - [`initialize`](#initialize) + - [`getLatestValidGame`](#getlatestvalidgame) + - [`updateLatestValidGame`](#updatelatestvalidgame) + - [`getLatestAnchorState`](#getlatestanchorstate) + - [`registerGameResult`](#registergameresult) + - [`tryUpdateLatestValidGame`](#tryupdatelatestvalidgame) + - [`isGameInvalid`](#isgameinvalid) + - [`isGameFinalized`](#isgamefinalized) + - [`isGameValid`](#isgamevalid) + - [`isGameBlacklisted`](#isgameblacklisted) + - [`setRespectedGameType`](#setrespectedgametype) + - [`updateValidityTimestamp`](#updatevaliditytimestamp) + - [`setGameBlacklisted`](#setgameblacklisted) + - [`getGameFinalityDelay`](#getgamefinalitydelay) - [Implementation](#implementation) - [`constructor`](#constructor) - [`initialize`](#initialize-1) + - [`anchors` / `getLatestAnchorState`](#anchors--getlatestanchorstate) + - [`registerMaybeValidGame`](#registermaybevalidgame) + - [`updateLatestValidGame`](#updatelatestvalidgame-1) + - [`tryUpdateLatestValidGame`](#tryupdatelatestvalidgame-1) + - [`setGameBlacklisted`](#setgameblacklisted-1) + - [`setRespectedGameType`](#setrespectedgametype-1) + - [`isGameInvalid`](#isgameinvalid-1) + - [`isGameValid`](#isgamevalid-1) + - [`disputeGameFinalityDelaySeconds`](#disputegamefinalitydelayseconds) + - [`disputeGameFactory`](#disputegamefactory) @@ -106,34 +116,34 @@ This contract manages and exposes dispute game validity so that other contracts ## Function-Level Invariants -### Initialize +### `initialize` - Initial anchor state must be an **authorized input**. - Dispute game factory must be an **authorized input**. - `dispute game finality delay` must be an **authorized input**. - Superchain config must be an **authorized input**. -### Get **latest valid game** +### `getLatestValidGame` Gets **latest valid game**. - Throws an error if the game is not valid. - Depends on the condition that `update latest valid game` is the only method to update the “latest valid game” state variable and that it will only update the state variable with a **valid game**. Still, it is possible for the once valid game to become invalid (via blacklisting or `update validity timestamp`). -### Update **latest valid game** +### `updateLatestValidGame` - Game must be **valid**. - Block number for latest valid game must be higher than current latest valid game. - This function is the ONLY way to update the latest valid game (after initialization). -### Get latest anchor state +### `getLatestAnchorState` - If the **latest valid game** is not blacklisted, return its root claim and l2 block number. - If the **latest valid game** is blacklisted, throw an error. - Must maintain the property that the timestamp of the game is not too old. - TODO: How old is too old? -### Register game result +### `registerGameResult` Stores the address of a not invalid dispute game in an array as a candidate for `latestValidGame`. @@ -141,52 +151,75 @@ Stores the address of a not invalid dispute game in an array as a candidate for - Calling game must only register itself. - TODO: -### Try update latest valid game based on previous game results +### `tryUpdateLatestValidGame` + +Try update latest valid game based on previous game results. - Callable by anyone. - Find the latest (comparing on l2BlockNumber) valid game you can find in the register within a fixed amount of gas. - Fixed gas amount ensures that this function does not get more expensive to call as time goes on. - Use this as input to `update latest valid game`. -### Is this game invalid? +### `isGameInvalid` Returns whether the game is an **invalid game**. -### Is this game finalized? +### `isGameFinalized` Returns whether the game is a **finalized game**. -### Is this game valid? +### `isGameValid` `return !isGameInvalid(game) && isGameFinalized(game)` -- Definition of **valid** is this condition passing. +Definition of **valid** is this condition passing. -### Is this game blacklisted? +### `isGameBlacklisted` Returns whether the game is a **blacklisted game**. -### Set respected game type +### `setRespectedGameType` - Must be **authorized** by . -### Update validity timestamp +### `updateValidityTimestamp` - Must be **authorized** by . - Must be greater than previous validity timestamp. - Cannot be greater than current block timestamp. -### Blacklist game +### `setGameBlacklisted` + +Blacklists a game. - Must be **authorized** by . -### Get dispute game finality delay +### `getGameFinalityDelay` -- Returns **authorized** finality delay duration in seconds. -- No external dependent; public getter for convenience. +Returns **authorized** finality delay duration in seconds. No external dependent; public getter for convenience. ## Implementation ### `constructor` ### `initialize` + +### `anchors` / `getLatestAnchorState` + +### `registerMaybeValidGame` + +### `updateLatestValidGame` + +### `tryUpdateLatestValidGame` + +### `setGameBlacklisted` + +### `setRespectedGameType` + +### `isGameInvalid` + +### `isGameValid` + +### `disputeGameFinalityDelaySeconds` + +### `disputeGameFactory` From 42d3d5da376bd46533f9b1591e2b0e011706a537 Mon Sep 17 00:00:00 2001 From: wildmolasses Date: Thu, 5 Dec 2024 12:21:40 -0500 Subject: [PATCH 04/19] wip: more ASR and Portal --- .../stage-one/anchor-state-registry.md | 98 ++++++++++++------- .../stage-one/dispute-game-interface.md | 4 + .../stage-one/fault-dispute-game.md | 16 +-- .../fault-proof/stage-one/optimism-portal.md | 89 +++++++++++++---- 4 files changed, 139 insertions(+), 68 deletions(-) diff --git a/specs/fault-proof/stage-one/anchor-state-registry.md b/specs/fault-proof/stage-one/anchor-state-registry.md index 01509121f..cb835e0ce 100644 --- a/specs/fault-proof/stage-one/anchor-state-registry.md +++ b/specs/fault-proof/stage-one/anchor-state-registry.md @@ -1,6 +1,5 @@ - **Table of Contents** - [Anchor State Registry](#anchor-state-registry) @@ -9,28 +8,32 @@ - [Definitions](#definitions) - [Top-Level Invariants](#top-level-invariants) - [Contract Dependents](#contract-dependents) - - [Contract Dependencies](#contract-dependencies) - [FaultDisputeGame](#faultdisputegame) + - [OptimismPortal](#optimismportal) + - [Contract Dependencies](#contract-dependencies) + - [FaultDisputeGame](#faultdisputegame-1) + - [DisputeGameFactory](#disputegamefactory) + - [SuperchainConfig](#superchainconfig) - [Function-Level Invariants](#function-level-invariants) - [`initialize`](#initialize) - [`getLatestValidGame`](#getlatestvalidgame) - [`updateLatestValidGame`](#updatelatestvalidgame) - [`getLatestAnchorState`](#getlatestanchorstate) - - [`registerGameResult`](#registergameresult) + - [`registerMaybeValidGame`](#registermaybevalidgame) - [`tryUpdateLatestValidGame`](#tryupdatelatestvalidgame) - [`isGameInvalid`](#isgameinvalid) - [`isGameFinalized`](#isgamefinalized) - [`isGameValid`](#isgamevalid) - [`isGameBlacklisted`](#isgameblacklisted) - [`setRespectedGameType`](#setrespectedgametype) - - [`updateValidityTimestamp`](#updatevaliditytimestamp) + - [`invalidateAllExistingGames`](#invalidateallexistinggames) - [`setGameBlacklisted`](#setgameblacklisted) - [`getGameFinalityDelay`](#getgamefinalitydelay) - [Implementation](#implementation) - [`constructor`](#constructor) - [`initialize`](#initialize-1) - [`anchors` / `getLatestAnchorState`](#anchors--getlatestanchorstate) - - [`registerMaybeValidGame`](#registermaybevalidgame) + - [`registerMaybeValidGame`](#registermaybevalidgame-1) - [`updateLatestValidGame`](#updatelatestvalidgame-1) - [`tryUpdateLatestValidGame`](#tryupdatelatestvalidgame-1) - [`setGameBlacklisted`](#setgameblacklisted-1) @@ -48,15 +51,15 @@ ### Perspective -Multiple contracts in the fault proof system have hard dependencies on things outside them: +Multiple contracts in the fault proof system have critical dependencies on things outside them: - The Portal needs to know whether a withdrawal's proof is based on a **valid** dispute game. -- A new dispute game needs to initialize with a **valid** anchor state. +- A new dispute game needs to initialize with the **latest valid anchor state**. - An existing dispute game needs to know whether it is **invalid**, so it can refund its bonds. The AnchorStateRegistry is these contracts' source of truth, managing and exposing dispute game and anchor state validity to moderate dispute games and withdrawals. -Furthermore, the AnchorStateRegistry is a crucial player in incident response. It can invalidate dispute games and withdrawals, effectively mitigating consequences from dispute games that resolve incorrectly. +Furthermore, the AnchorStateRegistry is a crucial player in incident response. It can invalidate dispute games, thereby invalidating withdrawals and dispute games founded on an incorrect root claim. ## Definitions @@ -67,7 +70,7 @@ Furthermore, the AnchorStateRegistry is a crucial player in incident response. I - **Blacklisted game** - A dispute game is blacklisted if it is set as blacklisted via **authorized input**. - **Validity timestamp** - - The validity timestamp is an **authorized input** that partly determines game validity. + - The validity timestamp is a timestamp internal to the contract that partly determines game validity and can only be adjusted via **authorized input**. - **Invalid game** - A dispute game is invalid if any of the following are true: - Game was not created by the dispute game factory. @@ -80,12 +83,17 @@ Furthermore, the AnchorStateRegistry is a crucial player in incident response. I - Game status is `CHALLENGER_WINS` or `DEFENDER_WINS`. - Game `resolvedAt` timestamp is not zero. - Game `resolvedAt` timestamp is more than `dispute game finality delay` seconds ago. +- **Maybe valid game** + - A dispute game that is not an **invalid game** (but not yet a **finalized game**). - **Valid game** - A game is a **Valid game** if it is not an **Invalid game**, and is a **Finalized game**. - **Latest valid game** - The latest valid game is a game whose anchor state is used to initialize new Fault Dispute Games. It was known to be a **valid game** when set. It will continue to be the latest valid game until updated with a more recent valid game, or blacklisted. - **Latest valid anchor state** - The latest valid anchor state is the output root of the latest valid game. +- **Dispute game finality delay** + - The dispute game finality delay is an **authorized input** representing the period of time between a dispute game resolving and a dispute game becoming finalized or valid. + - Also known as "air gap." ## Top-Level Invariants @@ -96,23 +104,41 @@ Furthermore, the AnchorStateRegistry is a crucial player in incident response. I ### Contract Dependents -This contract manages and exposes dispute game validity so that other contracts can do things like validate withdrawals and initialize dispute games correctly. +This contract manages and exposes dispute game validity so that other contracts can do things like correctly initialize dispute games and validate withdrawals. + +#### FaultDisputeGame + +A [FaultDisputeGame](fault-dispute-game.md) depends on this contract for a **latest valid anchor state** against which to resolve a claim and assumes its correct. Additionally, becauase proposers must gather L1 data for the window between the anchor state and the claimed state, FaultDisputeGames depend on this contract to keep a **latest valid anchor state** that's recent, so that proposer software is not overburdened (i.e. runs out of memory). + +#### OptimismPortal + +OptimismPortal depends on this contract to correctly report game validity as the basis for proving and finalizing withdrawals. -- This contract is the source of truth for the validity of an **anchor state**. - - [FaultDisputeGame](fault-dispute-game.md) and PermissionedDisputeGame depend on this contract for a **latest valid anchor state** against which to resolve a claim. These contracts assume the state is valid. -- Optimism Portal depends on this contract for accurate fault dispute game results. - - Can this dispute game can be used to prove a withdrawal? (Is the dispute game not an **invalid game**?) - - Can this dispute game can be used to finalize a withdrawal? (Is the dispute game a **valid game**?) +- Can this dispute game can be used to prove a withdrawal? (Is the dispute game a **maybe valid game**?) +- Can this dispute game can be used to finalize a withdrawal? (Is the dispute game a **valid game**?) ### Contract Dependencies #### FaultDisputeGame -- Only sets that special boolean if it actually is the respected game type. -- And the boolean never changes after it’s been set. -- Reports its game type correctly. -- Reports its l2BlockNumber correctly. -- Reports its createdAt timestamp correctly. +Depends on FaultDisputeGame to correctly report: + +- whether its game type was the respected game type when created (and that it never changes once set). +- its game type. +- its l2BlockNumber. +- its createdAt timestamp. + +#### DisputeGameFactory + +Depends on DisputeGameFactory to correctly report: + +- whether a game was created by the DisputeGameFactory (is "factory-registered"). + +#### SuperchainConfig + +Depends on SuperchainConfig to correctly report: + +- its guardian address. ## Function-Level Invariants @@ -132,9 +158,9 @@ Gets **latest valid game**. ### `updateLatestValidGame` -- Game must be **valid**. -- Block number for latest valid game must be higher than current latest valid game. -- This function is the ONLY way to update the latest valid game (after initialization). +- Game must be a **valid game**. +- Block number for candidate **valid game** must be higher than current **latest valid game**. +- This function is the ONLY way to update the **latest valid game** (after initialization). ### `getLatestAnchorState` @@ -143,17 +169,17 @@ Gets **latest valid game**. - Must maintain the property that the timestamp of the game is not too old. - TODO: How old is too old? -### `registerGameResult` +### `registerMaybeValidGame` -Stores the address of a not invalid dispute game in an array as a candidate for `latestValidGame`. +Stores the address of a **maybe valid game** in an array as a candidate for `latestValidGame`. -- Callable only by a not invalid game. -- Calling game must only register itself. -- TODO: +- Callable only by a **maybe valid game**. +- Calling game must only register itself (and not some other game). + - TODO: determine any invariants around registry ordering. ### `tryUpdateLatestValidGame` -Try update latest valid game based on previous game results. +Try to update **latest valid game** using registry of **maybe valid games**. - Callable by anyone. - Find the latest (comparing on l2BlockNumber) valid game you can find in the register within a fixed amount of gas. @@ -180,23 +206,23 @@ Returns whether the game is a **blacklisted game**. ### `setRespectedGameType` -- Must be **authorized** by . +- Must be **authorized** by _some role_. + +### `invalidateAllExistingGames` -### `updateValidityTimestamp` +Invalidates all games that exist. Note: until updated, the **latest valid game** (now invalidated) will still provide the **latest valid anchor state**. -- Must be **authorized** by . -- Must be greater than previous validity timestamp. -- Cannot be greater than current block timestamp. +- Must be **authorized** by _some role_. ### `setGameBlacklisted` Blacklists a game. -- Must be **authorized** by . +- Must be **authorized** by _some role_. ### `getGameFinalityDelay` -Returns **authorized** finality delay duration in seconds. No external dependent; public getter for convenience. +Returns **authorized** finality delay duration in seconds. No external dependents; public getter for convenience. ## Implementation diff --git a/specs/fault-proof/stage-one/dispute-game-interface.md b/specs/fault-proof/stage-one/dispute-game-interface.md index e4dcaa650..247488db3 100644 --- a/specs/fault-proof/stage-one/dispute-game-interface.md +++ b/specs/fault-proof/stage-one/dispute-game-interface.md @@ -305,5 +305,9 @@ interface IDisputeGame is IInitializable { /// @return rootClaim_ The root claim of the DisputeGame. /// @return extraData_ Any extra data supplied to the dispute game contract by the creator. function gameData() external view returns (GameType gameType_, Claim rootClaim_, bytes memory extraData_); + + /// @notice Returns whether this game's game type was the `respectedGameType` when created. + /// @return isRespectedGameType_ Whether this game's game type was the `respectedGameType` when created. + function isRespectedGameTypeWhenCreated() external view returns (bool isRespectedGameType_); } ``` diff --git a/specs/fault-proof/stage-one/fault-dispute-game.md b/specs/fault-proof/stage-one/fault-dispute-game.md index dd50424ef..f30b86392 100644 --- a/specs/fault-proof/stage-one/fault-dispute-game.md +++ b/specs/fault-proof/stage-one/fault-dispute-game.md @@ -11,7 +11,6 @@ - [Execution Trace](#execution-trace) - [Claims](#claims) - [Anchor State](#anchor-state) - - [Anchor State Registry](#anchor-state-registry) - [DAG](#dag) - [Subgame](#subgame) - [Game Tree](#game-tree) @@ -92,20 +91,7 @@ claims, committing to different output roots and FPVM states in the FDG. An anchor state, or anchor output root, is a previous output root that is assumed to be valid. An FDG is always initialized with an anchor state and execution is carried out between this anchor state and the [claimed output root](#claims). FDG contracts pull their anchor state from the -[Anchor State Registry](#anchor-state-registry) contract. The initial anchor state for a FDG is the -genesis state of the L2. - -Clients must currently gather L1 data for the window between the anchor state and the claimed -state. In order to reduce this L1 data requirement, [claims](#claims) about the state of the L2 -become new anchor states when dispute games resolve in their favor. FDG contracts set their anchor -states at initialization time so that these updates do not impact active games. - -### Anchor State Registry - -The Anchor State Registry is a registry that maps FDG types to their current [anchor states](#anchor-state). -The Anchor State Registry is specific to Fault Dispute Game contracts and may not be applicable to -other types of dispute game contracts that do not have the same concept of state that progresses -over time. +[Anchor State Registry](anchor-state-registry.md) contract. ### DAG diff --git a/specs/fault-proof/stage-one/optimism-portal.md b/specs/fault-proof/stage-one/optimism-portal.md index 2865f600d..975f88ab9 100644 --- a/specs/fault-proof/stage-one/optimism-portal.md +++ b/specs/fault-proof/stage-one/optimism-portal.md @@ -1,43 +1,98 @@ - **Table of Contents** - [Optimism Portal](#optimism-portal) - - [Overview (What this contract is actually supposed to do)](#overview-what-this-contract-is-actually-supposed-to-do) + - [Overview](#overview) + - [Perspective](#perspective) + - [Contract Dependencies](#contract-dependencies) + - [AnchorStateRegistry](#anchorstateregistry) + - [SuperchainConfig](#superchainconfig) + - [Contract Dependents](#contract-dependents) - [Definitions](#definitions) - [Top-Level Invariants](#top-level-invariants) - [Function-Level Invariants](#function-level-invariants) - - [Initialize the thing somehow](#initialize-the-thing-somehow) - - [Prove a withdrawal transaction](#prove-a-withdrawal-transaction) - - [Finalize a withdrawal transaction](#finalize-a-withdrawal-transaction) + - [`initialize`](#initialize) + - [`proveWithdrawalTransaction`](#provewithdrawaltransaction) + - [`finalizeWithdrawalTransaction`](#finalizewithdrawaltransaction) # Optimism Portal -## Overview (What this contract is actually supposed to do) +## Overview + +### Perspective + +This contract is responsible for moderating [withdrawals](../../protocol/withdrawals.md). + +### Contract Dependencies + +#### AnchorStateRegistry + +Depends on AnchorStateRegistry to correctly report: + +- Whether a game is an **invalid game**. +- Whether a game is a **valid game**. + +#### SuperchainConfig + +Depends on SuperchainConfig to correctly report: + +- System pause status. +- Guardian address. + +### Contract Dependents + +TODO ## Definitions +- **Authorized input** + - An input for which there is social consensus, i.e. coming from governance. +- **Proven withdrawal** +- **Finalized withdrawal** + ## Top-Level Invariants -- A withdrawal transaction must be proven against a game that is not `invalid`. -- A withdrawal transaction must be finalized against a game that is `valid`. +- A withdrawal transaction must be **proven** against a game that is not `invalid`. +- A withdrawal transaction may only be finalized against a game that is `valid`. + - Implicit in this is that a withdrawal transaction may only be finalized after the proof maturity delay has passed. +- A withdrawal transaction may only be finalized if it has already been **proven**. - A withdrawal transaction must be used only once to finalize a withdrawal. -- A withdrawal can only be finalized if it has been proven. - A withdrawal transaction that is finalized must attempt execution. # Function-Level Invariants -## Initialize the thing somehow +## `initialize` + +- Proof maturity delay seconds must be an **authorized input**. +- Anchor state registry must be an **authorized input**. +- Dispute game factory must be an **authorized input**. +- Superchain config must be an **authorized input**. +- System config must be an **authorized input**. + +## `proveWithdrawalTransaction` + +Proves a withdrawal transaction. + +- Withdrawal game must not be an **invalid game**. +- Withdrawal transaction's target must not be the OptimismPortal address. +- Withdrawal game's root claim must be equal to the hashed outputRootProof input. +- Must verify that the hash of this withdrawal is stored in the L2toL1MessagePasser contract on L2. +- A withdrawal can only be proven once unless the dispute game it proved against resolves against the favor of the root claim. +- Must add proof submitter to the list of proof submitters for this withdrawal hash. -- Need an **authorized** input for proof maturity delay seconds. -- Need an **authorized** reference to the anchor state registry. -- Need an **authorized** reference to the dispute game factory. -- Need an **authorized** input to system config. -- Need an **authorized** reference to superchain config. +## `finalizeWithdrawalTransaction` -## Prove a withdrawal transaction +Finalizes a withdrawal transaction that has already been proven. -## Finalize a withdrawal transaction +- Withdrawal transaction must have already been proven. +- The proof maturity delay duration must have elapsed between the time the withdrawal was proven and this call for its finalization. +- The time the withdrawal was proven must be greater than the time at which the withdrawal's game was created. +- Withdrawal transaction must not have been finalized before. +- The game upon which the withdrawal proof is based must be a **valid game**. +- Function must register the withdrawal as finalized. +- Function must revert when system is paused. +- TODO: withdrawal tx invariants (can't call token contract, exact balance must be transferred, estimator should revert for gas estimation) +- If these invariants are met, function must attempt execution of the withdrawal transaction. From 14e2aabc938584e2797e13309226efcc564f3964 Mon Sep 17 00:00:00 2001 From: wildmolasses Date: Thu, 5 Dec 2024 13:00:49 -0500 Subject: [PATCH 05/19] wip: formatting --- .../stage-one/anchor-state-registry.md | 44 +++++++++++++------ .../fault-proof/stage-one/optimism-portal.md | 14 +++--- 2 files changed, 39 insertions(+), 19 deletions(-) diff --git a/specs/fault-proof/stage-one/anchor-state-registry.md b/specs/fault-proof/stage-one/anchor-state-registry.md index cb835e0ce..570dc1684 100644 --- a/specs/fault-proof/stage-one/anchor-state-registry.md +++ b/specs/fault-proof/stage-one/anchor-state-registry.md @@ -1,5 +1,8 @@ +# Anchor State Registry + + **Table of Contents** - [Anchor State Registry](#anchor-state-registry) @@ -41,12 +44,10 @@ - [`isGameInvalid`](#isgameinvalid-1) - [`isGameValid`](#isgamevalid-1) - [`disputeGameFinalityDelaySeconds`](#disputegamefinalitydelayseconds) - - [`disputeGameFactory`](#disputegamefactory) + - [`disputeGameFactory`](#disputegamefactory-1) -# Anchor State Registry - ## Overview ### Perspective @@ -57,9 +58,11 @@ Multiple contracts in the fault proof system have critical dependencies on thing - A new dispute game needs to initialize with the **latest valid anchor state**. - An existing dispute game needs to know whether it is **invalid**, so it can refund its bonds. -The AnchorStateRegistry is these contracts' source of truth, managing and exposing dispute game and anchor state validity to moderate dispute games and withdrawals. +The AnchorStateRegistry is these contracts' source of truth, managing and exposing dispute game and anchor state +validity to moderate dispute games and withdrawals. -Furthermore, the AnchorStateRegistry is a crucial player in incident response. It can invalidate dispute games, thereby invalidating withdrawals and dispute games founded on an incorrect root claim. +Furthermore, the AnchorStateRegistry is a crucial player in incident response. It can invalidate dispute games, thereby +invalidating withdrawals and dispute games founded on an incorrect root claim. ## Definitions @@ -70,7 +73,8 @@ Furthermore, the AnchorStateRegistry is a crucial player in incident response. I - **Blacklisted game** - A dispute game is blacklisted if it is set as blacklisted via **authorized input**. - **Validity timestamp** - - The validity timestamp is a timestamp internal to the contract that partly determines game validity and can only be adjusted via **authorized input**. + - The validity timestamp is a timestamp internal to the contract that partly determines game validity and can only be + adjusted via **authorized input**. - **Invalid game** - A dispute game is invalid if any of the following are true: - Game was not created by the dispute game factory. @@ -88,31 +92,40 @@ Furthermore, the AnchorStateRegistry is a crucial player in incident response. I - **Valid game** - A game is a **Valid game** if it is not an **Invalid game**, and is a **Finalized game**. - **Latest valid game** - - The latest valid game is a game whose anchor state is used to initialize new Fault Dispute Games. It was known to be a **valid game** when set. It will continue to be the latest valid game until updated with a more recent valid game, or blacklisted. + - The latest valid game is a game whose anchor state is used to initialize new Fault Dispute Games. It was known to be + a **valid game** when set. It will continue to be the latest valid game until updated with a more recent valid game, + or blacklisted. - **Latest valid anchor state** - The latest valid anchor state is the output root of the latest valid game. - **Dispute game finality delay** - - The dispute game finality delay is an **authorized input** representing the period of time between a dispute game resolving and a dispute game becoming finalized or valid. + - The dispute game finality delay is an **authorized input** representing the period of time between a dispute game + resolving and a dispute game becoming finalized or valid. - Also known as "air gap." ## Top-Level Invariants - The contract will only assert **valid games** are valid. - The latest valid anchor state must never serve the output root of a blacklisted game. -- The latest valid anchor state must be recent enough so that the game doesn't break (run out of memory) in op-challenger. +- The latest valid anchor state must be recent enough so that the game doesn't break (run out of memory) in + op-challenger. - The validity timestamp must start at zero. ### Contract Dependents -This contract manages and exposes dispute game validity so that other contracts can do things like correctly initialize dispute games and validate withdrawals. +This contract manages and exposes dispute game validity so that other contracts can do things like correctly initialize +dispute games and validate withdrawals. #### FaultDisputeGame -A [FaultDisputeGame](fault-dispute-game.md) depends on this contract for a **latest valid anchor state** against which to resolve a claim and assumes its correct. Additionally, becauase proposers must gather L1 data for the window between the anchor state and the claimed state, FaultDisputeGames depend on this contract to keep a **latest valid anchor state** that's recent, so that proposer software is not overburdened (i.e. runs out of memory). +A [FaultDisputeGame](fault-dispute-game.md) depends on this contract for a **latest valid anchor state** against which +to resolve a claim and assumes its correct. Additionally, becauase proposers must gather L1 data for the window between +the anchor state and the claimed state, FaultDisputeGames depend on this contract to keep a **latest valid anchor +state** that's recent, so that proposer software is not overburdened (i.e. runs out of memory). #### OptimismPortal -OptimismPortal depends on this contract to correctly report game validity as the basis for proving and finalizing withdrawals. +OptimismPortal depends on this contract to correctly report game validity as the basis for proving and finalizing +withdrawals. - Can this dispute game can be used to prove a withdrawal? (Is the dispute game a **maybe valid game**?) - Can this dispute game can be used to finalize a withdrawal? (Is the dispute game a **valid game**?) @@ -154,7 +167,9 @@ Depends on SuperchainConfig to correctly report: Gets **latest valid game**. - Throws an error if the game is not valid. - - Depends on the condition that `update latest valid game` is the only method to update the “latest valid game” state variable and that it will only update the state variable with a **valid game**. Still, it is possible for the once valid game to become invalid (via blacklisting or `update validity timestamp`). + - Depends on the condition that `update latest valid game` is the only method to update the “latest valid game” state + variable and that it will only update the state variable with a **valid game**. Still, it is possible for the once + valid game to become invalid (via blacklisting or `update validity timestamp`). ### `updateLatestValidGame` @@ -210,7 +225,8 @@ Returns whether the game is a **blacklisted game**. ### `invalidateAllExistingGames` -Invalidates all games that exist. Note: until updated, the **latest valid game** (now invalidated) will still provide the **latest valid anchor state**. +Invalidates all games that exist. Note: until updated, the **latest valid game** (now invalidated) will still provide +the **latest valid anchor state**. - Must be **authorized** by _some role_. diff --git a/specs/fault-proof/stage-one/optimism-portal.md b/specs/fault-proof/stage-one/optimism-portal.md index 975f88ab9..790716dbd 100644 --- a/specs/fault-proof/stage-one/optimism-portal.md +++ b/specs/fault-proof/stage-one/optimism-portal.md @@ -1,5 +1,8 @@ +# Optimism Portal + + **Table of Contents** - [Optimism Portal](#optimism-portal) @@ -18,8 +21,6 @@ -# Optimism Portal - ## Overview ### Perspective @@ -80,7 +81,8 @@ Proves a withdrawal transaction. - Withdrawal transaction's target must not be the OptimismPortal address. - Withdrawal game's root claim must be equal to the hashed outputRootProof input. - Must verify that the hash of this withdrawal is stored in the L2toL1MessagePasser contract on L2. -- A withdrawal can only be proven once unless the dispute game it proved against resolves against the favor of the root claim. +- A withdrawal can only be proven once unless the dispute game it proved against resolves against the favor of the root + claim. - Must add proof submitter to the list of proof submitters for this withdrawal hash. ## `finalizeWithdrawalTransaction` @@ -88,11 +90,13 @@ Proves a withdrawal transaction. Finalizes a withdrawal transaction that has already been proven. - Withdrawal transaction must have already been proven. -- The proof maturity delay duration must have elapsed between the time the withdrawal was proven and this call for its finalization. +- The proof maturity delay duration must have elapsed between the time the withdrawal was proven and this call for its + finalization. - The time the withdrawal was proven must be greater than the time at which the withdrawal's game was created. - Withdrawal transaction must not have been finalized before. - The game upon which the withdrawal proof is based must be a **valid game**. - Function must register the withdrawal as finalized. - Function must revert when system is paused. -- TODO: withdrawal tx invariants (can't call token contract, exact balance must be transferred, estimator should revert for gas estimation) +- TODO: withdrawal tx invariants (can't call token contract, exact balance must be transferred, estimator should revert + for gas estimation) - If these invariants are met, function must attempt execution of the withdrawal transaction. From af03cb3be3286676abb2acb7566365723a12cba1 Mon Sep 17 00:00:00 2001 From: wildmolasses Date: Fri, 6 Dec 2024 14:29:04 -0500 Subject: [PATCH 06/19] wip: feedback --- .../stage-one/anchor-state-registry.md | 124 ++++++++---------- .../stage-one/dispute-game-interface.md | 2 +- .../fault-proof/stage-one/optimism-portal.md | 24 ++-- 3 files changed, 71 insertions(+), 79 deletions(-) diff --git a/specs/fault-proof/stage-one/anchor-state-registry.md b/specs/fault-proof/stage-one/anchor-state-registry.md index 570dc1684..37693c40e 100644 --- a/specs/fault-proof/stage-one/anchor-state-registry.md +++ b/specs/fault-proof/stage-one/anchor-state-registry.md @@ -5,46 +5,45 @@ **Table of Contents** -- [Anchor State Registry](#anchor-state-registry) - - [Overview](#overview) - - [Perspective](#perspective) - - [Definitions](#definitions) - - [Top-Level Invariants](#top-level-invariants) - - [Contract Dependents](#contract-dependents) - - [FaultDisputeGame](#faultdisputegame) - - [OptimismPortal](#optimismportal) - - [Contract Dependencies](#contract-dependencies) - - [FaultDisputeGame](#faultdisputegame-1) - - [DisputeGameFactory](#disputegamefactory) - - [SuperchainConfig](#superchainconfig) - - [Function-Level Invariants](#function-level-invariants) - - [`initialize`](#initialize) - - [`getLatestValidGame`](#getlatestvalidgame) - - [`updateLatestValidGame`](#updatelatestvalidgame) - - [`getLatestAnchorState`](#getlatestanchorstate) - - [`registerMaybeValidGame`](#registermaybevalidgame) - - [`tryUpdateLatestValidGame`](#tryupdatelatestvalidgame) - - [`isGameInvalid`](#isgameinvalid) - - [`isGameFinalized`](#isgamefinalized) - - [`isGameValid`](#isgamevalid) - - [`isGameBlacklisted`](#isgameblacklisted) - - [`setRespectedGameType`](#setrespectedgametype) - - [`invalidateAllExistingGames`](#invalidateallexistinggames) - - [`setGameBlacklisted`](#setgameblacklisted) - - [`getGameFinalityDelay`](#getgamefinalitydelay) - - [Implementation](#implementation) - - [`constructor`](#constructor) - - [`initialize`](#initialize-1) - - [`anchors` / `getLatestAnchorState`](#anchors--getlatestanchorstate) - - [`registerMaybeValidGame`](#registermaybevalidgame-1) - - [`updateLatestValidGame`](#updatelatestvalidgame-1) - - [`tryUpdateLatestValidGame`](#tryupdatelatestvalidgame-1) - - [`setGameBlacklisted`](#setgameblacklisted-1) - - [`setRespectedGameType`](#setrespectedgametype-1) - - [`isGameInvalid`](#isgameinvalid-1) - - [`isGameValid`](#isgamevalid-1) - - [`disputeGameFinalityDelaySeconds`](#disputegamefinalitydelayseconds) - - [`disputeGameFactory`](#disputegamefactory-1) +- [Overview](#overview) + - [Perspective](#perspective) +- [Definitions](#definitions) +- [Top-Level Invariants](#top-level-invariants) + - [Contract Dependents](#contract-dependents) + - [FaultDisputeGame](#faultdisputegame) + - [OptimismPortal](#optimismportal) + - [Contract Dependencies](#contract-dependencies) + - [FaultDisputeGame](#faultdisputegame-1) + - [DisputeGameFactory](#disputegamefactory) + - [SuperchainConfig](#superchainconfig) +- [Function-Level Invariants](#function-level-invariants) + - [`initialize`](#initialize) + - [`getLatestValidGame`](#getlatestvalidgame) + - [`updateLatestAnchorGame`](#updatelatestanchorgame) + - [`getLatestAnchorGame`](#getlatestanchorgame) + - [`registerMaybeValidGame`](#registermaybevalidgame) + - [`tryUpdateLatestValidGame`](#tryupdatelatestvalidgame) + - [`isGameInvalid`](#isgameinvalid) + - [`isGameFinalized`](#isgamefinalized) + - [`isGameValid`](#isgamevalid) + - [`isGameBlacklisted`](#isgameblacklisted) + - [`setRespectedGameType`](#setrespectedgametype) + - [`invalidateAllExistingGames`](#invalidateallexistinggames) + - [`setGameBlacklisted`](#setgameblacklisted) + - [`getGameFinalityDelay`](#getgamefinalitydelay) +- [Implementation](#implementation) + - [`constructor`](#constructor) + - [`initialize`](#initialize-1) + - [`anchors` / `getLatestAnchorState`](#anchors--getlatestanchorstate) + - [`registerMaybeValidGame`](#registermaybevalidgame-1) + - [`updateLatestValidGame`](#updatelatestvalidgame) + - [`tryUpdateLatestValidGame`](#tryupdatelatestvalidgame-1) + - [`setGameBlacklisted`](#setgameblacklisted-1) + - [`setRespectedGameType`](#setrespectedgametype-1) + - [`isGameInvalid`](#isgameinvalid-1) + - [`isGameValid`](#isgamevalid-1) + - [`disputeGameFinalityDelaySeconds`](#disputegamefinalitydelayseconds) + - [`disputeGameFactory`](#disputegamefactory) @@ -90,13 +89,11 @@ invalidating withdrawals and dispute games founded on an incorrect root claim. - **Maybe valid game** - A dispute game that is not an **invalid game** (but not yet a **finalized game**). - **Valid game** - - A game is a **Valid game** if it is not an **Invalid game**, and is a **Finalized game**. + - A game is a **valid game** if it is a **maybe valid game**, and is a **finalized game**. +- **Latest anchor game** + - A game is a **latest anchor game** if it had the highest l2BlockNumber from the set of valid games known by this contract. It must be a valid game at the time it it set, but can be an invalid game in one specific case. - **Latest valid game** - - The latest valid game is a game whose anchor state is used to initialize new Fault Dispute Games. It was known to be - a **valid game** when set. It will continue to be the latest valid game until updated with a more recent valid game, - or blacklisted. -- **Latest valid anchor state** - - The latest valid anchor state is the output root of the latest valid game. + - If the **latest anchor game** is a **valid game**, it is the **latest valid game**. Otherwise, there is no **latest valid game**. - **Dispute game finality delay** - The dispute game finality delay is an **authorized input** representing the period of time between a dispute game resolving and a dispute game becoming finalized or valid. @@ -105,9 +102,8 @@ invalidating withdrawals and dispute games founded on an incorrect root claim. ## Top-Level Invariants - The contract will only assert **valid games** are valid. -- The latest valid anchor state must never serve the output root of a blacklisted game. -- The latest valid anchor state must be recent enough so that the game doesn't break (run out of memory) in - op-challenger. +- The latest anchor game must never serve the output root of a blacklisted game. +- The latest anchor game must be recent enough so that the game doesn't break (run out of memory) in op-challenger. - The validity timestamp must start at zero. ### Contract Dependents @@ -140,6 +136,7 @@ Depends on FaultDisputeGame to correctly report: - its game type. - its l2BlockNumber. - its createdAt timestamp. +- its resolvedAt timestamp. #### DisputeGameFactory @@ -164,23 +161,19 @@ Depends on SuperchainConfig to correctly report: ### `getLatestValidGame` -Gets **latest valid game**. +Returns **latest valid game**, or reverts if there is no **latest valid game**. -- Throws an error if the game is not valid. - - Depends on the condition that `update latest valid game` is the only method to update the “latest valid game” state - variable and that it will only update the state variable with a **valid game**. Still, it is possible for the once - valid game to become invalid (via blacklisting or `update validity timestamp`). - -### `updateLatestValidGame` +### `updateLatestAnchorGame` - Game must be a **valid game**. -- Block number for candidate **valid game** must be higher than current **latest valid game**. -- This function is the ONLY way to update the **latest valid game** (after initialization). +- Game's block number must be higher than current **latest anchor game**. +- This function is the ONLY way to update the **latest anchor game** (after initialization). + +### `getLatestAnchorGame` -### `getLatestAnchorState` +Returns the **latest anchor game**. -- If the **latest valid game** is not blacklisted, return its root claim and l2 block number. -- If the **latest valid game** is blacklisted, throw an error. +- Must revert if the **latest anchor game** is blacklisted. - Must maintain the property that the timestamp of the game is not too old. - TODO: How old is too old? @@ -221,20 +214,19 @@ Returns whether the game is a **blacklisted game**. ### `setRespectedGameType` -- Must be **authorized** by _some role_. +- Must be **authorized** by guardian role. ### `invalidateAllExistingGames` -Invalidates all games that exist. Note: until updated, the **latest valid game** (now invalidated) will still provide -the **latest valid anchor state**. +Invalidates all games that exist. -- Must be **authorized** by _some role_. +- Must be **authorized** by guardian role. ### `setGameBlacklisted` Blacklists a game. -- Must be **authorized** by _some role_. +- Must be **authorized** by guardian role. ### `getGameFinalityDelay` diff --git a/specs/fault-proof/stage-one/dispute-game-interface.md b/specs/fault-proof/stage-one/dispute-game-interface.md index 247488db3..d7ecb6718 100644 --- a/specs/fault-proof/stage-one/dispute-game-interface.md +++ b/specs/fault-proof/stage-one/dispute-game-interface.md @@ -308,6 +308,6 @@ interface IDisputeGame is IInitializable { /// @notice Returns whether this game's game type was the `respectedGameType` when created. /// @return isRespectedGameType_ Whether this game's game type was the `respectedGameType` when created. - function isRespectedGameTypeWhenCreated() external view returns (bool isRespectedGameType_); + function wasRespectedGameTypeWhenCreated() external view returns (bool wasRespectedGameType_); } ``` diff --git a/specs/fault-proof/stage-one/optimism-portal.md b/specs/fault-proof/stage-one/optimism-portal.md index 790716dbd..f79198f70 100644 --- a/specs/fault-proof/stage-one/optimism-portal.md +++ b/specs/fault-proof/stage-one/optimism-portal.md @@ -2,10 +2,8 @@ - **Table of Contents** -- [Optimism Portal](#optimism-portal) - [Overview](#overview) - [Perspective](#perspective) - [Contract Dependencies](#contract-dependencies) @@ -51,17 +49,20 @@ TODO - **Authorized input** - An input for which there is social consensus, i.e. coming from governance. + - **Proven withdrawal** + - + - **Finalized withdrawal** ## Top-Level Invariants -- A withdrawal transaction must be **proven** against a game that is not `invalid`. -- A withdrawal transaction may only be finalized against a game that is `valid`. +- A withdrawal transaction must be **proven** against a game that is **maybe valid**. +- A withdrawal transaction may only be finalized against a game that is **valid**. - Implicit in this is that a withdrawal transaction may only be finalized after the proof maturity delay has passed. - A withdrawal transaction may only be finalized if it has already been **proven**. -- A withdrawal transaction must be used only once to finalize a withdrawal. -- A withdrawal transaction that is finalized must attempt execution. +- A withdrawal transaction must be used only once to **finalize** a withdrawal. +- A withdrawal transaction that is **finalized** must attempt execution. # Function-Level Invariants @@ -77,13 +78,13 @@ TODO Proves a withdrawal transaction. -- Withdrawal game must not be an **invalid game**. +- Withdrawal game must not be a **maybe valid game**. - Withdrawal transaction's target must not be the OptimismPortal address. - Withdrawal game's root claim must be equal to the hashed outputRootProof input. - Must verify that the hash of this withdrawal is stored in the L2toL1MessagePasser contract on L2. -- A withdrawal can only be proven once unless the dispute game it proved against resolves against the favor of the root - claim. -- Must add proof submitter to the list of proof submitters for this withdrawal hash. +- A withdrawal cannot be reproved by the same proof submitter unless both of the following are true: + - the dispute game previously used to prove the withdrawal is now an invalid game. + - the withdrawal was never finalized. ## `finalizeWithdrawalTransaction` @@ -92,10 +93,9 @@ Finalizes a withdrawal transaction that has already been proven. - Withdrawal transaction must have already been proven. - The proof maturity delay duration must have elapsed between the time the withdrawal was proven and this call for its finalization. -- The time the withdrawal was proven must be greater than the time at which the withdrawal's game was created. +- The time the withdrawal was proven must be greater or equal to the time at which the withdrawal's game was created. - Withdrawal transaction must not have been finalized before. - The game upon which the withdrawal proof is based must be a **valid game**. -- Function must register the withdrawal as finalized. - Function must revert when system is paused. - TODO: withdrawal tx invariants (can't call token contract, exact balance must be transferred, estimator should revert for gas estimation) From dd3b97cdde27bef64c82d3f99188e215641f8cd3 Mon Sep 17 00:00:00 2001 From: wildmolasses Date: Wed, 11 Dec 2024 13:16:11 -0500 Subject: [PATCH 07/19] wip: ASR --- .../stage-one/anchor-state-registry.md | 364 +++++++++++++----- .../fault-proof/stage-one/bond-incentives.md | 29 +- 2 files changed, 281 insertions(+), 112 deletions(-) diff --git a/specs/fault-proof/stage-one/anchor-state-registry.md b/specs/fault-proof/stage-one/anchor-state-registry.md index 37693c40e..1d6d699ae 100644 --- a/specs/fault-proof/stage-one/anchor-state-registry.md +++ b/specs/fault-proof/stage-one/anchor-state-registry.md @@ -2,45 +2,73 @@ - **Table of Contents** - [Overview](#overview) - [Perspective](#perspective) - [Definitions](#definitions) + - [Dispute game](#dispute-game) + - [Likely valid game](#likely-valid-game) + - [Finalized game](#finalized-game) + - [Dispute game finality delay](#dispute-game-finality-delay) + - [Valid game](#valid-game) + - [Blacklisted game](#blacklisted-game) + - [Retired valid game](#retired-valid-game) + - [Validity timestamp](#validity-timestamp) + - [Anchor state](#anchor-state) + - [Anchor game](#anchor-game) + - [Withdrawal](#withdrawal) + - [Authorized input](#authorized-input) +- [Assumptions](#assumptions) + - [aFDG-001: Fault dispute games correctly report their properties](#afdg-001-fault-dispute-games-correctly-report-their-properties) + - [Mitigations](#mitigations) + - [aFDG-002: Fault dispute games with correct claims resolve correctly at some regular rate](#afdg-002-fault-dispute-games-with-correct-claims-resolve-correctly-at-some-regular-rate) + - [Mitigations](#mitigations-1) + - [aDGF-001: Dispute game factory correctly identifies the games it created](#adgf-001-dispute-game-factory-correctly-identifies-the-games-it-created) + - [Mitigations](#mitigations-2) + - [aDGF-002: Games created by the DisputeGameFactory will be monitored](#adgf-002-games-created-by-the-disputegamefactory-will-be-monitored) + - [Mitigations](#mitigations-3) + - [aASR-001: Incorrectly resolving games will be blacklisted within the dispute game finality delay period](#aasr-001-incorrectly-resolving-games-will-be-blacklisted-within-the-dispute-game-finality-delay-period) + - [Mitigations](#mitigations-4) + - [aASR-002: Larger bugs in dispute game mechanics will be expired within the dispute game finality delay period](#aasr-002-larger-bugs-in-dispute-game-mechanics-will-be-expired-within-the-dispute-game-finality-delay-period) + - [Mitigations](#mitigations-5) + - [aASR-003: The AnchorStateRegistry will be correctly initialized at deployment](#aasr-003-the-anchorstateregistry-will-be-correctly-initialized-at-deployment) + - [Mitigations](#mitigations-6) + - [aSC-001: SuperchainConfig correctly reports its guardian address](#asc-001-superchainconfig-correctly-reports-its-guardian-address) + - [Mitigations](#mitigations-7) - [Top-Level Invariants](#top-level-invariants) - - [Contract Dependents](#contract-dependents) - - [FaultDisputeGame](#faultdisputegame) - - [OptimismPortal](#optimismportal) - - [Contract Dependencies](#contract-dependencies) - - [FaultDisputeGame](#faultdisputegame-1) - - [DisputeGameFactory](#disputegamefactory) - - [SuperchainConfig](#superchainconfig) +- [System Invariants](#system-invariants) + - [iASR-001: Claims about L2 state are validated before they're used by dependents.](#iasr-001-claims-about-l2-state-are-validated-before-theyre-used-by-dependents) +- [Component Invariants](#component-invariants) + - [iASR-000: Only "truly" **valid games** will be represented as **valid games**.](#iasr-000-only-truly-valid-games-will-be-represented-as-valid-games) + - [Impact](#impact) + - [Dependencies](#dependencies) - [Function-Level Invariants](#function-level-invariants) + - [`constructor`](#constructor) - [`initialize`](#initialize) - [`getLatestValidGame`](#getlatestvalidgame) - - [`updateLatestAnchorGame`](#updatelatestanchorgame) - - [`getLatestAnchorGame`](#getlatestanchorgame) - - [`registerMaybeValidGame`](#registermaybevalidgame) - - [`tryUpdateLatestValidGame`](#tryupdatelatestvalidgame) - - [`isGameInvalid`](#isgameinvalid) + - [`updateAnchorGame`](#updateanchorgame) + - [`getAnchorGame`](#getanchorgame) + - [`registerLikelyValidGame`](#registerlikelyvalidgame) + - [`tryUpdateAnchorGame`](#tryupdateanchorgame) + - [`isGameBlacklisted`](#isgameblacklisted) + - [`isGameLikelyValid`](#isgamelikelyvalid) - [`isGameFinalized`](#isgamefinalized) - [`isGameValid`](#isgamevalid) - - [`isGameBlacklisted`](#isgameblacklisted) - [`setRespectedGameType`](#setrespectedgametype) - - [`invalidateAllExistingGames`](#invalidateallexistinggames) + - [`retireAllExistingGames`](#retireallexistinggames) - [`setGameBlacklisted`](#setgameblacklisted) - [`getGameFinalityDelay`](#getgamefinalitydelay) - [Implementation](#implementation) - - [`constructor`](#constructor) + - [`constructor`](#constructor-1) - [`initialize`](#initialize-1) - [`anchors` / `getLatestAnchorState`](#anchors--getlatestanchorstate) - - [`registerMaybeValidGame`](#registermaybevalidgame-1) + - [`registerMaybeValidGame`](#registermaybevalidgame) - [`updateLatestValidGame`](#updatelatestvalidgame) - - [`tryUpdateLatestValidGame`](#tryupdatelatestvalidgame-1) + - [`tryUpdateLatestValidGame`](#tryupdatelatestvalidgame) - [`setGameBlacklisted`](#setgameblacklisted-1) - [`setRespectedGameType`](#setrespectedgametype-1) - - [`isGameInvalid`](#isgameinvalid-1) + - [`isGameInvalid`](#isgameinvalid) - [`isGameValid`](#isgamevalid-1) - [`disputeGameFinalityDelaySeconds`](#disputegamefinalitydelayseconds) - [`disputeGameFactory`](#disputegamefactory) @@ -51,6 +79,31 @@ ### Perspective +The whole point of the fault proof system is to create correctly resolving games whose claims we can depend on to +finalize withdrawals (or other L2-to-L1 dependents). Indeed, everything about the system, from the contract mechanics to +bond incentives, is engineered to provide complete confidence that the outcome of a resolved game is correct. Yet, there +are corner cases where the resolved game rebukes its platonic, game-theoretic ideal, resolving incorrectly. The anchor +state registry appreciates this and affords games and their dependents probabalistic validity by enforcing a game +finality delay, and adding additional dependencies like blacklisting and game retirement. These concessions improve the +confidence in resolved games, and calcify the assumptions upon which withdrawals and other dependents rest. + + ## Definitions -- **Anchor state** - - See [Fault Dispute Game -> Anchor State](fault-dispute-game.md#anchor-state). -- **Authorized input** - - An input for which there is social consensus, i.e. coming from governance. -- **Blacklisted game** - - A dispute game is blacklisted if it is set as blacklisted via **authorized input**. -- **Validity timestamp** - - The validity timestamp is a timestamp internal to the contract that partly determines game validity and can only be - adjusted via **authorized input**. -- **Invalid game** - - A dispute game is invalid if any of the following are true: - - Game was not created by the dispute game factory. - - Game was not created while it was the respected game type. - - Game is **blacklisted**. - - Game was created before the **validity timestamp**. - - Game status is `CHALLENGER_WINS`. -- **Finalized game** - - A dispute game is finalized if all of the following are true: - - Game status is `CHALLENGER_WINS` or `DEFENDER_WINS`. - - Game `resolvedAt` timestamp is not zero. - - Game `resolvedAt` timestamp is more than `dispute game finality delay` seconds ago. -- **Maybe valid game** - - A dispute game that is not an **invalid game** (but not yet a **finalized game**). -- **Valid game** - - A game is a **valid game** if it is a **maybe valid game**, and is a **finalized game**. -- **Latest anchor game** - - A game is a **latest anchor game** if it had the highest l2BlockNumber from the set of valid games known by this contract. It must be a valid game at the time it it set, but can be an invalid game in one specific case. -- **Latest valid game** - - If the **latest anchor game** is a **valid game**, it is the **latest valid game**. Otherwise, there is no **latest valid game**. -- **Dispute game finality delay** - - The dispute game finality delay is an **authorized input** representing the period of time between a dispute game - resolving and a dispute game becoming finalized or valid. - - Also known as "air gap." +### Dispute game -## Top-Level Invariants +> See [Fault Dispute Game](fault-dispute-game.md) -- The contract will only assert **valid games** are valid. -- The latest anchor game must never serve the output root of a blacklisted game. -- The latest anchor game must be recent enough so that the game doesn't break (run out of memory) in op-challenger. -- The validity timestamp must start at zero. +A dispute game is a contract that resolves an L2 state claim. -### Contract Dependents +### Likely valid game -This contract manages and exposes dispute game validity so that other contracts can do things like correctly initialize -dispute games and validate withdrawals. +A **likely valid game** is a dispute game that correctly resolved in favor of the defender. However, the system concedes +a possibility that it's not correct, and so it's not yet ready to be used as a **valid game** by dependents. A likely +valid game meets the following conditions: -#### FaultDisputeGame +- Game was created by the dispute game factory. +- Game is not **blacklisted**. +- Game was created while it was the respected game type. +- Game status is not `CHALLENGER_WINS`. +- Game was created after the **validity timestamp**. -A [FaultDisputeGame](fault-dispute-game.md) depends on this contract for a **latest valid anchor state** against which -to resolve a claim and assumes its correct. Additionally, becauase proposers must gather L1 data for the window between -the anchor state and the claimed state, FaultDisputeGames depend on this contract to keep a **latest valid anchor -state** that's recent, so that proposer software is not overburdened (i.e. runs out of memory). +### Finalized game -#### OptimismPortal +A finalized dispute game is a game that has been resolved in favor of either the challenger or defender. Furthermore, it +has passed the **dispute game finality delay** and can be used by dependents. A finalized game meets the following +conditions: -OptimismPortal depends on this contract to correctly report game validity as the basis for proving and finalizing -withdrawals. +- Game status is `CHALLENGER_WINS` or `DEFENDER_WINS`. +- Game `resolvedAt` timestamp is not zero. +- Game `resolvedAt` timestamp is more than `dispute game finality delay` seconds ago. -- Can this dispute game can be used to prove a withdrawal? (Is the dispute game a **maybe valid game**?) -- Can this dispute game can be used to finalize a withdrawal? (Is the dispute game a **valid game**?) +### Dispute game finality delay + +> Also known as "air gap." + +The dispute game finality delay is the period of time between a dispute game +resolving and a dispute game becoming finalized. It's set via **authorized input**. + +### Valid game -### Contract Dependencies +A game is a **valid game** if it, among other qualitifcations, has resolved in favor of the defender and has also matured past +the finality delay. In other words, it meets the conditions of both a **likely valid game** and a **finalized game**. -#### FaultDisputeGame +### Blacklisted game -Depends on FaultDisputeGame to correctly report: +A blacklisted game is a game that has been set as blacklisted via **authorized action**. It must not be considered +valid, and must not be used for finalizing withdrawals or any other dependent L2-to-L1 action. + +### Retired valid game + +A retired valid game is a dispute game whose `createdAt` timestamp is older than the **validity timestamp**. + +### Validity timestamp + +The validity timestamp is a timestamp internal to the contract that partly determines game validity and can only be +adjusted via **authorized input**. + +### Anchor state + +> See [Fault Dispute Game -> Anchor State](fault-dispute-game.md#anchor-state). + +An anchor state is a state root from L2. + +### Anchor game + +An **anchor game** is a game upon which other games should build. It was a **valid game** when it was set, but may have +since been retired. + +### Withdrawal + +> See [Withdrawals](../../protocol/withdrawals.md). + +A withdrawal is a cross-chain transaction initiated on L2, and finalized on L1. + +### Authorized input + +An authorized input is an input for which there is social consensus, i.e. coming from governance. + +## Assumptions + +> **NOTE:** Assumptions are utilized by specific invariants and do not apply globally. Invariants typically only rely on +> a subset of the following assumptions. Different invariants may rely on different assumptions. Refer to individual +> invariants for their dependencies. + +### aFDG-001: Fault dispute games correctly report their properties + +We assume that a fault dispute game will correctly report the following properties: -- whether its game type was the respected game type when created (and that it never changes once set). - its game type. -- its l2BlockNumber. -- its createdAt timestamp. -- its resolvedAt timestamp. +- whether its game type was the respected game type when created (also assumes this is set once and never changes). +- the l2BlockNumber of its root claim. +- its `createdAt` timestamp. +- its `resolvedAt` timestamp. + +#### Mitigations + +- Existing audit on `FaultDisputeGame`. Note: Existing audit does not yet cover the second property above (that a game correctly reports whether its game type was the respected game type when created). +- Integration testing. + +### aFDG-002: Fault dispute games with correct claims resolve correctly at some regular rate + +We assume that fault dispute games will regularly resolve in favor of the defender correctly. While the system +can handle games that resolve in favor of the challenger, as well as incorrect resolutions, there must be other games that resolve correctly to maintain the system's integrity. + +#### Mitigations + +- Existing incentives in fault proof system design. + +### aDGF-001: Dispute game factory correctly identifies the games it created -#### DisputeGameFactory +We assume that DisputeGameFactory will correctly identify whether it created a game (i.e. whether the game is "factory-registered"). -Depends on DisputeGameFactory to correctly report: +### Mitigations -- whether a game was created by the DisputeGameFactory (is "factory-registered"). +- Existing audit on the `DisputeGameFactory`. +- Integration testing. -#### SuperchainConfig +### aDGF-002: Games created by the DisputeGameFactory will be monitored -Depends on SuperchainConfig to correctly report: +We assume that games created by the DisputeGameFactory will be monitored for incorrect resolution. -- its guardian address. +#### Mitigations + +- Stakeholder incentives. + +### aASR-001: Incorrectly resolving games will be blacklisted within the dispute game finality delay period + +We assume that games that resolve incorrectly will be blacklisted via **authorized action** within the dispute game finality delay period. This further depends on [aDGF-002](#adgf-002-games-created-by-the-disputegamefactory-will-be-monitored). + +#### Mitigations + +- Stakeholder incentives / processes. + +### aASR-002: Larger bugs in dispute game mechanics will be expired within the dispute game finality delay period + +We assume that a larger bug affecting many games will be noticed via monitoring ([aDGF-002](#adgf-002-games-created-by-the-disputegamefactory-will-be-monitored)) and will be expired within the dispute game finality delay period. + +#### Mitigations + +- Stakeholder incentives / processes. + +### aASR-003: The AnchorStateRegistry will be correctly initialized at deployment + +We assume that the AnchorStateRegistry will be correctly initialized at deployment, including: + +- Address of initial anchor game. +- Address of `DisputeGameFactory`. +- An appropriate `DISPUTE_GAME_FINALITY_DELAY`. +- Address of `SuperchainConfig`. + +#### Mitigations + +- Verify the configured values in the deployment script. + +### aSC-001: SuperchainConfig correctly reports its guardian address + +We assume the SuperchainConfig contract correctly returns its guardian address. + +#### Mitigations + +- Existing audit on the `SuperchainConfig`. +- Integration testing. + +## Top-Level Invariants + +- When asked for a **valid game**, the contract will only serve games that truly resolved correctly to its dependents. +- The latest anchor game must never serve the output root of a blacklisted game. +- The latest anchor game must be recent enough so that the game doesn't break (run out of memory) in op-challenger. +- The validity timestamp must start at zero. + +## System Invariants + +### iASR-001: Claims about L2 state are validated before they're used by dependents. + +## Component Invariants + +### iASR-000: Only "truly" **valid games** will be represented as **valid games**. + +When asked for a **valid game** by its dependents, the contract will only serve **valid games** that "truly" resolved in +favor of defender. + +#### Impact + +**Severity: High** + +If this invariant is broken, an L2 state that's different from what dependents can be tricked into finalizing withdrawals based on incorrect state roots. + +#### Dependencies + +[FaultDisputeGame](./fault-dispute-game.md) depends on this contract for an **anchor game** against which to +resolve its claim. The contract assumes this **anchor game**'s state root is correct, and that it's recent enough that +proposer software doesn't run out of memory. + +[OptimismPortal](./optimism-portal.md) depends on this contract to correctly report game validity as the basis for +proving and finalizing withdrawals. + +- Can this dispute game can be used to prove a withdrawal? (Is the dispute game a **likely valid game**?) +- Can this dispute game can be used to finalize a withdrawal? (Is the dispute game a **valid game**?) ## Function-Level Invariants +### `constructor` + +The constructor must disable the initializer on the implementation contract. + ### `initialize` - Initial anchor state must be an **authorized input**. @@ -163,13 +331,13 @@ Depends on SuperchainConfig to correctly report: Returns **latest valid game**, or reverts if there is no **latest valid game**. -### `updateLatestAnchorGame` +### `updateAnchorGame` - Game must be a **valid game**. - Game's block number must be higher than current **latest anchor game**. - This function is the ONLY way to update the **latest anchor game** (after initialization). -### `getLatestAnchorGame` +### `getAnchorGame` Returns the **latest anchor game**. @@ -177,7 +345,7 @@ Returns the **latest anchor game**. - Must maintain the property that the timestamp of the game is not too old. - TODO: How old is too old? -### `registerMaybeValidGame` +### `registerLikelyValidGame` Stores the address of a **maybe valid game** in an array as a candidate for `latestValidGame`. @@ -185,7 +353,7 @@ Stores the address of a **maybe valid game** in an array as a candidate for `lat - Calling game must only register itself (and not some other game). - TODO: determine any invariants around registry ordering. -### `tryUpdateLatestValidGame` +### `tryUpdateAnchorGame` Try to update **latest valid game** using registry of **maybe valid games**. @@ -194,9 +362,13 @@ Try to update **latest valid game** using registry of **maybe valid games**. - Fixed gas amount ensures that this function does not get more expensive to call as time goes on. - Use this as input to `update latest valid game`. -### `isGameInvalid` +### `isGameBlacklisted` + +Returns whether the game is a **blacklisted game**. + +### `isGameLikelyValid` -Returns whether the game is an **invalid game**. +Returns whether the game is a **likely valid game**. ### `isGameFinalized` @@ -204,21 +376,17 @@ Returns whether the game is a **finalized game**. ### `isGameValid` -`return !isGameInvalid(game) && isGameFinalized(game)` - -Definition of **valid** is this condition passing. +Returns whether the game is a **valid game**. -### `isGameBlacklisted` - -Returns whether the game is a **blacklisted game**. +Assumes ### `setRespectedGameType` - Must be **authorized** by guardian role. -### `invalidateAllExistingGames` +### `retireAllExistingGames` -Invalidates all games that exist. +Retires all games that exist. - Must be **authorized** by guardian role. diff --git a/specs/fault-proof/stage-one/bond-incentives.md b/specs/fault-proof/stage-one/bond-incentives.md index 0fdd5c4c5..bb2a3f204 100644 --- a/specs/fault-proof/stage-one/bond-incentives.md +++ b/specs/fault-proof/stage-one/bond-incentives.md @@ -76,9 +76,9 @@ proof system. ### Authenticated Roles -| Name | Description | -| ------------ | ----------------------------------------------------------------------------------------------------- | -| Guardian | Role responsible for blacklisting dispute game contracts and changing the respected dispute game type | +| Name | Description | +| ---- | ----------- | +| Guardian | Role responsible for blacklisting dispute game contracts and changing the respected dispute game type | | System Owner | Role that owns the `ProxyAdmin` contract that in turn owns most `Proxy` contracts within the OP Stack | ### Base Fee Assumption @@ -139,18 +139,19 @@ incorrectly distribute bonds. - `DelayedWETH` has an `owner()` address. We typically expect this to be set to the `System Owner` address. - `DelayedWETH` has a `delay()` function that returns a period of time that withdrawals will be delayed. - `DelayedWETH` has an `unlock(guy,wad)` function that modifies a mapping called `withdrawals` keyed as - `withdrawals[msg.sender][guy] => WithdrawalRequest` where `WithdrawalRequest` is - `struct Withdrawal Request { uint256 amount, uint256 timestamp }`. When `unlock` is called, the timestamp for - `withdrawals[msg.sender][guy]` is set to the current timestamp and the amount is increased by the given amount. -- `DelayedWETH` modifies the `WETH.withdraw` function such that an address _must_ provide a "sub-account" to withdraw - from. The function signature becomes `withdraw(guy,wad)`. The function retrieves `withdrawals[msg.sender][guy]` and - checks that the current `block.timestamp` is greater than the timestamp on the withdrawal request plus the `delay()` - seconds and reverts if not. It also confirms that the amount being withdrawn is less than the amount in the withdrawal - request. Before completing the withdrawal, it reduces the amount contained within the withdrawal request. The original - `withdraw(wad)` function becomes an alias for `withdraw(msg.sender, wad)`. - `withdraw(guy,wad)` will not be callable when `SuperchainConfig.paused()` is `true`. +`withdrawals[msg.sender][guy] => WithdrawalRequest` where `WithdrawalRequest` is +`struct Withdrawal Request { uint256 amount, uint256 timestamp }`. When `unlock` is called, the timestamp for +`withdrawals[msg.sender][guy]` is set to the current timestamp and the amount is increased by the given amount. +- `DelayedWETH` modifies the `WETH.withdraw` function such that an address *must* provide a "sub-account" to withdraw +from. The function signature becomes `withdraw(guy,wad)`. The function retrieves `withdrawals[msg.sender][guy]` and +checks that the current `block.timestamp` is greater than the timestamp on the withdrawal request plus the `delay()` +seconds and reverts if not. It also confirms that the amount being withdrawn is less than the amount in the withdrawal +request. Before completing the withdrawal, it reduces the amount contained within the withdrawal request. The original +`withdraw(wad)` function becomes an alias for `withdraw(msg.sender, wad)`. +`withdraw(guy,wad)` will not be callable when `SuperchainConfig.paused()` is `true`. - `DelayedWETH` has a `hold()` function that allows the `owner()` address to give itself an allowance from any address. -- `DelayedWETH` has a `recover()` function that allows the `owner()` address to recover any amount of ETH from the contract. +- `DelayedWETH` has a `recover()` function that allows the `owner()` address to recover any amount of ETH from the +contract. #### Sub-Account Model From 624f4f2a033df32f0063696b4c38fe40f798760c Mon Sep 17 00:00:00 2001 From: wildmolasses Date: Wed, 11 Dec 2024 15:23:55 -0500 Subject: [PATCH 08/19] wip: more ASR --- .../stage-one/anchor-state-registry.md | 217 ++++++++++++------ 1 file changed, 141 insertions(+), 76 deletions(-) diff --git a/specs/fault-proof/stage-one/anchor-state-registry.md b/specs/fault-proof/stage-one/anchor-state-registry.md index 1d6d699ae..94b02da46 100644 --- a/specs/fault-proof/stage-one/anchor-state-registry.md +++ b/specs/fault-proof/stage-one/anchor-state-registry.md @@ -13,8 +13,9 @@ - [Dispute game finality delay](#dispute-game-finality-delay) - [Valid game](#valid-game) - [Blacklisted game](#blacklisted-game) - - [Retired valid game](#retired-valid-game) - - [Validity timestamp](#validity-timestamp) + - [Invalid game](#invalid-game) + - [Retired game](#retired-game) + - [Game retirement timestamp](#game-retirement-timestamp) - [Anchor state](#anchor-state) - [Anchor game](#anchor-game) - [Withdrawal](#withdrawal) @@ -38,15 +39,27 @@ - [Mitigations](#mitigations-7) - [Top-Level Invariants](#top-level-invariants) - [System Invariants](#system-invariants) - - [iASR-001: Claims about L2 state are validated before they're used by dependents.](#iasr-001-claims-about-l2-state-are-validated-before-theyre-used-by-dependents) -- [Component Invariants](#component-invariants) - - [iASR-000: Only "truly" **valid games** will be represented as **valid games**.](#iasr-000-only-truly-valid-games-will-be-represented-as-valid-games) + - [iASR-001: Games that make correct claims about L2 state can be distinguished from games that do not.](#iasr-001-games-that-make-correct-claims-about-l2-state-can-be-distinguished-from-games-that-do-not) - [Impact](#impact) - [Dependencies](#dependencies) + - [iASR-002: Valid withdrawals can be finalized within some bounded amount of time](#iasr-002-valid-withdrawals-can-be-finalized-within-some-bounded-amount-of-time) + - [Impact](#impact-1) + - [Dependencies](#dependencies-1) +- [Component Invariants](#component-invariants) + - [iASR-003: Only "truly" **valid games** will be represented as **valid games**.](#iasr-003-only-truly-valid-games-will-be-represented-as-valid-games) + - [Impact](#impact-2) + - [Dependencies](#dependencies-2) + - [iASR-004: The anchor game was created recently, within some bounded time period.](#iasr-004-the-anchor-game-was-created-recently-within-some-bounded-time-period) + - [Impact](#impact-3) + - [Dependencies](#dependencies-3) + - [iASR-005: The anchor game is a game whose claim is correct.](#iasr-005-the-anchor-game-is-a-game-whose-claim-is-correct) + - [Impact](#impact-4) + - [Dependencies](#dependencies-4) - [Function-Level Invariants](#function-level-invariants) +- [Implementation Spec](#implementation-spec) - [`constructor`](#constructor) - [`initialize`](#initialize) - - [`getLatestValidGame`](#getlatestvalidgame) + - [`getRecentValidGame`](#getrecentvalidgame) - [`updateAnchorGame`](#updateanchorgame) - [`getAnchorGame`](#getanchorgame) - [`registerLikelyValidGame`](#registerlikelyvalidgame) @@ -87,35 +100,6 @@ state registry appreciates this and affords games and their dependents probabali finality delay, and adding additional dependencies like blacklisting and game retirement. These concessions improve the confidence in resolved games, and calcify the assumptions upon which withdrawals and other dependents rest. - - ## Definitions ### Dispute game @@ -134,7 +118,6 @@ valid game meets the following conditions: - Game is not **blacklisted**. - Game was created while it was the respected game type. - Game status is not `CHALLENGER_WINS`. -- Game was created after the **validity timestamp**. ### Finalized game @@ -150,27 +133,32 @@ conditions: > Also known as "air gap." -The dispute game finality delay is the period of time between a dispute game -resolving and a dispute game becoming finalized. It's set via **authorized input**. +The dispute game finality delay is the period of time between a dispute game resolving and a dispute game becoming +finalized. It's set via **authorized input**. ### Valid game -A game is a **valid game** if it, among other qualitifcations, has resolved in favor of the defender and has also matured past -the finality delay. In other words, it meets the conditions of both a **likely valid game** and a **finalized game**. +A game is a **valid game** if it, among other qualifications, has resolved in favor of the defender and has also matured +past the finality delay. In other words, it meets the conditions of both a **likely valid game** and a **finalized +game**. ### Blacklisted game -A blacklisted game is a game that has been set as blacklisted via **authorized action**. It must not be considered +A **blacklisted game** is a game that has been set as blacklisted via **authorized action**. It must not be considered valid, and must not be used for finalizing withdrawals or any other dependent L2-to-L1 action. -### Retired valid game +### Invalid game + +An **invalid game** is a game whose claim was false, or does not meet some other **likely valid game** condition. -A retired valid game is a dispute game whose `createdAt` timestamp is older than the **validity timestamp**. +### Retired game -### Validity timestamp +A **retired game** is a game whose `createdAt` timestamp is older than the **game retirement timestamp**. It may be +valid, likely valid, or invalid. -The validity timestamp is a timestamp internal to the contract that partly determines game validity and can only be -adjusted via **authorized input**. +### Game retirement timestamp + +The game retirement timestamp determines **retired games** and can only be adjusted via **authorized input**. ### Anchor state @@ -180,8 +168,8 @@ An anchor state is a state root from L2. ### Anchor game -An **anchor game** is a game upon which other games should build. It was a **valid game** when it was set, but may have -since been retired. +An **anchor game** is a **valid game** that can be used by dependents as a starting point for new dispute games. It may +be a **retired game**. ### Withdrawal @@ -211,13 +199,15 @@ We assume that a fault dispute game will correctly report the following properti #### Mitigations -- Existing audit on `FaultDisputeGame`. Note: Existing audit does not yet cover the second property above (that a game correctly reports whether its game type was the respected game type when created). +- Existing audit on `FaultDisputeGame`. Note: Existing audit does not yet cover the second property above (that a game + correctly reports whether its game type was the respected game type when created). - Integration testing. ### aFDG-002: Fault dispute games with correct claims resolve correctly at some regular rate -We assume that fault dispute games will regularly resolve in favor of the defender correctly. While the system -can handle games that resolve in favor of the challenger, as well as incorrect resolutions, there must be other games that resolve correctly to maintain the system's integrity. +We assume that fault dispute games will regularly resolve in favor of the defender correctly. While the system can +handle games that resolve in favor of the challenger, as well as incorrect resolutions, there must be other games that +resolve correctly to maintain the system's integrity. #### Mitigations @@ -225,7 +215,8 @@ can handle games that resolve in favor of the challenger, as well as incorrect r ### aDGF-001: Dispute game factory correctly identifies the games it created -We assume that DisputeGameFactory will correctly identify whether it created a game (i.e. whether the game is "factory-registered"). +We assume that DisputeGameFactory will correctly identify whether it created a game (i.e. whether the game is +"factory-registered"). ### Mitigations @@ -242,7 +233,11 @@ We assume that games created by the DisputeGameFactory will be monitored for inc ### aASR-001: Incorrectly resolving games will be blacklisted within the dispute game finality delay period -We assume that games that resolve incorrectly will be blacklisted via **authorized action** within the dispute game finality delay period. This further depends on [aDGF-002](#adgf-002-games-created-by-the-disputegamefactory-will-be-monitored). +We assume that games that resolve incorrectly will be blacklisted via **authorized action** within the dispute game +finality delay period. This further depends on +[aDGF-002](#adgf-002-games-created-by-the-disputegamefactory-will-be-monitored). + +TODO: is this true? #### Mitigations @@ -250,7 +245,11 @@ We assume that games that resolve incorrectly will be blacklisted via **authoriz ### aASR-002: Larger bugs in dispute game mechanics will be expired within the dispute game finality delay period -We assume that a larger bug affecting many games will be noticed via monitoring ([aDGF-002](#adgf-002-games-created-by-the-disputegamefactory-will-be-monitored)) and will be expired within the dispute game finality delay period. +We assume that a larger bug affecting many games will be noticed via monitoring +([aDGF-002](#adgf-002-games-created-by-the-disputegamefactory-will-be-monitored)) and will be expired within the dispute +game finality delay period. + +TODO: is this true? #### Mitigations @@ -287,11 +286,50 @@ We assume the SuperchainConfig contract correctly returns its guardian address. ## System Invariants -### iASR-001: Claims about L2 state are validated before they're used by dependents. +### iASR-001: Games that make correct claims about L2 state can be distinguished from games that do not. + +System components that depend on accurate L2 state must be able to trust the ASR to validate games correctly. + +#### Impact + +**Severity: Critical** + +If this invariant is broken, the system will not be able to distinguish between games that make correct claims about L2 +state and games that do not. This could lead to incorrect withdrawals and other problems with L2-to-L1 dependents, +implying lost funds and lost confidence. + +#### Dependencies + +- [aFDG-001](#afdg-001-fault-dispute-games-correctly-report-their-properties) +- [aDGF-001](#adgf-001-dispute-game-factory-correctly-identifies-the-games-it-created) +- [aDGF-002](#adgf-002-games-created-by-the-disputegamefactory-will-be-monitored) +- [aASR-001](#aasr-001-incorrectly-resolving-games-will-be-blacklisted-within-the-dispute-game-finality-delay-period) +- [aASR-002](#aasr-002-larger-bugs-in-dispute-game-mechanics-will-be-expired-within-the-dispute-game-finality-delay-period) +- [aASR-003](#aasr-003-the-anchorstateregistry-will-be-correctly-initialized-at-deployment) +- [aSC-001](#asc-001-superchainconfig-correctly-reports-its-guardian-address) + +### iASR-002: Valid withdrawals can be finalized within some bounded amount of time + +#### Impact + +**Severity: Critical** + +If this invariant is broken, withdrawals can be frozen for a long period of time, causing a critical liveness failure. + +#### Dependencies + +- [aFDG-001](#afdg-001-fault-dispute-games-correctly-report-their-properties) +- [aDGF-001](#adgf-001-dispute-game-factory-correctly-identifies-the-games-it-created) +- [aDGF-002](#adgf-002-games-created-by-the-disputegamefactory-will-be-monitored) +- [aASR-001](#aasr-001-incorrectly-resolving-games-will-be-blacklisted-within-the-dispute-game-finality-delay-period) +- [aASR-002](#aasr-002-larger-bugs-in-dispute-game-mechanics-will-be-expired-within-the-dispute-game-finality-delay-period) +- [aASR-003](#aasr-003-the-anchorstateregistry-will-be-correctly-initialized-at-deployment) +- [aSC-001](#asc-001-superchainconfig-correctly-reports-its-guardian-address) +- [iASR-001](#iasr-001-games-that-make-correct-claims-about-l2-state-can-be-distinguished-from-games-that-do-not) ## Component Invariants -### iASR-000: Only "truly" **valid games** will be represented as **valid games**. +### iASR-003: Only "truly" **valid games** will be represented as **valid games**. When asked for a **valid game** by its dependents, the contract will only serve **valid games** that "truly" resolved in favor of defender. @@ -300,22 +338,50 @@ favor of defender. **Severity: High** -If this invariant is broken, an L2 state that's different from what dependents can be tricked into finalizing withdrawals based on incorrect state roots. +If this invariant is broken, an L2 state that's different from what dependents can be tricked into finalizing +withdrawals based on incorrect state roots, causing loss of funds. + +#### Dependencies + +- TODO + +### iASR-004: The anchor game was created recently, within some bounded time period. + +When asked for the **anchor game** by fault dispute games, the contract will only serve an **anchor game** that is +recent within some bounded period of time. + +#### Impact + +**Severity: High** + +If this invariant is broken, proposer software can break (run out of memory), leading to dispute game liveness issues +and possible incorrect resolution. #### Dependencies -[FaultDisputeGame](./fault-dispute-game.md) depends on this contract for an **anchor game** against which to -resolve its claim. The contract assumes this **anchor game**'s state root is correct, and that it's recent enough that -proposer software doesn't run out of memory. +- TODO + +### iASR-005: The anchor game is a game whose claim is correct. -[OptimismPortal](./optimism-portal.md) depends on this contract to correctly report game validity as the basis for -proving and finalizing withdrawals. +When asked for the **anchor game** by fault dispute games, the contract will only serve an **anchor game** that is a +valid game or a valid-retired game. -- Can this dispute game can be used to prove a withdrawal? (Is the dispute game a **likely valid game**?) -- Can this dispute game can be used to finalize a withdrawal? (Is the dispute game a **valid game**?) +#### Impact + +**Severity: High** + +If this invariant is broken, dispute games can be created with incorrect starting points, leading to games that can be +used to prove false claims. This would lead to an operational failure, requiring incident response. If incident response +doesn't occur, this could lead to loss of funds. + +#### Dependencies + +- TODO ## Function-Level Invariants +## Implementation Spec + ### `constructor` The constructor must disable the initializer on the implementation contract. @@ -327,40 +393,41 @@ The constructor must disable the initializer on the implementation contract. - `dispute game finality delay` must be an **authorized input**. - Superchain config must be an **authorized input**. -### `getLatestValidGame` +### `getRecentValidGame` -Returns **latest valid game**, or reverts if there is no **latest valid game**. +Returns **anchor game**. Reverts if the **anchor game** has been **retired**. ### `updateAnchorGame` - Game must be a **valid game**. -- Game's block number must be higher than current **latest anchor game**. -- This function is the ONLY way to update the **latest anchor game** (after initialization). +- Game must not be a **retired game**. +- Game's block number must be higher than current **anchor game**. +- This function is the ONLY way to update the **anchor game** (after initialization). ### `getAnchorGame` -Returns the **latest anchor game**. +Returns the **anchor game**. -- Must revert if the **latest anchor game** is blacklisted. +- Must revert if the **anchor game** is blacklisted. - Must maintain the property that the timestamp of the game is not too old. - TODO: How old is too old? ### `registerLikelyValidGame` -Stores the address of a **maybe valid game** in an array as a candidate for `latestValidGame`. +Stores the address of a **likely valid game** in an array as a candidate for **anchor game**. -- Callable only by a **maybe valid game**. +- Callable only by a **likely valid game**. - Calling game must only register itself (and not some other game). - TODO: determine any invariants around registry ordering. ### `tryUpdateAnchorGame` -Try to update **latest valid game** using registry of **maybe valid games**. +Try to update **anchor game** using registry of **likely valid games**. - Callable by anyone. - Find the latest (comparing on l2BlockNumber) valid game you can find in the register within a fixed amount of gas. - Fixed gas amount ensures that this function does not get more expensive to call as time goes on. -- Use this as input to `update latest valid game`. +- Use this as input to `updateAnchorGame`. ### `isGameBlacklisted` @@ -378,8 +445,6 @@ Returns whether the game is a **finalized game**. Returns whether the game is a **valid game**. -Assumes - ### `setRespectedGameType` - Must be **authorized** by guardian role. From c2b80ead125ddfa4020a9478e3cce55d8bfeace6 Mon Sep 17 00:00:00 2001 From: wildmolasses Date: Wed, 11 Dec 2024 15:55:50 -0500 Subject: [PATCH 09/19] wip: asr --- .../stage-one/anchor-state-registry.md | 190 +++++++----------- 1 file changed, 73 insertions(+), 117 deletions(-) diff --git a/specs/fault-proof/stage-one/anchor-state-registry.md b/specs/fault-proof/stage-one/anchor-state-registry.md index 94b02da46..8aa37082f 100644 --- a/specs/fault-proof/stage-one/anchor-state-registry.md +++ b/specs/fault-proof/stage-one/anchor-state-registry.md @@ -2,89 +2,77 @@ + **Table of Contents** -- [Overview](#overview) - - [Perspective](#perspective) -- [Definitions](#definitions) - - [Dispute game](#dispute-game) - - [Likely valid game](#likely-valid-game) - - [Finalized game](#finalized-game) - - [Dispute game finality delay](#dispute-game-finality-delay) - - [Valid game](#valid-game) - - [Blacklisted game](#blacklisted-game) - - [Invalid game](#invalid-game) - - [Retired game](#retired-game) - - [Game retirement timestamp](#game-retirement-timestamp) - - [Anchor state](#anchor-state) - - [Anchor game](#anchor-game) - - [Withdrawal](#withdrawal) - - [Authorized input](#authorized-input) -- [Assumptions](#assumptions) - - [aFDG-001: Fault dispute games correctly report their properties](#afdg-001-fault-dispute-games-correctly-report-their-properties) - - [Mitigations](#mitigations) - - [aFDG-002: Fault dispute games with correct claims resolve correctly at some regular rate](#afdg-002-fault-dispute-games-with-correct-claims-resolve-correctly-at-some-regular-rate) - - [Mitigations](#mitigations-1) - - [aDGF-001: Dispute game factory correctly identifies the games it created](#adgf-001-dispute-game-factory-correctly-identifies-the-games-it-created) - - [Mitigations](#mitigations-2) - - [aDGF-002: Games created by the DisputeGameFactory will be monitored](#adgf-002-games-created-by-the-disputegamefactory-will-be-monitored) - - [Mitigations](#mitigations-3) - - [aASR-001: Incorrectly resolving games will be blacklisted within the dispute game finality delay period](#aasr-001-incorrectly-resolving-games-will-be-blacklisted-within-the-dispute-game-finality-delay-period) - - [Mitigations](#mitigations-4) - - [aASR-002: Larger bugs in dispute game mechanics will be expired within the dispute game finality delay period](#aasr-002-larger-bugs-in-dispute-game-mechanics-will-be-expired-within-the-dispute-game-finality-delay-period) - - [Mitigations](#mitigations-5) - - [aASR-003: The AnchorStateRegistry will be correctly initialized at deployment](#aasr-003-the-anchorstateregistry-will-be-correctly-initialized-at-deployment) - - [Mitigations](#mitigations-6) - - [aSC-001: SuperchainConfig correctly reports its guardian address](#asc-001-superchainconfig-correctly-reports-its-guardian-address) - - [Mitigations](#mitigations-7) -- [Top-Level Invariants](#top-level-invariants) -- [System Invariants](#system-invariants) - - [iASR-001: Games that make correct claims about L2 state can be distinguished from games that do not.](#iasr-001-games-that-make-correct-claims-about-l2-state-can-be-distinguished-from-games-that-do-not) - - [Impact](#impact) - - [Dependencies](#dependencies) - - [iASR-002: Valid withdrawals can be finalized within some bounded amount of time](#iasr-002-valid-withdrawals-can-be-finalized-within-some-bounded-amount-of-time) - - [Impact](#impact-1) - - [Dependencies](#dependencies-1) -- [Component Invariants](#component-invariants) - - [iASR-003: Only "truly" **valid games** will be represented as **valid games**.](#iasr-003-only-truly-valid-games-will-be-represented-as-valid-games) - - [Impact](#impact-2) - - [Dependencies](#dependencies-2) - - [iASR-004: The anchor game was created recently, within some bounded time period.](#iasr-004-the-anchor-game-was-created-recently-within-some-bounded-time-period) - - [Impact](#impact-3) - - [Dependencies](#dependencies-3) - - [iASR-005: The anchor game is a game whose claim is correct.](#iasr-005-the-anchor-game-is-a-game-whose-claim-is-correct) - - [Impact](#impact-4) - - [Dependencies](#dependencies-4) -- [Function-Level Invariants](#function-level-invariants) -- [Implementation Spec](#implementation-spec) - - [`constructor`](#constructor) - - [`initialize`](#initialize) - - [`getRecentValidGame`](#getrecentvalidgame) - - [`updateAnchorGame`](#updateanchorgame) - - [`getAnchorGame`](#getanchorgame) - - [`registerLikelyValidGame`](#registerlikelyvalidgame) - - [`tryUpdateAnchorGame`](#tryupdateanchorgame) - - [`isGameBlacklisted`](#isgameblacklisted) - - [`isGameLikelyValid`](#isgamelikelyvalid) - - [`isGameFinalized`](#isgamefinalized) - - [`isGameValid`](#isgamevalid) - - [`setRespectedGameType`](#setrespectedgametype) - - [`retireAllExistingGames`](#retireallexistinggames) - - [`setGameBlacklisted`](#setgameblacklisted) - - [`getGameFinalityDelay`](#getgamefinalitydelay) -- [Implementation](#implementation) - - [`constructor`](#constructor-1) - - [`initialize`](#initialize-1) - - [`anchors` / `getLatestAnchorState`](#anchors--getlatestanchorstate) - - [`registerMaybeValidGame`](#registermaybevalidgame) - - [`updateLatestValidGame`](#updatelatestvalidgame) - - [`tryUpdateLatestValidGame`](#tryupdatelatestvalidgame) - - [`setGameBlacklisted`](#setgameblacklisted-1) - - [`setRespectedGameType`](#setrespectedgametype-1) - - [`isGameInvalid`](#isgameinvalid) - - [`isGameValid`](#isgamevalid-1) - - [`disputeGameFinalityDelaySeconds`](#disputegamefinalitydelayseconds) - - [`disputeGameFactory`](#disputegamefactory) +- [Anchor State Registry](#anchor-state-registry) + - [Overview](#overview) + - [Perspective](#perspective) + - [Definitions](#definitions) + - [Dispute game](#dispute-game) + - [Likely valid game](#likely-valid-game) + - [Finalized game](#finalized-game) + - [Dispute game finality delay](#dispute-game-finality-delay) + - [Valid game](#valid-game) + - [Blacklisted game](#blacklisted-game) + - [Invalid game](#invalid-game) + - [Retired game](#retired-game) + - [Game retirement timestamp](#game-retirement-timestamp) + - [Anchor state](#anchor-state) + - [Anchor game](#anchor-game) + - [Withdrawal](#withdrawal) + - [Authorized input](#authorized-input) + - [Assumptions](#assumptions) + - [aFDG-001: Fault dispute games correctly report certain properties](#afdg-001-fault-dispute-games-correctly-report-certain-properties) + - [Mitigations](#mitigations) + - [aFDG-002: Fault dispute games with correct claims resolve correctly at some regular rate](#afdg-002-fault-dispute-games-with-correct-claims-resolve-correctly-at-some-regular-rate) + - [Mitigations](#mitigations-1) + - [aDGF-001: Dispute game factory correctly identifies the games it created](#adgf-001-dispute-game-factory-correctly-identifies-the-games-it-created) + - [Mitigations](#mitigations-2) + - [aDGF-002: Games created by the DisputeGameFactory will be monitored](#adgf-002-games-created-by-the-disputegamefactory-will-be-monitored) + - [Mitigations](#mitigations-3) + - [aASR-001: Incorrectly resolving games will be blacklisted within the dispute game finality delay period](#aasr-001-incorrectly-resolving-games-will-be-blacklisted-within-the-dispute-game-finality-delay-period) + - [Mitigations](#mitigations-4) + - [aASR-002: Larger bugs in dispute game mechanics will be expired within the dispute game finality delay period](#aasr-002-larger-bugs-in-dispute-game-mechanics-will-be-expired-within-the-dispute-game-finality-delay-period) + - [Mitigations](#mitigations-5) + - [aASR-003: The AnchorStateRegistry will be correctly initialized at deployment](#aasr-003-the-anchorstateregistry-will-be-correctly-initialized-at-deployment) + - [Mitigations](#mitigations-6) + - [aSC-001: SuperchainConfig correctly reports its guardian address](#asc-001-superchainconfig-correctly-reports-its-guardian-address) + - [Mitigations](#mitigations-7) + - [System Invariants](#system-invariants) + - [iASR-001: Games that make correct claims about L2 state can be distinguished from games that do not.](#iasr-001-games-that-make-correct-claims-about-l2-state-can-be-distinguished-from-games-that-do-not) + - [Impact](#impact) + - [Dependencies](#dependencies) + - [iASR-002: Valid withdrawals can be finalized within some bounded amount of time](#iasr-002-valid-withdrawals-can-be-finalized-within-some-bounded-amount-of-time) + - [Impact](#impact-1) + - [Dependencies](#dependencies-1) + - [Component Invariants](#component-invariants) + - [iASR-003: Only "truly" **valid games** will be represented as **valid games**.](#iasr-003-only-truly-valid-games-will-be-represented-as-valid-games) + - [Impact](#impact-2) + - [Dependencies](#dependencies-2) + - [iASR-004: The anchor game was created recently, within some bounded time period.](#iasr-004-the-anchor-game-was-created-recently-within-some-bounded-time-period) + - [Impact](#impact-3) + - [Dependencies](#dependencies-3) + - [iASR-005: The anchor game is a game whose claim is correct.](#iasr-005-the-anchor-game-is-a-game-whose-claim-is-correct) + - [Impact](#impact-4) + - [Dependencies](#dependencies-4) + - [Function-Level Invariants](#function-level-invariants) + - [Implementation Spec](#implementation-spec) + - [`constructor`](#constructor) + - [`initialize`](#initialize) + - [`getRecentValidGame`](#getrecentvalidgame) + - [`updateAnchorGame`](#updateanchorgame) + - [`getAnchorGame`](#getanchorgame) + - [`registerLikelyValidGame`](#registerlikelyvalidgame) + - [`tryUpdateAnchorGame`](#tryupdateanchorgame) + - [`isGameBlacklisted`](#isgameblacklisted) + - [`isGameLikelyValid`](#isgamelikelyvalid) + - [`isGameFinalized`](#isgamefinalized) + - [`isGameValid`](#isgamevalid) + - [`setRespectedGameType`](#setrespectedgametype) + - [`retireAllExistingGames`](#retireallexistinggames) + - [`setGameBlacklisted`](#setgameblacklisted) + - [`getGameFinalityDelay`](#getgamefinalitydelay) @@ -187,7 +175,7 @@ An authorized input is an input for which there is social consensus, i.e. coming > a subset of the following assumptions. Different invariants may rely on different assumptions. Refer to individual > invariants for their dependencies. -### aFDG-001: Fault dispute games correctly report their properties +### aFDG-001: Fault dispute games correctly report certain properties We assume that a fault dispute game will correctly report the following properties: @@ -277,13 +265,6 @@ We assume the SuperchainConfig contract correctly returns its guardian address. - Existing audit on the `SuperchainConfig`. - Integration testing. -## Top-Level Invariants - -- When asked for a **valid game**, the contract will only serve games that truly resolved correctly to its dependents. -- The latest anchor game must never serve the output root of a blacklisted game. -- The latest anchor game must be recent enough so that the game doesn't break (run out of memory) in op-challenger. -- The validity timestamp must start at zero. - ## System Invariants ### iASR-001: Games that make correct claims about L2 state can be distinguished from games that do not. @@ -355,7 +336,7 @@ recent within some bounded period of time. **Severity: High** If this invariant is broken, proposer software can break (run out of memory), leading to dispute game liveness issues -and possible incorrect resolution. +and incorrect game resolution. #### Dependencies @@ -451,8 +432,9 @@ Returns whether the game is a **valid game**. ### `retireAllExistingGames` -Retires all games that exist. +Retires all currently deployed games. +- Must set the **game retirement timestamp** to the current block timestamp. - Must be **authorized** by guardian role. ### `setGameBlacklisted` @@ -464,29 +446,3 @@ Blacklists a game. ### `getGameFinalityDelay` Returns **authorized** finality delay duration in seconds. No external dependents; public getter for convenience. - -## Implementation - -### `constructor` - -### `initialize` - -### `anchors` / `getLatestAnchorState` - -### `registerMaybeValidGame` - -### `updateLatestValidGame` - -### `tryUpdateLatestValidGame` - -### `setGameBlacklisted` - -### `setRespectedGameType` - -### `isGameInvalid` - -### `isGameValid` - -### `disputeGameFinalityDelaySeconds` - -### `disputeGameFactory` From 65e198730de98e9a5251ea0564352b61fd213727 Mon Sep 17 00:00:00 2001 From: wildmolasses Date: Wed, 11 Dec 2024 20:13:36 -0500 Subject: [PATCH 10/19] wip: ASR edit --- specs/fault-proof/stage-one/anchor-state-registry.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/specs/fault-proof/stage-one/anchor-state-registry.md b/specs/fault-proof/stage-one/anchor-state-registry.md index 8aa37082f..c018f6dd5 100644 --- a/specs/fault-proof/stage-one/anchor-state-registry.md +++ b/specs/fault-proof/stage-one/anchor-state-registry.md @@ -33,7 +33,7 @@ - [Mitigations](#mitigations-3) - [aASR-001: Incorrectly resolving games will be blacklisted within the dispute game finality delay period](#aasr-001-incorrectly-resolving-games-will-be-blacklisted-within-the-dispute-game-finality-delay-period) - [Mitigations](#mitigations-4) - - [aASR-002: Larger bugs in dispute game mechanics will be expired within the dispute game finality delay period](#aasr-002-larger-bugs-in-dispute-game-mechanics-will-be-expired-within-the-dispute-game-finality-delay-period) + - [aASR-002: If a larger dispute game bug is found, all games will be retired before the first incorrect game's dispute game finality delay period has passed](#aasr-002-if-a-larger-dispute-game-bug-is-found-all-games-will-be-retired-before-the-first-incorrect-games-dispute-game-finality-delay-period-has-passed) - [Mitigations](#mitigations-5) - [aASR-003: The AnchorStateRegistry will be correctly initialized at deployment](#aasr-003-the-anchorstateregistry-will-be-correctly-initialized-at-deployment) - [Mitigations](#mitigations-6) @@ -231,7 +231,7 @@ TODO: is this true? - Stakeholder incentives / processes. -### aASR-002: Larger bugs in dispute game mechanics will be expired within the dispute game finality delay period +### aASR-002: If a larger dispute game bug is found, all games will be retired before the first incorrect game's dispute game finality delay period has passed We assume that a larger bug affecting many games will be noticed via monitoring ([aDGF-002](#adgf-002-games-created-by-the-disputegamefactory-will-be-monitored)) and will be expired within the dispute From 7422c6f8feaece6d1b5717679376e3be293ee679 Mon Sep 17 00:00:00 2001 From: wildmolasses Date: Wed, 11 Dec 2024 20:56:49 -0500 Subject: [PATCH 11/19] wip: ASR --- .../stage-one/anchor-state-registry.md | 162 +++++++++--------- 1 file changed, 82 insertions(+), 80 deletions(-) diff --git a/specs/fault-proof/stage-one/anchor-state-registry.md b/specs/fault-proof/stage-one/anchor-state-registry.md index c018f6dd5..c4cdc0082 100644 --- a/specs/fault-proof/stage-one/anchor-state-registry.md +++ b/specs/fault-proof/stage-one/anchor-state-registry.md @@ -2,77 +2,75 @@ - **Table of Contents** -- [Anchor State Registry](#anchor-state-registry) - - [Overview](#overview) - - [Perspective](#perspective) - - [Definitions](#definitions) - - [Dispute game](#dispute-game) - - [Likely valid game](#likely-valid-game) - - [Finalized game](#finalized-game) - - [Dispute game finality delay](#dispute-game-finality-delay) - - [Valid game](#valid-game) - - [Blacklisted game](#blacklisted-game) - - [Invalid game](#invalid-game) - - [Retired game](#retired-game) - - [Game retirement timestamp](#game-retirement-timestamp) - - [Anchor state](#anchor-state) - - [Anchor game](#anchor-game) - - [Withdrawal](#withdrawal) - - [Authorized input](#authorized-input) - - [Assumptions](#assumptions) - - [aFDG-001: Fault dispute games correctly report certain properties](#afdg-001-fault-dispute-games-correctly-report-certain-properties) - - [Mitigations](#mitigations) - - [aFDG-002: Fault dispute games with correct claims resolve correctly at some regular rate](#afdg-002-fault-dispute-games-with-correct-claims-resolve-correctly-at-some-regular-rate) - - [Mitigations](#mitigations-1) - - [aDGF-001: Dispute game factory correctly identifies the games it created](#adgf-001-dispute-game-factory-correctly-identifies-the-games-it-created) - - [Mitigations](#mitigations-2) - - [aDGF-002: Games created by the DisputeGameFactory will be monitored](#adgf-002-games-created-by-the-disputegamefactory-will-be-monitored) - - [Mitigations](#mitigations-3) - - [aASR-001: Incorrectly resolving games will be blacklisted within the dispute game finality delay period](#aasr-001-incorrectly-resolving-games-will-be-blacklisted-within-the-dispute-game-finality-delay-period) - - [Mitigations](#mitigations-4) - - [aASR-002: If a larger dispute game bug is found, all games will be retired before the first incorrect game's dispute game finality delay period has passed](#aasr-002-if-a-larger-dispute-game-bug-is-found-all-games-will-be-retired-before-the-first-incorrect-games-dispute-game-finality-delay-period-has-passed) - - [Mitigations](#mitigations-5) - - [aASR-003: The AnchorStateRegistry will be correctly initialized at deployment](#aasr-003-the-anchorstateregistry-will-be-correctly-initialized-at-deployment) - - [Mitigations](#mitigations-6) - - [aSC-001: SuperchainConfig correctly reports its guardian address](#asc-001-superchainconfig-correctly-reports-its-guardian-address) - - [Mitigations](#mitigations-7) - - [System Invariants](#system-invariants) - - [iASR-001: Games that make correct claims about L2 state can be distinguished from games that do not.](#iasr-001-games-that-make-correct-claims-about-l2-state-can-be-distinguished-from-games-that-do-not) - - [Impact](#impact) - - [Dependencies](#dependencies) - - [iASR-002: Valid withdrawals can be finalized within some bounded amount of time](#iasr-002-valid-withdrawals-can-be-finalized-within-some-bounded-amount-of-time) - - [Impact](#impact-1) - - [Dependencies](#dependencies-1) - - [Component Invariants](#component-invariants) - - [iASR-003: Only "truly" **valid games** will be represented as **valid games**.](#iasr-003-only-truly-valid-games-will-be-represented-as-valid-games) - - [Impact](#impact-2) - - [Dependencies](#dependencies-2) - - [iASR-004: The anchor game was created recently, within some bounded time period.](#iasr-004-the-anchor-game-was-created-recently-within-some-bounded-time-period) - - [Impact](#impact-3) - - [Dependencies](#dependencies-3) - - [iASR-005: The anchor game is a game whose claim is correct.](#iasr-005-the-anchor-game-is-a-game-whose-claim-is-correct) - - [Impact](#impact-4) - - [Dependencies](#dependencies-4) - - [Function-Level Invariants](#function-level-invariants) - - [Implementation Spec](#implementation-spec) - - [`constructor`](#constructor) - - [`initialize`](#initialize) - - [`getRecentValidGame`](#getrecentvalidgame) - - [`updateAnchorGame`](#updateanchorgame) - - [`getAnchorGame`](#getanchorgame) - - [`registerLikelyValidGame`](#registerlikelyvalidgame) - - [`tryUpdateAnchorGame`](#tryupdateanchorgame) - - [`isGameBlacklisted`](#isgameblacklisted) - - [`isGameLikelyValid`](#isgamelikelyvalid) - - [`isGameFinalized`](#isgamefinalized) - - [`isGameValid`](#isgamevalid) - - [`setRespectedGameType`](#setrespectedgametype) - - [`retireAllExistingGames`](#retireallexistinggames) - - [`setGameBlacklisted`](#setgameblacklisted) - - [`getGameFinalityDelay`](#getgamefinalitydelay) +- [Overview](#overview) + - [Perspective](#perspective) +- [Definitions](#definitions) + - [Dispute game](#dispute-game) + - [Likely valid game](#likely-valid-game) + - [Finalized game](#finalized-game) + - [Dispute game finality delay](#dispute-game-finality-delay) + - [Valid game](#valid-game) + - [Blacklisted game](#blacklisted-game) + - [Invalid game](#invalid-game) + - [Retired game](#retired-game) + - [Game retirement timestamp](#game-retirement-timestamp) + - [Anchor state](#anchor-state) + - [Anchor game](#anchor-game) + - [Withdrawal](#withdrawal) + - [Authorized input](#authorized-input) +- [Assumptions](#assumptions) + - [aFDG-001: Fault dispute games correctly report certain properties](#afdg-001-fault-dispute-games-correctly-report-certain-properties) + - [Mitigations](#mitigations) + - [aFDG-002: Fault dispute games with correct claims resolve correctly at some regular rate](#afdg-002-fault-dispute-games-with-correct-claims-resolve-correctly-at-some-regular-rate) + - [Mitigations](#mitigations-1) + - [aDGF-001: Dispute game factory correctly identifies the games it created](#adgf-001-dispute-game-factory-correctly-identifies-the-games-it-created) + - [Mitigations](#mitigations-2) + - [aDGF-002: Games created by the DisputeGameFactory will be monitored](#adgf-002-games-created-by-the-disputegamefactory-will-be-monitored) + - [Mitigations](#mitigations-3) + - [aASR-001: Incorrectly resolving games will be blacklisted within the dispute game finality delay period](#aasr-001-incorrectly-resolving-games-will-be-blacklisted-within-the-dispute-game-finality-delay-period) + - [Mitigations](#mitigations-4) + - [aASR-002: If a larger dispute game bug is found, all games will be retired before the first incorrect game's dispute game finality delay period has passed](#aasr-002-if-a-larger-dispute-game-bug-is-found-all-games-will-be-retired-before-the-first-incorrect-games-dispute-game-finality-delay-period-has-passed) + - [Mitigations](#mitigations-5) + - [aASR-003: The AnchorStateRegistry will be correctly initialized at deployment](#aasr-003-the-anchorstateregistry-will-be-correctly-initialized-at-deployment) + - [Mitigations](#mitigations-6) + - [aSC-001: SuperchainConfig correctly reports its guardian address](#asc-001-superchainconfig-correctly-reports-its-guardian-address) + - [Mitigations](#mitigations-7) +- [System Invariants](#system-invariants) + - [iASR-001: Games that make correct claims about L2 state can be distinguished from games that do not.](#iasr-001-games-that-make-correct-claims-about-l2-state-can-be-distinguished-from-games-that-do-not) + - [Impact](#impact) + - [Dependencies](#dependencies) + - [iASR-002: Valid withdrawals can be finalized within some bounded amount of time](#iasr-002-valid-withdrawals-can-be-finalized-within-some-bounded-amount-of-time) + - [Impact](#impact-1) + - [Dependencies](#dependencies-1) +- [Component Invariants](#component-invariants) + - [iASR-003: Only "truly" **valid games** will be represented as **valid games**.](#iasr-003-only-truly-valid-games-will-be-represented-as-valid-games) + - [Impact](#impact-2) + - [Dependencies](#dependencies-2) + - [iASR-004: The anchor game was created recently, within some bounded time period.](#iasr-004-the-anchor-game-was-created-recently-within-some-bounded-time-period) + - [Impact](#impact-3) + - [Dependencies](#dependencies-3) + - [iASR-005: The anchor game is a game whose claim is correct.](#iasr-005-the-anchor-game-is-a-game-whose-claim-is-correct) + - [Impact](#impact-4) + - [Dependencies](#dependencies-4) +- [Function-Level Invariants](#function-level-invariants) +- [Implementation Spec](#implementation-spec) + - [`constructor`](#constructor) + - [`initialize`](#initialize) + - [`getRecentValidGame`](#getrecentvalidgame) + - [`updateAnchorGame`](#updateanchorgame) + - [`getAnchorGame`](#getanchorgame) + - [`registerLikelyValidGame`](#registerlikelyvalidgame) + - [`tryUpdateAnchorGame`](#tryupdateanchorgame) + - [`isGameBlacklisted`](#isgameblacklisted) + - [`isGameLikelyValid`](#isgamelikelyvalid) + - [`isGameFinalized`](#isgamefinalized) + - [`isGameValid`](#isgamevalid) + - [`setRespectedGameType`](#setrespectedgametype) + - [`retireAllExistingGames`](#retireallexistinggames) + - [`setGameBlacklisted`](#setgameblacklisted) + - [`getGameFinalityDelay`](#getgamefinalitydelay) @@ -234,7 +232,7 @@ TODO: is this true? ### aASR-002: If a larger dispute game bug is found, all games will be retired before the first incorrect game's dispute game finality delay period has passed We assume that a larger bug affecting many games will be noticed via monitoring -([aDGF-002](#adgf-002-games-created-by-the-disputegamefactory-will-be-monitored)) and will be expired within the dispute +([aDGF-002](#adgf-002-games-created-by-the-disputegamefactory-will-be-monitored)) and will be retired within the dispute game finality delay period. TODO: is this true? @@ -281,11 +279,11 @@ implying lost funds and lost confidence. #### Dependencies -- [aFDG-001](#afdg-001-fault-dispute-games-correctly-report-their-properties) +- [aFDG-001](#afdg-001-fault-dispute-games-correctly-report-certain-properties) - [aDGF-001](#adgf-001-dispute-game-factory-correctly-identifies-the-games-it-created) - [aDGF-002](#adgf-002-games-created-by-the-disputegamefactory-will-be-monitored) - [aASR-001](#aasr-001-incorrectly-resolving-games-will-be-blacklisted-within-the-dispute-game-finality-delay-period) -- [aASR-002](#aasr-002-larger-bugs-in-dispute-game-mechanics-will-be-expired-within-the-dispute-game-finality-delay-period) +- [aASR-002](#aasr-002-if-a-larger-dispute-game-bug-is-found-all-games-will-be-retired-before-the-first-incorrect-games-dispute-game-finality-delay-period-has-passed) - [aASR-003](#aasr-003-the-anchorstateregistry-will-be-correctly-initialized-at-deployment) - [aSC-001](#asc-001-superchainconfig-correctly-reports-its-guardian-address) @@ -299,11 +297,11 @@ If this invariant is broken, withdrawals can be frozen for a long period of time #### Dependencies -- [aFDG-001](#afdg-001-fault-dispute-games-correctly-report-their-properties) +- [aFDG-001](#afdg-001-fault-dispute-games-correctly-report-certain-properties) - [aDGF-001](#adgf-001-dispute-game-factory-correctly-identifies-the-games-it-created) - [aDGF-002](#adgf-002-games-created-by-the-disputegamefactory-will-be-monitored) - [aASR-001](#aasr-001-incorrectly-resolving-games-will-be-blacklisted-within-the-dispute-game-finality-delay-period) -- [aASR-002](#aasr-002-larger-bugs-in-dispute-game-mechanics-will-be-expired-within-the-dispute-game-finality-delay-period) +- [aASR-002](#aasr-002-if-a-larger-dispute-game-bug-is-found-all-games-will-be-retired-before-the-first-incorrect-games-dispute-game-finality-delay-period-has-passed) - [aASR-003](#aasr-003-the-anchorstateregistry-will-be-correctly-initialized-at-deployment) - [aSC-001](#asc-001-superchainconfig-correctly-reports-its-guardian-address) - [iASR-001](#iasr-001-games-that-make-correct-claims-about-l2-state-can-be-distinguished-from-games-that-do-not) @@ -312,19 +310,22 @@ If this invariant is broken, withdrawals can be frozen for a long period of time ### iASR-003: Only "truly" **valid games** will be represented as **valid games**. -When asked for a **valid game** by its dependents, the contract will only serve **valid games** that "truly" resolved in -favor of defender. +When asked for a **valid game** by its dependents, the AnchorStateRegistry will only serve **valid games** representing correct L2 state claims. #### Impact **Severity: High** -If this invariant is broken, an L2 state that's different from what dependents can be tricked into finalizing -withdrawals based on incorrect state roots, causing loss of funds. +If this invariant is broken, the L1 will have an inaccurate view of L2 state. The OptimismPortal can be tricked into finalizing +withdrawals based on incorrect state roots, causing loss of funds. Other dependents would also be affected. #### Dependencies -- TODO +- [iASR-001](#iasr-001-games-that-make-correct-claims-about-l2-state-can-be-distinguished-from-games-that-do-not) +- [aASR-001](#aasr-001-incorrectly-resolving-games-will-be-blacklisted-within-the-dispute-game-finality-delay-period) +- [aASR-002](#aasr-002-if-a-larger-dispute-game-bug-is-found-all-games-will-be-retired-before-the-first-incorrect-games-dispute-game-finality-delay-period-has-passed) +- [aASR-003](#aasr-003-the-anchorstateregistry-will-be-correctly-initialized-at-deployment) +- [aSC-001](#asc-001-superchainconfig-correctly-reports-its-guardian-address) ### iASR-004: The anchor game was created recently, within some bounded time period. @@ -340,7 +341,8 @@ and incorrect game resolution. #### Dependencies -- TODO +- [aASR-003](#aasr-003-the-anchorstateregistry-will-be-correctly-initialized-at-deployment) +- [aFDG-002](#afdg-002-fault-dispute-games-with-correct-claims-resolve-correctly-at-some-regular-rate) ### iASR-005: The anchor game is a game whose claim is correct. From d9502c9cb3f676e176c97d328bca0f9722b561a9 Mon Sep 17 00:00:00 2001 From: wildmolasses Date: Wed, 11 Dec 2024 20:59:08 -0500 Subject: [PATCH 12/19] wip: ASR toc --- specs/fault-proof/stage-one/anchor-state-registry.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/specs/fault-proof/stage-one/anchor-state-registry.md b/specs/fault-proof/stage-one/anchor-state-registry.md index c4cdc0082..d5f3a8acf 100644 --- a/specs/fault-proof/stage-one/anchor-state-registry.md +++ b/specs/fault-proof/stage-one/anchor-state-registry.md @@ -26,7 +26,7 @@ - [aFDG-002: Fault dispute games with correct claims resolve correctly at some regular rate](#afdg-002-fault-dispute-games-with-correct-claims-resolve-correctly-at-some-regular-rate) - [Mitigations](#mitigations-1) - [aDGF-001: Dispute game factory correctly identifies the games it created](#adgf-001-dispute-game-factory-correctly-identifies-the-games-it-created) - - [Mitigations](#mitigations-2) + - [Mitigations](#mitigations-2) - [aDGF-002: Games created by the DisputeGameFactory will be monitored](#adgf-002-games-created-by-the-disputegamefactory-will-be-monitored) - [Mitigations](#mitigations-3) - [aASR-001: Incorrectly resolving games will be blacklisted within the dispute game finality delay period](#aasr-001-incorrectly-resolving-games-will-be-blacklisted-within-the-dispute-game-finality-delay-period) @@ -201,17 +201,17 @@ resolve correctly to maintain the system's integrity. ### aDGF-001: Dispute game factory correctly identifies the games it created -We assume that DisputeGameFactory will correctly identify whether it created a game (i.e. whether the game is +We assume that `DisputeGameFactory` will correctly identify whether it created a game (i.e. whether the game is "factory-registered"). -### Mitigations +#### Mitigations - Existing audit on the `DisputeGameFactory`. - Integration testing. ### aDGF-002: Games created by the DisputeGameFactory will be monitored -We assume that games created by the DisputeGameFactory will be monitored for incorrect resolution. +We assume that games created by the `DisputeGameFactory` will be monitored for incorrect resolution. #### Mitigations From 85724f4757ef5b62ba41165715bd7f2869b78a6f Mon Sep 17 00:00:00 2001 From: wildmolasses Date: Thu, 12 Dec 2024 17:01:49 -0500 Subject: [PATCH 13/19] wip: ASR acceptable invalid anchor game --- .../stage-one/anchor-state-registry.md | 27 +++++++++++++------ .../fault-proof/stage-one/optimism-portal.md | 26 +++++++++++++----- 2 files changed, 38 insertions(+), 15 deletions(-) diff --git a/specs/fault-proof/stage-one/anchor-state-registry.md b/specs/fault-proof/stage-one/anchor-state-registry.md index d5f3a8acf..b6a384374 100644 --- a/specs/fault-proof/stage-one/anchor-state-registry.md +++ b/specs/fault-proof/stage-one/anchor-state-registry.md @@ -15,6 +15,7 @@ - [Blacklisted game](#blacklisted-game) - [Invalid game](#invalid-game) - [Retired game](#retired-game) + - [Acceptable invalid anchor game](#acceptable-invalid-anchor-game) - [Game retirement timestamp](#game-retirement-timestamp) - [Anchor state](#anchor-state) - [Anchor game](#anchor-game) @@ -104,6 +105,7 @@ valid game meets the following conditions: - Game is not **blacklisted**. - Game was created while it was the respected game type. - Game status is not `CHALLENGER_WINS`. +- Game `createdAt` timestamp is less than the **game retirement timestamp**. ### Finalized game @@ -139,8 +141,14 @@ An **invalid game** is a game whose claim was false, or does not meet some other ### Retired game -A **retired game** is a game whose `createdAt` timestamp is older than the **game retirement timestamp**. It may be -valid, likely valid, or invalid. +A **retired game** is a game whose `createdAt` timestamp is older than the **game retirement timestamp**. A game that +gets retired is no longer considered valid. + +### Acceptable invalid anchor game + +An **acceptable invalid anchor game** is an **anchor game** that was a **valid game** when set and has been made +**invalid** via **game retirement**. It meets every other condition of validity and is still acceptable to use as the +**anchor game**. This is a special case that allows the system to continue functioning even if all games are retired. ### Game retirement timestamp @@ -154,8 +162,8 @@ An anchor state is a state root from L2. ### Anchor game -An **anchor game** is a **valid game** that can be used by dependents as a starting point for new dispute games. It may -be a **retired game**. +An **anchor game** is a **valid game** or an **acceptable invalid anchor game** that can be used by dependents as a +starting point for new dispute games. ### Withdrawal @@ -228,6 +236,7 @@ TODO: is this true? #### Mitigations - Stakeholder incentives / processes. +- Incident response plan. ### aASR-002: If a larger dispute game bug is found, all games will be retired before the first incorrect game's dispute game finality delay period has passed @@ -240,6 +249,7 @@ TODO: is this true? #### Mitigations - Stakeholder incentives / processes. +- Incident response plan. ### aASR-003: The AnchorStateRegistry will be correctly initialized at deployment @@ -310,14 +320,15 @@ If this invariant is broken, withdrawals can be frozen for a long period of time ### iASR-003: Only "truly" **valid games** will be represented as **valid games**. -When asked for a **valid game** by its dependents, the AnchorStateRegistry will only serve **valid games** representing correct L2 state claims. +When asked for a **valid game** by its dependents, the AnchorStateRegistry will only serve **valid games** representing +correct L2 state claims. #### Impact **Severity: High** -If this invariant is broken, the L1 will have an inaccurate view of L2 state. The OptimismPortal can be tricked into finalizing -withdrawals based on incorrect state roots, causing loss of funds. Other dependents would also be affected. +If this invariant is broken, the L1 will have an inaccurate view of L2 state. The OptimismPortal can be tricked into +finalizing withdrawals based on incorrect state roots, causing loss of funds. Other dependents would also be affected. #### Dependencies @@ -397,7 +408,7 @@ Returns the **anchor game**. ### `registerLikelyValidGame` -Stores the address of a **likely valid game** in an array as a candidate for **anchor game**. +Register the address of a **likely valid game** as a candidate for **anchor game**. - Callable only by a **likely valid game**. - Calling game must only register itself (and not some other game). diff --git a/specs/fault-proof/stage-one/optimism-portal.md b/specs/fault-proof/stage-one/optimism-portal.md index f79198f70..71f1d104a 100644 --- a/specs/fault-proof/stage-one/optimism-portal.md +++ b/specs/fault-proof/stage-one/optimism-portal.md @@ -11,6 +11,10 @@ - [SuperchainConfig](#superchainconfig) - [Contract Dependents](#contract-dependents) - [Definitions](#definitions) + - [Authorized input](#authorized-input) + - [Proven withdrawal](#proven-withdrawal) + - [Finalized withdrawal](#finalized-withdrawal) + - [Proof maturity delay](#proof-maturity-delay) - [Top-Level Invariants](#top-level-invariants) - [Function-Level Invariants](#function-level-invariants) - [`initialize`](#initialize) @@ -23,7 +27,7 @@ ### Perspective -This contract is responsible for moderating [withdrawals](../../protocol/withdrawals.md). +This contract is responsible for moderating L2-to-L1 [withdrawals](../../protocol/withdrawals.md). ### Contract Dependencies @@ -47,17 +51,25 @@ TODO ## Definitions -- **Authorized input** - - An input for which there is social consensus, i.e. coming from governance. +### Authorized input -- **Proven withdrawal** - - +An input for which there is social consensus, i.e. coming from governance. -- **Finalized withdrawal** +### Proven withdrawal + +A **proven withdrawal** is a withdrawal that is likely valid, because it's been proven using a **likely valid game**. However, because we don't have full confidence in the game's validity, we can't yet finalize the withdrawal. + +### Finalized withdrawal + +A **finalized withdrawal** is a withdrawal transaction that has been proven against a game that we now know is **valid**, and has waited the **proof maturity delay**. + +### Proof maturity delay + +The **proof maturity delay** is time that must elapse between a withdrawal being proven and it being finalized. ## Top-Level Invariants -- A withdrawal transaction must be **proven** against a game that is **maybe valid**. +- A withdrawal transaction must be **proven** against a game that is **likely valid**. - A withdrawal transaction may only be finalized against a game that is **valid**. - Implicit in this is that a withdrawal transaction may only be finalized after the proof maturity delay has passed. - A withdrawal transaction may only be finalized if it has already been **proven**. From 8d8795988e8b44d011ee26cdc1a26ab220ed3c82 Mon Sep 17 00:00:00 2001 From: wildmolasses Date: Thu, 12 Dec 2024 17:26:18 -0500 Subject: [PATCH 14/19] wip: portal --- .../stage-one/anchor-state-registry.md | 147 +++++++++--------- .../fault-proof/stage-one/optimism-portal.md | 88 ++++++++--- 2 files changed, 138 insertions(+), 97 deletions(-) diff --git a/specs/fault-proof/stage-one/anchor-state-registry.md b/specs/fault-proof/stage-one/anchor-state-registry.md index b6a384374..b73ef8c0e 100644 --- a/specs/fault-proof/stage-one/anchor-state-registry.md +++ b/specs/fault-proof/stage-one/anchor-state-registry.md @@ -2,76 +2,78 @@ + **Table of Contents** -- [Overview](#overview) - - [Perspective](#perspective) -- [Definitions](#definitions) - - [Dispute game](#dispute-game) - - [Likely valid game](#likely-valid-game) - - [Finalized game](#finalized-game) - - [Dispute game finality delay](#dispute-game-finality-delay) - - [Valid game](#valid-game) - - [Blacklisted game](#blacklisted-game) - - [Invalid game](#invalid-game) - - [Retired game](#retired-game) - - [Acceptable invalid anchor game](#acceptable-invalid-anchor-game) - - [Game retirement timestamp](#game-retirement-timestamp) - - [Anchor state](#anchor-state) - - [Anchor game](#anchor-game) - - [Withdrawal](#withdrawal) - - [Authorized input](#authorized-input) -- [Assumptions](#assumptions) - - [aFDG-001: Fault dispute games correctly report certain properties](#afdg-001-fault-dispute-games-correctly-report-certain-properties) - - [Mitigations](#mitigations) - - [aFDG-002: Fault dispute games with correct claims resolve correctly at some regular rate](#afdg-002-fault-dispute-games-with-correct-claims-resolve-correctly-at-some-regular-rate) - - [Mitigations](#mitigations-1) - - [aDGF-001: Dispute game factory correctly identifies the games it created](#adgf-001-dispute-game-factory-correctly-identifies-the-games-it-created) - - [Mitigations](#mitigations-2) - - [aDGF-002: Games created by the DisputeGameFactory will be monitored](#adgf-002-games-created-by-the-disputegamefactory-will-be-monitored) - - [Mitigations](#mitigations-3) - - [aASR-001: Incorrectly resolving games will be blacklisted within the dispute game finality delay period](#aasr-001-incorrectly-resolving-games-will-be-blacklisted-within-the-dispute-game-finality-delay-period) - - [Mitigations](#mitigations-4) - - [aASR-002: If a larger dispute game bug is found, all games will be retired before the first incorrect game's dispute game finality delay period has passed](#aasr-002-if-a-larger-dispute-game-bug-is-found-all-games-will-be-retired-before-the-first-incorrect-games-dispute-game-finality-delay-period-has-passed) - - [Mitigations](#mitigations-5) - - [aASR-003: The AnchorStateRegistry will be correctly initialized at deployment](#aasr-003-the-anchorstateregistry-will-be-correctly-initialized-at-deployment) - - [Mitigations](#mitigations-6) - - [aSC-001: SuperchainConfig correctly reports its guardian address](#asc-001-superchainconfig-correctly-reports-its-guardian-address) - - [Mitigations](#mitigations-7) -- [System Invariants](#system-invariants) - - [iASR-001: Games that make correct claims about L2 state can be distinguished from games that do not.](#iasr-001-games-that-make-correct-claims-about-l2-state-can-be-distinguished-from-games-that-do-not) - - [Impact](#impact) - - [Dependencies](#dependencies) - - [iASR-002: Valid withdrawals can be finalized within some bounded amount of time](#iasr-002-valid-withdrawals-can-be-finalized-within-some-bounded-amount-of-time) - - [Impact](#impact-1) - - [Dependencies](#dependencies-1) -- [Component Invariants](#component-invariants) - - [iASR-003: Only "truly" **valid games** will be represented as **valid games**.](#iasr-003-only-truly-valid-games-will-be-represented-as-valid-games) - - [Impact](#impact-2) - - [Dependencies](#dependencies-2) - - [iASR-004: The anchor game was created recently, within some bounded time period.](#iasr-004-the-anchor-game-was-created-recently-within-some-bounded-time-period) - - [Impact](#impact-3) - - [Dependencies](#dependencies-3) - - [iASR-005: The anchor game is a game whose claim is correct.](#iasr-005-the-anchor-game-is-a-game-whose-claim-is-correct) - - [Impact](#impact-4) - - [Dependencies](#dependencies-4) -- [Function-Level Invariants](#function-level-invariants) -- [Implementation Spec](#implementation-spec) - - [`constructor`](#constructor) - - [`initialize`](#initialize) - - [`getRecentValidGame`](#getrecentvalidgame) - - [`updateAnchorGame`](#updateanchorgame) - - [`getAnchorGame`](#getanchorgame) - - [`registerLikelyValidGame`](#registerlikelyvalidgame) - - [`tryUpdateAnchorGame`](#tryupdateanchorgame) - - [`isGameBlacklisted`](#isgameblacklisted) - - [`isGameLikelyValid`](#isgamelikelyvalid) - - [`isGameFinalized`](#isgamefinalized) - - [`isGameValid`](#isgamevalid) - - [`setRespectedGameType`](#setrespectedgametype) - - [`retireAllExistingGames`](#retireallexistinggames) - - [`setGameBlacklisted`](#setgameblacklisted) - - [`getGameFinalityDelay`](#getgamefinalitydelay) +- [Anchor State Registry](#anchor-state-registry) + - [Overview](#overview) + - [Perspective](#perspective) + - [Definitions](#definitions) + - [Dispute game](#dispute-game) + - [Likely valid game](#likely-valid-game) + - [Finalized game](#finalized-game) + - [Dispute game finality delay](#dispute-game-finality-delay) + - [Valid game](#valid-game) + - [Blacklisted game](#blacklisted-game) + - [Invalid game](#invalid-game) + - [Retired game](#retired-game) + - [Acceptable invalid anchor game](#acceptable-invalid-anchor-game) + - [Game retirement timestamp](#game-retirement-timestamp) + - [Anchor state](#anchor-state) + - [Anchor game](#anchor-game) + - [Withdrawal](#withdrawal) + - [Authorized input](#authorized-input) + - [Assumptions](#assumptions) + - [aFDG-001: Fault dispute games correctly report certain properties](#afdg-001-fault-dispute-games-correctly-report-certain-properties) + - [Mitigations](#mitigations) + - [aFDG-002: Fault dispute games with correct claims resolve correctly at some regular rate](#afdg-002-fault-dispute-games-with-correct-claims-resolve-correctly-at-some-regular-rate) + - [Mitigations](#mitigations-1) + - [aDGF-001: Dispute game factory correctly identifies the games it created](#adgf-001-dispute-game-factory-correctly-identifies-the-games-it-created) + - [Mitigations](#mitigations-2) + - [aDGF-002: Games created by the DisputeGameFactory will be monitored](#adgf-002-games-created-by-the-disputegamefactory-will-be-monitored) + - [Mitigations](#mitigations-3) + - [aASR-001: Incorrectly resolving games will be blacklisted within the dispute game finality delay period](#aasr-001-incorrectly-resolving-games-will-be-blacklisted-within-the-dispute-game-finality-delay-period) + - [Mitigations](#mitigations-4) + - [aASR-002: If a larger dispute game bug is found, all games will be retired before the first incorrect game's dispute game finality delay period has passed](#aasr-002-if-a-larger-dispute-game-bug-is-found-all-games-will-be-retired-before-the-first-incorrect-games-dispute-game-finality-delay-period-has-passed) + - [Mitigations](#mitigations-5) + - [aASR-003: The AnchorStateRegistry will be correctly initialized at deployment](#aasr-003-the-anchorstateregistry-will-be-correctly-initialized-at-deployment) + - [Mitigations](#mitigations-6) + - [aSC-001: SuperchainConfig correctly reports its guardian address](#asc-001-superchainconfig-correctly-reports-its-guardian-address) + - [Mitigations](#mitigations-7) + - [System Invariants](#system-invariants) + - [iASR-001: Games that make correct claims about L2 state can be distinguished from games that do not.](#iasr-001-games-that-make-correct-claims-about-l2-state-can-be-distinguished-from-games-that-do-not) + - [Impact](#impact) + - [Dependencies](#dependencies) + - [iASR-002: Valid withdrawals can be finalized within some bounded amount of time](#iasr-002-valid-withdrawals-can-be-finalized-within-some-bounded-amount-of-time) + - [Impact](#impact-1) + - [Dependencies](#dependencies-1) + - [Component Invariants](#component-invariants) + - [iASR-003: Only "truly" **valid games** will be represented as **valid games**.](#iasr-003-only-truly-valid-games-will-be-represented-as-valid-games) + - [Impact](#impact-2) + - [Dependencies](#dependencies-2) + - [iASR-004: The anchor game was created recently, within some bounded time period.](#iasr-004-the-anchor-game-was-created-recently-within-some-bounded-time-period) + - [Impact](#impact-3) + - [Dependencies](#dependencies-3) + - [iASR-005: The anchor game is a game whose claim is correct.](#iasr-005-the-anchor-game-is-a-game-whose-claim-is-correct) + - [Impact](#impact-4) + - [Dependencies](#dependencies-4) + - [Function-Level Invariants](#function-level-invariants) + - [Implementation Spec](#implementation-spec) + - [`constructor`](#constructor) + - [`initialize`](#initialize) + - [`getRecentValidGame`](#getrecentvalidgame) + - [`updateAnchorGame`](#updateanchorgame) + - [`getAnchorGame`](#getanchorgame) + - [`registerLikelyValidGame`](#registerlikelyvalidgame) + - [`tryUpdateAnchorGame`](#tryupdateanchorgame) + - [`isGameBlacklisted`](#isgameblacklisted) + - [`isGameLikelyValid`](#isgamelikelyvalid) + - [`isGameFinalized`](#isgamefinalized) + - [`isGameValid`](#isgamevalid) + - [`setRespectedGameType`](#setrespectedgametype) + - [`retireAllExistingGames`](#retireallexistinggames) + - [`setGameBlacklisted`](#setgameblacklisted) + - [`getGameFinalityDelay`](#getgamefinalitydelay) @@ -389,12 +391,12 @@ The constructor must disable the initializer on the implementation contract. ### `getRecentValidGame` -Returns **anchor game**. Reverts if the **anchor game** has been **retired**. +Returns **anchor game**. Reverts if the **anchor game** has been **retired** i.e. is an **acceptable invalid anchor +game**. ### `updateAnchorGame` - Game must be a **valid game**. -- Game must not be a **retired game**. - Game's block number must be higher than current **anchor game**. - This function is the ONLY way to update the **anchor game** (after initialization). @@ -402,7 +404,8 @@ Returns **anchor game**. Reverts if the **anchor game** has been **retired**. Returns the **anchor game**. -- Must revert if the **anchor game** is blacklisted. +- Must return a **valid game** or an **acceptable invalid anchor game**. +- Must revert if the **anchor game** is a **blacklisted game**. - Must maintain the property that the timestamp of the game is not too old. - TODO: How old is too old? @@ -419,7 +422,7 @@ Register the address of a **likely valid game** as a candidate for **anchor game Try to update **anchor game** using registry of **likely valid games**. - Callable by anyone. -- Find the latest (comparing on l2BlockNumber) valid game you can find in the register within a fixed amount of gas. +- Find the most recent (comparing on l2BlockNumber) valid game you can find in the register within a fixed amount of gas. - Fixed gas amount ensures that this function does not get more expensive to call as time goes on. - Use this as input to `updateAnchorGame`. diff --git a/specs/fault-proof/stage-one/optimism-portal.md b/specs/fault-proof/stage-one/optimism-portal.md index 71f1d104a..e9fd1f63c 100644 --- a/specs/fault-proof/stage-one/optimism-portal.md +++ b/specs/fault-proof/stage-one/optimism-portal.md @@ -2,19 +2,27 @@ + **Table of Contents** +- [Optimism Portal](#optimism-portal) - [Overview](#overview) - [Perspective](#perspective) - - [Contract Dependencies](#contract-dependencies) - - [AnchorStateRegistry](#anchorstateregistry) - - [SuperchainConfig](#superchainconfig) - - [Contract Dependents](#contract-dependents) - [Definitions](#definitions) - [Authorized input](#authorized-input) - [Proven withdrawal](#proven-withdrawal) - [Finalized withdrawal](#finalized-withdrawal) - [Proof maturity delay](#proof-maturity-delay) + - [Assumptions](#assumptions) + - [aASR-001: AnchorStateRegistry correctly distinguishes likely valid games](#aasr-001-anchorstateregistry-correctly-distinguishes-likely-valid-games) + - [Impact](#impact) + - [Mitigations](#mitigations) + - [aASR-002: AnchorStateRegistry correctly distinguishes valid games](#aasr-002-anchorstateregistry-correctly-distinguishes-valid-games) + - [Impact](#impact-1) + - [Mitigations](#mitigations-1) + - [aSC-001: SuperchainConfig correctly reports system pause status](#asc-001-superchainconfig-correctly-reports-system-pause-status) + - [Impact](#impact-2) + - [Mitigations](#mitigations-2) - [Top-Level Invariants](#top-level-invariants) - [Function-Level Invariants](#function-level-invariants) - [`initialize`](#initialize) @@ -27,45 +35,73 @@ ### Perspective -This contract is responsible for moderating L2-to-L1 [withdrawals](../../protocol/withdrawals.md). +The whole point of the fault proof system is to create correctly resolving games whose claims we can depend on to finalize withdrawals (or other L2-to-L1 dependents). This contract is responsible for moderating L2-to-L1 [withdrawals](../../protocol/withdrawals.md). Because of the probabilistic validity of games as discussed in [AnchorStateRegistry](./anchor-state-registry.md), we can't immediately finalize withdrawals. Instead, we must wait for both a [dispute game finality delay](./anchor-state-registry.md#dispute-game-finality-delay) and a **proof maturity delay** to pass before we can finalize a withdrawal. Meanwhile, our assumptions about the fault proof system do work such that by the time the withdrawal is finalized, we're confident the withdrawal is correct. -### Contract Dependencies +## Definitions -#### AnchorStateRegistry +### Authorized input -Depends on AnchorStateRegistry to correctly report: +An input for which there is social consensus, i.e. coming from governance. -- Whether a game is an **invalid game**. -- Whether a game is a **valid game**. +### Proven withdrawal -#### SuperchainConfig +A **proven withdrawal** is a withdrawal that is likely valid, because it's been proven using a **likely valid game**. +However, because we don't have full confidence in the game's validity, we can't yet finalize the withdrawal. -Depends on SuperchainConfig to correctly report: +### Finalized withdrawal -- System pause status. -- Guardian address. +A **finalized withdrawal** is a withdrawal transaction that has been proven against a game that we now know is +**valid**, and has waited the **proof maturity delay**. -### Contract Dependents +### Proof maturity delay -TODO +The **proof maturity delay** is time that must elapse between a withdrawal being proven and it being finalized. -## Definitions +## Assumptions -### Authorized input +### aASR-001: AnchorStateRegistry correctly distinguishes likely valid games -An input for which there is social consensus, i.e. coming from governance. +We assume that the AnchorStateRegistry correctly reports whether a game is a [**likely valid game**](./anchor-state-registry.md#likely-valid-game). -### Proven withdrawal +#### Impact -A **proven withdrawal** is a withdrawal that is likely valid, because it's been proven using a **likely valid game**. However, because we don't have full confidence in the game's validity, we can't yet finalize the withdrawal. +**Severity: Medium** -### Finalized withdrawal +If a game is reported as likely valid when it is not, an attacker can prove a withdrawal that is invalid. If [aASR-002](#aasr-002-anchorstateregistry-correctly-distinguishes-valid-games) holds, this may not result in severe consequences, but would negatively impact system hygiene. -A **finalized withdrawal** is a withdrawal transaction that has been proven against a game that we now know is **valid**, and has waited the **proof maturity delay**. +#### Mitigations -### Proof maturity delay +- Pending audit of `AnchorStateRegistry` +- Integration testing -The **proof maturity delay** is time that must elapse between a withdrawal being proven and it being finalized. +### aASR-002: AnchorStateRegistry correctly distinguishes valid games + +We assume that the AnchorStateRegistry correctly reports whether a game is a [**valid game**](./anchor-state-registry.md#valid-game). + +#### Impact + +**Severity: Critical** + +If a game is reported as valid when it is not, we may finalize a withdrawal that is invalid. This would result to a loss of funds and a loss of confidence in the system. + +#### Mitigations + +- Pending audit of `AnchorStateRegistry` +- Integration testing + +### aSC-001: SuperchainConfig correctly reports system pause status + +We assume SuperchainConfig correctly returns system pause status. + +#### Impact + +**Severity: Critical** + +If SuperchainConfig incorrectly reports system pause status, we may prove / finalize a withdrawal when the system is paused. This would create bad system hygiene, and could lead to a loss of funds or a loss of confidence in the system. + +#### Mitigations + +- Existing audit of `SuperchainConfig` ## Top-Level Invariants @@ -97,6 +133,7 @@ Proves a withdrawal transaction. - A withdrawal cannot be reproved by the same proof submitter unless both of the following are true: - the dispute game previously used to prove the withdrawal is now an invalid game. - the withdrawal was never finalized. +- System must not be paused. ## `finalizeWithdrawalTransaction` @@ -112,3 +149,4 @@ Finalizes a withdrawal transaction that has already been proven. - TODO: withdrawal tx invariants (can't call token contract, exact balance must be transferred, estimator should revert for gas estimation) - If these invariants are met, function must attempt execution of the withdrawal transaction. +- System must not be paused. From 22510a0dcf04528c9626399ee8b993ddfb6aa535 Mon Sep 17 00:00:00 2001 From: wildmolasses Date: Thu, 12 Dec 2024 17:27:04 -0500 Subject: [PATCH 15/19] wip: ASR and portal TOC --- .../stage-one/anchor-state-registry.md | 138 +++++++++--------- .../fault-proof/stage-one/optimism-portal.md | 26 +++- 2 files changed, 86 insertions(+), 78 deletions(-) diff --git a/specs/fault-proof/stage-one/anchor-state-registry.md b/specs/fault-proof/stage-one/anchor-state-registry.md index b73ef8c0e..903ab75eb 100644 --- a/specs/fault-proof/stage-one/anchor-state-registry.md +++ b/specs/fault-proof/stage-one/anchor-state-registry.md @@ -2,78 +2,76 @@ - **Table of Contents** -- [Anchor State Registry](#anchor-state-registry) - - [Overview](#overview) - - [Perspective](#perspective) - - [Definitions](#definitions) - - [Dispute game](#dispute-game) - - [Likely valid game](#likely-valid-game) - - [Finalized game](#finalized-game) - - [Dispute game finality delay](#dispute-game-finality-delay) - - [Valid game](#valid-game) - - [Blacklisted game](#blacklisted-game) - - [Invalid game](#invalid-game) - - [Retired game](#retired-game) - - [Acceptable invalid anchor game](#acceptable-invalid-anchor-game) - - [Game retirement timestamp](#game-retirement-timestamp) - - [Anchor state](#anchor-state) - - [Anchor game](#anchor-game) - - [Withdrawal](#withdrawal) - - [Authorized input](#authorized-input) - - [Assumptions](#assumptions) - - [aFDG-001: Fault dispute games correctly report certain properties](#afdg-001-fault-dispute-games-correctly-report-certain-properties) - - [Mitigations](#mitigations) - - [aFDG-002: Fault dispute games with correct claims resolve correctly at some regular rate](#afdg-002-fault-dispute-games-with-correct-claims-resolve-correctly-at-some-regular-rate) - - [Mitigations](#mitigations-1) - - [aDGF-001: Dispute game factory correctly identifies the games it created](#adgf-001-dispute-game-factory-correctly-identifies-the-games-it-created) - - [Mitigations](#mitigations-2) - - [aDGF-002: Games created by the DisputeGameFactory will be monitored](#adgf-002-games-created-by-the-disputegamefactory-will-be-monitored) - - [Mitigations](#mitigations-3) - - [aASR-001: Incorrectly resolving games will be blacklisted within the dispute game finality delay period](#aasr-001-incorrectly-resolving-games-will-be-blacklisted-within-the-dispute-game-finality-delay-period) - - [Mitigations](#mitigations-4) - - [aASR-002: If a larger dispute game bug is found, all games will be retired before the first incorrect game's dispute game finality delay period has passed](#aasr-002-if-a-larger-dispute-game-bug-is-found-all-games-will-be-retired-before-the-first-incorrect-games-dispute-game-finality-delay-period-has-passed) - - [Mitigations](#mitigations-5) - - [aASR-003: The AnchorStateRegistry will be correctly initialized at deployment](#aasr-003-the-anchorstateregistry-will-be-correctly-initialized-at-deployment) - - [Mitigations](#mitigations-6) - - [aSC-001: SuperchainConfig correctly reports its guardian address](#asc-001-superchainconfig-correctly-reports-its-guardian-address) - - [Mitigations](#mitigations-7) - - [System Invariants](#system-invariants) - - [iASR-001: Games that make correct claims about L2 state can be distinguished from games that do not.](#iasr-001-games-that-make-correct-claims-about-l2-state-can-be-distinguished-from-games-that-do-not) - - [Impact](#impact) - - [Dependencies](#dependencies) - - [iASR-002: Valid withdrawals can be finalized within some bounded amount of time](#iasr-002-valid-withdrawals-can-be-finalized-within-some-bounded-amount-of-time) - - [Impact](#impact-1) - - [Dependencies](#dependencies-1) - - [Component Invariants](#component-invariants) - - [iASR-003: Only "truly" **valid games** will be represented as **valid games**.](#iasr-003-only-truly-valid-games-will-be-represented-as-valid-games) - - [Impact](#impact-2) - - [Dependencies](#dependencies-2) - - [iASR-004: The anchor game was created recently, within some bounded time period.](#iasr-004-the-anchor-game-was-created-recently-within-some-bounded-time-period) - - [Impact](#impact-3) - - [Dependencies](#dependencies-3) - - [iASR-005: The anchor game is a game whose claim is correct.](#iasr-005-the-anchor-game-is-a-game-whose-claim-is-correct) - - [Impact](#impact-4) - - [Dependencies](#dependencies-4) - - [Function-Level Invariants](#function-level-invariants) - - [Implementation Spec](#implementation-spec) - - [`constructor`](#constructor) - - [`initialize`](#initialize) - - [`getRecentValidGame`](#getrecentvalidgame) - - [`updateAnchorGame`](#updateanchorgame) - - [`getAnchorGame`](#getanchorgame) - - [`registerLikelyValidGame`](#registerlikelyvalidgame) - - [`tryUpdateAnchorGame`](#tryupdateanchorgame) - - [`isGameBlacklisted`](#isgameblacklisted) - - [`isGameLikelyValid`](#isgamelikelyvalid) - - [`isGameFinalized`](#isgamefinalized) - - [`isGameValid`](#isgamevalid) - - [`setRespectedGameType`](#setrespectedgametype) - - [`retireAllExistingGames`](#retireallexistinggames) - - [`setGameBlacklisted`](#setgameblacklisted) - - [`getGameFinalityDelay`](#getgamefinalitydelay) +- [Overview](#overview) + - [Perspective](#perspective) +- [Definitions](#definitions) + - [Dispute game](#dispute-game) + - [Likely valid game](#likely-valid-game) + - [Finalized game](#finalized-game) + - [Dispute game finality delay](#dispute-game-finality-delay) + - [Valid game](#valid-game) + - [Blacklisted game](#blacklisted-game) + - [Invalid game](#invalid-game) + - [Retired game](#retired-game) + - [Acceptable invalid anchor game](#acceptable-invalid-anchor-game) + - [Game retirement timestamp](#game-retirement-timestamp) + - [Anchor state](#anchor-state) + - [Anchor game](#anchor-game) + - [Withdrawal](#withdrawal) + - [Authorized input](#authorized-input) +- [Assumptions](#assumptions) + - [aFDG-001: Fault dispute games correctly report certain properties](#afdg-001-fault-dispute-games-correctly-report-certain-properties) + - [Mitigations](#mitigations) + - [aFDG-002: Fault dispute games with correct claims resolve correctly at some regular rate](#afdg-002-fault-dispute-games-with-correct-claims-resolve-correctly-at-some-regular-rate) + - [Mitigations](#mitigations-1) + - [aDGF-001: Dispute game factory correctly identifies the games it created](#adgf-001-dispute-game-factory-correctly-identifies-the-games-it-created) + - [Mitigations](#mitigations-2) + - [aDGF-002: Games created by the DisputeGameFactory will be monitored](#adgf-002-games-created-by-the-disputegamefactory-will-be-monitored) + - [Mitigations](#mitigations-3) + - [aASR-001: Incorrectly resolving games will be blacklisted within the dispute game finality delay period](#aasr-001-incorrectly-resolving-games-will-be-blacklisted-within-the-dispute-game-finality-delay-period) + - [Mitigations](#mitigations-4) + - [aASR-002: If a larger dispute game bug is found, all games will be retired before the first incorrect game's dispute game finality delay period has passed](#aasr-002-if-a-larger-dispute-game-bug-is-found-all-games-will-be-retired-before-the-first-incorrect-games-dispute-game-finality-delay-period-has-passed) + - [Mitigations](#mitigations-5) + - [aASR-003: The AnchorStateRegistry will be correctly initialized at deployment](#aasr-003-the-anchorstateregistry-will-be-correctly-initialized-at-deployment) + - [Mitigations](#mitigations-6) + - [aSC-001: SuperchainConfig correctly reports its guardian address](#asc-001-superchainconfig-correctly-reports-its-guardian-address) + - [Mitigations](#mitigations-7) +- [System Invariants](#system-invariants) + - [iASR-001: Games that make correct claims about L2 state can be distinguished from games that do not.](#iasr-001-games-that-make-correct-claims-about-l2-state-can-be-distinguished-from-games-that-do-not) + - [Impact](#impact) + - [Dependencies](#dependencies) + - [iASR-002: Valid withdrawals can be finalized within some bounded amount of time](#iasr-002-valid-withdrawals-can-be-finalized-within-some-bounded-amount-of-time) + - [Impact](#impact-1) + - [Dependencies](#dependencies-1) +- [Component Invariants](#component-invariants) + - [iASR-003: Only "truly" **valid games** will be represented as **valid games**.](#iasr-003-only-truly-valid-games-will-be-represented-as-valid-games) + - [Impact](#impact-2) + - [Dependencies](#dependencies-2) + - [iASR-004: The anchor game was created recently, within some bounded time period.](#iasr-004-the-anchor-game-was-created-recently-within-some-bounded-time-period) + - [Impact](#impact-3) + - [Dependencies](#dependencies-3) + - [iASR-005: The anchor game is a game whose claim is correct.](#iasr-005-the-anchor-game-is-a-game-whose-claim-is-correct) + - [Impact](#impact-4) + - [Dependencies](#dependencies-4) +- [Function-Level Invariants](#function-level-invariants) +- [Implementation Spec](#implementation-spec) + - [`constructor`](#constructor) + - [`initialize`](#initialize) + - [`getRecentValidGame`](#getrecentvalidgame) + - [`updateAnchorGame`](#updateanchorgame) + - [`getAnchorGame`](#getanchorgame) + - [`registerLikelyValidGame`](#registerlikelyvalidgame) + - [`tryUpdateAnchorGame`](#tryupdateanchorgame) + - [`isGameBlacklisted`](#isgameblacklisted) + - [`isGameLikelyValid`](#isgamelikelyvalid) + - [`isGameFinalized`](#isgamefinalized) + - [`isGameValid`](#isgamevalid) + - [`setRespectedGameType`](#setrespectedgametype) + - [`retireAllExistingGames`](#retireallexistinggames) + - [`setGameBlacklisted`](#setgameblacklisted) + - [`getGameFinalityDelay`](#getgamefinalitydelay) diff --git a/specs/fault-proof/stage-one/optimism-portal.md b/specs/fault-proof/stage-one/optimism-portal.md index e9fd1f63c..b2fe6e99a 100644 --- a/specs/fault-proof/stage-one/optimism-portal.md +++ b/specs/fault-proof/stage-one/optimism-portal.md @@ -2,10 +2,8 @@ - **Table of Contents** -- [Optimism Portal](#optimism-portal) - [Overview](#overview) - [Perspective](#perspective) - [Definitions](#definitions) @@ -35,7 +33,13 @@ ### Perspective -The whole point of the fault proof system is to create correctly resolving games whose claims we can depend on to finalize withdrawals (or other L2-to-L1 dependents). This contract is responsible for moderating L2-to-L1 [withdrawals](../../protocol/withdrawals.md). Because of the probabilistic validity of games as discussed in [AnchorStateRegistry](./anchor-state-registry.md), we can't immediately finalize withdrawals. Instead, we must wait for both a [dispute game finality delay](./anchor-state-registry.md#dispute-game-finality-delay) and a **proof maturity delay** to pass before we can finalize a withdrawal. Meanwhile, our assumptions about the fault proof system do work such that by the time the withdrawal is finalized, we're confident the withdrawal is correct. +The whole point of the fault proof system is to create correctly resolving games whose claims we can depend on to +finalize withdrawals (or other L2-to-L1 dependents). This contract is responsible for moderating L2-to-L1 +[withdrawals](../../protocol/withdrawals.md). Because of the probabilistic validity of games as discussed in +[AnchorStateRegistry](./anchor-state-registry.md), we can't immediately finalize withdrawals. Instead, we must wait for +both a [dispute game finality delay](./anchor-state-registry.md#dispute-game-finality-delay) and a **proof maturity +delay** to pass before we can finalize a withdrawal. Meanwhile, our assumptions about the fault proof system do work +such that by the time the withdrawal is finalized, we're confident the withdrawal is correct. ## Definitions @@ -61,13 +65,16 @@ The **proof maturity delay** is time that must elapse between a withdrawal being ### aASR-001: AnchorStateRegistry correctly distinguishes likely valid games -We assume that the AnchorStateRegistry correctly reports whether a game is a [**likely valid game**](./anchor-state-registry.md#likely-valid-game). +We assume that the AnchorStateRegistry correctly reports whether a game is a [**likely valid +game**](./anchor-state-registry.md#likely-valid-game). #### Impact **Severity: Medium** -If a game is reported as likely valid when it is not, an attacker can prove a withdrawal that is invalid. If [aASR-002](#aasr-002-anchorstateregistry-correctly-distinguishes-valid-games) holds, this may not result in severe consequences, but would negatively impact system hygiene. +If a game is reported as likely valid when it is not, an attacker can prove a withdrawal that is invalid. If +[aASR-002](#aasr-002-anchorstateregistry-correctly-distinguishes-valid-games) holds, this may not result in severe +consequences, but would negatively impact system hygiene. #### Mitigations @@ -76,13 +83,15 @@ If a game is reported as likely valid when it is not, an attacker can prove a wi ### aASR-002: AnchorStateRegistry correctly distinguishes valid games -We assume that the AnchorStateRegistry correctly reports whether a game is a [**valid game**](./anchor-state-registry.md#valid-game). +We assume that the AnchorStateRegistry correctly reports whether a game is a [**valid +game**](./anchor-state-registry.md#valid-game). #### Impact **Severity: Critical** -If a game is reported as valid when it is not, we may finalize a withdrawal that is invalid. This would result to a loss of funds and a loss of confidence in the system. +If a game is reported as valid when it is not, we may finalize a withdrawal that is invalid. This would result to a loss +of funds and a loss of confidence in the system. #### Mitigations @@ -97,7 +106,8 @@ We assume SuperchainConfig correctly returns system pause status. **Severity: Critical** -If SuperchainConfig incorrectly reports system pause status, we may prove / finalize a withdrawal when the system is paused. This would create bad system hygiene, and could lead to a loss of funds or a loss of confidence in the system. +If SuperchainConfig incorrectly reports system pause status, we may prove / finalize a withdrawal when the system is +paused. This would create bad system hygiene, and could lead to a loss of funds or a loss of confidence in the system. #### Mitigations From dd375de6b32a98fd3f5ebfc1575cc7927cdc04ee Mon Sep 17 00:00:00 2001 From: wildmolasses Date: Fri, 13 Dec 2024 13:20:20 -0500 Subject: [PATCH 16/19] remove iASR-001 --- .../stage-one/anchor-state-registry.md | 27 ------------------- 1 file changed, 27 deletions(-) diff --git a/specs/fault-proof/stage-one/anchor-state-registry.md b/specs/fault-proof/stage-one/anchor-state-registry.md index 903ab75eb..28e574341 100644 --- a/specs/fault-proof/stage-one/anchor-state-registry.md +++ b/specs/fault-proof/stage-one/anchor-state-registry.md @@ -39,9 +39,6 @@ - [aSC-001: SuperchainConfig correctly reports its guardian address](#asc-001-superchainconfig-correctly-reports-its-guardian-address) - [Mitigations](#mitigations-7) - [System Invariants](#system-invariants) - - [iASR-001: Games that make correct claims about L2 state can be distinguished from games that do not.](#iasr-001-games-that-make-correct-claims-about-l2-state-can-be-distinguished-from-games-that-do-not) - - [Impact](#impact) - - [Dependencies](#dependencies) - [iASR-002: Valid withdrawals can be finalized within some bounded amount of time](#iasr-002-valid-withdrawals-can-be-finalized-within-some-bounded-amount-of-time) - [Impact](#impact-1) - [Dependencies](#dependencies-1) @@ -275,28 +272,6 @@ We assume the SuperchainConfig contract correctly returns its guardian address. ## System Invariants -### iASR-001: Games that make correct claims about L2 state can be distinguished from games that do not. - -System components that depend on accurate L2 state must be able to trust the ASR to validate games correctly. - -#### Impact - -**Severity: Critical** - -If this invariant is broken, the system will not be able to distinguish between games that make correct claims about L2 -state and games that do not. This could lead to incorrect withdrawals and other problems with L2-to-L1 dependents, -implying lost funds and lost confidence. - -#### Dependencies - -- [aFDG-001](#afdg-001-fault-dispute-games-correctly-report-certain-properties) -- [aDGF-001](#adgf-001-dispute-game-factory-correctly-identifies-the-games-it-created) -- [aDGF-002](#adgf-002-games-created-by-the-disputegamefactory-will-be-monitored) -- [aASR-001](#aasr-001-incorrectly-resolving-games-will-be-blacklisted-within-the-dispute-game-finality-delay-period) -- [aASR-002](#aasr-002-if-a-larger-dispute-game-bug-is-found-all-games-will-be-retired-before-the-first-incorrect-games-dispute-game-finality-delay-period-has-passed) -- [aASR-003](#aasr-003-the-anchorstateregistry-will-be-correctly-initialized-at-deployment) -- [aSC-001](#asc-001-superchainconfig-correctly-reports-its-guardian-address) - ### iASR-002: Valid withdrawals can be finalized within some bounded amount of time #### Impact @@ -314,7 +289,6 @@ If this invariant is broken, withdrawals can be frozen for a long period of time - [aASR-002](#aasr-002-if-a-larger-dispute-game-bug-is-found-all-games-will-be-retired-before-the-first-incorrect-games-dispute-game-finality-delay-period-has-passed) - [aASR-003](#aasr-003-the-anchorstateregistry-will-be-correctly-initialized-at-deployment) - [aSC-001](#asc-001-superchainconfig-correctly-reports-its-guardian-address) -- [iASR-001](#iasr-001-games-that-make-correct-claims-about-l2-state-can-be-distinguished-from-games-that-do-not) ## Component Invariants @@ -332,7 +306,6 @@ finalizing withdrawals based on incorrect state roots, causing loss of funds. Ot #### Dependencies -- [iASR-001](#iasr-001-games-that-make-correct-claims-about-l2-state-can-be-distinguished-from-games-that-do-not) - [aASR-001](#aasr-001-incorrectly-resolving-games-will-be-blacklisted-within-the-dispute-game-finality-delay-period) - [aASR-002](#aasr-002-if-a-larger-dispute-game-bug-is-found-all-games-will-be-retired-before-the-first-incorrect-games-dispute-game-finality-delay-period-has-passed) - [aASR-003](#aasr-003-the-anchorstateregistry-will-be-correctly-initialized-at-deployment) From 315f39ec6519e600320f799af5f9a5a9b3e19623 Mon Sep 17 00:00:00 2001 From: wildmolasses Date: Fri, 13 Dec 2024 13:26:41 -0500 Subject: [PATCH 17/19] wip: maybe instead of likely --- .../stage-one/anchor-state-registry.md | 156 ++++++++++-------- .../fault-proof/stage-one/optimism-portal.md | 18 +- 2 files changed, 100 insertions(+), 74 deletions(-) diff --git a/specs/fault-proof/stage-one/anchor-state-registry.md b/specs/fault-proof/stage-one/anchor-state-registry.md index 28e574341..3b63a359a 100644 --- a/specs/fault-proof/stage-one/anchor-state-registry.md +++ b/specs/fault-proof/stage-one/anchor-state-registry.md @@ -2,73 +2,78 @@ + **Table of Contents** -- [Overview](#overview) - - [Perspective](#perspective) -- [Definitions](#definitions) - - [Dispute game](#dispute-game) - - [Likely valid game](#likely-valid-game) - - [Finalized game](#finalized-game) - - [Dispute game finality delay](#dispute-game-finality-delay) - - [Valid game](#valid-game) - - [Blacklisted game](#blacklisted-game) - - [Invalid game](#invalid-game) - - [Retired game](#retired-game) - - [Acceptable invalid anchor game](#acceptable-invalid-anchor-game) - - [Game retirement timestamp](#game-retirement-timestamp) - - [Anchor state](#anchor-state) - - [Anchor game](#anchor-game) - - [Withdrawal](#withdrawal) - - [Authorized input](#authorized-input) -- [Assumptions](#assumptions) - - [aFDG-001: Fault dispute games correctly report certain properties](#afdg-001-fault-dispute-games-correctly-report-certain-properties) - - [Mitigations](#mitigations) - - [aFDG-002: Fault dispute games with correct claims resolve correctly at some regular rate](#afdg-002-fault-dispute-games-with-correct-claims-resolve-correctly-at-some-regular-rate) - - [Mitigations](#mitigations-1) - - [aDGF-001: Dispute game factory correctly identifies the games it created](#adgf-001-dispute-game-factory-correctly-identifies-the-games-it-created) - - [Mitigations](#mitigations-2) - - [aDGF-002: Games created by the DisputeGameFactory will be monitored](#adgf-002-games-created-by-the-disputegamefactory-will-be-monitored) - - [Mitigations](#mitigations-3) - - [aASR-001: Incorrectly resolving games will be blacklisted within the dispute game finality delay period](#aasr-001-incorrectly-resolving-games-will-be-blacklisted-within-the-dispute-game-finality-delay-period) - - [Mitigations](#mitigations-4) - - [aASR-002: If a larger dispute game bug is found, all games will be retired before the first incorrect game's dispute game finality delay period has passed](#aasr-002-if-a-larger-dispute-game-bug-is-found-all-games-will-be-retired-before-the-first-incorrect-games-dispute-game-finality-delay-period-has-passed) - - [Mitigations](#mitigations-5) - - [aASR-003: The AnchorStateRegistry will be correctly initialized at deployment](#aasr-003-the-anchorstateregistry-will-be-correctly-initialized-at-deployment) - - [Mitigations](#mitigations-6) - - [aSC-001: SuperchainConfig correctly reports its guardian address](#asc-001-superchainconfig-correctly-reports-its-guardian-address) - - [Mitigations](#mitigations-7) -- [System Invariants](#system-invariants) - - [iASR-002: Valid withdrawals can be finalized within some bounded amount of time](#iasr-002-valid-withdrawals-can-be-finalized-within-some-bounded-amount-of-time) - - [Impact](#impact-1) - - [Dependencies](#dependencies-1) -- [Component Invariants](#component-invariants) - - [iASR-003: Only "truly" **valid games** will be represented as **valid games**.](#iasr-003-only-truly-valid-games-will-be-represented-as-valid-games) - - [Impact](#impact-2) - - [Dependencies](#dependencies-2) - - [iASR-004: The anchor game was created recently, within some bounded time period.](#iasr-004-the-anchor-game-was-created-recently-within-some-bounded-time-period) - - [Impact](#impact-3) - - [Dependencies](#dependencies-3) - - [iASR-005: The anchor game is a game whose claim is correct.](#iasr-005-the-anchor-game-is-a-game-whose-claim-is-correct) - - [Impact](#impact-4) - - [Dependencies](#dependencies-4) -- [Function-Level Invariants](#function-level-invariants) -- [Implementation Spec](#implementation-spec) - - [`constructor`](#constructor) - - [`initialize`](#initialize) - - [`getRecentValidGame`](#getrecentvalidgame) - - [`updateAnchorGame`](#updateanchorgame) - - [`getAnchorGame`](#getanchorgame) - - [`registerLikelyValidGame`](#registerlikelyvalidgame) - - [`tryUpdateAnchorGame`](#tryupdateanchorgame) - - [`isGameBlacklisted`](#isgameblacklisted) - - [`isGameLikelyValid`](#isgamelikelyvalid) - - [`isGameFinalized`](#isgamefinalized) - - [`isGameValid`](#isgamevalid) - - [`setRespectedGameType`](#setrespectedgametype) - - [`retireAllExistingGames`](#retireallexistinggames) - - [`setGameBlacklisted`](#setgameblacklisted) - - [`getGameFinalityDelay`](#getgamefinalitydelay) +- [Anchor State Registry](#anchor-state-registry) + - [Overview](#overview) + - [Perspective](#perspective) + - [Definitions](#definitions) + - [Dispute game](#dispute-game) + - [Likely valid game](#likely-valid-game) + - [Finalized game](#finalized-game) + - [Dispute game finality delay](#dispute-game-finality-delay) + - [Valid game](#valid-game) + - [Blacklisted game](#blacklisted-game) + - [Invalid game](#invalid-game) + - [Retired game](#retired-game) + - [Acceptable invalid anchor game](#acceptable-invalid-anchor-game) + - [Game retirement timestamp](#game-retirement-timestamp) + - [Anchor state](#anchor-state) + - [Anchor game](#anchor-game) + - [Withdrawal](#withdrawal) + - [Authorized input](#authorized-input) + - [Assumptions](#assumptions) + - [aFDG-001: Fault dispute games correctly report certain properties](#afdg-001-fault-dispute-games-correctly-report-certain-properties) + - [Mitigations](#mitigations) + - [aFDG-002: Fault dispute games with correct claims resolve correctly at some regular rate](#afdg-002-fault-dispute-games-with-correct-claims-resolve-correctly-at-some-regular-rate) + - [Mitigations](#mitigations-1) + - [aDGF-001: Dispute game factory correctly identifies the games it created](#adgf-001-dispute-game-factory-correctly-identifies-the-games-it-created) + - [Mitigations](#mitigations-2) + - [aDGF-002: Games created by the DisputeGameFactory will be monitored](#adgf-002-games-created-by-the-disputegamefactory-will-be-monitored) + - [Mitigations](#mitigations-3) + - [aASR-001: Incorrectly resolving games will be blacklisted within the dispute game finality delay period](#aasr-001-incorrectly-resolving-games-will-be-blacklisted-within-the-dispute-game-finality-delay-period) + - [Mitigations](#mitigations-4) + - [aASR-002: If a larger dispute game bug is found, all games will be retired before the first incorrect game's dispute game finality delay period has passed](#aasr-002-if-a-larger-dispute-game-bug-is-found-all-games-will-be-retired-before-the-first-incorrect-games-dispute-game-finality-delay-period-has-passed) + - [Mitigations](#mitigations-5) + - [aASR-003: The AnchorStateRegistry will be correctly initialized at deployment](#aasr-003-the-anchorstateregistry-will-be-correctly-initialized-at-deployment) + - [Mitigations](#mitigations-6) + - [aSC-001: SuperchainConfig correctly reports its guardian address](#asc-001-superchainconfig-correctly-reports-its-guardian-address) + - [Mitigations](#mitigations-7) + - [System Invariants](#system-invariants) + - [iASR-001: Invalid withdrawals can never be finalized](#iasr-001-invalid-withdrawals-can-never-be-finalized) + - [Impact](#impact) + - [Dependencies](#dependencies) + - [iASR-002: Valid withdrawals can be finalized within some bounded amount of time](#iasr-002-valid-withdrawals-can-be-finalized-within-some-bounded-amount-of-time) + - [Impact](#impact-1) + - [Dependencies](#dependencies-1) + - [Component Invariants](#component-invariants) + - [iASR-003: Only "truly" **valid games** will be represented as **valid games**.](#iasr-003-only-truly-valid-games-will-be-represented-as-valid-games) + - [Impact](#impact-2) + - [Dependencies](#dependencies-2) + - [iASR-004: The anchor game was created recently, within some bounded time period.](#iasr-004-the-anchor-game-was-created-recently-within-some-bounded-time-period) + - [Impact](#impact-3) + - [Dependencies](#dependencies-3) + - [iASR-005: The anchor game is a game whose claim is correct.](#iasr-005-the-anchor-game-is-a-game-whose-claim-is-correct) + - [Impact](#impact-4) + - [Dependencies](#dependencies-4) + - [Function-Level Invariants](#function-level-invariants) + - [Implementation Spec](#implementation-spec) + - [`constructor`](#constructor) + - [`initialize`](#initialize) + - [`getRecentValidGame`](#getrecentvalidgame) + - [`updateAnchorGame`](#updateanchorgame) + - [`getAnchorGame`](#getanchorgame) + - [`registerLikelyValidGame`](#registerlikelyvalidgame) + - [`tryUpdateAnchorGame`](#tryupdateanchorgame) + - [`isGameBlacklisted`](#isgameblacklisted) + - [`isGameLikelyValid`](#isgamelikelyvalid) + - [`isGameFinalized`](#isgamefinalized) + - [`isGameValid`](#isgamevalid) + - [`setRespectedGameType`](#setrespectedgametype) + - [`retireAllExistingGames`](#retireallexistinggames) + - [`setGameBlacklisted`](#setgameblacklisted) + - [`getGameFinalityDelay`](#getgamefinalitydelay) @@ -272,6 +277,25 @@ We assume the SuperchainConfig contract correctly returns its guardian address. ## System Invariants +### iASR-001: Invalid withdrawals can never be finalized + +#### Impact + +**Severity: Critical** + +If this invariant is broken, the system can finalize an invalid withdrawal, causing a loss of funds and a loss of confidence. + +#### Dependencies + +- [aASR-001](#aasr-001-incorrectly-resolving-games-will-be-blacklisted-within-the-dispute-game-finality-delay-period) +- [aASR-002](#aasr-002-if-a-larger-dispute-game-bug-is-found-all-games-will-be-retired-before-the-first-incorrect-games-dispute-game-finality-delay-period-has-passed) +- [aASR-003](#aasr-003-the-anchorstateregistry-will-be-correctly-initialized-at-deployment) +- [aSC-001](#asc-001-superchainconfig-correctly-reports-its-guardian-address) +- [aFDG-001](#afdg-001-fault-dispute-games-correctly-report-certain-properties) +- [aFDG-002](#afdg-002-fault-dispute-games-with-correct-claims-resolve-correctly-at-some-regular-rate) +- [aDGF-001](#adgf-001-dispute-game-factory-correctly-identifies-the-games-it-created) +- [aDGF-002](#adgf-002-games-created-by-the-disputegamefactory-will-be-monitored) + ### iASR-002: Valid withdrawals can be finalized within some bounded amount of time #### Impact @@ -301,7 +325,7 @@ correct L2 state claims. **Severity: High** -If this invariant is broken, the L1 will have an inaccurate view of L2 state. The OptimismPortal can be tricked into +If this invariant is broken, the L1 will have an inaccurate view of L2 state. The `OptimismPortal` can be tricked into finalizing withdrawals based on incorrect state roots, causing loss of funds. Other dependents would also be affected. #### Dependencies diff --git a/specs/fault-proof/stage-one/optimism-portal.md b/specs/fault-proof/stage-one/optimism-portal.md index b2fe6e99a..417fb82a4 100644 --- a/specs/fault-proof/stage-one/optimism-portal.md +++ b/specs/fault-proof/stage-one/optimism-portal.md @@ -2,8 +2,10 @@ + **Table of Contents** +- [Optimism Portal](#optimism-portal) - [Overview](#overview) - [Perspective](#perspective) - [Definitions](#definitions) @@ -12,7 +14,7 @@ - [Finalized withdrawal](#finalized-withdrawal) - [Proof maturity delay](#proof-maturity-delay) - [Assumptions](#assumptions) - - [aASR-001: AnchorStateRegistry correctly distinguishes likely valid games](#aasr-001-anchorstateregistry-correctly-distinguishes-likely-valid-games) + - [aASR-001: AnchorStateRegistry correctly distinguishes maybe valid games](#aasr-001-anchorstateregistry-correctly-distinguishes-maybe-valid-games) - [Impact](#impact) - [Mitigations](#mitigations) - [aASR-002: AnchorStateRegistry correctly distinguishes valid games](#aasr-002-anchorstateregistry-correctly-distinguishes-valid-games) @@ -49,7 +51,7 @@ An input for which there is social consensus, i.e. coming from governance. ### Proven withdrawal -A **proven withdrawal** is a withdrawal that is likely valid, because it's been proven using a **likely valid game**. +A **proven withdrawal** is a withdrawal that is maybe valid, because it's been proven using a **maybe valid game**. However, because we don't have full confidence in the game's validity, we can't yet finalize the withdrawal. ### Finalized withdrawal @@ -63,16 +65,16 @@ The **proof maturity delay** is time that must elapse between a withdrawal being ## Assumptions -### aASR-001: AnchorStateRegistry correctly distinguishes likely valid games +### aASR-001: AnchorStateRegistry correctly distinguishes maybe valid games -We assume that the AnchorStateRegistry correctly reports whether a game is a [**likely valid -game**](./anchor-state-registry.md#likely-valid-game). +We assume that the AnchorStateRegistry correctly reports whether a game is a [**maybe valid +game**](./anchor-state-registry.md#maybe-valid-game). #### Impact **Severity: Medium** -If a game is reported as likely valid when it is not, an attacker can prove a withdrawal that is invalid. If +If a game is reported as maybe valid when it is not, an attacker can prove a withdrawal that is invalid. If [aASR-002](#aasr-002-anchorstateregistry-correctly-distinguishes-valid-games) holds, this may not result in severe consequences, but would negatively impact system hygiene. @@ -115,7 +117,7 @@ paused. This would create bad system hygiene, and could lead to a loss of funds ## Top-Level Invariants -- A withdrawal transaction must be **proven** against a game that is **likely valid**. +- A withdrawal transaction must be **proven** against a game that is **maybe valid**. - A withdrawal transaction may only be finalized against a game that is **valid**. - Implicit in this is that a withdrawal transaction may only be finalized after the proof maturity delay has passed. - A withdrawal transaction may only be finalized if it has already been **proven**. @@ -136,7 +138,7 @@ paused. This would create bad system hygiene, and could lead to a loss of funds Proves a withdrawal transaction. -- Withdrawal game must not be a **maybe valid game**. +- Withdrawal game must be a **maybe valid game**. - Withdrawal transaction's target must not be the OptimismPortal address. - Withdrawal game's root claim must be equal to the hashed outputRootProof input. - Must verify that the hash of this withdrawal is stored in the L2toL1MessagePasser contract on L2. From 00eccf1b98bcaf8b86e2e50942592081516b8051 Mon Sep 17 00:00:00 2001 From: wildmolasses Date: Fri, 13 Dec 2024 14:14:43 -0500 Subject: [PATCH 18/19] wip: ASR feedback --- .../stage-one/anchor-state-registry.md | 137 +++++++++--------- .../fault-proof/stage-one/optimism-portal.md | 2 - 2 files changed, 71 insertions(+), 68 deletions(-) diff --git a/specs/fault-proof/stage-one/anchor-state-registry.md b/specs/fault-proof/stage-one/anchor-state-registry.md index 3b63a359a..c1b97bc7c 100644 --- a/specs/fault-proof/stage-one/anchor-state-registry.md +++ b/specs/fault-proof/stage-one/anchor-state-registry.md @@ -10,14 +10,13 @@ - [Perspective](#perspective) - [Definitions](#definitions) - [Dispute game](#dispute-game) - - [Likely valid game](#likely-valid-game) + - [Maybe valid game](#maybe-valid-game) - [Finalized game](#finalized-game) - [Dispute game finality delay](#dispute-game-finality-delay) - [Valid game](#valid-game) - [Blacklisted game](#blacklisted-game) - [Invalid game](#invalid-game) - [Retired game](#retired-game) - - [Acceptable invalid anchor game](#acceptable-invalid-anchor-game) - [Game retirement timestamp](#game-retirement-timestamp) - [Anchor state](#anchor-state) - [Anchor game](#anchor-game) @@ -28,46 +27,49 @@ - [Mitigations](#mitigations) - [aFDG-002: Fault dispute games with correct claims resolve correctly at some regular rate](#afdg-002-fault-dispute-games-with-correct-claims-resolve-correctly-at-some-regular-rate) - [Mitigations](#mitigations-1) - - [aDGF-001: Dispute game factory correctly identifies the games it created](#adgf-001-dispute-game-factory-correctly-identifies-the-games-it-created) + - [aFDG-003: Fault dispute games are properly incentivized to resolve correctly](#afdg-003-fault-dispute-games-are-properly-incentivized-to-resolve-correctly) - [Mitigations](#mitigations-2) - - [aDGF-002: Games created by the DisputeGameFactory will be monitored](#adgf-002-games-created-by-the-disputegamefactory-will-be-monitored) + - [aDGF-001: Dispute game factory correctly identifies the games it created](#adgf-001-dispute-game-factory-correctly-identifies-the-games-it-created) - [Mitigations](#mitigations-3) - - [aASR-001: Incorrectly resolving games will be blacklisted within the dispute game finality delay period](#aasr-001-incorrectly-resolving-games-will-be-blacklisted-within-the-dispute-game-finality-delay-period) + - [aDGF-002: Games created by the DisputeGameFactory will be monitored](#adgf-002-games-created-by-the-disputegamefactory-will-be-monitored) - [Mitigations](#mitigations-4) - - [aASR-002: If a larger dispute game bug is found, all games will be retired before the first incorrect game's dispute game finality delay period has passed](#aasr-002-if-a-larger-dispute-game-bug-is-found-all-games-will-be-retired-before-the-first-incorrect-games-dispute-game-finality-delay-period-has-passed) + - [aASR-001: Incorrectly resolving games will be blacklisted within the dispute game finality delay period](#aasr-001-incorrectly-resolving-games-will-be-blacklisted-within-the-dispute-game-finality-delay-period) - [Mitigations](#mitigations-5) - - [aASR-003: The AnchorStateRegistry will be correctly initialized at deployment](#aasr-003-the-anchorstateregistry-will-be-correctly-initialized-at-deployment) + - [aASR-002: If a larger dispute game bug is found, all games will be retired before the first incorrect game's dispute game finality delay period has passed](#aasr-002-if-a-larger-dispute-game-bug-is-found-all-games-will-be-retired-before-the-first-incorrect-games-dispute-game-finality-delay-period-has-passed) - [Mitigations](#mitigations-6) - - [aSC-001: SuperchainConfig correctly reports its guardian address](#asc-001-superchainconfig-correctly-reports-its-guardian-address) + - [aASR-003: The AnchorStateRegistry will be correctly initialized at deployment](#aasr-003-the-anchorstateregistry-will-be-correctly-initialized-at-deployment) - [Mitigations](#mitigations-7) + - [aSC-001: SuperchainConfig correctly reports its guardian address](#asc-001-superchainconfig-correctly-reports-its-guardian-address) + - [Mitigations](#mitigations-8) - [System Invariants](#system-invariants) - - [iASR-001: Invalid withdrawals can never be finalized](#iasr-001-invalid-withdrawals-can-never-be-finalized) + - [iSYS-001: Invalid withdrawals can never be finalized](#isys-001-invalid-withdrawals-can-never-be-finalized) - [Impact](#impact) - [Dependencies](#dependencies) - - [iASR-002: Valid withdrawals can be finalized within some bounded amount of time](#iasr-002-valid-withdrawals-can-be-finalized-within-some-bounded-amount-of-time) + - [iSYS-002: Valid withdrawals can be finalized within some bounded amount of time](#isys-002-valid-withdrawals-can-be-finalized-within-some-bounded-amount-of-time) - [Impact](#impact-1) - [Dependencies](#dependencies-1) - [Component Invariants](#component-invariants) - - [iASR-003: Only "truly" **valid games** will be represented as **valid games**.](#iasr-003-only-truly-valid-games-will-be-represented-as-valid-games) + - [iASR-001: Only "truly" **valid games** will be represented as **valid games**.](#iasr-001-only-truly-valid-games-will-be-represented-as-valid-games) - [Impact](#impact-2) - [Dependencies](#dependencies-2) - - [iASR-004: The anchor game was created recently, within some bounded time period.](#iasr-004-the-anchor-game-was-created-recently-within-some-bounded-time-period) + - [iASR-002: The anchor state is recent, within some bounded time period.](#iasr-002-the-anchor-state-is-recent-within-some-bounded-time-period) - [Impact](#impact-3) - [Dependencies](#dependencies-3) - - [iASR-005: The anchor game is a game whose claim is correct.](#iasr-005-the-anchor-game-is-a-game-whose-claim-is-correct) + - [iASR-003: The anchor state is a correct L2 state root](#iasr-003-the-anchor-state-is-a-correct-l2-state-root) - [Impact](#impact-4) - [Dependencies](#dependencies-4) - [Function-Level Invariants](#function-level-invariants) - [Implementation Spec](#implementation-spec) - [`constructor`](#constructor) - [`initialize`](#initialize) - - [`getRecentValidGame`](#getrecentvalidgame) - - [`updateAnchorGame`](#updateanchorgame) - - [`getAnchorGame`](#getanchorgame) - - [`registerLikelyValidGame`](#registerlikelyvalidgame) - - [`tryUpdateAnchorGame`](#tryupdateanchorgame) + - [`getRecentValidState`](#getrecentvalidstate) + - [`updateAnchorState`](#updateanchorstate) + - [`getAnchorState`](#getanchorstate) + - [`registerAnchorGameCandidate`](#registeranchorgamecandidate) + - [`tryUpdateAnchorState`](#tryupdateanchorstate) - [`isGameBlacklisted`](#isgameblacklisted) - - [`isGameLikelyValid`](#isgamelikelyvalid) + - [`isGameRetired`](#isgameretired) + - [`isGameMaybeValid`](#isgamemaybevalid) - [`isGameFinalized`](#isgamefinalized) - [`isGameValid`](#isgamevalid) - [`setRespectedGameType`](#setrespectedgametype) @@ -97,10 +99,10 @@ confidence in resolved games, and calcify the assumptions upon which withdrawals A dispute game is a contract that resolves an L2 state claim. -### Likely valid game +### Maybe valid game -A **likely valid game** is a dispute game that correctly resolved in favor of the defender. However, the system concedes -a possibility that it's not correct, and so it's not yet ready to be used as a **valid game** by dependents. A likely +A **maybe valid game** is a dispute game that correctly resolved in favor of the defender. However, the system concedes +a possibility that it's not correct, and so it's not yet ready to be used as a **valid game** by dependents. A maybe valid game meets the following conditions: - Game was created by the dispute game factory. @@ -129,7 +131,7 @@ finalized. It's set via **authorized input**. ### Valid game A game is a **valid game** if it, among other qualifications, has resolved in favor of the defender and has also matured -past the finality delay. In other words, it meets the conditions of both a **likely valid game** and a **finalized +past the finality delay. In other words, it meets the conditions of both a **maybe valid game** and a **finalized game**. ### Blacklisted game @@ -139,19 +141,13 @@ valid, and must not be used for finalizing withdrawals or any other dependent L2 ### Invalid game -An **invalid game** is a game whose claim was false, or does not meet some other **likely valid game** condition. +An **invalid game** is a game whose claim was false, or does not meet some other **maybe valid game** condition. ### Retired game A **retired game** is a game whose `createdAt` timestamp is older than the **game retirement timestamp**. A game that gets retired is no longer considered valid. -### Acceptable invalid anchor game - -An **acceptable invalid anchor game** is an **anchor game** that was a **valid game** when set and has been made -**invalid** via **game retirement**. It meets every other condition of validity and is still acceptable to use as the -**anchor game**. This is a special case that allows the system to continue functioning even if all games are retired. - ### Game retirement timestamp The game retirement timestamp determines **retired games** and can only be adjusted via **authorized input**. @@ -160,12 +156,12 @@ The game retirement timestamp determines **retired games** and can only be adjus > See [Fault Dispute Game -> Anchor State](fault-dispute-game.md#anchor-state). -An anchor state is a state root from L2. +An anchor state is the state root from a correct L2 claim that is used as a starting point for new dispute games. ### Anchor game -An **anchor game** is a **valid game** or an **acceptable invalid anchor game** that can be used by dependents as a -starting point for new dispute games. +The **anchor game** is the game whose state root is used as the **anchor state**. In the overwhelming majority of cases, +it is a **valid game**, and in any case, its claim is correct. ### Withdrawal @@ -209,6 +205,15 @@ resolve correctly to maintain the system's integrity. - Existing incentives in fault proof system design. +### aFDG-003: Fault dispute games are properly incentivized to resolve correctly + +We assume that fault dispute games are properly incentivized to resolve correctly, implying that participants are +incentivized to play the game correctly to its correct conclusion. + +#### Mitigations + +- Existing incentives in fault proof system design. + ### aDGF-001: Dispute game factory correctly identifies the games it created We assume that `DisputeGameFactory` will correctly identify whether it created a game (i.e. whether the game is @@ -233,8 +238,6 @@ We assume that games that resolve incorrectly will be blacklisted via **authoriz finality delay period. This further depends on [aDGF-002](#adgf-002-games-created-by-the-disputegamefactory-will-be-monitored). -TODO: is this true? - #### Mitigations - Stakeholder incentives / processes. @@ -246,8 +249,6 @@ We assume that a larger bug affecting many games will be noticed via monitoring ([aDGF-002](#adgf-002-games-created-by-the-disputegamefactory-will-be-monitored)) and will be retired within the dispute game finality delay period. -TODO: is this true? - #### Mitigations - Stakeholder incentives / processes. @@ -277,13 +278,14 @@ We assume the SuperchainConfig contract correctly returns its guardian address. ## System Invariants -### iASR-001: Invalid withdrawals can never be finalized +### iSYS-001: Invalid withdrawals can never be finalized #### Impact **Severity: Critical** -If this invariant is broken, the system can finalize an invalid withdrawal, causing a loss of funds and a loss of confidence. +If this invariant is broken, the system can finalize an invalid withdrawal, causing a loss of funds and a loss of +confidence. #### Dependencies @@ -296,7 +298,7 @@ If this invariant is broken, the system can finalize an invalid withdrawal, caus - [aDGF-001](#adgf-001-dispute-game-factory-correctly-identifies-the-games-it-created) - [aDGF-002](#adgf-002-games-created-by-the-disputegamefactory-will-be-monitored) -### iASR-002: Valid withdrawals can be finalized within some bounded amount of time +### iSYS-002: Valid withdrawals can be finalized within some bounded amount of time #### Impact @@ -316,17 +318,17 @@ If this invariant is broken, withdrawals can be frozen for a long period of time ## Component Invariants -### iASR-003: Only "truly" **valid games** will be represented as **valid games**. +### iASR-001: Only "truly" **valid games** will be represented as **valid games**. When asked for a **valid game** by its dependents, the AnchorStateRegistry will only serve **valid games** representing correct L2 state claims. #### Impact -**Severity: High** +**Severity: Critical** If this invariant is broken, the L1 will have an inaccurate view of L2 state. The `OptimismPortal` can be tricked into -finalizing withdrawals based on incorrect state roots, causing loss of funds. Other dependents would also be affected. +finalizing withdrawals based on incorrect state roots, causing loss of funds. Other dependents will also be affected. #### Dependencies @@ -335,10 +337,10 @@ finalizing withdrawals based on incorrect state roots, causing loss of funds. Ot - [aASR-003](#aasr-003-the-anchorstateregistry-will-be-correctly-initialized-at-deployment) - [aSC-001](#asc-001-superchainconfig-correctly-reports-its-guardian-address) -### iASR-004: The anchor game was created recently, within some bounded time period. +### iASR-002: The anchor state is recent, within some bounded time period. -When asked for the **anchor game** by fault dispute games, the contract will only serve an **anchor game** that is -recent within some bounded period of time. +When asked for the **anchor state** by fault dispute games, the contract will only serve an **anchor state** whose L2 +block timestamp is recent, within some bounded period of time. #### Impact @@ -352,10 +354,10 @@ and incorrect game resolution. - [aASR-003](#aasr-003-the-anchorstateregistry-will-be-correctly-initialized-at-deployment) - [aFDG-002](#afdg-002-fault-dispute-games-with-correct-claims-resolve-correctly-at-some-regular-rate) -### iASR-005: The anchor game is a game whose claim is correct. +### iASR-003: The anchor state is a correct L2 state root -When asked for the **anchor game** by fault dispute games, the contract will only serve an **anchor game** that is a -valid game or a valid-retired game. +When asked for the **anchor state** by fault dispute games, the contract will serve an **anchor state** that's correct, +i.e. in agreement with a flawless L2 state oracle. #### Impact @@ -384,40 +386,39 @@ The constructor must disable the initializer on the implementation contract. - `dispute game finality delay` must be an **authorized input**. - Superchain config must be an **authorized input**. -### `getRecentValidGame` +### `getRecentValidState` -Returns **anchor game**. Reverts if the **anchor game** has been **retired** i.e. is an **acceptable invalid anchor -game**. +Returns the state of the **anchor game**. Reverts if the **anchor game** has been **retired**. -### `updateAnchorGame` +### `updateAnchorState` - Game must be a **valid game**. -- Game's block number must be higher than current **anchor game**. -- This function is the ONLY way to update the **anchor game** (after initialization). +- Game's block number must be higher than current **anchor state**'s block number. +- This function is the ONLY way to update the **anchor state** (after initialization). -### `getAnchorGame` +### `getAnchorState` -Returns the **anchor game**. +Returns the **anchor state** of the **anchor game**. -- Must return a **valid game** or an **acceptable invalid anchor game**. - Must revert if the **anchor game** is a **blacklisted game**. - Must maintain the property that the timestamp of the game is not too old. - TODO: How old is too old? -### `registerLikelyValidGame` +### `registerAnchorGameCandidate` -Register the address of a **likely valid game** as a candidate for **anchor game**. +Register a **maybe valid game** as a candidate for **anchor game**. -- Callable only by a **likely valid game**. +- Callable only by a **maybe valid game**. - Calling game must only register itself (and not some other game). - TODO: determine any invariants around registry ordering. -### `tryUpdateAnchorGame` +### `tryUpdateAnchorState` -Try to update **anchor game** using registry of **likely valid games**. +Try to update the **anchor state** using registry of **maybe valid games**. - Callable by anyone. -- Find the most recent (comparing on l2BlockNumber) valid game you can find in the register within a fixed amount of gas. +- Find the most recent (comparing on l2BlockNumber) valid game you can find in the register within a fixed amount of + gas. - Fixed gas amount ensures that this function does not get more expensive to call as time goes on. - Use this as input to `updateAnchorGame`. @@ -425,9 +426,13 @@ Try to update **anchor game** using registry of **likely valid games**. Returns whether the game is a **blacklisted game**. -### `isGameLikelyValid` +### `isGameRetired` + +Returns whether the game is a **retired game**. + +### `isGameMaybeValid` -Returns whether the game is a **likely valid game**. +Returns whether the game is a **maybe valid game**. ### `isGameFinalized` diff --git a/specs/fault-proof/stage-one/optimism-portal.md b/specs/fault-proof/stage-one/optimism-portal.md index 417fb82a4..5d986f4cc 100644 --- a/specs/fault-proof/stage-one/optimism-portal.md +++ b/specs/fault-proof/stage-one/optimism-portal.md @@ -2,10 +2,8 @@ - **Table of Contents** -- [Optimism Portal](#optimism-portal) - [Overview](#overview) - [Perspective](#perspective) - [Definitions](#definitions) From 11b3b5470d0b5c8d62e41fcbd92510a8602a5adf Mon Sep 17 00:00:00 2001 From: wildmolasses Date: Fri, 13 Dec 2024 14:53:44 -0500 Subject: [PATCH 19/19] wip: more ASR feedback --- .../stage-one/anchor-state-registry.md | 180 ++++++++---------- .../fault-proof/stage-one/optimism-portal.md | 30 +-- 2 files changed, 100 insertions(+), 110 deletions(-) diff --git a/specs/fault-proof/stage-one/anchor-state-registry.md b/specs/fault-proof/stage-one/anchor-state-registry.md index c1b97bc7c..86b8eb307 100644 --- a/specs/fault-proof/stage-one/anchor-state-registry.md +++ b/specs/fault-proof/stage-one/anchor-state-registry.md @@ -2,80 +2,76 @@ - **Table of Contents** -- [Anchor State Registry](#anchor-state-registry) - - [Overview](#overview) - - [Perspective](#perspective) - - [Definitions](#definitions) - - [Dispute game](#dispute-game) - - [Maybe valid game](#maybe-valid-game) - - [Finalized game](#finalized-game) - - [Dispute game finality delay](#dispute-game-finality-delay) - - [Valid game](#valid-game) - - [Blacklisted game](#blacklisted-game) - - [Invalid game](#invalid-game) - - [Retired game](#retired-game) - - [Game retirement timestamp](#game-retirement-timestamp) - - [Anchor state](#anchor-state) - - [Anchor game](#anchor-game) - - [Withdrawal](#withdrawal) - - [Authorized input](#authorized-input) - - [Assumptions](#assumptions) - - [aFDG-001: Fault dispute games correctly report certain properties](#afdg-001-fault-dispute-games-correctly-report-certain-properties) - - [Mitigations](#mitigations) - - [aFDG-002: Fault dispute games with correct claims resolve correctly at some regular rate](#afdg-002-fault-dispute-games-with-correct-claims-resolve-correctly-at-some-regular-rate) - - [Mitigations](#mitigations-1) - - [aFDG-003: Fault dispute games are properly incentivized to resolve correctly](#afdg-003-fault-dispute-games-are-properly-incentivized-to-resolve-correctly) - - [Mitigations](#mitigations-2) - - [aDGF-001: Dispute game factory correctly identifies the games it created](#adgf-001-dispute-game-factory-correctly-identifies-the-games-it-created) - - [Mitigations](#mitigations-3) - - [aDGF-002: Games created by the DisputeGameFactory will be monitored](#adgf-002-games-created-by-the-disputegamefactory-will-be-monitored) - - [Mitigations](#mitigations-4) - - [aASR-001: Incorrectly resolving games will be blacklisted within the dispute game finality delay period](#aasr-001-incorrectly-resolving-games-will-be-blacklisted-within-the-dispute-game-finality-delay-period) - - [Mitigations](#mitigations-5) - - [aASR-002: If a larger dispute game bug is found, all games will be retired before the first incorrect game's dispute game finality delay period has passed](#aasr-002-if-a-larger-dispute-game-bug-is-found-all-games-will-be-retired-before-the-first-incorrect-games-dispute-game-finality-delay-period-has-passed) - - [Mitigations](#mitigations-6) - - [aASR-003: The AnchorStateRegistry will be correctly initialized at deployment](#aasr-003-the-anchorstateregistry-will-be-correctly-initialized-at-deployment) - - [Mitigations](#mitigations-7) - - [aSC-001: SuperchainConfig correctly reports its guardian address](#asc-001-superchainconfig-correctly-reports-its-guardian-address) - - [Mitigations](#mitigations-8) - - [System Invariants](#system-invariants) - - [iSYS-001: Invalid withdrawals can never be finalized](#isys-001-invalid-withdrawals-can-never-be-finalized) - - [Impact](#impact) - - [Dependencies](#dependencies) - - [iSYS-002: Valid withdrawals can be finalized within some bounded amount of time](#isys-002-valid-withdrawals-can-be-finalized-within-some-bounded-amount-of-time) - - [Impact](#impact-1) - - [Dependencies](#dependencies-1) - - [Component Invariants](#component-invariants) - - [iASR-001: Only "truly" **valid games** will be represented as **valid games**.](#iasr-001-only-truly-valid-games-will-be-represented-as-valid-games) - - [Impact](#impact-2) - - [Dependencies](#dependencies-2) - - [iASR-002: The anchor state is recent, within some bounded time period.](#iasr-002-the-anchor-state-is-recent-within-some-bounded-time-period) - - [Impact](#impact-3) - - [Dependencies](#dependencies-3) - - [iASR-003: The anchor state is a correct L2 state root](#iasr-003-the-anchor-state-is-a-correct-l2-state-root) - - [Impact](#impact-4) - - [Dependencies](#dependencies-4) - - [Function-Level Invariants](#function-level-invariants) - - [Implementation Spec](#implementation-spec) - - [`constructor`](#constructor) - - [`initialize`](#initialize) - - [`getRecentValidState`](#getrecentvalidstate) - - [`updateAnchorState`](#updateanchorstate) - - [`getAnchorState`](#getanchorstate) - - [`registerAnchorGameCandidate`](#registeranchorgamecandidate) - - [`tryUpdateAnchorState`](#tryupdateanchorstate) - - [`isGameBlacklisted`](#isgameblacklisted) - - [`isGameRetired`](#isgameretired) - - [`isGameMaybeValid`](#isgamemaybevalid) - - [`isGameFinalized`](#isgamefinalized) - - [`isGameValid`](#isgamevalid) - - [`setRespectedGameType`](#setrespectedgametype) - - [`retireAllExistingGames`](#retireallexistinggames) - - [`setGameBlacklisted`](#setgameblacklisted) - - [`getGameFinalityDelay`](#getgamefinalitydelay) +- [Overview](#overview) + - [Perspective](#perspective) +- [Definitions](#definitions) + - [Dispute game](#dispute-game) + - [Maybe valid game](#maybe-valid-game) + - [Finalized game](#finalized-game) + - [Dispute game finality delay](#dispute-game-finality-delay) + - [Valid game](#valid-game) + - [Blacklisted game](#blacklisted-game) + - [Invalid game](#invalid-game) + - [Retired game](#retired-game) + - [Game retirement timestamp](#game-retirement-timestamp) + - [Anchor state](#anchor-state) + - [Anchor game](#anchor-game) + - [Withdrawal](#withdrawal) + - [Authorized input](#authorized-input) +- [Assumptions](#assumptions) + - [aFDG-001: Fault dispute games correctly report certain properties](#afdg-001-fault-dispute-games-correctly-report-certain-properties) + - [Mitigations](#mitigations) + - [aFDG-002: Fault dispute games with correct claims resolve correctly at some regular rate](#afdg-002-fault-dispute-games-with-correct-claims-resolve-correctly-at-some-regular-rate) + - [Mitigations](#mitigations-1) + - [aFDG-003: Fault dispute games are properly incentivized to resolve correctly](#afdg-003-fault-dispute-games-are-properly-incentivized-to-resolve-correctly) + - [Mitigations](#mitigations-2) + - [aDGF-001: Dispute game factory correctly identifies the games it created](#adgf-001-dispute-game-factory-correctly-identifies-the-games-it-created) + - [Mitigations](#mitigations-3) + - [aDGF-002: Games created by the DisputeGameFactory will be monitored](#adgf-002-games-created-by-the-disputegamefactory-will-be-monitored) + - [Mitigations](#mitigations-4) + - [aASR-001: Incorrectly resolving games will be invalidated within the dispute game finality delay period](#aasr-001-incorrectly-resolving-games-will-be-invalidated-within-the-dispute-game-finality-delay-period) + - [Mitigations](#mitigations-5) + - [aASR-002: The AnchorStateRegistry will be correctly initialized at deployment](#aasr-002-the-anchorstateregistry-will-be-correctly-initialized-at-deployment) + - [Mitigations](#mitigations-6) + - [aSC-001: SuperchainConfig correctly reports its guardian address](#asc-001-superchainconfig-correctly-reports-its-guardian-address) + - [Mitigations](#mitigations-7) +- [System Invariants](#system-invariants) + - [iSYS-001: Invalid withdrawals can never be finalized](#isys-001-invalid-withdrawals-can-never-be-finalized) + - [Impact](#impact) + - [Dependencies](#dependencies) + - [iSYS-002: Valid withdrawals can be finalized within some bounded amount of time](#isys-002-valid-withdrawals-can-be-finalized-within-some-bounded-amount-of-time) + - [Impact](#impact-1) + - [Dependencies](#dependencies-1) +- [Component Invariants](#component-invariants) + - [iASR-001: Only "truly" **valid games** will be represented as **valid games**](#iasr-001-only-truly-valid-games-will-be-represented-as-valid-games) + - [Impact](#impact-2) + - [Dependencies](#dependencies-2) + - [iASR-002: The anchor state is recent, within some bounded time period](#iasr-002-the-anchor-state-is-recent-within-some-bounded-time-period) + - [Impact](#impact-3) + - [Dependencies](#dependencies-3) + - [iASR-003: The anchor state is a correct L2 state root](#iasr-003-the-anchor-state-is-a-correct-l2-state-root) + - [Impact](#impact-4) + - [Dependencies](#dependencies-4) +- [Function-Level Invariants](#function-level-invariants) +- [Implementation Spec](#implementation-spec) + - [`constructor`](#constructor) + - [`initialize`](#initialize) + - [`getRecentValidState`](#getrecentvalidstate) + - [`updateAnchorState`](#updateanchorstate) + - [`getAnchorState`](#getanchorstate) + - [`registerAnchorGameCandidate`](#registeranchorgamecandidate) + - [`tryUpdateAnchorState`](#tryupdateanchorstate) + - [`isGameBlacklisted`](#isgameblacklisted) + - [`isGameRetired`](#isgameretired) + - [`isGameMaybeValid`](#isgamemaybevalid) + - [`isGameFinalized`](#isgamefinalized) + - [`isGameValid`](#isgamevalid) + - [`setRespectedGameType`](#setrespectedgametype) + - [`retireAllExistingGames`](#retireallexistinggames) + - [`setGameBlacklisted`](#setgameblacklisted) + - [`getGameFinalityDelay`](#getgamefinalitydelay) @@ -232,9 +228,9 @@ We assume that games created by the `DisputeGameFactory` will be monitored for i - Stakeholder incentives. -### aASR-001: Incorrectly resolving games will be blacklisted within the dispute game finality delay period +### aASR-001: Incorrectly resolving games will be invalidated within the dispute game finality delay period -We assume that games that resolve incorrectly will be blacklisted via **authorized action** within the dispute game +We assume that games that resolve incorrectly will be blacklisted or retired via **authorized action** within the dispute game finality delay period. This further depends on [aDGF-002](#adgf-002-games-created-by-the-disputegamefactory-will-be-monitored). @@ -243,18 +239,7 @@ finality delay period. This further depends on - Stakeholder incentives / processes. - Incident response plan. -### aASR-002: If a larger dispute game bug is found, all games will be retired before the first incorrect game's dispute game finality delay period has passed - -We assume that a larger bug affecting many games will be noticed via monitoring -([aDGF-002](#adgf-002-games-created-by-the-disputegamefactory-will-be-monitored)) and will be retired within the dispute -game finality delay period. - -#### Mitigations - -- Stakeholder incentives / processes. -- Incident response plan. - -### aASR-003: The AnchorStateRegistry will be correctly initialized at deployment +### aASR-002: The AnchorStateRegistry will be correctly initialized at deployment We assume that the AnchorStateRegistry will be correctly initialized at deployment, including: @@ -289,9 +274,8 @@ confidence. #### Dependencies -- [aASR-001](#aasr-001-incorrectly-resolving-games-will-be-blacklisted-within-the-dispute-game-finality-delay-period) -- [aASR-002](#aasr-002-if-a-larger-dispute-game-bug-is-found-all-games-will-be-retired-before-the-first-incorrect-games-dispute-game-finality-delay-period-has-passed) -- [aASR-003](#aasr-003-the-anchorstateregistry-will-be-correctly-initialized-at-deployment) +- [aASR-001](#aasr-001-incorrectly-resolving-games-will-be-invalidated-within-the-dispute-game-finality-delay-period) +- [aASR-002](#aasr-002-the-anchorstateregistry-will-be-correctly-initialized-at-deployment) - [aSC-001](#asc-001-superchainconfig-correctly-reports-its-guardian-address) - [aFDG-001](#afdg-001-fault-dispute-games-correctly-report-certain-properties) - [aFDG-002](#afdg-002-fault-dispute-games-with-correct-claims-resolve-correctly-at-some-regular-rate) @@ -311,14 +295,13 @@ If this invariant is broken, withdrawals can be frozen for a long period of time - [aFDG-001](#afdg-001-fault-dispute-games-correctly-report-certain-properties) - [aDGF-001](#adgf-001-dispute-game-factory-correctly-identifies-the-games-it-created) - [aDGF-002](#adgf-002-games-created-by-the-disputegamefactory-will-be-monitored) -- [aASR-001](#aasr-001-incorrectly-resolving-games-will-be-blacklisted-within-the-dispute-game-finality-delay-period) -- [aASR-002](#aasr-002-if-a-larger-dispute-game-bug-is-found-all-games-will-be-retired-before-the-first-incorrect-games-dispute-game-finality-delay-period-has-passed) -- [aASR-003](#aasr-003-the-anchorstateregistry-will-be-correctly-initialized-at-deployment) +- [aASR-001](#aasr-001-incorrectly-resolving-games-will-be-invalidated-within-the-dispute-game-finality-delay-period) +- [aASR-002](#aasr-002-the-anchorstateregistry-will-be-correctly-initialized-at-deployment) - [aSC-001](#asc-001-superchainconfig-correctly-reports-its-guardian-address) ## Component Invariants -### iASR-001: Only "truly" **valid games** will be represented as **valid games**. +### iASR-001: Only "truly" **valid games** will be represented as **valid games** When asked for a **valid game** by its dependents, the AnchorStateRegistry will only serve **valid games** representing correct L2 state claims. @@ -332,12 +315,13 @@ finalizing withdrawals based on incorrect state roots, causing loss of funds. Ot #### Dependencies -- [aASR-001](#aasr-001-incorrectly-resolving-games-will-be-blacklisted-within-the-dispute-game-finality-delay-period) -- [aASR-002](#aasr-002-if-a-larger-dispute-game-bug-is-found-all-games-will-be-retired-before-the-first-incorrect-games-dispute-game-finality-delay-period-has-passed) -- [aASR-003](#aasr-003-the-anchorstateregistry-will-be-correctly-initialized-at-deployment) +- [aFDG-001](#afdg-001-fault-dispute-games-correctly-report-certain-properties) +- [aDGF-002](#adgf-002-games-created-by-the-disputegamefactory-will-be-monitored) +- [aASR-001](#aasr-001-incorrectly-resolving-games-will-be-invalidated-within-the-dispute-game-finality-delay-period) +- [aASR-002](#aasr-002-the-anchorstateregistry-will-be-correctly-initialized-at-deployment) - [aSC-001](#asc-001-superchainconfig-correctly-reports-its-guardian-address) -### iASR-002: The anchor state is recent, within some bounded time period. +### iASR-002: The anchor state is recent, within some bounded time period When asked for the **anchor state** by fault dispute games, the contract will only serve an **anchor state** whose L2 block timestamp is recent, within some bounded period of time. @@ -351,7 +335,7 @@ and incorrect game resolution. #### Dependencies -- [aASR-003](#aasr-003-the-anchorstateregistry-will-be-correctly-initialized-at-deployment) +- [aASR-002](#aasr-002-the-anchorstateregistry-will-be-correctly-initialized-at-deployment) - [aFDG-002](#afdg-002-fault-dispute-games-with-correct-claims-resolve-correctly-at-some-regular-rate) ### iASR-003: The anchor state is a correct L2 state root diff --git a/specs/fault-proof/stage-one/optimism-portal.md b/specs/fault-proof/stage-one/optimism-portal.md index 5d986f4cc..d3236d8b9 100644 --- a/specs/fault-proof/stage-one/optimism-portal.md +++ b/specs/fault-proof/stage-one/optimism-portal.md @@ -116,9 +116,10 @@ paused. This would create bad system hygiene, and could lead to a loss of funds ## Top-Level Invariants - A withdrawal transaction must be **proven** against a game that is **maybe valid**. -- A withdrawal transaction may only be finalized against a game that is **valid**. - - Implicit in this is that a withdrawal transaction may only be finalized after the proof maturity delay has passed. -- A withdrawal transaction may only be finalized if it has already been **proven**. +- A withdrawal transaction may only be **finalized** against a game that is **valid**. + - Implicit in this is that a withdrawal transaction may only be **finalized** after the **proof maturity delay** has + passed. +- A withdrawal transaction may only be **finalized** if it has already been **proven**. - A withdrawal transaction must be used only once to **finalize** a withdrawal. - A withdrawal transaction that is **finalized** must attempt execution. @@ -136,12 +137,13 @@ paused. This would create bad system hygiene, and could lead to a loss of funds Proves a withdrawal transaction. -- Withdrawal game must be a **maybe valid game**. -- Withdrawal transaction's target must not be the OptimismPortal address. -- Withdrawal game's root claim must be equal to the hashed outputRootProof input. -- Must verify that the hash of this withdrawal is stored in the L2toL1MessagePasser contract on L2. +- Withdrawal game must be a [**maybe valid game**](./anchor-state-registry.md#maybe-valid-game). +- Withdrawal transaction's target must not be the `OptimismPortal` address. +- Withdrawal game's root claim must be equal to the hashed `outputRootProof` input. +- Must verify that the hash of this withdrawal is stored in the `L2toL1MessagePasser` contract on L2. - A withdrawal cannot be reproved by the same proof submitter unless both of the following are true: - - the dispute game previously used to prove the withdrawal is now an invalid game. + - the dispute game previously used to prove the withdrawal is now an [**invalid + game**](./anchor-state-registry.md#invalid-game). - the withdrawal was never finalized. - System must not be paused. @@ -154,9 +156,13 @@ Finalizes a withdrawal transaction that has already been proven. finalization. - The time the withdrawal was proven must be greater or equal to the time at which the withdrawal's game was created. - Withdrawal transaction must not have been finalized before. -- The game upon which the withdrawal proof is based must be a **valid game**. +- The game upon which the withdrawal proof is based must be a [**valid game**](./anchor-state-registry.md#valid-game). - Function must revert when system is paused. -- TODO: withdrawal tx invariants (can't call token contract, exact balance must be transferred, estimator should revert - for gas estimation) -- If these invariants are met, function must attempt execution of the withdrawal transaction. +- If the gas-paying token is not ether: + - Withdrawal transaction's target must not be the OP token address. + - If the withdrawal transaction transfers value: + - The call to `transfer` must revert on fail. + - The input amount must equal the balance delta of this contract after transfer. - System must not be paused. +- If these invariants are met, function must attempt execution of the withdrawal transaction. +- If the transaction wasn't successful and the `tx.origin` is the `ESTIMATION_ADDRESS`, revert with `GasEstimation()`.