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
/**
* Persona↔wallet binding — every embodied persona (api/_lib/persona-store.js)
* carries a real, deterministic Solana wallet and an on-chain identity: balance,
* ERC-8004-style reputation, token holdings, and a resolved SNS nameplate. The
* SAME persona_id always re-derives the SAME wallet, on any instance, forever —
* with NO private key ever stored anywhere and NO private key ever appearing in
* a tool response, a log line, or an error message.
*
* ── Deterministic derivation (the binding scheme) ────────────────────────────
* seed = HMAC-SHA256(PERSONA_WALLET_SECRET, "three.ws:persona-wallet:v1:" + personaId)
* keypair = Ed25519 Keypair.fromSeed(seed) // Solana's Keypair.fromSeed takes
* // exactly a 32-byte seed — SHA-256's
* // digest length, no truncation needed.
*
* This is a stateless HD-wallet-style derivation, not a stored secret: recovery
* needs only the persona_id (public) and the server's PERSONA_WALLET_SECRET
* (never leaves the server). Nothing is written to disk or a database to make a
* persona wallet "exist" — `personaWalletAddress` is a pure function of its
* input. The keypair object itself is constructed on demand, used for exactly
* one signature, and immediately falls out of scope — this module never returns
* it, logs it, or stores it on any object that escapes the function that made it.
*
* ── Domain separation ────────────────────────────────────────────────────────
* The HMAC "info" string embeds a fixed namespace + version, so this derivation
* can never collide with any other HMAC/derivation elsewhere in the codebase
* even if PERSONA_WALLET_SECRET happens to equal another module's secret (e.g.
* the WALLET_ENCRYPTION_KEY fallback in dev).
*/
import { createHmac } from 'node:crypto';
import { Keypair, PublicKey, LAMPORTS_PER_SOL } from '@solana/web3.js';
import {
getAssociatedTokenAddressSync, createTransferCheckedInstruction,
createAssociatedTokenAccountIdempotentInstruction, TOKEN_PROGRAM_ID,
} from '@solana/spl-token';
import { env } from './env.js';
import { solanaConnection } from './agent-pumpfun.js';
import { submitProtected } from './execution-engine.js';
import { USDC_MINT_BY_NETWORK, USDC_DECIMALS } from './vault-jupiter.js';
import { valuateHoldings } from './portfolio.js';
import { solUsdPrice, explorerAccountUrl, explorerTxUrl } from './avatar-wallet.js';
import { solanaReputation } from '../_mcp/tools/solana.js';
import { reservePersonaSpend, finalizePersonaSpend, releasePersonaSpend, defaultSessionId, PERSONA_SPEND_CAPS } from './persona-spend-ledger.js';
import { fetchUpstreamJson } from './upstream-fetch.js';
const HMAC_DOMAIN = 'three.ws:persona-wallet:v1:';
const SNS_API = 'https://sns-api.bonfida.com';
function netOf(network) {
return network === 'devnet' ? 'devnet' : 'mainnet';
}
/**
* Derive the persona's 32-byte Ed25519 seed. Never exported — the seed is as
* sensitive as the private key it produces (Keypair.fromSeed is deterministic),
* so it stays fully inside this module's private call graph.
*/
function derivePersonaSeed(personaId) {
const secret = env.PERSONA_WALLET_SECRET;
if (!secret) {
throw Object.assign(new Error('persona wallets are not configured (PERSONA_WALLET_SECRET/WALLET_ENCRYPTION_KEY/JWT_SECRET unset)'), {
code: 'no_persona_wallet_secret',
});
}
return createHmac('sha256', secret).update(HMAC_DOMAIN + personaId).digest();
}
/**
* Construct the persona's keypair, hand it to `fn`, then let it be
* garbage-collected. `fn` MUST NOT return the Keypair, its secretKey, or any
* derivative of the secret bytes — only `fn`'s own return value escapes this
* function. This is the ONLY place a persona's signing key is ever constructed.
*/
async function withPersonaKeypair(personaId, fn) {
const seed = derivePersonaSeed(personaId);
const keypair = Keypair.fromSeed(seed);
return fn(keypair);
}
/** The persona's Solana address — deterministic, public, safe to log/return. */
export function personaWalletAddress(personaId) {
const seed = derivePersonaSeed(personaId);
// Ed25519 public key derivation from a seed touches no secret material beyond
// what Keypair.fromSeed already computes; .publicKey is safe to expose.
return Keypair.fromSeed(seed).publicKey.toBase58();
}
// ── on-chain reads ────────────────────────────────────────────────────────────
/** Native SOL + USDC balance for a persona's address. Never throws. */
export async function getPersonaBalances(address, network = 'mainnet') {
const net = netOf(network);
const conn = solanaConnection(net);
const pk = new PublicKey(address);
let sol = 0;
try {
sol = (await conn.getBalance(pk, 'confirmed')) / LAMPORTS_PER_SOL;
} catch { /* RPC hiccup — report 0, never fabricate */ }
let usdc = 0;
try {
const mint = new PublicKey(USDC_MINT_BY_NETWORK[net]);
const ata = getAssociatedTokenAddressSync(mint, pk, false, TOKEN_PROGRAM_ID);
const info = await conn.getTokenAccountBalance(ata, 'confirmed').catch(() => null);
usdc = info?.value?.uiAmount || 0;
} catch { /* no ATA yet, or RPC hiccup — 0 is honest */ }
let solUsd = null;
try { solUsd = await solUsdPrice(); } catch { solUsd = null; }
return {
sol, usdc,
sol_usd: solUsd != null ? Number((sol * solUsd).toFixed(4)) : null,
total_usd: solUsd != null ? Number((sol * solUsd + usdc).toFixed(4)) : null,
};
}
/**
* ERC-8004-style reputation, reusing the SAME computed-summary path the paid
* `solana_agent_reputation` tool exposes (api/_mcp/tools/solana.js), keyed by
* the persona's own wallet address as its attestation identity. A freshly
* derived persona wallet legitimately has zero attestations until someone
* memos one to it — that is real data, not an error.
*/
export async function getPersonaReputation(address, network = 'mainnet') {
try {
return await solanaReputation(address, netOf(network));
} catch {
// No database configured (local/dev) or an RPC hiccup — degrade to the
// same honest zero-state shape the live path would report for a fresh
// wallet, rather than surfacing an internal error to a chat turn.
return {
agent: address, network: netOf(network),
feedback: { total: 0, verified: 0, disputed: 0, score_avg: 0, score_avg_verified: 0 },
validation: { passed: 0, failed: 0 },
degraded: true,
};
}
}
/** Live holdings (SOL + every priced SPL token) for a persona's address. */
export async function getPersonaHoldings(address, network = 'mainnet') {
try {
const { holdings, solUsd } = await valuateHoldings({ network: netOf(network), address });
const priced = holdings.filter((h) => h.usd != null);
const totalUsd = priced.reduce((sum, h) => sum + h.usd, 0);
return {
count: holdings.length,
total_usd: Number(totalUsd.toFixed(4)),
sol_usd_price: solUsd,
top: [...holdings].sort((a, b) => (b.usd ?? -1) - (a.usd ?? -1)).slice(0, 5).map((h) => ({
symbol: h.symbol || null, mint: h.mint || null, amount: h.amount, usd: h.usd ?? null,
})),
degraded: false,
};
} catch {
return { count: 0, total_usd: 0, sol_usd_price: null, top: [], degraded: true };
}
}
/**
* A verified SNS (Solana Name Service) nameplate for the persona's address,
* reusing the same Bonfida source `ens_sns_resolve` reads from — in reverse:
* given the address, does it hold a favourite .sol domain? ENS reverse lookup
* does not apply here (persona wallets are Solana addresses, not 0x EVM
* addresses); when a persona's wallet is bridged to an EVM identity in the
* future, the same ens_sns_resolve forward path already covers .eth names.
* Best-effort — a Bonfida outage degrades to `{ name: null, verified: false }`,
* never an error.
*/
export async function getPersonaNameplate(address) {
try {
const body = await fetchUpstreamJson(`${SNS_API}/v2/user/fav-domains/${address}`, {}, { name: 'bonfida-sns', timeoutMs: 5_000, attempts: 2 });
const fav = body?.[address] || body?.data?.[address] || null;
const name = typeof fav === 'string' ? fav : fav?.domain || fav?.name || null;
if (name) return { name: name.endsWith('.sol') ? name : `${name}.sol`, verified: true, source: 'sns' };
} catch { /* best effort */ }
return { name: null, verified: false, source: 'sns' };
}
// ── pure visual-tier mappings (network-free, unit-testable) ──────────────────
/** Reputation → a discrete trust tier the viewer maps to an aura. */
export function reputationTierFor(reputation) {
const fb = reputation?.feedback || {};
const verified = Number(fb.verified || 0);
const avg = Number(fb.score_avg_verified || 0);
const disputed = Number(fb.disputed || 0);
if (disputed > 0 && disputed >= verified) return 'disputed';
if (verified >= 15 && avg >= 4.5) return 'eminent';
if (verified >= 3 && avg >= 4) return 'trusted';
if (Number(fb.total || 0) > 0) return 'emerging';
return 'unranked';
}
/** Live USD holdings total → a discrete cosmetic tier. */
export function holdingsTierFor(totalUsd) {
const usd = Number(totalUsd || 0);
if (usd >= 1000) return 'platinum';
if (usd >= 100) return 'gold';
if (usd >= 10) return 'silver';
if (usd > 0) return 'bronze';
return 'none';
}
/** Balance floor under which the body renders in a designed "muted" state. */
export const MUTED_BALANCE_USD_FLOOR = Number(process.env.PERSONA_MUTED_USD_FLOOR || 0.05);
export function isMutedBalance(balances) {
const total = balances?.total_usd;
if (total == null) return balances?.sol === 0 && balances?.usdc === 0;
return total < MUTED_BALANCE_USD_FLOOR;
}
// ── the composed identity read ────────────────────────────────────────────────
/**
* `persona_identity` — the full read: address, live balances, reputation,
* holdings, nameplate, plus the derived visual tiers the viewer consumes
* directly. Every sub-read degrades independently (never throws), so a single
* flaky upstream (Bonfida, an RPC, the attestation index) never blanks the
* whole card — each field reports its own honest fallback.
*/
export async function getPersonaIdentity(personaId, { network = 'mainnet' } = {}) {
const address = personaWalletAddress(personaId);
const net = netOf(network);
const [balances, reputation, holdings, nameplate] = await Promise.all([
getPersonaBalances(address, net),
getPersonaReputation(address, net),
getPersonaHoldings(address, net),
getPersonaNameplate(address),
]);
return {
persona_id: personaId,
address,
network: net,
explorer: explorerAccountUrl(address, net),
balances,
reputation,
holdings,
nameplate,
visual: {
reputation_tier: reputationTierFor(reputation),
holdings_tier: holdingsTierFor(holdings.total_usd),
muted: isMutedBalance(balances),
verified_name: nameplate.verified ? nameplate.name : null,
},
caps: PERSONA_SPEND_CAPS,
fetched_at: new Date().toISOString(),
};
}
// ── guarded value ops (persona_tip / persona_send) ────────────────────────────
/**
* Send USDC from a persona's own wallet to a destination address — the shared
* implementation behind `persona_tip` and `persona_send`. Fully guarded:
* 1. reservePersonaSpend() enforces the per-call AND per-session USDC caps
* and books the amount atomically BEFORE any key is touched, so parallel
* calls cannot each pass a stale total.
* 2. Real settlement rides the SAME MEV-aware execution engine
* (submitProtected) every other outbound transfer on the platform uses.
* 3. finalizePersonaSpend() stamps the signature on the reserved row (a failed
* transfer releases it), so the cap holds across restarts / instances.
* Returns a structured result; only ever throws on a caller error (bad address)
* BEFORE any spend is reserved.
*/
export async function sendPersonaUsdc({ personaId, sessionId, to, usdc, tool = 'persona_send', network = 'mainnet', memo }) {
const net = netOf(network);
const amount = Number(usdc);
const session = sessionId || defaultSessionId(personaId);
let toPk;
try { toPk = new PublicKey(to); } catch {
return { status: 'failed', code: 'bad_address', message: 'That does not look like a valid Solana address.' };
}
const fromAddress = personaWalletAddress(personaId);
if (toPk.toBase58() === fromAddress) {
return { status: 'failed', code: 'self_payment', message: 'A persona cannot tip itself.' };
}
const gate = await reservePersonaSpend({ personaId, sessionId: session, usdc: amount, tool, toAddress: toPk.toBase58() });
if (!gate.ok) return { status: 'blocked', ...gate };
const reservation = gate.reservation;
const conn = solanaConnection(net);
const mintPk = new PublicKey(USDC_MINT_BY_NETWORK[net]);
const raw = BigInt(Math.max(0, Math.round(amount * 10 ** USDC_DECIMALS)));
let signature;
try {
signature = await withPersonaKeypair(personaId, async (keypair) => {
const fromAta = getAssociatedTokenAddressSync(mintPk, keypair.publicKey, false, TOKEN_PROGRAM_ID);
const toAta = getAssociatedTokenAddressSync(mintPk, toPk, false, TOKEN_PROGRAM_ID);
const instructions = [
createAssociatedTokenAccountIdempotentInstruction(keypair.publicKey, toAta, toPk, mintPk, TOKEN_PROGRAM_ID),
createTransferCheckedInstruction(fromAta, mintPk, toAta, keypair.publicKey, raw, USDC_DECIMALS, [], TOKEN_PROGRAM_ID),
];
const result = await submitProtected({
network: net, connection: conn, payer: keypair, instructions,
opts: { tipMode: 'off', confirmTimeoutMs: 45_000 },
});
return result.signature;
});
} catch (e) {
await releasePersonaSpend(reservation).catch(() => {});
return { status: 'failed', code: e?.code || 'send_failed', message: (e?.message || 'the transfer did not settle').slice(0, 200) };
}
// The reserved row already counts toward every cap; a failed finalize only
// loses the signature on it, never the spend.
await finalizePersonaSpend(reservation, signature).catch(() => {});
return {
status: 'ok',
signature,
explorer: explorerTxUrl(signature, net),
from: fromAddress,
to: toPk.toBase58(),
usdc: amount,
network: net,
session_id: session,
session_spent_usdc: Number((gate.spent_usdc + amount).toFixed(6)),
session_cap_usdc: PERSONA_SPEND_CAPS.maxPerSessionUsdc,
memo: memo || null,
};
}