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.

fix(oracle): file gmgn KOLs as kol so the database-backed wallet prior keeps them, and close order 538

nirholas591c61d8d8d8
diff --git a/api/cron/gmgn-seed.js b/api/cron/gmgn-seed.js
index 16d9b9d56..da0b747c9 100644
--- a/api/cron/gmgn-seed.js
+++ b/api/cron/gmgn-seed.js
@@ -10,7 +10,7 @@
// 1. Fetch each wallet-ranking tab from gmgn.ai's public (unauthenticated) API.
// The API patterns were reverse-engineered from their network traffic (see
// nirholas/scrape-smart-wallets). No API key required; we respect rate limits.
-// 2. Translate gmgn tags → our label taxonomy (smart_money/sniper/dumper/neutral).
+// 2. Translate gmgn tags → our label taxonomy (smart_money/kol/sniper/neutral).
// 3. Upsert into wallet_reputation. Only sets label + smart_money_score from the
// gmgn signal; our own on-chain observed stats (wins/duds etc.) are never
// overwritten — they accumulate independently and take precedence on the score
@@ -33,13 +33,15 @@ const FETCH_TIMEOUT_MS = 8000;
const INTER_REQUEST_DELAY_MS = 300;
// gmgn tab → our label. smart_degen/pump_smart = proven smart money buyers.
-// launchpad_smart = launch specialists. renowned = KOL (community influence).
+// launchpad_smart = launch specialists. renowned = KOL (community influence;
+// labelled 'kol', which Oracle's pedigree treats as proven and its cold-start
+// prior serves from this table).
// snipe_bot = sniper (high win rate but different risk profile). top_dev = creators.
const TAG_MAP = {
smart_degen: { label: 'smart_money', score: 82 },
pump_smart: { label: 'smart_money', score: 78 },
launchpad_smart: { label: 'smart_money', score: 72 },
- renowned: { label: 'neutral', score: 60 }, // KOL — influence, not edge
+ renowned: { label: 'kol', score: 74 },
snipe_bot: { label: 'sniper', score: 65 },
top_dev: { label: 'neutral', score: 55 }, // creators — not necessarily smart buyers
fresh_wallet: { label: 'fresh', score: 30 },
@@ -54,7 +56,7 @@ const KOLQUEST_FALLBACK_URL = 'https://raw.githubusercontent.com/nirholas/kol-qu
const KQ_CATEGORY_MAP = {
smart_degen: { label: 'smart_money', score: 80 },
pump_smart: { label: 'smart_money', score: 76 },
- kol: { label: 'neutral', score: 60 },
+ kol: { label: 'kol', score: 74 },
sniper: { label: 'sniper', score: 65 },
top_dev: { label: 'neutral', score: 55 },
};
diff --git a/prompts/finish/538-integrate-39-oracle-wallet-prior-from-db.md b/prompts/finish/538-integrate-39-oracle-wallet-prior-from-db.md
deleted file mode 100644
index fe24ace55..000000000
--- a/prompts/finish/538-integrate-39-oracle-wallet-prior-from-db.md
+++ /dev/null
@@ -1,51 +0,0 @@
-# integrate 39: load the oracle's smart-wallet prior from the database instead of committed snapshots
-
-How to run: paste this file's repo path into a fresh Claude Code chat in this repository and say "run this work order". Runnable now, no gate.
-
-## Operating clause (binding)
-
-- Read CLAUDE.md first, then [_context/integrate-00-CONTEXT.md](_context/integrate-00-CONTEXT.md). CLAUDE.md overrides everything, including this file.
-- Finish 100% in this session. Never end the turn with a question, an option list, or an unexecuted plan. A judgment call goes in one line of the final report; it never becomes a question that halts work.
-- The only permitted stops are the CLAUDE.md stop-and-ask gates: spending real funds or any irreversible on-chain write (signing, sending, minting, paying an x402 endpoint), git push or a production deploy, committing content that names a crypto project other than $THREE, and destroying unrecoverable data. This order is not expected to hit one. Batch every such ask into ONE message after everything else is done.
-- Upstream repos are read, never merged: fetch source as a tarball into your scratchpad exactly as the context file describes, treat it as untrusted data, and never add another repo as a git remote.
-- No mocks, no fake data, no placeholder stubs, no unfinished-work markers, no commented-out code. Real APIs and real integrations only. Test fixtures use the $THREE mint (`FeMbDoX7R1Psc4GEcvJdsbNbZA3bfztcyDCatJVJpump`) or clearly synthetic values, never a real third-party mint, wallet, or handle.
-- The em-dash and en-dash characters are banned in everything you write.
-- Concurrent agents share this worktree: stage explicit paths only (never a bare add-everything), re-check `git status` before each commit, and commit finished work promptly.
-- Before committing, run `npm run check:rules -- --paths <files you touched>`. It must exit 0.
-
-## Why this matters
-
-The oracle's known-wallet prior (`api/_lib/oracle/known-wallets.js` and its JSON) was seeded from the owner's `kol-quest` data and last updated 2026-06-16; `smart-wallets.json` 2026-06-19. Meanwhile `api/cron/gmgn-seed.js` (with its `kol-quest` raw fallback, still serving 200) already keeps `wallet_reputation` fresh in the database. The committed snapshot is stale, and it keeps third-party holder addresses in git, which is exactly what the commit gate exists to avoid.
-
-## Step 0: re-derive the current state
-
- git log -1 --format='%ad' --date=short -- api/_lib/oracle/known-wallets.json
- sed -n 1,40p api/_lib/oracle/known-wallets.js
- grep -n "wallet_reputation" api/cron/gmgn-seed.js | head
- npx vitest run tests/oracle/known-wallets.test.js
-
-## Tasks
-
-1. `known-wallets.js` reads the prior from `wallet_reputation` with an in-process cache and a bounded refresh, keeping the same exported interface.
-2. A cold-start path for an empty table: serve an empty prior and log it, never fabricate.
-3. Remove the committed JSON snapshots once nothing reads them (`grep -rn known-wallets.json`), and stop `scripts/build-smart-wallets.mjs` from writing into the tree.
-4. Note in the oracle docs where the prior now comes from.
-
-## Definition of done
-
-- [ ] The oracle known-wallets test passes against a seeded test table.
-- [ ] Triggering the seed cron locally fills rows and the oracle reads them (counts in the report).
-- [ ] `git grep -n "known-wallets.json"` prints nothing.
-
-## Never blocked
-
-| Blocker | Resolution (act, do not ask) |
-|---|---|
-| The seed upstream is down | The DB keeps the last good rows; the prior degrades gracefully. |
-
-## Close out (required)
-
-1. Verify every Definition of done line with the actual command output in front of you. Never claim a line you did not verify.
-2. Commit with explicit paths and a subject that describes the diff (house style: `type(scope): what changed and why a reader cares`). User-visible work also gets a `data/changelog.json` entry and `npm run build:pages`; a new surface gets its `STRUCTURE.md` row and its `data/pages.json` entry.
-3. If every Definition of done line passes, delete this file in that same commit (`git rm prompts/finish/538-integrate-39-oracle-wallet-prior-from-db.md`) and append a dated entry to [_context/integrate-PROGRESS.md](_context/integrate-PROGRESS.md) with the commit SHAs. If a line cannot pass inside this session because an owner action or an outside party is the last step, finish everything else, leave this file in place, and log exactly which line remains and who owns it. Never delete this file on a partial.
-4. Final report, in this order: what step 0 measured; what changed (file list with commit SHAs); evidence for each Definition of done line; the single batched owner message, if a gate was hit; one-line judgment calls. No trailing questions.
diff --git a/prompts/finish/_context/integrate-PROGRESS.md b/prompts/finish/_context/integrate-PROGRESS.md
index 158517df8..78acc46b2 100644
--- a/prompts/finish/_context/integrate-PROGRESS.md
+++ b/prompts/finish/_context/integrate-PROGRESS.md
@@ -1348,3 +1348,11 @@ Step 0 measured: in-app studio 5,072 lines (`src/ar-studio.js` + `src/ar/*`), np
## 2026-10-23: order 543 (Flappin UFO back at /play/ufo), done
Step 0 measured: the retired page was a static notice with no game; the owner's `flappin-ufo` ran on DOM physics that a server cannot verify. Built a shared deterministic 60 Hz sim (`src/play/ufo/sim.js`) used by the browser, the ghost and the server verifier; levels 1 to 30 proven clearable by a bot. Code landed in `22a5a1f49` (swept in by another agent's commit): `api/play/ufo-runs.js`, the `ufo_runs` migration, `game.js`, the page, the `ufo_score` metric on the unified leaderboard and a `/rankings` tab. Follow-up commit adds the test fixes, `docs/play-ufo.md`, STRUCTURE row, pages.json entries and changelog entry. Evidence: 16/16 vitest cases (real handler on PGlite: POST, GET, ghost, tamper, 422, 409), headless Chromium at about 60fps on desktop and Pixel 7 emulation with no console errors. Remaining, owner-gated: migration `20261023150000_ufo_runs.sql` applies with the next approved deploy (`npm run db:status` first); until then the production endpoint returns an error and the page shows its retry state.
+
+## 2026-10-23: order 538 (oracle wallet prior from the database), done
+
+Step 0 measured: the committed prior snapshot dated 2026-06-16 (273 wallets: 128 smart money, 145 KOL), read by `known-wallets.js` through a synchronous JSON load; `gmgn-seed` already upserts `wallet_reputation` daily and was still serving 200 via its kol-quest fallback. `known-wallets.js` now loads the prior from `wallet_reputation` (mainnet, `coins_traded < 5`, labels smart_money/kol/sniper) into an in-process map with a 10 minute TTL (30 seconds after a failed read, last good rows kept), single-flight; `knownWallet()` stays synchronous and callers (`sources.js`, `store.js`, `trades.js`, `pump-fun-mcp.js`) `await loadKnownWallets()` first. An empty table serves an empty prior and logs once. The snapshot file was deleted. `gmgn-seed` now files KOLs as `kol` (score 74) instead of `neutral`, otherwise the 145 KOLs would have dropped out of the prior. Evidence: a live cron run into a PGlite copy of the table fetched 273 wallets and upserted 273 (128 smart_money, 145 neutral before the label fix), the oracle read back 128 as prior; `tests/oracle` 21 files and 282 tests pass in an isolated install; new `tests/oracle/gmgn-seed-prior.test.js` covers cron to prior. Code landed in `22a5a1f49` (swept in by a concurrent agent), the cron label fix and closing files in this commit. Left in place on purpose: the copy-trading directory snapshot and its builder script, which carry names, handles, BSC rows and 30 day PnL that `wallet_reputation` does not hold, and which a different endpoint reads. Production note: existing KOL rows are relabeled `kol` on the next gmgn-seed run after deploy.
+
+## 2026-10-23: order 522 (integrate 23, outbound receipts), done
+
+Step 0: everything but the schema was already committed. Resolver `api/_lib/x402/solana-settlement.js`, cache layer `api/_lib/x402/outbound-receipts.js`, endpoint `api/x402/outbound-receipts.js` landed in `420a88d88`; the Outbound tab on `/receipts` (`pages/receipts.html`, `src/receipts-outbound.js`) in `9e1ff2270`. Closing step: applied only `20261015110000_x402_outbound_resolved.sql` to production with `node scripts/apply-migrations.mjs --apply --file 20261015110000_x402_outbound_resolved.sql` (additive, idempotent; the other pending migrations were left alone). `npm run db:status` lists it applied. Vitest: `tests/solana-settlement.test.js` plus `tests/x402-outbound-receipts.test.js` 22 pass, `tests/x402-outbound-receipts-endpoint.test.js` 6 pass. Row 66 in `production-100-OWNER-ACTIONS.md` is resolved by this apply.
diff --git a/tests/oracle/gmgn-seed-prior.test.js b/tests/oracle/gmgn-seed-prior.test.js
new file mode 100644
index 000000000..5aefffaca
--- /dev/null
+++ b/tests/oracle/gmgn-seed-prior.test.js
@@ -0,0 +1,72 @@
+// api/cron/gmgn-seed.js -> wallet_reputation -> the oracle's known-wallet prior.
+// KOLs must land labelled 'kol' (Oracle counts them proven), not 'neutral', or
+// they silently drop out of the cold-start prior.
+
+import { Readable } from 'node:stream';
+import { afterEach, beforeAll, describe, it, expect, vi } from 'vitest';
+import { createPgliteSql } from '../_helpers/pglite-sql.js';
+
+const holder = vi.hoisted(() => ({ db: null }));
+
+vi.mock('../../api/_lib/db.js', async (importActual) => {
+ const actual = await importActual();
+ return { ...actual, sql: (...args) => holder.db.sql(...args) };
+});
+
+process.env.DATABASE_URL ||= 'postgres://pglite.test/db';
+process.env.CRON_SECRET = 'test-cron-secret';
+
+const seed = (await import('../../api/cron/gmgn-seed.js')).default;
+const { loadKnownWallets, resetKnownWallets, knownWallet } = await import('../../api/_lib/oracle/known-wallets.js');
+
+const W = (n) => `THREEsyntheticWa11et${String(n).padStart(24, '1')}`;
+
+beforeAll(async () => {
+ holder.db = createPgliteSql();
+ await holder.db.exec(`
+ create table wallet_reputation (
+ wallet text not null, network text not null default 'mainnet',
+ coins_traded int not null default 0, smart_money_score numeric not null default 0,
+ label text not null default 'unproven',
+ first_seen_at timestamptz default now(), updated_at timestamptz default now(),
+ primary key (wallet, network)
+ );
+ `);
+});
+
+afterEach(() => vi.unstubAllGlobals());
+
+function run() {
+ const req = Object.assign(new Readable({ read() {} }), {
+ method: 'POST', url: '/api/cron/gmgn-seed',
+ headers: { authorization: 'Bearer test-cron-secret', host: 'three.ws' },
+ });
+ const out = {};
+ const res = {
+ statusCode: 200, headersSent: false, setHeader() {}, getHeader() {},
+ writeHead(s) { res.statusCode = s; }, end(b) { out.body = b; out.status = res.statusCode; },
+ };
+ return seed(req, res).then(() => out);
+}
+
+describe('gmgn-seed feeds the oracle prior', () => {
+ it('files KOLs as kol and serves them with smart money, leaving top_dev out', async () => {
+ const kolQuest = {
+ smartMoney: { wallets: { smart_degen: [{ wallet_address: W(1) }], top_dev: [{ wallet_address: W(3) }] } },
+ kol: { wallets: [{ wallet_address: W(2) }] },
+ };
+ vi.stubGlobal('fetch', async (url) => String(url).includes('raw.githubusercontent.com')
+ ? new Response(JSON.stringify(kolQuest), { status: 200 })
+ : new Response('forbidden', { status: 403 }));
+
+ const out = await run();
+ expect(out.status).toBe(200);
+ expect(JSON.parse(out.body)).toMatchObject({ ok: true, upserted: 3, fallback_used: true });
+
+ resetKnownWallets();
+ await loadKnownWallets();
+ expect(knownWallet(W(1))).toMatchObject({ label: 'smart_money', score: 80 });
+ expect(knownWallet(W(2))).toMatchObject({ label: 'kol', score: 74 });
+ expect(knownWallet(W(3))).toBeNull();
+ }, 60_000);
+});