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
fix(x402): let a buyer charged for a failed call retry with the same payment instead of a 409
nirholasc2e980f09f8f
diff --git a/api/_lib/x402/spent-payments.js b/api/_lib/x402/spent-payments.jsindex f74292dfa..63e04c4f6 100644--- a/api/_lib/x402/spent-payments.js+++ b/api/_lib/x402/spent-payments.js@@ -20,10 +20,14 @@// another request already honoured this proof, i.e.// a replay that raced past the lookup.//-// The claim runs LAST in the settle path on purpose. A payment that settled-// but then failed a downstream step (SIWX grant write, receipt sign) leaves no-// spent row, so the payer's retry with the same header still works. The row is-// written only for a payment that was actually honoured end to end.+// The claim runs LAST in the settle path on purpose, and a payment that+// settled but then failed a downstream step is NOT a replay: the buyer was+// charged and got nothing. Such a proof is recorded with outcome+// `failed_after_settle` plus the settlement it produced, and the same X-PAYMENT+// header may then re-run the work a bounded number of times within a window+// (claimPaidRetry) with no second verify or settle. Re-verifying would not+// work anyway: the payment already landed on chain, so the facilitator rejects+// it. Only a proof whose work was delivered (`delivered`) answers 409.//// Failure policy: FAIL OPEN, deliberately. The in-cache guard, the payment// identifier reservation and the on-chain settle-credit gate all remain in@@ -52,48 +56,83 @@ function logDegraded(op, err) {);}+/** Retries a buyer gets after a failure that happened once they were charged. */+export const PAID_RETRY_MAX = Math.max(1, Number(process.env.X402_PAID_RETRY_MAX) || 3);+/** How long those retries stay open, from the first failure. */+export const PAID_RETRY_WINDOW_SECONDS = Math.max(+ 60,+ Number(process.env.X402_PAID_RETRY_WINDOW_SECONDS) || 24 * 3600,+);+/**- * Has this payment proof already been honoured?+ * Has this payment proof already been honoured, and if it failed after the+ * buyer was charged, may it still be retried?** @param {string|null|undefined} paymentHash Hash of the signed X-PAYMENT proof.- * @returns {Promise<{ spent: boolean, unavailable: boolean }>}- * `spent` is true only on a positive, durable answer. `unavailable` marks the- * fail-open path so the caller can log it rather than silently trusting a- * "not spent" that was never actually checked.+ * @returns {Promise<{ spent: boolean, unavailable: boolean, retryable: boolean, endpoint: string|null }>}+ * `spent` is true only on a positive, durable answer. `retryable` is true when+ * the proof settled but its work failed, retries remain and the window is+ * open. `unavailable` marks the fail-open path so the caller can log it rather+ * than silently trusting a "not spent" that was never actually checked.*/export async function isPaymentSpent(paymentHash) {- if (!paymentHash) return { spent: false, unavailable: false };+ if (!paymentHash) return { spent: false, unavailable: false, retryable: false, endpoint: null };try {const rows = await sql`- SELECT 1 FROM x402_spent_payments WHERE payment_hash = ${paymentHash} LIMIT 1+ SELECT endpoint, outcome, retry_count, retry_until+ FROM x402_spent_payments WHERE payment_hash = ${paymentHash} LIMIT 1`;- return { spent: Boolean(rows?.length), unavailable: false };+ const row = rows?.[0];+ if (!row) return { spent: false, unavailable: false, retryable: false, endpoint: null };+ const retryable =+ row.outcome === 'failed_after_settle' &&+ Number(row.retry_count || 0) < PAID_RETRY_MAX &&+ (!row.retry_until || new Date(row.retry_until).getTime() > Date.now());+ return { spent: true, unavailable: false, retryable, endpoint: row.endpoint ?? null };} catch (err) {logDegraded('lookup', err);- return { spent: false, unavailable: true };+ return { spent: false, unavailable: true, retryable: false, endpoint: null };}}/*** Claim the proof as spent. Atomic: the primary key is the arbiter, so of any* set of concurrent requests carrying one X-PAYMENT header exactly one claim- * returns a row.+ * returns a row. Pass `outcome: 'failed_after_settle'` (with the settlement)+ * when the buyer was charged but the work did not complete, so the same header+ * can retry through claimPaidRetry.** @param {object} args* @param {string|null|undefined} args.paymentHash* @param {string} args.endpoint Route the proof was spent on (audit context).* @param {string|number|null} [args.amountAtomics] Price paid, in asset atomics.+ * @param {'delivered'|'failed_after_settle'} [args.outcome]+ * @param {object|null} [args.settlement] { transaction, network, payer, asset, amount, header }+ * @param {string|null} [args.lastError]* @returns {Promise<{ granted: boolean, replay: boolean, unavailable: boolean }>}*/-export async function claimSpentPayment({ paymentHash, endpoint, amountAtomics = null }) {+export async function claimSpentPayment({+ paymentHash,+ endpoint,+ amountAtomics = null,+ outcome = 'delivered',+ settlement = null,+ lastError = null,+}) {// No hash means no signed proof to key on (never produced by the paid-endpoint// path, which derives the hash before it gets here). Nothing to claim, and// nothing that could double-deliver under this key either.if (!paymentHash) return { granted: true, replay: false, unavailable: false };+ const failed = outcome === 'failed_after_settle';try {const rows = await sql`- INSERT INTO x402_spent_payments (payment_hash, endpoint, amount_atomics)- VALUES (${paymentHash}, ${endpoint}, ${amountAtomics == null ? null : String(amountAtomics)})+ INSERT INTO x402_spent_payments+ (payment_hash, endpoint, amount_atomics, outcome, settlement, last_error, retry_until)+ VALUES (${paymentHash}, ${endpoint}, ${amountAtomics == null ? null : String(amountAtomics)},+ ${failed ? 'failed_after_settle' : 'delivered'},+ ${settlement ? JSON.stringify(settlement) : null}::jsonb,+ ${lastError ? String(lastError).slice(0, 500) : null},+ ${failed ? new Date(Date.now() + PAID_RETRY_WINDOW_SECONDS * 1000) : null})ON CONFLICT (payment_hash) DO NOTHINGRETURNING payment_hash`;@@ -105,6 +144,108 @@ export async function claimSpentPayment({ paymentHash, endpoint, amountAtomics =}}+/**+ * Record that a claimed proof's work failed after settlement. Opens (or keeps)+ * the retry window and stores the settlement the retry will re-emit.+ *+ * @returns {Promise<{ retriesLeft: number, retryUntil: string|null }>}+ */+export async function markFailedAfterSettle({ paymentHash, settlement = null, lastError = null }) {+ if (!paymentHash) return { retriesLeft: 0, retryUntil: null };+ try {+ const rows = await sql`+ UPDATE x402_spent_payments+ SET outcome = 'failed_after_settle',+ settlement = coalesce(settlement, ${settlement ? JSON.stringify(settlement) : null}::jsonb),+ last_error = ${lastError ? String(lastError).slice(0, 500) : null},+ retry_until = coalesce(retry_until, ${new Date(Date.now() + PAID_RETRY_WINDOW_SECONDS * 1000)}),+ updated_at = now()+ WHERE payment_hash = ${paymentHash}+ RETURNING retry_count, retry_until+ `;+ const row = rows?.[0];+ if (!row) return { retriesLeft: 0, retryUntil: null };+ const open = !row.retry_until || new Date(row.retry_until).getTime() > Date.now();+ return {+ retriesLeft: open ? Math.max(0, PAID_RETRY_MAX - Number(row.retry_count || 0)) : 0,+ retryUntil: row.retry_until ? new Date(row.retry_until).toISOString() : null,+ };+ } catch (err) {+ logDegraded('mark_failed', err);+ return { retriesLeft: 0, retryUntil: null };+ }+}++/**+ * Take one retry for a proof that failed after settlement. Atomic: two+ * concurrent retries of one header cannot both run. Returns the stored+ * settlement so the retry can answer with the original x-payment-response.+ *+ * @returns {Promise<{ granted: boolean, settlement: object|null, attempt: number }>}+ */+export async function claimPaidRetry({ paymentHash, endpoint }) {+ if (!paymentHash) return { granted: false, settlement: null, attempt: 0 };+ try {+ const rows = await sql`+ UPDATE x402_spent_payments+ SET outcome = 'retrying', retry_count = retry_count + 1, updated_at = now()+ WHERE payment_hash = ${paymentHash}+ AND endpoint = ${endpoint}+ AND outcome = 'failed_after_settle'+ AND retry_count < ${PAID_RETRY_MAX}+ AND (retry_until IS NULL OR retry_until > now())+ RETURNING settlement, retry_count+ `;+ const row = rows?.[0];+ if (!row) return { granted: false, settlement: null, attempt: 0 };+ const settlement = typeof row.settlement === 'string' ? JSON.parse(row.settlement) : row.settlement;+ return { granted: true, settlement: settlement || null, attempt: Number(row.retry_count) };+ } catch (err) {+ logDegraded('claim_retry', err);+ return { granted: false, settlement: null, attempt: 0 };+ }+}++/** A retried call delivered: from here on the proof answers 409 like any other. */+export async function markDelivered(paymentHash) {+ if (!paymentHash) return;+ try {+ await sql`+ UPDATE x402_spent_payments+ SET outcome = 'delivered', last_error = NULL, updated_at = now()+ WHERE payment_hash = ${paymentHash}+ `;+ } catch (err) {+ logDegraded('mark_delivered', err);+ }+}++export const PAID_RETRY_SENTENCE =+ 'You were charged; repeat this exact request with the same payment to get your result.';+export const PAID_EXHAUSTED_SENTENCE =+ 'You were charged, and this payment has used up its retries. Contact support with the settlement transaction and it will be made right.';++/**+ * The fields every failure after settlement carries, so a buyer's client can+ * tell "you paid, retry safely" from "you were not charged".+ *+ * @param {{ settlement: object|null, retriesLeft: number, retryUntil?: string|null }} ctx+ */+export function paidFailureFields({ settlement, retriesLeft, retryUntil = null }) {+ const retrySafe = retriesLeft > 0;+ return {+ paid: true,+ retry_safe: retrySafe,+ settlement: {+ transaction: settlement?.transaction ?? null,+ network: settlement?.network ?? null,+ },+ retries_left: Math.max(0, retriesLeft),+ ...(retryUntil ? { retry_until: retryUntil } : {}),+ message: retrySafe ? PAID_RETRY_SENTENCE : PAID_EXHAUSTED_SENTENCE,+ };+}+/*** 409 for a proof that was already honoured. Distinct from the idempotency* conflict/in-flight 409s (`x-x402-idempotent: conflict` / `in-flight`) so a