feat: implement proposer (#349)

* feat(fault_proof): implement proposer

* fix: fix deploy script to set reward/bond in wei

* docs: add quick start guide

* cleanup

* fix

Cargo.toml

@@ -1,11 +1,11 @@
 [workspace]
-members = ["utils/*", "programs/*", "scripts/*", "proposer/succinct"]
+members = ["utils/*", "programs/*", "scripts/*", "proposer/succinct", "fault_proof"]
 resolver = "2"
 
 [workspace.package]
 license = "MIT"
 edition = "2021"
-authors = ["ratankaliani", "zachobront"]
+authors = ["ratankaliani", "zachobront", "fakedev9999"]
 homepage = "https://succinctlabs.github.io/op-succinct/"
 repository = "https://github.com/succinctlabs/op-succinct"
 
@@ -62,6 +62,7 @@ op-succinct-build-utils = { path = "utils/build" }
 op-succinct-proposer = { path = "proposer/succinct" }
 
 # Alloy (Network)
+alloy-network = { version = "0.11.0", default-features = false }
 alloy-signer-local = { version = "0.11.0", default-features = false }
 alloy-provider = { version = "0.11.0", default-features = false }
 alloy-transport = { version = "0.11.0", default-features = false }
@@ -85,6 +86,7 @@ alloy-primitives = { version = "0.8.19", default-features = false, features = [
     "sha3-keccak",
 ] }
 alloy-sol-types = { version = "0.8.19", default-features = false }
+alloy-sol-macro = { version = "0.8.19", default-features = false }
 
 # OP Alloy
 op-alloy-consensus = { version = "0.10.0", default-features = false }

book/SUMMARY.md

@@ -23,6 +23,9 @@
   - [Update Contract Parameters](./contracts/update-parameters.md)
   - [Modifications to Original `L2OutputOracle`](./contracts/modifications.md)
 - [Fault Proofs](./fault_proofs/fault_proof_architecture.md)
+  - [Quick Start](./fault_proofs/quick_start.md)
+  - [Deploy FP Contracts](./fault_proofs/deploy.md)
+  - [How to run the FP Proposer](./fault_proofs/proposer.md)
 - [Experimental](./experimental/intro.md)
   - [OptimismPortalV2](./experimental/optimism-portal-v2.md)
 - [FAQ](./faq.md)

book/fault_proofs/deploy.md

@@ -0,0 +1,124 @@
+# Deploying OP Succinct Fault Dispute Game
+
+This guide explains how to deploy the OP Succinct Fault Dispute Game contracts using the `DeployOPSuccinctFDG.s.sol` script.
+
+## Overview
+
+The deployment script performs the following actions:
+1. Deploys the `DisputeGameFactory` implementation and proxy.
+2. Deploys the `AnchorStateRegistry` implementation and proxy.
+3. Deploys a mock `OptimismPortal2` for testing.
+4. Deploys the `AccessManager` and configures it for permissionless games.
+5. Deploys either a mock SP1 verifier for testing or uses a provided verifier address.
+6. Deploys the `OPSuccinctFaultDisputeGame` implementation.
+7. Configures the factory with initial bond and game implementation.
+
+## Prerequisites
+
+- [Foundry](https://book.getfoundry.sh/getting-started/installation) installed.
+- Access to an Ethereum node (local or network).
+- Environment variables properly configured.
+
+## Configuration
+
+Create a `.env` file in the contracts directory with the following variables:
+
+### Required Environment Variables
+
+| Variable | Description | Example |
+|----------|-------------|---------|
+| `GAME_TYPE` | Unique identifier for the game type (uint32). | `42` |
+| `DISPUTE_GAME_FINALITY_DELAY_SECONDS` | Delay before finalizing dispute games. | `604800` for 7 days |
+| `MAX_CHALLENGE_DURATION` | Maximum duration for challenges in seconds. | `604800` for 7 days |
+| `MAX_PROVE_DURATION` | Maximum duration for proving in seconds. | `86400` for 1 day |
+
+### SP1 Verifier Configuration
+For testing, set:
+```bash
+USE_SP1_MOCK_VERIFIER=true
+```
+
+For production, set all of these:
+| Variable | Description | Example |
+|----------|-------------|---------|
+| `VERIFIER_ADDRESS` | Address of the SP1 verifier ([see contract addresses](https://docs.succinct.xyz/docs/sp1/verification/onchain/contract-addresses)) | `0x...` |
+| `ROLLUP_CONFIG_HASH` | Hash of the rollup configuration | `0x...` |
+| `AGGREGATION_VKEY` | Verification key for aggregation | `0x...` |
+| `RANGE_VKEY_COMMITMENT` | Commitment to range verification key | `0x...` |
+
+## Deployment
+
+1. Install dependencies:
+   ```bash
+   forge install
+   ```
+
+2. Change directory to contracts:
+   ```bash
+   cd contracts
+   ```
+
+3. Build the contracts:
+   ```bash
+   forge build
+   ```
+
+4. Run the deployment script:
+   ```bash
+   forge script script/fp/DeployOPSuccinctFDG.s.sol --broadcast --rpc-url <RPC_URL> --private-key <PRIVATE_KEY>
+   ```
+
+## Contract Parameters
+
+The deployment script deploys the contract with the following parameters:
+
+- **Initial Bond**: 0.01 ETH by default (configurable via `INITIAL_BOND` in wei, so 10000000000000000 wei for 0.01 ETH).
+- **Proof Reward**: 0.01 ETH by default (configurable via `PROOF_REWARD` in wei, so 10000000000000000 wei for 0.01 ETH).
+- **Starting Anchor Root**: Genesis configuration with block number 0.
+- **Access Control**: Permissionless (address(0) can propose and challenge).
+
+## Post-Deployment
+
+After deployment, the script will output the addresses of:
+- Factory Proxy.
+- Game Implementation.
+- SP1 Verifier.
+- Portal2.
+- Anchor State Registry.
+- Access Manager.
+
+Save these addresses for future reference and configuration of other components.
+
+## Security Considerations
+
+- The deployer address will be set as the factory owner.
+- Initial parameters are set for testing - adjust for production.
+- The mock SP1 verifier (`USE_SP1_MOCK_VERIFIER=true`) should ONLY be used for testing.
+- For production deployments:
+  - Provide a valid `VERIFIER_ADDRESS`.
+  - Configure proper `ROLLUP_CONFIG_HASH`, `AGGREGATION_VKEY`, and `RANGE_VKEY_COMMITMENT`.
+  - Review and adjust finality delay and duration parameters.
+  - Consider access control settings.
+
+## Troubleshooting
+
+Common issues and solutions:
+
+1. **Compilation Errors**:
+   - Ensure Foundry is up to date (run `foundryup`).
+   - Run `forge clean && forge build`.
+
+2. **Deployment Failures**:
+   - Check RPC connection.
+   - Verify sufficient ETH balance.
+   - Confirm environment variables are set correctly.
+
+## Next Steps
+
+After deployment:
+
+1. Update the proposer configuration with the factory address.
+2. Configure the challenger with the game parameters.
+3. Test the deployment with a sample game.
+4. Monitor initial games for correct behavior.
+5. For production: Replace mock OptimismPortal2 with the real implementation.

book/fault_proofs/proposer.md

@@ -0,0 +1,157 @@
+# Fault Proof Proposer
+
+The fault proof proposer is a component responsible for creating and managing OP-Succinct fault dispute games on the L1 chain. It continuously monitors the L2 chain and creates new dispute games at regular intervals to ensure the validity of L2 state transitions.
+
+## Prerequisites
+
+Before running the proposer, ensure you have:
+
+1. Rust toolchain installed (latest stable version)
+2. Access to L1 and L2 network nodes
+3. The DisputeGameFactory contract deployed (See [Deploy](./deploy.md))
+4. Sufficient ETH balance for:
+   - Transaction fees
+   - Game bonds (configurable in the factory)
+5. Required environment variables properly configured (see [Configuration](#configuration))
+
+## Overview
+
+The proposer performs several key functions:
+
+1. **Game Creation**: Creates new dispute games for L2 blocks at configurable intervals
+2. **Game Resolution**: Optionally resolves unchallenged games after their deadline passes
+3. **Chain Monitoring**: Continuously monitors the L2 chain's safe head and creates proposals accordingly
+4. **Fast Finality Mode**: Optionally enables fast finality by including proofs with proposals
+
+## Configuration
+
+The proposer is configured through various environment variables. Create a `.env.proposer` file in the fault_proof directory:
+
+### Required Environment Variables
+
+| Variable | Description |
+|----------|-------------|
+| `L1_RPC` | L1 RPC endpoint URL |
+| `L2_RPC` | L2 RPC endpoint URL |
+| `FACTORY_ADDRESS` | Address of the DisputeGameFactory contract |
+| `GAME_TYPE` | Type identifier for the dispute game |
+| `PRIVATE_KEY` | Private key for transaction signing |
+
+### Optional Environment Variables
+
+| Variable | Description | Default Value |
+|----------|-------------|---------------|
+| `PROPOSAL_INTERVAL_IN_BLOCKS` | Number of L2 blocks between proposals | `1800` |
+| `FETCH_INTERVAL` | Polling interval in seconds | `30` |
+| `ENABLE_GAME_RESOLUTION` | Whether to enable automatic game resolution | `true` |
+| `MAX_GAMES_TO_CHECK_FOR_RESOLUTION` | Maximum number of games to check for resolution | `100` |
+
+```env
+# Required Configuration
+L1_RPC=                  # L1 RPC endpoint URL
+L2_RPC=                  # L2 RPC endpoint URL
+FACTORY_ADDRESS=         # Address of the DisputeGameFactory contract (obtained from deployment)
+GAME_TYPE=               # Type identifier for the dispute game (must match factory configuration)
+PRIVATE_KEY=             # Private key for transaction signing
+
+# Optional Configuration
+PROPOSAL_INTERVAL_IN_BLOCKS=1800    # Number of L2 blocks between proposals
+FETCH_INTERVAL=30                   # Polling interval in seconds
+ENABLE_GAME_RESOLUTION=false        # Whether to enable automatic game resolution
+MAX_GAMES_TO_CHECK_FOR_RESOLUTION=100  # Maximum number of games to check for resolution
+```
+
+### Configuration Steps
+
+1. Deploy the DisputeGameFactory contract following the [deployment guide](./deploy.md)
+2. Copy the factory address from the deployment output
+3. Create `.env` file with the above configuration
+4. Ensure your account has sufficient ETH for bonds and gas
+
+## Running
+
+To run the proposer:
+   ```bash
+   cargo run --bin proposer
+   ```
+
+The proposer will run indefinitely, creating new games and optionally resolving them based on the configuration.
+
+## Features
+
+### Game Creation
+- Creates new dispute games at configurable block intervals.
+- Computes L2 output roots for game proposals.
+- Ensures proper game sequencing with parent-child relationships.
+- Handles bond requirements for game creation.
+- Supports fast finality mode with proofs.
+
+### Game Resolution
+When enabled (`ENABLE_GAME_RESOLUTION=true`), the proposer:
+- Monitors unchallenged games
+- Resolves games after their challenge period expires
+- Respects parent-child game relationships in resolution
+- Only resolves games whose parent games are already resolved
+
+### Chain Monitoring
+- Monitors the L2 chain's finalized (safe) head
+- Creates proposals for new blocks as they become available
+- Maintains proper spacing between proposals based on configuration
+- Tracks the latest valid proposal for proper sequencing
+
+## Logging
+
+The proposer uses the `tracing` crate for logging with a default level of INFO. You can adjust the log level by setting the `RUST_LOG` environment variable:
+
+```bash
+RUST_LOG=debug cargo run --bin proposer
+```
+
+## Error Handling
+
+The proposer includes robust error handling for:
+- RPC connection issues
+- Transaction failures
+- Contract interaction errors
+- Invalid configurations
+
+Errors are logged with appropriate context to aid in debugging.
+
+## Architecture
+
+The proposer is built around the `OPSuccinctProposer` struct which manages:
+- Configuration state.
+- Wallet management for transactions.
+- Game creation and resolution logic.
+- Chain monitoring and interval management.
+
+Key components:
+- `ProposerConfig`: Handles environment-based configuration.
+- `handle_game_creation`: Main function for proposing new games that:
+  - Monitors the L2 chain's safe head.
+  - Determines appropriate block numbers for proposals.
+  - Creates new games with proper parent-child relationships.
+- `handle_game_resolution`: Main function for resolving games that:
+  - Checks if resolution is enabled.
+  - Manages resolution of unchallenged games.
+  - Respects parent-child relationships.
+- `run`: Main loop that:
+  - Runs at configurable intervals.
+  - Handles both game creation and resolution.
+  - Provides error isolation between creation and resolution tasks.
+
+### Helper Functions
+- `create_game`: Creates individual games with proper bonding.
+- `try_resolve_unchallenged_game`: Attempts to resolve a single game.
+- `should_attempt_resolution`: Determines if games can be resolved based on parent status.
+- `resolve_unchallenged_games`: Manages batch resolution of games.
+
+## Development
+
+When developing or modifying the proposer:
+1. Ensure all environment variables are properly set.
+2. Test with a local L1/L2 setup first.
+3. Monitor logs for proper operation.
+4. Test game creation and resolution separately.
+5. Verify proper handling of edge cases (network issues, invalid responses, etc.).
+6. Test both normal and fast finality modes.