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.

17.5 KB
Raw Blame
// The external-signer contract: prepare, then submit.
//
//   prepareExternalTx  simulates an unsigned transaction, stores its exact
//                      message bytes in pending_external_txs, and returns a
//                      tx_id plus the base64 transaction for the wallet to sign.
//   submitExternalTx   takes that tx_id and the signed transaction, proves the
//                      expected key signed it, checks the signed message still
//                      carries every instruction that was prepared, broadcasts,
//                      confirms, and reconciles the result into
//                      agent_custody_events with the on-chain signature.
//
// The external path is confirmed by the signature itself: the platform never
// holds the key, so there is no confirm flag to check. What the platform does
// guarantee is that the ledger row describes the transaction that actually
// landed. Wallets are allowed to add instructions (priority fees, guard
// assertions); they are not allowed to drop or alter one we prepared.

import { PublicKey, VersionedTransaction, VersionedMessage } from '@solana/web3.js';
import bs58 from 'bs58';
import { ed25519 } from '@noble/curves/ed25519.js';
import { sql } from '../db.js';
import { solanaConnection } from '../solana/connection.js';
import { pollConfirmation } from '../solana/confirm.js';
import { recordCustodyEvent } from '../agent-trade-guards.js';
import { clientError } from './builders.js';

// A blockhash lives ~150 slots (about 60 to 90 seconds). The row outlives it a
// little so a late submit gets the precise "expired" answer instead of a 404.
export const PREPARED_TTL_MS = 150_000;
const MAX_LOG_LINES = 30;

// What each kind writes into the custody ledger once it confirms.
const LEDGER = {
	transfer: { eventType: 'spend', category: 'transfer' },
	withdraw: { eventType: 'withdraw', category: 'withdraw' },
	swap: { eventType: 'spend', category: 'trade' },
	session_grant: { eventType: 'signer_session_grant', category: 'custody' },
	session_revoke: { eventType: 'signer_session_revoke', category: 'custody' },
};

export const EXTERNAL_TX_KINDS = Object.freeze(Object.keys(LEDGER));

// Hooks other custody modules register to run after a kind confirms (the
// session grant flips the signer to active, the revoke finalizes it). Kept as
// a registry so this module never imports its callers.
const confirmHooks = new Map();

/** Register `fn(row, signature)` to run after a transaction of `kind` confirms. */
export function onExternalTxConfirmed(kind, fn) {
	confirmHooks.set(kind, fn);
}

function b64(bytes) {
	return Buffer.from(bytes).toString('base64');
}

function versionOf(tx) {
	return tx.message.version === 'legacy' ? 'legacy' : 'v0';
}

/**
 * Stable identity for every account a compiled message references. Static keys
 * resolve to their base58; lookup-table accounts resolve to table + index, which
 * is exactly as specific as the message itself.
 */
function accountIdentities(message) {
	const ids = message.staticAccountKeys.map((k) => k.toBase58());
	const lookups = message.addressTableLookups || [];
	for (const l of lookups) for (const i of l.writableIndexes) ids.push(`${l.accountKey.toBase58()}#w${i}`);
	for (const l of lookups) for (const i of l.readonlyIndexes) ids.push(`${l.accountKey.toBase58()}#r${i}`);
	return ids;
}

/** Each instruction as `program|account,account|datahex`, order preserved. */
export function instructionFingerprints(message) {
	const ids = accountIdentities(message);
	return message.compiledInstructions.map((ix) => {
		const program = ids[ix.programIdIndex];
		const accounts = ix.accountKeyIndexes.map((i) => ids[i]).join(',');
		return `${program}|${accounts}|${Buffer.from(ix.data).toString('hex')}`;
	});
}

/**
 * Compare the message we prepared with the one the wallet signed.
 * @returns {{ ok: boolean, modified: boolean, reason?: string }}
 */
export function compareMessages(preparedBytes, signedMessage) {
	const signedBytes = Buffer.from(signedMessage.serialize());
	if (Buffer.compare(Buffer.from(preparedBytes), signedBytes) === 0) return { ok: true, modified: false };

	const prepared = VersionedMessage.deserialize(Buffer.from(preparedBytes));
	if (!prepared.staticAccountKeys[0].equals(signedMessage.staticAccountKeys[0])) {
		return { ok: false, modified: true, reason: 'fee payer changed' };
	}
	if (prepared.recentBlockhash !== signedMessage.recentBlockhash) {
		return { ok: false, modified: true, reason: 'recent blockhash changed' };
	}
	const signedSet = new Map();
	for (const f of instructionFingerprints(signedMessage)) signedSet.set(f, (signedSet.get(f) || 0) + 1);
	for (const f of instructionFingerprints(prepared)) {
		const n = signedSet.get(f) || 0;
		if (n === 0) return { ok: false, modified: true, reason: 'a prepared instruction is missing or was altered' };
		signedSet.set(f, n - 1);
	}
	return { ok: true, modified: true };
}

