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.

18.6 KB
Raw Blame
// A2A (Agent-to-Agent) x402 transport — client side.
//
// Drives the two-leg handshake from the caller's perspective:
//   1. POST `{ method: "message/send", params: { message: { … } } }` to the
//      peer's A2A endpoint with the X-A2A-Extensions header. The peer replies
//      with a task in state `input-required` carrying `x402.payment.required`.
//   2. Build a `PaymentPayload`, POST it back with the same `taskId` and
//      `x402.payment.status: payment-submitted`. The peer verifies, runs the
//      handler, settles, and replies with state `completed` +
//      `x402.payment.receipts`.
//
// Rails:
//   • Solana (primary) — `exact` scheme as an SPL TransferChecked, built via the
//     official @x402/svm ExactSvmScheme, partially signed by the payer and
//     co-signed by the peer's facilitator fee payer. `createSolanaSigner(secret)`
//     yields the @solana/kit signer; `buildSolanaExactPayload()` the payload.
//   • EVM (fallback) — `exact` scheme as an EIP-3009 transferWithAuthorization.
//     `createPrivateKeySigner(privateKey)` uses viem's accounts API for Base /
//     other EVM chains; `buildEvmExactPayload()` builds the payload.

import { randomBytes, randomUUID } from 'node:crypto';

import bs58 from 'bs58';

import { fetchSafePublicUrlPinned } from '../ssrf-guard.js';

import {
	A2A_EXTENSIONS_HEADER,
	A2A_X402_EXTENSION_URI,
} from './a2a-server.js';
import {
	NETWORK_SOLANA_MAINNET,
	NETWORK_SOLANA_DEVNET,
	isSolanaNetwork,
	solanaLocalTestNetwork,
} from './solana-networks.js';

export { A2A_EXTENSIONS_HEADER, A2A_X402_EXTENSION_URI };

// Solana is the primary A2A settlement rail. CAIP-2 ids must match what the
// server advertises (api/_lib/x402/a2a-server.js → NETWORK_SOLANA_*); both the
// ids and the rail predicate come from solana-networks.js so the client, the
// spec module and the payload decoder can never drift apart.
export { NETWORK_SOLANA_MAINNET, NETWORK_SOLANA_DEVNET, isSolanaNetwork };

function isEvmExactNetwork(network) {
	return /^eip155:\d+$/.test(network);
}

// ── Errors ────────────────────────────────────────────────────────────────

export class A2AClientError extends Error {
	constructor(code, message, details) {
		super(message);
		this.code = code;
		this.details = details;
	}
}

// ── Signers ───────────────────────────────────────────────────────────────

// EIP-3009 transferWithAuthorization signer powered by viem. Returns an
// object `{ address, network, signAuthorization }` consumable by
// payA2A() / buildEvmExactPayload().
export async function createPrivateKeySigner(privateKey) {
	if (!privateKey || typeof privateKey !== 'string') {
		throw new A2AClientError(
			'invalid_signer',
			'createPrivateKeySigner: privateKey hex string required',
		);
	}
	const { privateKeyToAccount } = await import('viem/accounts');
	const account = privateKeyToAccount(privateKey.startsWith('0x') ? privateKey : `0x${privateKey}`);
	return {
		address: account.address,
		signAuthorization: async ({ domain, message }) => {
			const types = {
				TransferWithAuthorization: [
					{ name: 'from', type: 'address' },
					{ name: 'to', type: 'address' },
					{ name: 'value', type: 'uint256' },
					{ name: 'validAfter', type: 'uint256' },
					{ name: 'validBefore', type: 'uint256' },
					{ name: 'nonce', type: 'bytes32' },
				],
			};
			return account.signTypedData({
				domain,
				types,
				primaryType: 'TransferWithAuthorization',
				message,
			});
		},
	};
}

