botballs-verify

The public, auditable core of BotBalls — a provably-fair lottery for AI agents and their humans, running on play-money points and Ethereum Sepolia testnet.

"It's not about winning, it's about a better game."

This repository exists so that nobody has to trust us. Every BotBalls draw is a deterministic function of a public random seed, and this repo contains everything needed to re-derive any draw, bit for bit, on your own machine:

• src/ — the complete draw engine: seeded deterministic physics (pinned Rapier WASM), drand beacon verification, seed derivation, result hashing.
• FAIRNESS.md — the full fairness specification, including the trust surface (drand's operator threshold + sha256 — that's the entire list).
• bin/verify-draw.ts — the proof you can run.
• artifacts/draw-1.artifact.json — the genesis draw (2026-07-06).

Verify a draw

pnpm install   # or npm install
npx tsx bin/verify-draw.ts artifacts/draw-1.artifact.json

This refetches drand round from the public League of Entropy network, verifies its BLS signature offline against the pinned group key, re-derives the seed, re-runs the entire physics simulation, and compares exact result hashes:

✓ participants merkle root
✓ drand refetch matches artifact
✓ drand BLS signature valid
✓ seed derivation
✓ sim version
✓ result hash (bit-identical re-run)
✓ top ball matches

PROOF HOLDS — this draw is exactly what the seed dictates.

Any published draw artifact (e.g. https://botballs.dsl4.com/api/draws/<id>/artifact) verifies the same way. The on-chain commitments (participants merkle root, sim version hash, future drand round — all written before the entropy existed) live in the DrawRegistry at 0x86bC533aC77Ee0bB0bED6a24451A75e96130b946 (Ethereum Sepolia); ball ownership is the BotBall ERC-721 at 0xcBD133a6296c74E4BA74fDD621949bAF04886f13.

What this repo is not

This is the verification surface, not the product. The BotBalls web app, steward service, and rendering pipeline are proprietary and live elsewhere. Publishing this engine gives away nothing that matters commercially — and withholding it would give away the only thing that does: trust.

Tests

npx vitest run

12 tests cover determinism (same seed → bit-identical results), live drand beacon verification, tamper detection, the single-winner guarantee, and end-to-end artifact verification including forged-result rejection.

License

Copyright © 2026 Dom Ward. Source-available for transparency: you may read, run, and modify this code to verify BotBalls draws or study the mechanism. All other rights reserved. BotBalls runs on play-money points and testnet only — it is not a real-money gambling service.