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.

22.5 KB
Raw Blame
// Agent wallet generation and management.
// Generates a random EVM/Solana wallet per agent and encrypts the private key at
// rest using AES-256-GCM.
//
// Key management (v2): the encryption key derives from a DEDICATED secret
// (WALLET_ENCRYPTION_KEY) — independent of JWT_SECRET — with a RANDOM per-record
// salt embedded in each ciphertext. This fixes two problems with the original v1
// scheme: (1) it tied every custodial wallet's confidentiality to JWT_SECRET, the
// highest-circulation secret on the platform (every session/bearer check), so a
// single JWT_SECRET leak decrypted all wallets and rotating it to invalidate
// sessions would have bricked every wallet; (2) v1 used a constant salt, so all
// records shared one derived key.
//
// Migration is dual-read, no data backfill required: ciphertexts written by v1
// (no version tag) still decrypt with the legacy JWT_SECRET + constant-salt
// derivation; new writes use v2 and records re-encrypt opportunistically on their
// next write. Set WALLET_ENCRYPTION_KEY in every environment that holds custodial
// keys; until it is set the code falls back to JWT_SECRET (with a warning) so
// deploys don't break, but the per-record salt still applies.

import { webcrypto } from 'node:crypto';
import { evmFallbackProvider } from './evm/rpc.js';
// Single source of truth for the AES-256-GCM secret box (HKDF key derivation,
// per-record salt, v1 legacy read). Shared with the coin treasury + launcher so
// every custodial secret on the platform uses the same at-rest scheme.
import { encryptSecret, decryptSecret, isEncryptedSecret } from './secret-box.js';

const randomBytes = (n) => {
	const b = new Uint8Array(n);
	(globalThis.crypto || webcrypto).getRandomValues(b);
	return b;
};

// Local aliases preserve the original call sites below; re-exported so existing
// importers of these names from agent-wallet.js keep working.
const encrypt = encryptSecret;
const decrypt = decryptSecret;
export { encryptSecret, decryptSecret, isEncryptedSecret };

// ── Wallet generation ───────────────────────────────────────────────────────

/**
 * Generate a new Ethereum wallet for an agent.
 * Returns { address, encrypted_key } where encrypted_key is the AES-GCM
 * encrypted private key (base64). Store encrypted_key in agent meta.
 */
export async function generateAgentWallet() {
	// Generate 32 random bytes for a private key
	const pk = randomBytes(32);
	const pkHex = '0x' + Array.from(pk, (b) => b.toString(16).padStart(2, '0')).join('');

	// Compute address from private key using ethers
	const { computeAddress } = await import('ethers');
	const address = computeAddress(pkHex);

	const encrypted_key = await encrypt(pkHex);
	return { address, encrypted_key };
}

/**
 * Recover an agent wallet's private key from its encrypted form.
 * Only call this when the agent needs to sign a transaction.
 *
 * Audit hook (mirrors recoverSolanaAgentKeypair): pass
 * `audit: { agentId, userId, reason, meta }` and a usage_events row + an
 * owner-viewable custody event are written fire-and-forget, so every decrypt of
 * a custodial EVM key is traceable with its reason — parity with the Solana path.
 */
export async function recoverAgentKey(encryptedKey, audit = null) {
	const pkHex = await decrypt(encryptedKey);
	if (audit && audit.agentId) {
		let address = null;
		try {
			const { computeAddress } = await import('ethers');
			address = computeAddress(pkHex);
		} catch { /* address is decoration on the audit row */ }
		import('./usage.js')
			.then(({ recordEvent }) =>
				recordEvent({
					userId: audit.userId ?? null,
					agentId: audit.agentId,
					kind: 'evm_key_use',
					tool: audit.reason || 'sign',
					status: 'ok',
					meta: { address, ...(audit.meta || {}) },
				}),
			)
			.catch(() => {});
		import('./agent-trade-guards.js')
			.then(({ recordCustodyEvent }) =>
				recordCustodyEvent({
					agentId: audit.agentId,
					userId: audit.userId ?? null,
					eventType: 'key_recover',
					reason: audit.reason || 'sign',
					meta: { address, chain: 'evm', ...(audit.meta || {}) },
				}),
			)
			.catch(() => {});
	}
	return pkHex;
}

