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.

20.6 KB
Raw Blame
// @ts-check
// Verifiable Proof-of-Custody — server prover.
//
// Snapshots every custodial agent wallet's PUBLIC facts (address, live on-chain
// balance, a commitment to its authorized-state head from the custody ledger),
// builds a Merkle tree over all wallets, persists the epoch + leaves, and anchors
// the Merkle root on-chain as a signed SPL-Memo. Owners later fetch a per-wallet
// inclusion proof and verify it themselves in the browser against the on-chain
// root (src/proof-of-custody/verifier.js) — "don't trust, verify".
//
// The leaf encoding + tree construction live in src/proof-of-custody/merkle.js —
// the SAME module the browser verifier imports — so prover and verifier can never
// drift. This file must never hash a leaf any other way.

import {
	PublicKey,
	Transaction,
	TransactionInstruction,
} from '@solana/web3.js';
import { sendAndConfirm } from './solana/confirm.js';

import { sql } from './db.js';
import { mapPool } from './pool.js';
import { solanaConnection } from './solana/connection.js';
import { RPC } from './solana-attestations.js';
import { loadAttesterKeypair } from './attest-event.js';
import { explorerTxUrl } from './avatar-wallet.js';
import {
	computeLeafHash,
	buildMerkleTree,
	getMerkleProof,
} from '../../src/proof-of-custody/merkle.js';

const MEMO_PROGRAM_ID = new PublicKey('MemoSq4gqABAXKb96qnH8TysNcWxMyWCqXgDLGmfcHr');
const ANCHOR_KIND = 'threews.custody.v1';
const TX_TIMEOUT_MS = 20_000;

// Wall-clock budget for the snapshot phase (balance + ledger-head reads). When
// public RPC is rate-limited, the rotating fetch can sweep the whole endpoint
// chain per read — sequential and unbounded, N wallets × sweep once blew clean
// past the function's maxDuration and 504'd the cron (July 2026). Wallets not
// read before the deadline are skipped this epoch exactly like an RPC failure:
// never attested with a guessed balance, picked up again next epoch. Budget +
// TX_TIMEOUT_MS + persistence must stay under the route's maxDuration (120s).
const SNAPSHOT_BUDGET_MS = 80_000;
// Read balances in small concurrent batches: enough to cut wall-clock ~5×,
// small enough not to worsen the very 429s the rotating fetch is dodging.
const BALANCE_READ_CONCURRENCY = 5;

// The balances are read on the network the custodial wallets actually operate on
// (mainnet). The root commitment is a hash with no value, so it is anchored on
// the cheaper devnet by default — still a real, independently-fetchable on-chain
// artifact. Both are overridable for operators who want mainnet anchoring.
export const SNAPSHOT_NETWORK = process.env.CUSTODY_SNAPSHOT_NETWORK === 'devnet' ? 'devnet' : 'mainnet';
export const ANCHOR_NETWORK = process.env.CUSTODY_ANCHOR_NETWORK === 'mainnet' ? 'mainnet' : 'devnet';

// Reconciliation fee tolerance: a withdraw burns ~5k lamports of network fee that
// the ledger's recorded amount does not include, and a SOL "max" sweep leaves a
// rent/fee reserve. Allow a small floor plus per-authorized-event headroom so a
// legitimately-explained drop is never flagged as unexplained.
const RECON_FEE_FLOOR_LAMPORTS = 1_000_000n; // 0.001 SOL
const RECON_FEE_PER_EVENT_LAMPORTS = 50_000n; // generous per-tx fee allowance

function isValidSolAddress(addr) {
	if (typeof addr !== 'string' || addr.length < 32 || addr.length > 44) return false;
	if (!/^[1-9A-HJ-NP-Za-km-z]+$/.test(addr)) return false;
	try { new PublicKey(addr); return true; } catch { return false; }
}

