@@ -172,18 +172,18 @@ rotation, old-signer games stay eligible for defense, resolution, and claims,
172172but the restart scan does not fast-finalize them.
173173
174174** Operational requirement** : rotated-out prestate artifacts must remain published
175- under ` PRESTATES_URL ` for as long as games created under them can be live, or the
175+ under ` KONA_SP1_PROPOSER_PRESTATES_URL ` for as long as games created under them can be live, or the
176176proposer loses the ability to defend, resolve, and claim those games.
177177
178178### Proof providers
179179
180- - ` PROOF_PROVIDER =network` : real SP1 proving via the Succinct Prover Network.
180+ - ` KONA_SP1_PROPOSER_PROOF_PROVIDER =network` : real SP1 proving via the Succinct Prover Network.
181181 Proving keys are set up per prestate on first use, and the aggregation
182182 verifying key must hash to the on-chain prestate (mismatches poison the
183183 prestate and remove its games from the owned set). The registered prestate's
184184 keys are verified BEFORE any game is created on it, so the proposer never
185185 bonds a game it has not proven it can defend.
186- - ` PROOF_PROVIDER =mock` : dev-only. Runs the full pipeline natively (witness
186+ - ` KONA_SP1_PROPOSER_PROOF_PROVIDER =mock` : dev-only. Runs the full pipeline natively (witness
187187 collection computes the real range/consolidation outputs and the aggregation
188188 inputs are validated), then submits placeholder proof bytes. Only a deployment
189189 with a mock game verifier (devstack) accepts them. No ELFs, no SPN credentials.
@@ -212,41 +212,84 @@ slot (blocking a later defense of that game): watch
212212
213213### Environment
214214
215- Required:
215+ All proposer-owned variables use the ` KONA_SP1_PROPOSER_ ` prefix.
216+
217+ Required core configuration:
218+
219+ | Variable | Purpose |
220+ | ---| ---|
221+ | ` KONA_SP1_PROPOSER_L1_RPC ` | L1 execution RPC |
222+ | ` KONA_SP1_PROPOSER_SUPERROOT_RPC ` | op-supernode or single-chain op-node RPC serving ` superroot_atTimestamp ` |
223+ | ` KONA_SP1_PROPOSER_FACTORY_ADDRESS ` | ` DisputeGameFactory ` address |
224+ | ` KONA_SP1_PROPOSER_PRESTATES_URL ` | prestate artifact directory (` <vkey>.agg.bin.gz ` + ` <vkey>.range.bin.gz ` ) |
225+ | ` KONA_SP1_PROPOSER_PROOF_PROVIDER ` | ` network ` or ` mock ` ; no default |
226+ | ` KONA_SP1_PROPOSER_L1_BEACON_RPC ` | L1 beacon API (blob sidecars for derivation witnesses) |
227+ | ` KONA_SP1_PROPOSER_L2_RPCS ` | comma-separated L2 EL RPCs, one per chain (order-irrelevant) |
228+
229+ Optional core and operational configuration:
230+
231+ | Variable | Purpose |
232+ | ---| ---|
233+ | ` KONA_SP1_PROPOSER_ROLLUP_CONFIG_PATHS ` | comma-separated rollup config files; absent = registry fallback |
234+ | ` KONA_SP1_PROPOSER_L1_CONFIG_PATH ` | L1 chain config file; absent = registry fallback |
235+ | ` KONA_SP1_PROPOSER_DEPENDENCY_SET_PATH ` | dependency-set config file; absent = registry fallback |
236+ | ` KONA_SP1_PROPOSER_PROPOSAL_INTERVAL_SECONDS ` | proposal interval (default ` 3600 ` ) |
237+ | ` KONA_SP1_PROPOSER_PROPOSAL_SAFETY ` | ` safe ` or ` finalized ` (default ` finalized ` ) |
238+ | ` KONA_SP1_PROPOSER_FETCH_INTERVAL ` | loop interval in seconds (default ` 30 ` ) |
239+ | ` KONA_SP1_PROPOSER_METRICS_PORT ` | ` 0 ` disables metrics; ` auto ` selects a free port (default ` 0 ` ) |
240+ | ` KONA_SP1_PROPOSER_SYNC_L1_CONFIRMATIONS ` | L1 confirmation lag for pinned reads (default ` 0 ` ) |
241+ | ` KONA_SP1_PROPOSER_TX_CONFIRMATION_TIMEOUT ` | transaction confirmation timeout in seconds (default ` 60 ` ) |
242+ | ` KONA_SP1_PROPOSER_MAX_FEE_PER_GAS ` | L1 max-fee cap in wei (default uncapped) |
243+ | ` KONA_SP1_PROPOSER_MAX_PRIORITY_FEE_PER_GAS ` | L1 priority-fee cap in wei (default uncapped) |
244+ | ` KONA_SP1_PROPOSER_RANGE_SPLIT_COUNT ` | chunks per defended span (default ` 1 ` , maximum ` 16 ` ) |
245+ | ` KONA_SP1_PROPOSER_MAX_CONCURRENT_RANGE_PROOFS ` | child-proof concurrency per game (default ` 1 ` ) |
246+ | ` KONA_SP1_PROPOSER_MAX_CONCURRENT_DEFENSE_TASKS ` | concurrent defended games (default ` 8 ` , minimum ` 1 ` ) |
247+ | ` KONA_SP1_PROPOSER_FAST_FINALITY_MODE ` | prove signer-created owned games while unchallenged (default ` false ` ) |
248+ | ` KONA_SP1_PROPOSER_FAST_FINALITY_PROVING_LIMIT ` | total in-flight proving tasks before creation pauses (default ` 1 ` ) |
249+
250+ SP1 network configuration applies when ` KONA_SP1_PROPOSER_PROOF_PROVIDER=network ` :
251+
252+ | Variable | Purpose |
253+ | ---| ---|
254+ | ` KONA_SP1_PROPOSER_NETWORK_PRIVATE_KEY ` | SPN requester private key, or AWS KMS key ARN when KMS is enabled |
255+ | ` KONA_SP1_PROPOSER_NETWORK_RPC_URL ` | SPN RPC override; absent or empty uses the SP1 SDK default for the selected network mode |
256+ | ` KONA_SP1_PROPOSER_USE_KMS_REQUESTER ` | use AWS KMS for request signing (default ` false ` ) |
257+ | ` KONA_SP1_PROPOSER_RANGE_PROOF_STRATEGY ` | range fulfillment strategy (default ` reserved ` ) |
258+ | ` KONA_SP1_PROPOSER_AGG_PROOF_STRATEGY ` | aggregation fulfillment strategy (default ` reserved ` ) |
259+ | ` KONA_SP1_PROPOSER_SP1_TIMEOUT_SECONDS ` | overall proof timeout (default ` 14400 ` ) |
260+ | ` KONA_SP1_PROPOSER_NETWORK_CALLS_TIMEOUT ` | individual network-call timeout (default ` 15 ` ) |
261+ | ` KONA_SP1_PROPOSER_AUCTION_TIMEOUT ` | unassigned mainnet request timeout (default ` 60 ` ) |
262+ | ` KONA_SP1_PROPOSER_RANGE_CYCLE_LIMIT ` | range request cycle limit (default ` 1e12 ` ) |
263+ | ` KONA_SP1_PROPOSER_RANGE_GAS_LIMIT ` | range request gas limit (default ` 1e12 ` ) |
264+ | ` KONA_SP1_PROPOSER_AGG_CYCLE_LIMIT ` | aggregation request cycle limit (default ` 1e12 ` ) |
265+ | ` KONA_SP1_PROPOSER_AGG_GAS_LIMIT ` | aggregation request gas limit (default ` 1e12 ` ) |
266+ | ` KONA_SP1_PROPOSER_MAX_PRICE_PER_PGU ` | maximum price per proving gas unit (default ` 3e8 ` ) |
267+ | ` KONA_SP1_PROPOSER_MIN_AUCTION_PERIOD ` | minimum auction period in seconds (default ` 1 ` ) |
268+
269+ Transaction signing requires one of these configurations:
216270
217271| Variable | Purpose |
218272| ---| ---|
219- | ` L1_RPC ` | L1 execution RPC |
220- | ` SUPERROOT_RPC ` | op-supernode or single-chain op-node RPC serving ` superroot_atTimestamp ` |
221- | ` FACTORY_ADDRESS ` | ` DisputeGameFactory ` address |
222- | ` PRESTATES_URL ` | prestate artifact directory (` <vkey>.agg.bin.gz ` + ` <vkey>.range.bin.gz ` ) |
223- | ` PROOF_PROVIDER ` | ` network ` or ` mock ` ; no default |
224- | ` L1_BEACON_RPC ` | L1 beacon API (blob sidecars for derivation witnesses) |
225- | ` L2_RPCS ` | comma-separated L2 EL RPCs, one per chain (order-irrelevant) |
226- | ` PRIVATE_KEY ` or ` SIGNER_URL ` +` SIGNER_ADDRESS ` | L1 transaction signer |
273+ | ` KONA_SP1_PROPOSER_PRIVATE_KEY ` | local L1 transaction-signing key |
274+ | ` KONA_SP1_PROPOSER_SIGNER_URL ` | Web3Signer URL; requires ` KONA_SP1_PROPOSER_SIGNER_ADDRESS ` |
275+ | ` KONA_SP1_PROPOSER_SIGNER_ADDRESS ` | Web3Signer address; requires ` KONA_SP1_PROPOSER_SIGNER_URL ` |
227276
228- Optional (defaults in parentheses) :
277+ Logging and telemetry :
229278
230279| Variable | Purpose |
231280| ---| ---|
232- | ` ROLLUP_CONFIG_PATHS ` , ` L1_CONFIG_PATH ` , ` DEPENDENCY_SET_PATH ` | chain config files; absent = superchain-registry fallback, matching the executor CLI |
233- | ` PROPOSAL_INTERVAL_SECONDS ` (3600), ` PROPOSAL_SAFETY ` (finalized), ` FETCH_INTERVAL ` (30) | proposal cadence |
234- | ` METRICS_PORT ` (0 = disabled, ` auto ` = a free port reported on the startup line), ` SYNC_L1_CONFIRMATIONS ` (0), ` TX_CONFIRMATION_TIMEOUT ` (60) | operations |
235- | ` MAX_FEE_PER_GAS ` , ` MAX_PRIORITY_FEE_PER_GAS ` | L1 fee caps in wei (unset = uncapped) |
236- | ` RANGE_SPLIT_COUNT ` (1, max 16) | chunks a defended span is split into |
237- | ` MAX_CONCURRENT_RANGE_PROOFS ` (1) | child-proof concurrency within one game |
238- | ` MAX_CONCURRENT_DEFENSE_TASKS ` (8) | games defended concurrently (must be >= 1) |
239- | ` FAST_FINALITY_MODE ` (false) | prove signer-created owned games while unchallenged |
240- | ` FAST_FINALITY_PROVING_LIMIT ` (1) | total in-flight proving tasks (defense included) before creation pauses |
241- | ` NETWORK_PRIVATE_KEY ` (network mode; ` USE_KMS_REQUESTER ` for AWS KMS) | SPN requester key |
242- | ` RANGE_PROOF_STRATEGY ` , ` AGG_PROOF_STRATEGY ` (reserved) | SPN fulfillment strategies |
243- | ` SP1_TIMEOUT_SECONDS ` (14400), ` NETWORK_CALLS_TIMEOUT ` (15), ` AUCTION_TIMEOUT ` (60) | SPN timeouts |
244- | ` RANGE_CYCLE_LIMIT ` , ` RANGE_GAS_LIMIT ` , ` AGG_CYCLE_LIMIT ` , ` AGG_GAS_LIMIT ` (1e12) | SPN request limits |
245- | ` MAX_PRICE_PER_PGU ` (3e8), ` MIN_AUCTION_PERIOD ` (1) | SPN pricing |
281+ | ` KONA_SP1_PROPOSER_LOGGER_NAME ` | OpenTelemetry service name (default ` kona-sp1 ` ) |
282+ | ` KONA_SP1_PROPOSER_OTLP_ENDPOINT ` | OpenTelemetry endpoint (default ` http://localhost:4317 ` ) |
283+ | ` KONA_SP1_PROPOSER_OTLP_ENABLED ` | enable OpenTelemetry export (default ` false ` ) |
284+ | ` KONA_SP1_PROPOSER_LOG_FORMAT ` | ` pretty ` or ` json ` (default ` pretty ` ) |
285+
286+ The proposer and its dependencies also observe the standard ` RUST_LOG ` , ` NO_COLOR ` ,
287+ ` SSL_CERT_DIR ` , ` SSL_CERT_FILE ` , ` OTEL_* ` , proxy, AWS credential, and SP1 worker/debug
288+ variables. ` KONA_SP1_ELF_DIR ` configures shared build/test infrastructure.
246289
247290### Fast finality
248291
249- With ` FAST_FINALITY_MODE =true` the proposer proves every signer-created owned
292+ With ` KONA_SP1_PROPOSER_FAST_FINALITY_MODE =true` the proposer proves every signer-created owned
250293game while it is still unchallenged, spawned by the per-tick scan one fetch
251294interval after creation. A proven game is over immediately, so it resolves as
252295soon as its parent does instead of waiting out ` maxChallengeDuration ` : proof
@@ -256,7 +299,7 @@ Off by default.
256299Spend framing: in network mode this proves every game created by this signer
257300whose prestate artifacts are available. At a one-hour proposal interval that is
258301a baseline of 24 aggregation proofs per day; the default
259- ` FAST_FINALITY_PROVING_LIMIT =1` serializes them. An unchallenged game created by
302+ ` KONA_SP1_PROPOSER_FAST_FINALITY_PROVING_LIMIT =1` serializes them. An unchallenged game created by
260303another proposer is not proven, even when it uses a known prestate. Enabling the
261304mode on a chain with an existing unchallenged backlog proves the signer-created
262305owned backlog.
@@ -267,7 +310,7 @@ Concurrency interaction:
267310| ---| ---|
268311| active proving tasks (defense + fast finality) >= limit | no new fast-finality proving; game creation paused this tick |
269312| defense tasks alone >= limit | same: defense load pauses creation (upstream parity) |
270- | fast-finality tasks in flight | never count against ` MAX_CONCURRENT_DEFENSE_TASKS ` |
313+ | fast-finality tasks in flight | never count against ` KONA_SP1_PROPOSER_MAX_CONCURRENT_DEFENSE_TASKS ` |
271314| game challenged while a fast-finality proof is in flight | the proof stays valid; per-game dedup prevents a second task |
272315| a fast-finality proof keeps failing at the limit | creation stays paused until it succeeds or is classified unprovable; watch ` kona_sp1_proposer_game_proving_error ` |
273316## Building
0 commit comments