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.
JavaScript 3d-generationai-agentsanimationavatardigital-humangenerative-aiglbgltfimage-to-3dllmmcpmcp-servermodel-context-protocolsolanatext-to-3dthreejsweb-componentswebglwebxrx402
// Owner-funded agent budgets enforced by the chain: the Solana Subscriptions
// and Allowances program (@solana/subscriptions, MIT, Solana Foundation).
//
// The owner keeps funds in their OWN token account and signs one transaction
// that creates a fixed-delegation allowance (mint, cap, expiry) naming the
// agent's custodial wallet as delegatee. The agent can then pull up to the
// remaining allowance and not a lamport more, and the owner can revoke at any
// time with one signature. The cap is enforced by the program, not by our
// database; this module only (a) builds the unsigned owner transactions with
// the official generated client, (b) reads live allowance state off chain, and
// (c) exposes the remaining allowance as a hard ceiling so a pull the program
// would reject is refused before a transaction is ever built.
//
// Nothing here signs for the owner. The agent-side pull is signed with the
// agent's own custodial key by the caller (api/agents/solana-allowance.js).
import { PublicKey, Transaction, TransactionInstruction } from '@solana/web3.js';
import { getAssociatedTokenAddressSync, TOKEN_PROGRAM_ID, TOKEN_2022_PROGRAM_ID } from '@solana/spl-token';
import { address, createNoopSigner, createSolanaRpc } from '@solana/kit';
import {
SUBSCRIPTIONS_PROGRAM_ADDRESS,
UNKNOWN_INIT_ID,
fetchMaybeSubscriptionAuthority,
fetchMaybeFixedDelegation,
fetchMaybeRecurringDelegation,
findSubscriptionAuthorityPda,
findFixedDelegationPda,
findRecurringDelegationPda,
getInitSubscriptionAuthorityOverlayInstructionAsync,
getCreateFixedDelegationOverlayInstructionAsync,
getCreateRecurringDelegationOverlayInstructionAsync,
getRevokeDelegationOverlayInstruction,
getTransferFixedOverlayInstructionAsync,
getTransferRecurringOverlayInstructionAsync,
getSubscriptionsErrorMessage,
} from '@solana/subscriptions';
export const ALLOWANCE_PROGRAM_ID = SUBSCRIPTIONS_PROGRAM_ADDRESS;
const SOLANA_ADDRESS_RE = /^[1-9A-HJ-NP-Za-km-z]{32,44}$/;
const U64_MAX = (1n << 64n) - 1n;
export class AllowanceError extends Error {
constructor(code, message, extra = {}) {
super(message);
this.code = code;
this.extra = extra;
}
}
/** Recurring pulls (agent-to-agent subscriptions) ship behind a flag. */
export function recurringEnabled(env = process.env) {
return env.ALLOWANCE_RECURRING_ENABLED === '1' || env.ALLOWANCE_RECURRING_ENABLED === 'true';
}
function assertAddress(value, name) {
if (typeof value !== 'string' || !SOLANA_ADDRESS_RE.test(value)) {
throw new AllowanceError('invalid_request', `${name} must be a base58 Solana address`);
}
try {
new PublicKey(value);
} catch {
throw new AllowanceError('invalid_request', `${name} is not a valid Solana address`);
}
return value;
}
function toBigInt(value, name) {
try {
const n = typeof value === 'bigint' ? value : BigInt(String(value));
if (n < 0n || n > U64_MAX) throw new Error('range');
return n;
} catch {
throw new AllowanceError('invalid_request', `${name} must be a non-negative integer that fits in u64`);
}
}
// Kit AccountRole: 0 readonly, 1 writable, 2 readonly signer, 3 writable signer.
export function kitInstructionToWeb3(ix) {
return new TransactionInstruction({
programId: new PublicKey(ix.programAddress),
keys: (ix.accounts ?? []).map((a) => ({
pubkey: new PublicKey(a.address),
isSigner: a.role >= 2,
isWritable: (a.role & 1) === 1,
})),
data: Buffer.from(ix.data ?? []),
});
}
// The shared RPC pool is imported lazily so the pure ceiling math and the
// transaction builders stay loadable (and testable) with an injected connection.
async function connectionFor(network, connection) {
if (connection) return connection;
const { solanaConnection } = await import('./solana/connection.js');
return solanaConnection({ network });
}
function kitRpc(conn) {
return createSolanaRpc(conn.rpcEndpoint);
}
async function tokenProgramFor(connection, mint) {
const info = await connection.getAccountInfo(new PublicKey(mint), 'confirmed');
if (!info) throw new AllowanceError('mint_not_found', 'that token mint does not exist on this network');
if (info.owner.equals(TOKEN_PROGRAM_ID)) return TOKEN_PROGRAM_ID;
if (info.owner.equals(TOKEN_2022_PROGRAM_ID)) return TOKEN_2022_PROGRAM_ID;
throw new AllowanceError('mint_unsupported', 'that account is not an SPL or Token-2022 mint');
}
function ownerAta(mint, owner, tokenProgram) {
return getAssociatedTokenAddressSync(new PublicKey(mint), new PublicKey(owner), true, tokenProgram);
}
// ── pure ceiling math ─────────────────────────────────────────────────────────
/**
* Remaining pullable amount of a recurring delegation right now. A period that
* has fully elapsed resets the pulled counter, mirroring the program.
*/
export function recurringRemaining({ amountPerPeriod, amountPulledInPeriod, currentPeriodStartTs, periodLengthS }, nowTs) {
const per = BigInt(amountPerPeriod);
const start = BigInt(currentPeriodStartTs);
const len = BigInt(periodLengthS);
if (BigInt(nowTs) < start) return 0n;
if (len > 0n && BigInt(nowTs) >= start + len) return per;
const left = per - BigInt(amountPulledInPeriod);
return left > 0n ? left : 0n;
}
/**
* The hard ceiling. `remaining` is the live on-chain allowance; `ownerBalance`
* is the owner's token balance (an allowance cannot move funds the owner does
* not hold). A request above either, past expiry, or with no allowance at all
* is refused here, before any transaction exists.
*/
export function checkAllowanceCeiling({ remaining, expiryTs = 0n, ownerBalance = null, amount, nowTs = Math.floor(Date.now() / 1000) }) {
const want = BigInt(amount);
if (want <= 0n) return { allow: false, code: 'invalid_amount', reason: 'pull amount must be greater than zero' };
if (remaining == null) {
return { allow: false, code: 'no_allowance', reason: 'no active on-chain allowance for this agent and token' };
}
const exp = BigInt(expiryTs ?? 0n);
if (exp !== 0n && BigInt(nowTs) >= exp) {
return { allow: false, code: 'allowance_expired', reason: 'the owner-funded allowance has expired' };
}
const left = BigInt(remaining);
if (want > left) {
return {
allow: false,
code: 'allowance_exceeded',
reason: `requested ${want} exceeds the remaining on-chain allowance of ${left}`,
detail: { remaining: left.toString(), requested: want.toString() },
};
}
if (ownerBalance != null && want > BigInt(ownerBalance)) {
return {
allow: false,
code: 'owner_balance_low',
reason: `the owner's token account holds ${BigInt(ownerBalance)}, less than the requested ${want}`,
detail: { ownerBalance: BigInt(ownerBalance).toString(), requested: want.toString() },
};
}
return { allow: true, code: 'ok', reason: 'within the on-chain allowance', detail: { remaining: left.toString() } };
}
// ── unsigned owner transactions ───────────────────────────────────────────────
async function finalizeUnsigned(connection, feePayer, instructions) {
const { blockhash, lastValidBlockHeight } = await connection.getLatestBlockhash('confirmed');
const tx = new Transaction({ feePayer: new PublicKey(feePayer), blockhash, lastValidBlockHeight });
tx.add(...instructions);
const serialized = tx.serialize({ requireAllSignatures: false, verifySignatures: false });
return { transaction: serialized.toString('base64'), blockhash, lastValidBlockHeight };
}
/**
* Build the owner's create-allowance transaction, unsigned. Adds the one-time
* SubscriptionAuthority init for this mint when the owner has none yet.
*/
export async function prepareCreateAllowance({
network = 'mainnet',
owner,
delegatee,
mint,
amount,
expiryTs,
nonce = BigInt(Date.now()),
kind = 'fixed',
periodLengthS,
startTs = 0,
connection = null,
env = process.env,
}) {
assertAddress(owner, 'owner');
assertAddress(delegatee, 'delegatee');
assertAddress(mint, 'mint');
if (owner === delegatee) throw new AllowanceError('invalid_request', 'the agent wallet must differ from the owner wallet');
if (kind !== 'fixed' && kind !== 'recurring') throw new AllowanceError('invalid_request', 'kind must be "fixed" or "recurring"');
if (kind === 'recurring' && !recurringEnabled(env)) {
throw new AllowanceError('feature_disabled', 'recurring allowances are not enabled on this deployment');
}
const cap = toBigInt(amount, 'amount');
if (cap === 0n) throw new AllowanceError('invalid_request', 'amount must be greater than zero');
const expiry = toBigInt(expiryTs ?? 0, 'expiryTs');
const nowTs = BigInt(Math.floor(Date.now() / 1000));
if (expiry !== 0n && expiry <= nowTs) throw new AllowanceError('invalid_request', 'expiryTs must be in the future');
if (kind === 'recurring') {
if (expiry === 0n) throw new AllowanceError('invalid_request', 'a recurring allowance needs an expiry');
if (!periodLengthS || BigInt(periodLengthS) <= 0n) throw new AllowanceError('invalid_request', 'periodLengthS is required for a recurring allowance');
}
const conn = await connectionFor(network, connection);
const rpc = kitRpc(conn);
const tokenProgram = await tokenProgramFor(conn, mint);
const userAta = ownerAta(mint, owner, tokenProgram);
const ataInfo = await conn.getAccountInfo(userAta, 'confirmed');
if (!ataInfo) {
throw new AllowanceError('owner_token_account_missing', 'the owner wallet has no token account for this mint yet; fund it first');
}
const ownerSigner = createNoopSigner(address(owner));
const [authorityPda] = await findSubscriptionAuthorityPda({ tokenMint: address(mint), user: address(owner) });
const authority = await fetchMaybeSubscriptionAuthority(rpc, authorityPda);
const instructions = [];
let expectedInitId;
if (!authority.exists) {
instructions.push(
await getInitSubscriptionAuthorityOverlayInstructionAsync({
owner: ownerSigner,
tokenMint: address(mint),
tokenProgram: address(tokenProgram.toBase58()),
userAta: address(userAta.toBase58()),
}),
);
expectedInitId = UNKNOWN_INIT_ID;
} else {
expectedInitId = authority.data.initId;
}
const common = {
delegator: ownerSigner,
delegatee: address(delegatee),
tokenMint: address(mint),
nonce,
expiryTs: expiry,
expectedSubscriptionAuthorityInitId: expectedInitId,
};
let delegationPda;
if (kind === 'fixed') {
instructions.push(await getCreateFixedDelegationOverlayInstructionAsync({ ...common, amount: cap }));
[delegationPda] = await findFixedDelegationPda({
subscriptionAuthority: authorityPda,
delegator: address(owner),
delegatee: address(delegatee),
nonce,
});
} else {
instructions.push(
await getCreateRecurringDelegationOverlayInstructionAsync({
...common,
amountPerPeriod: cap,
periodLengthS: BigInt(periodLengthS),
startTs: BigInt(startTs),
}),
);
[delegationPda] = await findRecurringDelegationPda({
subscriptionAuthority: authorityPda,
delegator: address(owner),
delegatee: address(delegatee),
nonce,
});
}
const built = await finalizeUnsigned(conn, owner, instructions.map(kitInstructionToWeb3));
return {
...built,
network,
kind,
owner,
delegatee,
mint,
tokenProgram: tokenProgram.toBase58(),
ownerTokenAccount: userAta.toBase58(),
amount: cap.toString(),
expiryTs: Number(expiry),
nonce: nonce.toString(),
delegationPda: String(delegationPda),
initializesAuthority: !authority.exists,
programId: ALLOWANCE_PROGRAM_ID,
};
}
/** Build the owner's one-click revoke transaction, unsigned. */
export async function prepareRevokeAllowance({ network = 'mainnet', owner, delegationPda, connection = null }) {
assertAddress(owner, 'owner');
assertAddress(delegationPda, 'delegationPda');
const conn = await connectionFor(network, connection);
const info = await conn.getAccountInfo(new PublicKey(delegationPda), 'confirmed');
if (!info) throw new AllowanceError('allowance_not_found', 'that allowance no longer exists on chain (already revoked or closed)');
const ix = getRevokeDelegationOverlayInstruction({
authority: createNoopSigner(address(owner)),
delegationAccount: address(delegationPda),
});
const built = await finalizeUnsigned(conn, owner, [kitInstructionToWeb3(ix)]);
return { ...built, network, owner, delegationPda, programId: ALLOWANCE_PROGRAM_ID };
}
// ── live on-chain state ───────────────────────────────────────────────────────
/**
* Read one allowance off chain by its delegation PDA. Returns null when the
* account is gone (revoked or closed). `remaining` is the live pullable amount.
*/
export async function readAllowance({ network = 'mainnet', kind = 'fixed', delegationPda, connection = null, nowTs = Math.floor(Date.now() / 1000) }) {
const conn = await connectionFor(network, connection);
const rpc = kitRpc(conn);
const fetcher = kind === 'recurring' ? fetchMaybeRecurringDelegation : fetchMaybeFixedDelegation;
const acct = await fetcher(rpc, address(delegationPda));
if (!acct.exists) return null;
const d = acct.data;
const mint = String(d.mint);
const owner = String(d.header.delegator);
const delegatee = String(d.header.delegatee);
const expiryTs = Number(d.expiryTs);
let remaining;
let cap;
if (kind === 'recurring') {
remaining = recurringRemaining(d, nowTs);
cap = d.amountPerPeriod;
} else {
remaining = d.amount;
cap = null;
}
return {
kind,
delegationPda,
owner,
delegatee,
mint,
remaining: remaining.toString(),
capOnChain: cap == null ? null : cap.toString(),
expiryTs,
expired: expiryTs !== 0 && nowTs >= expiryTs,
periodLengthS: kind === 'recurring' ? Number(d.periodLengthS) : null,
};
}
/** The owner's current balance of the mint (0n when the token account is absent). */
export async function readOwnerBalance({ network = 'mainnet', owner, mint, connection = null }) {
const conn = await connectionFor(network, connection);
const tokenProgram = await tokenProgramFor(conn, mint);
const ata = ownerAta(mint, owner, tokenProgram);
try {
const bal = await conn.getTokenAccountBalance(ata, 'confirmed');
return BigInt(bal.value.amount);
} catch {
return 0n;
}
}
/**
* Preflight for a pull: live allowance + owner balance run through the ceiling.
* This is the function the spend guards and the pull endpoint both call.
*/
export async function checkAllowancePull({ network = 'mainnet', kind = 'fixed', delegationPda, amount, connection = null }) {
const live = await readAllowance({ network, kind, delegationPda, connection });
if (!live) {
return { allow: false, code: 'no_allowance', reason: 'the allowance was revoked or no longer exists on chain', live: null };
}
const ownerBalance = await readOwnerBalance({ network, owner: live.owner, mint: live.mint, connection });
const verdict = checkAllowanceCeiling({ remaining: live.remaining, expiryTs: live.expiryTs, ownerBalance, amount });
return { ...verdict, live, ownerBalance: ownerBalance.toString() };
}
// ── agent-side pull ───────────────────────────────────────────────────────────
/**
* Build the pull transaction signed by the agent's custodial keypair. Funds land
* in the agent wallet's own token account (created idempotently if missing), so
* everything the agent does next with them still passes the existing guards.
* The caller must have run checkAllowancePull first; the program re-enforces
* the same limits regardless.
*/
export async function buildSignedPull({ network = 'mainnet', kind = 'fixed', delegationPda, owner, mint, amount, agentKeypair, connection = null }) {
const conn = await connectionFor(network, connection);
const tokenProgram = await tokenProgramFor(conn, mint);
const delegatorAta = ownerAta(mint, owner, tokenProgram);
const receiverAta = ownerAta(mint, agentKeypair.publicKey.toBase58(), tokenProgram);
const { createAssociatedTokenAccountIdempotentInstruction } = await import('@solana/spl-token');
const instructions = [
createAssociatedTokenAccountIdempotentInstruction(agentKeypair.publicKey, receiverAta, agentKeypair.publicKey, new PublicKey(mint), tokenProgram),
];
const input = {
amount: toBigInt(amount, 'amount'),
delegatee: createNoopSigner(address(agentKeypair.publicKey.toBase58())),
delegationPda: address(delegationPda),
delegator: address(owner),
delegatorAta: address(delegatorAta.toBase58()),
receiverAta: address(receiverAta.toBase58()),
tokenMint: address(mint),
tokenProgram: address(tokenProgram.toBase58()),
};
const kitIx = kind === 'recurring' ? await getTransferRecurringOverlayInstructionAsync(input) : await getTransferFixedOverlayInstructionAsync(input);
instructions.push(kitInstructionToWeb3(kitIx));
const { blockhash, lastValidBlockHeight } = await conn.getLatestBlockhash('confirmed');
const tx = new Transaction({ feePayer: agentKeypair.publicKey, blockhash, lastValidBlockHeight });
tx.add(...instructions);
tx.sign(agentKeypair);
return { tx, blockhash, lastValidBlockHeight, receiverAta: receiverAta.toBase58() };
}
/**
* Translate a program rejection (simulation error plus logs, or a thrown RPC
* error) into a message an owner can act on: the program's own text for its
* custom errors (e.g. "Transfer amount exceeds delegation limit"), and a plain
* explanation when the delegation account has been closed by a revoke.
*/
export function describeProgramFailure(err) {
const msg = String(err?.message ?? err ?? '');
if (msg.includes('InvalidAccountOwner')) {
return 'the allowance account no longer exists on chain (revoked or closed)';
}
const hex = msg.match(/custom program error: 0x([0-9a-f]+)/i);
const dec = msg.match(/"Custom":\s*(\d+)/);
const code = hex ? parseInt(hex[1], 16) : dec ? Number(dec[1]) : null;
if (code != null) {
try {
return getSubscriptionsErrorMessage(code);
} catch {
return `program error ${code}`;
}
}
return msg.slice(0, 300);
}