/** Enumerate every custodial wallet with a syntactically valid Solana address. */
export async function listCustodialWallets() {
	const rows = await sql`
		SELECT id, user_id, meta->>'solana_address' AS address
		FROM agent_identities
		WHERE deleted_at IS NULL
		  AND meta->>'solana_address' IS NOT NULL
		ORDER BY id ASC
	`;
	return rows
		.filter((r) => isValidSolAddress(r.address))
		.map((r) => ({ agentId: r.id, userId: r.user_id, address: r.address }));
}

/**
 * Commitment to a wallet's authorized-state head: the id (and signature) of the
 * most recent custody-ledger event for that agent on the snapshot network, or
 * 'genesis' if the wallet has no recorded custody events yet. Folding the ledger
 * head into the leaf is what ties verification to the movement ledger — any
 * authorized change advances the head, so the leaf changes epoch-over-epoch in a
 * way the owner can map to a logged reason.
 */
export async function ledgerHeadFor(agentId, network = SNAPSHOT_NETWORK) {
	const [row] = await sql`
		SELECT id, signature
		FROM agent_custody_events
		WHERE agent_id = ${agentId} AND network = ${network}
		ORDER BY id DESC
		LIMIT 1
	`;
	if (!row) return 'genesis';
	return `${row.id}:${row.signature || ''}`;
}

/** Live on-chain lamports for an address; null on RPC failure (caller decides). */
async function readLamports(conn, address) {
	try {
		return await conn.getBalance(new PublicKey(address), 'confirmed');
	} catch {
		return null;
	}
}

/** Next monotonic epoch number (max + 1, starting at 1). */
async function nextEpoch() {
	const [row] = await sql`SELECT COALESCE(MAX(epoch), 0) AS max FROM custody_attestation_epochs`;
	return BigInt(row?.max ?? 0) + 1n;
}

/**
 * Run one attestation round: snapshot → Merkle → persist → anchor on-chain.
 *
 * Idempotent-ish by monotonic epoch: each call mints a NEW epoch (epochs are a
 * monotonic, append-only log so rollback/replay is detectable). Anchoring is
 * best-effort — if the attester key is unfunded/unset the epoch is still recorded
 * with anchor_status 'pending' and can be anchored later, exactly like the other
 * on-chain payout lanes. Returns a summary.
 *
 * @param {object} [opts]
 * @param {boolean} [opts.anchor=true]  set false to snapshot without an on-chain write
 */