/**
 * Idempotently provision a custodial EVM wallet for an agent.
 *
 * Mirrors getOrCreateAgentSolanaWallet(): generate a keypair via
 * generateAgentWallet(), store the address in agent_identities.wallet_address
 * and the encrypted key in meta.encrypted_wallet_key, and never re-create if one
 * already exists. Returns { address, created }.
 */
export async function getOrCreateAgentEvmWallet(agentId, { chainId = 8453 } = {}) {
	const { sql } = await import('./db.js');
	const [row] = await sql`
		select id, wallet_address, meta from agent_identities
		where id = ${agentId} and deleted_at is null
		limit 1
	`;
	if (!row) throw new Error('agent not found');
	if (row.wallet_address && row.meta?.encrypted_wallet_key) {
		return { address: row.wallet_address, created: false };
	}

	const wallet = await generateAgentWallet();
	const meta = {
		...(row.meta || {}),
		encrypted_wallet_key: wallet.encrypted_key,
		evm_wallet_source: 'generated',
	};
	await sql`
		update agent_identities
		set wallet_address = ${wallet.address},
		    chain_id = coalesce(chain_id, ${chainId}),
		    meta = ${JSON.stringify(meta)}::jsonb
		where id = ${agentId}
	`;
	return { address: wallet.address, created: true };
}

/**
 * Idempotently provision BOTH the EVM and Solana custodial wallets for an agent.
 * Used by the "create wallet" action on every avatar surface and by the
 * auto-provision on first avatar save. Returns the live addresses.
 * @returns {Promise<{ evm: string, solana: string, created: boolean }>}
 */
export async function provisionAgentWallets(agentId, { chainId = 8453 } = {}) {
	const evm = await getOrCreateAgentEvmWallet(agentId, { chainId });
	const sol = await getOrCreateAgentSolanaWallet(agentId);
	return { evm: evm.address, solana: sol.address, created: evm.created || sol.created };
}

// ── EVM on-chain balance + spend helpers ────────────────────────────────────

let _ethUsdPrice = null;
let _ethUsdPriceAt = 0;
const ETH_USD_CACHE_MS = 5 * 60_000;

// ETH/USD for the affordability checks below. The read goes through the shared
// coin-price failover (CoinGecko → DefiLlama → Kraken/Coinbase/Bitfinex) rather
// than a bare CoinGecko fetch, so a keyless-tier 429 no longer turns "can this
// agent afford the call?" into a hard error. Still throws when every source is
// down: the callers divide by this price, and a guessed rate would silently
// mis-size a spend.
async function fetchEthUsdPrice() {
	if (_ethUsdPrice && Date.now() - _ethUsdPriceAt < ETH_USD_CACHE_MS) return _ethUsdPrice;
	const { fetchCoinPriceUsd } = await import('./market-fallbacks.js');
	_ethUsdPrice = await fetchCoinPriceUsd('ethereum');
	_ethUsdPriceAt = Date.now();
	return _ethUsdPrice;
}

/**
 * Query the live ETH balance of an agent's wallet_address on its registered chain.
 * @returns {{ address: string, chain_id: number, balance_wei: string, balance_eth: string }}
 */
export async function getAgentBalance(agentId) {
	const { sql } = await import('./db.js');
	const [agent] = await sql`
		select wallet_address, chain_id
		from agent_identities
		where id = ${agentId} and deleted_at is null
		limit 1
	`;
	if (!agent?.wallet_address) throw new Error('agent has no wallet_address');
	const chainId = agent.chain_id || 8453;

	const { formatEther } = await import('ethers');
	const provider = await evmFallbackProvider(chainId);
	const balanceBigInt = await provider.getBalance(agent.wallet_address);
	return {
		address: agent.wallet_address,
		chain_id: chainId,
		balance_wei: balanceBigInt.toString(),
		balance_eth: formatEther(balanceBigInt),
	};
}

