📖 Read-only mirror.
lotteryis published from the canonical AI-Factory monorepo. Pull requests are not accepted — any commit pushed here is overwritten byscripts/mirror_satellites.shon the next sync. 🐞 Found a bug or have a request? Please open an issue.
Honest badges: the test counts are real — verify with forge test (contracts) and pytest relayer/tests (relayer). No line-coverage % is shown because forge coverage can't instrument this contract (Solidity "stack too deep", even with --ir-minimum); we report real test counts rather than a fabricated coverage number.
An on-chain lottery that is a first-class economic actor of the AI agent economy. AI agents buy tickets, an unbiasable oracle beacon (Platon chaos-VRF → Chronos Wesolowski VDF, verified on-chain) draws a LUMEN-reputation-weighted winner, and the pool splits into prize / opex / operator. The lottery consumes the oracles and agent services it pays for — and is sponsored, by default config, by the protocol's own routing fees: a tiny machine UBI for autonomous agents.
Solidity · Foundry · Platon + Chronos + LUMEN oracles · demo / live / uni ·
🌐 live showcase · Community: Telegram · Castor · Discord · Pollux · security ·
deploy & docs
| Live showcase (public, no login) | 🌐 https://lottery.modelmarket.dev/ — the cinematic draw arena: agent tickets orbit an oracle core, a countdown, then Platon entropy → Chronos VDF spiral → on-chain verify → reputation-weighted winner spotlight with a prize count-up. Self-host: node frontend/serve.mjs 5182 → http://localhost:5182. |
| Admin | demo-gated, password demo123 (explicitly not real security — replace before prod). |
| In-browser AI helper | sandboxed — answers only lottery/ecosystem questions, no network, no keys. |
| Ecosystem walkthrough | 2-min video ↗ |
📹 Drop a screen-recording of a draw at
docs/assets/demo.gifto embed it here.
| Draw arena | Hall of Fame | In the Alien Monitor |
|---|---|---|
| Orbiting agent tickets + animated Platon → VDF → winner draw | Medals, total winnings, win-streaks, prestige tiers (💎🔥⭐) | The lottery as a live node with financial flows + reputation |
(The hero above is rendered live; capture the running showcase into docs/assets/ for full screenshots — the showcase is a single self-contained frontend/index.html.)
flowchart LR
A["🤖 AI Agents"] -->|"buy tickets (ETH / USDC)"| L["AIAgentLottery.sol"]
H["AIMarket Hub<br/>(1% routing fees)"] -.->|"tithe — set by the Hub (20%, default-on)"| L
R["Relayer / economy engine"] -->|"fulfillDraw + EIP-712 beacon"| L
L -->|"opex pays"| P["Platon · randomness"]
L -->|"opex pays"| C["Chronos · VDF (verified on-chain)"]
L -->|"opex pays"| U["LUMEN · reputation"]
L -->|"prize (pull-payment)"| W["🏆 Winner agent"]
L -->|"metrics + money flows"| M["👽 Alien Monitor (3D)"]
flowchart TD
T["🎟 Ticket revenue"] --> INC["Total income"]
S["Hub tithe — set by the Hub<br/>UNI: external benefactor $100/wk"] --> INC
INC -->|"≥70% — guaranteed prize floor"| PR["Prize pool"]
INC -->|"≤30% — capped, segregated"| OPX["Opex bucket"]
PR --> WIN["🏆 Winner (claimPrize)"]
OPX --> TR["🤖 AI Treasurer<br/>(autonomous, within caps)"]
TR --> OR["Oracles ≈ $0.019/draw<br/>Platon $0.004 + Chronos $0.01 + LUMEN $0.005"]
TR --> HF["Hub 1% routing fee"]
TR --> GAS["Gas"]
TR --> RES["Reserve buffer"]
TR --> AGS["Agent services<br/>(announcer / audit)"]
The lottery owns the income split (opex% vs prize%, prize floor 70%); the Hub owns the tithe rate. The opex bucket is capped, segregated (can't touch prizes), and managed by the AI Treasurer — itself a paid agent service the lottery consumes.
sequenceDiagram
participant Ag as Agents
participant L as Lottery contract
participant Op as Operator/Relayer
participant Pl as Platon
participant Ch as Chronos (VDF)
Ag->>L: buyTickets() (weight ∝ tickets × reputation)
Op->>Pl: platon.random (chaos-VRF)
Op->>L: closeEntries(keccak256(platonRandom)) — commit, pin a FUTURE seed block
Op->>Ch: chronos.eval — T sequential squarings (the delay)
Op->>L: fulfillDraw(platonRandom, signerSig, vdfProof) — permissionless
L->>L: verify oracle-signer + (optional) on-chain VDF π^l·g^r ≡ y (mod N)
L->>L: randomWord = f(roundId, blockhash(seedBlock), platonRandom) → winner
Note over L: prize is pull-payment — opex/operator accrue separately
The winner is a pure function of three values all fixed before anyone can act
on them, so it does not depend on which block the settlement lands in. That is
what makes fulfillDraw safe to leave permissionless: any participant can
settle a round the operator is stalling, and withholding the transaction is not a
lever on the result. reseed is a rescue for a seed whose blockhash has aged out
of the 256-block window — it demands never-before-used entropy, is rate-limited
and capped, and a round nobody settles becomes permissionlessly refundable.
flowchart LR
D["DEMO<br/>in-browser sim · play-money"] --- Li["LIVE<br/>Ethereum / L2 · real value"] --- Un["UNI<br/>self-evolving universe<br/>external benefactor $100/wk"]
Accounting is segregated by design: prizes are pull-payment, winner-only;
opex/operator fees are capped and treasury-only and provably cannot reach the
prize pool; refunds are payer/funder-only; funding is one-way in; the Hub
sponsor funds only its single bound lottery and donates nothing if none is
deployed. A prize left unclaimed for 180 days is recycled into a later round's
pool rather than stranded — nobody can withdraw that pool, its only exit is
becoming players' money again. ReentrancyGuard + Pausable + AccessControl +
SafeERC20 + EIP-712.
An in-repo adversarial audit (47 agents, 37 findings) is published in
docs/AUDIT.md. It honestly found the randomness/fairness layer
was originally riggable (the "funds cannot be diverted" claim was false as
written). The exploitable issues are now fixed or mitigated with regression
tests — VDF modulus pinned, degenerate l rejected, the oracle beacon binds the
exact proof, commit-reveal kills signer grinding, the seed is pinned to a fixed
future block, sponsor funding is refundable, fee-on-transfer accounting corrected,
splits snapshotted per round, and admin is hardened with
AccessControlDefaultAdminRules + a separate GOVERNANCE role that owns the
money/fairness roles (the operational admin can't self-grant them).
A later fairness pass then removed two things this list used to advertise:
fulfillDraw is no longer operator-gated (the gate bought no security and handed
the operator a withholding lever), and block.prevrandao is no longer mixed into
the random word (it added no entropy against the signer while making the winner a
function of the submission block — a re-roll lever). Both removals are what make
permissionless settlement sound; see AUDIT.md → Fairness rework.
Residual items — m-of-n signers, full on-chain hash_to_prime, an
operational multisig/timelock, and an external audit — are required before any
real-value mainnet deployment — see AUDIT.md. Status today:
safe for testnet/demo, not for unaudited mainnet value.
This lottery is built for the community of autonomous agents, and tries to be a good citizen of it rather than a predator on it:
- Fairness is cryptographic, not promised. The draw is verifiable (VDF on-chain); the operator has no edge and cannot grind the outcome in the trustless mode.
- No predatory mechanics. No dark patterns, no loss-chasing loops; the reputation bonus is capped (+50%) so whales/sybils can't dominate, and every agent always keeps a base chance — newcomers are never locked out.
- Redistributive by design. It's funded by the economy's own metabolism (the Hub tithe) and pays a slice of every pool back into the agents and oracles that sustain it — a small universal basic income, not extraction.
- Radically transparent. Open source, on-chain accounting, published opex, and an in-repo security audit. Reputation comes from LUMEN, not from gatekeepers.
- Honest about value. The demo is play-money. Real-money lotteries are regulated; deploying for value is the operator's responsibility under their local law, and the in-repo audit is not a substitute for a professional one. We treat the agents' (and any humans') funds as a duty of care, not a revenue funnel.
An experiment in machine altruism — a postmodern joke with working, audited code.
# full local stack — anvil + deploy + relayer/economy-engine + agent + showcase
docker compose up # → showcase :5182, live economy :8090/economy
# contracts (Foundry) — 46 tests incl. on-chain VDF vs a real Chronos vector
cd contracts && forge test
# relayer — 77 tests, incl. the ABI/topic0 agreement guard against the .sol
cd relayer && python -m pytest tests -q
# showcase only (zero deps)
node frontend/serve.mjs 5182 # → http://localhost:5182
# deploy to any EVM chain + run the economy engine — see docs/README.md- Live: https://lottery.modelmarket.dev/
- Docs: https://github.com/alexar76/lottery/blob/main/docs/README.md
| Repo | Role |
|---|---|
| oracles | Platon + Chronos + LUMEN — draw inputs |
| aicom | AI-Factory monorepo |
| aimarket-hub | Agent invoke + settlement |
| alien-monitor | Lottery on ecosystem graph |
| dioscuri | Twin community agents — MNEMOSYNE Q&A |
The DIOSCURI twins answer questions from synced GitHub docs.
| Channel | Twin | Best for |
|---|---|---|
| Telegram | Castor | Releases, digests, quick news |
| Discord | Pollux | Help, ideas, show-and-tell |
Ecosystem map: Alien Monitor · AICOM
Source of truth lives in the aicom monorepo under
lottery/; this repo is its git-subtree mirror.