// Decode a Solana secret key from any of the encodings used across this
// codebase: a JSON byte array (solana-keygen), base58 (Phantom export), or
// base64. Returns the 64-byte expanded secret key.
function decodeSolanaSecret(secret) {
	const trimmed = String(secret).trim();
	if (trimmed.startsWith('[')) {
		try {
			const bytes = Uint8Array.from(JSON.parse(trimmed));
			if (bytes.length === 64) return bytes;
		} catch {
			/* fall through to the error below */
		}
		throw new A2AClientError('invalid_signer', 'Solana secret: malformed 64-byte JSON array');
	}
	for (const decode of [() => bs58.decode(trimmed), () => new Uint8Array(Buffer.from(trimmed, 'base64'))]) {
		try {
			const bytes = decode();
			if (bytes.length === 64) return bytes;
		} catch {
			/* try the next encoding */
		}
	}
	throw new A2AClientError(
		'invalid_signer',
		'Solana secret must be a 64-byte key encoded as base58, base64, or a JSON array',
	);
}

// Build a Solana @solana/kit signer from a platform-funded payer secret. The
// returned signer carries `.address` (the payer's base58 pubkey) and signs the
// SPL TransferChecked payment built by buildSolanaExactPayload().
export async function createSolanaSigner(secret) {
	if (!secret || typeof secret !== 'string') {
		throw new A2AClientError('invalid_signer', 'createSolanaSigner: secret key string required');
	}
	const { createKeyPairSignerFromBytes } = await import('@solana/kit');
	return createKeyPairSignerFromBytes(decodeSolanaSecret(secret));
}

// ── Payload builders ──────────────────────────────────────────────────────

function randomHex32() {
	return `0x${randomBytes(32).toString('hex')}`;
}

// Build a Solana `exact` PaymentPayload for a Solana `accepts` entry, using the
// official @x402/svm scheme. It constructs an SPL TransferChecked from the
// payer's USDC ATA to the peer's, with the peer-advertised `extra.feePayer` as
// the transaction fee payer (co-signed by the facilitator on /settle), and
// partially signs it with `signer`. The base64 wire transaction lands in
// `payload.transaction` — exactly what the server's confirmSolanaPayment decodes
// and PayAI settles. Shape mirrors buildEvmExactPayload so the A2A submit leg is
// rail-agnostic.
export async function buildSolanaExactPayload({ accept, signer, resource, rpcUrl }) {
	if (accept.scheme !== 'exact') {
		throw new A2AClientError(
			'unsupported_scheme',
			`a2a-client: only exact scheme supported on Solana, got ${accept.scheme}`,
		);
	}
	if (!accept.extra?.feePayer) {
		throw new A2AClientError(
			'missing_fee_payer',
			'a2a-client: Solana accept entry is missing extra.feePayer (facilitator co-signer)',
			{ network: accept.network },
		);
	}
	if (!signer || typeof signer.address !== 'string') {
		throw new A2AClientError(
			'invalid_signer',
			'buildSolanaExactPayload: a @solana/kit signer is required (try createSolanaSigner)',
		);
	}
	// @x402/svm allowlists the three public Solana CAIP-2 ids, and it consults
	// the network for exactly one thing: which RPC client to construct. On the
	// local test lane we already hand it the RPC URL, so present the devnet
	// shape to that selector while the payload keeps the lane's real id. The
	// built transaction is unaffected: it is signed against the blockhash of
	// whatever RPC `rpcUrl` names, which is the local validator.
	const localLane = solanaLocalTestNetwork();
	let schemeAccept = accept;
	if (localLane && accept.network === localLane) {
		if (!rpcUrl) {
			throw new A2AClientError(
				'missing_rpc_url',
				'buildSolanaExactPayload: the local Solana test lane requires an explicit rpcUrl',
				{ network: accept.network },
			);
		}
		schemeAccept = { ...accept, network: NETWORK_SOLANA_DEVNET };
	}
	const { ExactSvmScheme } = await import('@x402/svm');
	const scheme = new ExactSvmScheme(signer, rpcUrl ? { rpcUrl } : undefined);
	const built = await scheme.createPaymentPayload(2, schemeAccept);
	return {
		x402Version: built.x402Version || 2,
		scheme: 'exact',
		network: accept.network,
		resource,
		accepted: accept,
		payload: built.payload,
	};
}