/**
 * Verify every required signature on a signed transaction, and that `expected`
 * is one of the signers.
 * @returns {{ ok: boolean, reason?: string, signature?: string }}
 */
export function verifySignatures(tx, expected) {
	const message = tx.message;
	const messageBytes = message.serialize();
	const required = message.header.numRequiredSignatures;
	const signers = message.staticAccountKeys.slice(0, required).map((k) => k.toBase58());
	if (!signers.includes(expected)) return { ok: false, reason: `the expected signer ${expected} is not a signer of this transaction` };
	for (let i = 0; i < required; i++) {
		const sig = tx.signatures[i];
		if (!sig || sig.every((b) => b === 0)) return { ok: false, reason: `missing signature for ${signers[i]}` };
		let valid = false;
		try {
			valid = ed25519.verify(sig, messageBytes, message.staticAccountKeys[i].toBytes());
		} catch {
			valid = false;
		}
		if (!valid) return { ok: false, reason: `invalid signature for ${signers[i]}` };
	}
	return { ok: true, signature: bs58.encode(tx.signatures[0]) };
}

function trimLogs(logs) {
	if (!Array.isArray(logs)) return [];
	return logs.length > MAX_LOG_LINES ? logs.slice(-MAX_LOG_LINES) : logs;
}

/**
 * Simulate an unsigned transaction against the live cluster. Throws a 422 with
 * the program logs when it would fail, so nobody is asked to sign a
 * transaction that cannot land.
 */
export async function simulateUnsigned(connection, transaction) {
	let result;
	try {
		result = await connection.simulateTransaction(transaction, {
			sigVerify: false,
			replaceRecentBlockhash: false,
			commitment: 'confirmed',
		});
	} catch (err) {
		throw Object.assign(new Error(`simulation failed upstream: ${err?.message || 'rpc error'}`), {
			status: 502, code: 'upstream_error', expose: true,
		});
	}
	const v = result?.value || {};
	const simulation = {
		ok: !v.err,
		err: v.err ? JSON.stringify(v.err) : null,
		units_consumed: v.unitsConsumed ?? null,
		logs: trimLogs(v.logs),
	};
	if (v.err) {
		const e = clientError('simulation_failed', `The transaction would fail on-chain: ${simulation.err}`, 422);
		e.detail = { simulation };
		throw e;
	}
	return simulation;
}

/**
 * Store an unsigned transaction for an external signer.
 *
 * @param {object} p
 * @param {string} p.userId
 * @param {string|null} [p.agentId]
 * @param {string} p.kind            one of EXTERNAL_TX_KINDS
 * @param {'mainnet'|'devnet'} p.network
 * @param {string} p.signer          base58 key that must sign
 * @param {VersionedTransaction} p.transaction
 * @param {object} p.summary         what the transaction does, in plain fields
 * @param {number|null} [p.lastValidBlockHeight]
 * @param {boolean} [p.simulate=true]
 * @returns {Promise<object>}        the public prepared shape
 */
export async function prepareExternalTx({ userId, agentId = null, kind, network, signer, transaction, summary, lastValidBlockHeight = null, simulate = true, connection = null }) {
	if (!LEDGER[kind]) throw new Error(`unknown external tx kind: ${kind}`);
	const conn = connection || solanaConnection({ network, commitment: 'confirmed' });
	const required = transaction.message.staticAccountKeys
		.slice(0, transaction.message.header.numRequiredSignatures)
		.map((k) => k.toBase58());
	if (!required.includes(signer)) throw new Error(`prepared transaction does not require a signature from ${signer}`);

	const simulation = simulate ? await simulateUnsigned(conn, transaction) : null;
	const messageB64 = b64(transaction.message.serialize());
	const txB64 = b64(transaction.serialize());
	const expiresAt = new Date(Date.now() + PREPARED_TTL_MS);

	const [row] = await sql`
		INSERT INTO pending_external_txs
			(user_id, agent_id, kind, network, signer_pubkey, message_b64, tx_b64, tx_version,
			 summary, simulation, last_valid_block_height, expires_at)
		VALUES
			(${userId}, ${agentId}, ${kind}, ${network}, ${signer}, ${messageB64}, ${txB64}, ${versionOf(transaction)},
			 ${JSON.stringify(summary || {})}::jsonb, ${simulation ? JSON.stringify(simulation) : null}::jsonb,
			 ${lastValidBlockHeight}, ${expiresAt.toISOString()})
		RETURNING id, created_at
	`;
	return {
		tx_id: row.id,
		signer: 'external',
		kind,
		network,
		signer_pubkey: signer,
		transaction: txB64,
		encoding: 'base64',
		version: versionOf(transaction),
		summary: summary || {},
		simulation,
		last_valid_block_height: lastValidBlockHeight,
		expires_at: expiresAt.toISOString(),
		submit: { method: 'POST', path: '/api/tx/submit', body: { tx_id: row.id, signed_transaction: '<base64>' } },
	};
}

