Merge pull request #7122 from ethereum-optimism/inphi/dispute-specs

specs: Update Dispute Game Specifications

specs/dispute-game-interface.md

@@ -30,6 +30,13 @@ single dispute game will not result in the bug becoming consensus.
 For added context, we define a few types that are used in the following snippets.
 
 ```solidity
+
+/// @notice A custom type for a generic hash.
+type Hash is bytes32;
+
+/// @notice A dedicated timestamp type.
+type Timestamp is uint64;
+
 /// @notice The type of proof system being used.
 enum GameType {
     /// @dev The game will use a `IDisputeGame` implementation that utilizes fault proofs.
@@ -90,38 +97,74 @@ interface IDisputeGameFactory {
     /// @param rootClaim The root claim of the dispute game
     event DisputeGameCreated(address indexed disputeProxy, GameType indexed gameType, Claim indexed rootClaim);
 
-    /// @notice `games` queries an internal a mapping that maps the hash of `gameType ++ rootClaim ++ extraData`
-    ///          to the deployed `DisputeGame` clone.
+    /// @notice Emitted when a new game implementation added to the factory
+    /// @param impl The implementation contract for the given `GameType`.
+    /// @param gameType The type of the DisputeGame.
+    event ImplementationSet(address indexed impl, GameType indexed gameType);
+
+    /// @notice The total number of dispute games created by this factory.
+    /// @return gameCount_ The total number of dispute games created by this factory.
+    function gameCount() external view returns (uint256 gameCount_);
+
+    /// @notice `games` queries an internal mapping that maps the hash of
+    ///         `gameType ++ rootClaim ++ extraData` to the deployed `DisputeGame` clone.
     /// @dev `++` equates to concatenation.
-    /// @param gameType The type of the DisputeGame - used to decide the proxy implementation
-    /// @param rootClaim The root claim of the DisputeGame.
-    /// @param extraData Any extra data that should be provided to the created dispute game.
-    /// @return _proxy The clone of the `DisputeGame` created with the given parameters. Returns `address(0)` if nonexistent.
-    function games(GameType gameType, Claim rootClaim, bytes calldata extraData) external view returns (IDisputeGame _proxy);
-
-    /// @notice `gameImpls` is a mapping that maps `GameType`s to their respective `IDisputeGame` implementations.
-    /// @param gameType The type of the dispute game.
-    /// @return _impl The address of the implementation of the game type. Will be cloned on creation of a new dispute game
-    ///               with the given `gameType`.
-    function gameImpls(GameType gameType) public view returns (IDisputeGame _impl);
-
-    /// @notice The owner of the contract.
-    /// @dev Owner Permissions:
-    ///      - Update the implementation contracts for a given game type.
-    /// @return _owner The owner of the contract.
-    function owner() public view returns (address _owner);
+    /// @param _gameType The type of the DisputeGame - used to decide the proxy implementation
+    /// @param _rootClaim The root claim of the DisputeGame.
+    /// @param _extraData Any extra data that should be provided to the created dispute game.
+    /// @return proxy_ The clone of the `DisputeGame` created with the given parameters.
+    ///         Returns `address(0)` if nonexistent.
+    /// @return timestamp_ The timestamp of the creation of the dispute game.
+    function games(GameType _gameType, Claim _rootClaim, bytes calldata _extraData)
+        external
+        view
+        returns (IDisputeGame proxy_, Timestamp timestamp_);
+
+    /// @notice `gameAtIndex` returns the dispute game contract address and its creation timestamp
+    ///          at the given index. Each created dispute game increments the underlying index.
+    /// @param _index The index of the dispute game.
+    /// @return gameType_ The type of the DisputeGame - used to decide the proxy implementation.
+    /// @return timestamp_ The timestamp of the creation of the dispute game.
+    /// @return proxy_ The clone of the `DisputeGame` created with the given parameters.
+    ///         Returns `address(0)` if nonexistent.
+    function gameAtIndex(uint256 _index)
+        external
+        view
+        returns (GameType gameType_, Timestamp timestamp_, IDisputeGame proxy_);
+
+    /// @notice `gameImpls` is a mapping that maps `GameType`s to their respective
+    ///         `IDisputeGame` implementations.
+    /// @param _gameType The type of the dispute game.
+    /// @return impl_ The address of the implementation of the game type.
+    ///         Will be cloned on creation of a new dispute game with the given `gameType`.
+    function gameImpls(GameType _gameType) external view returns (IDisputeGame impl_);
 
     /// @notice Creates a new DisputeGame proxy contract.
-    /// @param gameType The type of the DisputeGame - used to decide the proxy implementation
-    /// @param rootClaim The root claim of the DisputeGame.
-    /// @param extraData Any extra data that should be provided to the created dispute game.
-    function create(GameType gameType, Claim rootClaim, bytes calldata extraData) external returns (IDisputeGame proxy);
-
-    /// @notice Sets the implementation contract for a specific `GameType`
+    /// @param _gameType The type of the DisputeGame - used to decide the proxy implementation.
+    /// @param _rootClaim The root claim of the DisputeGame.
+    /// @param _extraData Any extra data that should be provided to the created dispute game.
+    /// @return proxy_ The address of the created DisputeGame proxy.
+    function create(GameType _gameType, Claim _rootClaim, bytes calldata _extraData)
+        external
+        returns (IDisputeGame proxy_);
+
+    /// @notice Sets the implementation contract for a specific `GameType`.
     /// @dev May only be called by the `owner`.
-    /// @param gameType The type of the DisputeGame
-    /// @param impl The implementation contract for the given `GameType`
-    function setImplementation(GameType gameType, IDisputeGame impl) external;
+    /// @param _gameType The type of the DisputeGame.
+    /// @param _impl The implementation contract for the given `GameType`.
+    function setImplementation(GameType _gameType, IDisputeGame _impl) external;
+
+    /// @notice Returns a unique identifier for the given dispute game parameters.
+    /// @dev Hashes the concatenation of `gameType . rootClaim . extraData`
+    ///      without expanding memory.
+    /// @param _gameType The type of the DisputeGame.
+    /// @param _rootClaim The root claim of the DisputeGame.
+    /// @param _extraData Any extra data that should be provided to the created dispute game.
+    /// @return uuid_ The unique identifier for the given dispute game parameters.
+    function getGameUUID(GameType _gameType, Claim _rootClaim, bytes memory _extraData)
+        external
+        pure
+        returns (Hash uuid_);
 }
 ```
 
