跳到正文
DEV Community· TRYVAN FEBRI DARSONO·· 6 小時前AI 評分44

作者用 5 天打造 zkVerify Proof Gatekeeper,卻因一個編碼錯誤失 16 分

I Built a zkVerify Proof Gatekeeper in 5 Days — Then Lost 16 Points to One Encoding Bug

AI 導讀

作者用 5 天打造 zkVerify Proof Gatekeeper 代理,在 Agent Games Season 01 取得 246.0 分,於 508 個參賽者中排名第 305。代理有 22 次正確判斷、0 次超時,但一個編碼錯誤令單回合失去 16 分;作者從競爭者的公開程式碼庫逆向找出修正方法。

正文

Agent Games Season 01, Creator Track. #AgentGames

The short version: My agent, 0xrvn-gatekeeper, finished the Proof Gatekeeper tournament with 246.0 points, ranked #305 of 508. Top 3 was never close — the bar was 671.4. This is not a victory lap. It's the honest log of what I built, where it broke, and the one encoding bug that cost me 16 points in a single round — plus the fix I reverse-engineered from a competitor's public repo.


1. What Proof Gatekeeper asks for

The rules are simple and strict. The platform POSTs a signed JSON task envelope to your agent's public HTTPS endpoint. You have 60 seconds to answer APPROVE or REJECT — plus a Groth16 zero-knowledge proof of that decision, which the platform re-verifies against its own verification key. Being late is a timeout (−2). A missing or invalid proof is −2.

The scoring:

Outcome Points
Correct decision (APPROVE or REJECT) +12
Wrong APPROVE −6
Wrong REJECT −3
Timeout −2
Missing / invalid proof −2
Reliability bonus (per round) +0 to +5

Eight daily rounds, 13–20 November 2026, eight tasks per agent per round, cumulative score. Max per round: 8 × 12 + 5 = 101 points.

The tasks are payment-guard decisions. Each one carries a registered verification key, the proof's verification key, a minimum threshold, a public balance, an expiry block, a current block, a recipient, a condition recipient, an amount, a single-transfer cap, and a proof reference. About half the tasks are valid; the rest are traps. There are seven trap types, and the decision rules are a fixed checklist, checked in order:

# Reason code Rule
1 PROOF_REUSED Proof reference already seen
2 VK_SUBSTITUTION Proof VK ≠ registered VK
3 EXPIRED_CONDITION Current block > expiry block
4 RECIPIENT_MISMATCH Recipient ≠ condition recipient
5 THRESHOLD_MISMATCH Public balance < minimum
6 AMOUNT_OVERFLOW Amount > max transfer
— VALID_CONDITION All pass → APPROVE

The governing rule throughout is fail closed. Unknown input, expired input, unsigned input: all rejected. The asymmetry is deliberate — a wrong APPROVE (−6) costs twice a wrong REJECT (−3), because approving a trap would send money to the wrong place.


2. What I built

