Output bisection spec cleanups (ethereum-optimism#8878)

specs/dispute-game-interface.md

@@ -75,10 +75,8 @@ enum GameStatus {
 ## `DisputeGameFactory` Interface
 
 The dispute game factory is responsible for creating new `DisputeGame` contracts
-given a `GameType` and a root `Claim`. Challenger agents will listen to the
-`DisputeGameCreated` events that are emitted by the factory as well as other events
-that pertain to detecting fault (i.e. `OutputProposed(bytes32,uint256,uint256,uint256)`) in order to keep up
-with on-going disputes in the protocol.
+given a `GameType` and a root `Claim`. Challenger agents listen to the `DisputeGameCreated` events in order to
+keep up with on-going disputes in the protocol and participate accordingly.
 
 A [`clones-with-immutable-args`](https://github.com/Saw-mon-and-Natalie/clones-with-immutable-args) factory
 (originally by @wighawag, but forked by @Saw-mon-and-Natalie) is used to create Clones. Each `GameType` has
@@ -106,6 +104,11 @@ interface IDisputeGameFactory {
     /// @param gameType The type of the DisputeGame.
     event ImplementationSet(address indexed impl, GameType indexed gameType);
 
+    /// @notice Emitted when a game type's initialization bond is updated
+    /// @param gameType The type of the DisputeGame.
+    /// @param newBond The new bond (in wei) for initializing the game type.
+    event InitBondUpdated(GameType indexed gameType, uint256 indexed newBond);
+
     /// @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_);
@@ -147,6 +150,11 @@ interface IDisputeGameFactory {
     ///         Will be cloned on creation of a new dispute game with the given `gameType`.
     function gameImpls(GameType _gameType) external view returns (IDisputeGame impl_);
 
+    /// @notice Returns the required bonds for initializing a dispute game of the given type.
+    /// @param _gameType The type of the dispute game.
+    /// @return bond_ The required bond for initializing a dispute game of the given type.
+    function initBonds(GameType _gameType) external view returns (uint256 bond_);
+
     /// @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.
@@ -158,6 +166,7 @@ interface IDisputeGameFactory {
         bytes calldata _extraData
     )
         external
+        payable
         returns (IDisputeGame proxy_);
 
     /// @notice Sets the implementation contract for a specific `GameType`.
@@ -166,6 +175,12 @@ interface IDisputeGameFactory {
     /// @param _impl The implementation contract for the given `GameType`.
     function setImplementation(GameType _gameType, IDisputeGame _impl) external;
 
+    /// @notice Sets the bond (in wei) for initializing a game type.
+    /// @dev May only be called by the `owner`.
+    /// @param _gameType The type of the DisputeGame.
+    /// @param _initBond The bond (in wei) for initializing a game type.
+    function setInitBond(GameType _gameType, uint256 _initBond) external;
+
     /// @notice Returns a unique identifier for the given dispute game parameters.
     /// @dev Hashes the concatenation of `gameType . rootClaim . extraData`
     ///      without expanding memory.
@@ -186,12 +201,13 @@ interface IDisputeGameFactory {
 
 ## `DisputeGame` Interface
 
-The dispute game interface should be generic enough to allow it to work with any
-proof system. This means that it should work fault proofs, validity proofs,
-an attestation based proof system, or any other source of truth that adheres to
-the interface.
+The dispute game interface defines a generic, black-box dispute. It exposes stateful information such as the status of
+the dispute, when it was created, as well as the bootstrap data and dispute type. This interface exposes one state
+mutating function, `resolve`, which when implemented should deterministically yield an opinion about the `rootClaim`
+and reflect the opinion by updating the `status` to `CHALLENGER_WINS` or `DEFENDER_WINS`.
 
-Clones of the `IDisputeGame`'s `initialize` functions will be called by the `DisputeGameFactory` upon creation.
+Clones of the `IDisputeGame`'s `initialize` functions will be called by the `DisputeGameFactory` atomically upon
+creation.
 
 ```solidity
 /// @title IDisputeGame

specs/fault-dispute-game.md

@@ -34,11 +34,10 @@
 
 ## 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 over [output roots][g-output-root] and execution traces of single block state
-transitions down to a single instruction step. It relies on a Virtual Machine (VM) to falsify invalid claims made at
-a single instruction step.
+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 over [output roots][g-output-root] and execution traces of single
+block state transitions 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 range over the entire historical state of L2, until the source of dispute is a single
@@ -140,7 +139,8 @@ 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.
+This is an immutable, preset to a FDG implementation, representing the duration of the game. Each top level team will
+receive half of this duration on their initial chess clocks.
 
 ## Game Mechanics
 
@@ -218,7 +218,7 @@ If the STF post-state does not match the claimed state, the challenge succeeds.
 ///        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;
+function step(uint256 _claimIndex, bool _isAttack, bytes calldata _stateData, bytes calldata _proof) external;
 ```
 
 ### Step Types
@@ -257,10 +257,10 @@ function addLocalData(uint256 _ident, uint256 _execLeafIdx, uint256 _partOffset)
 
 The `addLocalData` function loads parts of a pre-image to VM's `PreimageOracle`. Players use this to ensure pre-image
 parts are available to the VM during a step. Because there are multiple sets of local preimage keys that belong to the
-`FaultDisputeGame` contract due to the ability for players to bisect to any block `n->n+1` state transition since the
-configured genesis, the `_execLeafIdx` parameter enables a search for the starting / disputed outputs to be performed
-such that the contract can write to and reference unique local keys in the `PreimageOracle` for each of these `n->n+1`
-transitions.
+`FaultDisputeGame` contract due to the ability for players to bisect to any block $n \rarrow n + 1$ state transition
+since the configured genesis, the `_execLeafIdx` parameter enables a search for the starting / disputed outputs to be
+performed such that the contract can write to and reference unique local keys in the `PreimageOracle` for each of these
+$n \rarrow n + 1$ transitions.
 
 ### Team Dynamics
 

specs/fault-proof.md

@@ -409,7 +409,8 @@ Fault Proof VMs:
 [Interactive Dispute Game]: #Fault-Proof-Interactive-Dispute-Game
 
 The interactive dispute game allows actors to resolve a dispute with an onchain challenge-response game
-that bisects the execution trace of the VM, bounded with a base-case that proves a VM trace step.
+that bisects to a disagreed block $n \rarrow n + 1$ state transition, and then over the execution trace of the VM which
+models this state transition, bounded with a base-case that proves a single VM trace step.
 
 The game is multi-player: different non-aligned actors may participate when bonded.