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.
JavaScript 3d-generationai-agentsanimationavatardigital-humangenerative-aiglbgltfimage-to-3dllmmcpmcp-servermodel-context-protocolsolanatext-to-3dthreejsweb-componentswebglwebxrx402
feat(ops): add the economy wallet registry operator surface
nirholas936393d7b92a
diff --git a/scripts/dev-screenshot.mjs b/scripts/dev-screenshot.mjsnew file mode 100644index 000000000..af67f4da5--- /dev/null+++ b/scripts/dev-screenshot.mjs@@ -0,0 +1,17 @@+import { chromium } from 'playwright';+const OUT = process.env.SHOT_DIR || process.cwd();+const b = await chromium.launch();+for (const t of process.argv.slice(2)) {+ const [url, name, w] = t.split('::');+ const p = await b.newPage({ viewport: { width: Number(w) || 1440, height: 1400 } });+ const errs = [];+ p.on('pageerror', (e) => errs.push('pageerror: ' + e.message));+ p.on('console', (m) => { if (m.type() === 'error' && !m.text().includes('WebSocket')) errs.push('err: ' + m.text().slice(0, 160)); });+ await p.goto(url, { waitUntil: 'domcontentloaded', timeout: 45000 }).catch((e) => console.log('nav', e.message.split('\n')[0]));+ await p.waitForTimeout(7000);+ await p.screenshot({ path: `${OUT}/${name}.png`, fullPage: true });+ console.log('--- ' + name + ' | ' + p.url());+ errs.slice(0, 6).forEach((e) => console.log(' ' + e));+ await p.close();+}+await b.close();diff --git a/scripts/economy-wallets.mjs b/scripts/economy-wallets.mjsnew file mode 100644index 000000000..27121afcf--- /dev/null+++ b/scripts/economy-wallets.mjs@@ -0,0 +1,270 @@+#!/usr/bin/env node+// The economy wallet registry: generate fresh platform wallets, and keep a+// permanent log of every wallet the economy has ever used.+// ---------------------------------------------------------------------------+// Before this script the only record of a platform wallet was the env var+// holding its secret. Rotating a signer overwrote that var, and the previous+// address survived nowhere: reconciling an old settle or a July fee meant+// reading the chain and guessing. `economy_wallet_registry` (migration+// 20260819010000) is the durable log, and this is its operator surface.+//+// Roles are the signer names in api/_lib/solana-signers.js, which stays the+// source of truth for what each wallet pays for and the SOL floor it must hold.+//+// SECRET HANDLING: a generated secret is written to ONE file outside the repo+// with mode 0600 and is never printed, never logged, and never stored in the+// database. The registry records only the public address and WHERE the secret+// lives. Nothing here reads or writes Secret Manager or Cloud Run; the cutover+// command is printed for an operator to run, because putting a live signing key+// into production is a deliberate human act.+//+// Usage:+// npm run economy:wallets -- list+// npm run economy:wallets -- record --role economy-master --address <pubkey> --status active+// npm run economy:wallets -- new --role economy-master [--vanity www] [--out <dir>]+// npm run economy:wallets -- activate --role economy-master --address <pubkey>+// npm run economy:wallets -- retire --role economy-master --address <pubkey>+//+// `new` never touches production. It generates, logs the address as `pending`,+// and prints the two steps that make it live (fund it, then set the env var).++import { chmodSync, mkdirSync, writeFileSync } from 'node:fs';+import { homedir } from 'node:os';+import { join, resolve } from 'node:path';+import { Keypair } from '@solana/web3.js';+import bs58 from 'bs58';+import { SOLANA_SIGNERS } from '../api/_lib/solana-signers.js';+import { sql } from '../api/_lib/db.js';++const NETWORK = 'solana-mainnet';++// Some roles are ONE physical wallet read through several env vars. Rotating the+// role means moving every var in the set in the same cutover: the x402 ring+// advertises its receiver publicly (X402_PAY_TO_SOLANA) and co-signs with the+// matching secret, and a challenge that advertises one address while the server+// signs with another fails every settle against it. api/_lib/solana-signers.js+// documents the shared identity; this map is what an operator must not forget.+const ROLE_ALIAS_VARS = {+ 'pump-x402-launcher': ['X402_PAY_TO_SOLANA (public address)', 'X402_TREASURY_SECRET_BASE58 (same secret, base58)'],+ 'economy-master': ['X402_FEE_PAYER_SOLANA (public address, advertised on every 402 challenge)'],+};+const SERVICE = 'three-ws-api';+const REGION = 'us-central1';+const PROJECT = 'aerial-vehicle-466722-p5';++function parseArgs(argv) {+ const [command, ...rest] = argv;+ const flags = {};+ for (let i = 0; i < rest.length; i++) {+ const token = rest[i];+ if (!token.startsWith('--')) continue;+ const eq = token.indexOf('=');+ if (eq > 2) {+ flags[token.slice(2, eq)] = token.slice(eq + 1);+ continue;+ }+ const name = token.slice(2);+ // Collect every following token up to the next flag, so an unquoted+ // multi-word value (npm strips one layer of quoting) survives intact.+ const words = [];+ while (i + 1 < rest.length && !rest[i + 1].startsWith('--')) words.push(rest[++i]);+ flags[name] = words.length ? words.join(' ') : true;+ }+ return { command, flags };+}++function specFor(role) {+ const spec = SOLANA_SIGNERS.find((s) => s.name === role);+ if (!spec) {+ const names = SOLANA_SIGNERS.map((s) => s.name).join(', ');+ throw new Error(`unknown role "${role}". Known roles: ${names}`);+ }+ return spec;+}++/** Encode a 64-byte secret key the way the role's env var is named. */+function encodeSecret(envVar, secretKey) {+ if (envVar.endsWith('_BASE58')) return bs58.encode(secretKey);+ return Buffer.from(secretKey).toString('base64');+}++/**+ * Grind a keypair until its address starts with `prefix` (case-insensitive).+ * Base58 has no vowel-free shortcuts, so a 3-character prefix is the practical+ * ceiling for an interactive run; anything longer is left to a dedicated tool.+ */+function generate(prefix) {+ if (!prefix) return Keypair.generate();+ const want = String(prefix).toLowerCase();+ if (want.length > 4) throw new Error('--vanity longer than 4 characters takes too long here');+ for (;;) {+ const kp = Keypair.generate();+ if (kp.publicKey.toBase58().toLowerCase().startsWith(want)) return kp;+ }+}++async function list(flags) {+ const role = flags.role || null;+ const rows = role+ ? await sql`select * from economy_wallet_registry where role = ${role} order by role, created_at desc`+ : await sql`select * from economy_wallet_registry order by role, created_at desc`;+ if (!rows.length) {+ console.log('registry is empty. Record the live wallets first:');+ console.log(' npm run economy:wallets -- record --role <role> --address <pubkey> --status active');+ return;+ }+ console.log(`economy wallet registry (${rows.length} row(s))`);+ console.log('='.repeat(78));+ let currentRole = null;+ for (const r of rows) {+ if (r.role !== currentRole) {+ currentRole = r.role;+ console.log(`\n${r.role}`);+ }+ const mark = r.status === 'active' ? '●' : r.status === 'pending' ? '○' : '·';+ const when = (r.activated_at || r.created_at).toISOString().slice(0, 10);+ console.log(` ${mark} ${r.status.padEnd(7)} ${r.address} ${when}${r.rotated_from ? ` (rotated from ${r.rotated_from})` : ''}`);+ if (r.env_var) console.log(` secret: ${r.secret_location || r.env_var}`);+ }+}++async function record(flags) {+ const role = requireFlag(flags, 'role');+ const address = requireFlag(flags, 'address');+ const spec = specFor(role);+ const status = flags.status || 'active';+ if (!['pending', 'active', 'retired'].includes(status)) throw new Error(`bad --status "${status}"`);+ if (status === 'active') await retireActive(role, address);+ const rows = await sql`+ insert into economy_wallet_registry+ (role, address, network, status, env_var, secret_location, purpose, notes, activated_at)+ values (+ ${role}, ${address}, ${NETWORK}, ${status}, ${spec.env},+ ${flags['secret-location'] || `cloud-run env ${spec.env}`},+ ${spec.purpose}, ${flags.notes || null},+ ${status === 'active' ? new Date().toISOString() : null}+ )+ on conflict (role, address, network) do update+ set status = excluded.status,+ env_var = excluded.env_var,+ secret_location = coalesce(excluded.secret_location, economy_wallet_registry.secret_location),+ purpose = excluded.purpose,+ notes = coalesce(excluded.notes, economy_wallet_registry.notes),+ activated_at = coalesce(economy_wallet_registry.activated_at, excluded.activated_at)+ returning id, status`;+ console.log(`recorded ${role} ${address} as ${rows[0].status}`);+}++/** Retire whatever currently holds the active slot for a role. */+async function retireActive(role, except) {+ const rows = await sql`+ update economy_wallet_registry+ set status = 'retired', retired_at = now()+ where role = ${role} and network = ${NETWORK} and status = 'active'+ and address <> ${except || ''}+ returning address`;+ for (const r of rows) console.log(`retired previous ${role} wallet ${r.address}`);+ return rows.map((r) => r.address)[0] || null;+}++async function newWallet(flags) {+ const role = requireFlag(flags, 'role');+ const spec = specFor(role);+ const outDir = resolve(String(flags.out || join(homedir(), '.three-ws-wallets')));+ const kp = generate(flags.vanity === true ? null : flags.vanity);+ const address = kp.publicKey.toBase58();+ const encoded = encodeSecret(spec.env, kp.secretKey);++ mkdirSync(outDir, { recursive: true, mode: 0o700 });+ const outFile = join(outDir, `${role}.${address}.env`);+ writeFileSync(outFile, `${spec.env}=${encoded}\n`, { mode: 0o600 });+ chmodSync(outFile, 0o600);++ const [previous] = await sql`+ select address from economy_wallet_registry+ where role = ${role} and network = ${NETWORK} and status = 'active' limit 1`;++ await sql`+ insert into economy_wallet_registry+ (role, address, network, status, env_var, secret_location, purpose, rotated_from, notes)+ values (${role}, ${address}, ${NETWORK}, 'pending', ${spec.env}, ${outFile}, ${spec.purpose},+ ${previous?.address || null}, ${flags.notes || 'generated by scripts/economy-wallets.mjs'})+ on conflict (role, address, network) do nothing`;++ console.log(`\nfresh ${role} wallet`);+ console.log('='.repeat(78));+ console.log(` address ${address}`);+ console.log(` secret file ${outFile} (mode 0600, outside the repo, never committed)`);+ console.log(` env var ${spec.env}`);+ console.log(` needs ${spec.minSol} SOL to clear its floor${spec.isMaster ? ' (funding root: fund it first)' : ''}`);+ if (previous) console.log(` replaces ${previous.address}`);+ console.log('\nlogged as pending. To make it live:');+ console.log(` 1. fund ${address} with at least ${spec.minSol} SOL`);+ console.log(` 2. gcloud run services update ${SERVICE} --region ${REGION} --project ${PROJECT} \\`);+ console.log(` --update-env-vars "${spec.env}=$(cut -d= -f2- ${outFile})"`);+ console.log(` 3. npm run economy:wallets -- activate --role ${role} --address ${address}`);+ const aliases = ROLE_ALIAS_VARS[role];+ if (aliases) {+ console.log('\n This role is read through more than one env var. Move them together,');+ console.log(' or the challenge advertises one address while the server signs with another:');+ for (const alias of aliases) console.log(` ${alias}`);+ }+ if (spec.holdsTokens) {+ console.log('\n This role HOLDS token balances. Sweep the old wallet before retiring it,');+ console.log(' or the float stays stranded at the previous address.');+ }+}++async function activate(flags) {+ const role = requireFlag(flags, 'role');+ const address = requireFlag(flags, 'address');+ specFor(role);+ const [row] = await sql`+ select status from economy_wallet_registry+ where role = ${role} and address = ${address} and network = ${NETWORK} limit 1`;+ if (!row) throw new Error(`${role} ${address} is not in the registry. Record or generate it first.`);+ const previous = await retireActive(role, address);+ await sql`+ update economy_wallet_registry+ set status = 'active', activated_at = coalesce(activated_at, now()), retired_at = null,+ rotated_from = coalesce(rotated_from, ${previous})+ where role = ${role} and address = ${address} and network = ${NETWORK}`;+ console.log(`${role} is now ${address}`);+ console.log('Confirm production agrees before trusting it:');+ console.log(' npm run audit:service-wallets');+}++async function retire(flags) {+ const role = requireFlag(flags, 'role');+ const address = requireFlag(flags, 'address');+ const rows = await sql`+ update economy_wallet_registry+ set status = 'retired', retired_at = now()+ where role = ${role} and address = ${address} and network = ${NETWORK}+ returning address`;+ if (!rows.length) throw new Error(`${role} ${address} is not in the registry`);+ console.log(`retired ${role} ${address}`);+}++function requireFlag(flags, name) {+ const value = flags[name];+ if (!value || value === true) throw new Error(`--${name} is required`);+ return String(value);+}++const { command, flags } = parseArgs(process.argv.slice(2));+const commands = { list, record, new: newWallet, activate, retire };+const run = commands[command];++if (!run) {+ console.error('usage: npm run economy:wallets -- <list|record|new|activate|retire> [flags]');+ console.error(' see the header of scripts/economy-wallets.mjs for every flag');+ process.exit(1);+}++try {+ await run(flags);+} catch (err) {+ console.error(`economy:wallets ${command}: ${err.message}`);+ process.exit(1);+}