@@ -146,82 +189,51 @@ interface IDisputeGame {
     /// @custom:invariant The `initialize` function may only be called once.
     function initialize() external;
 
-    /// @notice Returns the semantic version of the DisputeGame contract
-    function version() external pure returns (string memory _version);
+    /// @notice Emitted when the game is resolved.
+    /// @param status The status of the game after resolution.
+    event Resolved(GameStatus indexed status);
 
     /// @notice Returns the timestamp that the DisputeGame contract was created at.
-    function createdAt() external pure returns (Timestamp _createdAt);
+    function createdAt() external pure returns (Timestamp createdAt_);
 
     /// @notice Returns the current status of the game.
-    function status() external view returns (GameStatus _status);
+    function status() external view returns (GameStatus status_);
 
     /// @notice Getter for the game type.
     /// @dev `clones-with-immutable-args` argument #1
     /// @dev The reference impl should be entirely different depending on the type (fault, validity)
     ///      i.e. The game type should indicate the security model.
-    /// @return _gameType The type of proof system being used.
-    function gameType() external view returns (GameType _gameType);
+    /// @return gameType_ The type of proof system being used.
+    function gameType() external view returns (GameType gameType_);
 
     /// @notice Getter for the root claim.
-    /// @return _rootClaim The root claim of the DisputeGame.
+    /// @return rootClaim_ The root claim of the DisputeGame.
     /// @dev `clones-with-immutable-args` argument #2
-    function rootClaim() external view returns (Claim _rootClaim);
+    function rootClaim() external view returns (Claim rootClaim_);
 
     /// @notice Getter for the extra data.
     /// @dev `clones-with-immutable-args` argument #3
-    /// @return _extraData Any extra data supplied to the dispute game contract by the creator.
-    function extraData() external view returns (bytes memory _extraData);
+    /// @return extraData_ Any extra data supplied to the dispute game contract by the creator.
+    function extraData() external view returns (bytes memory extraData_);
 
-    /// @notice Returns the address of the `BondManager` used 
-    function bondManager() public view returns (IBondManager _bondManager);
+    /// @notice Returns the address of the `BondManager` used
+    function bondManager() public view returns (IBondManager bondManager_);
 
     /// @notice If all necessary information has been gathered, this function should mark the game
     ///         status as either `CHALLENGER_WINS` or `DEFENDER_WINS` and return the status of
     ///         the resolved game. It is at this stage that the bonds should be awarded to the
     ///         necessary parties.
     /// @dev May only be called if the `status` is `IN_PROGRESS`.
-    function resolve() public returns (GameStatus _status);
-}
-
-////////////////////////////////////////////////////////////////
-//              OUTPUT ATTESTATION DISPUTE GAME               //
-////////////////////////////////////////////////////////////////
-
-/// @title IDisputeGame_OutputAttestation
-/// @notice The interface for an attestation-based DisputeGame meant to contest output
-///         proposals in Optimism's `L2OutputOracle` contract.
-interface IDisputeGame_OutputAttestation is IDisputeGame {
-    /// @notice A mapping of addresses from the `signerSet` to booleans signifying whether
-    ///         or not they have authorized the `rootClaim` to be invalidated.
-    function challenges(address challenger) external view returns (bool _challenged);
-
-    /// @notice The signer set consists of authorized public keys that may challenge the `rootClaim`.
-    ///         This set of signers is snapshotted from the `SystemConfig` upon creation of the game.
-    /// @return An array of authorized signers from the `SystemConfig` contract.
-    function frozenSignerSet() external view returns (address[] memory _signers);
-
-    /// @notice The signer set consists of authorized public keys that may challenge the `rootClaim`.
-    /// @return _isAuthorized Whether or not the `addr` is part of the frozen signer set.
-    function signerSet(address addr) external view override returns (bool _isAuthorized);
-
-    /// @notice The amount of signatures required to successfully challenge the `rootClaim`
-    ///         output proposal. Once this threshold is met by members of the `signerSet`
-    ///         calling `challenge`, the game will be resolved to `CHALLENGER_WINS`.
-    /// @custom:invariant The `signatureThreshold` may never be greater than the length of the `signerSet`.
-    function frozenSignatureThreshold() external view returns (uint256 _signatureThreshold);
-
-    /// @notice Returns the L2 Block Number that the `rootClaim` commits to. Exists within the `extraData`.
-    function l2BlockNumber() public view returns (uint256 _l2BlockNumber);
-
-    /// @notice Challenge the `rootClaim`.
-    /// @dev - If the `ecrecover`ed address that created the signature is not a part of the
-    ///      signer set returned by `signerSet`, this function should revert.
-    ///      - If the signature provided is the signature that breaches the signature threshold,
-    ///      the function should call the `resolve` function to resolve the game as `CHALLENGER_WINS`.
-    ///      - When the game resolves, the bond attached to the root claim should be distributed among
-    ///      the signers who participated in challenging the invalid claim.
-    /// @param signature An EIP-712 signature committing to the `rootClaim` and `l2BlockNumber` (within the `extraData`)
-    ///                  from a key that exists within the `signerSet`.
-    function challenge(bytes calldata signature) external;
+    /// @return status_ The status of the game after resolution.
+    function resolve() public returns (GameStatus status_);
+
+    /// @notice A compliant implementation of this interface should return the components of the
+    ///         game UUID's preimage provided in the cwia payload. The preimage of the UUID is
+    ///         constructed as `keccak256(gameType . rootClaim . extraData)` where `.` denotes
+    ///         concatenation.
+    /// @return gameType_ The type of proof system being used.
+    /// @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_);
 }
 ```

specs/fault-dispute-game.md

+# Fault Dispute Game
+
+<!-- START doctoc generated TOC please keep comment here to allow auto update -->
+<!-- DON'T EDIT THIS SECTION, INSTEAD RE-RUN doctoc TO UPDATE -->
+**Table of Contents**
+
+- [Overview](#overview)
+- [Definitions](#definitions)
+  - [Virtual Machine (VM)](#virtual-machine-vm)
+  - [Execution Trace](#execution-trace)
+  - [Claims](#claims)
+  - [DAG](#dag)
+  - [Game Tree](#game-tree)
+  - [Position](#position)
+  - [GAME_DURATION](#game_duration)
+- [Game Mechanics](#game-mechanics)
+  - [Actors](#actors)
+  - [Moves](#moves)
+    - [Attack](#attack)
+    - [Defend](#defend)
+  - [Step](#step)
+  - [Step Types](#step-types)
+  - [Team Dynamics](#team-dynamics)
+  - [Game Clock](#game-clock)
+  - [Resolution](#resolution)
+
+<!-- END doctoc generated TOC please keep comment here to allow auto update -->
+
+## Overview
+
+The Fault Dispute Game (FDG) is a specific type of
+[dispute game](./dispute-game-interface.md) that verifies the validity of a
+root claim by iteratively bisecting an execution trace down to a single instruction step.
+It relies on a Virtual Machine (VM) to falsify invalid claims made
+at a single instruction step.
+
+Actors, i.e. Players, interact with the game by making claims that dispute other claims in the FDG.
+Each claim made narrows the execution trace until the source of dispute is a single state transition.
+Once a time limit is reached, the dispute game is _resolved_, based on
+claims made that are disputed and which aren't, to determine the winners of the game.
+
+## Definitions
+
+### Virtual Machine (VM)
+
+This is a state transition function (STF) that takes a _pre-state_ and computes the post-state.
+The VM may reference external data during the STF and as such, it also accepts a _proof_ of this data.
+Typically, the pre-state contains a commitment to the _proof_ to verify the integrity of the data referenced.
+
+Mathemtically, we define the STF as $VM(S_i,P_i)$ where
+
+- $S_i$ is the pre-state
+- $P_i$ is an optional proof needed for the transition from $S_i$ to $S_{i+1}$.
+
+### Execution Trace
+
+An execution trace $T$ is a sequence $(S_0,S_1,S_2,...,S_n)$ where each $S_i$ is a VM state and
+for each $i$, $0 \le i \lt n$, $S_{n+1} = VM(S_i, P_i)$.
+Every execution trace has a unique starting state, $S_0$, that's preset to a FDG implementation.
+We refer to this state as the **ABSOLUTE\_PRESTATE**.
+
+### Claims
+
+Claims assert an execution trace. This is represented as `ClaimHash`, a `bytes32` commitment to
+the last VM state in the trace. A FDG is initialized with a root claim, which commits to the entire
+execution trace. As we'll see later, there can be multiple claims, committing to different states in the FDG.
+
+### DAG
+
+A Directed Acyclic Graph $G = (V,E)$ representing the relationship between claims, where:
+
+- $V$ is the set of nodes, each representing a claim. Formally, $V = \{C_1,C_2,...,C_n\}$,
+where $C_i$ is a claim.
+- $E$ is the set of _directed_ edges. An edge $(C_i,C_j)$ exists if $C_j$ is a direct dispute
+against $C_i$ through either an "Attack" or "Defend" [move](#moves).
+
+### Game Tree
+
+The Game Tree is a binary tree of positions. Every claim in the DAG references a position in the Game Tree.
+ The Game Tree has a maximum depth, `MAX_GAME_DEPTH`, that's preset to an FDG implementation.
+Thus, the Game Tree contains $2^{d-1}$ positions, where $d$ is the `MAX_GAME_DEPTH`
+(unless $d=0$, in which case there's only 1 position).
+
+### Position
+
+A position represents the location of a claim in the Game Tree. This is represented by a
+"generalized index" (or **gindex**) where the high-order bit is the level in the tree and the remaining
+bits is a unique bit pattern, allowing a unique identifier for each node in the tree.
+
+The **gindex** of a position $n$ can be calculated as $2^{d(n)} + idx(n)$, where:
+
+- $d(n)$ is a function returning the depth of the position in the Game Tree
+- $idx(n)$ is a function returning the index of the position at its depth (starting from the left).
+
+Positions at the deepest level of the game tree correspond to indices in the execution trace.
+Positions higher up the game tree also cover the deepest, right-most positions relative to the current position.
+We refer to this coverage as the **trace index** of a Position.
+
+> This means claims commit to an execution trace that terminates at the same index as their Position's trace index.
+
+Note that there can be multiple positions covering the same _trace index_.
+
+### GAME_DURATION
+
+This is an immutable, preset to a FDG implementation, representing the duration of the game.
+
+## Game Mechanics
+
+### Actors
+
+The game involves two types of participants (or Players): **Challengers** and **Defenders**.
+These players are grouped into separate teams, each employing distinct strategies to interact with the game.
+Team members share a common goal regarding the game's outcome. Players interact with the game primarily through _moves_.
+
+### Moves
+
+A Move is a challenge against a claim's execution trace and must include an alternate claim asserting a different trace.
+Moves can either be attacks or defenses and serve to update to DAG by adding nodes and edges targeting the disputed
+claim.
+
+Initially, claims added to the DAG are _uncontesteed_ (i.e. not **countered**). Once a move targets a claim, that claim
+ is considered countered.
+The status of a claim &mdash; whether it's countered or not &mdash; helps determine its validity and, ultimately, the
+ game's winner.
+
+#### Attack
+
+A logical move made when a claim is disagreed with.
+A claim at the relative attack position to a node, `n`, in the Game Tree commits to half
+of the trace of the `n`’s claim.
+The attack position relative to a node can be calculated by multiplying its gindex by 2.
+
+To illustrate this, here's a Game Tree highlighting an attack on a Claim positioned at 6.
+
+![Attacking node 6](assets/attack.png)
+
+Attacking the node at 6 moves creates a new claim positioned at 12.
+
+#### Defend
+
+The logical move against a claim when you agree with both it and its parent.
+A defense at the relative position to a node, `n``, in the Game Tree commits to the first half of n + 1’s trace range.
+
+![Defend at 4](assets/defend.png)
+
+Note that because of this, some nodes may never exist within the Game Tree.
+However, they're not necessary as these nodes have complimentary, valid positions
+with the same trace index within the tree. For example, a Position with gindex 5 has the same
+trace index as another Position with gindex 2. We can verify that all trace indices have valid moves within the game:
+
+![Game Tree Showing All Valid Move Positions](assets/valid-moves.png)
+
+There may be multiple claims at the same position, so long as their `ClaimHash` are unique.
+
+Each move adds new claims to the Game Tree at strictly increasing depth.
+Once a claim is at `MAX_GAME_DEPTH`, the only way to dispute such claims is to **step**.
+
+### Step
+
+At `MAX_GAME_DEPTH`, the position of claims correspond to indices of an execution trace.
+It's at this point that the FDG is able to query the VM to determine the validity of claims,
+by checking the states they're committing to.
+This is done by applying the VM's STF to the state a claim commits to.
+If the STF post-state does not match the claimed state, the challenge succeeds.
+
+```solidity
+/// @notice Perform an instruction step via an on-chain fault proof processor.
+/// @dev This function should point to a fault proof processor in order to execute
+///      a step in the fault proof program on-chain. The interface of the fault proof
+///      processor contract should adhere to the `IBigStepper` interface.
+/// @param _claimIndex The index of the challenged claim within `claimData`.
+/// @param _isAttack Whether or not the step is an attack or a defense.
+/// @param _stateData The stateData of the step is the preimage of the claim at the given
+///        prestate, which is at `_stateIndex` if the move is an attack and `_claimIndex` if
+///        the move is a defense. If the step is an attack on the first instruction, it is
+///        the absolute prestate of the fault proof VM.
+/// @param _proof Proof to access memory nodes in the VM's merkle state tree.
+function step(uint256 _claimIndex, bool isAttack, bytes calldata _stateData, bytes calldata _proof) external;
+```
+
+### Step Types
+
+Similar to moves, there are two ways to step on a claim; attack or defend.
+These determine the pre-state input to the VM STF and the expected output.
+
+- **Attack Step** - Challenges a claim by providing a pre-state, proving an invalid state transition.
+It uses the previous state in the execution trace as input and expects the disputed claim's state as output.
+There must exist a claim in the DAG that commits to the input.
+- **Defense Step** - Challenges a claim by proving it was an invalid attack,
+thereby defending the disputed ancestor's claim. It uses the disputed claim's state as input and expects
+the next state in the execution trace as output. There must exist a claim in the DAG that commits to the
+ expected output.
+
+The FDG step handles the inputs to the VM and asserts the expected output.
+A step that successfully proves an invalid post-state (when attacking) or pre-state (when defending) is a
+successful counter against the disputed claim.
+Players interface with `step` by providing an indicator of attack and state data (including any proofs)
+that corresponds to the expected pre/post state (depending on whether it's an attack or defend).
+The FDG will assert that an existing claim commits to the state data provided by players.
+
+### Team Dynamics
+
+Challengers seek to dispute the root claim, while Defenders aim to support it.
+Both types of actors will move accordingly to support their team. For Challengers, this means
+attacking the root claim and disputing claims positioned at even depths in the Game Tree.
+Defenders do the opposite by disputing claims positioned at odd depths.
+
+Players on either team are motivated to support the actions of their teammates.
+This involves countering disputes against claims made by their team (assuming these claims are honest).
+Uncontested claims are likely to result in a loss, as explained later under [Resolution](#resolution).
+
+### Game Clock
+
+Every claim in the game has a Clock. A claim's inherits the clock of its grandparent claim in the
+ DAG (and so on). Akin to a chess clock, it keeps track of the total time each team takes to make
+  moves, preventing delays.
+Making a move resumes the clock for the disputed claim and puases it for the newly added one.
+
+A move against a particular claim is no longer possible once the parent of the disputed claim's Clock
+ has exceeded half of the `GAME_DURATION`. By which point, the claim's clock has _expired_.
+
+### Resolution
+
+Resolving the FDG determines which team won.
+This is done by examining the left-most, uncontested (or undisputed) claim.
+If the depth of this claim is odd then Challengers win, otherwise Defenders win.
+Resolution is only possible once the Clock of the left-most, uncontested claim has expired.
+
+Given these rules, players are motivated to move quickly to challenge dishonest claims.
+Each move bisects the execution trace and eventually, `MAX_GAME_DEPTH` is reached where disputes
+can be settled conclusively. Dishonest players are disincentivized to participate, via backwards induction,
+as an invalid claim won't remain uncontested. Further incentives can be added to the game by requiring
+claims to be bonded, while rewarding game winners using the bonds of dishonest claims.