From 794d8897627a99b9f3d37898848a0c28a202f25b Mon Sep 17 00:00:00 2001 From: wildmolasses Date: Fri, 6 Dec 2024 14:29:04 -0500 Subject: [PATCH] wip: feedback --- .../stage-one/anchor-state-registry.md | 120 ++++++++---------- .../stage-one/dispute-game-interface.md | 2 +- .../fault-proof/stage-one/optimism-portal.md | 24 ++-- 3 files changed, 69 insertions(+), 77 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..4119600b5 100644 --- a/specs/fault-proof/stage-one/anchor-state-registry.md +++ b/specs/fault-proof/stage-one/anchor-state-registry.md @@ -2,49 +2,47 @@ - **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 +88,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. @@ -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**. - -- 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`). +Returns **latest valid game**, or reverts if there is no **latest valid game**. -### `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)