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
docs(ops): write the economy wallet rotation runbook
nirholas0bfa14b2c3f7
diff --git a/docs/ops/economy-wallet-rotation.md b/docs/ops/economy-wallet-rotation.mdnew file mode 100644index 000000000..8ead89d72--- /dev/null+++ b/docs/ops/economy-wallet-rotation.md@@ -0,0 +1,96 @@+# Economy wallet registry and rotation++Every Solana wallet the platform spends from is defined in+[`api/_lib/solana-signers.js`](../../api/_lib/solana-signers.js): a role name, the+env var holding its secret, what it pays for, and the SOL floor it must keep.+That file answers "what does the economy use right now". It cannot answer "what+did the economy use in July", because rotating a signer overwrites an env var and+the previous address survives nowhere.++`economy_wallet_registry` is the missing half: a durable, append-only log of every+wallet each role has ever held, with the lineage between them. Reconciling an old+settle, attributing a fee, or proving which wallet received a payment last quarter+is now a query instead of an archaeology session on the chain.++**No secret material is ever stored in the registry.** A row records the public+address and *where* the secret lives (an env var name, or the 0600 file a freshly+generated key was written to). Nothing in this flow reads or writes Secret+Manager, and nothing puts a key into production for you: the cutover command is+printed for a human to run, because installing a live signing key is a deliberate+act.++- Schema: [`api/_lib/migrations/20260819010000_economy_wallet_registry.sql`](../../api/_lib/migrations/20260819010000_economy_wallet_registry.sql)+- Operator surface: [`scripts/economy-wallets.mjs`](../../scripts/economy-wallets.mjs) (`npm run economy:wallets`)+- Related: [economy funding root](../economy-master.md), [money map](../money-map.md), [x402 ring economy](../x402-ring-economy.md)++## Commands++```bash+npm run economy:wallets -- list # whole registry, newest first per role+npm run economy:wallets -- list --role economy-master # one role's history++# log a wallet that is already live (backfill, or an imported wallet)+npm run economy:wallets -- record --role economy-master --address <pubkey> --status active++# generate a fresh wallet for a role, logged as pending, production untouched+npm run economy:wallets -- new --role economy-master --vanity www++# flip a pending wallet to live AFTER it is funded and its env var is set+npm run economy:wallets -- activate --role economy-master --address <pubkey>++npm run economy:wallets -- retire --role economy-master --address <pubkey>+```++`--vanity` grinds a case-insensitive address prefix (up to 4 characters) so a+rotated wallet keeps the house `www…` look. Three characters takes a few seconds.++A unique partial index enforces **exactly one active wallet per role per+network**, so a half-finished rotation cannot be left behind: `activate` retires+the predecessor in the same step, and a second concurrent activation fails loudly+rather than leaving two wallets both claiming to be live.++## Rotating a role++Order matters. Funding first and env last means the window where production holds+a key to an empty wallet is zero.++1. **Generate.** `npm run economy:wallets -- new --role <role>`. The secret lands+ in `~/.three-ws-wallets/<role>.<pubkey>.env` (mode 0600, outside the repo). The+ address is logged as `pending` with `rotated_from` pointing at the incumbent.+2. **Fund it** to at least the role's `minSol` floor. Below the floor the wallet+ is live but useless: the sponsor stops settling, and an engine stalls.+3. **Sweep the old wallet** if the role carries `holdsTokens` (the x402 ring+ treasury holds the USDC float). Skipping this strands the float at an address+ production no longer reads.+4. **Set the env var**, including every alias for that role (see below), with a+ single `gcloud run services update --update-env-vars`. Never+ `--set-env-vars`: it replaces the entire env set.+5. **Activate** in the registry, then verify with `npm run audit:service-wallets`,+ which derives each pubkey from the secret production actually holds and+ cross-checks it against what the live 402 challenges advertise.++## Roles read through more than one env var++One physical wallet can be read through several vars. Rotating the role means+moving all of them in the same cutover, because a 402 challenge that advertises+one address while the server co-signs with another fails every settle against it.++| Role | Vars that must move together |+| --- | --- |+| `economy-master` | `ECONOMY_MASTER_SECRET_BASE58` (secret), `X402_FEE_PAYER_SOLANA` (advertised fee payer) |+| `pump-x402-launcher` (the x402 ring treasury) | `PUMP_X402_LAUNCHER_SECRET_KEY_B64` (secret), `X402_TREASURY_SECRET_BASE58` (same key, base58), `X402_PAY_TO_SOLANA` (advertised receiver) |++`npm run economy:wallets -- new` prints the alias set for the role it is+generating, so this table is a reference rather than something to remember.++## Why the master is the one to be careful with++The economy master is also the x402 sponsor fee payer. Below+`X402_SPONSOR_SOL_FLOOR_LAMPORTS` the self-facilitator refuses to settle and+`buildRequirements()` withdraws the Solana accept from every 402 challenge, so+Solana-only paid endpoints return `settlement_unavailable` and every other paid+endpoint quietly degrades to Base-only. The outward symptom is not a clean+outage, which is exactly why the runway alert in+[`api/_lib/x402/sponsor-runway.js`](../../api/_lib/x402/sponsor-runway.js) measures+days-to-floor rather than days-to-zero. Rotate the master only with the+replacement already funded above its floor.diff --git a/scripts/dev-skeleton-shot.mjs b/scripts/dev-skeleton-shot.mjsnew file mode 100644index 000000000..178f5df64--- /dev/null+++ b/scripts/dev-skeleton-shot.mjs@@ -0,0 +1,12 @@+import { chromium } from 'playwright';+const OUT = process.env.SHOT_DIR || process.cwd();+const b = await chromium.launch();+const p = await b.newPage({ viewport: { width: 1440, height: 900 } });+// Hold the entity fetch open so the skeleton is what the camera sees.+await p.route('**/api/agents/**', async (r) => { await new Promise((s) => setTimeout(s, 9000)); r.continue(); });+p.goto(process.argv[2], { waitUntil: 'commit' }).catch(() => {});+await p.waitForTimeout(3500);+await p.screenshot({ path: `${OUT}/v2-skeleton.png` });+console.log('aria-busy:', await p.$eval('#av-shell', (n) => n.getAttribute('aria-busy')));+console.log('status text:', await p.$eval('[role="status"]', (n) => n.innerText.trim()).catch(() => 'none'));+await b.close();