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
#!/usr/bin/env node
// scripts/x402-ring-coverage-sweep.js
//
// Proves that EVERY paid x402 endpoint in api/_lib/x402/ring-catalog.js actually
// settles when paid — not just that it 402s. For each catalog entry it:
// 1. probes the endpoint (no payment) and records the 402 challenge + that a
// Solana USDC accept is advertised at the expected price;
// 2. pays it once via payX402 (real 402 → signed Solana USDC transfer → replay
// with X-PAYMENT), recording the facilitator settle signature;
// 3. confirms the 200 business response carries a real (non-error) payload;
// 4. for the load-bearing tips/commerce endpoints, asserts the real business
// effect landed (tip row written, cover charged, billboard placed, sale
// recorded) — not just the payment log.
//
// It then writes tasks/x402-ring/COVERAGE.md (the human table) and
// tasks/x402-ring/coverage-report.json (the machine record).
//
// Real payments only — no mocks. Requires an env-complete, funded context:
// X402_SEED_SOLANA_SECRET_BASE58 (or X402_AGENT_…) funded with USDC + SOL,
// X402_SELF_FACILITATOR_ENABLED=true, the ring env from tasks 02–03, and (for
// the business-effect assertions) DATABASE_URL / Redis. Without a payer it
// exits cleanly with a "no payer configured" report rather than faking data.
//
// Usage:
// node scripts/x402-ring-coverage-sweep.js # autobuy set only
// node scripts/x402-ring-coverage-sweep.js --manual # + autobuy:false
// node scripts/x402-ring-coverage-sweep.js --only=dance-tip,club-cover
// node scripts/x402-ring-coverage-sweep.js --max-usd=0.50 # total spend cap
// node scripts/x402-ring-coverage-sweep.js --origin=http://localhost:3000
//
// The autobuy sweep at default prices costs ≈ $0.30. --manual entries mint real
// artifacts (pump-launch deploys a coin; cosmetic-purchase can pay a creator) —
// only run --manual on devnet or with explicit owner sign-off.
import { mkdirSync, writeFileSync } from 'node:fs';
import { fileURLToPath } from 'node:url';
import { dirname, join } from 'node:path';
import { RING_CATALOG } from '../api/_lib/x402/ring-catalog.js';
import { payX402, bootstrapSolanaContext, fetchWithTimeout, parseSolanaAccept } from '../api/_lib/x402/pay.js';
const HERE = dirname(fileURLToPath(import.meta.url));
const OUT_DIR = join(HERE, '..', 'tasks', 'x402-ring');
// ── args ──────────────────────────────────────────────────────────────────────
const argv = process.argv.slice(2);
const flag = (name) => argv.includes(`--${name}`);
const opt = (name, dflt) => {
const hit = argv.find((a) => a.startsWith(`--${name}=`));
return hit ? hit.slice(name.length + 3) : dflt;
};
const INCLUDE_MANUAL = flag('manual');
const ONLY = (opt('only', '') || '').split(',').map((s) => s.trim()).filter(Boolean);
const MAX_USD = Number(opt('max-usd', INCLUDE_MANUAL ? '2' : '0.5'));
const ORIGIN = (opt('origin', process.env.APP_ORIGIN || 'https://three.ws')).replace(/\/$/, '');
// ── business-effect verifiers ───────────────────────────────────────────────
// Each returns { checked:boolean, ok:boolean, note:string }. They run a cheap
// before/after probe around the paid call so the sweep proves the real effect
// landed, not just the payment. Missing DB/Redis → { checked:false }.
async function loadSql() {
try {
const { sql } = await import('../api/_lib/db.js');
// A trivial probe confirms the connection is live.
await sql`SELECT 1`;
return sql;
} catch { return null; }
}
async function loadRedis() {
try {
const { getRedis } = await import('../api/_lib/redis.js');
const r = getRedis();
if (r) await r.ping();
return r;
} catch { return null; }
}
const EFFECT = {
async 'dance-tip'({ sql }) {
if (!sql) return { checked: false };
const before = Number((await sql`SELECT count(*)::int AS n FROM club_tips`)[0]?.n || 0);
return {
async after() {
const now = Number((await sql`SELECT count(*)::int AS n FROM club_tips`)[0]?.n || 0);
return { checked: true, ok: now > before, note: `club_tips ${before}→${now} (tip recorded)` };
},
};
},
async 'club-cover'({ sql }) {
if (!sql) return { checked: false };
const q = () => sql`
SELECT count(*)::int AS n FROM x402_audit_log
WHERE route = '/api/x402/club-cover' AND settlement_status = 'success'`;
const before = Number((await q())[0]?.n || 0);
return {
async after() {
const now = Number((await q())[0]?.n || 0);
return { checked: true, ok: now > before, note: `settled cover charges ${before}→${now}` };
},
};
},
async billboard({ redis }) {
if (!redis) return { checked: false };
const { RING_CANARY_MINT } = await import('../api/_lib/x402/ring-catalog.js');
return {
async after() {
const placement = await redis.get(`billboard:${RING_CANARY_MINT}`);
return { checked: true, ok: !!placement, note: placement ? 'billboard placement written to Redis' : 'no placement key found' };
},
};
},
async 'cosmetic-purchase'({ sql }) {
if (!sql) return { checked: false };
const before = Number((await sql`SELECT count(*)::int AS n FROM cosmetic_sales`.catch(() => [{ n: 0 }]))[0]?.n || 0);
return {
async after() {
const now = Number((await sql`SELECT count(*)::int AS n FROM cosmetic_sales`.catch(() => [{ n: before }]))[0]?.n || 0);
return { checked: true, ok: now > before, note: `cosmetic_sales ${before}→${now} (sale recorded)` };
},
};
},
};
// ── sweep ─────────────────────────────────────────────────────────────────────
async function main() {
let entries = RING_CATALOG.filter((e) => (INCLUDE_MANUAL ? true : e.autobuy));
if (ONLY.length) entries = entries.filter((e) => ONLY.includes(e.slug));
let ctx;
try {
ctx = await bootstrapSolanaContext();
} catch (err) {
const report = { generatedAt: new Date().toISOString(), origin: ORIGIN, error: `no_payer: ${err.message}`, rows: [] };
writeReport(report);
console.error(`[sweep] no payer configured — wrote a stub report. ${err.message}`);
process.exit(1);
}
const sql = await loadSql();
const redis = await loadRedis();
const rows = [];
let spentAtomic = 0;
for (const e of entries) {
const qs = e.query ? `?${new URLSearchParams(e.query).toString()}` : '';
const url = `${ORIGIN}${e.path}${qs}`;
const body = e.method === 'POST' ? e.body() : null;
const capRemaining = Math.max(0, Math.round(MAX_USD * 1e6) - spentAtomic);
// 1. Probe the 402 challenge (no payment).
let challenge402 = false;
let advertisedAtomic = null;
let solanaAccept = false;
try {
const probe = await fetchWithTimeout(url, {
method: e.method,
headers: { 'content-type': 'application/json' },
...(body != null ? { body: JSON.stringify(body) } : {}),
});
challenge402 = probe.status === 402;
if (challenge402) {
const acc = parseSolanaAccept(probe.body);
solanaAccept = !!acc;
advertisedAtomic = acc ? Number(acc.amount) : null;
}
} catch { /* recorded as challenge402=false below */ }
// 2. Prep the business-effect before-probe.
let effect = { checked: false };
try {
const mk = EFFECT[e.slug];
if (mk) effect = await mk({ sql, redis });
} catch { /* effect stays unchecked */ }
// 3. Pay it (unless it would exceed the spend cap).
let result;
if (advertisedAtomic != null && advertisedAtomic > capRemaining) {
result = { success: false, paid: false, skipped: true, amountAtomic: advertisedAtomic, txSig: null, status: 402, responseBody: null, errorMsg: 'spend_cap_reached' };
} else {
try {
result = await payX402({ url, method: e.method, body, ...ctx, remainingCap: capRemaining });
} catch (err) {
result = { success: false, paid: false, amountAtomic: 0, txSig: null, status: 0, responseBody: null, errorMsg: err.message };
}
}
if (result.paid) spentAtomic += result.amountAtomic || 0;
// 4. Business-effect after-probe.
let effectResult = { checked: false, ok: null, note: '' };
if (effect.after && result.paid) {
try { effectResult = await effect.after(); } catch (err) { effectResult = { checked: true, ok: false, note: `effect check failed: ${err.message}` }; }
}
const liveness = summarize(result.responseBody);
rows.push({
slug: e.slug,
path: e.path,
method: e.method,
autobuy: e.autobuy,
priceAtomic: advertisedAtomic ?? e.priceAtomicDefault,
challenge402,
solanaAccept,
settleSignature: result.txSig || null,
responseOk: result.success && liveness.ok,
status: result.status,
error: result.errorMsg || null,
effect: effectResult,
businessEffect: e.businessEffect,
note: e.note || '',
});
const mark = result.paid ? '✓' : (result.skipped ? '·' : '✗');
console.log(`${mark} ${e.slug.padEnd(28)} settle=${result.txSig ? result.txSig.slice(0, 12) + '…' : '—'} ${result.errorMsg || ''}`);
}
const report = { generatedAt: new Date().toISOString(), origin: ORIGIN, includeManual: INCLUDE_MANUAL, spentUsd: (spentAtomic / 1e6).toFixed(4), rows };
writeReport(report);
const settled = rows.filter((r) => r.settleSignature).length;
console.log(`\n[sweep] ${settled}/${rows.length} settled, spent $${report.spentUsd}. Wrote COVERAGE.md + coverage-report.json`);
}
function summarize(body) {
if (body == null) return { ok: false };
if (typeof body === 'string') return { ok: body.length > 0 };
if (Array.isArray(body)) return { ok: body.length > 0 };
if (typeof body === 'object') return { ok: Object.keys(body).length > 0 && !body.error };
return { ok: true };
}
function writeReport(report) {
mkdirSync(OUT_DIR, { recursive: true });
writeFileSync(join(OUT_DIR, 'coverage-report.json'), JSON.stringify(report, null, '\t') + '\n');
writeFileSync(join(OUT_DIR, 'COVERAGE.md'), renderMarkdown(report));
}
function renderMarkdown(report) {
const usd = (a) => (a == null ? '—' : `$${(a / 1e6).toFixed(a >= 1e6 ? 2 : 3)}`);
const yn = (b) => (b === true ? '✅' : b === false ? '❌' : '—');
const lines = [];
lines.push('# x402 Ring — Endpoint Coverage');
lines.push('');
lines.push(`Generated ${report.generatedAt} against \`${report.origin}\`` + (report.includeManual ? ' (including --manual autobuy:false entries)' : '') + '.');
lines.push('');
if (report.error) {
lines.push(`> **No live sweep run:** \`${report.error}\`. Run this script from an env-complete, funded context (see the header of \`scripts/x402-ring-coverage-sweep.js\`).`);
lines.push('');
} else {
lines.push(`Total verification spend: **$${report.spentUsd}**. A ✓ settle signature is a real on-chain USDC payment settled by the self-hosted facilitator.`);
lines.push('');
}
lines.push('| Slug | Price | 402 | Sol accept | Settle signature | Response OK | Business effect verified |');
lines.push('|------|------:|:---:|:----------:|------------------|:-----------:|--------------------------|');
for (const r of report.rows || []) {
const effect = r.effect?.checked ? `${yn(r.effect.ok)} ${r.effect.note}` : (r.autobuy ? '—' : '(manual)');
const sig = r.settleSignature ? `\`${r.settleSignature}\`` : (r.error ? `❌ ${r.error}` : '—');
lines.push(`| \`${r.slug}\` | ${usd(r.priceAtomic)} | ${yn(r.challenge402)} | ${yn(r.solanaAccept)} | ${sig} | ${yn(r.responseOk)} | ${effect} |`);
}
lines.push('');
lines.push('## autobuy:false — justifications');
lines.push('');
for (const r of (report.rows || []).filter((x) => !x.autobuy)) {
lines.push(`- **\`${r.slug}\`** — ${r.note || r.businessEffect}`);
}
lines.push('');
return lines.join('\n');
}
main().catch((err) => {
console.error('[sweep] fatal', err);
process.exit(1);
});