// Build a Solana `upto` PaymentPayload for an `upto` accepts entry using the
// official @x402/svm upto client scheme. It signs a payment-channel `open`
// transaction whose deposit equals the offered cap; the seller later claims only
// the measured amount and the rest of the deposit returns to this signer.
//
// The cap IS the most this call can cost, so it is checked against the agent's
// own per-call limit BEFORE anything is signed: `maxPerCallAtomics` refuses an
// offer whose cap exceeds it, exactly as the spending-cap layer would for an
// `exact` price.
export async function buildSolanaUptoPayload({ accept, signer, resource, rpcUrl, maxPerCallAtomics }) {
	if (accept.scheme !== 'upto') {
		throw new A2AClientError(
			'unsupported_scheme',
			`a2a-client: buildSolanaUptoPayload needs an upto accept, got ${accept.scheme}`,
		);
	}
	if (maxPerCallAtomics != null && BigInt(accept.amount) > BigInt(maxPerCallAtomics)) {
		throw new A2AClientError(
			'cap_exceeds_limit',
			`a2a-client: upto cap ${accept.amount} exceeds the per-call limit ${maxPerCallAtomics}`,
			{ cap: String(accept.amount), limit: String(maxPerCallAtomics) },
		);
	}
	if (!accept.extra?.feePayer || !accept.extra?.receiverAuthorizer) {
		throw new A2AClientError(
			'missing_upto_extra',
			'a2a-client: upto accept is missing extra.feePayer or extra.receiverAuthorizer',
			{ network: accept.network },
		);
	}
	if (!signer || typeof signer.address !== 'string') {
		throw new A2AClientError(
			'invalid_signer',
			'buildSolanaUptoPayload: a @solana/kit signer is required (try createSolanaSigner)',
		);
	}
	const { UptoSvmScheme } = await import('@x402/svm/upto/client');
	const scheme = new UptoSvmScheme(signer, rpcUrl ? { rpcUrl } : undefined);
	const built = await scheme.createPaymentPayload(2, accept);
	return {
		x402Version: built.x402Version || 2,
		scheme: 'upto',
		network: accept.network,
		resource,
		accepted: accept,
		payload: built.payload,
	};
}

const CHAIN_ID_BY_NETWORK = {
	'eip155:8453': 8453, // Base mainnet
	'eip155:84532': 84532, // Base sepolia
	'eip155:1': 1, // Ethereum mainnet
	'eip155:137': 137, // Polygon
	'eip155:42161': 42161, // Arbitrum
};

function chainIdFor(network) {
	if (CHAIN_ID_BY_NETWORK[network]) return CHAIN_ID_BY_NETWORK[network];
	const m = /^eip155:(\d+)$/.exec(network);
	if (m) return Number(m[1]);
	throw new A2AClientError('unsupported_network', `a2a-client: cannot derive chainId from ${network}`);
}

// Build an EIP-3009 `exact` PaymentPayload for an EVM `accepts` entry.
export async function buildEvmExactPayload({ accept, signer, resource }) {
	if (accept.scheme !== 'exact') {
		throw new A2AClientError(
			'unsupported_scheme',
			`a2a-client: only exact scheme supported here, got ${accept.scheme}`,
		);
	}
	const chainId = chainIdFor(accept.network);
	const validAfter = 0;
	const validBefore = Math.floor(Date.now() / 1000) + (accept.maxTimeoutSeconds || 600);
	const nonce = randomHex32();
	const domain = {
		name: accept.extra?.name || 'USD Coin',
		version: accept.extra?.version || '2',
		chainId,
		verifyingContract: accept.asset,
	};
	const message = {
		from: signer.address,
		to: accept.payTo,
		value: accept.amount,
		validAfter,
		validBefore,
		nonce,
	};
	const signature = await signer.signAuthorization({ domain, message });
	return {
		x402Version: 2,
		scheme: 'exact',
		network: accept.network,
		resource,
		accepted: accept,
		payload: {
			signature,
			authorization: {
				from: signer.address,
				to: accept.payTo,
				value: accept.amount,
				validAfter: String(validAfter),
				validBefore: String(validBefore),
				nonce,
			},
		},
	};
}

