Circuit and proof reference
Source: circuits/zk_sniper/ (Noir) · Verifier project: contracts/verifiers/ ·
Proof system: UltraHonk (Barretenberg), zero-knowledge evm flavour (bb -t evm), deployed
with one linked library.
No verifier or game built from this circuit is deployed anywhere. Treat the numbers on this page (sizes, hashes) as the state of the committed artifacts at the time of writing; the build script prints the current values every time it runs.
What the circuit proves
For a committed square (hider_x, hider_y) with salt hider_salt, and a sniper guess, the
circuit proves two things at once:
- The prover knows the opening of the public commitment:
Poseidon(hider_x, hider_y, hider_salt) == hider_position_hash. - The result bit is correct:
is_hit = (hider_x == sniper_guess_x) and (hider_y == sniper_guess_y).
Nothing about (hider_x, hider_y, hider_salt) is revealed beyond that bit.
fn main(
hider_x: u32, hider_y: u32, hider_salt: Field, // private
hider_position_hash: pub Field, sniper_guess_x: pub u32, sniper_guess_y: pub u32,
) -> pub bool {
assert(hider_x < GRID); assert(hider_y < GRID); // GRID = 8
assert(sniper_guess_x < GRID); assert(sniper_guess_y < GRID);
let h = hash_3([hider_x as Field, hider_y as Field, hider_salt]); // Poseidon, BN254
assert(h == hider_position_hash);
(hider_x == sniper_guess_x) & (hider_y == sniper_guess_y)
}
Why the on-grid assertions matter
If the circuit allowed hider_x = 9, a hider could commit to a square that does not exist and then
prove a miss for every guess on the board, forever, while the pool grows. The assertions make
such a commitment unprovable: there is then no valid proof at all for any shot, and the first
shot ends in a timeout in the sniper's favour. The same check rejects an off-grid guess.
Public inputs
The order is the same everywhere and must never change:
| Index | Circuit name | In Solidity | Notes |
|---|---|---|---|
| 0 | hider_position_hash | bytes32(positionHash) | Stored in the round at createRound |
| 1 | sniper_guess_x | bytes32(uint256(x)) | The pending shot's column |
| 2 | sniper_guess_y | bytes32(uint256(y)) | The pending shot's row |
| 3 | is_hit | bytes32(uint256(isHit ? 1 : 0)) | The circuit's return value, appended last |
Each value is a 32-byte big-endian field element. ZkSniper.publicInputsFor(roundId, x, y, isHit)
returns exactly this array for the pending shot at (x, y) (it reverts with NoPendingShot unless
that square is pending), and it is what answerShot passes to the verifier. bb.js returns the
same four values in proof.publicInputs.
The generated verifier declares NUMBER_OF_PUBLIC_INPUTS = 12. That is the 4 application inputs
above plus 8 elements of Barretenberg's pairing-point object, which live inside the proof. Callers
(and the game contract) pass only the 4 application inputs, and the verifier rejects any other
length.
Proof system
| Item | Value |
|---|---|
| Scheme | UltraHonk, zero-knowledge flavour (bb -t evm). The commitments to the witness polynomials are blinded and every proof is randomized |
| Circuit size | 4,096 gates (2^12), 12 public inputs including the pairing-point object |
| Proof size | 7,232 bytes (226 field elements). Proofs are randomized: two proofs of the same statement differ |
| Verifier runtime size | 24,244 bytes, which is 332 bytes under the 24,576 B EIP-170 limit |
| Linked library | ZKTranscriptLib, 6,108 bytes. The verifier calls it, so it must be deployed first and its address written into the verifier's creation code |
| Verification gas | About 2.35 million gas for a direct verify transaction (about 2.2M of it execution; 7,492 bytes of calldata and the 21,000 base cost are included). Deploying the library and the verifier together costs roughly 8.7M gas |
| Failure behaviour | An invalid proof reverts (it never returns false). The game maps every revert to InvalidProof |
The verifier is compiled in its own Foundry project (contracts/verifiers/, solc 0.8.27,
evm_version = cancun, via_ir = false, optimizer_runs = 1). The main contracts project never
compiles it: tests and deploy scripts load the committed forge artifacts
contracts/test/artifacts/ZkSniperVerifier.json and ZkSniperTranscriptLib.json and link them
(see below). The optimizer setting is a documented constant because the margin is thin (see the table).
| Build | Verifier runtime | Margin to EIP-170 |
|---|---|---|
evm (ZK), runs = 1 or 20 (shipped: 1) | 24,244 B | 332 B |
evm (ZK), runs = 100 | 24,304 B | 272 B |
evm (ZK), runs = 200 | 25,174 B | over the limit |
evm (ZK), via_ir = true | does not compile ("stack too deep") | n/a |
bb has no --optimized verifier for the ZK flavour, so there is no smaller variant to fall back
on.
build.sh asserts the optimizer setting, prints both runtime sizes and fails if either exceeds
the limit, so a toolchain bump that breaks the margin is caught at build time.
Why the zero-knowledge flavour is mandatory
An earlier version of this repository shipped the cheaper non-ZK flavour (evm-no-zk, 14,455 B,
6,368 B proofs) and described it as "not formally zero-knowledge, but no practical recovery known".
That claim was wrong. An adversarial review found a recovery of the hider's square from public
data, and two independent reviewers reproduced it. These docs describe the mechanism; they do not
re-derive it.
- A non-ZK proof is deterministic (the same witness gives the same bytes) and the commitments to the witness polynomials are not blinded.
- Such a commitment is linear in the witness. Two answered shots at different squares are proofs
over the same private witness
(x, y, salt). The salt-dependent part of the Poseidon computation is identical in both, so subtracting the commitments of the two proofs cancels it. What remains depends only on public values and on the hidden(x, y), so an observer can test the 64 candidate squares offline, without knowing the salt. - Every answered shot publishes its proof in calldata. After two answered misses anybody can recover the square, with no help from the hider, and a sniper who knows it wins with one more shot.
The salt is a 254-bit secret and the position only 6 bits, which is why the old claim sounded plausible: the attack never touches the salt. The ZK flavour blinds the commitments and randomizes the proof, so two proofs of the same hidden square share no usable structure. It costs a linked library, a thin size margin and roughly four times the verification gas of the old build. That is the price of the game being private at all.
Consequences, all enforced in the repository:
- The browser, SDK and responder must pass
{ verifierTarget: 'evm' }to bothgenerateProofandverifyProofof@aztec/bb.js(the SDK exportsSNIPER_VERIFIER_TARGET). A proof made with theevm-no-zktarget is a different format, is rejected on-chain, and must never be produced for a real position. build.shno longer offersevm-no-zkand refuses a leftoverVERIFIER_TARGET=evm-no-zk.- A non-ZK verifier rejects the committed 7,232-byte ZK fixtures, so the deploy-time fixture check fails for it; the bytecode drift check is the second line of defence.
What the ZK flavour does not change: each answered miss still tells everybody that square is not the hider's (that is the game), and the responder operator still learns the square from the hit proof it holds. The generated verifier and Barretenberg have had no external audit.
Gas, simulation and the gas cap
A tampered proof can burn every unit of gas it is given. Most corruptions revert in under 0.5M
gas, but a corrupted curve point reaches a bn254 precompile (ecAdd, ecMul, ecPairing), and a
failing precompile consumes all the gas forwarded to it. In a scan that flipped one bit in each
of the 226 proof words, 4 words consumed the whole 30M gas cap of the call. The contract treats a
verifier that runs out of gas like any other failure and reports InvalidProof.
So anything that submits answerShot (browser, SDK, relayer) must send with an explicit gas
limit of a few million, never an open-ended one, and must not send a proof it has not checked.
The SDK exports SNIPER_ANSWER_GAS_LIMIT (3.5M) and simulateSniperAnswer for a wallet that sends
a proof it has not verified. The responder and the browser session key instead verify every proof once,
when it is built or loaded (an eth_call of the verifier under a gas ceiling, or verifyProof in the
browser), and then send the stored answer with a fixed 3M gas limit and no simulation at shot time:
the verifier is immutable in the game, so a proof that verified once verifies again, and skipping
the simulation is what makes answers arrive in seconds (Answer times). A measured
answer uses about 2.37M gas (a hit about 2.39M).
Version pins
Proofs only verify when every tool agrees. The pins:
| Component | Version |
|---|---|
nargo | 1.0.0-beta.20 |
bb (Barretenberg CLI) | 5.0.0-nightly.20260324 |
@noir-lang/noir_js | 1.0.0-beta.20 (exact; SDK optional peer dependency and web dependency) |
@aztec/bb.js | 5.0.0-nightly.20260324 (exact; must equal the bb CLI version) |
noir-lang/poseidon (Noir library) | tag v0.3.0 (Nargo.toml) |
poseidon-lite (JavaScript) | 0.3.0 (poseidon3 via the poseidon-lite/poseidon3 subpath) |
| Verifier compiler | solc 0.8.27, Cancun, via_ir = false, optimizer runs 1 |
build.sh fails when your nargo or bb differ from the pins (set ALLOW_TOOLCHAIN_DRIFT=1
for a throwaway build, which downgrades it to a warning; never commit its outputs). A different
version may produce a different verification key, and proofs made with one version are rejected by a
verifier built with another.
The pinned nargo accepts only a git tag for a dependency, so the Poseidon tag v0.3.0 cannot
be pinned by commit in Nargo.toml. The commit is pinned in circuits/zk_sniper/dependencies.pin.json
together with a hash of the dependency sources embedded in the circuit; build.sh fails if the
checkout is at another commit, and the artifact check fails if the committed circuit embeds other
sources. Rebuilding the verifier project also needs solc 0.8.27, which
scripts/setup-toolchain.sh installs next to 0.8.26.
Build pipeline
Run from the repository root:
cd circuits/zk_sniper
./build.sh # add --clean to delete build products first
It runs, in order (with -t evm):
nargo test && nargo compile
node scripts/gen-prover-inputs.mjs # poseidon-lite -> Prover.{hit,miss}.toml + fixtures/zk-sniper-vectors.json
nargo execute --prover-name Prover.hit.toml witness_hit
nargo execute --prover-name Prover.miss.toml witness_miss
bb write_vk -t evm -b target/zk_sniper.json -o target/
bb write_solidity_verifier -t evm -k target/vk -o <tmp>/ZkSniperVerifier.sol
bb prove -t evm -b target/zk_sniper.json -w target/witness_hit.gz -k target/vk -o target/proof_hit/
bb prove -t evm -b target/zk_sniper.json -w target/witness_miss.gz -k target/vk -o target/proof_miss/
bb verify -t evm -k target/vk -p target/proof_hit/proof -i target/proof_hit/public_inputs
bb verify -t evm -k target/vk -p target/proof_miss/proof -i target/proof_miss/public_inputs
node scripts/pack-fixtures.mjs # -> contracts/test/artifacts/zk-sniper-proof-{hit,miss}.json
(cd ../../contracts/verifiers && forge build --force --sizes)
Then it checks and copies:
- The generated verifier embeds the verification key hash (
vk_hash). The script refuses to continue if it does not, and writes a header (tool versions, target,vk_hash, input order) above the generated source. - Tamper checks. Six corrupted proofs or inputs must each be rejected by
bb verify: a flipped proof byte, a hit proof withis_hitflipped to 0, a wrong guess x, a wrong position hash, a miss proof against hit inputs, and a truncated proof. - The verifier must link exactly one library (
ZKTranscriptLib), and the library must link nothing. - The runtime sizes of the verifier and the library are compared with the EIP-170 limit; the script fails above it.
ZkSniperVerifier.jsonandZkSniperTranscriptLib.jsonare copied tocontracts/test/artifacts/and the compiled circuitzk_sniper.jsontoapps/web/public/circuits/for the browser prover. The verifier artifact keeps its library placeholder; it is linked at deploy time.
Committed outputs, so that scripts/preflight.sh never needs nargo or bb:
| File | What |
|---|---|
circuits/zk_sniper/target/{zk_sniper.json,vk,vk_hash} | Compiled circuit, verification key and its hash. The circuit JSON is sanitized by scripts/sanitize-circuit.mjs so that file_map holds no developer path (src/main.nr, deps/github.com/...); bytecode, abi, hash and the sources are untouched, so vk and vk_hash do not change |
circuits/zk_sniper/dependencies.pin.json | The Poseidon commit and the hash of the dependency sources the circuit must embed |
circuits/zk_sniper/fixtures/*.json | Hit and miss proof fixtures and the Poseidon vectors |
contracts/verifiers/ZkSniperVerifier.sol | Generated Solidity verifier |
contracts/test/artifacts/{ZkSniperVerifier,ZkSniperTranscriptLib,zk-sniper-proof-hit,zk-sniper-proof-miss}.json | Forge artifacts of the verifier and its library, and the proofs used by the Foundry tests and deploy scripts. The proof fixtures also carry the circuit's vkHash |
contracts/script/ZkSniperVerifierLinker.sol | The one helper that deploys the library and links the verifier |
apps/web/public/circuits/zk_sniper.json | Circuit loaded by the in-browser prover |
Proof bytes change every time the build is re-run (proofs are randomized, so the fixtures are
rewritten with new, equally valid proofs). The circuit, vk, vk_hash and the verifier are
deterministic.
Deploying the verifier
The verifier calls ZKTranscriptLib, so its creation code contains a library placeholder
(__$...$__) and vm.deployCode on the artifact fails. Every deployment goes through
ZkSniperVerifierLinker (contracts/script/ZkSniperVerifierLinker.sol), in forge tests and in
broadcast scripts alike:
- deploy the library from
ZkSniperTranscriptLib.json; - read
ZkSniperVerifier.json, check that its only placeholder is the one derived fromZkSniperVerifier.sol:ZKTranscriptLib(anything else reverts), write the library address over every occurrence, andCREATEthe result.
Both steps are plain CREATEs, so under vm.broadcast they become two transactions (library, then
verifier). The deploy scripts then check the committed hit and miss fixtures against the deployed
verifier before they deploy the game. The helper was exercised against a real anvil with
forge script --broadcast: the deployed verifier accepted the committed hit and miss proofs and
rejected the hit proof with is_hit flipped.
Regenerating and verifying the verifier
Regenerate whenever the circuit, nargo or bb changes. Never edit the generated file by hand.
-
Install the pinned tools (
noirup -v 1.0.0-beta.20,bbup -v 5.0.0-nightly.20260324). -
Run
circuits/zk_sniper/build.sh --cleanand read its output for warnings. -
Confirm the
vk_hash. It must appear identically intarget/vk_hash, in the header and theVK_HASHconstant ofcontracts/verifiers/ZkSniperVerifier.sol, and later in the deployment JSON (games.zkSniperVkHash). -
Run the contract suite from
contracts/:forge build --sizesforge test --match-path 'test/games/*'The fixture tests deploy the real verifier through the linker and check a real hit proof, a real miss proof, a tampered proof, a flipped result bit, a wrong guess and a full
answerShotround trip. A mock verifier is used only in narrow unit tests. The tests that expect a rejection cap the gas they supply. -
Re-run the TypeScript checks (
pnpm -C packages/sdk test). The prover test generates a real proof in Node and verifies it, and is skipped only if the circuit artifact is missing. -
A new verifier requires a new
ZkSniperdeployment: the verifier address is immutable in the game contract.
Three checks guard the committed inputs, and none of them is an audit:
scripts/check-sniper-artifacts.mjs(run byscripts/preflight.shandscripts/release-check.sh) requires the verifier's realuint256 constant VK_HASH(not only the header comment), the header, both proof fixtures and the verifier creation code to equaltarget/vk_hash; the web circuit to equaltarget/zk_sniper.json, hold no absolute path and embed the pinned Poseidon sources; the committed artifacts to equal a rebuild ofcontracts/verifiers(needssolc 0.8.27); and, with the pinnednargoandbbon the path, the circuit andvkto re-derive to the committed values.scripts/release-check.shtreatscontracts/verifiers,contracts/test/artifacts,circuits/zk_sniper,apps/web/public/circuitsandcontracts/scriptas guarded paths, likecontracts/src: unmerged or unpushed work touching them fails the release stamp.scripts/check-deployed-bytecode.mjscompares the deployed game, verifier and library with the build. Immutables are not blanket-masked: the game'sverifiermust equalgames.zkSniperVerifier; the verifier'sLOG_N,VK_HASH,NUM_PUBLIC_INPUTSand MSM-size values must equal whatZkSniperVerifier.solsays, andVK_HASHmust equaltarget/vk_hashandgames.zkSniperVkHash. Only the linked library address is masked: it must be one address at every link offset, equalgames.zkSniperVerifierLibrary, and its code must equal the committedZkSniperTranscriptLib.json.
The deploy scripts also check the committed hit and miss fixtures against the verifier before deploying anything, and never deploy a mock verifier.
Hash parity
Three implementations of the same hash must agree bit for bit:
| Where | Implementation |
|---|---|
| Circuit | poseidon::poseidon::bn254::hash_3 from noir-lang/poseidon v0.3.0 |
| SDK and web | poseidon3 from poseidon-lite 0.3.0 (circomlib parameters) |
| Test fixtures | Vectors generated by scripts/gen-prover-inputs.mjs with poseidon-lite |
The parity is pinned in three places:
- A Noir test asserts
hash_3([1, 2, 3])equals0x0e7732d89e6939c0ff03d5e58dab6302f3230e269dc5b968f725df34ab36d732, the circomlib value of Poseidon(1, 2, 3) (decimal6542985608222806190361240322586112750744169038454362455181422643027100751666). gen-prover-inputs.mjsasserts the same vector and writesfixtures/zk-sniper-vectors.json(seven{x, y, salt, hash}vectors including salts at the field boundary), which the SDK tests compare against.- A Noir test checks the commitment for
(x = 3, y = 5, salt = 123456789), which is also the committed hit and miss fixture.
A salt is reduced modulo the BN254 scalar field. The contract rejects a positionHash at or above
the field, because the verifier works on field elements.
The SDK imports Poseidon from the poseidon-lite/poseidon3 subpath on purpose. The web app
aliases the bare poseidon-lite specifier to a smaller shim, and the subpath import avoids it.
Proving from code
The hider's side lives in the SDK. The prover objects are injected so that importing the SDK does not pull WebAssembly into a bundle:
import { Noir } from '@noir-lang/noir_js';
import { UltraHonkBackend } from '@aztec/bb.js';
import circuit from '../circuits/zk_sniper/target/zk_sniper.json';
import { createSniperProver, sniperCommitment, sniperRandomSalt } from '@zk-pad/sdk';
const salt = sniperRandomSalt();
const hash = sniperCommitment(3, 5, salt); // goes in createRound
const prover = createSniperProver({
noir: new Noir(circuit),
backend: new UltraHonkBackend(circuit.bytecode),
});
const proof = await prover.prove({ x: 3, y: 5, salt }, { x: 6, y: 2 });
// proof.publicInputs = [positionHash, 6, 2, 0]; send proof.proof to answerShot(roundId, 6, 2, false, ...)
await prover.destroy();
The web app runs the same code inside a Web Worker and fetches the circuit from
/circuits/zk_sniper.json. Proof generation and proof verification both pass
{ verifierTarget: 'evm' } to match the ZK verifier. Proving downloads the public CRS (structured
reference string) the first time, which is why a hider should prepare proofs before going offline.
The download comes from crs.aztec-cdn.foundation (falling back to crs.aztec-labs.com) and is
cached in the browser; it is not checked against a known hash. No secret leaves the browser and
a wrong CRS cannot produce a proof the verifier accepts, so the failure is availability (the
hider cannot answer), as described in the security model.
Send the result with a simulation and an explicit gas limit (simulateSniperAnswer).