op-zk-proposer for a chain whose DisputeGameFactory has the ZK dispute game (game type 10) registered. The proposer creates a game for the chain’s super root on a fixed interval, proves challenged games, resolves games, and claims bonds.
If you are moving an existing chain to ZK proofs, follow Migrating to ZK proofs, which tells you when to start the proposer. For how the proposer fits into the system, read ZK proof system components.
Before you start
You need:- The chain’s
DisputeGameFactoryaddress, or its network name if the chain is in the superchain-registry. - A super root source serving
superroot_atTimestamp: anop-supernodefor an interop set, or the chain’sop-nodewith its safe head database (--safedb.path) enabled for a chain on its own. You can configure several for redundancy. - An L1 execution node that supports JSON-RPC batch requests, and an L1 beacon node that serves blob sidecars for the range the proposer proves.
- An L2 execution node for each chain in the super root. Each must serve a different chain.
- An L1 transaction signer, as a private key or a Web3Signer-compatible remote signer such as op-signer, funded with enough ETH for init bonds and gas. Each game locks one init bond until it resolves and its bond is claimed, so the balance must cover every game in flight.
- A Succinct Prover Network account with a PROVE balance, unless you prove on local GPUs. Proofs are paid for from this account, which is separate from the L1 signer. See Fund the prover network account.
- A URL serving the prestate’s program files,
<vkey>.agg.bin.gz,<vkey>.range.bin.gz, and<vkey>.log.bin.gz, for every prestate that games on the chain use. See Verifying a ZK absolute prestate.
This guide uses the Succinct Prover Network. The proposer can also generate proofs on local NVIDIA GPUs; see Prove on local GPUs.
Plan memory and disk
The proposer collects the data that each proof reads before it requests the proof. It holds each request’s encoded input in memory until the request is uploaded, so plan memory for about twiceOP_ZK_PROPOSER_MAX_STDIN_BYTES (1.5 GiB by default) for each chunk it proves at once. It proves up to OP_ZK_PROPOSER_MAX_CONCURRENT_DEFENSE_TASKS games at once (default 8), and up to OP_ZK_PROPOSER_MAX_CONCURRENT_RANGE_PROOFS chunks of each game at once (default 1). With the defaults, that is 8 chunks, or about 24 GiB. With fast finality on, add up to OP_ZK_PROPOSER_FAST_FINALITY_PROVING_LIMIT more games.
Set OP_ZK_PROPOSER_DATA_DIR to keep the collected data on disk instead of in memory. The encoded request inputs stay in memory. The directory need not persist across restarts, but it must belong to one proposer process, because the proposer deletes the leftover collections in it at startup. Under attack, a proof can need much more data than usual, so alert on the volume’s usage.
Configure the proposer
The proposer is configured with environment variables, all prefixedOP_ZK_PROPOSER_. A minimal configuration for a chain in the superchain-registry:
OP_ZK_PROPOSER_NETWORK with OP_ZK_PROPOSER_FACTORY_ADDRESS, and set OP_ZK_PROPOSER_ROLLUP_CONFIG_PATHS, OP_ZK_PROPOSER_L1_CONFIG_PATH, and OP_ZK_PROPOSER_DEPENDENCY_SET_PATH to the chain’s configuration files. The chain also needs a prestate built with the same configuration; see Build a prestate for a custom chain.
In production, keep keys out of the environment:
- For the L1 signer, use
OP_ZK_PROPOSER_SIGNER_URLandOP_ZK_PROPOSER_SIGNER_ADDRESS. To use mTLS, also setOP_ZK_PROPOSER_SIGNER_TLS_CA,OP_ZK_PROPOSER_SIGNER_TLS_CERT, andOP_ZK_PROPOSER_SIGNER_TLS_KEY. - For the prover network requester, use
OP_ZK_PROPOSER_SPN_SIGNER_URLandOP_ZK_PROPOSER_SPN_SIGNER_ADDRESS. This signer requires an HTTPS URL and mTLS, so also setOP_ZK_PROPOSER_SPN_SIGNER_TLS_CA,OP_ZK_PROPOSER_SPN_SIGNER_TLS_CERT, andOP_ZK_PROPOSER_SPN_SIGNER_TLS_KEY.
OP_ZK_PROPOSER_PROPOSAL_INTERVAL_SECONDS: seconds between proposals (default3600). A longer interval means fewer games and bonds, and more blocks to prove per challenged game.OP_ZK_PROPOSER_PROPOSAL_SAFETY: proposefinalized(default) orsafeL2 state. A proposal of state that later changes is invalid and loses its bond, so keep the default unless you have a reason to change it.OP_ZK_PROPOSER_RANGE_SPLIT_COUNT: how many chunks a challenged game’s range is split into (default16, at most128). More chunks make each proof request smaller, at the cost of more requests.OP_ZK_PROPOSER_MAX_CONCURRENT_DEFENSE_TASKS: how many challenged games it proves at once (default8).
Fund the prover network account
WithOP_ZK_PROPOSER_PROOF_PROVIDER=network, the proposer pays for proofs from its prover network requester’s PROVE balance. Find the requester’s address in the address label of the op_zk_proposer_spn_requester_info metric once the proposer is running.
When the requester is a key in a remote signer that can only sign prover network requests, it cannot deposit for itself. Fund it from another account with the spn-wallet tool in the monorepo:
--broadcast, spn-wallet prints what it would send and signs nothing. PROVE is always on Ethereum mainnet, even for chains that settle on Sepolia. See the spn-wallet documentation for depositing from L1 and signing with a KMS key.
Keep the balance well above the cost of defending several games at once. A challenged game that cannot be proven because the balance ran out loses its bond.
Prove on local GPUs
WithOP_ZK_PROPOSER_PROOF_PROVIDER=local-cuda, the proposer generates proofs on local NVIDIA GPUs instead of buying them from the Succinct Prover Network. It needs no prover network account, so it can serve as a backup during a prover network outage. The prestate and verifier checks are the same as in network mode.
This mode runs only in the op-zk-proposer-cuda image, which is built for amd64 and includes the GPU prover server. The image is published as us-docker.pkg.dev/oplabs-tools-artifacts/images/op-zk-proposer-cuda:vX.Y.Z, from the same commit as the op-zk-proposer release vX.Y.Z. Set OP_ZK_PROPOSER_CUDA_DEVICES to the comma-separated IDs of the GPUs to use (default 0). See Local CUDA proving in the SP1 integration README for the memory settings and how the proposer runs each request.
In this mode, the proposer does not export prove_balance or spn_requester_info.
Start the proposer
Run the container image with your configuration. The image runs as user10001, so that user must be able to write to the directory mounted at /data. For a new named volume, set its owner once before the first run:
op-zk-proposer/vX.Y.Z release tag publishes the image tag vX.Y.Z. Use a release that supports the kona-sp1-program release your chain’s prestate comes from. The two releases are normally tagged on the same commit.
Look for op-zk-proposer started in the logs. Before it proposes, the proposer runs these checks:
- Anchor state. At startup, it waits until the anchor state in the
AnchorStateRegistrymatches the super root that its super root source reports for the anchor’s timestamp. If they differ, it logs an error and keeps retrying, and continues once they match, without a restart. - Prestate. Before it creates a game on a prestate, it loads that prestate’s program files and checks that their verification key matches it.
- Verifier. On every creation cycle, it checks that the verifier registered for the game accepts proofs from the PLONK circuit of its SP1 SDK. If it does not, it logs an error with the expected and actual verifier hashes, and pauses creating games. It keeps defending games whose verifier matches.
Verify the proposer
Within one proposal interval, check that it created a game:Monitor the proposer
The proposer exports Prometheus metrics prefixedop_zk_proposer_. Alert on at least these:
Also alert on Prometheus failing to scrape the proposer. See the complete metric list for diagnostic metrics such as
game_proving_error and span_bisections.
Run op-dispute-mon as well, to watch every game on the chain independently of the proposer.
Retry failed proof requests
Some proof requests fail in ways the proposer does not retry by itself, for example when the prover network reports that a request cannot be executed. The proposer marks these terminal. To retry them without a restart, which would lose all proving progress, send the processSIGUSR1:
Processed terminal proof retry lists the games it reset.
Enable fast finality
WithOP_ZK_PROPOSER_FAST_FINALITY_MODE=true, the proposer proves every game its signer creates as soon as it is created, instead of only challenged ones. A proven game resolves as soon as its parent resolves, instead of waiting out its challenge window. See Fast finality.
This buys a full set of proofs for every game: range, consolidation, and aggregation proofs, plus any log-commitment proofs. At a one-hour interval, that is about 24 games a day. OP_ZK_PROPOSER_FAST_FINALITY_PROVING_LIMIT (default 1) caps the proving tasks in flight; while the cap is reached, the proposer pauses creating games. Alert on deadline_passed_total{window="fast_finality"} to see games that were not proven in time. A missed fast-finality window does not lose the game.
Keep old prestates available
The proposer can only defend, resolve, and claim games whose prestate program files it can load. When you change the chain’s prestate, keep the old files atOP_ZK_PROPOSER_PRESTATES_URL for as long as games created under the old prestate can still be live. Alert when op_zk_proposer_unknown_prestate_challenged increases: the proposer skipped a challenged game because it cannot load or validate the game’s prestate.
Next steps
- Set up op-challenger for ZK dispute games.
- Read ZK proofs security for why proving in time matters.