/**
 * Returns true if the agent's EVM wallet can afford priceUsd (at current ETH/USD).
 */
export async function canAfford(agentId, priceUsd) {
	const { parseEther } = await import('ethers');
	const [bal, ethUsd] = await Promise.all([getAgentBalance(agentId), fetchEthUsdPrice()]);
	const priceEth = priceUsd / ethUsd;
	const priceWei = parseEther(priceEth.toFixed(18));
	return BigInt(bal.balance_wei) >= priceWei;
}

const SPEND_ABI = [
	'function spend(uint256 agentId, address payable recipient, uint256 amountWei, string calldata memo) external',
];

/**
 * Calls IdentityRegistry.spend() via the agent's delegated signer key.
 * @param {{ agentId: string, recipient: string, amountWei: bigint|string, memo: string, signer: import('ethers').Signer }} opts
 * @returns {Promise<string>} tx hash
 */
export async function delegatedSpend({ agentId, recipient, amountWei, memo, signer }) {
	const { sql } = await import('./db.js');
	const [agent] = await sql`
		select erc8004_agent_id, chain_id from agent_identities
		where id = ${agentId} and deleted_at is null
		limit 1
	`;
	if (!agent?.erc8004_agent_id) throw new Error('agent has no on-chain erc8004_agent_id');

	const chainId = agent.chain_id || 8453;
	const { CHAIN_BY_ID, IDENTITY_REGISTRY_MAINNET, IDENTITY_REGISTRY_TESTNET } = await import('./erc8004-chains.js');
	const chain = CHAIN_BY_ID[chainId];
	const registryAddress = chain?.testnet ? IDENTITY_REGISTRY_TESTNET : IDENTITY_REGISTRY_MAINNET;

	const { Contract } = await import('ethers');
	const registry = new Contract(registryAddress, SPEND_ABI, signer);
	const tx = await registry.spend(agent.erc8004_agent_id, recipient, amountWei, memo || '');
	return tx.hash;
}

/**
 * Fire-and-forget: charge an agent for a paid skill call.
 * Records in agent_payments; broadcasts on-chain via delegatedSpend if affordable.
 * Never throws — errors are logged and the payment row reflects the outcome.
 */
