Merge pull request #5264 from ethereum-optimism/specs/dispute-game-interface

specs: DisputeGame interface + behavior

specs/dispute-game-interface.md

+# Dispute Game Interface
+
+<!-- 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)
+- [Types](#types)
+- [`DisputeGameFactory` Interface](#disputegamefactory-interface)
+- [`DisputeGame` Interface](#disputegame-interface)
+
+<!-- END doctoc generated TOC please keep comment here to allow auto update -->
+
+## Overview
+
+A dispute game is played between multiple parties when contesting the truthiness
+of a claim. In the context of an optimistic rollup, claims are made about the
+state of the layer two network to enable withdrawals to the layer one. A proposer
+makes a claim about the layer two state such that they can withdraw and a
+challenger can dispute the validity of the claim. The security of the layer two
+comes from the ability of fraudulent withdrawals being able to be disputed.
+
+A dispute game interface is defined to allow for multiple implementations of
+dispute games to exist. If multiple dispute games run in production, it gives
+a similar security model as having multiple protocol clients, as a bug in a
+single dispute game will not result in the bug becoming consensus.
+
+## Types
+
+For added context, we define a few types that are used in the following snippets.
+
+```solidity
+/// @notice The type of proof system being used.
+enum GameType {
+    /// @dev The game will use a `IDisputeGame` implementation that utilizes fault proofs.
+    FAULT,
+    /// @dev The game will use a `IDisputeGame` implementation that utilizes validity proofs.
+    VALIDITY,
+    /// @dev The game will use a `IDisputeGame` implementation that utilizes attestation proofs.
+    ATTESTATION
+}
+
+/// @notice The current status of the dispute game.
+enum GameStatus {
+    /// @dev The game is currently in progress, and has not been resolved.
+    IN_PROGRESS,
+    /// @dev The game has concluded, and the `rootClaim` was challenged successfully.
+    CHALLENGER_WINS,
+    /// @dev The game has concluded, and the `rootClaim` could not be contested.
+    DEFENDER_WINS
+}
+
+/// @notice A dedicated timestamp type.
+type Timestamp is uint64;
+
+/// @notice A `Claim` type represents a 32 byte hash or other unique identifier for a claim about
+///         a certain piece of information.
+/// @dev For the `FAULT` `GameType`, this will be a root of the merklized state of the fault proof
+///      program at the end of the state transition.
+///      For the `ATTESTATION` `GameType`, this will be an output root.
+type Claim is bytes32;
+```
+
+## `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.
+
+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
+a corresponding implementation within the factory, and when a new game is created, the factory creates a
+clone of the `GameType`'s pre-deployed implementation contract.
+
+The `rootClaim` of created dispute games can either be a claim that the creator agrees or disagrees with.
+This is an implementation detail that is left up to the `IDisputeGame` to handle within its `resolve` function.
+
+When the `DisputeGameFactory` creates a new `DisputeGame` contract, it calls `initialize()` on the clone to
+set up the game.
+
+```solidity
+/// @title IDisputeGameFactory
+/// @notice The interface for a DisputeGameFactory contract.
+interface IDisputeGameFactory {
+    /// @notice Emitted when a new dispute game is created
+    /// @param disputeProxy The address of the dispute game proxy
+    /// @param gameType The type of the dispute game proxy's implementation
+    /// @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.
+    /// @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);
+
+    /// @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`
+    /// @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;
+}
+```
+
+## `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.
+
+Clones of the `IDisputeGame`'s `initialize` functions will be called by the `DisputeGameFactory` upon creation.
+
+```solidity
+////////////////////////////////////////////////////////////////
+//                    GENERIC DISPUTE GAME                    //
+////////////////////////////////////////////////////////////////
+
+/// @title IDisputeGame
+/// @notice The generic interface for a DisputeGame contract.
+interface IDisputeGame {
+    /// @notice Initializes the DisputeGame contract.
+    /// @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 Returns the timestamp that the DisputeGame contract was created at.
+    function createdAt() external pure returns (Timestamp _createdAt);
+
+    /// @notice Returns the current status of the game.
+    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);
+
+    /// @notice Getter for the root claim.
+    /// @return _rootClaim The root claim of the DisputeGame.
+    /// @dev `clones-with-immutable-args` argument #2
+    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);
+
+    /// @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`.
+    /// @return An array of authorized signers.
+    function signerSet() external view returns (address[] memory _signers);
+
+    /// @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 signatureThreshold() public view returns (uint16 _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 `ecrecover`ed address that created the signature is not the msg.sender,
+    ///      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;
+}
+```

specs/dispute-game.md

+# 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**
+
+- [Attestation Dispute Game](#attestation-dispute-game)
+  - [Smart Contract Implementation](#smart-contract-implementation)
+    - [Attestation Structure](#attestation-structure)
+  - [Why EIP-712](#why-eip-712)
+
+<!-- END doctoc generated TOC please keep comment here to allow auto update -->
+
+## Attestation Dispute Game
+
+The output attestation based dispute game shifts the current permissioned output proposal process
+to a permissionless, social-consensus based architecture that can progressively decentralize over
+time by increasing the size of the signer set. In this "game," output proposals can be submitted
+permissionlessly. To prevent "invalid output proposals," a social quorum can revert an output proposal
+when an invalid one is discovered. The set of signers is maintained in the `SystemConfig` contract,
+and these signers will issue [EIP-712](https://eips.ethereum.org/EIPS/eip-712) signatures
+over canonical output roots and the `l2BlockNumber`s they commit to as attestations. To learn more,
+see the [DisputeGame Interface Spec](./dispute-game-interface.md).
+
+In the above language, an "invalid output proposal" is defined as an output proposal that represents
+a non-canonical state of the L2 chain.
+
+### Smart Contract Implementation
+
+The `AttestationDisputeGame` should implement the `IDisputeGame` interface and also be able to call
+out to the `L2OutputOracle`. It is expected that the `L2OutputOracle` will grant permissions to
+`AttestationDisputeGame` contracts to call its `deleteL2Outputs` function at the *specific* `l2BlockNumber`
+that is embedded in the `AttestationDisputeGame`'s `extraData`.
+
+The `AttestationDisputeGame` should be configured with a quorum ratio at deploy time. It should also
+maintain a set of attestor accounts, which is fetched by the `SystemConfig` contract and snapshotted
+at deploy time. This snapshot is necessary to have a fixed upper bound on resolution cost, which in
+turn gives a fix cost for the necessary bond attached to output proposals.
+
+The ability to add and remove attestor accounts should be enabled by a single immutable
+account that controls the `SystemConfig`. It should be impossible to remove accounts such that quorum
+is not able to be reached. It is ok to allow accounts to be added or removed in the middle of an
+open challenge, as it will not affect the `signerSet` that exists within open challenges.
+
+A challenge is created when an alternative output root for a given `l2BlockNumber` is presented to the
+`DisputeGameFactory` contract. Multiple challenges should be able to run in parallel.
+
+For simplicity, the `AttestationDisputeGame` does not need to track what output proposals are
+committed to as part of the attestations. It only needs to check that the attested output root
+is different than the proposed output root. If this is not checked, then it will be possible
+to remove output proposals that are in agreement with the attestations and create a griefing vector.
+
+#### Attestation Structure
+
+The EIP-712 [typeHash](https://eips.ethereum.org/EIPS/eip-712#rationale-for-typehash) should be
+defined as the following:
+
+```solidity
+TYPE_HASH = keccak256("Dispute(bytes32 outputRoot,uint256 l2BlockNumber)");
+```
+
+The components for the `typeHash` are as follows:
+
+- `outputRoot` - The **correct** output root that commits to the given `l2BlockNumber`. This should be a
+  positive attestation where the `rootClaim` of the `AttestationDisputeGame` is the **correct** output root
+  for the given `l2BlockNumber`.
+- `l2BlockNumber` - The L2 block number that the `outputRoot` commits to. The `outputRoot` should commit
+  to the entirety of the L2 state from genesis up to and including this `l2BlockNumber`.
+
+### Why EIP-712
+
+It is important to use EIP-712 to decouple the originator of the transaction and the attestor. This
+will allow a decentralized network of attestors that serve attestations to bots that are responsible
+for ensuring that all output proposals submitted to the network will not allow for malicious withdrawals
+from the bridge.
+
+It is important to have replay protection to ensure that attestations cannot be used more than once.