Playing as the hider
A hider is the player who locks collateral and keeps a square secret. Every shot must be answered with a zero-knowledge proof. You do not answer shots by hand. Before the round goes live your browser builds the proof for every square, and something answers each shot for you within seconds. This page covers what you choose, what that choice costs, and what you watch.
ZK-Sniper is not deployed on any network and has had no audit. Nothing here is a promise that a deployment will exist. The rules are those of the code in the repository.
At launch createRound is gated: unless the owner has opened creation, only addresses the platform
approved (approvedHider) can host a round, and anyone else gets HiderNotApproved. If your wallet
is not approved you can still play as a sniper. Rounds hosted by an approved address are answered by
the House's own responders. See House rounds.
What you commit and what you must keep
When you create a round you choose three secrets:
| Secret | What it is |
|---|---|
| x, y | The square, each from 0 to 7 |
| salt | A random number with about 250 bits of entropy, generated for you |
Only Poseidon(x, y, salt) goes on-chain. You alone can produce proofs for it. If you lose the
three values, nobody can build new proofs for you. If your answerer already holds the 64 proofs it
can keep answering, but if it does not, every shot ends in a timeout that pays the sniper the whole
pool. If someone else obtains the values, they know your square and can shoot it.
The hider key
The three values travel as one text string, the hider key, which looks like zks1. followed
by encoded data. The app stores it in your browser when you create a round and makes you save it
before you can continue. Treat it like a wallet seed phrase:
- Back it up in a password manager or another place you control. Browser storage can be cleared, and a private window forgets everything when it closes.
- Never share it. Whoever holds it can win your pool by shooting your square, or by selling the knowledge.
- Importing it elsewhere (the keys page of the app) lets you monitor the round from a new browser or device and rebuild proofs there. The key carries its own commitment and is rejected if it has been altered.
- The key does not hold funds. The collateral sits in the contract and comes back to the wallet that created the round, through an escape.
Use a fresh salt every time
The salt must be random and never reused. A guessable salt (a date, a word, a number) lets
anyone try all 64 squares offline and recognise your commitment. The app generates salts with a
cryptographic random source. If you build your own client, use the SDK helper sniperRandomSalt.
How answering works now
Earlier drafts of this game asked the hider to prove and send an answer for every shot, with about 27 minutes to do it. That cannot work in a live game: a hider would have to be at the screen the whole time, and a sniper would wait minutes to learn if a guess missed. The rules are now:
- Proofs are built before the round exists. Because the commitment is known up front, the app
builds all 64 answers (63 misses and the one hit) before you send
createRound. Each is just a transaction waiting to be sent. - Something answers automatically. When a shot is mined, the answerer sends the stored proof for that square. You choose the answerer when you create the round (next section). There is no mode where you click once per shot.
- The answer window is a backstop. The default window is 267 blocks, about 2 minutes on BSC
at 0.45 s per block. A normal answer lands in about 1 to 3 seconds; the window only decides how
long your answerer may be down before a sniper can claim the pool by timeout. The window is
copied into your round at creation, so a later change by the contract owner never shortens it:
check
answerWindowBlocksingetRoundbefore you create a round on a contract you do not know. - If one square is the hit, the answerer answers that one first. A hit answer pays the sniper what a timeout would, and it ends the round, so there is nothing to gain by delaying it. See how a hit settles.
The contract's rules for the window are in the contract reference: at least 67 blocks (about 30 seconds), at most 28,800 (about 3.6 hours). Why the old 27-minute default is gone, and what the short window costs you, is under outage risk.
Choosing who answers
You pick one of two answerers in the create-round flow, before the proofs are built:
| zk-pad responder (recommended) | This browser | |
|---|---|---|
| Who sends the answers | zk-pad's responder service | A key stored in this browser tab |
| Works while you are offline | Yes | No. Only while this tab stays open and awake |
| Typical answer time | about 1 to 3 seconds | about 1 to 3 seconds while the tab is in the foreground |
| Gas for the answers | zk-pad pays | You fund the key (about 0.0115 BNB at 0.05 gwei; see below) |
| Who learns your square | zk-pad. It holds the 64 proofs, one of which says "hit" | Only you. The proofs never leave the device |
| What can take it down | A responder outage (two redundant instances run to make this unlikely) | Closing the tab, a locked phone, a dead battery, a throttled background tab, an empty key |
| Cost of the round | Subject to the responder's limits (below) | Your gas only |
House rounds always use the House's responders; there is no choice.
There is no third option in which the answer waits for you. Because answerShot is permissionless, you
can in an emergency send a stored proof yourself (see the emergency fallback),
but the game is built so you should never have to.
Preparing the proofs
After you pick the square, the price and the answerer, the app shows Preparing proofs and builds all 64 proofs in your browser before the "create" button works. Keep the tab open until it finishes.
What to expect:
- It runs in several background workers in parallel, as many as your device sensibly supports (at most 4; fewer on phones). Each worker needs a lot of memory: in Node, each extra copy of the prover added about 400 to 500 MB. On a phone the app starts with one or two.
- The first time, it downloads the public proving parameters (the CRS). That download can fail or be slow; see security.
- How long? Measured in Node on one developer machine: about 0.5 s per proof, 32 s for all 64 on one thread, about 9 s with 4 workers. Browser and phone times have not been measured. Expect seconds to a few minutes depending on the device. The app does not promise a time up front: it estimates the time left after it has finished its first proofs, and warns if the device looks slow.
- You can cancel, and you can resume. Finished proofs are kept in your browser's storage, so coming back continues from where it stopped. Changing the square or the salt discards them.
- The proofs are as sensitive as the hider key: they reveal your square. They stay on the device unless you chose the zk-pad responder.
- Each set is checked before you can continue (a hit and a miss are verified, and all 64 are checked to belong to your commitment).
Your commitment and the squat case
A commitment hash can be used only once, and it does not contain your address. If someone copied
your pending transaction's hash and got in first (a commitment squat), your createRound
reverts with PositionHashUsed. Nothing is lost except the proofs: they were built for that hash,
so the app picks a fresh salt and prepares them again. The squatter only locks up their own
collateral, because they cannot answer any shot. This is accepted and not fixed.
The zk-pad responder
The responder is a service run by zk-pad, part of the relayer. It watches the chain and sends the answer for every shot on your round. To do that it must hold your 64 proofs.
The 64 proofs include the one that says "this square is a hit". Whoever runs the responder therefore knows your square. They could shoot it from another address and win your pool, or pass the information on, and the contract cannot stop that. A breach of the responder's store would expose every round it serves at once. The operator of the zk-pad responder is zk-pad.
This is a real trade, not a free feature: the responder gives you reliability and takes your privacy. It used to be an opt-in extra for hiders who expected to be offline. It is now the default recommendation because it is the only way to be answered while you are away. If that is not a trade you accept, choose This browser.
What it receives and when
- After the proofs are built the app asks your wallet to sign a stage message (EIP-712, domain
ZkPadSniperResponder, typeStageProofs, bound to the chain and the game, over the position hash and a hash of the proofs). It does not move funds. - The app uploads the 64 proofs (about 0.9 MB) to the responder's staging route. The responder checks them: exactly 64, for 64 distinct squares, exactly one hit, each bound to your commitment and its square, each verifying against the deployed verifier, your wallet allowed to create rounds (the gate), a wallet balance of at least the responder's minimum collateral, the commitment not already used, and that the responder can afford to answer for one more round (next section).
- Staged proofs wait for 15 minutes by default. You then send
createRound. When the responder sees theRoundCreatedevent for your commitment from the same wallet, it arms the round by itself. There is no second signature and no upload after the round exists. If the 15 minutes pass, the app asks you to sign again. - If someone else creates a round with your commitment first, nothing is armed (the wallet does not match) and the staged entry expires. They learn nothing: the responder never serves proofs.
You can revoke the stored proofs with a signed request at any time; the responder deletes them when the round ends. The earlier "upload after creation" route still exists to re-arm a round that was evicted or revoked.
What it will and will not pay for
The responder pays the gas of every answer (about 2.4 million gas each) and earns nothing for it:
answerShot refunds the caller nothing and the contract has no answerer reward. So the operator
decides, before the round starts, whether it will serve it. The limits are published by the
service (GET /v1/sniper/config) so the app can show them before you pay. These are the intended
defaults; a deployment can change them.
| Limit | Default | What it means for you |
|---|---|---|
| Miss answers per round | 63 over the round's life | Raised from 8 so that a full board of shots is covered. The hit answer is separate |
| Fees must justify the gas | the cheapest shot (baseFee) must pay for one answer (counted as 2.5M gas) within 5% | A round with a small base fee is refused with HTTP 422 when the client declares its base fee at staging, and in every case when the round is created: a round that fails the check at that point is not armed and the monitor says so |
| The gas price used for that check | the higher of the current price and a floor of 0.2 gwei by default | A gas spike after you create the round does not make the responder drop it. The check is done up front, at the worst case |
| Worst-case budget | each admitted round reserves 64 answers at that price (0.032 BNB at the floor). Defaults: 0.1 BNB per hider (three rounds) and 1 BNB overall | A hider with rounds already held, or a responder at its overall budget, is refused at staging (HTTP 422 / 503) |
| Mid-round refusals | only "responder wallet empty" and a global emergency brake (ten times the overall budget spent in one window) | Budgets are enforced when a round is admitted, not by refusing answers later. A refusal in the middle of a round would turn into a free timeout for whoever caused it |
| Collateral floor | 0.064 BNB (a base fee of 0.001 BNB) | A smaller round is refused |
| Capacity | 100 rounds, 10 per hider; the longest-idle round is evicted when full; proofs older than 14 days with no pending shot are dropped | A stored upload is not guaranteed to be there for ever. The monitor shows whether your round is armed |
| House rounds | not subject to the cost rules | The House's own rounds are answered regardless; the limit that protects the responder from strangers does not apply to its operator |
By this arithmetic, at the 0.2 gwei floor one answer is counted as 2.5M gas x 0.2 gwei = 0.0005 BNB, so a community round needs a base fee of at least about 0.01 BNB to be admitted. A smaller community round cannot use the responder and should use This browser. These prices are the defaults, not measurements of BSC.
A refused round is not a bug. Check the monitor after you create a round: if it says the round is not armed (for example because the fee check failed at creation), re-arm it or switch to a browser answerer before the first shot, and do not rely on the responder until the monitor says armed.
How it is authorized
Staging, uploading and deleting proofs requires a signature from the round's hider wallet. Smart contract wallets are supported through ERC-1271. The responder answers each shot by sending the stored calldata from its own funded keys with a fixed gas limit (3 million; a miss uses about 2.37 million). It does not simulate at shot time because every proof was verified when it was loaded and the verifier cannot change. See Answer times for the path and the numbers.
The responder is a feature-flagged part of the zk-pad relayer. Whether a given deployment runs one is
a deployment choice. API details are in the SDK API.md.
This browser: the session key
If you choose This browser, the app creates a session key in your browser. It is a throwaway key whose only job is to send your answers, so no wallet prompt appears per shot.
- You fund it. It needs gas for up to 64 answers. The app recommends an amount from the live gas price: 64 answers of about 2.39 million gas at 0.05 gwei is 0.0077 BNB, and the app asks for 1.5 times that, about 0.0115 BNB, with a floor of 0.005 BNB. At 1 gwei the same recommendation would be about 0.23 BNB. The create button is a two-step: fund the key (one wallet transaction), then create the round (a second). If the second fails the key stays funded and is reused on retry.
- It cannot touch your collateral.
answerShotis authorized by the proof, not by the caller. If the key leaks, the worst case is that someone spends its balance. - But it lives next to your hider key. It is stored in the same browser storage, so a script that can read one can read the other (for example through a cross-site-scripting bug on the site). Keep the balance small, and sweep it.
- The tab has to stay open. The key answers while this tab is open and awake. A tab in the background is throttled by the browser; a phone that locks may suspend it; a closed tab sends nothing. The app polls for shots from a background worker thread and asks the browser to keep the screen awake where it can, but no browser guarantees a background tab. The monitor shows the state as degraded when the tab is hidden and as not answering when it has not polled for more than 10 seconds. If this happens when a shot arrives, the shot times out after the window and a sniper takes the pool, including your collateral.
- One tab only. A lock stops a second tab from sending the same answers.
- Running dry. If gas jumps while the round is live and the key can no longer pay, answers stop. The monitor warns when the balance covers only a few answers and has a top-up button.
- Sweep, export, forget. You can sweep what is left back to your wallet at any time (the app also offers it after the round ends), export the key behind a confirmation, and forget it only after sweeping, because the app refuses to forget a key that still holds funds.
- No simulation. The proofs were checked when they were built and the gas limit is fixed, so the key sends without simulating first.
An older "helper key" or "burner" from earlier drafts, if one is in your browser, is shown on the keys page as a legacy key so you can sweep or export it. Nothing creates a new one.
Watching the round: the monitor
On your own round the page is a monitor, not a to-do list. It shows:
- Status of the auto-answer: healthy, arming, degraded, not answering.
- Who is answering: the zk-pad responder, the House responder or this browser, whether the backup responder is up, and whether the feed is live or polling.
- Answers history: every answer with the time it took (for example 1.2 s), who sent it and its block.
- Waiting shots, read-only, with a "slow" mark after 10 seconds and a countdown to the point where a sniper could claim.
- Session key (browser mode): address, balance, how many answers it covers, top-up, sweep, export, forget.
- Start extraction (below) and your hider key.
- A collapsed emergency area (next).
If nothing is answering, the monitor says so in plain words, with the time left and two buttons: arm the responder again, or use this browser.
Emergency fallback
The only manual answer left is behind a collapsed "Emergency" section. If your answerer is not answering and a shot is close to its deadline, you can send the stored proof yourself with your wallet. The proof is already built, so it is one confirmation. If this device has no prepared proofs (you imported the key elsewhere, or storage was cleared), the app offers to rebuild them first, and that takes the time the build takes. Do not plan around it.
Outage risk and what protects you
The window is short on purpose, and that has a price you should understand.
Answers are automatic, so nobody needs 27 minutes to wake up and open a tab. A long window only makes snipers wait and ties up their money. The cost of a short window is this: if your answerer is down for the whole window (267 blocks, about 2 minutes by default), a sniper who fired during the outage can claim the pool. Because the responder's health endpoint and the chain are public, a bot can notice an outage and fire a probe at every live round. A probe costs one base fee; the payout is about 58.5 base fees. Break-even is a win chance of about 1.7%, which the bot reaches once the answerer has been down for a short time. The numbers are on the economics page.
Who bears it: the hider. In a House round that is the House; in a community round it is you. Snipers never lose money to a responder outage.
What the design does about it:
- Two redundant responders. The primary answers at once. A backup instance on different infrastructure waits a short, configurable delay (1.5 s by default), checks the chain, and skips any square already answered. If the primary is healthy the backup sends nothing.
- Separate keys and RPCs. Each instance has its own funded sender keys and its own RPC providers, so one stuck transaction or one provider failure does not stop both.
- Alerts and checks on the public health endpoint, wired by the operator (a list is in security).
What it does not cover: a bug that stops both instances, a poisoned proof store, a compromised
operator, and a contract owner who sets the minimum 67-block window (about 30 seconds) for new rounds,
which leaves the failover almost no room. The monitor and getRound show your round's actual window.
If you pick This browser, the same risk applies at your end: it is a tab on a device you control, which is a weaker answerer than a pair of servers.
What can go wrong, and what it costs
| Situation | Result |
|---|---|
| A shot arrives and your answerer sends the miss proof | That square is cleared. The round stays open. The sniper sees "Answered in 1.8 s" or similar |
| The shot is a hit | You lose the pool: the sniper gets pool minus 10%. This is the game |
| Your answerer is down for the whole window | claimTimeout pays the sniper of the unanswered shot the pool (minus 10%) as if it were a hit |
| Your answerer is down briefly but answers before the window ends | Nothing lost. The sniper's row turns "Slow" after 10 s and may show a countdown |
| An answer arrives after the deadline | Rejected. Only the timeout can settle it |
| Several shots are pending and one of them expires | The first expired shot that anybody claims ends the round in its sniper's favour, and the other pending shots are void |
Staying silent never helps you against an honest sniper. A timeout pays the sniper exactly what a hit would, so withholding the answer to a hit saves nothing, and withholding the answer to a miss only hands the sniper a pool they did not earn.
Starting a round
- Pick a square and a base fee. The collateral is 64 times the base fee, and it is the starting pool. The app shows the pricing table for your base fee before you commit. A lower base fee means smaller pools and cheaper shots; read Economics and fairness to see what that does to your odds. Your round also records the contract's current answer and extraction windows.
- Choose who answers: the zk-pad responder or this browser.
- Wait for the proofs. In responder mode the app then asks for the stage signature and uploads. In browser mode it asks you to fund the session key.
- Send
createRound. The app stores the secret under the commitment before the transaction goes out, so a closed tab does not lose it. If the browser cannot store it the app warns you and refuses to send. If your wallet is not an approved hider the contract refuses withHiderNotApproved(see House rounds). - Save your hider key when the app shows it. In responder mode the dialog also shows "Arming" and then "armed"; if it takes more than about 20 seconds it says so and keeps trying.
Leaving: extraction
You can leave at any time that the round is not already settled:
- Press Extract (
initiateExtraction). A countdown starts, 100 blocks by default (about 45 seconds on BSC), taken from your round's own snapshot. You can only do this once per round, and you can do it while shots are pending. - Snipers can keep firing until the countdown ends. Your answerer keeps answering, including the shots that were already pending. In browser mode, keep the tab open.
- When the countdown has ended and no shot is pending, press Escape (
claimEscape). You receive the pool minus 10% of the fees and sponsorships (never of your own collateral).
A shot fired in the last block of the countdown has a full answer window of its own, so an escape can be delayed by up to about 2 minutes at the default window (267 blocks), or by the whole window of your round, unless that shot is answered sooner. Normally it is answered within seconds. A hit still wins for the sniper.
The hider's own address cannot fire at its round. A second wallet can, and the chain cannot tell it from a real sniper. That is an accepted limitation, and a hider who uses it is cheating the snipers: see Security model and Economics and fairness for what it costs and why the contract cannot prevent it. With the 2-minute default, the second-wallet timeout void needs about 2 minutes of waiting instead of 27; the cost to the cheater (the 10% rake) is unchanged. The honest way out is the extraction above.
Pausing the contract never stops you: initiateExtraction, claimEscape and answerShot all
keep working while it is paused. Only new rounds, new shots and sponsorships stop. Closing the
creation gate or removing your approval does not stop you either: it only blocks new rounds.
Checklist
- Hider key saved outside the browser
- You chose an answerer on purpose, and you know what it can see (responder) or what it needs (browser tab open, a funded session key)
- All 64 proofs finished and the app shows them ready (and, in responder mode, armed)
- Session key funded for a full round, and you know how to sweep it (browser mode)
- You know the answer window and extraction window recorded in your round (
getRound) - You have read Economics and fairness and picked a base fee on purpose
- You accept that you can lose the whole collateral and that nothing here is audited