export async function triggerSkillPayment({ agentId, skillSlug, skillId }) {
	try {
		const { sql } = await import('./db.js');

		// Resolve skill price and author wallet
		const [skill] = await sql`
			select ms.id, ms.price_per_call_usd, ms.author_id,
			       uw.address as author_wallet
			from marketplace_skills ms
			left join user_wallets uw on uw.user_id = ms.author_id
			    and uw.chain_type = 'evm' and uw.is_primary = true
			where ms.slug = ${skillSlug}
			limit 1
		`;
		if (!skill || Number(skill.price_per_call_usd) <= 0) return;

		const priceUsd = Number(skill.price_per_call_usd);

		// Validate the payout recipient shape before it can be used as a transfer
		// target — never sign a spend to a malformed/unexpected address.
		if (skill.author_wallet && !/^0x[0-9a-fA-F]{40}$/.test(String(skill.author_wallet))) {
			console.warn(`[agent-payments] skill ${skillSlug} has a malformed author_wallet; skipping`);
			return;
		}

		// Load agent to get chain + encrypted key
		const [agent] = await sql`
			select wallet_address, chain_id, erc8004_agent_id, meta
			from agent_identities
			where id = ${agentId} and deleted_at is null
			limit 1
		`;
		if (!agent) return;

		// Enforce the agent's per-transaction USD ceiling so a server-signed skill
		// charge can't exceed the owner's configured limit (this path previously
		// bypassed the spend policy entirely — only an affordability check applied).
		const { getSpendLimits } = await import('./agent-trade-guards.js');
		const spendLimits = getSpendLimits(agent.meta);
		if (spendLimits.per_tx_usd != null && priceUsd > spendLimits.per_tx_usd + 1e-9) {
			console.warn(
				`[agent-payments] skill ${skillSlug} ($${priceUsd}) exceeds agent ${agentId} per_tx_usd ` +
					`($${spendLimits.per_tx_usd}); skipping`,
			);
			await sql`
				insert into agent_payments
					(payer_agent_id, skill_id, amount_wei, chain_id, memo, status)
				values (${agentId}, ${skill.id ?? null}, '0', ${agent.chain_id || 8453}, ${skillSlug}, 'failed')
			`.catch(() => {});
			return;
		}

		const chainId = agent.chain_id || 8453;
		const encryptedKey = agent.meta?.encrypted_wallet_key;
		if (!encryptedKey) return;

		// Convert USD → wei
		const ethUsd = await fetchEthUsdPrice();
		const priceEth = priceUsd / ethUsd;
		const { parseEther, Wallet } = await import('ethers');
		const amountWei = parseEther(priceEth.toFixed(18));

		const affordable = BigInt(
			(await getAgentBalance(agentId).catch(() => ({ balance_wei: '0' }))).balance_wei,
		) >= amountWei;

		if (!affordable) {
			await sql`
				insert into agent_payments
					(payer_agent_id, skill_id, amount_wei, chain_id, memo, status)
				values (
					${agentId}, ${skill.id ?? null}, ${amountWei.toString()},
					${chainId}, ${skillSlug}, 'failed'
				)
			`;
			console.warn(`[agent-payments] agent ${agentId} cannot afford skill ${skillSlug}`);
			return;
		}

		// Insert pending row first
		const [row] = await sql`
			insert into agent_payments
				(payer_agent_id, skill_id, amount_wei, chain_id, memo, status)
			values (
				${agentId}, ${skill.id ?? null}, ${amountWei.toString()},
				${chainId}, ${skillSlug}, 'pending'
			)
			returning id
		`;

		// Build signer + dispatch tx (fire-and-forget)
		(async () => {
			try {
				const pkHex = await decrypt(encryptedKey);
				const provider = await evmFallbackProvider(chainId);
				const signer = new Wallet(pkHex, provider);
				const recipient = skill.author_wallet || signer.address;
				const txHash = await delegatedSpend({
					agentId,
					recipient,
					amountWei,
					memo: skillSlug,
					signer,
				});
				await sql`
					update agent_payments set status = 'confirmed', tx_hash = ${txHash}
					where id = ${row.id}
				`;
			} catch (e) {
				await sql`
					update agent_payments set status = 'failed'
					where id = ${row.id}
				`.catch(() => {});
				console.error(`[agent-payments] tx failed for ${agentId}/${skillSlug}`, e?.message);
			}
		})();
	} catch (e) {
		console.error('[agent-payments] triggerSkillPayment error', e?.message);
	}
}

// ── Solana wallet ───────────────────────────────────────────────────────────

/**
 * Generate a new Solana keypair for an agent.
 * Returns { address, encrypted_secret } where encrypted_secret is the base64
 * AES-GCM ciphertext of the 64-byte secret key (also base64-encoded inside).
 */
export async function generateSolanaAgentWallet() {
	const { Keypair } = await import('@solana/web3.js');
	const kp = Keypair.generate();
	const secretB64 = Buffer.from(kp.secretKey).toString('base64');
	const encrypted_secret = await encrypt(secretB64);
	return { address: kp.publicKey.toBase58(), encrypted_secret };
}

// Circle USDC mints — the x402 settlement asset, per cluster. Used for the
// USDC balance readout on a freshly provisioned wallet (not a coin token; $THREE
// is the only coin, USDC is the payment rail).
const USDC_MINT_BY_CLUSTER = {
	mainnet: 'EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v',
	devnet: '4zMMC9srt5Ri5X14GAgXhaHii3GnPAEERYPJgZJDncDU',
};

/**
 * Idempotently provision a custodial Solana wallet for an agent.
 *
 * Mirrors the POST branch of api/agents/solana-wallet.js: generate a keypair via
 * generateSolanaAgentWallet(), store the address + encrypted secret in agent
 * meta, and never re-create if one already exists. Returns { address, created }.
 */