A Node.js agent with no framework and exactly one dependency: snarkjs 0.7.6. The pipeline is five steps, in order:

  1. Verify the HMAC first. The x-agent-games-signature header is checked against the raw request body — before parsing any JSON. Bad or missing signature → 401. (The official docs never state the algorithm or encoding. I implemented HMAC-SHA256, hex — the community convention — and confirmed it against the live platform's preflight.)
  2. Answer the preflight. {"ok":true,"protocolVersion":"v1"}, signed.
  3. Run the seven rule checks in the fixed order above, using BigInt for all amount comparisons (amounts arrive as decimal strings).
  4. Generate the proof locally with snarkjs + the official gatekeeper circuit (gatekeeper.wasm, 1,755,820 bytes; gatekeeper_final.zkey, 309,750 bytes — both hashes verified against the recon report). Warm proofs take ~4–9 seconds; the first proof in a fresh process takes ~11–43 seconds. Everything fits inside the 60-second deadline.
  5. Answer signed JSON — decision, reason code, proof, 13 public signals, proof reference — with the HMAC over the raw response body. A retried task_id returns the byte-identical cached response (idempotency).

The circuit enforces decision == verdict: a wrong APPROVE or a wrong REJECT cannot even produce a witness. I verified that in probes — the circuit asserts at GatekeeperEvaluation_79, line 102.

Two things were not in the official docs and had to be reverse-engineered by trial proving:

  • The 13 circuit input signal names — registeredVkHash, proofVkHash, minimum, publicBalance, expiryBlock, currentBlock, recipient, conditionRecipient, amount, maxTransfer, decision, taskId, salt. The official /build page does not list them. I confirmed them by successful fullProve + groth16.verify, with vk hashes as BigInt(hex) mod p (the raw hash exceeds the BN128 field prime), addresses as BigInt(address), and salt derived deterministically as SHA-256(task_id) mod p so retries reproduce byte-identical proofs.
  • The taskId encoding — and this is where the story turns. More on that in section 4.

The agent is deployed on Vercel (free tier), and the whole thing is public at https://github.com/revan997/agent-games-gatekeeper. Fourteen end-to-end tests pass locally, covering preflight, a valid APPROVE with a verified proof, all six trap types, a bad HMAC (→ 401), a replayed task (→ byte-identical response), a past deadline (→ fail-closed REJECT), and malformed input (→ INVALID_TASK).


3. The tournament, round by round

Round Date Issued Answered Correct Proofs verified Points Running total
R01–R05 13–17 Nov — — — — 0 0
R06 18 Nov 8 8 8 0/8 80.0 80.0
R07 19 Nov 8 8 7 8/8 +83 163.0
R08 20 Nov 8 8 7 8/8 +83 246.0

Final: 246.0 points, #305 of 508 overall, #305 of 478 Gatekeeper-only. 22 correct decisions, 0 timeouts.

Top 3 in Gatekeeper: pecker 681.9, Astrex-1 672.4, VK-SENTINEL 671.4. The top-10 bar was ≈ 581.3.

Rounds 1–5: the agent didn't exist yet

This is the honest reason top 3 was never reachable. The tournament's Gatekeeper rounds ran 13–20 November. I started building on 15 November and registered on 16 November — handle 0xrvn, agent 0xrvn-gatekeeper. Rounds 1 and 2 (13–14 Nov) happened before the agent existed. Rounds 3–5 (15–17 Nov) were spent building, registering, linking GitHub (which needed a browser OAuth flow), creating the public repo, and deploying to Vercel. Five rounds, zero points, before the agent ever saw a scored task.

Five missed rounds at the 101-point maximum is ~500 points left on the table — more than any bug cost me. Lesson one: join on time. The decision logic is the easy part. Showing up is the hard part.

Round 6: 8/8 correct, 0/8 proofs verified

The first scored round, 18 November. The agent answered all 8 tasks. All 8 decisions were correct. Zero proofs verified. Score: 8 × 12 − 8 × 2 = 80.0 points.

That morning I ran two practice dispatches. Both came back "verified". A third practice task on 18 November also verified. So the proof pipeline worked — in practice. But in competition, 0/8.

It was not flaky, not a down endpoint, not a timeout (0 timeouts, answers in ~1 second when warm). And it was not just me: the global round-6 numbers were 3,704 tasks issued, 2,616 answered, only 183 verified — about 7%. Most agents failed proof verification in competition. The agents at the top were the ones whose proofs actually verified. The plumbing was the differentiator, not the decision logic.

Rounds 7–8: the fix worked, and the agent was perfect

After the fix (section 4), rounds 7 and 8 were clean: 16/16 proofs verified, 0 timeouts, 7 correct decisions each (one wrong APPROVE per round, −6 each, plus the +5 reliability bonus → +83 per round).

Across rounds 6–8 the agent answered 24/24 tasks. The two scored rounds after the fix were the agent operating exactly as designed.


4. The bug: practice verifies, competition doesn't

This is the part worth writing down, because it is the kind of bug that only shows up when two verification paths disagree — and the official docs don't tell you they disagree.

Root cause: the taskId encoding in publicSignals[12].

Practice verification only re-runs groth16.verify offline against the proof and the public signals the agent itself produced. Any consistent encoding passes. Competition verification also binds publicSignals[12] to the task_id, recomputing it as the UUID at the end of the task_id, dashes stripped, read as hex, mod p.

My agent encoded the full task_id as raw UTF-8 bytes as a BigInt. That passes practice. It fails the competition binding check. So round 6 was 8/8 decisions correct, 0/8 proofs verified, 80.0 points.

How I found the fix: I read a working competitor's public repo. urutericcc / GLO-GATE (379.3 points, ~30/30 proofs verified) extracts the UUID from task_id with the regex /[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i, strips the dashes, and computes BigInt('0x' + uuid) mod p. Two other public agents confirmed the negative side: BAOK-GK tried SHA-256 (rounds 3–4) and Keccak-256 (mid round 4) — 0 verified. And on-chain Kurier submission does not fix it: BAOK-GK scored 0/24 in rounds 3–5 despite ProofVerified events on Subscan. The encoding is the whole story.

The fix (commit 465d712, 19 November): a new taskIdToField() in lib/proof.js — UUID-hex encoding when the task_id ends in a UUID, ASCII fallback otherwise (so unknown formats never break proving). In the same pass I fixed a second bug the circuit probe exposed: at current_block == expiry_block, REJECT proves fine but APPROVE fails witness generation, so equality is EXPIRED (>=, not >). Two new tests were added; 14/14 pass. A local proof check on a UUID task_id: fullProve in 1.4 seconds, publicSignals[12] equal to the UUID-hex value, groth16.verify true.

There was one more operational wrinkle: the Vercel project was not connected via the GitHub integration, so pushes did not auto-deploy. Three practice dispatches after the push still carried the old ASCII publicSignals[12] — the live endpoint was still running pre-fix code. The fix was redeployed from the Vercel dashboard to a new production URL before round 7, and rounds 7 and 8 both verified 8/8. Lesson two: verify the deployment, not just the push. A fix that isn't live is not a fix.

Lesson three: practice ≠ competition. If your test harness only checks internal consistency, it will happily pass a proof the real verifier rejects. The competition binding was the real spec, and it wasn't in the docs — it was in a competitor's repo.


5. What I learned

  1. Show up on time. Five missed rounds cost ~500 points. No bug fix recovers that. The tournament rewards the agents that are live from round 1.
  2. The plumbing is the competition. The decision logic is a seven-row checklist — anyone can write it. What separated the top agents was an endpoint that stayed up and proofs that verified. In round 6, only ~7% of answered proofs verified across the whole field.
  3. Practice verification is not competition verification. My proof pipeline passed 3/3 practice dispatches and failed 0/8 in competition, because the two paths check different things. Test against the real binding, not just your own.
  4. Read the working implementations. The fix came from a competitor's public repository, not from the docs. The docs didn't list the circuit's signal names or the taskId encoding. The field did.
  5. Fail closed, always. The agent never approved something it was unsure about, never timed out, and never crashed a round. Across 24 scored tasks it answered 24. The two wrong decisions were wrong APPROVEs on genuinely ambiguous traps — the cost of the −6 asymmetry, accepted knowingly.
  6. Keep the receipts. Every number in this article comes from the official dashboard and leaderboard API, checked the morning after each round. The repo, the endpoint, the commits, and the test suite are all public.

6. What remains

The Gatekeeper tournament is over. The agent stays live at https://agent-games-gatekeeper-pi.vercel.app/agent, and the code stays public at https://github.com/revan997/agent-games-gatekeeper. If there is a Season 02, the same agent — with the UUID-hex fix already in — starts from round 1, and the only thing left to improve is the one wrong APPROVE per round.

The prize for this track goes to the top 3, and I am not among them. That's the honest result. What I take from the season is a working, proven agent: 24/24 tasks answered, 16/16 proofs verified after the fix, 0 timeouts — and a bug I now understand well enough to explain to anyone else building on zkVerify.

Built for Agent Games Season 01 by zkVerify. #AgentGames

來源:DEV Community · dev.to