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.

8.2 KB
Raw Blame
// Avatar demo wallet — a single custodial Solana wallet that an embeddable
// 3D-avatar widget owns and can autonomously spend from (see
// /api/agent/wallet, /api/agent/send-sol and pages/avatar-wallet-chat.html).
//
// Security model (deliberately scoped for a low-value demo wallet):
//   - The signing secret never leaves the server — it lives only in the
//     AVATAR_WALLET_SECRET env var and is loaded on demand to sign.
//   - Every send is hard-capped at AVATAR_MAX_SEND_USD (default $2) so a
//     compromised/abused widget can move at most a couple of dollars per call.
//   - The recipient is validated as a real base58 pubkey; an optional
//     AVATAR_DEFAULT_RECIPIENT is the "send me" target when none is given.
//   - Fund this wallet with only a few dollars of SOL. It is a demo wallet,
//     not a treasury.

import {
	Connection,
	Keypair,
	LAMPORTS_PER_SOL,
	PublicKey,
	SystemProgram,
	Transaction,
	TransactionInstruction,
} from '@solana/web3.js';
import { solanaConnection } from './solana/connection.js';
import { submitProtected } from './execution-engine.js';
import { solPriceUsd } from './sol-price.js';
import bs58 from 'bs58';

const bs58decode = bs58.default ? bs58.default.decode : bs58.decode;

// SPL Memo program — used to stamp every avatar payment on-chain so the
// transaction is self-describing in an explorer.
const MEMO_PROGRAM_ID = new PublicKey('MemoSq4gqABAXKb96qnH8TysNcWxMyWCqXgDLGmfcHr');

const DEFAULT_MAINNET_RPC = 'https://api.mainnet-beta.solana.com';
const DEFAULT_DEVNET_RPC = 'https://api.devnet.solana.com';

/**
 * Parse a Solana secret key from any of the common encodings into a Keypair:
 *   - JSON byte array ("[12,34,...]")
 *   - base58 string (Phantom export format)
 *   - base64 string (64-byte secret)
 * Throws a tagged error if no/invalid secret is supplied.
 */
export function loadAvatarKeypair(secret) {
	const trimmed = (secret || '').trim();
	if (!trimmed) {
		throw Object.assign(new Error('avatar wallet not configured (set AVATAR_WALLET_SECRET)'), {
			code: 'no_wallet',
		});
	}

	let bytes = null;
	if (trimmed.startsWith('[')) {
		bytes = Uint8Array.from(JSON.parse(trimmed));
	} else {
		// Try base58 first (Phantom), then base64. A 64-byte result wins.
		for (const decode of [() => bs58decode(trimmed), () => new Uint8Array(Buffer.from(trimmed, 'base64'))]) {
			try {
				const b = decode();
				if (b && b.length === 64) {
					bytes = b;
					break;
				}
			} catch {
				/* try next encoding */
			}
		}
	}

	if (!bytes || bytes.length !== 64) {
		throw Object.assign(new Error('invalid AVATAR_WALLET_SECRET (expected a 64-byte base58/base64/json secret key)'), {
			code: 'bad_wallet',
		});
	}
	return Keypair.fromSecretKey(Uint8Array.from(bytes));
}

/** Resolve the avatar wallet configuration from the environment. */
export function avatarWalletConfig() {
	const secret = process.env.AVATAR_WALLET_SECRET || '';
	const network = (process.env.AVATAR_NETWORK || 'mainnet').toLowerCase() === 'devnet' ? 'devnet' : 'mainnet';
	const rpcUrl =
		network === 'devnet'
			? process.env.SOLANA_RPC_URL_DEVNET || DEFAULT_DEVNET_RPC
			: process.env.SOLANA_RPC_URL || DEFAULT_MAINNET_RPC;

	const maxSendUsd = clampNumber(parseFloat(process.env.AVATAR_MAX_SEND_USD || '2'), 0.01, 100);
	const defaultRecipient = (process.env.AVATAR_DEFAULT_RECIPIENT || '').trim() || null;
	const demoToken = (process.env.AVATAR_DEMO_TOKEN || '').trim() || null;
	// When set, every send is forced to AVATAR_DEFAULT_RECIPIENT and any
	// client-supplied `to` is ignored — makes the wallet drain-proof (it can
	// only ever pay you, regardless of who hits the endpoint).
	const lockRecipient = ['1', 'true', 'yes'].includes((process.env.AVATAR_LOCK_RECIPIENT || '').trim().toLowerCase());

	let address = null;
	let configured = false;
	if (secret) {
		try {
			address = loadAvatarKeypair(secret).publicKey.toBase58();
			configured = true;
		} catch {
			configured = false;
		}
	}

	return { configured, address, network, rpcUrl, maxSendUsd, defaultRecipient, demoToken, lockRecipient };
}