export async function getOrCreateAgentSolanaWallet(agentId) {
	const { sql } = await import('./db.js');
	const [row] = await sql`
		select id, meta from agent_identities
		where id = ${agentId} and deleted_at is null
		limit 1
	`;
	if (!row) throw new Error('agent not found');

	let meta = { ...(row.meta || {}) };
	if (meta.solana_address) {
		return { address: meta.solana_address, created: false };
	}

	const sol = await generateSolanaAgentWallet();
	meta = {
		...meta,
		solana_address: sol.address,
		encrypted_solana_secret: sol.encrypted_secret,
		solana_wallet_source: 'generated',
	};
	await sql`update agent_identities set meta = ${JSON.stringify(meta)}::jsonb where id = ${agentId}`;
	return { address: sol.address, created: true };
}

/**
 * Read the live SOL + USDC balances for a Solana address on the given cluster.
 * Never throws — an RPC failure returns nulls so a provision call still succeeds
 * with the wallet address (balances can be re-read later via wallet_status).
 * @returns {Promise<{ sol: number|null, usdc: number|null }>}
 */
export async function getSolanaAddressBalances(address, cluster = 'mainnet') {
	const net = cluster === 'devnet' ? 'devnet' : 'mainnet';
	let sol = null;
	let usdc = null;
	try {
		const { PublicKey } = await import('@solana/web3.js');
		const { getAssociatedTokenAddressSync, TOKEN_PROGRAM_ID, ASSOCIATED_TOKEN_PROGRAM_ID } =
			await import('@solana/spl-token');
		const { solanaConnection } = await import('./agent-pumpfun.js');
		const conn = solanaConnection(net);
		const owner = new PublicKey(address);
		const lamports = await conn.getBalance(owner);
		sol = lamports / 1e9;
		try {
			const ata = getAssociatedTokenAddressSync(
				new PublicKey(USDC_MINT_BY_CLUSTER[net]),
				owner,
				false,
				TOKEN_PROGRAM_ID,
				ASSOCIATED_TOKEN_PROGRAM_ID,
			);
			const bal = await conn.getTokenAccountBalance(ata);
			usdc = bal?.value?.uiAmount ?? 0;
		} catch {
			usdc = 0; // no ATA yet → zero USDC
		}
	} catch (err) {
		// RPC failure: report nulls rather than throw, so a caller that only needed
		// the address still succeeds. Log it, because a null here is indistinguishable
		// from a genuinely empty wallet everywhere downstream, and a silent swallow
		// leaves an operator no way to tell an outage from a zero balance.
		console.warn('[agent-wallet] solana balance read failed', net, err?.message);
	}
	return { sol, usdc };
}

// Validate a string is a syntactically valid Solana (base58, 32-byte) address.
// A truthy meta.solana_address that does not parse is treated as missing so the
// wallet is re-provisioned rather than handed downstream to crash a PublicKey().
async function isValidSolanaAddress(address) {
	if (typeof address !== 'string' || address.length < 32 || address.length > 44) return false;
	if (!/^[1-9A-HJ-NP-Za-km-z]+$/.test(address)) return false;
	try {
		const { PublicKey } = await import('@solana/web3.js');
		// Constructing throws on a malformed (non-32-byte) base58 string.
		// eslint-disable-next-line no-new
		new PublicKey(address);
		return true;
	} catch {
		return false;
	}
}

/**
 * Idempotently guarantee an agent has a usable custodial Solana wallet.
 *
 * This is THE single entry point every wallet-touching endpoint (deposit, trade,
 * x402 pay, withdraw) must call before assuming `meta.solana_address` /
 * `meta.encrypted_solana_secret` exist. It:
 *   1. loads the agent row,
 *   2. returns the existing wallet if both the address is a valid Solana key and
 *      a recoverable encrypted secret is present ({ created: false }),
 *   3. otherwise generates + persists a fresh keypair via the canonical
 *      generateSolanaAgentWallet() and audit-logs the lazy provision
 *      ({ created: true }).
 *
 * A row whose address fails to parse, or whose secret is missing, is repaired —
 * never handed downstream to throw inside a PublicKey() / signing call. The
 * secret never leaves the server and is never returned, logged, or put in an
 * error message.
 *
 * @param {string} agentId
 * @param {string|null} [userId] — owner, for the audit trail (optional)
 * @param {{ reason?: string }} [opts]
 * @returns {Promise<{ address: string, created: boolean }>}
 */
