Skip to main content

How ZK-Sniper works

ZK-Sniper is a two-sided guessing game on an 8x8 grid. A hider locks BNB behind one secret square. Snipers pay to guess squares. The hider answers every guess with a zero-knowledge proof, so the square stays secret until somebody guesses it.

Not deployed

ZK-Sniper is not deployed on any network, including BSC mainnet. This page describes the rules implemented in the repository. There are no addresses, no live rounds and no audit yet. See Security model.

The game does not favour everyone equally

The price curve rewards snipers with deep pockets, a hider whose answerer is down for a whole answer window loses by timeout, and a hider with a second wallet can exit without facing a hit and keep real snipers' fees for about 10% of the collateral. Read Economics and fairness and the known limitations before putting money in on either side. Rounds are meant to be hosted only by platform-approved addresses at launch (House rounds); that changes who the hider is, but the chain cannot prove the House does not shoot its own round.

Who can host a round​

createRound is gated. It succeeds only if the contract's openCreation flag is true or the caller is an approvedHider; otherwise it reverts HiderNotApproved. The intended launch is House-only: openCreation is false and only approved addresses host rounds, because the chain cannot tell a hider's second address from a real sniper. The gate applies only to creating a round. It never touches shots, answers, timeouts, extraction, escape or withdrawals, and changing it never affects a round that is already running. See House rounds.

The idea in one minute​

  1. The hider picks a square (x, y) and a random secret salt, and publishes only a commitment: a Poseidon hash of the three values. The hider also locks collateral worth 64 times a chosen base fee.
  2. A sniper pays the current shot cost and names a square. That square is now pending, with its own answer deadline. Other snipers can keep firing at other squares while it waits: any number of shots can be pending at once.
  3. The hider's answerer sends a zero-knowledge proof that the sniper's square is a hit or a miss relative to the committed square. The contract checks the proof. The proof reveals nothing else about the square. This is automatic: all 64 proofs are built before the round goes live, so an answer is just a transaction, and it normally lands in about 1 to 3 seconds (Answer times).
  4. A miss clears that square's pending shot; its fee stays in the pool, which grows. A hit pays the whole pool (less the rake) to the sniper who hit it and ends the round.
  5. If nothing answers a shot before its deadline, that sniper takes the pool anyway (timeout). The deadline is a failure backstop, about 2 minutes by default, not the normal pace of the game.
  6. The hider can instead extract: start a short countdown and walk away with the pool (less a rake on the fees) if nobody hits first and every pending shot has been answered.

Timeline of a round​

Time is counted in blocks, never seconds. The numbers below use the defaults and the BSC block time of about 0.45 s (since the Fermi hard fork), so they move if the chain's block time does. A shot is normally answered within a few seconds, long before any clock matters; the clocks describe what happens when an answer does not come.

If instead B had hit the hider's square and the hider answered with a hit proof, B would be paid the pool less 10% and the round would end at once. If the hider never answered B, B would call claimTimeout after B's own deadline and be paid the same way.

The clocks​

ClockStartsLength (default)Real time at 0.45 sAllowed range (blocks)
Answer windowWhen a shot is fired; one clock per pending shot267 blocksabout 2 minutes67 to 28,800 (about 30 seconds to 3.6 hours)
Extraction countdownWhen the hider calls initiateExtraction100 blocksabout 45 seconds20 to 28,800 (about 9 seconds to 3.6 hours)

The answer window is the failure backstop: answers are automatic and normally land in seconds, so the window is how long a hider's answerer may be down, not how long the hider has to act. Both lengths are copied into each round when it is created. The owner can change the settings later, but only rounds created afterwards pick the change up: no running clock and no future clock of a round that already exists can move. Read the two numbers from getRound (fields answerWindowBlocks and extractionWindowBlocks) before you play.

Why shots are concurrent​

An earlier design allowed only one pending shot at a time. That let a hider fire once from a second wallet, never answer, and so hold the only slot through the whole extraction countdown while real snipers were locked out, then answer their own shot and escape risk-free. A single slot also let anybody send a 1-wei sponsorship just before a duel shot and make the exact-fee transaction revert.

The contract now keeps one pending record per square. Firing needs only an unshot square, so a parked shot blocks nothing but its own square. The price still rises with every shot fired, answered or not. Concurrency does not remove the second-wallet limitations: a hider with a second wallet can still exit without facing a hit and keep real snipers' fees, as described under Timeout and the race between expired shots.

