Skip to content

Commit 44a65a0

Browse files
Kourin1996Farhad-Shabani
Kourin1996
and
Farhad-Shabani
committed
feat: add preflight check script for fp (succinctlabs#669)
* feat: add preflight check script for fp * docs: update and fix * chore: cleanup * chore: default to .env.preflight * chore: apply comments * docs: add note about altda feature flags * feat: introduce SET_IMPL_BLOCK env var * refactor: make AGG_PROOF_MODE configurable * chore: make USE_KMS_REQUESTER optional * docs: make l1 beacon rpc required * configurable CHUNK_SIZE * fix: effective strategy * fix * cleanup * docs * docs --------- Co-authored-by: Farhad Shabani <Farhad.Shabani@gmail.com>
1 parent 7d7f17c commit 44a65a0

File tree

8 files changed

+941
-436
lines changed

8 files changed

+941
-436
lines changed

‎Cargo.lock‎

Lines changed: 411 additions & 422 deletions
Some generated files are not rendered by default. Learn more about customizing how changed files appear on GitHub.

‎book/SUMMARY.md‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -36,6 +36,7 @@
3636
- [Resources](./fault_proofs/resources.md)
3737
- [Gas Costs](./fault_proofs/gas_costs.md)
3838
- [Testing Guide](./fault_proofs/testing.md)
39+
- [Pre-Flight Validation](./fault_proofs/preflight.md)
3940
- [Best Practices](./fault_proofs/best_practices.md)
4041
- [Experimental Features](./fault_proofs/experimental/experimental.md)
4142
- [Celestia DA](./fault_proofs/experimental/celestia.md)

‎book/fault_proofs/preflight.md‎

Lines changed: 119 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,119 @@
1+
# Pre-Flight Validation
2+
3+
**Proving will break if parameters are incorrect.** After deploying contracts, run this script to verify the contract configuration before the mainnet upgrade.
4+
5+
## What Does Pre-Flight Validate?
6+
7+
Catches configuration issues before production by testing the complete proof generation and submission pipeline end-to-end. The game creation and proof submission is simulated on a forked L1 network.
8+
9+
## Prerequisites
10+
11+
- Deployed `DisputeGameFactory` contract
12+
- L1/L2 RPC access
13+
- SP1 network prover access
14+
15+
## Required Environment Variables
16+
17+
Create a `.env.preflight` file in the **repository root** with the following variables.
18+
19+
> **Note:** Using `.env.preflight` avoids conflicts with existing `.env` files from deployments or other operations. You can specify a different file with `--env-file` if needed.
20+
21+
### Contract Configuration
22+
```bash
23+
# Address of the DisputeGameFactory contract on L1
24+
FACTORY_ADDRESS=
25+
26+
# Game type identifier for OPSuccinctFaultDisputeGames
27+
# This must match the game type registered in the factory
28+
GAME_TYPE=42
29+
30+
# Optional: block number where DisputeGameFactory.setImplementation was called.
31+
# Set when you want to bypass on-chain log discovery (e.g., restrictive RPC rate limits).
32+
# SET_IMPL_BLOCK=<L1_BLOCK_NUMBER>
33+
```
34+
35+
### Signing Configuration
36+
```bash
37+
# L1 private key used to create and prove the dispute game on the forked Anvil chain
38+
# This must be a whitelisted address in the OPSuccinctFaultDisputeGame contract
39+
PRIVATE_KEY=0x...
40+
```
41+
42+
### Network Configuration
43+
```bash
44+
# L1 RPC endpoint (used for Anvil fork during validation)
45+
L1_RPC=<YOUR_L1_RPC>
46+
47+
# L1 beacon chain RPC endpoint (needed when validating blocks with blob/EIP-4844 data)
48+
L1_BEACON_RPC=<YOUR_L1_BEACON_RPC>
49+
50+
# L2 RPC endpoint
51+
L2_RPC=<YOUR_L2_RPC>
52+
53+
# L2 node RPC endpoint (often same as L2_RPC)
54+
L2_NODE_RPC=<YOUR_L2_NODE_RPC>
55+
```
56+
57+
### Prover Configuration
58+
```bash
59+
# Range proof fulfillment strategy
60+
# Options: "reserved", "hosted", "auction"
61+
# - reserved: Use SP1 Network Reserved mode (requires reserved capacity)
62+
# - hosted: Use SP1 Network Hosted mode (managed by SP1)
63+
# - auction: Use SP1 Network Auction mode (open competitive bidding)
64+
RANGE_PROOF_STRATEGY=auction
65+
66+
# Aggregation proof fulfillment strategy
67+
# Options: "reserved", "hosted", "auction"
68+
# Compatibility rules:
69+
# - If RANGE_PROOF_STRATEGY is "auction", this must also be "auction"
70+
# - If RANGE_PROOF_STRATEGY is "reserved" or "hosted", this can be either "reserved" or "hosted"
71+
AGG_PROOF_STRATEGY=auction
72+
73+
# Optional: aggregation proof mode ("plonk" default or "groth16")
74+
# Note: Changing the proof mode requires the corresponding SP1 verifier contract
75+
# address to be set in your deployment.
76+
# AGG_PROOF_MODE=plonk
77+
78+
# Set to 'true' to use AWS KMS for key management (requires KMS configuration).
79+
# Set to 'false' to use a local private key (requires NETWORK_PRIVATE_KEY below).
80+
# Optional; defaults to 'false' if omitted.
81+
# USE_KMS_REQUESTER=false
82+
83+
# SP1 network prover private key (required when USE_KMS_REQUESTER=false)
84+
# When USE_KMS_REQUESTER=true, this should be an AWS KMS key ARN instead
85+
NETWORK_PRIVATE_KEY=0x...
86+
```
87+
88+
## Running Pre-Flight Validation
89+
90+
Run the preflight script from the **repository root**:
91+
92+
```bash
93+
RUST_LOG=info cargo run --release --bin preflight
94+
```
95+
96+
```admonish note
97+
For rollups using alternative DA layers, compile with the matching feature flag:
98+
`--features celestia` or `--features eigenda` (for example,
99+
`RUST_LOG=info cargo run --release --features eigenda --bin preflight`).
100+
```
101+
102+
By default, this uses `.env.preflight`. To use a different environment file:
103+
104+
```bash
105+
RUST_LOG=info cargo run --release --bin preflight -- --env-file .env.custom
106+
```
107+
108+
The script will:
109+
1. Fetch the anchor L2 block number from the factory
110+
2. Generate a range proof for the game
111+
3. Generate an aggregation proof for the game
112+
4. Fork L1 at a finalized block using Anvil
113+
5. Create a game at 10 blocks after the anchor
114+
6. Prove the game with the aggregation proof
115+
7. Verify the game has been validated with the aggregation proof
116+
117+
Generated proofs are saved to:
118+
- `data/{CHAIN_ID}/proofs/range/{L2_START_BLOCK}-{L2_END_BLOCK}.bin`
119+
- `data/{CHAIN_ID}/proofs/agg/agg.bin`

‎book/introduction.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -13,7 +13,7 @@ It combines a few key technologies:
1313
- [SP1](https://docs.succinct.xyz/docs/sp1/introduction), Succinct's state-of-the-art Rust zkVM
1414
- [Succinct Prover Network](https://docs.succinct.xyz/docs/sp1/prover-network/intro), Succinct's low-latency, cost-effective proving API
1515

16-
OP Succinct is the only production-ready proving solution for the OP Stack and trusted by teams like [Mantle](https://www.mantle.xyz/blog/announcements/op-succinct-mantle-network-testnet) and [Phala](https://phala.network/posts/phala-network-20-first-opsuccinct-layer-2-on-ethereum).
16+
OP Succinct is the only production-ready proving solution for the OP Stack and trusted by teams like [Mantle](https://www.mantle.xyz/blog/announcements/op-succinct-mantle-network-testnet) and [Phala](https://phala.com/).
1717

1818

1919
## Proving Options

‎fault-proof/src/contract.rs‎

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -12,6 +12,9 @@ sol! {
1212
/// @notice Emitted when a new dispute game is created.
1313
event DisputeGameCreated(address indexed disputeProxy, GameType indexed gameType, Claim indexed rootClaim);
1414

15+
/// @notice Emitted when a new game implementation added to the factory
16+
event ImplementationSet(address indexed impl, GameType indexed gameType);
17+
1518
/// @notice `gameImpls` is a mapping that maps `GameType`s to their respective
1619
/// `IDisputeGame` implementations.
1720
mapping(GameType => IDisputeGame) public gameImpls;

‎scripts/prove/Cargo.toml‎

Lines changed: 12 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -33,9 +33,21 @@ op-succinct-client-utils.workspace = true
3333
op-succinct-proof-utils.workspace = true
3434
op-succinct-scripts = { path = "../utils" }
3535
op-succinct-elfs.workspace = true
36+
op-succinct-fp.workspace = true
3637

3738
# alloy
39+
alloy-contract.workspace = true
40+
alloy-eips.workspace = true
41+
alloy-network.workspace = true
42+
alloy-node-bindings.workspace = true
3843
alloy-primitives.workspace = true
44+
alloy-signer-local.workspace = true
45+
alloy-sol-types.workspace = true
46+
alloy-provider = { workspace = true, features = ["reqwest"] }
47+
alloy-transport-http = { workspace = true, features = [
48+
"reqwest",
49+
"reqwest-native-tls",
50+
] }
3951

4052
# sp1
4153
sp1-sdk.workspace = true

‎scripts/utils/Cargo.toml‎

Lines changed: 17 additions & 13 deletions
Original file line numberDiff line numberDiff line change
@@ -39,18 +39,24 @@ path = "bin/fetch_fault_dispute_game_config.rs"
3939
name = "gen-sp1-test-artifacts"
4040
path = "bin/gen_sp1_test_artifacts.rs"
4141

42-
[[bin]]
43-
name = "game-monitor"
44-
path = "bin/game_monitor.rs"
45-
46-
4742
[[bin]]
4843
name = "parallel-cost-estimator"
4944
path = "bin/parallel_cost_estimator.rs"
5045

46+
[[bin]]
47+
name = "preflight"
48+
path = "bin/preflight.rs"
49+
5150
[dependencies]
5251

5352
# workspace
53+
alloy-network.workspace = true
54+
alloy-node-bindings.workspace = true
55+
alloy-provider = { workspace = true, features = ["reqwest"] }
56+
alloy-transport-http = { workspace = true, features = [
57+
"reqwest",
58+
"reqwest-native-tls",
59+
] }
5460
alloy-primitives.workspace = true
5561
alloy-sol-types.workspace = true
5662
alloy-signer-local.workspace = true
@@ -65,22 +71,20 @@ log.workspace = true
6571
csv.workspace = true
6672
serde.workspace = true
6773
futures.workspace = true
74+
rayon = "1.10.0"
6875
serde_json.workspace = true
76+
env_logger = "0.11"
77+
tracing.workspace = true
78+
79+
# local
6980
op-succinct-host-utils.workspace = true
7081
op-succinct-client-utils.workspace = true
7182
op-succinct-proof-utils.workspace = true
7283
op-succinct-elfs.workspace = true
7384
op-succinct-fp.workspace = true
74-
alloy-provider.workspace = true
75-
sp1-sdk.workspace = true
76-
rayon = "1.10.0"
77-
env_logger = "0.11"
78-
79-
# local
80-
81-
# alloy
8285

8386
# sp1
87+
sp1-sdk.workspace = true
8488

8589
rustls = "0.23.23"
8690

0 commit comments

Comments
 (0)