// ── A2A protocol helpers ──────────────────────────────────────────────────

function buildJsonRpcRequest({ id, message }) {
	return {
		jsonrpc: '2.0',
		id: id || randomUUID(),
		method: 'message/send',
		params: { message },
	};
}

async function postJsonRpc(endpoint, body, extraHeaders) {
	// The peer endpoint is caller-controlled (validated once upstream), so the
	// POST goes through the pinned SSRF guard: the socket connects only to the
	// pre-validated IP and every redirect hop is re-validated, closing the
	// 302-to-internal and DNS-rebinding paths a hostile peer could use to read
	// internal JSON services through us. maxBytes bounds the reply body.
	const res = await fetchSafePublicUrlPinned(
		endpoint,
		{
			method: 'POST',
			headers: {
				'content-type': 'application/json',
				accept: 'application/json',
				[A2A_EXTENSIONS_HEADER]: A2A_X402_EXTENSION_URI,
				...(extraHeaders || {}),
			},
			body: JSON.stringify(body),
		},
		{ maxBytes: 2 * 1024 * 1024 },
	);
	const text = await res.text();
	let parsed;
	try {
		parsed = text ? JSON.parse(text) : {};
	} catch (err) {
		throw new A2AClientError('parse_error', `non-JSON A2A reply: ${err.message}`, { text });
	}
	if (!res.ok) {
		throw new A2AClientError(
			'transport_error',
			`A2A peer returned HTTP ${res.status}`,
			{ status: res.status, body: parsed },
		);
	}
	if (parsed.error) {
		throw new A2AClientError(
			'jsonrpc_error',
			parsed.error.message || 'JSON-RPC error',
			parsed.error,
		);
	}
	return parsed.result;
}

function readTaskStatus(task) {
	if (!task || task.kind !== 'task') {
		throw new A2AClientError('invalid_reply', 'expected `kind: "task"` in A2A reply');
	}
	return task.status?.state;
}

function readPaymentRequired(task) {
	const meta = task.status?.message?.metadata;
	if (meta?.['x402.payment.status'] !== 'payment-required') return null;
	const required = meta['x402.payment.required'];
	if (!required || !Array.isArray(required.accepts) || !required.accepts.length) {
		throw new A2AClientError(
			'malformed_payment_required',
			'task carries payment-required status but no accepts list',
			required,
		);
	}
	return required;
}

function readReceipts(task) {
	const meta = task.status?.message?.metadata;
	if (!meta) return null;
	return {
		status: meta['x402.payment.status'] || null,
		receipts: Array.isArray(meta['x402.payment.receipts']) ? meta['x402.payment.receipts'] : [],
		error: meta['x402.payment.error'] || null,
		lifecycle: meta['x402.payment.lifecycle'] || null,
	};
}

// Default network preference list — Solana first, EVM fallback. Callers can
// override by passing `networkPreference` to `payA2A`.
const DEFAULT_NETWORK_PREFERENCE = [
	NETWORK_SOLANA_MAINNET,
	'eip155:8453',
	'eip155:84532',
	'eip155:1',
];

function pickAccept(accepts, preference) {
	const order = preference?.length ? preference : DEFAULT_NETWORK_PREFERENCE;
	for (const net of order) {
		const match = accepts.find((a) => a.network === net && a.scheme === 'exact');
		if (match) return match;
	}
	// Fall back to the first `exact` accept on any rail we can settle — Solana
	// preferred over EVM when both are offered without an explicit preference.
	const solana = accepts.find((a) => a.scheme === 'exact' && isSolanaNetwork(a.network));
	if (solana) return solana;
	const evm = accepts.find((a) => a.scheme === 'exact' && isEvmExactNetwork(a.network));
	if (evm) return evm;
	throw new A2AClientError(
		'no_supported_accept',
		'a2a-client: peer offered no supported scheme=exact accept on Solana or EVM',
		{ accepts: accepts.map(({ network, scheme }) => ({ network, scheme })) },
	);
}