The board​

  • 8 columns (x = 0 to 7, shown as A to H) and 8 rows (y = 0 to 7, shown as 1 to 8), so 64 squares.
  • Each square can be guessed once per round, even if the first guess was a miss. The contract tracks fired squares in a 64-bit bitmap (bit y * 8 + x) and, separately, the squares that are still waiting for an answer.
  • The proof circuit rejects coordinates of 8 or more, both for the hider's committed square and for a guess.

The commitment​

The hider's commitment is

positionHash = Poseidon(x, y, salt) // BN254 Poseidon, 3 inputs
  • Only the hash goes on-chain, in createRound.
  • The salt is a random field element. It is what makes the hash impossible to guess: without it, anybody could hash all 64 possible squares and compare. Never use a memorable salt.
  • The same hash can only be used for one round ever. The commitment contains no hider address, so a front-runner can copy a hash from the mempool and take it first (squatting). Your createRound then reverts with PositionHashUsed and you retry with a fresh salt. The squatter cannot answer shots, so it only locks its own collateral.
  • The hash must be a valid field element (below the BN254 scalar field), as the proof system requires.
  • Because the circuit only accepts squares on the grid, a hider cannot commit to a square that does not exist (which could never be hit). See the circuit reference.

Shot prices​

Everything below is deterministic and can be recomputed by anyone. The SDK exports the same math (sniperShotCost, sniperPricingMatrix, sniperHitPayout, sniperEscapePayout) and the contract rounds down in exactly the same places.

Let baseFee be the hider's chosen base fee and remaining = 64 - shotsTaken.

RuleValue
Collateral (paid once at creation, no top-ups)baseFee * 64
Opening poolthe collateral
Cost of the next shot when remaining > 2baseFee * 64 / remaining (rounded down)
Cost of the next shot when remaining <= 2 (the final duel)pool / 2 (rounded down)
Every shotits fee is added to the pool when the shot is fired

So the price of a shot goes up as squares run out: the first shot costs exactly the base fee, the shot after 32 misses costs twice that, and the shot after 48 misses four times that. The pool only grows, and shotsTaken goes up when a shot is fired, not when it is answered. With several shots pending, each new shooter therefore already pays the higher price.

You must send at least the current shot cost. The contract keeps exactly the cost and refunds the excess to you (through the same push that pays winners; if your address cannot receive it, the refund is credited for withdraw). A pad protects you only against a price rise smaller than the pad. A sponsorship, or another shot that takes the squares left from 3 to 2 (the price jumps to half the pool), can raise the price by more than any pad, and your shot then reverts with InsufficientFee and charges nothing. The hider's own address cannot fire at its round.

Worked table: base fee 0.01 BNB​

The collateral is 0.64 BNB. Amounts are in BNB, rounded to four decimals; each row assumes every earlier shot was a miss and nobody sponsored the round. "Hit pays" is what the sniper receives if this shot hits (pool plus the shot fee, less the 10% rake). "Escape pays" is what the hider would receive by escaping with this pool, before this shot is fired.

Shots takenSquares leftPool beforeShot costHit paysRake on a hitHit returnChance (random square)Escape pays
0640.64000.01000.58500.065058.50x1.56%0.6400
1630.65000.01020.59410.066058.49x1.58%0.6490
8560.72470.01140.66260.073657.97x1.78%0.7163
16480.82250.01330.75220.083656.42x2.08%0.8042
24400.93780.01600.85840.095453.65x2.50%0.9080
32321.07870.02000.98880.109949.44x3.12%1.0348
40241.25950.02671.15750.128643.41x4.16%1.1975
48161.51240.04001.39720.155234.93x6.25%1.4252
5681.93670.08001.81500.201722.69x12.50%1.8070
6042.34280.16002.25250.250314.08x25.00%2.1725
6132.50280.21332.44450.271611.46x33.33%2.3165
6222.71611.35803.66670.40742.70x50.00%2.5085
6314.07412.03715.50010.61112.70x100.00%3.7307

The last two rows are the final duel: with two squares left the shot costs half the pool, and with one square left the shot is a certain hit if all the other 63 squares were answered misses. While other shots are still pending that does not hold, because the hider's square may be among them. A rational hider extracts before that.