export async function runAttestationEpoch({ anchor = true } = {}) {
	const startedAt = Date.now();
	const wallets = await listCustodialWallets();
	const conn = solanaConnection({ url: RPC[SNAPSHOT_NETWORK] || RPC.mainnet, commitment: 'confirmed' });

	const epoch = await nextEpoch();
	const epochNum = Number(epoch);

	// Build leaves in a stable order (wallets are already ordered by agent id).
	// Reads run in small concurrent batches under a wall-clock budget; results
	// are assembled in the original wallet order so the tree stays deterministic.
	const deadline = startedAt + SNAPSHOT_BUDGET_MS;
	const leaves = [];
	let totalLamports = 0n;
	let rpcFailures = 0;
	// A bounded pool rather than fixed batches: with batching, one slow RPC read
	// held its whole batch's slots idle until it drained. `mapPool` keeps every
	// slot busy and still returns results in wallet order, so the tree stays
	// deterministic.
	const results = await mapPool(wallets, BALANCE_READ_CONCURRENCY, async (w) => {
		// Out of snapshot time — skip the remaining wallets this epoch (same
		// contract as an RPC failure: never attest a balance we didn't read).
		if (Date.now() >= deadline) return null;
		const lamports = await readLamports(conn, w.address);
		// An RPC failure must not silently attest a wrong (zero) balance. Skip
		// the wallet this epoch rather than committing an unverifiable leaf; it
		// is included again next epoch once RPC recovers.
		if (lamports == null) return null;
		const balanceLamports = String(lamports);
		const ledgerHead = await ledgerHeadFor(w.agentId, SNAPSHOT_NETWORK);
		const leafHash = await computeLeafHash({
			agentId: w.agentId,
			address: w.address,
			balanceLamports,
			ledgerHead,
			epoch: epochNum,
		});
		return {
			agentId: w.agentId,
			address: w.address,
			balanceLamports,
			ledgerHead,
			leafHash,
		};
	});
	for (const leaf of results) {
		if (leaf == null) { rpcFailures++; continue; }
		leaves.push(leaf);
		totalLamports += BigInt(leaf.balanceLamports);
	}

	const tree = await buildMerkleTree(leaves.map((l) => l.leafHash));
	const root = tree.root;
	if (!root) {
		// No verifiable wallets this round — record an empty epoch so the chain of
		// epochs stays contiguous and the public page can show "0 wallets".
		await sql`
			INSERT INTO custody_attestation_epochs
				(epoch, network, anchor_network, merkle_root, wallet_count, total_lamports,
				 anchor_status, snapshot_ms)
			VALUES (${String(epoch)}, ${SNAPSHOT_NETWORK}, ${ANCHOR_NETWORK},
				${'0'.repeat(64)}, 0, 0, 'empty', ${Date.now() - startedAt})
		`;
		return { epoch: epochNum, wallet_count: 0, root: null, anchor_status: 'empty', rpc_failures: rpcFailures };
	}

	// Persist the epoch + leaves atomically so a proof read can never see a
	// half-written tree.
	await sql.transaction([
		sql`
			INSERT INTO custody_attestation_epochs
				(epoch, network, anchor_network, merkle_root, wallet_count, total_lamports,
				 anchor_status, snapshot_ms)
			VALUES (${String(epoch)}, ${SNAPSHOT_NETWORK}, ${ANCHOR_NETWORK}, ${root},
				${leaves.length}, ${String(totalLamports)}, 'pending', ${Date.now() - startedAt})
		`,
		...leaves.map((l, i) => sql`
			INSERT INTO custody_attestation_leaves
				(epoch, leaf_index, agent_id, address, balance_lamports, ledger_head, leaf_hash)
			VALUES (${String(epoch)}, ${i}, ${l.agentId}, ${l.address},
				${l.balanceLamports}, ${l.ledgerHead}, ${l.leafHash})
		`),
	]);

	let anchorResult = { status: 'pending', signature: null };
	if (anchor) {
		anchorResult = await anchorRoot({ epoch, root, walletCount: leaves.length });
	}

	return {
		epoch: epochNum,
		wallet_count: leaves.length,
		root,
		total_lamports: String(totalLamports),
		anchor_status: anchorResult.status,
		anchor_signature: anchorResult.signature,
		rpc_failures: rpcFailures,
		snapshot_ms: Date.now() - startedAt,
	};
}

/**
 * Commit a Merkle root on-chain as a signed SPL-Memo and record the signature.
 * Best-effort: a missing/undecodable/unfunded attester key marks the epoch
 * 'anchor_failed' with the reason instead of throwing, so the snapshot still
 * stands and a later run can re-anchor.
 *
 * @returns {Promise<{ status: 'anchored'|'anchor_failed', signature: string|null, error?: string }>}
 */
export async function anchorRoot({ epoch, root, walletCount }) {
	let attester;
	try {
		attester = loadAttesterKeypair();
	} catch (e) {
		await markAnchorFailed(epoch, e.code || 'attester_key_not_configured');
		return { status: 'anchor_failed', signature: null, error: e.code || e.message };
	}

	const payload = {
		v: 1,
		kind: ANCHOR_KIND,
		epoch: Number(epoch),
		root,
		wallet_count: walletCount,
		snapshot_network: SNAPSHOT_NETWORK,
		ts: Math.floor(Date.now() / 1000),
	};
	const conn = solanaConnection({ url: RPC[ANCHOR_NETWORK] || RPC.devnet, commitment: 'confirmed' });
	const ix = new TransactionInstruction({
		programId: MEMO_PROGRAM_ID,
		keys: [{ pubkey: attester.publicKey, isSigner: true, isWritable: false }],
		data: Buffer.from(JSON.stringify(payload), 'utf8'),
	});
	const tx = new Transaction().add(ix);

	let signature;
	try {
		signature = await withTimeout(
			sendAndConfirm(conn, tx, [attester], { commitment: 'confirmed' }),
			TX_TIMEOUT_MS,
		);
	} catch (e) {
		await markAnchorFailed(epoch, (e && e.message) ? String(e.message).slice(0, 300) : 'anchor_send_failed');
		return { status: 'anchor_failed', signature: null, error: 'anchor_send_failed' };
	}

	await sql`
		UPDATE custody_attestation_epochs
		SET anchor_sig = ${signature}, anchor_status = 'anchored',
		    anchor_error = NULL, anchored_at = now()
		WHERE epoch = ${String(epoch)}
	`;
	return { status: 'anchored', signature };
}

