SkillOS

1# SkillOS
2 
3> Skill economy infrastructure for the agent era.
4 
5Verified human + agent skill arena protocol. Phase 1 testnet is live on Base Sepolia: six games, on-chain tournament settlement, three AI features, and permissionless sponsor-funded prize pools. Pure infrastructure — no custody, no protocol-level KYC, sweepstakes-safe at the storage layer.
6 
7> Brand evolution: the public-facing rebrand to **SkillOS** is queued for the Phase 2 mainnet cutover window.
8 
9The marketing site (`https://www.skillos.games`) lives in a **separate repo** — `skillos-apex` — and is not part of this monorepo.
10 
11## Overview
12 
13SkillOS is a 5-actor protocol:
14 
15- **Players** compete in daily skill tournaments and earn USDC from sponsor-funded prize pools. Free first entry, optional retry fees.
16- **Developers** plug into the tournament framework and AI features to ship skill games without infra overhead. Public SDK is Phase 2 (see below).
17- **SkillOS** runs the substrate: cron-driven tournament create + settle, attestation signer, anti-cheat review pipeline.
18- **Sponsors** fund prize pools permissionlessly via `SponsorshipModule`. Soulbound `SponsorReceipt` (ERC-5192) issued per sponsorship.
19- **AI Labs** access anti-cheat-verified decision sequences via x402 per-call settlement (no subscription tier).
20 
21Architectural invariants — non-negotiable, see [`CLAUDE.md`](./CLAUDE.md) for the full list:
22 
231. **Storage-segregated sweepstakes safety.** Retry fees and prize pools live on separate slots in `TournamentPool`. Foundation treasury never funds prize pools. A buggy module physically cannot corrupt segregated accumulators.
242. **Class-agnostic protocol.** Humans and agents compete on the same arena. The storage layer does not differentiate player class.
253. **`trustedSigner` attestation.** Phase 1 reality. Decentralizes through Phase 5.
264. **Cron is the only tournament-state writer.** Manual settle paths exist only as ops break-glass.
275. **AI is fire-on-mount, not blocking.** Tournament settlement never depends on AI availability.
28 
29## Repository structure
30 
31```
32apps/
33  2048           — reference implementation; hosts public x402 endpoints
34  wordle, sudoku, minesweeper, clicker, match3
35                 — solo-tournament flow, mirror 2048 architecture
36  sponsor        — permissionless prize-pool funding dashboard
37 
38packages/
39  ai-coach       — Claude prompt library (Coach / Recap / Anti-Cheat per-game)
40  contracts      — ABIs + addresses + game-slug helpers (re-exports from /contracts/out)
41  duel-backend   — solo + duel API handlers, settle, settle-guard, cron
42  game-types     — shared TypeScript types (Duel state, status enums)
43  lib-shared     — Supabase client, http helpers, attestation, RPC utilities
44  sp-engine      — Skill Points calculation engine
45  ui             — design system + shared components
46 
47contracts/       — Foundry workspace (Solidity 0.8.26)
48  src/           — Solidity sources
49  test/          — Foundry tests (extend the settle-guard tripwire pattern)
50  lib/           — vendored deps (openzeppelin-contracts, forge-std)
51  deployments/   — chain deploy artifacts (e.g. sponsor-stack-base-sepolia.json)
52 
53supabase/migrations/     — Postgres migration files (forward-only)
54docs/                    — sponsor-flow.md, audit/, superpowers/
55reports/                 — point-in-time audits
56scripts/                 — backfill-sp, jury-tournaments seed, x402-smoke
57 
58@skillos/sdk           — planned Phase 2 public release. Not yet scaffolded on disk;
59                           do not import from this name yet.
60```
61 
62## The six games
63 
642048 · Wordle · Sudoku · Minesweeper · Clicker · Match3
65 
66Each lives at `<game>.skillos.games`. 2048 is the reference implementation and currently hosts the public x402 endpoints; the other five mirror its solo-tournament flow.
67 
68## AI features (live across all six games)
69 
70| Feature | Role | Model |
71|---|---|---|
72| AI Coach | Post-match tactical feedback | Claude Sonnet 4.6 |
73| AI Recap | Match summary | Claude Haiku 4.5 |
74| AI Anti-Cheat | Server-side plausibility check on submit | Claude Haiku 4.5 |
75 
76Generation lives in `packages/ai-coach`. Per-flow handlers live in `packages/duel-backend/src/api`. AI is exposed via per-app routes at `/api/tournaments/solo/[runId]/{coach,recap,plausibility}` and POSTed from the result-page mount, not from the submission path. AI prompt formulations and anti-cheat detection methods are intentionally not documented in this README — see `packages/ai-coach` source.
77 
78## Smart contracts (Phase 1, Base Sepolia)
79 
80Foundry workspace at `/contracts/`. Solidity 0.8.26, optimizer 200 runs, no via_ir. Chain ID 84532.
81 
82Deployed v2.1 stack (April 29, 2026). Authoritative addresses live in [`contracts/deployments/sponsor-stack-base-sepolia.json`](contracts/deployments/sponsor-stack-base-sepolia.json):
83 
84| Contract | Address | Notes |
85|---|---|---|
86| `TournamentPool` v2.1 | `0x52049b812780134d2F69D6c20C2ef881D49702da` | Prize pool escrow, retry-fee collection, settlement (storage-segregated) |
87| `SponsorshipModule` | `0xD76670adB574A4C8D06dfF47127e7143d780ff87` | Permissionless prize-pool funding |
88| `SponsorReceiptSBT` | `0xCCC183c72D666A16E03bf38E8c2DFa8a68b2e768` | Soulbound receipt, ERC-5192 |
89| `MockSanctionsOracle` | `0x0CB38F0A0511aF07FC34A20DCaB9e2Fc8061B1CC` | Pre-tx sanctions screen (mock; mainnet-gated swap) |
90 
91Verification: all four contracts verified on **Blockscout** (`https://base-sepolia.blockscout.com/`). Etherscan V2 API previously rejected bytecode-identical compilations; the deployment artifact records the switch.
92 
93Other Solidity sources in-tree (not part of the deployed v2.1 stack): `ChallengeEscrow.sol` (async-duel stake escrow, currently paused), `SkillbaseAnchor.sol` (daily SP-ledger snapshot anchor), `ArcadePool.sol`.
94 
95ABIs and address constants are exported from `@skillos/contracts`.
96 
97**Tests:** 156 Foundry tests passing across 6 test suites (`forge test`). The settle-guard suite is the tripwire for the storage-segregation invariant — extend, don't skip.
98 
99**v2.2 (Phase 2):** developer fee splitter with on-chain 70/30 enforcement and a Foundry invariant test for accumulator reconciliation. Full spec deferred to `docs/adr/0001-v22-fee-splitter.md` when the ADR system activates in Phase 2 — implementation details will follow contract auditor consultation. Mainnet deployment is audit-gated; see Phase 2 below.
100 
101## Architecture
102 
103**Economic flows (Phase 1).** 1 USDC retry fees split 70/30 dev/platform (off-chain accounting in Phase 1; moves on-chain in v2.2). Permissionless sponsor funding routes directly into segregated prize-pool slots via `SponsorshipModule`. AI-lab data licensing settles per-call via x402 micropayments — no subscription tier.
104 
105**On-chain.** See [Smart contracts](#smart-contracts-phase-1-base-sepolia) above.
106 
107**Off-chain.** Next.js App Router on Vercel + Postgres on Supabase.
108 
109- Each app is a separate Next.js project deployed independently to its own Vercel project under scope `simpl3s-projects`. Shared code lives in `/packages`. Turborepo 2.3.3 orchestrates dev/build/lint/typecheck across the workspace.
110- Per-app `/api/cron/*` routes drive tournament create + settle (signed by `STUDIO_PRIVATE_KEY`, gated on `CRON_SECRET`). Cron is the only writer of tournament state.
111- Solo runs flow through `/api/tournaments/solo/[runId]/{coach,recap,plausibility}`. AI is fire-on-mount — Coach/Recap components POST only when the result page is viewed.
112- Sponsor app (`apps/sponsor`) is the dashboard for prize-pool funding; it indexes `SponsorshipModule` events via a daily cron.
113 
114## Phase roadmap
115 
116Two numbering systems coexist in the codebase: a **product roadmap** (Phase 1 → 5, this section) and **engineering-internal contract versions** (v2.0 → v2.1 → v2.2, Smart Contracts section above). Don't reconcile — the audiences differ. See [`CLAUDE.md`](./CLAUDE.md#two-phase-numbering-systems).
117 
118- **Phase 1 — Shipped (now).** Testnet on Base Sepolia. Six games, three AI features, on-chain tournament settlement, permissionless sponsor MVP, Blockscout-verified v2.1 stack.
119- **Phase 2 — Mainnet activation (H2 2026, audit-gated).** v2.2 developer fee splitter (on-chain 70/30), `@skillos/sdk` public release, agent player-class API, SkillOS rebrand cutover, sponsor onboarding pipeline. Mainnet contingent on sweepstakes legal review. Public timeline tracks apex (`skillos-apex`); internal sprints may target tighter dates.
120- **Phase 3+ (achievement-gated).** Dispute layer, Emergency Games Fund, ad revenue.
121- **Phase 4+ (achievement-gated, optional).** Substrate-maturity-gated decisions including potential governance token + opt-in data tokenization. Triggers: sustained adoption + regulatory clarity (Howey/MiCA) + organic economy maturity + lawyer review. The SP system can remain off-chain accounting indefinitely if the platform doesn't warrant tokenization. Optionality > obligation.
122- **Phase 5 (vision).** Substrate intelligence — native AI oracle, foundation models trained on anti-cheat-verified decision data.
123 
124**Deferred to Phase 2 v2.2 mainnet cutover:**
125- Existing `@skillos/*` package names remain locked until v2.2 deploy + Vercel project rename + DNS migration
126- Future packages (e.g., `@skillos/sdk`) will be minted directly under the new namespace at publication time
127- Live `*.skillos.games` URLs locked until DNS cutover
128- `SkillbaseAnchor.sol` and other contract identifier renames locked until v2.2 deploy
129- `apps/2048` x402 paid-API response strings (`via-skillbase` → `via-skillos`) flip with route handler changes
130 
131## Development setup
132 
133**Requirements:**
134- Node.js ≥ 20.0.0
135- npm ≥ 10.0.0 (workspaces)
136- Foundry (for contract work) — `forge`, `cast`, `anvil`
137- Supabase project (URL + service-role key) for database-backed flows
138 
139**Install + dev:**
140 
141```bash
142npm install                                # workspace install (all apps + packages)
143npm run dev                                # turbo runs every app in parallel
144npm run dev:2048                           # 2048 only (convenience alias)
145npm run dev -w @skillos/app-wordle       # any other game
146```
147 
148Health check (any app, after `dev`): `http://localhost:3000/api/health`.
149 
150**Environment variables.** Each app has its own `.env.local.example` — there is no root-level template. Copy per app:
151 
152```bash
153cp apps/2048/.env.local.example apps/2048/.env.local
154# repeat for each app you intend to run
155cp contracts/.env.example contracts/.env   # Foundry RPC + signer
156```
157 
158Required keys (per app, see each `.env.local.example` for the canonical list): Supabase URL + service-role key, `STUDIO_PRIVATE_KEY`, `CRON_SECRET`, CDP / x402 facilitator keys (2048 only).
159 
160**Foundry tests:**
161 
162```bash
163cd contracts
164forge test                                 # 156 tests, 6 suites
165forge test --match-contract TournamentPool # focused suite
166```
167 
168**Database (Supabase).** Migrations are forward-only and live in `supabase/migrations/` (currently 11 files, `v2_*.sql` lineage starting 2026-04-21). Apply via the Supabase REST API or `supabase db push`.
169 
170**Vercel deployment.** Each app is its own Vercel project; install/build commands are pinned via per-app `vercel.json` (Vercel UI parsing has historically truncated workspace-relative install commands — do not rely on the dashboard for these). See [`CLAUDE.md`](./CLAUDE.md#vercel-push-gating) for the canonical git author identity required for pushes to Vercel-linked branches.
171 
172**No CI today.** `.github/workflows/` does not exist. PR checks are honor-system in Phase 1; required typecheck + lint + Foundry test gates land with the Phase 2 discipline transition.
173 
174## Engineering principles
175 
1761. **Sweepstakes safety > everything.** Storage-layer invariant, non-negotiable. Any change risking it requires explicit founder discussion before merge.
1772. **Sponsor-funded prize pools only.** Enforced on-chain.
1783. **Class-agnostic protocol.** Storage doesn't differentiate human vs. agent player class.
1794. **Honest framing > overclaim.** Pitch what's shipped; signal what's roadmap; never promise unconditional tokens.
1805. **CLI/MCP first.** Use `vercel`, `gh`, `cast`, `forge`, `supabase`, `npm` over dashboard manual work.
1816. **Phase 2 discipline (transitioning):** direct-to-main BANNED, branch + PR + review mandatory, ADR docs (`docs/adr/`) for major decisions, pre-commit hooks (typecheck + secret scan), integration test expansion.
182 
183See [`CLAUDE.md`](./CLAUDE.md) for the full operational playbook.
184 
185## License
186 
187Currently private. License decisions deferred to the Phase 2 mainnet / SDK launch window.
188 
189## Live endpoints + proof
190 
191- Production sponsor app: <https://sponsor.skillos.games>
192- 2048 game + x402 public APIs: <https://2048.skillos.games>
193- x402 endpoints (Base Sepolia, CDP facilitator): docs at [`apps/2048/src/app/api/public/README.md`](apps/2048/src/app/api/public/README.md), live tx proof at [`reports/x402-live-proof.md`](reports/x402-live-proof.md).
194 
195## Reference docs
196 
197- [`CLAUDE.md`](./CLAUDE.md) — agent-operational guidance, architectural invariants, decision priority order
198- [`docs/sponsor-flow.md`](docs/sponsor-flow.md) — sponsorship architecture, sanctions oracle, end-user flow
199- [`docs/superpowers/specs/2026-04-21-skillbase-v2-backend-design.md`](docs/superpowers/specs/2026-04-21-skillbase-v2-backend-design.md) — V2 backend spec (locked)
200- [`docs/audit/task-10-v2-cutover/README.md`](docs/audit/task-10-v2-cutover/README.md) — V2 cutover reconciliation
201- [`reports/codebase-hygiene-20260424-1532.md`](reports/codebase-hygiene-20260424-1532.md) — pre-submission code audit (categories A–L)
202 
203## Links
204 
205- Live: <https://www.skillos.games>
206- Sponsor app: <https://sponsor.skillos.games>
207- Game examples: <https://2048.skillos.games>, <https://wordle.skillos.games>
208- X / Twitter: [@SkillOS](https://x.com/SkillOS)
209- Telegram: <https://t.me/Skill_OS>
210