All 64 rows (base fee 0.01 BNB)
Shots takenSquares leftPool beforeShot costHit paysRake on a hitHit returnChance (random square)Escape pays
0640.64000.01000.58500.065058.50x1.56%0.6400
1630.65000.01020.59410.066058.49x1.58%0.6490
2620.66020.01030.60340.067058.46x1.61%0.6581
3610.67050.01050.61290.068158.41x1.63%0.6674
4600.68100.01070.62250.069258.36x1.66%0.6769
5590.69160.01080.63220.070258.28x1.69%0.6865
6580.70250.01100.64220.071458.20x1.72%0.6962
7570.71350.01120.65230.072558.09x1.75%0.7062
8560.72470.01140.66260.073657.97x1.78%0.7163
9550.73620.01160.67300.074857.84x1.81%0.7266
10540.74780.01190.68370.076057.69x1.85%0.7370
11530.75970.01210.69460.077257.52x1.88%0.7477
12520.77170.01230.70560.078457.33x1.92%0.7586
13510.78400.01250.71690.079757.13x1.96%0.7696
14500.79660.01280.72850.080956.91x2.00%0.7809
15490.80940.01310.74020.082256.67x2.04%0.7925
16480.82250.01330.75220.083656.42x2.08%0.8042
17470.83580.01360.76450.084956.14x2.12%0.8162
18460.84940.01390.77700.086355.85x2.17%0.8285
19450.86330.01420.78980.087855.53x2.22%0.8410
20440.87750.01450.80290.089255.20x2.27%0.8538
21430.89210.01490.81630.090754.84x2.32%0.8669
22420.90700.01520.83000.092254.47x2.38%0.8803
23410.92220.01560.84400.093854.07x2.43%0.8940
24400.93780.01600.85840.095453.65x2.50%0.9080
25390.95380.01640.87320.097053.21x2.56%0.9224
26380.97020.01680.88840.098752.75x2.63%0.9372
27370.98710.01730.90390.100452.26x2.70%0.9524
28361.00440.01780.91990.102251.75x2.77%0.9679
29351.02220.01830.93640.104051.21x2.85%0.9839
30341.04040.01880.95330.105950.65x2.94%1.0004
31331.05930.01940.97080.107950.06x3.03%1.0173
32321.07870.02000.98880.109949.44x3.12%1.0348
33311.09870.02061.00740.111948.79x3.22%1.0528
34301.11930.02131.02660.114148.12x3.33%1.0714
35291.14060.02211.04640.116347.42x3.44%1.0906
36281.16270.02291.06700.118646.68x3.57%1.1104
37271.18560.02371.08830.120945.91x3.70%1.1310
38261.20930.02461.11050.123445.11x3.84%1.1523
39251.23390.02561.13350.125944.28x4.00%1.1745
40241.25950.02671.15750.128643.41x4.16%1.1975
41231.28610.02781.18260.131442.50x4.34%1.2215
42221.31400.02911.20880.134341.55x4.54%1.2466
43211.34310.03051.23620.137440.56x4.76%1.2728
44201.37350.03201.26500.140639.53x5.00%1.3002
45191.40550.03371.29530.143938.45x5.26%1.3290
46181.43920.03561.32730.147537.33x5.55%1.3593
47171.47480.03761.36120.151236.16x5.88%1.3913
48161.51240.04001.39720.155234.93x6.25%1.4252
49151.55240.04271.43560.159533.65x6.66%1.4612
50141.59510.04571.47670.164132.30x7.14%1.4996
51131.64080.04921.52100.169030.90x7.69%1.5407
52121.69000.05331.56900.174329.42x8.33%1.5850
53111.74340.05821.62140.180227.87x9.09%1.6330
54101.80160.06401.67900.186626.23x10.00%1.6854
5591.86560.07111.74300.193724.51x11.11%1.7430
5681.93670.08001.81500.201722.69x12.50%1.8070
5772.01670.09141.89730.210820.75x14.28%1.8790
5862.10810.10671.99330.221518.69x16.66%1.9613
5952.21480.12802.10850.234316.47x20.00%2.0573
6042.34280.16002.25250.250314.08x25.00%2.1725
6132.50280.21332.44450.271611.46x33.33%2.3165
6222.71611.35803.66670.40742.70x50.00%2.5085
6314.07412.03715.50010.61112.70x100.00%3.7307
How to read the "chance" column

The chance column assumes the hider's square is uniformly random among the squares not yet guessed. A hider who picked a predictable square (a corner, say) is easier to hit than that. Against a uniformly random square, a single shot's expected return (chance times hit return) is about 0.91x on the first shot and passes 1x from the seventh shot on, because the pool grows faster than the price. That is the heart of the economics: the game favours a sniper who can afford to keep shooting, and the hider's tools against that are a low base fee, an early extraction and an answerer that does not go down. Nothing here promises that hiding or sniping is profitable. See Risks.

