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
// Verify an on-chain SOL, USDC or $THREE transfer into the platform deposit
// wallet and credit the depositor's prepaid balance (api/_lib/credits.js).
//
// Trust model (server-authoritative — a client "I paid" claim is never trusted):
// 1. The transaction is confirmed and didn't error on-chain.
// 2. A SIGNER of the transaction is a Solana wallet linked to the authenticated
// user — binds the deposit to the right account and stops anyone from
// claiming someone else's transfer by pasting its signature.
// 3. The platform deposit wallet actually received funds — computed from pre/post
// balances (lamport delta for SOL, token-balance delta for $THREE), robust to
// a destination ATA created within the same transaction and to which transfer
// variant was used.
// 4. The credit is idempotent per (tx signature, asset) via a UNIQUE
// idempotency_key, so the same deposit can never be credited twice — while a
// single tx carrying both SOL and $THREE still credits each asset once.
// 5. Credits settle only once the tx is FINALIZED (rooted); a confirmed-but-not
// -finalized tx returns a retryable `pending` result so a reorg can never
// credit a deposit that later disappears.
//
// Deposited funds land in the treasury / x402 receive wallet — the platform's
// prepaid float. Spending credits is internal ledger accounting; the treasury →
// buyback / holder-reflection loop runs from there (see token/config.js economy
// note). Deposits are therefore NOT split on receipt.
import { solanaConnection } from './solana/connection.js';
import { sql } from './db.js';
import { env } from './env.js';
import { creditAccount } from './credits.js';
import {
TOKEN_MINT,
TOKEN_DECIMALS,
TOKEN_SYMBOL,
treasuryWalletOrNull,
creditBonusBps,
} from './token/config.js';
import { getTokenPriceUsd } from './token/price.js';
import { solanaMintUsdPrice } from './balances.js';
import { USDC_CREDIT_RATE } from './pricing/catalog.js';
const SOL_MINT = 'So11111111111111111111111111111111111111112';
const LAMPORTS_PER_SOL = 1_000_000_000;
// Circle's USDC mints per cluster (same table api/_lib/agent-usdc-transfer.js
// pays from). Devnet is only reachable outside production, see network below.
const USDC_MINT_BY_NETWORK = Object.freeze({
mainnet: 'EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v',
devnet: '4zMMC9srt5Ri5X14GAgXhaHii3GnPAEERYPJgZJDncDU',
});
const USDC_DECIMALS = 6;
export const DEPOSIT_ASSETS = Object.freeze(['SOL', 'USDC', 'THREE']);
/**
* Every asset the deposit wallet accepts, with how each one is priced. This is
* the single source the /api/credits payload and the deposit verifier share, so
* the credits page can only ever advertise an asset the verifier will credit.
* `rate.kind` is `fixed` (usd_per_unit is the published rate) or `live_price`
* (the mainnet quote at verification time). `bonus_bps` is extra credit on top
* of the USD value, from owner policy (THREE_CREDIT_BONUS_BPS); 0 means none.
* @param {'mainnet'|'devnet'} [network]
*/
export function depositAssetCatalog(network = 'mainnet') {
const net = network === 'devnet' ? 'devnet' : 'mainnet';
return [
{
asset: 'SOL',
label: 'SOL',
mint: SOL_MINT,
decimals: 9,
native: true,
rate: { kind: 'live_price', source: 'mainnet quote at verification' },
bonus_bps: 0,
},
{
asset: 'USDC',
label: 'USDC',
mint: USDC_MINT_BY_NETWORK[net],
decimals: USDC_DECIMALS,
native: false,
rate: { kind: 'fixed', usd_per_unit: USDC_CREDIT_RATE, source: 'published rate' },
bonus_bps: 0,
},
{
asset: 'THREE',
label: TOKEN_SYMBOL,
mint: TOKEN_MINT,
decimals: TOKEN_DECIMALS,
native: false,
rate: { kind: 'live_price', source: 'mainnet quote at verification' },
bonus_bps: creditBonusBps(),
},
];
}
/**
* The single Solana address users send deposits to. Defaults to the existing x402
* Solana receive wallet (then the treasury) so a working deploy needs no new env;
* set CREDITS_DEPOSIT_WALLET_SOLANA to route deposits to a dedicated wallet.
*/
export function depositWallet() {
return (
(process.env.CREDITS_DEPOSIT_WALLET_SOLANA || '').trim() ||
env.X402_PAY_TO_SOLANA ||
treasuryWalletOrNull() ||
null
);
}
function rpcUrl(network) {
return network === 'devnet'
? env.SOLANA_RPC_URL_DEVNET || 'https://api.devnet.solana.com'
: env.SOLANA_RPC_URL || 'https://api.mainnet-beta.solana.com';
}
function depositError(message, status = 422, code = 'deposit_unverified', extra = {}) {
return Object.assign(new Error(message), { status, code, ...extra });
}
function isSolAddress(s) {
return typeof s === 'string' && /^[1-9A-HJ-NP-Za-km-z]{32,44}$/.test(s);
}
/** Set of Solana addresses linked to a user (user_wallets + legacy wallet_address). */
export async function linkedSolanaWallets(user) {
const rows = await sql`
select address from user_wallets where user_id = ${user.id} and chain_type = 'solana'
`;
const set = new Set(rows.map((r) => r.address));
if (user.wallet_address && isSolAddress(user.wallet_address)) set.add(user.wallet_address);
return set;
}
function accountKeyStr(k) {
return k?.pubkey?.toString?.() || String(k?.pubkey ?? '');
}
/** Signers of a parsed transaction, as base58 strings. */
function signerSet(tx) {
const keys = tx.transaction?.message?.accountKeys || [];
const out = new Set();
for (const k of keys) if (k.signer) out.add(accountKeyStr(k));
return out;
}
// Net SPL atomics credited to `owner` for `mint`, from pre/post token balances.
function tokenCreditedTo(tx, { mint, owner }) {
const pre = tx.meta?.preTokenBalances || [];
const post = tx.meta?.postTokenBalances || [];
let delta = 0n;
for (const p of post) {
if (p.mint !== mint || p.owner !== owner) continue;
const before = pre.find((x) => x.accountIndex === p.accountIndex);
delta +=
BigInt(p.uiTokenAmount?.amount ?? '0') - BigInt(before?.uiTokenAmount?.amount ?? '0');
}
return delta;
}
// Net lamports credited to `owner`, from pre/post native balances (index-aligned
// with accountKeys in a parsed transaction).
function lamportsCreditedTo(tx, owner) {
const keys = tx.transaction?.message?.accountKeys || [];
const idx = keys.findIndex((k) => accountKeyStr(k) === owner);
if (idx < 0) return 0n;
const pre = BigInt(tx.meta?.preBalances?.[idx] ?? 0);
const post = BigInt(tx.meta?.postBalances?.[idx] ?? 0);
return post - pre;
}
/**
* Verify a deposit transaction and credit the user's prepaid balance.
* @param {{ user: object, asset: 'SOL'|'USDC'|'THREE', txSignature: string, network?: string }} args
* @returns {Promise<object>} credit result for the API response
*/
export async function verifyAndCreditDeposit({ user, asset, txSignature, network: requestedNetwork = 'mainnet' }) {
// Devnet only outside production. Credits are priced at the mainnet SOL and
// $THREE price and spend as real USDC through /api/pay/execute, so accepting a
// faucet-funded devnet transfer minted real money from nothing. Same rule as
// api/payments/solana/[action].js.
const network = requestedNetwork === 'devnet' && process.env.NODE_ENV !== 'production' ? 'devnet' : 'mainnet';
const sink = depositWallet();
if (!sink)
throw depositError('the deposit wallet is not configured', 503, 'deposit_unavailable');
const assetU = String(asset || '').toUpperCase();
if (!DEPOSIT_ASSETS.includes(assetU))
throw depositError(`asset must be one of ${DEPOSIT_ASSETS.join(', ')}`, 400, 'bad_request');
if (typeof txSignature !== 'string' || txSignature.length < 32 || txSignature.length > 128) {
throw depositError('a valid tx_signature is required', 400, 'bad_request');
}
const connection = solanaConnection({ url: rpcUrl(network), commitment: 'confirmed' });
// Credits settle only on a FINALIZED (rooted) transaction. A merely
// "confirmed" tx can still be dropped by a chain reorg, which would credit a
// deposit that later vanishes. getParsedTransaction at finalized commitment
// returns the tx only once it is rooted; until then we report a retryable
// `pending` result so the client polls instead of seeing a spurious error.
let tx;
try {
tx = await connection.getParsedTransaction(txSignature, {
maxSupportedTransactionVersion: 1,
commitment: 'finalized',
});
} catch {
tx = null;
}
if (!tx) {
// Not finalized yet, or genuinely unknown. Check the signature status to
// tell "confirmed, still finalizing" (keep polling) apart from "failed"
// and "not found" (stop).
let status = null;
try {
const { value } = await connection.getSignatureStatuses([txSignature], {
searchTransactionHistory: true,
});
status = value?.[0] || null;
} catch {
status = null;
}
if (status?.err) throw depositError('transaction failed on-chain', 422, 'tx_failed');
if (status && status.confirmationStatus !== 'finalized') {
return {
ok: false,
pending: true,
status: 'awaiting_finalization',
confirmation_status: status.confirmationStatus || 'processed',
tx_signature: txSignature,
message:
'Confirmed on-chain — finalizing. This takes a few seconds, then your credits land automatically.',
};
}
throw depositError(
'transaction not found — it may need more confirmations',
422,
'tx_not_found',
);
}
if (tx.meta?.err) throw depositError('transaction failed on-chain', 422, 'tx_failed');
// Bind the deposit to the authenticated user: a signer must be one of their
// linked Solana wallets.
const linked = await linkedSolanaWallets(user);
const matched = [...signerSet(tx)].find((s) => linked.has(s));
if (!matched) {
throw depositError(
'this transfer was not signed by a wallet linked to your account — sign in with the sending wallet, or link it, then retry',
403,
'wallet_not_linked',
);
}
let usd;
let assetAmount;
let priceUsd;
let amount; // human units, for display
if (assetU === 'SOL') {
const lamports = lamportsCreditedTo(tx, sink);
if (lamports <= 0n) {
throw depositError(
'no SOL was received at the deposit wallet in this transaction',
422,
'no_funds_received',
);
}
priceUsd = await solanaMintUsdPrice(SOL_MINT);
if (!(priceUsd > 0))
throw depositError(
'live SOL price unavailable — try again shortly',
503,
'price_unavailable',
);
assetAmount = lamports;
amount = Number(lamports) / LAMPORTS_PER_SOL;
usd = amount * priceUsd;
} else if (assetU === 'USDC') {
// USDC is credited at the published fixed rate (pricing/catalog.js), never
// a quote: credits are USD-denominated and 1 USDC is $1.00 of credits.
const atomics = tokenCreditedTo(tx, { mint: USDC_MINT_BY_NETWORK[network], owner: sink });
if (atomics <= 0n) {
throw depositError(
'no USDC was received at the deposit wallet in this transaction',
422,
'no_funds_received',
);
}
priceUsd = USDC_CREDIT_RATE;
assetAmount = atomics;
amount = Number(atomics) / 10 ** USDC_DECIMALS;
usd = amount * priceUsd;
} else {
const atomics = tokenCreditedTo(tx, { mint: TOKEN_MINT, owner: sink });
if (atomics <= 0n) {
throw depositError(
'no $THREE was received at the deposit wallet in this transaction',
422,
'no_funds_received',
);
}
const p = await getTokenPriceUsd();
priceUsd = p.priceUsd;
assetAmount = atomics;
amount = Number(atomics) / 10 ** TOKEN_DECIMALS;
usd = amount * priceUsd;
}
usd = Math.round(usd * 1e6) / 1e6;
if (!(usd > 0))
throw depositError(
'deposit amount rounds to zero at the current price',
422,
'amount_too_small',
);
// Idempotency is per (signature, asset): one transaction can carry both SOL
// and $THREE to the deposit wallet, and each asset is credited once. Legacy
// deposits were keyed on the signature alone (`deposit:<sig>`), so if such a
// row already exists we reuse that key — re-verifying an old deposit resolves
// to a replay instead of double-crediting under the new per-asset key.
const legacyKey = `deposit:${txSignature}`;
const [priorLegacy] = await sql`
select 1 from credit_ledger where idempotency_key = ${legacyKey} limit 1
`;
const idempotencyKey = priorLegacy ? legacyKey : `deposit:${assetU}:${txSignature}`;
const res = await creditAccount({
userId: user.id,
amountUsd: usd,
kind: 'deposit',
refType: `deposit_${assetU.toLowerCase()}`,
refId: txSignature,
txSignature,
asset: assetU,
assetAmount,
priceUsd,
idempotencyKey,
meta: { slot: tx.slot ?? null, signer: matched, amount, network },
});
// Paying in $THREE earns the owner-configured bonus as a separate `grant`
// row on the same ledger, keyed on the deposit so a re-verify replays it
// instead of granting twice. The bonus is read at credit time, so a policy
// change applies to the next deposit and never rewrites an old one.
const bonusBps = assetU === 'THREE' ? creditBonusBps() : 0;
let bonusUsd = 0;
let balanceUsd = res.balanceUsd;
if (bonusBps > 0) {
bonusUsd = Math.round(usd * bonusBps) / 10_000;
bonusUsd = Math.round(bonusUsd * 1e6) / 1e6;
if (bonusUsd > 0) {
const bonus = await creditAccount({
userId: user.id,
amountUsd: bonusUsd,
kind: 'grant',
action: 'deposit.three_bonus',
refType: 'deposit_three_bonus',
refId: txSignature,
txSignature,
asset: assetU,
assetAmount: 0n,
priceUsd,
idempotencyKey: `${idempotencyKey}:bonus`,
meta: { bonus_bps: bonusBps, base_usd: usd, network },
});
balanceUsd = bonus.balanceUsd;
if (bonus.replay) bonusUsd = 0;
}
}
return {
ok: true,
replay: res.replay,
balance_usd: balanceUsd,
credited_usd: res.replay ? 0 : usd,
bonus_usd: res.replay ? 0 : bonusUsd,
bonus_bps: bonusBps,
usd,
asset: assetU,
amount,
price_usd: priceUsd,
tx_signature: txSignature,
};
}