{"id":50520030,"url":"https://github.com/0800tim/tournamental","last_synced_at":"2026-06-03T03:07:43.058Z","repository":{"id":357349435,"uuid":"1233544924","full_name":"0800tim/tournamental","owner":"0800tim","description":"Tournamental — verified tournament prediction game + 3D match renderer (tournamental.com)","archived":false,"fork":false,"pushed_at":"2026-05-28T02:58:41.000Z","size":23840,"stargazers_count":1,"open_issues_count":16,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-05-28T03:23:17.444Z","etag":null,"topics":["betting","cryptography","prediction","prediction-model","sports","sports-analytics","sports-betting","sweepstakes"],"latest_commit_sha":null,"homepage":"https://tournamental.com","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/0800tim.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":".github/FUNDING.yml","license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":".github/CODEOWNERS","security":".github/security/network-allowlist.txt","support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":"AGENTS.md","dco":null,"cla":null},"funding":{"github":"0800tim","custom":["https://www.drips.network/app/projects/github/0800tim/tournamental"]}},"created_at":"2026-05-09T04:34:46.000Z","updated_at":"2026-05-28T02:58:55.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/0800tim/tournamental","commit_stats":null,"previous_names":["0800tim/tournamental"],"tags_count":1,"template":false,"template_full_name":null,"purl":"pkg:github/0800tim/tournamental","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/0800tim%2Ftournamental","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/0800tim%2Ftournamental/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/0800tim%2Ftournamental/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/0800tim%2Ftournamental/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/0800tim","download_url":"https://codeload.github.com/0800tim/tournamental/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/0800tim%2Ftournamental/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":33845858,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-06-03T02:00:06.370Z","response_time":59,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["betting","cryptography","prediction","prediction-model","sports","sports-analytics","sports-betting","sweepstakes"],"created_at":"2026-06-03T03:07:42.212Z","updated_at":"2026-06-03T03:07:43.053Z","avatar_url":"https://github.com/0800tim.png","language":"TypeScript","funding_links":["https://github.com/sponsors/0800tim","https://www.drips.network/app/projects/github/0800tim/tournamental"],"categories":[],"sub_categories":[],"readme":"# Tournamental\n\n[![License: Apache 2.0](https://img.shields.io/badge/License-Apache_2.0-blue.svg)](LICENSE)\n[![npm: @tournamental/bracket-engine](https://img.shields.io/npm/v/@tournamental/bracket-engine.svg?label=%40tournamental%2Fbracket-engine)](https://www.npmjs.com/package/@tournamental/bracket-engine)\n[![Open issues](https://img.shields.io/github/issues/0800tim/tournamental.svg)](https://github.com/0800tim/tournamental/issues)\n[![Last commit](https://img.shields.io/github/last-commit/0800tim/tournamental.svg)](https://github.com/0800tim/tournamental/commits/main)\n\u003c!-- TODO: replace https://discord.gg/tournamental with the finalised invite URL once it is reserved. See docs/55-public-launch-checklist.md. --\u003e\n[![Discord](https://img.shields.io/badge/discord-tournamental-5865F2.svg?logo=discord\u0026logoColor=white)](https://discord.gg/tournamental)\n\n\u003e **Predict the tournament. Beat the market. Prove it.**\n\u003e\n\u003e Tournamental is a live tournament prediction game with a 3D match-renderer watch-along, Telegram-bot identity, blockchain-verified prediction receipts, and a long-term reputation network, all on a write-once / serve-via-CDN architecture so a million viewers cost the same as ten. Open source under Apache 2.0, brand and treasury held by the Tournamental operating company, contributor revenue streamed via the Drips Network.\n\nDomain: **tournamental.com**. Brand expansion when needed: **Tournamental, Verified Tournament Oracle Network**.\n\n## What just shipped\n\n- **npm packages live** under [`@tournamental/*`](https://www.npmjs.com/search?q=%40tournamental) -- `spec`, `bracket-engine`, `social-cards`, and `plugin-sdk` (in development).\n- **MCP server live** at [`mcp.tournamental.com`](https://mcp.tournamental.com) so Claude, Cursor, Windsurf, and other Model Context Protocol clients can read live Tournamental state.\n- **Engineering blog + plugin SDK** -- the engineering log at [`tournamental.com/engineering`](https://tournamental.com/engineering) is now the canonical entry point for builders, and the plugin SDK in [`packages/plugin-sdk/`](packages/plugin-sdk) lets you drop in renderers, scorers, ingest sources, identity providers, share-card pipelines, odds feeds, and affiliate routers without forking the core.\n\n## Build on Tournamental in 20 minutes\n\n1. Read [The Tournamental stack at a glance](https://tournamental.com/engineering/2026-05-13-stack-at-a-glance) for the six-step \"vibe-code your app on top of Tournamental\" walkthrough.\n2. Pick the npm packages you need:\n   - [`@tournamental/spec`](https://www.npmjs.com/package/@tournamental/spec) -- the canonical JSON message spec.\n   - [`@tournamental/bracket-engine`](https://www.npmjs.com/package/@tournamental/bracket-engine) -- cascade and scoring engine.\n   - [`@tournamental/social-cards`](https://www.npmjs.com/package/@tournamental/social-cards) -- OG, podium, and share-card renderer.\n   - [`@tournamental/plugin-sdk`](https://www.npmjs.com/package/@tournamental/plugin-sdk) -- plugin contracts for community-built modes.\n3. Wire your agent (Claude, Cursor, Windsurf) to the MCP server at [`mcp.tournamental.com`](https://mcp.tournamental.com) so it can read live state without you writing a fetch layer first.\n4. Browse the aggregated API reference at [`tournamental.com/api`](https://tournamental.com/api) (Scalar UI, deep-linkable per service). Per-service OpenAPI snapshots live under [`docs/api/`](docs/api/) for offline use.\n5. Ship it, open a PR for the contrib pool, and post in [Show and Tell](https://github.com/0800tim/tournamental/discussions/categories/show-and-tell).\n\n## Read the engineering log\n\nIf you are an AI agent or a human engineer landing in this repo and trying to work out where to plug in, start with the engineering log at **[tournamental.com/engineering](https://tournamental.com/engineering)** rather than the docs folder. The first post, [The Tournamental stack at a glance](https://tournamental.com/engineering/2026-05-13-stack-at-a-glance), maps every service and package and gives you a six-step \"vibe-code your app on top of Tournamental\" walkthrough. Subsequent posts drill into specific subsystems (renderer, scoring, on-chain, plugins, performance). RSS at `/engineering/rss.xml`. Public Q\u0026A at [GitHub Discussions](https://github.com/0800tim/tournamental/discussions).\n\n## What Tournamental is\n\nA live tournament intelligence game. Users predict match outcomes and tournament-wide brackets, lock predictions before the result is known, and earn points scored against live market implied probabilities — so calling a 25%-implied underdog correctly is worth more than calling a 90% favourite. Every locked prediction is timestamped and committed to a blockchain Merkle batch (a **VStamp**) so the leaderboard is verifiably tamper-proof. Users build a long-term **Prediction IQ** that becomes a portable reputation asset.\n\nThe 3D match-renderer (originally specced as a stand-alone framework, \"SimulatedSports\") is the watch-along surface — players, ball, pitch, stylized avatars, live commentary remixed via ElevenLabs, all driven by a normalized JSON spec stream that's distributed via Cloudflare. The prediction game and the renderer are independent layers sharing the same canonical match stream.\n\nThe killer line:\n\n\u003e **Everyone says they knew what would happen. Tournamental proves who really did.**\n\n## Core architecture in one diagram\n\n```\n   Producers (mock, video→AI, tracking feed, StatsBomb replay)\n                          │  spec stream (JSON)\n                          ▼\n                   Stream server (origin)\n                          │  chunks + manifest\n                          ▼\n                  Cloudflare CDN ──▶ Match renderer (web, R3F)\n                          │\n                          │  events\n                          ▼\n              ┌────────────────────────────┐       ┌─────────────────────┐\n              │ Game service (predictions, │ ───▶  │ VStamp service      │\n              │ leaderboards, badges,      │       │ (Merkle batching,   │\n              │ pools — Redis + flat JSON) │       │  Polygon + OTS)     │\n              └─────────────┬──────────────┘       └─────────────────────┘\n                            │ pub/sub\n                            ▼\n              ┌────────────────────────────┐       ┌─────────────────────┐\n              │ Tournament Bot (Telegram,  │       │ Clip pipeline       │\n              │  identity, notifications,  │       │ (headless renderer  │\n              │  group leaderboards)       │       │  + ffmpeg → IG/TT/  │\n              └────────────────────────────┘       │  YT/X/Telegram)     │\n                                                   └─────────────────────┘\n```\n\n## Repo layout\n\n```\nSimulatedSports/                           working folder name; consumer brand is \"Tournamental\"\n├── README.md                              this file\n├── Tournamental Pitch.md                               one-page elevator pitch\n├── REVIEW.md                              docs-pack readiness audit\n├── CLAUDE.md                              orchestrator + agent operations entrypoint\n├── AGENT-PROMPTS.md                       copy-paste starter prompts for code agents\n├── CONTRIBUTING.md                        contributor guide (humans + agents)\n├── IDEAS.md                               backlog parking lot\n├── sessions/                              per-session work notes\n├── docs/                                  detailed design docs (start here)\n│   ├── 01-vision-and-scope.md             what we're building and not building\n│   ├── 02-spec.md                         the JSON message spec (the contract)\n│   ├── 03-architecture.md                 end-to-end system design\n│   ├── 04-renderer.md                     Next.js + React Three Fiber renderer\n│   ├── 05-mock-producer.md                synthetic match generator\n│   ├── 06-video-ingest.md                 video → JSON pipeline (CV + LLM)\n│   ├── 07-avatars-and-assets.md           player likeness, jerseys, animations\n│   ├── 08-cdn-distribution.md             Cloudflare CDN, chunking, cache\n│   ├── 09-agent-task-breakdown.md         parallel work plan for code agents\n│   ├── 10-roadmap.md                      weekend MVP and beyond\n│   ├── 11-historic-data-sources.md        free data research; AR-FR 2022 plan\n│   ├── 12-odds-and-predictions.md         odds, predictions, leaderboards, sweepstakes\n│   ├── 13-telegram-bot-and-auth.md        Tournament Bot — auth (Telegram + email + TOTP + passkeys), notifications\n│   ├── 14-clip-generation-and-social.md   auto-clips → TikTok / Reels / Shorts / Telegram\n│   ├── 15-tournamental-brand-and-positioning.md  Tournamental brand, taglines, NZ regulatory framing, monetisation overview\n│   ├── 16-game-modes-and-scoring.md       10 game modes, scoring formula, personality leaderboards\n│   ├── 17-vstamp-and-prediction-iq.md     blockchain verification + Prediction IQ reputation\n│   ├── 18-monetization.md                 affiliate routing + sponsorship + Pro + B2B + creator + data licensing\n│   ├── 19-open-source-and-contributor-revenue.md  Apache 2.0, Tournamental, Drips Network revshare\n│   ├── 20-identity-humanness-bots.md      multi-provider OAuth, Humanness Score, bot policy, friend graph\n│   └── 21-onchain-sweepstakes-oracle.md   user-organised on-chain pools + Tournamental-as-oracle (Polygon/Base)\n├── spec/\n│   ├── types.ts                           canonical TypeScript types\n│   └── examples/                          sample JSON payloads\n└── prompts/                               LLM prompts (frame-analyzer, commentary-extractor)\n```\n\n## npm packages\n\nWorkspace packages publish to npm under the `@tournamental` scope since\n2026-05-13. Apps inside this monorepo (`apps/web`, `apps/marketing`,\n`apps/game`, and friends) stay as `@vtorn/*` because they are internal\ndeploy targets and do not publish.\n\nPublic packages:\n\n- `@tournamental/spec` -- canonical message spec for every producer and\n  renderer.\n- `@tournamental/bracket-engine` -- cascade and scoring engine for the\n  bracket prophet flow.\n- `@tournamental/social-cards` -- OG, podium, and share-card renderer.\n- `@tournamental/plugin-sdk` -- plugin contracts for community-built\n  modes (in development).\n\n## v0.2 demo target: 2022 World Cup Final\n\nThe first non-mock demo recreates **Argentina 3–3 France (4–2 pens), 2022 World Cup Final**, driven by **StatsBomb Open Data** (free, on GitHub, includes events + 360° freeze-frames for every match). Player photos via Wikidata / Wikimedia Commons. Full plan in [docs/11-historic-data-sources.md](docs/11-historic-data-sources.md). Tournamental-flavour: every viewer can predict the match alongside the rendered replay, score against the 2022 implied probabilities (we have the StatsBomb data for that), and walk away with a verifiable VStamp on their best calls.\n\n## Documentation\n\n- **Hive-mind index** for agents and contributors: [`docs/README.md`](docs/README.md). Start here.\n- **Glossary** of Tournamental-specific terms: [`docs/glossary.md`](docs/glossary.md).\n- **Playbooks** for adding apps, routes, debugging PRs, merge conflicts, feature flags, doc updates: [`docs/playbook/`](docs/playbook/).\n- **API reference** with per-service Swagger UI URLs and committed OpenAPI 3.0 specs: [`docs/api/README.md`](docs/api/README.md).\n\n## API\n\n- **Public API portal** at [`tournamental.com/api`](https://tournamental.com/api), one aggregated Scalar-rendered reference across every public Fastify service in the monorepo, with deep-links at `/api/\u003cservice-slug\u003e`. Built from the committed `docs/api/*.openapi.json` snapshots so it works offline. Architecture in [`docs/53-api-portal.md`](docs/53-api-portal.md).\n- **Per-service snapshots** committed under [`docs/api/`](docs/api/), regenerated by `pnpm --filter @vtorn/\u003cservice\u003e run openapi:snapshot` (alias for the existing `dump-openapi` script).\n\n## Quickstart for code agents\n\nEach doc in `docs/` is written to be picked up by a separate code agent and implemented independently. The agent task breakdown lives in [docs/09-agent-task-breakdown.md](docs/09-agent-task-breakdown.md) and identifies which docs are blocking, which can run in parallel, and the contract surface each agent must respect.\n\nThere are now thirteen agents (A–M):\n\n- **A–E** — match-stream critical path (spec, mock producer, stream server, renderer, spec client).\n- **F–I** — match-stream parallel work (video ingest, CDN deploy, avatars, demo site).\n- **J** — game service: predictions, leaderboards, badges, pools.\n- **K** — Tournament Bot: Telegram + email + TOTP + passkey auth, notifications, group leaderboards.\n- **L** — clip pipeline: headless renderer → MP4 variants → social posting.\n- **M** — VStamp service: Merkle batching, Polygon anchoring, OpenTimestamps proofs.\n\nCritical-path \"watchable demo\" remains a weekend-one job (agents A–E + minimal H). The full Tournamental launch with predictions, bot, VStamps, and clip distribution is a 2–4 week pack of work for a parallel team of code agents — roughly the timeframe to a tournament window like the 2026 World Cup.\n\n## Build a plugin in 10 minutes\n\nTournamental ships a plugin SDK so third parties can drop in a replacement renderer, scorer, ingest source, identity provider, commentary voice, share-card pipeline, odds feed, or affiliate router without forking the core. Eight extension points are first-class in v0.1.\n\nQuickstart:\n\n- SDK: [`packages/plugin-sdk/`](packages/plugin-sdk) + [`packages/plugin-sdk/README.md`](packages/plugin-sdk/README.md)\n- Reference plugin: [`packages/plugins/example-cel-shaded-renderer/`](packages/plugins/example-cel-shaded-renderer)\n- Full architecture doc: [`docs/28-plugin-architecture.md`](docs/28-plugin-architecture.md)\n- Revenue split via Drips: [`docs/19-open-source-and-contributor-revenue.md`](docs/19-open-source-and-contributor-revenue.md)\n\n```bash\npnpm add @tournamental/plugin-sdk\n# Create plugin.json declaring `provides: [\"renderer\"]` (or another capability)\n# Export a default PluginFactory from src/index.ts\n# Drop it in plugins/ for dev or publish to npm under @tournamental-plugin/*\n```\n\nPlugins are dynamically loaded at app boot. License must be Apache-2.0, MIT, BSD-2-Clause, or BSD-3-Clause (the manifest schema rejects everything else). Plugins shipped in `packages/plugins/*` or under the `@tournamental-plugin/*` npm scope receive a share of the upstream Drips treasury per [doc 19](docs/19-open-source-and-contributor-revenue.md).\n\n## Deploys\n\nCI/CD is build-slot blue-green: build to `\u003cslot\u003e-staging`, smoke-test on a\nprivate port, atomic-swap `\u003cslot\u003e-prod`, PM2 reload. Worst-case ~2-3s\nperceived downtime. Generalised across all monorepo apps.\n\n- Architecture: [docs/47-cicd-pipeline.md](docs/47-cicd-pipeline.md)\n- Deploy runbook: [docs/cicd/01-deploy-runbook.md](docs/cicd/01-deploy-runbook.md)\n- Rollback: [docs/cicd/02-rollback-runbook.md](docs/cicd/02-rollback-runbook.md)\n- Incident flag: [docs/cicd/03-incident-flag-runbook.md](docs/cicd/03-incident-flag-runbook.md)\n- Secrets rotation: [docs/cicd/04-secrets-rotation-runbook.md](docs/cicd/04-secrets-rotation-runbook.md)\n\nTop-level scripts: `pnpm deploy:staging --apps=marketing`,\n`pnpm deploy:promote`, `pnpm deploy:rollback --app=marketing --buildKind=astro`.\n\n## Positioning (short version)\n\nTournamental is **free-to-play**. Points are not redeemable for cash. We never operate as a sportsbook. We display public market odds (Polymarket, The Odds API) as a data layer for scoring difficulty; we surface affiliate links to regulated operators *only where legal for the user*. Sweepstakes pools are tracked but not custodial — users settle off-platform. Detailed regulatory framing (including the NZ-specific Polymarket/Kalshi situation) in [docs/15-tournamental-brand-and-positioning.md](docs/15-tournamental-brand-and-positioning.md).\n\n## Disclaimer\n\nThis project is provided for educational and demonstration purposes only. Tournamental does not offer or facilitate real-money wagers. Producer implementations that consume copyrighted broadcasts, scrape paid data feeds, or republish licensed tracking streams are the responsibility of the operator running them, not this framework. Operators are responsible for confirming the legality of any market-data display or affiliate-link placement in their jurisdiction.\n\n## License and structure\n\nTournamental ships **100% open source** under **Apache 2.0** (code) and **CC-BY-4.0** (docs). The brand, wordmark, and the official `@TournamentalBot` Telegram identity are owned by **Tournamental** and are *not* licensed for forks — see `TRADEMARK.md`. Anyone may fork the protocol, run their own instance, set their own affiliate destinations, build their own world.\n\n**Contributor revenue share.** A fixed percentage of net affiliate revenue (and other monetization lanes) flows to a public Drips Network treasury that streams USDC to scored contributors quarterly. Code merges, accepted RFCs, games built on the platform, vulnerability disclosures, and major reviews all earn into the pool. **This is revenue share, not equity.** Full design and contributor onboarding in [docs/19-open-source-and-contributor-revenue.md](docs/19-open-source-and-contributor-revenue.md).\n\n**Comparable structures.** Optimism, Filecoin, Mozilla, Linux Foundation, Radworks. Foundation-backed open protocol with brand-and-treasury controlled by the entity, contributor revshare via on-chain streaming.\n\nAsset packs (avatars, stadium models, jersey textures) follow the licence of their original creators; the framework itself contains none.\n\n## Sub-processors\n\nProduction Tournamental surfaces depend on the following third-party services. New contributors should know the data-flow boundary before shipping anything that touches user data. The same list appears in [SECURITY.md](SECURITY.md) for the security-disclosure context.\n\n- **Supabase** -- managed Postgres + auth (user records, sessions, predictions, leaderboards).\n- **Cloudflare** -- DNS, CDN, Workers, Tunnel, WAF; the public edge for every Tournamental surface.\n- **Aiva SMS** -- SMS and WhatsApp gateway for OTP delivery during the auth flow.\n- **GoHighLevel** -- CRM for syndicate signups and marketing automation.\n- **npm registry** -- distribution channel for the `@tournamental/*` packages.\n- **GitHub** -- source hosting, issues, discussions, releases, and security advisories.\n- **Drips Network** -- on-chain contributor revenue treasury (Ethereum + L2).\n- **Polymarket** -- read-only prediction-market odds used for difficulty scoring.\n- **StatsBomb Open Data** -- read-only historical match data for the replay demos.\n\nSub-processor changes ship as their own PR with a CHANGELOG entry and a SECURITY.md update.\n\n## Community\n\n- **Discussions** -- ideas, help, and show-and-tell at [GitHub Discussions](https://github.com/0800tim/tournamental/discussions). Templates live in [`.github/DISCUSSION_TEMPLATE/`](.github/DISCUSSION_TEMPLATE/).\n- **Discord** -- live chat at [discord.gg/tournamental](https://discord.gg/tournamental) (invite finalised at public-launch, see [docs/55-public-launch-checklist.md](docs/55-public-launch-checklist.md)).\n- **Code of Conduct** -- the [Contributor Covenant 2.1](CODE_OF_CONDUCT.md). Report violations to `0800tim@gmail.com`.\n- **Security** -- private disclosure flow in [SECURITY.md](SECURITY.md). Do not open public issues for vulnerabilities.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2F0800tim%2Ftournamental","html_url":"https://awesome.ecosyste.ms/projects/github.com%2F0800tim%2Ftournamental","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2F0800tim%2Ftournamental/lists"}