The ten percent rake​

The platform keeps 10% (1,000 basis points of 10,000). The rake is paid to the treasury address when a round settles:

How the round endsWho is paidRake base
Hit (a valid hit proof)The sniper who fired the hit square gets pool minus rakeThe whole pool, including every shot fee still in it
Timeout (a shot unanswered past its deadline)The sniper who fired that unanswered shot gets pool minus rakeThe whole pool
Escape (the hider extracts)Hider gets pool minus rakeOnly pool - collateral: the sniper fees and sponsorships. The hider's own collateral is never raked

Rounding is always down, so the rake can be a wei lower than an exact 10%, and the payout plus the rake always equals the pool exactly. When a round ends in a hit or a timeout, every other shot that was still pending is void: its fee simply stays in the pool and is paid to the winner.

Hits, misses and answering​

After fireShot(roundId, x, y) the square is pending and has its own deadline. The round stays Open, so other snipers can fire at other squares while it waits. The hider's answerer (or anybody holding a valid proof) calls answerShot(roundId, x, y, isHit, proof) for that square before its deadline:

  • Miss: the proof shows the guess is not the committed square. That square's pending record is cleared and the round stays Open. The square still counts as guessed and cannot be shot again. The fee stays in the pool.
  • Hit: the proof shows the guess is the committed square. The sniper who fired it is paid and the round ends. Other pending shots are void.
  • A proof that does not verify against the committed hash, the pending square and the claimed result reverts with InvalidProof. You cannot answer "miss" for a square that is a hit. The contract reports every verifier failure, including a verifier that runs out of gas, as InvalidProof.
  • Shots can be answered in any order. Only one hit can ever exist, because the circuit pins the hider's single square.

answerShot is permissionless: it is the proof, not the caller, that authorizes the outcome. This is what lets the zk-pad responder or a session key in the hider's browser answer for the hider without any power over the hider's funds.

Answering is expensive and a bad proof can burn gas

Verifying one proof costs about 2.35 million gas as a direct transaction (the proof is 7,232 bytes). A tampered proof can make a bn254 precompile fail, and a failing precompile burns all the gas it was given. Anything that sends answerShot must set an explicit gas limit of a few million, never an open-ended one, and should only send proofs that were checked first. The responder and the browser session key check every proof when it is built or loaded and then send with a fixed 3M gas limit without simulating at shot time, because a proof that verified once verifies again (the verifier is immutable in the game). A client that sends a proof it has not checked should simulate first; the SDK helper simulateSniperAnswer does this with a 3.5M limit. See the circuit reference.

Answer window and timeout​

When a shot is fired the contract records a deadline for that square: the current block plus the round's answerWindowBlocks. The default is 267 blocks, about 2 minutes on BSC at roughly 0.45 s per block. The contract counts blocks, never seconds, so the real time moves with the chain. The range the owner may set for new rounds is 67 to 28,800 blocks (about 30 seconds to 3.6 hours).

Why the window is short. The earlier default was 3,600 blocks (about 27 minutes) with a minimum of 1,800. That length existed to give a person time to notice a shot, open a tab and send a proof by hand for every shot. That is not a playable game: the hider cannot be at the screen the whole round and a sniper cannot wait minutes to learn whether a guess missed. Answers are now automatic and proofs are built before the round starts, so a normal answer lands in about 1 to 3 seconds and the window only has to cover a failure of the answerer. A short window is also what a sniper wants: their money is tied up for less. The price of a short window is that an answerer outage of about 2 minutes is enough for a sniper to claim a timeout, which is why the responder runs redundantly. That trade-off is spelled out under the responder and the first-shot-timeout bot.

An answer is accepted up to and including the square's deadline block. If the deadline passes with no valid answer, anyone can call claimTimeout(roundId, x, y). The pool (less the rake) is sent to the sniper who fired that square, regardless of who calls, and the round ends. A late answer is rejected.

This is why a hider must have an answerer that works for the whole round: the zk-pad responder, or a funded session key in an open browser tab. See the hider guide.

How fast answers arrive​

The service level the project tests for is a 95th percentile under 6 seconds and no answer over 10 seconds, with a typical answer in 1 to 3 seconds. That is measured on a local chain with 1 s blocks, with the real verifier and real proofs, including bursts of pending shots. It is not yet measured on BSC. The test, the budget and the numbers measured so far are on Answer times. The app shows each answer's measured time, and calls a shot "slow" only after 10 seconds.

Timeout and the race between expired shots​

