Skip to content

Open-source platform for 3D AI agents. Turn text or a photo into a rigged, animated GLB avatar, give it an LLM brain, memory and a wallet, and embed it anywhere with one web component. Remote MCP server, x402 payments, Three.js, browser-native.

docs(event-markets): document the live odds feed schema, reconnect and load behavior, keep the home ticker static for one or two markets, and carry the scoring docs and changelog entry that share these files

nirholasc7fe89998d13
diff --git a/STRUCTURE.md b/STRUCTURE.md
index 9191e65b3..829f73370 100644
--- a/STRUCTURE.md
+++ b/STRUCTURE.md
@@ -22,6 +22,8 @@ bottom.
| Event Market auto-open | [api/_lib/event-markets/auto-open.js](api/_lib/event-markets/auto-open.js), [sources/](api/_lib/event-markets/sources/), [api/cron/event-markets-open.js](api/cron/event-markets-open.js), [api/ops/event-markets.js](api/ops/event-markets.js), [pages/event-markets-admin.html](pages/event-markets-admin.html) `→ /admin/event-markets` | Live once migration 20261012010000 is applied | Opens a market per Arena tournament, platform event, build round and bounty; adds late entrants pre-lock; logs skips; writes the `event_market.opened` outbox row. Docs: [docs/event-markets.md](docs/event-markets.md). Tests: [tests/event-markets-auto-open.test.js](tests/event-markets-auto-open.test.js) |
| Event Market resolution | [api/_lib/event-markets/resolvers/](api/_lib/event-markets/resolvers/), [lifecycle.js](api/_lib/event-markets/lifecycle.js), [override.js](api/_lib/event-markets/override.js), [api/cron/event-markets-resolve.js](api/cron/event-markets-resolve.js), [api/ops/event-market-override.js](api/ops/event-market-override.js), [data/event-market-resolution.json](data/event-market-resolution.json) | Live once migration 20261012130000 is applied | Locks at `locks_at`, resolves from our own arena, event, launch, round and bounty records with the evidence stored on the market, retries while pending, voids on tie, no data, cancellation or timeout; admin override needs a written reason. Docs: [docs/event-markets.md](docs/event-markets.md#how-markets-resolve). Tests: [tests/event-market-resolvers.test.js](tests/event-market-resolvers.test.js), [tests/event-market-lifecycle.test.js](tests/event-market-lifecycle.test.js) |
| Event Market pages and share cards | [pages/event-markets.html](pages/event-markets.html) `→ /event-markets`, [pages/event-market.html](pages/event-market.html) `→ /event-markets/<slug>`, [src/event-markets/](src/event-markets/), [api/event-market-og.js](api/event-market-og.js), [api/event-market-share.js](api/event-market-share.js), [api/_lib/event-market-card.js](api/_lib/event-market-card.js) | Live | Browse and detail pages, pick flow, odds chart, per-market SVG share card and crawlable meta page, entry strips on Arena, event, launches and home. Docs: [docs/event-markets.md](docs/event-markets.md#pages-and-share-cards). Tests: [tests/event-market-card.test.js](tests/event-market-card.test.js) |
+| Event Market scoring, leaderboard and rewards | [api/_lib/event-markets/scoring.js](api/_lib/event-markets/scoring.js), [rollup.js](api/_lib/event-markets/rollup.js), [fairness.js](api/_lib/event-markets/fairness.js), [leaderboard.js](api/_lib/event-markets/leaderboard.js), [api/cron/event-markets-rollup.js](api/cron/event-markets-rollup.js), [data/event-market-scoring.json](data/event-market-scoring.json), [pages/event-markets-leaderboard.html](pages/event-markets-leaderboard.html) `→ /event-markets/leaderboard`, [scripts/event-markets-season-payouts.mjs](scripts/event-markets-season-payouts.mjs) | Live once migration 20261012400000 is applied; payouts owner-gated | Scores, streaks, season ranks and badges from the rollup cron; wallet-derived names; fair-play ranking checks; season reward table printed for owner approval, never sent automatically. Docs: [docs/event-markets.md](docs/event-markets.md#scoring-and-seasons). Tests: [tests/event-markets-scoring.test.js](tests/event-markets-scoring.test.js) |
+| Event Market live feed | [api/event-markets/stream.js](api/event-markets/stream.js), [api/_lib/event-markets/hub.js](api/_lib/event-markets/hub.js), [feed.js](api/_lib/event-markets/feed.js), [moves.js](api/_lib/event-markets/moves.js), [live-stats.js](api/_lib/event-markets/live-stats.js), [api/cron/event-markets-feed.js](api/cron/event-markets-feed.js), [src/event-markets/live-feed.js](src/event-markets/live-feed.js), [ticker.js](src/event-markets/ticker.js), [data/event-markets-feed.json](data/event-markets-feed.json) | Live (migration 20261012200000 applied) | SSE odds, picks, moves and lifecycle with Last-Event-ID resume, odds-move detector, home ticker, in-place odds on the market page with polling fallback, pulse and trending additions. Docs: [docs/event-markets.md](docs/event-markets.md#live-feed). Tests: [tests/event-markets-live-feed.test.js](tests/event-markets-live-feed.test.js), [tests/event-markets-live-stats.test.js](tests/event-markets-live-stats.test.js). Bench: [scripts/event-markets-fanout-bench.mjs](scripts/event-markets-fanout-bench.mjs) |
| Walk companion + playground | [walk-sdk/](walk-sdk) `→ /walk-companion.js` | Published as `@three-ws/walk` | Corner mascot + full-page stroll/platformer playground + diverse avatar picker. App entries: [src/walk-companion.js](src/walk-companion.js), [src/walk-playground.js](src/walk-playground.js) |
| The walkaround world (`/temporary`) | [pages/temporary.html](pages/temporary.html) `→ /temporary`, app [src/walk.js](src/walk.js), environments [src/walk-environments.js](src/walk-environments.js) + [public/environments/](public/environments), multiplayer [src/walk-net.js](src/walk-net.js) → `walk_world`, day/night [src/walk-day-night.js](src/walk-day-night.js), radar [src/game/hud/minimap.js](src/game/hud/minimap.js), companions [src/walk-npcs.js](src/walk-npcs.js), agent desks [src/walk-agent-desk.js](src/walk-agent-desk.js) | Live | Walk your avatar through six real staged environments (park, cyberpunk street, beach, gallery, void, office) with physics-driven locomotion on a heightfield, four camera modes, gestures, voice chat, trails, capture, and live peers. **Time of day is real and shared:** the same deterministic world clock `/play` runs on ([src/shared/world-clock.js](src/shared/world-clock.js)) drives the sun arc, sky gradient, light levels, and IBL strength, so two people in the same world always agree on whether it is night. The sky crossfades on a wider curve than the light levels, so dawn and dusk linger instead of flipping. Armed for outdoor stages only (indoor/void keep their authored manifest lighting) and paused while AR passthrough owns the rig. **The radar is `/play`'s:** `/temporary` mounts the same rotating GTA-style minimap the world HUD uses, with a compass, the walkable-disc boundary ring, and live blips for peers (their nameplate colours), NPC companions, live agent desks, the guide's named landmarks, and scenery. Click or tap it to set a walk-to waypoint (`Minimap.worldFromScreen()` inverts the rotating projection); `M` or the dock button toggles it and the choice persists. **Frame pacing is shared too:** the loop runs through [src/shared/frame-governor.js](src/shared/frame-governor.js) (60fps focused, 30 unfocused, 30 under power saver) and the controls overlay carries the cross-surface Power-saver switch. Tests: [tests/walk-day-night.test.js](tests/walk-day-night.test.js), [tests/minimap-projection.test.js](tests/minimap-projection.test.js) |
| Walk landing + one-tag embed (`/walk`) | [pages/walk-landing.html](pages/walk-landing.html) `→ /walk`, embed app [pages/walk-embed.html](pages/walk-embed.html) `→ /walk/app` and `→ /walk-embed` ([src/walk-embed.js](src/walk-embed.js)), board [pages/walk-leaderboard.html](pages/walk-leaderboard.html) `→ /walk-leaderboard`, ranking API [api/walk/leaderboard.js](api/walk/leaderboard.js), curated quotes [data/walk-social.json](data/walk-social.json) | Live | The marketing entry for Walk and the surface the `→ /walk` route actually serves (the walkaround world above is at `/temporary`). Live demo embeds across six environments, the copyable one-tag iframe snippet, the Chrome extension pitch, and a top-three teaser off the real all-time distance ranking, which reads `rows` straight from the leaderboard endpoint and falls back to designed empty and retryable error states. All nine demo iframes stay keyboard-reachable, which axe's `frame-focusable-content` rule requires of any frame whose document has focusable content, and each gets a scripted focus ring because an iframe whose document holds focus matches no focus pseudo-class. Page copy is mirrored in the `walk_landing` namespace of [public/locales/en.json](public/locales/en.json), which the i18n runtime applies over the served HTML, so the two must be edited together. |
diff --git a/data/changelog.json b/data/changelog.json
index f3988d326..4a1cd24ae 100644
--- a/data/changelog.json
+++ b/data/changelog.json
@@ -29872,6 +29872,24 @@
"feature"
],
"link": "/event-markets"
+ },
+ {
+ "date": "2026-10-10",
+ "title": "Event Markets leaderboard: seasons, streaks, badges and rewards",
+ "summary": "Every resolved call now scores. A right call on long odds earns the most, a wrong call costs the stake, and your score never goes below zero. Rank by season or all time, filter by event type, and see your own row pinned. Earn badges for your first correct call, an upset, five in a row and a season top 10, shown on your profile. Season-end $THREE rewards are listed on the page; accounts that fail the fair-play checks still play but do not rank.",
+ "tags": [
+ "feature"
+ ],
+ "link": "/event-markets/leaderboard"
+ },
+ {
+ "date": "2026-10-10",
+ "title": "Event Markets: odds that move while you watch",
+ "summary": "Event market odds now update live. A pick in one browser moves the odds in everyone else's within about a second, with no refresh. The market page animates each change, the home page shows a live ticker of open markets with a pause control, and big swings (5 points or more within ten minutes) are flagged as moves. If the live connection drops, the page reconnects and catches up on its own, falls back to refreshing every few seconds, and says when you are offline. Picks stay anonymous: the feed shows counts, never who picked.",
+ "tags": [
+ "feature"
+ ],
+ "link": "/event-markets"
}
]
}
diff --git a/docs/event-markets.md b/docs/event-markets.md
index bf4040c9d..22c3eb2f5 100644
--- a/docs/event-markets.md
+++ b/docs/event-markets.md
@@ -164,3 +164,78 @@ The market page itself is the SPA at `/event-markets/view?m=<slug>`; the crawlab
**Entry points.** The nav (Play, next to The Arena), the Arena tournament page, the `/event` page, `/launches` (launch cohort markets) and the home page, each through `src/event-markets/entry-strip.js`. A strip renders nothing when there is no open market, so no surface shows an empty promo.
Code: [src/event-markets/](../src/event-markets/), [api/event-market-og.js](../api/event-market-og.js), [api/event-market-share.js](../api/event-market-share.js), [api/_lib/event-market-card.js](../api/_lib/event-market-card.js). Tests: [tests/event-market-card.test.js](../tests/event-market-card.test.js).
+
+## Live feed
+
+`GET /api/event-markets/stream` is a server-sent event stream of odds, picks and lifecycle changes. No parameter gives the global feed (every open market); `?slug=<slug>` gives one market. Config lives in [data/event-markets-feed.json](../data/event-markets-feed.json).
+
+### How it works
+
+Database triggers (migration `20261012200000_event_market_live_feed.sql`) append every pick change and status change to an append-only log, `event_market_events`, so every write path is covered: the REST route, cron resolvers and agent forecasters. A processor turns raw rows into a fresh `odds` snapshot per touched market and, when a share crossed the move threshold, a `move`. The log's bigserial id is the SSE event id, so any Cloud Run instance can serve any listener and `Last-Event-ID` resumes across instances. Each instance polls the log once per `pollIntervalMs` (250 ms) for all of its listeners. `/api/cron/event-markets-feed` runs the same processor every minute so moves are recorded when nobody is watching.
+
+### Events
+
+Every `data:` object carries `seq` (the log id). Rows carry the market `slug`.
+
+| Event | When | Data |
+| --- | --- | --- |
+| `snapshot` | First frame of a new connection | `{ seq, markets: [odds] }` |
+| `resync` | Reconnect whose gap the log cannot replay | same as `snapshot` |
+| `resume` | Reconnect that can be replayed | `{ from, to, replayed }`, followed by the missed events |
+| `open` / `lock` / `resolve` | Market status change (once per market) | `{ slug, title, status, locks_at }`, `resolve` adds `winner_outcome_id`, `winner_label` |
+| `odds` | A pick changed the odds | one odds object: `{ slug, title, status, locks_at, pick_count, outcomes: [{ id, label, picks, share, percent }] }` |
+| `pick` | A pick was placed, changed or withdrawn | `{ slug, outcome_id, batched? }` |
+| `move` | An outcome's share moved at least `move.thresholdPoints` (5) within `move.windowSeconds` (600) | `{ slug, label, outcome_id, share_from, share_to, delta_points, window_seconds }` |
+| `ping` | Every 15 s | `{ t }` |
+| `close` | Just before the connection's lifetime ends | none |
+
+A `move` fires once per outcome per window bucket and is also written to `event_market_moves`, which the announcement drafts read.
+
+### Privacy
+
+A `pick` event names the outcome and nothing else. It never carries an account, wallet or handle, and a pick's author is not derivable from the feed. Pick counts are aggregate.
+
+### Reconnecting
+
+Cloud Run ends a request at its timeout (300 s here), so the server closes a connection after about 270 s (jittered) with `event: close`, and `retry: 2000` tells the browser how long to wait. Reconnect with the last id in the `Last-Event-ID` header (a browser's EventSource does this itself) or `?lastEventId=<id>`. The client in [src/event-markets/live-feed.js](../src/event-markets/live-feed.js) additionally dedupes by `seq`, treats 33 s of silence as a dead connection, backs off exponentially with jitter, closes while the tab is hidden, falls back to polling the REST read every 5 s after three failures, and reports `live`, `reconnecting`, `polling` or `offline`.
+
+### Load handling
+
+- At most one `odds` frame per market per second per listener. Held frames are sent without an `id:` line so `Last-Event-ID` never moves backwards.
+- 20 connections per IP and 5000 per process; over the cap the endpoint answers 429 with `Retry-After`.
+- A listener whose socket backlog exceeds 256 KB is dropped and resumes from its last id.
+- Measured with `node scripts/event-markets-fanout-bench.mjs 1000 20 20` (the real hub, 1000 listeners, 20 markets, 40 log rows per round): about 1.9 ms of hub time per tick, 21,000 frames and 4.8 MB written per tick, no retained heap growth. Database cost does not scale with listeners: 2 queries per tick per process. Real socket writes add kernel time on top of the hub figure.
+
+### Where it shows
+
+The market page patches odds in place with a flash (static under `prefers-reduced-motion`) and a connection chip; the home page shows a ticker strip with a pause control, hidden unless a market is live. `/api/pulse?view=event-markets` returns `live_count`, `biggest_mover` and `closing_soon`; `/api/trending` includes `markets` ranked by picks in the last hour.
+
+## Scoring and seasons
+
+Every resolved call scores. All constants live in [data/event-market-scoring.json](../data/event-market-scoring.json); the leaderboard page quotes that file, so the docs and the code cannot drift.
+
+**Formula.** `p` is the market's chance for your pick at the moment you made it (`odds_at_pick`, stamped on the pick).
+
+```
+win = round(stake x clamp(1 / p - 1, 0.1, 10))
+loss = -stake
+score = running total in settle order, never below 0
+```
+
+A 80% favourite pays x0.25, an even call x1, a 20% call x4, a 5% call x10 (the cap). A heavy favourite is never worth zero (floor x0.1). Void markets are refunded and do not count. Code: [scoring.js](../api/_lib/event-markets/scoring.js), tests: [tests/event-markets-scoring.test.js](../tests/event-markets-scoring.test.js).
+
+**Stats.** Per account, per scope (season or all time) and per source kind: calls, hits, hit rate, average odds at pick, best call, current and longest streak, rank. A miss resets the current streak. You rank after 3 resolved calls and a positive score.
+
+**Seasons.** Calendar quarters in UTC, keyed `2026-Q4`. A season is final once it has ended.
+
+**Rollup.** `GET /api/cron/event-markets-rollup` ([rollup.js](../api/_lib/event-markets/rollup.js)) scores newly resolved markets into `event_market_scores` (primary key market and account, `on conflict do nothing`), recomputes stats only for seasons that changed, awards badges and, for ended seasons, proposes rewards. Running it twice changes nothing. `?full=1` recomputes everything. An admin override deletes a market's score rows and the next run re-scores them.
+
+**API.** `GET /api/event-markets/leaderboard?scope=season|all&season=2026-Q4&source_kind=all&limit=25` (your own row comes back as `me`), `GET /api/event-markets/seasons`, `GET /api/event-markets/seasons/:id/rewards`, `GET /api/event-markets/me`. Names are the display name, username or a shortened wallet; never an email.
+
+**Badges** (through the achievements system, shown on profiles): first correct call, upset call (right when the market gave the pick under 25%), 5 in a row, season top 10, season champion. Each is awarded once per account.
+
+**Rewards.** Top 10 each season: rank 1 gets 50,000 $THREE, ranks 2 to 3 get 25,000, ranks 4 to 10 get 10,000, plus platform perks. The list is computed automatically at season end into `event_market_season_payouts` as `proposed`. Paying is owner-gated: `node --env-file=.env scripts/event-markets-season-payouts.mjs --season 2026-Q4` prints the table (recipient wallet, amount, token, chain) and stops. Nothing is sent until the owner says yes; `--approve` only records that yes, `--paid <account> <signature>` records a landed transfer.
+
+**Fair play.** One account has one pick per market (primary key). A pick ranks only if, at pick time, the account is at least 24 hours old, has a linked wallet or verified email, and is not a service account. A pick that fails still plays but is stored `ranked = false`, never scores on the board and never earns rewards. Checks: [fairness.js](../api/_lib/event-markets/fairness.js).
+
+Page: `/event-markets/leaderboard`. Migration: `20261012400000_event_market_scoring.sql` (check `npm run db:status`, then the owner-approved migrate).
diff --git a/src/event-markets/ticker.js b/src/event-markets/ticker.js
index 030c159eb..6d23065f0 100644
--- a/src/event-markets/ticker.js
+++ b/src/event-markets/ticker.js
@@ -41,7 +41,7 @@ function render() {
if (!open.length) { mount.replaceChildren(); return; }
open.sort((a, b) => Date.parse(a.locks_at) - Date.parse(b.locks_at));
const items = open.map(item);
- const list = h('ul', { class: 'em-tk-list', 'data-paused': String(paused) }, items, open.length > 2 ? open.map(item).map((li) => { li.setAttribute('aria-hidden', 'true'); return li; }) : null);
+ const list = h('ul', { class: 'em-tk-list', 'data-paused': String(paused), 'data-scroll': String(open.length > 2) }, items, open.length > 2 ? open.map(item).map((li) => { li.setAttribute('aria-hidden', 'true'); return li; }) : null);
const btn = h('button', { class: 'em-tk-pause', type: 'button', 'aria-pressed': String(paused), onclick: () => { paused = !paused; render(); } }, paused ? 'Resume' : 'Pause');
mount.replaceChildren(h('span', { class: 'em-tk-tag' }, h('span', { class: 'dot', 'aria-hidden': 'true' }), 'Live'), h('div', { class: 'em-tk-view' }, list), btn);
}