Skip to main content

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.

Not deployed

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:

  1. The prover knows the opening of the public commitment: Poseidon(hider_x, hider_y, hider_salt) == hider_position_hash.
  2. 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:

IndexCircuit nameIn SolidityNotes
0hider_position_hashbytes32(positionHash)Stored in the round at createRound
1sniper_guess_xbytes32(uint256(x))The pending shot's column
2sniper_guess_ybytes32(uint256(y))The pending shot's row
3is_hitbytes32(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 verifier reports 12 public inputs

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​

ItemValue
SchemeUltraHonk, zero-knowledge flavour (bb -t evm). The commitments to the witness polynomials are blinded and every proof is randomized
Circuit size4,096 gates (2^12), 12 public inputs including the pairing-point object
Proof size7,232 bytes (226 field elements). Proofs are randomized: two proofs of the same statement differ
Verifier runtime size24,244 bytes, which is 332 bytes under the 24,576 B EIP-170 limit
Linked libraryZKTranscriptLib, 6,108 bytes. The verifier calls it, so it must be deployed first and its address written into the verifier's creation code
Verification gasAbout 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 behaviourAn 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).

BuildVerifier runtimeMargin to EIP-170
evm (ZK), runs = 1 or 20 (shipped: 1)24,244 B332 B
evm (ZK), runs = 10024,304 B272 B
evm (ZK), runs = 20025,174 Bover the limit
evm (ZK), via_ir = truedoes 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 both generateProof and verifyProof of @aztec/bb.js (the SDK exports SNIPER_VERIFIER_TARGET). A proof made with the evm-no-zk target is a different format, is rejected on-chain, and must never be produced for a real position.
  • build.sh no longer offers evm-no-zk and refuses a leftover VERIFIER_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:

ComponentVersion
nargo1.0.0-beta.20
bb (Barretenberg CLI)5.0.0-nightly.20260324
@noir-lang/noir_js1.0.0-beta.20 (exact; SDK optional peer dependency and web dependency)
@aztec/bb.js5.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 compilersolc 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 with is_hit flipped 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.json and ZkSniperTranscriptLib.json are copied to contracts/test/artifacts/ and the compiled circuit zk_sniper.json to apps/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:

FileWhat
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.jsonThe Poseidon commit and the hash of the dependency sources the circuit must embed
circuits/zk_sniper/fixtures/*.jsonHit and miss proof fixtures and the Poseidon vectors
contracts/verifiers/ZkSniperVerifier.solGenerated Solidity verifier
contracts/test/artifacts/{ZkSniperVerifier,ZkSniperTranscriptLib,zk-sniper-proof-hit,zk-sniper-proof-miss}.jsonForge 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.solThe one helper that deploys the library and links the verifier
apps/web/public/circuits/zk_sniper.jsonCircuit 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:

  1. deploy the library from ZkSniperTranscriptLib.json;
  2. read ZkSniperVerifier.json, check that its only placeholder is the one derived from ZkSniperVerifier.sol:ZKTranscriptLib (anything else reverts), write the library address over every occurrence, and CREATE the 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.

  1. Install the pinned tools (noirup -v 1.0.0-beta.20, bbup -v 5.0.0-nightly.20260324).

  2. Run circuits/zk_sniper/build.sh --clean and read its output for warnings.

  3. Confirm the vk_hash. It must appear identically in target/vk_hash, in the header and the VK_HASH constant of contracts/verifiers/ZkSniperVerifier.sol, and later in the deployment JSON (games.zkSniperVkHash).

  4. Run the contract suite from contracts/:

    forge build --sizes
    forge 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 answerShot round trip. A mock verifier is used only in narrow unit tests. The tests that expect a rejection cap the gas they supply.

  5. 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.

  6. A new verifier requires a new ZkSniper deployment: 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 by scripts/preflight.sh and scripts/release-check.sh) requires the verifier's real uint256 constant VK_HASH (not only the header comment), the header, both proof fixtures and the verifier creation code to equal target/vk_hash; the web circuit to equal target/zk_sniper.json, hold no absolute path and embed the pinned Poseidon sources; the committed artifacts to equal a rebuild of contracts/verifiers (needs solc 0.8.27); and, with the pinned nargo and bb on the path, the circuit and vk to re-derive to the committed values.
  • scripts/release-check.sh treats contracts/verifiers, contracts/test/artifacts, circuits/zk_sniper, apps/web/public/circuits and contracts/script as guarded paths, like contracts/src: unmerged or unpushed work touching them fails the release stamp.
  • scripts/check-deployed-bytecode.mjs compares the deployed game, verifier and library with the build. Immutables are not blanket-masked: the game's verifier must equal games.zkSniperVerifier; the verifier's LOG_N, VK_HASH, NUM_PUBLIC_INPUTS and MSM-size values must equal what ZkSniperVerifier.sol says, and VK_HASH must equal target/vk_hash and games.zkSniperVkHash. Only the linked library address is masked: it must be one address at every link offset, equal games.zkSniperVerifierLibrary, and its code must equal the committed ZkSniperTranscriptLib.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:

WhereImplementation
Circuitposeidon::poseidon::bn254::hash_3 from noir-lang/poseidon v0.3.0
SDK and webposeidon3 from poseidon-lite 0.3.0 (circomlib parameters)
Test fixturesVectors 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]) equals 0x0e7732d89e6939c0ff03d5e58dab6302f3230e269dc5b968f725df34ab36d732, the circomlib value of Poseidon(1, 2, 3) (decimal 6542985608222806190361240322586112750744169038454362455181422643027100751666).
  • gen-prover-inputs.mjs asserts the same vector and writes fixtures/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.

SDK import

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).