specs: Update dispute game interfaces

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,41 +189,52 @@ 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);
+    /// @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_);
 }
 
 ////////////////////////////////////////////////////////////////