export async function ensureAgentWallet(agentId, userId = null, opts = {}) {
	if (!agentId) throw new Error('agentId required');
	const { sql } = await import('./db.js');
	const [row] = await sql`
		select id, user_id, meta from agent_identities
		where id = ${agentId} and deleted_at is null
		limit 1
	`;
	if (!row) throw new Error('agent not found');

	const meta = { ...(row.meta || {}) };
	const hasValidAddress = await isValidSolanaAddress(meta.solana_address);
	const hasSecret = typeof meta.encrypted_solana_secret === 'string' && meta.encrypted_solana_secret.length > 0;
	if (hasValidAddress && hasSecret) {
		return { address: meta.solana_address, created: false };
	}

	const sol = await generateSolanaAgentWallet();
	const nextMeta = {
		...meta,
		solana_address: sol.address,
		encrypted_solana_secret: sol.encrypted_secret,
		solana_wallet_source: meta.solana_wallet_source || 'lazy_provision',
	};
	await sql`update agent_identities set meta = ${JSON.stringify(nextMeta)}::jsonb where id = ${agentId}`;

	// Audit the lazy provision: custodial keys are real funds, every mint must be
	// traceable. Fire-and-forget — telemetry must never block the wallet path.
	// The address is public; the secret is never recorded.
	try {
		const { recordEvent } = await import('./usage.js');
		recordEvent({
			userId: userId ?? row.user_id ?? null,
			agentId,
			kind: 'solana_wallet_provision',
			tool: opts.reason || 'ensure',
			status: 'ok',
			meta: { address: sol.address, source: 'lazy_provision', repaired: hasValidAddress !== hasSecret },
		});
	} catch {
		/* audit best-effort */
	}
	return { address: sol.address, created: true };
}

/**
 * Recover a Solana Keypair from its encrypted form.
 * Only call this when the agent needs to sign a transaction.
 *
 * Audit hook: pass `audit: { agentId, userId, reason, meta }` and a
 * usage_events row will be written fire-and-forget so every decrypt
 * is traceable.
 */
export async function recoverSolanaAgentKeypair(encryptedSecret, audit = null) {
	// Self-custody: an agent whose owner chose external or session signing is
	// never signed for by the platform, whichever route asked. Rotation after a
	// key export is the one owner-initiated exception (`custodyOverride`).
	if (audit?.agentId && !audit.custodyOverride) {
		const { assertPlatformSigningAllowed } = await import('./custody/signing.js');
		await assertPlatformSigningAllowed(audit.agentId);
	}
	const { Keypair } = await import('@solana/web3.js');
	const secretB64 = await decrypt(encryptedSecret);
	const kp = Keypair.fromSecretKey(Buffer.from(secretB64, 'base64'));
	if (audit && audit.agentId) {
		const { recordEvent } = await import('./usage.js');
		recordEvent({
			userId: audit.userId ?? null,
			agentId: audit.agentId,
			kind: 'solana_key_use',
			tool: audit.reason || 'sign',
			status: 'ok',
			meta: { address: kp.publicKey.toBase58(), ...(audit.meta || {}) },
		});
		// Mirror into the owner-viewable custody trail so every decrypt of a
		// custodial key is traceable with its reason, alongside withdraws and
		// limit changes. Fire-and-forget — never block or fail the signing path.
		import('./agent-trade-guards.js')
			.then(({ recordCustodyEvent }) =>
				recordCustodyEvent({
					agentId: audit.agentId,
					userId: audit.userId ?? null,
					eventType: 'key_recover',
					reason: audit.reason || 'sign',
					meta: { address: kp.publicKey.toBase58(), ...(audit.meta || {}) },
				}),
			)
			.catch(() => {});
	}
	return kp;
}