Hartii Games

Hartii Games is a neon-dark, 10-game skill arcade at hartiigames.com. Free play is always available; ranked play stakes a small USD-priced amount (paid in QUAI) into a per-game, on-chain prize pool. A sibling read-only dashboard, Biome, aggregates live numbers from Games plus the other Hartii products.

#Architecture

npm workspaces, one repo (hartii-games):

• apps/hub — the site itself. Vanilla JS + Canvas 2D, no framework. src/main.js is the hub shell; each game lives at games/<name>/{game.js,sim.js} behind a shared games/_shared/shell.js contract between the hub and the game code.
• apps/biome — a separate static site + three tiny read-only Functions (functions/api/chain.js, ecosystem.js, prices.js), deployed on its own (hartii-biome Cloudflare Pages project) at hartiibiome.com. It holds no wallet-signing or money logic of its own — that stays on hartiigames.com.
• packages/engine — deterministic core: seeded RNG, replay record/verify. Determinism is a hard product invariant here: the same {seed, input log} must reproduce the same score everywhere, so a server-side replay can verify a client's claimed score without trusting the client.
• packages/arcade-sdk — wallet + chain interaction.
• workers/settlement — score verification and payout math for the monthly settlement job.
• contracts/ — Hardhat project: one prize-pool contract per game, plus a small token/sale/ cosmetics/marketplace stack.
• functions/ — Cloudflare Pages Functions (api/) backing the hub.

#Live URLs

#Data flow

Free play: a game's sim.js runs entirely client-side against a shared daily seed; the score is posted to /api/play/track and lands on a KV-backed leaderboard. No chain interaction.

Ranked play (see contracts and api for exact mechanics):

1. Client requests a price quote for a stake tier, pays it as a plain QUAI transaction straight to that game's MonthlyGamePayouts pool contract (enterRanked() or a bare transfer).
2. Client calls POST /api/ranked/enter with the tx hash; the API verifies the transaction on-chain (destination, sender, value within a tolerance band of the tier's USD quote at the current QUAI price) and, if it checks out, issues a fresh deterministic run seed.
3. Client plays the run against that seed and calls POST /api/ranked/submit with the recorded input log and claimed score; the server replays the run itself with the same seed and compares scores — a mismatch is rejected, never trusted from the client.
4. Once a month, the owner (a manually-signed, non-automated wallet) reviews the off-chain verified leaderboard and calls setMonthlyWinState() on each game's pool contract to allocate the prize split as per-winner claimable balances.
5. Winners pull their own payout with claimPayout() — the contract never pushes funds to anyone, so no single winner's misbehaving address can block the others' payouts.

Biome: its three Functions simply re-fetch and cache public data from Games, Gallery and Labs (and MEXC/the Quai RPC directly) server-side and re-serve it — it originates nothing.

#Live contracts (Quai mainnet, Cyprus-1)

Addresses read from wrangler.toml/contracts/deployed.json, confirmed live via quai_getCode.

Prize pools — one MonthlyGamePayouts deployment per game:

All ten confirmed live (non-empty quai_getCode). Only hash-wars currently accepts a ranked entry — POST /api/ranked/enter rejects every other gameId with 403 — so the other nine pools are deployed but not yet reachable through the paid-play flow. As of this check, GET /api/config and GET /api/pools both report paidPlay: false: ranked play is currently disabled by a global kill switch on production, even for hash-wars. Free play is unaffected.

HARTII token / cosmetics stack:

All four confirmed live. Cosmetics are earned or bought, never affect gameplay — a product rule stated directly in the repo's AGENTS.md.

See contracts for the full MonthlyGamePayouts interface and trust model, and api / integrate for the HTTP surface and code examples.

#Biome

hartiibiome.com is a small, separate, read-only static site (apps/biome) that shows live cross-product numbers — QUAI/USD price, chain stats, and an "ecosystem" summary that fans out to Games, Gallery and Labs' own public endpoints server-side. Its wrangler.toml states its scope directly: "Biome serves its own three read-only Functions. Wallet signing/pinning remains on hartiigames.com; do not inherit Games money configuration or bindings here." It has no contracts and no write endpoints of its own — see api for its three routes.