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
// api/_lib/x402/pipelines/builder-code-attribution.js
//
// Builder Code Attribution Tracker — autonomous pipeline (self / Finance).
//
// Coinbase builder rewards (and x402scan analytics) credit on-chain x402
// volume to the app that exposed the paid endpoint via the ERC-8021 Schema 2
// `builder-code` extension. For three.ws that app code is
// `three_d_agent` (env X402_BUILDER_CODE_APP). The credit only happens when:
//
// 1. the paid endpoint DECLARES the builder-code extension on its 402
// challenge (extensions["builder-code"].info.a = "three_d_agent"), AND
// 2. the buyer ECHOES that app code in its X-PAYMENT payload, so the
// facilitator suffixes the settlement-tx calldata with the attribution
// CBOR map at settle time.
//
// If a single priced endpoint silently drops the declaration (a route that
// bypasses build402Body, an env regression that unsets X402_BUILDER_CODE_APP,
// or a deploy that forgets the extension), every USDC dollar that endpoint
// settles is UNATTRIBUTED — real revenue that earns three.ws zero builder
// rewards. Nothing surfaces that gap today.
//
// This tracker is the watchdog. Every 6h the autonomous loop calls run(ctx):
//
// • ATTRIBUTION SWEEP (free) — probes a representative set of priced
// /api/x402/* endpoints for their live 402 challenge and verifies each one
// declares the builder-code extension with a === three_d_agent. Any 402
// endpoint missing/mismatched is an attribution gap → alert.
//
// • SETTLEMENT PROOF (one real $0.001 payment) — pays the cheapest declaring
// endpoint (dance-tip) with the builder-code echo ATTACHED to the X-PAYMENT
// envelope (a=three_d_agent, w=<wallet code>, s=[builder_code_attribution]),
// then reads the X-PAYMENT-RESPONSE header. The resource server enforces the
// echo (it rejects a non-echoing payment with `builder_code_tampered`, 402),
// so a 200 + settled tx signature is end-to-end proof that an ATTRIBUTED
// payment settles on-chain — the tx Coinbase's reward indexer reads. The
// header's settlement object (transaction/network/payer, plus any
// extensions the route echoes back) is captured for audit.
//
// Value sink: builder_code_attribution (one upserted row per endpoint, keyed by
// endpoint). Columns carry the per-endpoint declaration verdict + the live
// settlement proof. See ensureSchema() below for the full shape.
//
// Downstream consumer: api/ops/health.js → loadBuilderAttribution() folds an
// attribution gap (a priced endpoint that stopped declaring three_d_agent, or
// a failed attributed settlement) into the platform health verdict so on-call
// sees lost-rewards risk before a billing cycle closes.
//
// The loop owns cooldown, daily-spend accounting and the single summary row in
// x402_autonomous_log (value_extracted = the attribution summary). This module
// owns the probes, the attributed payment, the per-endpoint persistence and the
// gap detection. No mocks — every probe reads a live challenge and the proof is
// a real on-chain USDC payment.
import { randomUUID } from 'node:crypto';
import { PublicKey } from '@solana/web3.js';
import {
getAssociatedTokenAddressSync,
TOKEN_PROGRAM_ID, ASSOCIATED_TOKEN_PROGRAM_ID,
} from '@solana/spl-token';
import { sql as defaultSql } from '../../db.js';
import { env } from '../../env.js';
import { logger } from '../../usage.js';
import { BUILDER_CODE, isValidBuilderCode } from '../../x402-builder-code.js';
import {
fetchWithTimeout,
parseSolanaAccept,
buildPaymentTx,
bootstrapSolanaContext,
admitSponsorSettle,
nextAutoNonce,
currentBlockhash,
USDC_MINT,
} from '../pay.js';
const log = logger('x402-builder-code-attribution');
const USER_AGENT = 'threews-x402-builder-attribution/1.0';
// The service code this tracker self-attributes with on its settlement echo.
const SERVICE_CODE = 'builder_code_attribution';
// Redis flag a consumer can read in one GET to learn an attribution gap is open.
const REDIS_ALERT_KEY = 'x402:builder-attribution:alert';
const ALERT_TTL_SECONDS = 7 * 60 * 60; // a little over the 6h cadence
// Representative set of priced /api/x402/* endpoints. Every one of these flows
// through paidEndpoint → build402Body, which auto-declares the builder-code
// extension when X402_BUILDER_CODE_APP is set — so each is expected to advertise
// `a = three_d_agent` on its 402 challenge. `settle: true` marks the single
// endpoint we actually pay (the cheapest, $0.001 dance-tip) to prove the
// attributed settlement path end-to-end; the rest are probe-only (free).
const SWEEP_ENDPOINTS = [
{
// dance-tip is GET (query params); booking one $0.001 dance is the same
// benign side effect the volume entries already produce, so it's our paid
// settlement proof. The probe (free 402) books nothing; the ticket is
// created only after payment settles.
path: '/api/x402/dance-tip?dancer=4&dance=hiphop',
method: 'GET',
body: null,
settle: true,
},
{
// model-check keys on a query param; a stable public rig keeps the probe
// deterministic. The probe never pays, so it books nothing.
path: `/api/x402/model-check?url=${encodeURIComponent('https://three.ws/avatars/xbot.glb')}`,
method: 'GET',
body: null,
},
{ path: '/api/x402/crypto-intel', method: 'POST', body: { topic: 'solana' } },
{
// token-intel is GET (?mint=…). Canary: the well-known USDC mint.
path: '/api/x402/token-intel?mint=EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v&network=mainnet',
method: 'GET',
body: null,
},
{ path: '/api/x402/fact-check', method: 'POST', body: { claim: 'The sky is blue' } },
{
// symbol-availability is GET (?ticker=…&network=…).
path: '/api/x402/symbol-availability?ticker=HEALTH&network=mainnet',
method: 'GET',
body: null,
},
];
// One-time DDL guard per warm instance (mirrors the loop's ensureSchema idiom).
let _schemaReady = false;
async function ensureSchema(sql) {
if (_schemaReady) return;
await sql`
CREATE TABLE IF NOT EXISTS builder_code_attribution (
endpoint text PRIMARY KEY,
method text,
challenged boolean NOT NULL DEFAULT false, -- returned a real 402
attributed boolean NOT NULL DEFAULT false, -- declared builder-code on the challenge
declared_code text, -- the app code (a) advertised
expected_code text, -- X402_BUILDER_CODE_APP in force
matches boolean NOT NULL DEFAULT false, -- declared_code === expected_code
price_atomic bigint, -- challenge amount (atomics)
gap boolean NOT NULL DEFAULT false, -- 402 endpoint with missing/mismatched attribution
settled boolean NOT NULL DEFAULT false, -- this endpoint carried the live settlement proof
echo_accepted boolean NOT NULL DEFAULT false, -- attributed payment settled (server enforces echo)
response_attributed boolean NOT NULL DEFAULT false, -- X-PAYMENT-RESPONSE echoed a builder-code block
tx_signature text,
payer text,
error text,
run_id uuid,
checked_at timestamptz DEFAULT now()
)
`;
await sql`CREATE INDEX IF NOT EXISTS builder_code_attribution_gap_idx ON builder_code_attribution (gap) WHERE gap = true`;
_schemaReady = true;
}
async function upsertRow(sql, runId, row) {
await sql`
INSERT INTO builder_code_attribution
(endpoint, method, challenged, attributed, declared_code, expected_code,
matches, price_atomic, gap, settled, echo_accepted, response_attributed,
tx_signature, payer, error, run_id, checked_at)
VALUES
(${row.endpoint}, ${row.method}, ${row.challenged}, ${row.attributed},
${row.declared_code || null}, ${row.expected_code || null},
${row.matches}, ${row.price_atomic ?? null}, ${row.gap}, ${row.settled},
${row.echo_accepted}, ${row.response_attributed},
${row.tx_signature || null}, ${row.payer || null}, ${row.error || null},
${runId}, now())
ON CONFLICT (endpoint) DO UPDATE SET
method = EXCLUDED.method,
challenged = EXCLUDED.challenged,
attributed = EXCLUDED.attributed,
declared_code = EXCLUDED.declared_code,
expected_code = EXCLUDED.expected_code,
matches = EXCLUDED.matches,
price_atomic = EXCLUDED.price_atomic,
gap = EXCLUDED.gap,
settled = EXCLUDED.settled,
echo_accepted = EXCLUDED.echo_accepted,
response_attributed = EXCLUDED.response_attributed,
tx_signature = EXCLUDED.tx_signature,
payer = EXCLUDED.payer,
error = EXCLUDED.error,
run_id = EXCLUDED.run_id,
checked_at = now()
`;
}
async function persistRows(sql, log, runId, rows) {
try {
await ensureSchema(sql);
for (const row of rows) await upsertRow(sql, runId, row);
} catch (err) {
log?.warn?.('builder_attribution_persist_failed', { message: err?.message });
}
}
// Pull the declared app builder code off a live 402 challenge body.
function declaredAppCode(challenge) {
const a = challenge?.extensions?.[BUILDER_CODE]?.info?.a;
return typeof a === 'string' ? a : null;
}
// Probe one endpoint for its 402 challenge and classify the attribution verdict.
// Free read — never pays. A non-402 response means the endpoint isn't priced
// (no rewards to attribute), recorded as not-a-gap.
async function probeEndpoint(origin, expectedCode, ep) {
const endpointUrl = `${origin}${ep.path}`;
const base = {
endpoint: ep.path,
method: ep.method,
challenged: false,
attributed: false,
declared_code: null,
expected_code: expectedCode,
matches: false,
price_atomic: null,
gap: false,
settled: false,
echo_accepted: false,
response_attributed: false,
tx_signature: null,
payer: null,
error: null,
_settle: !!ep.settle,
_endpointUrl: endpointUrl,
_body: ep.body,
};
try {
const res = await fetchWithTimeout(endpointUrl, {
method: ep.method,
headers: { 'content-type': 'application/json', 'user-agent': USER_AGENT },
...(ep.body != null ? { body: JSON.stringify(ep.body) } : {}),
});
if (res.status !== 402) {
// Not a priced challenge this call — nothing to attribute, not a gap.
base.error = `not_402:http_${res.status}`;
return base;
}
base.challenged = true;
base.challenge = res.body;
const accept = parseSolanaAccept(res.body);
if (accept?.amount != null) base.price_atomic = Number(accept.amount);
base.accept = accept;
const code = declaredAppCode(res.body);
base.declared_code = code;
base.attributed = !!code;
base.matches = !!code && code === expectedCode;
// A priced (402) endpoint that fails to declare the expected app code can
// never be credited — that is the attribution gap we alert on.
base.gap = !base.matches;
if (!base.attributed) base.error = 'builder_code_not_declared';
else if (!base.matches) base.error = `builder_code_mismatch:${code}`;
return base;
} catch (err) {
base.error = `probe_failed:${err?.message || 'network'}`;
return base;
}
}
// Settle ONE real attributed payment against the dance-tip challenge captured in
// the probe. Builds the SPL transfer, attaches the builder-code echo to the
// X-PAYMENT envelope, replays the request, and reads the X-PAYMENT-RESPONSE
// settlement. Returns the settlement outcome — never throws for protocol faults.
async function settleAttributed({ row, buyer, conn, blockhash, mintInfo, remainingCap, expectedCode }) {
const accept = row.accept;
const out = { amountAtomic: 0, txSig: null, payer: null, echoAccepted: false, responseAttributed: false, settleResp: null, error: null };
if (!accept) { out.error = 'no_solana_accept'; return out; }
if (!USDC_MINT || accept.asset !== USDC_MINT) { out.error = `unexpected_asset:${accept.asset}`; return out; }
if (!accept.extra?.feePayer) { out.error = 'missing_fee_payer'; return out; }
const amountAtomic = Number(accept.amount || 0);
if (amountAtomic > (remainingCap ?? Infinity)) { out.error = 'cap_would_exceed'; return out; }
// The loop hands every pipeline the tick's shared blockhash: a random nonce
// keeps this payment's signature distinct from any other same-amount payment
// to the same payTo in the tick (see x402-autonomous-loop.js).
const payNonce = nextAutoNonce();
const admission = await admitSponsorSettle({ accept, connection: conn, nonce: payNonce });
if (!admission.ok) { out.error = admission.reason || 'fee_runway_exhausted'; return out; }
// Echo the declared app code (anti-tamper: the server rejects a mismatch) and
// self-attribute the wallet + service so the settlement CBOR records who
// exposed the endpoint (a), who paid (w), and which service ran (s).
const declaredA = declaredAppCode(row.challenge) || expectedCode;
const echo = { a: declaredA };
const walletCode = env.X402_BUILDER_CODE_WALLET;
if (isValidBuilderCode(walletCode)) echo.w = walletCode;
echo.s = [SERVICE_CODE];
try {
const receiverAta = getAssociatedTokenAddressSync(
new PublicKey(accept.asset), new PublicKey(accept.payTo),
false, TOKEN_PROGRAM_ID, ASSOCIATED_TOKEN_PROGRAM_ID,
);
const receiverAtaInfo = await conn.getAccountInfo(receiverAta).catch(() => null);
// Sign against a fresh blockhash: this runs inside a loop tick that can be
// minutes old, and the tick's own hash expires after about 60 seconds.
const signBlockhash = await currentBlockhash(conn, blockhash);
const txBase64 = buildPaymentTx({
accept, buyer, blockhash: signBlockhash, mintInfo,
receiverAtaExists: receiverAtaInfo !== null,
nonce: payNonce,
});
const xPayment = Buffer.from(JSON.stringify({
x402Version: 2,
scheme: 'exact',
network: accept.network,
resource: { url: row._endpointUrl, mimeType: 'application/json' },
payload: { transaction: txBase64 },
accepted: accept,
extensions: { [BUILDER_CODE]: echo },
})).toString('base64');
const paidRes = await fetchWithTimeout(row._endpointUrl, {
method: row.method,
headers: {
'content-type': 'application/json',
'user-agent': USER_AGENT,
'x-payment': xPayment,
},
...(row._body != null ? { body: JSON.stringify(row._body) } : {}),
});
if (!paidRes.ok) {
// A 402 here with builder_code_tampered would mean the echo was rejected —
// captured verbatim so the verdict reflects exactly why attribution failed.
const reason = paidRes.body?.error || paidRes.body?.code || `http_${paidRes.status}`;
out.error = typeof reason === 'string' ? reason : `http_${paidRes.status}`;
return out;
}
// 200 + accepted echo = the attributed payment settled. Read the receipt.
out.echoAccepted = true;
out.amountAtomic = amountAtomic;
const header = paidRes.headers?.get?.('x-payment-response');
if (header) {
try {
const settled = JSON.parse(Buffer.from(header, 'base64').toString('utf8'));
out.settleResp = settled;
out.txSig = settled?.transaction || null;
out.payer = settled?.payer || null;
out.responseAttributed = !!settled?.extensions?.[BUILDER_CODE];
} catch { /* header malformed — settlement still happened */ }
}
return out;
} catch (err) {
out.error = `settle_threw:${err?.message || 'unknown'}`;
return out;
}
}
/**
* Builder Code Attribution Tracker executor (run()-style registry contract).
*
* @param {object} ctx — supplied by the autonomous loop:
* { origin, buyer, conn, blockhash, mintInfo, remainingCap, redis, sql, log, runId }.
* All optional for standalone/manual runs (Solana context is bootstrapped on demand).
* @returns the aggregate outcome the loop records to x402_autonomous_log:
* { success, amountAtomic, txSig, responseData, signalData, valueExtracted, errorMsg, note }
*/
export async function run(ctx = {}) {
const runId = ctx.runId || randomUUID();
const origin = ctx.origin || env.APP_ORIGIN || 'https://three.ws';
const sql = ctx.sql || defaultSql;
const redis = ctx.redis || null;
const expectedCode = env.X402_BUILDER_CODE_APP || null;
// Attribution is disabled platform-wide when no app code is configured — there
// is nothing to track and no rewards to earn. Record the state, spend nothing.
if (!expectedCode) {
log.info('builder_attribution_disabled', { run_id: runId });
return {
success: false,
amountAtomic: 0,
txSig: null,
skipped: true,
signalData: { enabled: false },
errorMsg: 'builder_code_app_unset',
note: 'X402_BUILDER_CODE_APP unset — attribution disabled',
};
}
// ── Phase 1: attribution sweep (free probes) ──────────────────────────────
const rows = await Promise.all(SWEEP_ENDPOINTS.map((ep) => probeEndpoint(origin, expectedCode, ep)));
// ── Phase 2: settlement proof (one real attributed payment) ───────────────
// Pay the cheapest declaring endpoint to prove an attributed settlement lands
// on-chain. Skip the payment if that endpoint never declared attribution (the
// gap is already recorded) or the wallet isn't configured.
const settleRow = rows.find((r) => r._settle && r.challenged && r.matches);
let amountAtomic = 0;
let txSig = null;
let settleResp = null;
// settleExecuted = we actually had a wallet and ran the attributed payment.
// Distinguishes "couldn't run the proof (no wallet)" from "proof failed".
let settleExecuted = false;
if (settleRow) {
let solana = null;
if (ctx.buyer && ctx.conn && ctx.blockhash && ctx.mintInfo) {
solana = { buyer: ctx.buyer, conn: ctx.conn, blockhash: ctx.blockhash, mintInfo: ctx.mintInfo };
} else {
// Standalone/manual run — bootstrap our own Solana context. A missing
// keypair degrades gracefully (recorded, no spend).
try {
solana = await bootstrapSolanaContext({ buyer: ctx.buyer });
} catch (err) {
settleRow.error = `wallet_unconfigured:${err?.message || 'no_keypair'}`;
}
}
if (solana) {
settleExecuted = true;
const r = await settleAttributed({
row: settleRow,
buyer: solana.buyer,
conn: solana.conn,
blockhash: solana.blockhash,
mintInfo: solana.mintInfo,
remainingCap: ctx.remainingCap,
expectedCode,
});
settleRow.settled = r.echoAccepted;
settleRow.echo_accepted = r.echoAccepted;
settleRow.response_attributed = r.responseAttributed;
settleRow.tx_signature = r.txSig;
settleRow.payer = r.payer;
if (r.error) settleRow.error = r.error;
amountAtomic = r.amountAtomic;
txSig = r.txSig;
settleResp = r.settleResp;
}
}
// ── Persist per-endpoint verdicts (the value sink) ────────────────────────
await persistRows(sql, log, runId, rows.map(stripScratch));
// ── Derive the summary + alert state ──────────────────────────────────────
const challenged = rows.filter((r) => r.challenged);
const gaps = challenged.filter((r) => r.gap);
const attributionOk = gaps.length === 0;
// The settlement proof is meaningful only when we actually ran it (had a
// declaring endpoint AND a wallet). A run that couldn't even attempt the proof
// (no wallet, no declaring endpoint to pay) isn't a failure — only an executed
// proof that came back echo_accepted=false is an attributed-settle FAILURE.
const settleAttempted = !!settleRow;
const settleProven = !!(settleRow && settleRow.echo_accepted);
const proofOk = !settleExecuted || settleProven;
await writeAlert(redis, attributionOk && proofOk ? null : {
run_id: runId,
gaps: gaps.map((g) => ({ endpoint: g.endpoint, error: g.error })),
settle_proven: settleProven,
ts: new Date().toISOString(),
});
const signalData = {
expected_code: expectedCode,
endpoints_probed: rows.length,
endpoints_challenged: challenged.length,
attributed: challenged.filter((r) => r.matches).length,
gaps: gaps.length,
gap_endpoints: gaps.map((g) => g.endpoint),
attribution_ok: attributionOk,
settle_attempted: settleAttempted,
settle_proven: settleProven,
settle_tx: txSig,
response_attributed: !!(settleRow && settleRow.response_attributed),
};
if (!attributionOk) {
log.warn('builder_attribution_gap', { run_id: runId, gaps: signalData.gap_endpoints, expected: expectedCode });
} else if (!proofOk) {
log.warn('builder_attribution_settle_failed', { run_id: runId, endpoint: settleRow?.endpoint, error: settleRow?.error });
} else {
log.info('builder_attribution_ok', { run_id: runId, attributed: signalData.attributed, settle_tx: txSig });
}
const note = attributionOk
? `${signalData.attributed}/${challenged.length} attributed${settleProven ? `, settle ${txSig ? 'proven' : 'ok'}` : settleExecuted ? ', SETTLE_FAILED' : ''}`
: `ATTRIBUTION_GAP ${gaps.length}: ${signalData.gap_endpoints.join(',')}`;
return {
// success = no attribution gap AND (if attempted) the attributed payment
// settled. amountAtomic reflects only what actually moved on-chain so the
// loop's daily-spend accounting is exact.
success: attributionOk && proofOk,
amountAtomic,
txSig,
responseData: {
expected_code: expectedCode,
endpoints: rows.map((r) => ({
endpoint: r.endpoint, challenged: r.challenged, matches: r.matches,
gap: r.gap, declared_code: r.declared_code, error: r.error,
})),
settlement: settleResp,
},
signalData,
valueExtracted: {
attribution_ok: attributionOk,
gaps: signalData.gap_endpoints,
settle_proven: settleProven,
settle_tx: txSig,
},
errorMsg: attributionOk ? (proofOk ? null : `attributed_settle_failed:${settleRow?.error || 'unknown'}`) : `attribution_gap:${signalData.gap_endpoints.join(',')}`,
note,
};
}
// Drop the transient scratch fields (challenge body, accept, urls) before the row
// reaches the persistence layer — they're working state, not columns.
function stripScratch(r) {
const { challenge, accept, _settle, _endpointUrl, _body, ...row } = r;
return row;
}
async function writeAlert(redis, alert) {
if (!redis) return;
try {
if (alert) {
await redis.set(REDIS_ALERT_KEY, JSON.stringify(alert), { ex: ALERT_TTL_SECONDS });
} else {
await redis.del(REDIS_ALERT_KEY);
}
} catch (err) {
log.warn('builder_attribution_alert_write_failed', { message: err?.message });
}
}
export const BUILDER_CODE_ATTRIBUTION = Object.freeze({
endpoint: '/api/x402/*',
serviceCode: SERVICE_CODE,
redisAlertKey: REDIS_ALERT_KEY,
sweepEndpoints: SWEEP_ENDPOINTS.map((e) => e.path),
});