// ── Public client ─────────────────────────────────────────────────────────

// Send an initial unpaid message and return the peer's payment-required task.
export async function requestQuote({ endpoint, text = 'Initiate paid skill.', taskId }) {
	const message = {
		kind: 'message',
		role: 'user',
		messageId: randomUUID(),
		...(taskId ? { taskId } : {}),
		parts: [{ kind: 'text', text }],
	};
	const task = await postJsonRpc(endpoint, buildJsonRpcRequest({ message }));
	const required = readPaymentRequired(task);
	if (!required) {
		throw new A2AClientError(
			'unexpected_state',
			`expected payment-required, got state ${readTaskStatus(task) || 'unknown'}`,
			{ task },
		);
	}
	return { task, required, taskId: task.id };
}

// Submit a signed PaymentPayload for the given taskId and return the
// completed (or failed) task.
export async function submitPayment({
	endpoint,
	taskId,
	paymentPayload,
	text = 'Here is the payment authorization.',
}) {
	const message = {
		kind: 'message',
		role: 'user',
		messageId: randomUUID(),
		taskId,
		parts: [{ kind: 'text', text }],
		metadata: {
			'x402.payment.status': 'payment-submitted',
			'x402.payment.payload': paymentPayload,
		},
	};
	const task = await postJsonRpc(endpoint, buildJsonRpcRequest({ message }));
	const receipts = readReceipts(task);
	const state = readTaskStatus(task);
	return { task, state, ...receipts };
}

// End-to-end: quote → sign → submit. Returns the completed task plus parsed
// receipt fields. Throws A2AClientError on transport / signing / settlement
// failure.
export async function payA2A({
	endpoint,
	signer,
	solanaSigner,
	rpcUrl,
	text,
	networkPreference,
	onQuote,
}) {
	if (!endpoint) throw new A2AClientError('invalid_args', 'payA2A: endpoint is required');
	const hasEvmSigner = signer && typeof signer.signAuthorization === 'function';
	const hasSolanaSigner = solanaSigner && typeof solanaSigner.address === 'string';
	if (!hasEvmSigner && !hasSolanaSigner) {
		throw new A2AClientError(
			'invalid_signer',
			'payA2A: a Solana signer (createSolanaSigner) or EVM signer (createPrivateKeySigner) is required',
		);
	}

	const { task: quoteTask, required, taskId } = await requestQuote({ endpoint, text });
	if (typeof onQuote === 'function') {
		try {
			await onQuote({ task: quoteTask, required, taskId });
		} catch (err) {
			throw new A2AClientError('quote_rejected', err.message || 'caller rejected the quote');
		}
	}

	// Restrict selection to rails we actually hold a signer for, so we never
	// pick a Solana accept with only an EVM signer in hand (or vice-versa).
	const payable = required.accepts.filter((a) =>
		isSolanaNetwork(a.network) ? hasSolanaSigner : hasEvmSigner,
	);
	if (!payable.length) {
		throw new A2AClientError(
			'no_supported_accept',
			'payA2A: no peer accept matches an available signer',
			{ accepts: required.accepts.map(({ network, scheme }) => ({ network, scheme })) },
		);
	}
	const accept = pickAccept(payable, networkPreference);
	const resource = required.resource || { url: endpoint, mimeType: 'application/json' };
	const paymentPayload = isSolanaNetwork(accept.network)
		? await buildSolanaExactPayload({ accept, signer: solanaSigner, resource, rpcUrl })
		: await buildEvmExactPayload({ accept, signer, resource });

	const result = await submitPayment({ endpoint, taskId, paymentPayload });

	if (result.state !== 'completed') {
		throw new A2AClientError(
			result.error || 'payment_failed',
			result.receipts?.[0]?.errorReason ||
				`A2A task ended in state ${result.state}`,
			result,
		);
	}
	return result;
}