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
fix: disable deposits for unsignable agent wallets
ni3a84f244000545
diff --git a/api/agents/solana-wallet.js b/api/agents/solana-wallet.jsindex fbea35911..b698fb5b7 100644--- a/api/agents/solana-wallet.js+++ b/api/agents/solana-wallet.js@@ -155,6 +155,29 @@ async function resolveAuth(req) {return null;}+// A deposit address is safe to advertise only when the stored custodial key can+// actually sign for that exact address. Balance reads alone cannot prove this:+// an address whose encryption key was retired still has a perfectly valid,+// publicly-readable on-chain balance. Keep this verdict in the API so every+// funding surface can fail closed instead of independently guessing from the+// presence of an address.+async function walletSigningStatus(meta = {}) {+ if (!meta.solana_address) return { signable: false, reason: 'wallet_missing' };+ if (!meta.encrypted_solana_secret) return { signable: false, reason: 'key_missing' };+ try {+ const keypair = await recoverSolanaAgentKeypair(meta.encrypted_solana_secret);+ if (keypair.publicKey.toBase58() !== meta.solana_address) {+ return { signable: false, reason: 'key_mismatch' };+ }+ return { signable: true, reason: null };+ } catch (e) {+ return {+ signable: false,+ reason: isUnrecoverableSecret(e) ? 'key_retired' : 'key_error',+ };+ }+}+// ── activity ──────────────────────────────────────────────────────────────────async function handleActivity(req, res, id) {@@ -309,10 +332,14 @@ async function handlePublicWalletRead(req, res, id) {wallet: null,balance: null,chain: 'solana',+ deposits_enabled: false,+ deposits_disabled_reason: 'wallet_missing',},});}+ const signing = await walletSigningStatus(row.meta);+let lamports = null;let balanceError = null;const balCacheKey = `sol:bal:${address}:${net}`;@@ -343,6 +370,8 @@ async function handlePublicWalletRead(req, res, id) {chain: 'solana',network: net,lamports,+ deposits_enabled: signing.signable,+ ...(!signing.signable ? { deposits_disabled_reason: signing.reason } : {}),...(balanceError ? { balance_error: balanceError } : {}),},});@@ -470,24 +499,17 @@ async function handleWallet(req, res, id) {? await _reverseSnsCached(meta.solana_address): null;- // Can we still SIGN for this wallet, or are we showing the owner a balance they+ // Can we still SIGN for this wallet, or are we showing a balance whose funds// can never move? A custodial secret sealed under a retired WALLET_ENCRYPTION_KEY// still reads back a perfectly healthy on-chain balance, so the wallet card looked// identical to a working one right up until the owner typed an amount, confirmed a// withdrawal, and got a 500. Measured 2026-08-01: two customer agents holding// 0.35 SOL are in exactly that state. The check is a local AES-GCM attempt on one- // record (no network, sub-millisecond) and runs only on the owner's own read.- let signable = null;- let signableReason = null;- if (meta.encrypted_solana_secret) {- try {- await recoverSolanaAgentKeypair(meta.encrypted_solana_secret);- signable = true;- } catch (e) {- signable = false;- signableReason = isUnrecoverableSecret(e) ? 'key_retired' : 'key_error';- }- }+ // record (no network, sub-millisecond). The public read exposes only the deposit+ // safety verdict; the owner read additionally exposes the signing verdict.+ const signing = await walletSigningStatus(meta);+ const signable = signing.signable;+ const signableReason = signing.reason;return json(res, req.method === 'POST' ? 201 : 200, {data: {@@ -498,6 +520,8 @@ async function handleWallet(req, res, id) {...(balanceError ? { balance_error: balanceError } : {}),signable,...(signableReason ? { signable_reason: signableReason } : {}),+ deposits_enabled: signable,+ ...(!signable ? { deposits_disabled_reason: signableReason } : {}),vanity_prefix: meta.solana_vanity_prefix || null,vanity_suffix: meta.solana_vanity_suffix || null,source: meta.solana_wallet_source || (meta.encrypted_solana_secret ? 'generated' : null),diff --git a/docs/agent-wallets.md b/docs/agent-wallets.mdindex d6033eebf..d89f9549d 100644--- a/docs/agent-wallets.md+++ b/docs/agent-wallets.md@@ -69,7 +69,9 @@ The **Agent Wallet Hub** lives at `/agent/:id/wallet`. Owners see all 23 sectionKey endpoints:-- `GET /api/agents/:id/solana` — address, live balance (public)+- `GET /api/agents/:id/solana` — address, live balance, and `deposits_enabled`+ safety verdict (public). Funding UIs must require `deposits_enabled === true`;+ a missing, false, or unreadable verdict is not safe to fund.- `GET /api/agents/:id/solana/activity` — parsed transaction feed (owner only)- `GET`/`PUT /api/agents/:id/solana/limits` — read and set the spend policy- `POST /api/agents/:id/solana/withdraw` — sweep an asset outdiff --git a/src/agent-wallet-hub/tabs/deposit.js b/src/agent-wallet-hub/tabs/deposit.jsindex 481ec09d2..4e06a86b1 100644--- a/src/agent-wallet-hub/tabs/deposit.js+++ b/src/agent-wallet-hub/tabs/deposit.js@@ -135,6 +135,11 @@ registerWalletTab({const state = {loaded: false,address: ctx.agent?.solana_address || ctx.agent?.meta?.solana_address || null,+ // Funding is enabled only after the API proves that the platform can+ // sign for this exact address. Unknown must fail closed: otherwise a+ // stale address remains fundable during an API error or old deployment.+ depositsEnabled: null,+ depositsDisabledReason: null,amount: '', // user-entered SOL amount for the QR/deep-linkamountError: false,// Live confirmation tracking.@@ -271,6 +276,41 @@ registerWalletTab({return;}+ if (state.depositsEnabled !== true) {+ const reason = state.depositsDisabledReason;+ const knownKeyFailure = ['key_retired', 'key_missing', 'key_mismatch', 'key_error'].includes(reason);+ panel.innerHTML = `+ <div class="awh-card">+ <div class="awh-dep-who">+ ${avatar ? `<img class="awh-dep-who-av" src="${escapeHtml(avatar)}" alt="" loading="lazy" data-fallback="remove" />` : ''}+ <div class="awh-dep-who-txt"><strong>Deposits are disabled for ${escapeHtml(agentName)}.</strong></div>+ </div>+ <div class="awh-err" role="alert">+ <strong>Do not send funds to this wallet.</strong>+ <div class="why" style="text-transform:none; margin-top:6px; line-height:1.5;">+ ${knownKeyFailure+ ? 'The platform cannot authorize outgoing transactions from this address. Existing on-chain funds remain visible, but sending more would leave those funds immovable.'+ : 'The platform could not verify that it can authorize outgoing transactions from this address. Funding controls stay disabled until that safety check succeeds.'}+ </div>+ </div>+ <div class="awh-dep-label" style="margin-top:12px">Disabled wallet address</div>+ <div class="awh-dep-addr" title="${escapeHtml(state.address)}">${escapeHtml(state.address)}</div>+ <div class="awh-dep-actions" style="margin-top:12px">+ <a class="awh-btn" href="${escapeHtml(explorerAddressUrl(state.address, net))}" target="_blank" rel="noopener">View existing funds ↗</a>+ ${ctx.isOwner ? `<a class="awh-btn" href="/support?topic=wallet-key&agent=${encodeURIComponent(ctx.agentId)}">Contact support</a>` : ''}+ <button class="awh-btn" type="button" data-act="reload">Re-check</button>+ </div>+ </div>`;+ panel.querySelector('[data-act="reload"]')?.addEventListener('click', () => {+ state.loaded = false;+ state.depositsEnabled = null;+ state.depositsDisabledReason = null;+ render();+ loadInitial();+ });+ return;+ }+const uri = solanaUri();panel.innerHTML = `<div class="awh-card">@@ -394,18 +434,24 @@ registerWalletTab({} catch {return { ok: false };}- if (!r) return { ok: false };- if (r.status === 'forbidden') return { ok: false, forbidden: true };- if (r.status === 'none') return { ok: true, address: null, sol: null };- if (r.status === 'error') return { ok: false };- if (r.data?.balance_error) return { ok: false };- return { ok: true, address: r.data?.address || null, sol: r.data?.sol ?? null };+ if (!r) return { ok: false, depositsEnabled: false, depositsDisabledReason: 'health_unavailable' };+ if (r.status === 'forbidden') return { ok: false, forbidden: true, depositsEnabled: false, depositsDisabledReason: 'health_unavailable' };+ if (r.status === 'none') return { ok: true, address: null, sol: null, depositsEnabled: false, depositsDisabledReason: 'wallet_missing' };+ if (r.status === 'error') return { ok: false, depositsEnabled: false, depositsDisabledReason: 'health_unavailable' };+ const health = {+ depositsEnabled: r.data?.deposits_enabled === true,+ depositsDisabledReason: r.data?.deposits_disabled_reason || (r.data?.deposits_enabled === true ? null : 'health_unavailable'),+ };+ if (r.data?.balance_error) return { ok: false, address: r.data?.address || null, ...health };+ return { ok: true, address: r.data?.address || null, sol: r.data?.sol ?? null, ...health };}async function loadInitial() {const res = await readBalance();+ state.depositsEnabled = res.depositsEnabled === true;+ state.depositsDisabledReason = res.depositsDisabledReason || null;if (res.ok) {- if (res.address) state.address = res.address;+ state.address = res.address;state.balanceError = false;if (typeof res.sol === 'number') state.baselineSol = res.sol;} else {@@ -420,6 +466,16 @@ registerWalletTab({async function poll() {if (!visible || destroyed || !state.address) return;const res = await readBalance();+ if (res.depositsEnabled !== true) {+ state.depositsEnabled = false;+ state.depositsDisabledReason = res.depositsDisabledReason || 'health_unavailable';+ if (res.address) state.address = res.address;+ state.balanceError = !res.ok;+ render();+ return;+ }+ state.depositsEnabled = true;+ state.depositsDisabledReason = null;if (!res.ok) {if (!state.balanceError) {state.balanceError = true;@@ -483,6 +539,8 @@ registerWalletTab({// A network switch resets the live-confirmation baseline for the new cluster.detachNet = ctx.onNetworkChange(() => {state.loaded = false;+ state.depositsEnabled = null;+ state.depositsDisabledReason = null;state.baselineSol = null;state.received = null;state.receivedCount = 0;diff --git a/src/agent-wallet-hub/tabs/withdraw.js b/src/agent-wallet-hub/tabs/withdraw.jsindex 7a708e16e..0d95ccd8a 100644--- a/src/agent-wallet-hub/tabs/withdraw.js+++ b/src/agent-wallet-hub/tabs/withdraw.js@@ -528,7 +528,7 @@ registerWalletTab({// does not send the field leaves it undefined, which stays null here and// keeps the form exactly as it was: this gate blocks only on a definite no.async function loadSignable() {- const res = await call(`/api/agents/${encodeURIComponent(ctx.agentId)}/wallet?network=${ctx.getNetwork()}`);+ const res = await call(`/api/agents/${encodeURIComponent(ctx.agentId)}/solana?network=${ctx.getNetwork()}`);if (destroyed || !res.ok) return;if (res.data?.signable === false) {state.signable = false;diff --git a/tests/agent-wallet-deposit-tab.test.js b/tests/agent-wallet-deposit-tab.test.jsindex efe7cc4c8..1a1722e36 100644--- a/tests/agent-wallet-deposit-tab.test.js+++ b/tests/agent-wallet-deposit-tab.test.js@@ -82,7 +82,7 @@ describe('Deposit tab — public funding surface', () => {});it('renders the QR, address, copy control and who-you-are-funding header', async () => {- fetchAgentSolanaWallet.mockResolvedValue({ status: 'ok', data: { address: ADDR, sol: 0 } });+ fetchAgentSolanaWallet.mockResolvedValue({ status: 'ok', data: { address: ADDR, sol: 0, deposits_enabled: true } });const { panel, inst } = mountTab();inst.onShow();await tick();@@ -99,7 +99,7 @@ describe('Deposit tab — public funding surface', () => {});it('shows the calm "waiting for your first deposit" state before any funds land', async () => {- fetchAgentSolanaWallet.mockResolvedValue({ status: 'ok', data: { address: ADDR, sol: 0 } });+ fetchAgentSolanaWallet.mockResolvedValue({ status: 'ok', data: { address: ADDR, sol: 0, deposits_enabled: true } });const { panel, inst } = mountTab();inst.onShow();await tick();@@ -111,7 +111,7 @@ describe('Deposit tab — public funding surface', () => {it('rewrites the deep-link with ?amount= when an amount is entered', async () => {vi.useFakeTimers();try {- fetchAgentSolanaWallet.mockResolvedValue({ status: 'ok', data: { address: ADDR, sol: 0 } });+ fetchAgentSolanaWallet.mockResolvedValue({ status: 'ok', data: { address: ADDR, sol: 0, deposits_enabled: true } });const { panel, inst } = mountTab();inst.onShow();await vi.runOnlyPendingTimersAsync();@@ -133,7 +133,7 @@ describe('Deposit tab — public funding surface', () => {it('fires the "received" confirmation only on a real balance increase', async () => {vi.useFakeTimers();try {- fetchAgentSolanaWallet.mockResolvedValueOnce({ status: 'ok', data: { address: ADDR, sol: 0 } });+ fetchAgentSolanaWallet.mockResolvedValue({ status: 'ok', data: { address: ADDR, sol: 0, deposits_enabled: true } });const ctx = makeCtx();const { panel, inst } = mountTab(ctx);inst.onShow();@@ -142,7 +142,7 @@ describe('Deposit tab — public funding surface', () => {expect(ctx.toast).not.toHaveBeenCalled();// Next poll observes a real on-chain increase.- fetchAgentSolanaWallet.mockResolvedValue({ status: 'ok', data: { address: ADDR, sol: 0.5 } });+ fetchAgentSolanaWallet.mockResolvedValue({ status: 'ok', data: { address: ADDR, sol: 0.5, deposits_enabled: true } });await vi.advanceTimersByTimeAsync(15_000);await vi.runOnlyPendingTimersAsync();@@ -155,20 +155,42 @@ describe('Deposit tab — public funding surface', () => {}});- it('keeps the address + QR usable and shows a paused state when the RPC is unreachable', async () => {+ it('fails closed without funding controls when wallet health cannot be verified', async () => {fetchAgentSolanaWallet.mockResolvedValue({ status: 'error', error: 'rpc down' });const { panel, inst } = mountTab();inst.onShow();await tick();- // Address comes from the agent record, so funding still works.+ // The address may remain visible for identification, but it cannot be copied,+ // encoded in a QR/deep-link, or tipped until the API proves it is signable.expect(panel.textContent).toContain(ADDR);- expect(panel.querySelector('a.awh-dep-qr svg')).toBeTruthy();- expect(panel.querySelector('.awh-dep-status[data-state="paused"]')).toBeTruthy();+ expect(panel.textContent).toMatch(/Do not send funds/i);+ expect(panel.querySelector('a.awh-dep-qr')).toBeNull();+ expect(panel.querySelector('[data-host="deeplink"]')).toBeNull();+ expect(panel.querySelector('[data-act="copy"]')).toBeNull();+ expect(panel.querySelector('[data-act="tip"]')).toBeNull();+ inst.destroy();+ });++ it('removes every funding affordance for a retired-key wallet', async () => {+ fetchAgentSolanaWallet.mockResolvedValue({+ status: 'ok',+ data: { address: ADDR, sol: 1, deposits_enabled: false, deposits_disabled_reason: 'key_retired' },+ });+ const { panel, inst } = mountTab();+ inst.onShow();+ await tick();++ expect(panel.textContent).toMatch(/Deposits are disabled/i);+ expect(panel.textContent).toMatch(/Do not send funds/i);+ expect(panel.querySelector('a.awh-dep-qr')).toBeNull();+ expect(panel.querySelector('[data-host="deeplink"]')).toBeNull();+ expect(panel.querySelector('[data-act="copy"]')).toBeNull();+ expect(panel.querySelector('[data-act="tip"]')).toBeNull();inst.destroy();});it('never throws or blanks the panel on an extreme agent name (QR stays scannable)', async () => {- fetchAgentSolanaWallet.mockResolvedValue({ status: 'ok', data: { address: ADDR, sol: 0 } });+ fetchAgentSolanaWallet.mockResolvedValue({ status: 'ok', data: { address: ADDR, sol: 0, deposits_enabled: true } });const longName = '🚀'.repeat(300); // emoji → 4 bytes each, far past QR capacityconst ctx = makeCtx({ agent: { id: 'agent-1', name: longName, solana_address: ADDR } });const { panel, inst } = mountTab(ctx);diff --git a/tests/api/solana-wallet-balance.test.js b/tests/api/solana-wallet-balance.test.jsindex aa42fcb61..d91598a44 100644--- a/tests/api/solana-wallet-balance.test.js+++ b/tests/api/solana-wallet-balance.test.js@@ -16,6 +16,7 @@ const addr = () => Keypair.generate().publicKey.toBase58();// Shared, mutable RPC stub state — defined before vi.mock so the (lazy) mock// factory closes over it, matching the pattern in solana-wallet-import.test.js.const rpcState = { lamports: 0, calls: 0, err: null };+const keyState = { err: null, addressOverride: null };vi.mock('../../api/_lib/auth.js', () => ({getSessionUser: vi.fn(async () => null),@@ -47,11 +48,15 @@ vi.mock('../../api/_lib/agent-pumpfun.js', () => {return rpcState.lamports;},});- return { solanaConnection: () => conn(), solanaPublicConnection: () => conn() };+ return { solanaConnection: () => conn(), solanaPublicConnection: () => conn(), isUnrecoverableSecret: (e) => e?.name === 'OperationError' };});vi.mock('../../api/_lib/agent-wallet.js', () => ({generateSolanaAgentWallet: vi.fn(async () => ({ address: 'x', encrypted_secret: 'y' })),+ recoverSolanaAgentKeypair: vi.fn(async (secret) => {+ if (keyState.err) throw keyState.err;+ return { publicKey: { toBase58: () => keyState.addressOverride || secret } };+ }),}));const { default: handler } = await import('../../api/agents/solana-wallet.js');@@ -72,7 +77,7 @@ function makeRes() {}async function read(address, network = 'mainnet') {// Unique address per call keeps the shared cache from leaking across tests.- sqlState.queue.push([{ id: 'agent-1', meta: { solana_address: address } }]);+ sqlState.queue.push([{ id: 'agent-1', meta: { solana_address: address, encrypted_solana_secret: address } }]);const req = makeReq(`/api/agents/agent-1/solana?network=${network}`);const res = makeRes();await handler(req, res, 'agent-1');@@ -83,6 +88,8 @@ beforeEach(() => {rpcState.lamports = 0;rpcState.calls = 0;rpcState.err = null;+ keyState.err = null;+ keyState.addressOverride = null;sqlState.queue = [];});@@ -94,6 +101,7 @@ describe('GET /api/agents/:id/solana — public balance read', () => {expect(body.data.balance).toBe(2.5);expect(body.data.lamports).toBe(2_500_000_000);expect(body.data.balance_error).toBeUndefined();+ expect(body.data.deposits_enabled).toBe(true);});it('surfaces balance_error=rpc_rate_limited when the RPC 429s on every attempt', async () => {@@ -123,4 +131,19 @@ describe('GET /api/agents/:id/solana — public balance read', () => {expect(second.body.data.balance).toBe(1);expect(rpcState.calls).toBe(callsAfterFirst); // no additional RPC call});++ it('disables deposits when the custodial key is retired', async () => {+ keyState.err = Object.assign(new Error('decrypt failed'), { name: 'OperationError' });+ const { status, body } = await read(addr());+ expect(status).toBe(200);+ expect(body.data.deposits_enabled).toBe(false);+ expect(body.data.deposits_disabled_reason).toBe('key_retired');+ });++ it('disables deposits when the recovered key does not own the advertised address', async () => {+ keyState.addressOverride = addr();+ const { body } = await read(addr());+ expect(body.data.deposits_enabled).toBe(false);+ expect(body.data.deposits_disabled_reason).toBe('key_mismatch');+ });});