/** The public view of a pending row. */
export function publicExternalTx(row) {
	return {
		tx_id: row.id,
		kind: row.kind,
		network: row.network,
		agent_id: row.agent_id,
		signer_pubkey: row.signer_pubkey,
		status: row.status,
		signature: row.signature,
		message_modified: row.message_modified,
		summary: row.summary,
		custody_event_id: row.custody_event_id,
		error: row.error,
		expires_at: row.expires_at,
		submitted_at: row.submitted_at,
		confirmed_at: row.confirmed_at,
		created_at: row.created_at,
	};
}

export async function getExternalTx(txId, userId) {
	const [row] = await sql`SELECT * FROM pending_external_txs WHERE id = ${txId} AND user_id = ${userId}`;
	return row || null;
}

export async function listExternalTxs(userId, { agentId = null, limit = 25 } = {}) {
	const lim = Math.min(100, Math.max(1, Number(limit) || 25));
	return sql`
		SELECT * FROM pending_external_txs
		WHERE user_id = ${userId} AND (${agentId}::uuid IS NULL OR agent_id = ${agentId})
		ORDER BY created_at DESC
		LIMIT ${lim}
	`;
}

function decodeSigned(signedB64) {
	if (typeof signedB64 !== 'string' || !signedB64.trim()) {
		throw clientError('invalid_transaction', 'signed_transaction must be a base64-encoded transaction');
	}
	try {
		return VersionedTransaction.deserialize(Buffer.from(signedB64.trim(), 'base64'));
	} catch {
		throw clientError('invalid_transaction', 'signed_transaction could not be decoded as a Solana transaction');
	}
}

async function reconcileToLedger(row, signature) {
	if (!row.agent_id) return null;
	const map = LEDGER[row.kind];
	const s = row.summary || {};
	const lamports = s.asset === 'SOL' && s.amount_raw ? s.amount_raw : null;
	return recordCustodyEvent({
		agentId: row.agent_id,
		userId: row.user_id,
		eventType: map.eventType,
		category: map.category,
		network: row.network,
		asset: s.asset ?? null,
		amountLamports: lamports,
		amountRaw: s.amount_raw ?? null,
		usd: typeof s.usd === 'number' ? s.usd : null,
		destination: s.to ?? s.output_mint ?? s.delegate ?? null,
		signature,
		reason: `external_${row.kind}`,
		status: 'confirmed',
		idempotencyKey: `external:${row.id}`,
		meta: {
			signer: 'external',
			signer_pubkey: row.signer_pubkey,
			tx_id: row.id,
			message_modified: row.message_modified,
			summary: s,
		},
	});
}

/**
 * Verify, broadcast, confirm, and reconcile a signed external transaction.
 * Idempotent: a repeat submit of a confirmed row returns it unchanged.
 */