async function markAnchorFailed(epoch, reason) {
	await sql`
		UPDATE custody_attestation_epochs
		SET anchor_status = 'anchor_failed', anchor_error = ${String(reason).slice(0, 300)}
		WHERE epoch = ${String(epoch)} AND anchor_status <> 'anchored'
	`;
}

function withTimeout(promise, ms) {
	let timer;
	const timeout = new Promise((_, reject) => {
		timer = setTimeout(() => reject(new Error(`anchor rpc timeout after ${ms}ms`)), ms);
	});
	return Promise.race([promise, timeout]).finally(() => clearTimeout(timer));
}

function epochRowToPublic(row) {
	if (!row) return null;
	const anchorNet = row.anchor_network || ANCHOR_NETWORK;
	const totalLamports = String(row.total_lamports ?? '0');
	return {
		epoch: Number(row.epoch),
		network: row.network,
		anchor_network: anchorNet,
		merkle_root: row.merkle_root,
		wallet_count: row.wallet_count,
		total_lamports: totalLamports,
		total_sol: Number(BigInt(totalLamports)) / 1e9,
		anchor_sig: row.anchor_sig || null,
		anchor_explorer: row.anchor_sig ? explorerTxUrl(row.anchor_sig, anchorNet) : null,
		anchor_status: row.anchor_status,
		created_at: row.created_at,
		anchored_at: row.anchored_at || null,
	};
}

/** Public, no-auth aggregate for the integrity page — never per-wallet data. */
export async function getPublicIntegrity() {
	const [latest] = await sql`
		SELECT * FROM custody_attestation_epochs
		ORDER BY epoch DESC LIMIT 1
	`;
	const [agg] = await sql`
		SELECT COUNT(*)::int AS epochs, MIN(created_at) AS since,
		       COUNT(*) FILTER (WHERE anchor_status = 'anchored')::int AS anchored
		FROM custody_attestation_epochs
	`;
	const recent = await sql`
		SELECT epoch, network, anchor_network, merkle_root, wallet_count, total_lamports,
		       anchor_sig, anchor_status, created_at, anchored_at
		FROM custody_attestation_epochs
		ORDER BY epoch DESC LIMIT 12
	`;
	return {
		latest: epochRowToPublic(latest),
		epochs_total: agg?.epochs ?? 0,
		epochs_anchored: agg?.anchored ?? 0,
		since: agg?.since ?? null,
		recent: recent.map(epochRowToPublic),
	};
}

/** Public anchor reference for one epoch (lets a verifier cross-check the root). */
export async function getAnchorRef(epoch) {
	const [row] = await sql`
		SELECT * FROM custody_attestation_epochs WHERE epoch = ${String(epoch)}
	`;
	return epochRowToPublic(row);
}

/**
 * Public anchor reference for the newest epoch. One row, one query: the anchor
 * endpoint used to answer `?epoch=latest` out of getPublicIntegrity(), which
 * also runs a full-table aggregate and a 12-row recent list it then discards.
 */
export async function getLatestAnchorRef() {
	const [row] = await sql`
		SELECT * FROM custody_attestation_epochs ORDER BY epoch DESC LIMIT 1
	`;
	return epochRowToPublic(row);
}

