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
// Signed payment quotes for the $THREE token layer.
//
// The server prices a USD amount, splits it per policy, and seals the result
// into a compact HMAC-signed token: base64url(JSON(payload)) + '.' + sig.
// The client builds and sends one transaction from the quote's legs, then
// returns the quote token + tx signature on settle. Signing it means the client
// cannot tamper with the token amount, the split ratio, or the destinations
// after the server priced them — and the embedded `exp` enforces a short
// validity window so a stale price can't be exploited after the market moves.
//
// Boot guard mirrors api/_lib/holder-pass.js: production MUST set
// THREE_QUOTE_SECRET or quotes would be forgeable by anyone reading this source.
import crypto from 'node:crypto';
import { env } from '../env.js';
import { randomToken } from '../crypto.js';
import { isRpcOutageError, rpcUnavailableError } from '../rpc-degrade.js';
import {
TOKEN_MINT,
TOKEN_DECIMALS,
TOKEN_SYMBOL,
resolveSplitLegs,
applySplit,
} from './config.js';
import { quoteTokenForUsd } from './price.js';
const DEV_SECRET = 'three-ws-token-quote-dev-secret';
let _warned = false;
function secret() {
const s = env.THREE_QUOTE_SECRET;
if (s) return s;
if (process.env.NODE_ENV === 'production') {
// Typed like the treasury/rewards guards in ./config.js rather than a bare
// throw. All three are the same condition (a fund-routing var unset at
// deploy time) and a user meets them the same way, at the moment they try
// to pay. A bare Error reached wrap()'s sanitizer and rendered as
// "internal error, quote ref ...", which reads like a platform bug and
// tells an operator nothing; the typed 503 keeps the actionable code and
// the honest retry state. /api/healthz reports the same condition up front
// (three_token_rail) so it no longer takes a paying user to discover it.
const e = new Error(
'[token] THREE_QUOTE_SECRET is required in production: refusing to sign payment quotes with the dev secret.',
);
e.status = 503;
e.code = 'quote_signing_unavailable';
throw e;
}
if (!_warned) {
_warned = true;
console.warn(
'[token] THREE_QUOTE_SECRET is not set — using the insecure dev secret. ' +
'Set THREE_QUOTE_SECRET in production or payment quotes can be forged.',
);
}
return DEV_SECRET;
}
function b64url(buf) {
return Buffer.from(buf)
.toString('base64')
.replace(/=+$/, '')
.replace(/\+/g, '-')
.replace(/\//g, '_');
}
function b64urlToBuf(s) {
return Buffer.from(s.replace(/-/g, '+').replace(/_/g, '/'), 'base64');
}
function hmac(body) {
return b64url(crypto.createHmac('sha256', secret()).update(body).digest());
}
function quoteError(message, status = 422, code = 'invalid_quote') {
return Object.assign(new Error(message), { status, code });
}
/**
* Price a USD amount, split it, and return a signed quote.
* @param {{
* purpose: string, // 'spin' | 'marketplace_sale' | ...
* usd: number, // USD amount to charge
* splitPolicy: string, // a key of SPLIT_POLICIES
* sellerWallet?: string, // required when the policy has a 'seller' leg
* network?: 'mainnet'|'devnet',
* refType?: string|null, // links the payment to a spin / listing for audit
* refId?: string|null,
* }} params
*/
export async function issueQuote({
purpose,
usd,
splitPolicy,
sellerWallet = null,
network = 'mainnet',
refType = null,
refId = null,
}) {
let priced;
try {
priced = await quoteTokenForUsd(usd);
} catch (err) {
// Already-typed pricing errors (price_unavailable, amount_too_*) pass
// through untouched. A raw RPC-chain exhaustion becomes the typed
// retryable 503 so no caller ever prices a payment off a guess.
if (err?.code || !isRpcOutageError(err)) throw err;
throw rpcUnavailableError('could not price the quote: Solana RPC is temporarily unavailable', err);
}
const legs = applySplit(priced.atomics, resolveSplitLegs(splitPolicy, { sellerWallet }));
const now = Math.floor(Date.now() / 1000);
const nonce = await randomToken(16);
const payload = {
v: 1,
purpose,
network,
mint: TOKEN_MINT,
decimals: TOKEN_DECIMALS,
symbol: TOKEN_SYMBOL,
usd: priced.usd,
priceUsd: priced.priceUsd,
priceSource: priced.source,
total: priced.atomics.toString(),
// Destinations + per-leg atomics the client must satisfy on-chain.
legs: legs.map((l) => ({
role: l.role,
address: l.address,
bps: l.bps,
atomics: l.atomics.toString(),
})),
// The nonce doubles as the transaction memo, binding the on-chain tx to
// this exact quote and serving as the replay-protection key at settle.
nonce,
refType,
refId,
iat: now,
exp: now + env.THREE_QUOTE_TTL_S,
};
const body = b64url(Buffer.from(JSON.stringify(payload)));
const token = `${body}.${hmac(body)}`;
return { token, quote: payload, expiresAt: new Date(payload.exp * 1000).toISOString() };
}
/**
* Verify a quote token's signature and expiry, returning the payload.
* Throws (422 invalid_quote / 410 quote_expired) on any tamper or timeout.
*/
export function verifyQuote(token) {
if (typeof token !== 'string' || !token.includes('.'))
throw quoteError('malformed quote token');
const [body, sig] = token.split('.');
if (!body || !sig) throw quoteError('malformed quote token');
const expected = hmac(body);
const a = Buffer.from(sig);
const b = Buffer.from(expected);
if (a.length !== b.length || !crypto.timingSafeEqual(a, b))
throw quoteError('quote signature invalid');
let payload;
try {
payload = JSON.parse(b64urlToBuf(body).toString('utf8'));
} catch {
throw quoteError('quote payload unreadable');
}
const now = Math.floor(Date.now() / 1000);
if (!payload.exp || payload.exp < now) throw quoteError('quote expired', 410, 'quote_expired');
if (!payload.nonce || !Array.isArray(payload.legs) || payload.legs.length === 0) {
throw quoteError('quote missing required fields');
}
return payload;
}