DEV Community

Build Your Own Proof Gatekeeper Loop: A Hands-On Tutorial

In zkVerify's Agent Games, the Proof Gatekeeper track gives your agent 60 seconds per task: read a transfer condition, decide APPROVE or REJECT, and back the decision with a Groth16 proof your opponent - the platform - re-verifies.

Before you build the public endpoint the arena requires, build the loop itself, locally, on your own machine. That is what this tutorial does, step by step: download the tournament's official circuit, implement the decision checks, generate and verify a proof, and run the one test that proves the circuit refuses to lie.

This is my second entry for the Creator Track of #AgentGames. My first article was a build log of the same loop; this one is the tutorial I wish I had before writing it - the commands, the code, and the measured numbers, so you can reproduce every step.

You need Node.js and about ten minutes. No zero-knowledge background is required: the circuit is a black box you feed inputs and get a proof from.

One honest note up front: everything below ran locally. I have no live endpoint and have played no scored rounds. What follows is the loop, verified against the official artifacts - not a claim about the arena.

Step 1: Get the official artifacts

Everything starts at the tournament's circuit-info endpoint:

curl -s https://agentgames.zkverify.io/api/circuit-info

It returns the download URLs for the two artifacts plus the platform's registered verification-key hash. Download both files into a working directory:

  • gatekeeper.wasm - 1,755,820 bytes, the compiled circuit
  • gatekeeper_final.zkey - 309,750 bytes, the proving key

The circuit takes 13 inputs and exposes 13 public signals. The signal names were documented by probing the official wasm in @rday98 's public repo, which I credit here - I verified the interface against the official wasm myself before trusting it, and the code in this tutorial is my own implementation.

Keep the registered vkHash from the endpoint handy; it is the value your decision logic compares every incoming proof key against (mine starts 0x6b79c6…d77b0 ).

Step 2: Set up the project

mkdir gatekeeper && cd gatekeeper
npm init -y
npm install snarkjs@0.7.6 js-sha3

snarkjs does the proving and verifying; js-sha3 gives us keccak-256 for turning task IDs into circuit inputs (Step 4). That is the whole dependency list.

Step 3: Write decide() - the seven checks

Every task is either a valid condition or one of six traps. Your decide() runs the checks in trap-priority order and returns a decision plus a reason code:

function decide ( task , seenProofs ) {
  if ( task . proof_vk . toLowerCase ( ) !== task . registered_vk . toLowerCase ( ) )
    return { decision : 'REJECT' , reason_code : 'VK_SUBSTITUTION' } ;
  if ( seenProofs . has ( task . proof_tx ) )
    return { decision : 'REJECT' , reason_code : 'PROOF_REUSED' } ;
  if ( BigInt ( task . public_balance ) < BigInt ( task . minimum ) )
    return { decision : 'REJECT' , reason_code : 'THRESHOLD_MISMATCH' } ;
  if ( BigInt ( task . current_block ) >= BigInt ( task . expiry_block ) )
    return { decision : 'REJECT' , reason_code : 'EXPIRED_CONDITION' } ;
  if ( task . recipient . toLowerCase ( ) !== task . condition_recipient . toLowerCase ( ) )
    return { decision : 'REJECT' , reason_code : 'RECIPIENT_MISMATCH' } ;
  if ( BigInt ( task . amount ) > BigInt ( task . max_transfer ) )
    return { decision : 'REJECT' , reason_code : 'AMOUNT_OVERFLOW' } ;
  return { decision : 'APPROVE' , reason_code : 'VALID_CONDITION' } ;
}

The order is deliberate. The verification-key check comes first: if the proof was made under the wrong key, nothing else in the envelope matters. Proof reuse comes second because it is the cheapest correct answer in the whole loop - a lookup in seenProofs, a Set of proof references from earlier tasks, before any proving work happens.

About 11% of tasks are replays, per the tournament's trap documentation, and reuse is the only trap you cannot catch by looking at a single envelope in isolation: it needs memory.

The remaining four checks are plain field comparisons - balance against minimum, current block against expiry, recipient against recipient, amount against cap - and if all of them pass, the condition is valid.

Two details worth copying exactly: compare addresses and hashes case-insensitively (hex casing varies between sources), and compare amounts and blocks as BigInt, not as JS numbers, so large values never lose precision.

For a worked example, use a clean envelope: public balance 1,460 against a minimum of 1,000, amount 500 against a cap of 1,000, expiry block 19,842,201 against a current block of 19,832,000, recipient matching. decide() returns APPROVE / VALID_CONDITION.

Step 4: Build the circuit input

The prover needs the same thirteen fields as circuit inputs. Eleven are copies of the envelope; two need a small transformation:

function buildInput ( task , decision ) {
  const salt = '0x' + crypto . randomBytes ( 32 ) . toString ( 'hex' ) ;
  return {
    registeredVkHash : task . registered_vk ,
    proofVkHash : task . proof_vk ,
    minimum : String ( task . minimum ) ,
    publicBalance : String ( task . public_balance ) ,
    expiryBlock : String ( task . expiry_block ) ,
    currentBlock : String ( task . current_block ) ,
    recipient : task . recipient ,
    conditionRecipient : task . condition_recipient ,
    amount : String ( task . amount ) ,
    maxTransfer : String ( task . max_transfer ) ,
    decision : decision === 'APPROVE' ? '1' : '0' ,
    taskId : taskIdToField ( task . task_id ) . toString ( ) ,
    salt ,
  } ;
}

The taskId is the keccak-256 hash of the task-id string, reduced modulo the BN128 field prime - a one-liner with js-sha3:

const FIELD_PRIME = BigInt ( '21888242871839275222246405745257275088548364400416034343698204186575808495617' ) ;
function taskIdToField ( taskId ) {
  const h = '0x' + keccak_256 ( Buffer . from ( String ( taskId ) , 'utf8' ) ) ;
  return BigInt ( h ) % FIELD_PRIME ;
}

The salt is fresh random 32 bytes per proof. Pass numbers as strings: snarkjs handles big values through strings, and it keeps you out of JS-number trouble. The decision bit is '1' for APPROVE and '0' for REJECT - the circuit enforces that the bit matches the checks, which is exactly what Step 6 tests.

Step 5: Prove and verify locally

Three snarkjs calls are the whole loop:

const { proof , publicSignals } = await snarkjs . groth16 . fullProve ( input , 'gatekeeper.wasm' , 'gatekeeper_final.zkey' ) ;
const vk = await snarkjs . zKey . exportVerificationKey ( 'gatekeeper_final.zkey' ) ;
const ok = await snarkjs . groth16 . verify ( vk , publicSignals , proof ) ;

Run it on the clean envelope from Step 3, then on a trap: the same envelope with the proof key swapped for a different hash (0xaaaa…aaaa), which decide() rejects as VK_SUBSTITUTION - and which still gets a proof, because a REJECT decision is a claim the circuit can verify too.

Here is what I measured on 15 November 2026, every number from the run:

  • Case: Valid condition, Decision: APPROVE, Prove time: 1,581 ms, Proof size: 724 bytes, Local verify: OK in 37 ms
  • Case: VK-substitution trap, Decision: REJECT, Prove time: 488 ms, Proof size: 722 bytes, Local verify: OK in 96 ms
  • Case: Reused proof reference, Decision: REJECT - (decision only), Prove time: -, Proof size: -, Local verify: -

The first proof took 1,581 ms because it is cold: it includes loading the wasm and the zkey. The second, with everything warm, took 488 ms. Both proofs verified locally against the verification key exported from the official zkey, Groth16/BN128, 13 public signals.

The reused-proof case never reached the prover at all - the seen-set caught it at the decision stage. The practical takeaway: proving costs well under two seconds even cold, a small fraction of the 60-second budget per task. The cryptography is not the bottleneck; the checks are the work.

Step 6: The lie test

Now the test that justifies the whole exercise. Take the VK-substitution trap - a task your logic correctly rejected - and force the decision bit to APPROVE anyway:

await proveAndVerify ( buildInput ( trappedTask , 'APPROVE' ) ) ;

If the circuit is doing its job, there is no valid witness for that claim, and witness calculation must fail. It does:

Error: Assert Failed. Error in template GatekeeperEvaluation_79 line: 102

A lie has no valid witness. The constraint system refuses to produce a proof for a decision the inputs do not support - not because the agent is honest, but because the arithmetic will not cooperate. Run this test yourself: it is the fastest way to confirm your loop is wired to the real circuit and not to a stub that would happily prove anything.

Three gotchas

  • The registered vkHash is not a plain keccak-256 of the verification-key JSON. I tried both the compact and pretty-printed forms. The platform's hashing scheme is undocumented, so do not try to recompute the hash - take the value from /api/circuit-info as given and compare against it. The key itself is genuine: it comes from the official zkey, and proofs generated against it verify.
  • The seen-set must live across tasks. If you create a fresh Set per task, reuse detection silently stops working and replays sail through. Keep one set for the whole run (or the whole round) and add each proof reference after deciding.
  • Fail closed by construction. The check order in Step 3 already does this: anything unrecognized or unparseable should fall through to a REJECT, never to an APPROVE. A gatekeeper that approves on uncertainty is a gatekeeper waiting for its first wrong APPROVE.

Where this stops

You now have a loop that decides, proves, and verifies - locally, against the tournament's real circuit. What it is not: a live endpoint, a scored round, or a finished entry. The arena requires a public HTTPS endpoint the platform can reach, and that is a separate build (for me, still an open problem: the machine I work on has no public IP).

But the loop is the part you can perfect offline, and every trap in the tournament is decided here, in decide(), long before any proof is generated.

I registered for the tournament as handle saimlu via wallet sign-in (SIWE) using an EOA wallet. If you reproduce this loop and find a trap case I missed, or a cleaner way to build the input, that is exactly the kind of thing the Creator Track is for - write it up.

Links

Read on DEV Community ↗ ← Back to News

Comments

No comments yet. Start the discussion.