export async function submitExternalTx({ userId, txId, signedTransaction, connection = null }) {
	const row = await getExternalTx(txId, userId);
	if (!row) throw clientError('not_found', 'No prepared transaction with that tx_id for this account.', 404);
	if (row.status === 'confirmed') return { ...publicExternalTx(row), replayed: true };
	if (row.status === 'submitted') throw clientError('in_flight', 'This transaction is already being submitted. Poll GET /api/tx/submit?tx_id= for its result.', 409);
	if (row.status === 'failed') throw clientError('already_failed', `This transaction already failed (${row.error || 'unknown error'}). Prepare a new one.`, 409);
	if (row.status === 'expired' || new Date(row.expires_at).getTime() < Date.now()) {
		await sql`UPDATE pending_external_txs SET status = 'expired', updated_at = now() WHERE id = ${row.id} AND status = 'prepared'`;
		throw clientError('expired', 'This prepared transaction expired before it was signed. Prepare it again; blockhashes are only valid for about a minute.', 410);
	}

	const tx = decodeSigned(signedTransaction);
	const cmp = compareMessages(Buffer.from(row.message_b64, 'base64'), tx.message);
	if (!cmp.ok) throw clientError('transaction_mismatch', `The signed transaction does not match what was prepared: ${cmp.reason}.`, 422);
	const sig = verifySignatures(tx, row.signer_pubkey);
	if (!sig.ok) throw clientError('invalid_signature', sig.reason, 422);

	// Claim the row: exactly one submit wins even under concurrent retries.
	const [claimed] = await sql`
		UPDATE pending_external_txs
		SET status = 'submitted', signature = ${sig.signature}, message_modified = ${cmp.modified},
		    submitted_at = now(), updated_at = now()
		WHERE id = ${row.id} AND status = 'prepared'
		RETURNING *
	`;
	if (!claimed) {
		const fresh = await getExternalTx(txId, userId);
		if (fresh?.status === 'confirmed') return { ...publicExternalTx(fresh), replayed: true };
		throw clientError('in_flight', 'This transaction is already being submitted.', 409);
	}

	const conn = connection || solanaConnection({ network: row.network, commitment: 'confirmed' });
	const raw = Buffer.from(tx.serialize());
	try {
		await conn.sendRawTransaction(raw, { skipPreflight: false, preflightCommitment: 'confirmed', maxRetries: 3 });
	} catch (err) {
		const msg = String(err?.message || err);
		// A duplicate submit of an already-landed transaction is success, not failure.
		if (!/already been processed|AlreadyProcessed/i.test(msg)) {
			await markFailed(claimed.id, `broadcast rejected: ${msg.slice(0, 400)}`);
			throw clientError('broadcast_failed', `The network rejected the transaction: ${msg.slice(0, 300)}`, 422);
		}
	}

	const strategy = claimed.last_valid_block_height
		? { signature: sig.signature, blockhash: tx.message.recentBlockhash, lastValidBlockHeight: Number(claimed.last_valid_block_height) }
		: sig.signature;
	let confirmation;
	try {
		confirmation = await pollConfirmation(conn, strategy, 'confirmed');
	} catch (err) {
		// Unknown outcome: leave it 'submitted' so a later GET re-checks the chain.
		throw Object.assign(new Error(`confirmation timed out: ${err?.message || 'unknown'}`), {
			status: 202, code: 'pending_confirmation', expose: true,
			detail: { tx_id: claimed.id, signature: sig.signature },
		});
	}
	if (confirmation?.value?.err) {
		await markFailed(claimed.id, `reverted on-chain: ${JSON.stringify(confirmation.value.err)}`);
		throw clientError('reverted', `The transaction landed but reverted: ${JSON.stringify(confirmation.value.err)}`, 422);
	}
	return finalizeConfirmed(claimed, sig.signature);
}

async function markFailed(id, message) {
	await sql`UPDATE pending_external_txs SET status = 'failed', error = ${message}, updated_at = now() WHERE id = ${id}`;
}

async function finalizeConfirmed(row, signature) {
	const custodyEventId = await reconcileToLedger(row, signature);
	const [done] = await sql`
		UPDATE pending_external_txs
		SET status = 'confirmed', confirmed_at = now(), custody_event_id = ${custodyEventId}, updated_at = now()
		WHERE id = ${row.id}
		RETURNING *
	`;
	const hook = confirmHooks.get(row.kind);
	if (hook) await hook(done, signature);
	return publicExternalTx(done);
}

/**
 * Re-check a 'submitted' row whose confirmation timed out. Returns the row as it
 * stands after the check.
 */
export async function refreshSubmittedTx(txId, userId, { connection = null } = {}) {
	const row = await getExternalTx(txId, userId);
	if (!row) return null;
	if (row.status !== 'submitted' || !row.signature) return publicExternalTx(row);
	const conn = connection || solanaConnection({ network: row.network, commitment: 'confirmed' });
	let status = null;
	try {
		const res = await conn.getSignatureStatuses([row.signature], { searchTransactionHistory: true });
		status = res?.value?.[0] || null;
	} catch {
		return publicExternalTx(row);
	}
	if (status?.err) {
		await markFailed(row.id, `reverted on-chain: ${JSON.stringify(status.err)}`);
		return publicExternalTx(await getExternalTx(txId, userId));
	}
	if (status && (status.confirmationStatus === 'confirmed' || status.confirmationStatus === 'finalized')) {
		return finalizeConfirmed(row, row.signature);
	}
	if (!status && new Date(row.expires_at).getTime() + 60_000 < Date.now()) {
		const height = await conn.getBlockHeight('confirmed').catch(() => null);
		if (height != null && row.last_valid_block_height && height > Number(row.last_valid_block_height)) {
			await markFailed(row.id, 'expired: the blockhash lapsed before the transaction landed');
			return publicExternalTx(await getExternalTx(txId, userId));
		}
	}
	return publicExternalTx(row);
}

/** Normalize a base58 key or throw a 400 naming the field. */
export function requirePubkey(value, field) {
	try {
		const pk = new PublicKey(String(value || '').trim());
		return pk.toBase58();
	} catch {
		throw clientError('invalid_parameter', `${field} must be a base58 Solana address`);
	}
}