bsv-x402 0.9.1 → 0.10.0

package/README.md

@@ -1,24 +1,35 @@
 # bsv-x402
 
-A JavaScript client library for the [x402 payment protocol](https://x402.merkleworks.io/). Wraps `fetch()` to handle HTTP 402 payment flows transparently.
+A JavaScript client library and browser extension for BSV micropayments over HTTP 402. Wraps `fetch()` to transparently handle payment flows using multiple protocols (Custom X402, BRC-105, BRC-121).
 
 ## How It Works
 
 ```js
-import { x402Fetch } from 'bsv-x402'
+import { createX402Fetch } from 'bsv-x402'
 
+const x402Fetch = createX402Fetch({ brc105Wallet: window.CWI })
 const response = await x402Fetch('https://api.example.com/paid-endpoint')
 ```
 
 When the server responds with `402 Payment Required`, the library:
 
-1. Parses the `X402-Challenge` header
+1. Detects the protocol from response headers (X402-Challenge, BRC-105, or BRC-121)
 2. Constructs a payment transaction via the browser wallet ([BRC-100](https://github.com/bitcoin-sv/BRCs/blob/master/wallet/0100.md) / `window.CWI`)
-3. Broadcasts the transaction to the BSV network
-4. Retries the original request with an `X402-Proof` header
+3. Sends the proof to the server and retries the request
+4. On server 200: broadcasts the transaction (transitioning `nosend` → `unproven`)
+5. On server 4xx: aborts the transaction (freeing locked UTXOs)
 
 The app developer just uses `x402Fetch` in place of `fetch`. The browser wallet handles key management and signing.
 
+## Browser Extension
+
+The repository also includes browser extensions (Chromium, Firefox, Safari) that provide a full BRC-100 wallet with native x402 support:
+
+- `window.CWI` injection (all 28 BRC-100 wallet methods)
+- Built-in wallet via `@bsv/wallet-toolbox-client`
+- Autospend controls with Doom II difficulty tiers
+- UTXO Admin view for wallet diagnostics
+
 ## Installation
 
 ```bash
@@ -28,12 +39,22 @@ npm install bsv-x402
 ## Development
 
 ```bash
-npm install       # Install dependencies
-npm run build     # Compile TypeScript → dist/
-npm test          # Run tests
-npm run typecheck # Type-check without emitting
+npm install          # Install dependencies
+npm run build        # Compile TypeScript → dist/
+npm test             # Run tests (vitest)
+npm run typecheck    # Type-check without emitting
+npm run build:all    # Build library + all browser extensions
 ```
 
+## Documentation
+
+- [DESIGN.md](DESIGN.md) — architecture and protocol details
+- [ECONOMICS.md](ECONOMICS.md) — economics of ARC broadcasting for micropayments
+- [BEEF-SIGNALLING.md](BEEF-SIGNALLING.md) — how BEEF type communicates broadcast intent
+- [CHANGELOG.md](CHANGELOG.md) — version history
+
 ## Status
 
-Early development. The fetch wrapper and challenge parsing are in place; the BRC-100 wallet integration (`constructProof`) is not yet implemented.
+Active development (v0.9.1). Library core: multi-protocol 402 handling (Custom X402, BRC-105, BRC-121), adversarial `noSend` payment flow with broadcast-on-200, BEEF acknowledgement mechanism. Browser extensions: full BRC-100 wallet, autospend controls, UTXO recovery tools.
+
+Server counterpart: [x402-rack](https://github.com/sgbett/x402-rack) (Ruby/Rack middleware).

package/dist/index.cjs

@@ -28,11 +28,13 @@ __export(index_exports, {
   clampBalanceToTier: () => clampBalanceToTier,
   constructBrc105Proof: () => constructBrc105Proof,
   constructBrc121Proof: () => constructBrc121Proof,
+  constructPayGatewayProof: () => constructPayGatewayProof,
   createX402Fetch: () => createX402Fetch,
   initialState: () => initialState,
   parseBrc105Challenge: () => parseBrc105Challenge,
   parseBrc121Challenge: () => parseBrc121Challenge,
   parseChallenge: () => parseChallenge,
+  parsePayGatewayChallenge: () => parsePayGatewayChallenge,
   recordPayment: () => recordPayment,
   x402Fetch: () => x402Fetch
 });
@@ -78,7 +80,7 @@ function parseBrc105Challenge(response) {
   };
 }
 
-// src/brc105-proof.ts
+// src/bytes.ts
 function bytesToHex(bytes) {
   return Array.from(bytes).map((b) => b.toString(16).padStart(2, "0")).join("");
 }
@@ -98,6 +100,8 @@ function bytesToBase64(bytes) {
 function numberArrayToBase64(arr) {
   return bytesToBase64(new Uint8Array(arr));
 }
+
+// src/brc105-proof.ts
 var RIPEMD160_CONSTANTS = {
   // Round constants for left and right paths
   KL: [0, 1518500249, 1859775393, 2400959708, 2840853838],
@@ -523,34 +527,66 @@ async function createDerivationSuffix(wallet) {
   return numberArrayToBase64(nonceBytes);
 }
 async function constructBrc105Proof(challenge, wallet, origin) {
-  const { publicKey: clientIdentityKey } = await wallet.getPublicKey({ identityKey: true });
-  const derivationSuffix = await createDerivationSuffix(wallet);
+  let clientIdentityKey;
+  try {
+    const r = await wallet.getPublicKey({ identityKey: true });
+    clientIdentityKey = r.publicKey;
+  } catch (err) {
+    console.error("[x402] BRC-105 proof: failed to get identity key:", err);
+    throw err;
+  }
+  let derivationSuffix;
+  try {
+    derivationSuffix = await createDerivationSuffix(wallet);
+  } catch (err) {
+    console.error("[x402] BRC-105 proof: failed to generate derivation suffix:", err);
+    throw err;
+  }
   const keyID = `${challenge.derivationPrefix} ${derivationSuffix}`;
-  const { publicKey: derivedPublicKey } = await wallet.getPublicKey({
-    protocolID: [2, "3241645161d8"],
-    keyID,
-    counterparty: challenge.serverIdentityKey
-  });
-  const lockingScript = await pubkeyToP2PKHLockingScript(derivedPublicKey);
+  let derivedPublicKey;
+  try {
+    const r = await wallet.getPublicKey({
+      protocolID: [2, "3241645161d8"],
+      keyID,
+      counterparty: challenge.serverIdentityKey
+    });
+    derivedPublicKey = r.publicKey;
+  } catch (err) {
+    console.error("[x402] BRC-105 proof: BRC-29 key derivation failed:", err);
+    throw err;
+  }
+  let lockingScript;
+  try {
+    lockingScript = await pubkeyToP2PKHLockingScript(derivedPublicKey);
+  } catch (err) {
+    console.error("[x402] BRC-105 proof: P2PKH script generation failed:", err);
+    throw err;
+  }
   const description = origin ? `Payment for request to ${origin}` : "BRC-105 payment";
-  const result = await wallet.createAction({
-    description,
-    outputs: [{
-      satoshis: challenge.satoshisRequired,
-      lockingScript,
-      outputDescription: "HTTP request payment",
-      customInstructions: JSON.stringify({
-        derivationPrefix: challenge.derivationPrefix,
-        derivationSuffix,
-        payee: challenge.serverIdentityKey
-      })
-    }],
-    options: {
-      returnTXIDOnly: false,
-      noSend: true,
-      randomizeOutputs: false
-    }
-  });
+  let result;
+  try {
+    result = await wallet.createAction({
+      description,
+      outputs: [{
+        satoshis: challenge.satoshisRequired,
+        lockingScript,
+        outputDescription: "HTTP request payment",
+        customInstructions: JSON.stringify({
+          derivationPrefix: challenge.derivationPrefix,
+          derivationSuffix,
+          payee: challenge.serverIdentityKey
+        })
+      }],
+      options: {
+        returnTXIDOnly: false,
+        noSend: true,
+        randomizeOutputs: false
+      }
+    });
+  } catch (err) {
+    console.error(`[x402] BRC-105 proof: createAction failed (${challenge.satoshisRequired} sats):`, err);
+    throw err;
+  }
   let transactionBase64;
   if (result.tx && Array.isArray(result.tx) && result.tx.length > 0) {
     transactionBase64 = numberArrayToBase64(result.tx);
@@ -608,54 +644,64 @@ function parseBrc121Challenge(response) {
 }
 
 // src/brc121-proof.ts
-function bytesToBase642(bytes) {
-  let binary = "";
-  for (const b of bytes) binary += String.fromCharCode(b);
-  return btoa(binary);
-}
-function numberArrayToBase642(arr) {
-  return bytesToBase642(new Uint8Array(arr));
-}
-function hexToBytes2(hex) {
-  if (hex.length % 2 !== 0) throw new Error("Hex string must have even length");
-  const bytes = new Uint8Array(hex.length / 2);
-  for (let i = 0; i < hex.length; i += 2) {
-    bytes[i / 2] = parseInt(hex.slice(i, i + 2), 16);
-  }
-  return bytes;
-}
 async function constructBrc121Proof(challenge, wallet, origin) {
-  const { publicKey: clientIdentityKey } = await wallet.getPublicKey({ identityKey: true });
+  let clientIdentityKey;
+  try {
+    const r = await wallet.getPublicKey({ identityKey: true });
+    clientIdentityKey = r.publicKey;
+  } catch (err) {
+    console.error("[x402] BRC-121 proof: failed to get identity key:", err);
+    throw err;
+  }
   const nonceBytes = crypto.getRandomValues(new Uint8Array(8));
   const nonce = btoa(String.fromCharCode(...nonceBytes));
   const time = String(Date.now());
   const timeSuffixB64 = btoa(time);
   const keyID = `${nonce} ${timeSuffixB64}`;
-  const { publicKey: derivedPublicKey } = await wallet.getPublicKey({
-    protocolID: [2, "3241645161d8"],
-    keyID,
-    counterparty: challenge.serverIdentityKey
-  });
-  const lockingScript = await pubkeyToP2PKHLockingScript(derivedPublicKey);
+  let derivedPublicKey;
+  try {
+    const r = await wallet.getPublicKey({
+      protocolID: [2, "3241645161d8"],
+      keyID,
+      counterparty: challenge.serverIdentityKey
+    });
+    derivedPublicKey = r.publicKey;
+  } catch (err) {
+    console.error("[x402] BRC-121 proof: BRC-29 key derivation failed:", err);
+    throw err;
+  }
+  let lockingScript;
+  try {
+    lockingScript = await pubkeyToP2PKHLockingScript(derivedPublicKey);
+  } catch (err) {
+    console.error("[x402] BRC-121 proof: P2PKH script generation failed:", err);
+    throw err;
+  }
   const description = origin ? `Payment for request to ${origin}` : "BRC-121 payment";
-  const result = await wallet.createAction({
-    description,
-    outputs: [{
-      satoshis: challenge.satoshis,
-      lockingScript,
-      outputDescription: "BRC-121 payment"
-    }],
-    options: {
-      randomizeOutputs: false,
-      noSend: true,
-      returnTXIDOnly: false
-    }
-  });
+  let result;
+  try {
+    result = await wallet.createAction({
+      description,
+      outputs: [{
+        satoshis: challenge.satoshis,
+        lockingScript,
+        outputDescription: "BRC-121 payment"
+      }],
+      options: {
+        randomizeOutputs: false,
+        noSend: true,
+        returnTXIDOnly: false
+      }
+    });
+  } catch (err) {
+    console.error(`[x402] BRC-121 proof: createAction failed (${challenge.satoshis} sats):`, err);
+    throw err;
+  }
   let transactionBase64;
   if (result.tx && Array.isArray(result.tx) && result.tx.length > 0) {
-    transactionBase64 = numberArrayToBase642(result.tx);
+    transactionBase64 = numberArrayToBase64(result.tx);
   } else if (result.rawTx && typeof result.rawTx === "string" && result.rawTx.length > 0) {
-    transactionBase64 = bytesToBase642(hexToBytes2(result.rawTx));
+    transactionBase64 = bytesToBase64(hexToBytes(result.rawTx));
   } else {
     throw new Error("Wallet returned no transaction data (neither tx nor rawTx)");
   }
@@ -720,23 +766,158 @@ function parseChallenge(header) {
   };
 }
 
-// src/x402-fetch.ts
-function bytesToBase643(bytes) {
-  let binary = "";
-  for (const b of bytes) binary += String.fromCharCode(b);
-  return btoa(binary);
-}
-function numberArrayToBase643(arr) {
-  return bytesToBase643(new Uint8Array(arr));
+// src/paygateway-challenge.ts
+function parsePayGatewayChallenge(response) {
+  const header = response.headers.get("Payment-Required");
+  if (header === null || header.length === 0) {
+    return null;
+  }
+  let json;
+  try {
+    json = atob(header);
+  } catch {
+    return null;
+  }
+  let parsed;
+  try {
+    parsed = JSON.parse(json);
+  } catch {
+    return null;
+  }
+  if (typeof parsed !== "object" || parsed === null) {
+    return null;
+  }
+  const obj = parsed;
+  if (obj.x402Version !== 2) {
+    return null;
+  }
+  if (!Array.isArray(obj.accepts) || obj.accepts.length === 0) {
+    return null;
+  }
+  const bsvAccept = obj.accepts.find((entry) => {
+    if (typeof entry !== "object" || entry === null) return false;
+    const e = entry;
+    return typeof e.network === "string" && e.network.startsWith("bsv:");
+  });
+  if (!bsvAccept) {
+    return null;
+  }
+  if (typeof bsvAccept.payTo !== "string" || bsvAccept.payTo.length === 0) {
+    throw new Error("[x402] PayGateway: missing or empty payTo in BSV accept entry");
+  }
+  if (!/^[0-9a-fA-F]+$/.test(bsvAccept.payTo)) {
+    throw new Error("[x402] PayGateway: payTo must be a hex-encoded locking script");
+  }
+  let amountStr;
+  if (typeof bsvAccept.amount === "string") {
+    amountStr = bsvAccept.amount;
+  } else if (typeof bsvAccept.amount === "number") {
+    amountStr = String(bsvAccept.amount);
+  } else {
+    throw new Error("[x402] PayGateway: missing or invalid amount in BSV accept entry");
+  }
+  const amountNum = Number(amountStr);
+  if (!Number.isFinite(amountNum) || !Number.isInteger(amountNum) || amountNum <= 0) {
+    throw new Error("[x402] PayGateway: amount must be a positive integer");
+  }
+  const extra = bsvAccept.extra;
+  if (typeof extra !== "object" || extra === null) {
+    throw new Error("[x402] PayGateway: missing extra object in BSV accept entry");
+  }
+  if (typeof extra.payToSig !== "string" || extra.payToSig.length === 0) {
+    throw new Error("[x402] PayGateway: missing or empty extra.payToSig in BSV accept entry");
+  }
+  const selectedAccept = {
+    scheme: typeof bsvAccept.scheme === "string" ? bsvAccept.scheme : "exact",
+    network: bsvAccept.network,
+    amount: amountStr,
+    asset: typeof bsvAccept.asset === "string" ? bsvAccept.asset : "BSV",
+    payTo: bsvAccept.payTo,
+    maxTimeoutSeconds: typeof bsvAccept.maxTimeoutSeconds === "number" ? bsvAccept.maxTimeoutSeconds : 60,
+    extra: {
+      payToSig: extra.payToSig,
+      ...typeof extra.partialTx === "string" ? { partialTx: extra.partialTx } : {},
+      ...typeof extra.derivationPrefix === "string" ? { derivationPrefix: extra.derivationPrefix } : {},
+      ...typeof extra.derivationSuffix === "string" ? { derivationSuffix: extra.derivationSuffix } : {}
+    }
+  };
+  const resource = typeof obj.resource === "object" && obj.resource !== null ? obj.resource : { url: "" };
+  return {
+    x402Version: 2,
+    resource,
+    accepts: [selectedAccept],
+    selectedAccept
+  };
 }
-function hexToBytes3(hex) {
-  if (hex.length % 2 !== 0) throw new Error("Hex string must have even length");
-  const bytes = new Uint8Array(hex.length / 2);
-  for (let i = 0; i < hex.length; i += 2) {
-    bytes[i / 2] = parseInt(hex.slice(i, i + 2), 16);
+
+// src/paygateway-proof.ts
+async function constructPayGatewayProof(challenge, wallet, origin) {
+  const accept = challenge.selectedAccept;
+  const satoshis = parseInt(accept.amount, 10);
+  if (isNaN(satoshis) || satoshis <= 0) {
+    const msg = `[x402] PayGateway proof: invalid amount "${accept.amount}"`;
+    console.error(msg);
+    throw new Error(msg);
   }
-  return bytes;
+  const description = origin ? `Payment for request to ${origin}` : "PayGateway payment";
+  let result;
+  try {
+    result = await wallet.createAction({
+      description,
+      outputs: [{
+        satoshis,
+        lockingScript: accept.payTo,
+        outputDescription: "PayGateway payment"
+      }],
+      options: {
+        noSend: true,
+        returnTXIDOnly: false,
+        randomizeOutputs: false
+      }
+    });
+  } catch (err) {
+    console.error(`[x402] PayGateway proof: createAction failed (${satoshis} sats):`, err);
+    throw err;
+  }
+  let rawtx;
+  let beef;
+  if (result.tx && Array.isArray(result.tx) && result.tx.length > 0) {
+    const txBytes = new Uint8Array(result.tx);
+    rawtx = bytesToHex(txBytes);
+    beef = bytesToBase64(txBytes);
+  } else if (result.rawTx && typeof result.rawTx === "string" && result.rawTx.length > 0) {
+    rawtx = result.rawTx;
+  } else {
+    const msg = "[x402] PayGateway proof: wallet returned no transaction data (neither tx nor rawTx)";
+    console.error(msg);
+    throw new Error("Wallet returned no transaction data (neither tx nor rawTx)");
+  }
+  const proof = { rawtx, txid: result.txid };
+  if (beef) {
+    proof.beef = beef;
+  }
+  const abort = wallet.abortAction ? async () => {
+    try {
+      await wallet.abortAction({ reference: result.txid });
+    } catch (err) {
+      console.warn("[x402] PayGateway abortAction failed:", err);
+    }
+  } : void 0;
+  const broadcast = wallet.createAction ? async () => {
+    try {
+      await wallet.createAction({
+        description: "Broadcast x402 payment",
+        outputs: [],
+        options: { sendWith: [result.txid] }
+      });
+    } catch (err) {
+      console.warn("[x402] PayGateway broadcast failed:", err);
+    }
+  } : void 0;
+  return { proof, abort, broadcast };
 }
+
+// src/x402-fetch.ts
 var BASE58_ALPHABET = "123456789ABCDEFGHJKLMNPQRSTUVWXYZabcdefghijkmnopqrstuvwxyz";
 function base58ToBytes(encoded) {
   let leadingZeros = 0;
@@ -805,9 +986,9 @@ async function defaultConstructProof(challenge) {
   }
   let beef;
   if (result.tx && Array.isArray(result.tx) && result.tx.length > 0) {
-    beef = numberArrayToBase643(result.tx);
+    beef = numberArrayToBase64(result.tx);
   } else if (result.rawTx && typeof result.rawTx === "string" && result.rawTx.length > 0) {
-    beef = bytesToBase643(hexToBytes3(result.rawTx));
+    beef = bytesToBase64(hexToBytes(result.rawTx));
   } else {
     throw new Error("Wallet returned no transaction data (neither tx nor rawTx)");
   }
@@ -822,6 +1003,8 @@ function createX402Fetch(config = {}) {
   const brc105Wallet = config.brc105Wallet;
   const brc121ProofConstructor = config.brc121ProofConstructor;
   const brc121Wallet = config.brc121Wallet;
+  const payGatewayProofConstructor = config.payGatewayProofConstructor;
+  const payGatewayWallet = config.payGatewayWallet;
   const maxRetries = config.maxRetries ?? 2;
   const ackWallet = config.ackWallet;
   const serverIdentityKey = config.serverIdentityKey;
@@ -891,7 +1074,8 @@ function createX402Fetch(config = {}) {
       let challenge;
       try {
         challenge = parseChallenge(challengeHeader);
-      } catch {
+      } catch (err) {
+        console.warn("[x402] Malformed X402-Challenge header, treating as non-payable:", err);
         return response;
       }
       let proof;
@@ -915,7 +1099,8 @@ function createX402Fetch(config = {}) {
       let brc105Challenge;
       try {
         brc105Challenge = parseBrc105Challenge(response);
-      } catch {
+      } catch (err) {
+        console.warn("[x402] Malformed BRC-105 challenge headers, treating as non-payable:", err);
         return response;
       }
       const buildProof = async () => {
@@ -954,7 +1139,8 @@ function createX402Fetch(config = {}) {
           retryResponse = await fetch(input, { ...init, headers: proofHeaders(proof) });
           networkError = false;
           break;
-        } catch {
+        } catch (err) {
+          console.warn(`[x402] Network error on retry attempt ${attempt + 1}/${maxRetries + 1}:`, err);
           networkError = true;
         }
       }
@@ -1017,7 +1203,8 @@ function createX402Fetch(config = {}) {
     let brc121Challenge;
     try {
       brc121Challenge = parseBrc121Challenge(response);
-    } catch {
+    } catch (err) {
+      console.warn("[x402] Malformed BRC-121 challenge headers, treating as non-payable:", err);
       return response;
     }
     if (brc121Challenge) {
@@ -1064,7 +1251,8 @@ function createX402Fetch(config = {}) {
           retryResponse = await fetch(input, { ...init, headers: proofHeaders(proof) });
           networkError = false;
           break;
-        } catch {
+        } catch (err) {
+          console.warn(`[x402] Network error on retry attempt ${attempt + 1}/${maxRetries + 1}:`, err);
           networkError = true;
         }
       }
@@ -1124,6 +1312,123 @@ function createX402Fetch(config = {}) {
       await processPendingBeefs(freshResponse);
       return freshResponse;
     }
+    let payGatewayChallenge;
+    try {
+      payGatewayChallenge = parsePayGatewayChallenge(response);
+    } catch (err) {
+      console.warn("[x402] Malformed PayGateway challenge, treating as non-payable:", err);
+      return response;
+    }
+    if (payGatewayChallenge) {
+      if (!payGatewayProofConstructor && !payGatewayWallet) {
+        await processPendingBeefs(response);
+        return response;
+      }
+      const buildProof = async () => {
+        if (payGatewayProofConstructor) {
+          return payGatewayProofConstructor(payGatewayChallenge);
+        }
+        return constructPayGatewayProof(payGatewayChallenge, payGatewayWallet, origin);
+      };
+      const proofHeaders = (proof2, challenge) => {
+        const h = new Headers(init?.headers);
+        const signaturePayload = {
+          x402Version: challenge.x402Version,
+          accepted: challenge.selectedAccept,
+          payload: {
+            rawtx: proof2.rawtx,
+            txid: proof2.txid,
+            ...proof2.beef ? { beef: proof2.beef } : {}
+          }
+        };
+        h.set("Payment-Signature", btoa(JSON.stringify(signaturePayload)));
+        injectAckHeader(h);
+        return h;
+      };
+      let proof;
+      let abort;
+      let broadcast;
+      try {
+        const result = await buildProof();
+        proof = result.proof;
+        abort = result.abort;
+        broadcast = result.broadcast;
+      } catch (err) {
+        console.error("[x402] Proof construction failed (paygateway):", err);
+        config.onProofError?.(err, "paygateway");
+        return response;
+      }
+      let retryResponse;
+      let networkError = false;
+      for (let attempt = 0; attempt <= maxRetries; attempt++) {
+        if (attempt > 0) {
+          await delay(1e3 * 2 ** (attempt - 1));
+        }
+        try {
+          retryResponse = await fetch(input, { ...init, headers: proofHeaders(proof, payGatewayChallenge) });
+          networkError = false;
+          break;
+        } catch (err) {
+          console.warn(`[x402] Network error on retry attempt ${attempt + 1}/${maxRetries + 1}:`, err);
+          networkError = true;
+        }
+      }
+      if (networkError) {
+        throw new Error(
+          `[x402] Payment state unknown: network error after ${maxRetries + 1} attempts. The transaction may have been broadcast \u2014 do not retry with a new transaction without checking on-chain state.`
+        );
+      }
+      if (retryResponse.ok) {
+        if (broadcast) {
+          broadcast().catch((err) => console.warn("[x402] broadcast failed:", err));
+        }
+        await processPendingBeefs(retryResponse);
+        return retryResponse;
+      }
+      if (abort) {
+        try {
+          await abort();
+          console.warn("[x402] Server rejected PayGateway payment, UTXOs released via abortAction");
+        } catch (err) {
+          console.warn("[x402] abortAction failed during server rejection:", err);
+        }
+      }
+      let freshProof;
+      let freshAbort;
+      let freshBroadcast;
+      try {
+        const result = await buildProof();
+        freshProof = result.proof;
+        freshAbort = result.abort;
+        freshBroadcast = result.broadcast;
+      } catch (err) {
+        console.error("[x402] Fresh proof construction failed (paygateway):", err);
+        config.onProofError?.(err, "paygateway");
+        return retryResponse;
+      }
+      let freshResponse;
+      try {
+        freshResponse = await fetch(input, { ...init, headers: proofHeaders(freshProof, payGatewayChallenge) });
+      } catch {
+        throw new Error(
+          "[x402] Payment state unknown: network error on fresh retry. The transaction may have been broadcast \u2014 do not retry with a new transaction without checking on-chain state."
+        );
+      }
+      if (freshResponse.ok) {
+        if (freshBroadcast) {
+          freshBroadcast().catch((err) => console.warn("[x402] broadcast failed:", err));
+        }
+      } else if (freshAbort) {
+        try {
+          await freshAbort();
+          console.warn("[x402] Server rejected fresh PayGateway payment, UTXOs released via abortAction");
+        } catch (err) {
+          console.warn("[x402] freshAbort failed during double rejection:", err);
+        }
+      }
+      await processPendingBeefs(freshResponse);
+      return freshResponse;
+    }
     await processPendingBeefs(response);
     return response;
   };
@@ -1238,11 +1543,13 @@ function initialState(config, walletBalance) {
   clampBalanceToTier,
   constructBrc105Proof,
   constructBrc121Proof,
+  constructPayGatewayProof,
   createX402Fetch,
   initialState,
   parseBrc105Challenge,
   parseBrc121Challenge,
   parseChallenge,
+  parsePayGatewayChallenge,
   recordPayment,
   x402Fetch
 });