Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

feat: FaultDisputeGame changes for incident response improvements #524

Prev Previous commit
Next Next commit
expand FDG, bond incentives
wildmolasses committed Jan 28, 2025
commit 3a99b9feee25f09cfb75691c165a22cb423853e2
78 changes: 58 additions & 20 deletions specs/fault-proof/stage-one/bond-incentives.md
Original file line number Diff line number Diff line change
@@ -4,20 +4,27 @@
<!-- DON'T EDIT THIS SECTION, INSTEAD RE-RUN doctoc TO UPDATE -->
**Table of Contents**

- [Overview](#overview)
- [Moves](#moves)
- [Subgame Resolution](#subgame-resolution)
- [Leftmost Claim Incentives](#leftmost-claim-incentives)
- [Fault Proof Mainnet Incentives](#fault-proof-mainnet-incentives)
- [Authenticated Roles](#authenticated-roles)
- [Base Fee Assumption](#base-fee-assumption)
- [Bond Scaling](#bond-scaling)
- [Required Bond Formula](#required-bond-formula)
- [Other Incentives](#other-incentives)
- [DelayedWETH](#delayedweth)
- [Sub-Account Model](#sub-account-model)
- [Delay Period](#delay-period)
- [Integration](#integration)
- [Bond Incentives](#bond-incentives)
- [Overview](#overview)
- [Moves](#moves)
- [Subgame Resolution](#subgame-resolution)
- [Leftmost Claim Incentives](#leftmost-claim-incentives)
- [Fault Proof Mainnet Incentives](#fault-proof-mainnet-incentives)
- [Authenticated Roles](#authenticated-roles)
- [Base Fee Assumption](#base-fee-assumption)
- [Bond Scaling](#bond-scaling)
- [Required Bond Formula](#required-bond-formula)
- [Other Incentives](#other-incentives)
- [Game Finalization](#game-finalization)
- [Bond Distribution Mode](#bond-distribution-mode)
- [Normal Mode](#normal-mode)
- [Refund Mode](#refund-mode)
- [Game Closure](#game-closure)
- [Claiming Credit](#claiming-credit)
- [DelayedWETH](#delayedweth)
- [Sub-Account Model](#sub-account-model)
- [Delay Period](#delay-period)
- [Integration](#integration)

<!-- END doctoc generated TOC please keep comment here to allow auto update -->

@@ -125,9 +132,40 @@ opportunity cost of locking up capital in the dispute game. While we do not expl
these costs, we assume that the current bond rewards, based on this specification, are enough as a whole to cover
all other costs of participation.

## Game Finalization

After the game is resolved, claimants must wait for the [AnchorStateRegistry's `isGameFinalized()`](anchor-state-registry.md#isgamefinalized) to return `true` before they can claim their bonds. This implies a wait period of at least the `disputeGameFinalityDelaySeconds` variable from the `OptimismPortal` contract. After the game is finalized, bonds can be distributed.

### Bond Distribution Mode

The FDG will in most cases distribute bonds to the winners of the game after it is resolved and finalized, but in special cases will refund the bonds to the original depositor.

#### Normal Mode

In normal mode, the FDG will distribute bonds to the winners of the game after it is resolved and finalized.

#### Refund Mode

In refund mode, the FDG will refund the bonds to the original depositor.

### Game Closure

The `FaultDisputeGame` contract can be closed after finalization via the `closeGame()` function, or if the game is not yet closed, can be closed via `claimCredit`.

`closeGame` must do the following:

1. Verify the game is resolved and finalized according to the Anchor State Registry
2. Attempt to set this game as the new anchor game .
3. Determine the bond distribution mode based on whether the [AnchorStateRegistry's `isGameProper()`](anchor-state-registry.md#isgameproper) returns `true`.
4. Emit a `GameClosed` event with the chosen distribution mode.

### Claiming Credit

After the game is closed and the bond distribution mode is determined, there is a 2-step process to claim credit. First, `claimCredit(address claimant)` should be called to unlock the credit from the [DelayedWETH](#delayedweth) contract. After DelayedWETH's [delay period](#delay-period) has passed, `claimCredit` should be called again to withdraw the credit.

### DelayedWETH

FPM introduces a contract `DelayedWETH` designed to hold the bonded ETH for each
`DelayedWETH` is designed to hold the bonded ETH for each
[Fault Dispute Game](fault-dispute-game.md).
`DelayedWETH` is an extended version of the standard `WETH` contract that introduces a delayed unwrap mechanism that
allows an owner address to function as a backstop in the case that a Fault Dispute Game would
@@ -174,8 +212,8 @@ over multiple timezones.

- When `FaultDisputeGame.initialize` is triggered, `DelayedWETH.deposit{value: msg.value}()` is called.
- When `FaultDisputeGame.move` is triggered, `DelayedWETH.deposit{value: msg.value}()` is called.
- When `FaultDisputeGame.resolveClaim` is triggered, `DelayedWETH.unlock(recipient, bond)` is called.
- When `FaultDisputeGame.claimCredit` is triggered, `DelayedWETH.withdraw(recipient, claim)` is called.
- When `FaultDisputeGame.resolveClaim` is triggered, the game will add to the claimant's internal credit balance.
- When `FaultDisputeGame.claimCredit` is triggered, `DelayedWETH.withdraw(recipient, credit)` is called.

```mermaid
sequenceDiagram
@@ -195,13 +233,13 @@ sequenceDiagram

loop resolveClaim by Users
U->>FDG: resolveClaim()
FDG->>DW: unlock(recipient, bond)
Note over DW: Starts timer for recipient
FDG->>FDG: Add to claimant credit
end

loop claimCredit by Users
U->>FDG: claimCredit()
FDG->>DW: withdraw(recipient, claim)
FDG->>DW: unlock(recipient, bond)
FDG->>DW: withdraw(recipient, credit)
Note over DW: Checks timer/amount for recipient
DW->>FDG: Transfer claim to FDG
FDG->>U: Transfer claim to User
72 changes: 32 additions & 40 deletions specs/fault-proof/stage-one/fault-dispute-game.md
Original file line number Diff line number Diff line change
@@ -2,37 +2,39 @@

<!-- 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)
- [PreimageOracle](#preimageoracle)
- [Execution Trace](#execution-trace)
- [Claims](#claims)
- [Anchor State](#anchor-state)
- [Anchor State Registry](#anchor-state-registry)
- [DAG](#dag)
- [Subgame](#subgame)
- [Game Tree](#game-tree)
- [Position](#position)
- [MAX_CLOCK_DURATION](#max_clock_duration)
- [CLOCK_EXTENSION](#clock_extension)
- [Freeloader Claims](#freeloader-claims)
- [Core Game Mechanics](#core-game-mechanics)
- [Actors](#actors)
- [Moves](#moves)
- [Attack](#attack)
- [Defend](#defend)
- [L2 Block Number Challenge](#l2-block-number-challenge)
- [Step](#step)
- [Step Types](#step-types)
- [PreimageOracle Interaction](#preimageoracle-interaction)
- [Team Dynamics](#team-dynamics)
- [Game Clock](#game-clock)
- [Resolution](#resolution)
- [Resolving the L2 Block Number Challenge](#resolving-the-l2-block-number-challenge)
- [Finalization](#finalization)
- [Fault Dispute Game](#fault-dispute-game)
- [Overview](#overview)
- [Definitions](#definitions)
- [Virtual Machine (VM)](#virtual-machine-vm)
- [PreimageOracle](#preimageoracle)
- [Execution Trace](#execution-trace)
- [Claims](#claims)
- [Anchor State](#anchor-state)
- [Anchor State Registry](#anchor-state-registry)
- [DAG](#dag)
- [Subgame](#subgame)
- [Game Tree](#game-tree)
- [Position](#position)
- [MAX_CLOCK_DURATION](#max_clock_duration)
- [CLOCK_EXTENSION](#clock_extension)
- [Freeloader Claims](#freeloader-claims)
- [Core Game Mechanics](#core-game-mechanics)
- [Actors](#actors)
- [Moves](#moves)
- [Attack](#attack)
- [Defend](#defend)
- [L2 Block Number Challenge](#l2-block-number-challenge)
- [Step](#step)
- [Step Types](#step-types)
- [PreimageOracle Interaction](#preimageoracle-interaction)
- [Team Dynamics](#team-dynamics)
- [Game Clock](#game-clock)
- [Resolution](#resolution)
- [Resolving the L2 Block Number Challenge](#resolving-the-l2-block-number-challenge)
- [Finalization](#finalization)

<!-- END doctoc generated TOC please keep comment here to allow auto update -->

@@ -552,14 +554,4 @@ Thus, no moves against the root, including uncontested ones, can win a root subg

### Finalization

Once the game is resolved, if the claim is shown to be valid, the FDG reports its state to the
Anchor State Registry. The Anchor State Registry verifies that the request to update an anchor
state comes from a FDG contract created by the Dispute Game Factory contract, confirms that the
game resolved in favor of the defender, and confirms that the updated state would be newer than
the current anchor state (based on the result of `FaultDisputeGame.l2BlockNumber()`). If these
conditions are true, the Anchor State Registry updates the anchor state for the given game type.

Note that the dependency of the Anchor State Registry on the `l2BlockNumber()` function means that
the registry may not be applicable to dispute game types that do not have a similar sense of
progressing state over time. Currently, the Anchor State Registry is therefore assumed to be
specific to the Fault Dispute Game contract and not to other dispute game types.
Once the game is resolved, it must wait for the `disputeGameFinalityDelaySeconds` on the `OptimismPortal` to pass before it can be finalized, after which bonds can be distributed via the process outlined in [Bond Incentives: Game Finalization](bond-incentives.md#game-finalization).