Merge pull request #6226 from ethereum-optimism/clabby/ctb/fault-game-invariants

chore(docs): `FaultDisputeGame`

packages/contracts-bedrock/.gas-snapshot

@@ -32,12 +32,12 @@ DisputeGameFactory_SetImplementation_Test:test_setImplementation_notOwner_revert
 DisputeGameFactory_SetImplementation_Test:test_setImplementation_succeeds() (gas: 44243)
 DisputeGameFactory_TransferOwnership_Test:test_transferOwnership_notOwner_reverts() (gas: 15950)
 DisputeGameFactory_TransferOwnership_Test:test_transferOwnership_succeeds() (gas: 18642)
-FaultDisputeGame_ResolvesCorrectly_CorrectRoot2:test_resolvesCorrectly_succeeds() (gas: 502174)
-FaultDisputeGame_ResolvesCorrectly_CorrectRoot3:test_resolvesCorrectly_succeeds() (gas: 504053)
-FaultDisputeGame_ResolvesCorrectly_CorrectRoot:test_resolvesCorrectly_succeeds() (gas: 491517)
-FaultDisputeGame_ResolvesCorrectly_IncorrectRoot2:test_resolvesCorrectly_succeeds() (gas: 500937)
-FaultDisputeGame_ResolvesCorrectly_IncorrectRoot3:test_resolvesCorrectly_succeeds() (gas: 502816)
-FaultDisputeGame_ResolvesCorrectly_IncorrectRoot:test_resolvesCorrectly_succeeds() (gas: 490280)
+FaultDisputeGame_ResolvesCorrectly_CorrectRoot2:test_resolvesCorrectly_succeeds() (gas: 502169)
+FaultDisputeGame_ResolvesCorrectly_CorrectRoot3:test_resolvesCorrectly_succeeds() (gas: 504048)
+FaultDisputeGame_ResolvesCorrectly_CorrectRoot:test_resolvesCorrectly_succeeds() (gas: 491512)
+FaultDisputeGame_ResolvesCorrectly_IncorrectRoot2:test_resolvesCorrectly_succeeds() (gas: 500932)
+FaultDisputeGame_ResolvesCorrectly_IncorrectRoot3:test_resolvesCorrectly_succeeds() (gas: 502811)
+FaultDisputeGame_ResolvesCorrectly_IncorrectRoot:test_resolvesCorrectly_succeeds() (gas: 490275)
 FaultDisputeGame_Test:test_extraData_succeeds() (gas: 17426)
 FaultDisputeGame_Test:test_gameData_succeeds() (gas: 17917)
 FaultDisputeGame_Test:test_gameStart_succeeds() (gas: 10315)
@@ -51,12 +51,12 @@ FaultDisputeGame_Test:test_move_gameDepthExceeded_reverts() (gas: 408100)
 FaultDisputeGame_Test:test_move_gameNotInProgress_reverts() (gas: 10968)
 FaultDisputeGame_Test:test_move_nonExistentParent_reverts() (gas: 24655)
 FaultDisputeGame_Test:test_move_simpleAttack_succeeds() (gas: 107344)
-FaultDisputeGame_Test:test_resolve_challengeContested_succeeds() (gas: 224789)
+FaultDisputeGame_Test:test_resolve_challengeContested_succeeds() (gas: 224784)
 FaultDisputeGame_Test:test_resolve_notInProgress_reverts() (gas: 9657)
-FaultDisputeGame_Test:test_resolve_rootContested_succeeds() (gas: 109754)
+FaultDisputeGame_Test:test_resolve_rootContested_succeeds() (gas: 109749)
 FaultDisputeGame_Test:test_resolve_rootUncontestedClockNotExpired_succeeds() (gas: 21422)
-FaultDisputeGame_Test:test_resolve_rootUncontested_succeeds() (gas: 27256)
-FaultDisputeGame_Test:test_resolve_teamDeathmatch_succeeds() (gas: 395447)
+FaultDisputeGame_Test:test_resolve_rootUncontested_succeeds() (gas: 27251)
+FaultDisputeGame_Test:test_resolve_teamDeathmatch_succeeds() (gas: 395442)
 FaultDisputeGame_Test:test_rootClaim_succeeds() (gas: 8181)
 FeeVault_Test:test_constructor_succeeds() (gas: 18185)
 GasBenchMark_L1CrossDomainMessenger:test_sendMessage_benchmark_0() (gas: 352113)

packages/contracts-bedrock/contracts/dispute/interfaces/IFaultDisputeGame.sol

@@ -20,19 +20,19 @@ interface IFaultDisputeGame is IDisputeGame {
 
     /// @notice Emitted when a new claim is added to the DAG by `claimant`
     /// @param parentIndex The index within the `claimData` array of the parent claim
-    /// @param pivot The claim being added
+    /// @param claim The claim being added
     /// @param claimant The address of the claimant
-    event Move(uint256 indexed parentIndex, Claim indexed pivot, address indexed claimant);
+    event Move(uint256 indexed parentIndex, Claim indexed claim, address indexed claimant);
 
     /// @notice Attack a disagreed upon `Claim`.
     /// @param _parentIndex Index of the `Claim` to attack in `claimData`.
-    /// @param _pivot The `Claim` at the relative attack position.
-    function attack(uint256 _parentIndex, Claim _pivot) external payable;
+    /// @param _claim The `Claim` at the relative attack position.
+    function attack(uint256 _parentIndex, Claim _claim) external payable;
 
     /// @notice Defend an agreed upon `Claim`.
     /// @param _parentIndex Index of the claim to defend in `claimData`.
-    /// @param _pivot The `Claim` at the relative defense position.
-    function defend(uint256 _parentIndex, Claim _pivot) external payable;
+    /// @param _claim The `Claim` at the relative defense position.
+    function defend(uint256 _parentIndex, Claim _claim) external payable;
 
     /// @notice Perform the final step via an on-chain fault proof processor
     /// @dev This function should point to a fault proof processor in order to execute
@@ -42,7 +42,10 @@ interface IFaultDisputeGame is IDisputeGame {
     /// @param _stateIndex The index of the pre/post state of the step within `claimData`.
     /// @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 @ `prestateIndex`
+    /// @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 leaf nodes in the VM.
     function step(
         uint256 _stateIndex,