/**
 * Owner-gated inclusion proof for one agent's wallet at the latest epoch in which
 * it was attested. Returns the leaf's public fields, the Merkle path to the root,
 * the on-chain anchor reference, and a movement reconciliation against the custody
 * ledger. The caller (api/agents/solana-wallet.js) has already verified ownership.
 *
 * @returns {Promise<object>} { included, ...proof } — included:false if the wallet
 *          has no leaf yet (e.g. provisioned after the last snapshot).
 */
export async function getInclusionProof(agentId) {
	// Latest epoch that actually contains this wallet's leaf.
	const [leafRow] = await sql`
		SELECT epoch, leaf_index, agent_id, address, balance_lamports, ledger_head, leaf_hash
		FROM custody_attestation_leaves
		WHERE agent_id = ${agentId}
		ORDER BY epoch DESC LIMIT 1
	`;
	if (!leafRow) {
		const [anyEpoch] = await sql`SELECT MAX(epoch) AS epoch FROM custody_attestation_epochs`;
		return {
			included: false,
			latest_epoch: anyEpoch?.epoch != null ? Number(anyEpoch.epoch) : null,
			reason: 'no_leaf_yet',
		};
	}

	const epoch = leafRow.epoch;
	const [epochRow] = await sql`SELECT * FROM custody_attestation_epochs WHERE epoch = ${String(epoch)}`;

	// Rebuild the epoch's tree from its stored leaves to emit a verifiable path.
	const all = await sql`
		SELECT leaf_index, leaf_hash FROM custody_attestation_leaves
		WHERE epoch = ${String(epoch)} ORDER BY leaf_index ASC
	`;
	const tree = await buildMerkleTree(all.map((r) => r.leaf_hash));
	const proof = getMerkleProof(tree.layers, leafRow.leaf_index);

	const reconciliation = await reconcile(agentId, epoch, leafRow);

	const anchorNet = epochRow.anchor_network || ANCHOR_NETWORK;
	return {
		included: true,
		epoch: Number(epoch),
		network: epochRow.network,
		anchor: {
			network: anchorNet,
			signature: epochRow.anchor_sig || null,
			explorer: epochRow.anchor_sig ? explorerTxUrl(epochRow.anchor_sig, anchorNet) : null,
			status: epochRow.anchor_status,
			kind: ANCHOR_KIND,
		},
		// Everything the browser needs to recompute the leaf hash itself.
		leaf: {
			agentId,
			address: leafRow.address,
			balanceLamports: String(leafRow.balance_lamports),
			balanceSol: Number(BigInt(String(leafRow.balance_lamports))) / 1e9,
			ledgerHead: leafRow.ledger_head,
			epoch: Number(epoch),
			index: leafRow.leaf_index,
			leafHash: leafRow.leaf_hash,
		},
		proof,
		// The server's claimed root. The verifier recomputes from leaf+proof and
		// then confirms THAT against the on-chain anchor — it never trusts this.
		merkle_root: epochRow.merkle_root,
		wallet_count: epochRow.wallet_count,
		snapshot_at: epochRow.created_at,
		reconciliation,
	};
}

/**
 * Movement reconciliation: does the balance change since the previous epoch map
 * to authorized, logged custody events? Surfaces "no unexplained movements" as a
 * verifiable claim and loudly flags an outflow the ledger can't account for.
 */