Every pending shot has its own timeout, and the first one that is claimed ends the round. That has two consequences you should understand before playing:

  • If several shots are past their deadline, whoever calls claimTimeout first chooses which expired sniper is paid. The others get nothing. Expired snipers should claim promptly.
  • A timeout on one square ends the round and voids every other pending shot, including shots still inside their answer window. Their fees stay in the pool. Because all shots in a round use the same window, a shot fired earlier always expires earlier.

The second point is a known, unmitigated limitation. A hider with a second address can fire a shot from it, leave it unanswered, and later let it time out first: the round ends in that address's favour, any real sniper's shot fired in between is void, and the hider keeps the real snipers' fees. The hider avoids losing to a hit at a cost of about 10% of the collateral (0.1 x (C + F), 0.065 BNB at a 0.64 BNB collateral and a 0.01 BNB fee), plus gas. A second version needs no timeout at all: the second address shoots the hider's own square and the hider answers it as a hit, a self-hit exit that skips the extraction countdown, for the same cost.

The contract cannot tell whose shot is whose, so a pending shot older than yours is a risk to your own shot. This is an accepted property of a design with no identity, not something the contract mitigates, and no rule that ignores identity can fix it. Snipers in community rounds are exposed. At launch only platform-approved addresses are meant to host rounds (House rounds), which is the trust-minimised path available, but the chain still cannot prove that a House hider does not shoot its own round. See the known limitations, in particular the hider shooting their own round, and Economics and fairness.

Extraction and escape​

A hider who has had enough can leave with the pool:

  1. initiateExtraction(roundId). Allowed once per round, while the round is Open, with or without shots pending, and also while the contract is paused. The contract records extractionEndBlock = now + extractionWindowBlocks, using the round's own snapshot. The default window is 100 blocks, about 45 seconds on BSC.
  2. During the countdown snipers can keep firing, up to and including the end block. A shot fired in time has to be answered, and a hit still ends the round for the sniper. Nobody can fire after the end block.
  3. claimEscape(roundId). Once the end block has passed and no shot is pending, the hider is paid pool - rake, with the rake taken only on pool - collateral. Any pending shot blocks escaping until it is answered or the round ends by timeout.

Two points of honesty about step 3. First, the countdown is short, but a shot fired in its last block has a full answer window, so an escape can be delayed by up to an answer window (about 2 minutes by default) unless that shot is answered sooner, which normally takes seconds. Second, the hider must answer the shots of real snipers like anybody else; a sniper who fires a hit square during the countdown wins if the hider answers truthfully.

The extraction window is deliberately short on BSC: 100 blocks is the time snipers get to react once the hider announces the exit. The owner can change the setting within bounds (20 to 28,800 blocks), but a running round keeps the value it was created with.

Sponsorship​

Anybody can add BNB to a live round with sponsorRound. Sponsorships go into the pool, so they raise what a hit pays (and what an escape pays the hider), and they are raked like fees on an escape. They never change the shot price (except in the final duel, where the price is pool / 2). A sponsor cannot take the money back. The hook exists so that the protocol can pour fees into game pools later; no such flow is built.

If a payout fails​

The contract pays winners directly, forwarding a fixed gas allowance of 50,000. This applies to the winner, the treasury and the refund of an overpaid shot. If the recipient is a contract that reverts, uses more than that, or cannot accept BNB, the payout is credited to that address instead (PayoutDeferred) and the round still settles. The recipient collects it with withdraw(), or with withdrawTo(address) to send it somewhere that can receive it. A hostile recipient, including the treasury, therefore cannot block a round from ending. The direct payment is only attempted when the transaction has enough gas left to give the recipient the whole allowance, otherwise the call reverts ("insufficient gas") so that nobody can force a deferral by starving it; resubmit with more gas.

Pausing​

The owner can pause the contract. Pausing stops entries only: createRound, fireShot and sponsorRound. It never stops an exit. initiateExtraction, claimEscape, answerShot, claimTimeout, withdraw and withdrawTo always work, so a hider can always start and finish an extraction and a pending shot can always be answered or timed out. The owner also cannot renounce ownership (renounceOwnership reverts with RenounceDisabled), so a paused game can always be resumed. See the contract reference and Security model.

One thing pause does change, and it is an admin-trust assumption: countdowns keep running while fireShot is rejected. An owner (or a timelock) that pauses right after a hider calls initiateExtraction removes the snipers' last-chance shots, and the hider escapes without facing them. A pause is also ordinary incident response, so the chain cannot tell the two apart. The owner cannot take funds this way, only withhold new shots.

Next​