/** True when `s` is a parseable Solana public key. */
export function isValidPubkey(s) {
	try {
		// eslint-disable-next-line no-new
		new PublicKey(String(s));
		return true;
	} catch {
		return false;
	}
}

let _connByUrl = new Map();
export function getConnection(rpcUrl) {
	const url = rpcUrl || DEFAULT_MAINNET_RPC;
	if (!_connByUrl.has(url)) _connByUrl.set(url, solanaConnection({ url: url, commitment: 'confirmed' }));
	return _connByUrl.get(url);
}

/**
 * Live SOL/USD price. Delegates to the canonical 7-source failover in
 * api/_lib/sol-price.js (Kraken/Coinbase/Bitfinex/CoinGecko/Jupiter/DefiLlama/DIA,
 * cached 60s) instead of the old two-source inline fetch. Preserves this
 * function's throw-on-failure contract: money-moving callers (send-sol, deal,
 * settle-fee) rely on a thrown `price_unavailable` to refuse a send rather than
 * value it against a zero price — solPriceUsd() returns 0 on total failure, so we
 * translate that back into the throw the callers expect.
 */
export async function solUsdPrice() {
	const usd = await solPriceUsd();
	if (!(Number(usd) > 0)) {
		throw Object.assign(new Error('SOL price unavailable'), { code: 'price_unavailable' });
	}
	return Number(usd);
}

/** Native SOL balance (lamports + SOL) for a pubkey on the given connection. */
export async function getSolBalance(connection, pubkey) {
	const pk = pubkey instanceof PublicKey ? pubkey : new PublicKey(pubkey);
	const lamports = await connection.getBalance(pk, 'confirmed');
	return { lamports, sol: lamports / LAMPORTS_PER_SOL };
}

/**
 * Build and locally sign a native SOL transfer (with an optional memo) against
 * the given recent blockhash. Returns the signed Transaction without
 * broadcasting — split out from sendSol so the exact tx the endpoint submits
 * can be verified offline (see scripts/verify-send-sol.mjs).
 */
function buildSolTransferInstructions({ fromKeypair, to, lamports, memo }) {
	const toPubkey = to instanceof PublicKey ? to : new PublicKey(to);
	const lamportsInt = Math.round(Number(lamports));
	if (!Number.isFinite(lamportsInt) || lamportsInt <= 0) {
		throw Object.assign(new Error('transfer amount must be a positive number of lamports'), { code: 'bad_amount' });
	}
	const ixs = [SystemProgram.transfer({ fromPubkey: fromKeypair.publicKey, toPubkey, lamports: lamportsInt })];
	if (memo) {
		ixs.push(
			new TransactionInstruction({
				programId: MEMO_PROGRAM_ID,
				keys: [],
				data: Buffer.from(String(memo).slice(0, 180), 'utf8'),
			}),
		);
	}
	return ixs;
}

export function buildSignedSolTransfer({ fromKeypair, to, lamports, memo, blockhash }) {
	const tx = new Transaction().add(...buildSolTransferInstructions({ fromKeypair, to, lamports, memo }));
	tx.feePayer = fromKeypair.publicKey;
	tx.recentBlockhash = blockhash;
	tx.sign(fromKeypair);
	return tx;
}

/**
 * Sign and submit a native SOL transfer, returning the signature on confirmation.
 * The single money-moving primitive shared by /api/agent/send-sol, the chat
 * sendSol tool, the agent economy, and the verification script. Routes through
 * the protected sender: data-driven priority fee + CU, rebroadcast with blockhash
 * refresh, and a hard throw on an on-chain revert — so a send no longer drops
 * silently under congestion or reports a reverted transfer as success.
 */
export async function sendSol({ connection, fromKeypair, to, lamports, memo, network = 'mainnet' }) {
	const instructions = buildSolTransferInstructions({ fromKeypair, to, lamports, memo });
	const { signature } = await submitProtected({ network, connection, payer: fromKeypair, instructions });
	return signature;
}

/** Build the Solscan URL for a signature on the active network. */
export function explorerTxUrl(signature, network) {
	const cluster = network === 'devnet' ? '?cluster=devnet' : '';
	return `https://solscan.io/tx/${signature}${cluster}`;
}

/** Build the Solscan account URL for an address on the active network. */
export function explorerAccountUrl(address, network) {
	const cluster = network === 'devnet' ? '?cluster=devnet' : '';
	return `https://solscan.io/account/${address}${cluster}`;
}

function clampNumber(n, min, max) {
	if (!Number.isFinite(n)) return min;
	return Math.min(max, Math.max(min, n));
}

export { LAMPORTS_PER_SOL, PublicKey };