export async function reconcile(agentId, epoch, currentLeaf) {
	const [prev] = await sql`
		SELECT epoch, balance_lamports FROM custody_attestation_leaves
		WHERE agent_id = ${agentId} AND epoch < ${String(epoch)}
		ORDER BY epoch DESC LIMIT 1
	`;
	const currentBalance = BigInt(String(currentLeaf.balance_lamports));

	if (!prev) {
		return {
			status: 'baseline',
			human: 'First attested epoch for this wallet — nothing to reconcile against yet. Future epochs will check every balance change against your authorized custody events.',
			current_balance_lamports: String(currentBalance),
		};
	}

	const prevBalance = BigInt(String(prev.balance_lamports));
	const delta = currentBalance - prevBalance;

	// Window between the two epochs' snapshots.
	const [bounds] = await sql`
		SELECT
			(SELECT created_at FROM custody_attestation_epochs WHERE epoch = ${String(prev.epoch)}) AS prev_at,
			(SELECT created_at FROM custody_attestation_epochs WHERE epoch = ${String(epoch)}) AS cur_at
	`;
	const events = await sql`
		SELECT id, event_type, category, amount_lamports, usd, signature, reason, created_at
		FROM agent_custody_events
		WHERE agent_id = ${agentId}
		  AND network = ${SNAPSHOT_NETWORK}
		  AND event_type IN ('withdraw', 'spend')
		  AND asset = 'SOL'
		  AND amount_lamports IS NOT NULL
		  AND created_at > ${bounds.prev_at}
		  AND created_at <= ${bounds.cur_at}
		ORDER BY id ASC
	`;
	let authorizedOutflow = 0n;
	for (const e of events) authorizedOutflow += BigInt(String(e.amount_lamports));
	const tolerance = RECON_FEE_FLOOR_LAMPORTS + BigInt(events.length) * RECON_FEE_PER_EVENT_LAMPORTS;

	const summarized = events.map((e) => ({
		id: String(e.id),
		event_type: e.event_type,
		category: e.category,
		amount_lamports: String(e.amount_lamports),
		amount_sol: Number(BigInt(String(e.amount_lamports))) / 1e9,
		reason: e.reason,
		signature: e.signature,
		explorer: e.signature ? explorerTxUrl(e.signature, SNAPSHOT_NETWORK) : null,
		created_at: e.created_at,
	}));

	if (delta >= 0n) {
		// Balance flat or up. Incoming deposits are external (not in the custody
		// ledger), so an increase is expected and benign; there is no unexplained
		// OUTFLOW, which is the property we attest.
		return {
			status: 'reconciled',
			prev_epoch: Number(prev.epoch),
			prev_balance_lamports: String(prevBalance),
			current_balance_lamports: String(currentBalance),
			delta_lamports: String(delta),
			delta_sol: Number(delta) / 1e9,
			authorized_outflow_lamports: String(authorizedOutflow),
			authorized_events: summarized,
			unexplained_lamports: '0',
			human: delta === 0n
				? 'Balance unchanged since the previous epoch. No movement, nothing unexplained.'
				: `Balance increased by ${(Number(delta) / 1e9).toFixed(6)} SOL — an incoming deposit. Deposits are external to custody and never move funds out, so there is nothing to authorize.`,
		};
	}

	const outflow = -delta;
	const unexplained = outflow > authorizedOutflow + tolerance ? outflow - authorizedOutflow : 0n;
	const reconciled = unexplained === 0n;
	return {
		status: reconciled ? 'reconciled' : 'unexplained',
		prev_epoch: Number(prev.epoch),
		prev_balance_lamports: String(prevBalance),
		current_balance_lamports: String(currentBalance),
		delta_lamports: String(delta),
		delta_sol: Number(delta) / 1e9,
		authorized_outflow_lamports: String(authorizedOutflow),
		authorized_events: summarized,
		unexplained_lamports: String(unexplained),
		human: reconciled
			? `Balance fell by ${(Number(outflow) / 1e9).toFixed(6)} SOL, fully explained by ${summarized.length} authorized custody event${summarized.length === 1 ? '' : 's'} (withdraw/spend) plus network fees. No unexplained movement.`
			: `⚠ Balance fell by ${(Number(outflow) / 1e9).toFixed(6)} SOL but only ${(Number(authorizedOutflow) / 1e9).toFixed(6)} SOL is accounted for by authorized custody events. ${(Number(unexplained) / 1e9).toFixed(6)} SOL of outflow is UNEXPLAINED — this should never happen and warrants investigation.`,
	};
}