bsv-x402 0.7.0 → 0.8.0

package/dist/index.cjs

@@ -27,9 +27,11 @@ __export(index_exports, {
   checkPayment: () => checkPayment,
   clampBalanceToTier: () => clampBalanceToTier,
   constructBrc105Proof: () => constructBrc105Proof,
+  constructBrc121Proof: () => constructBrc121Proof,
   createX402Fetch: () => createX402Fetch,
   initialState: () => initialState,
   parseBrc105Challenge: () => parseBrc105Challenge,
+  parseBrc121Challenge: () => parseBrc121Challenge,
   parseChallenge: () => parseChallenge,
   recordPayment: () => recordPayment,
   x402Fetch: () => x402Fetch
@@ -574,6 +576,96 @@ async function constructBrc105Proof(challenge, wallet, origin) {
   return { proof, abort };
 }
 
+// src/brc121-challenge.ts
+function parseBrc121Challenge(response) {
+  if (response.headers.get("x-bsv-payment-version") !== null) {
+    return null;
+  }
+  const satsHeader = response.headers.get("x-bsv-sats");
+  const serverHeader = response.headers.get("x-bsv-server");
+  if (!satsHeader || !serverHeader) {
+    return null;
+  }
+  const satoshis = Number(satsHeader);
+  if (!Number.isFinite(satoshis) || !Number.isInteger(satoshis) || satoshis <= 0) {
+    throw new Error(`BRC-121: x-bsv-sats must be a positive integer, got "${satsHeader}"`);
+  }
+  if (!/^0[23][0-9a-fA-F]{64}$/.test(serverHeader)) {
+    throw new Error("BRC-121: x-bsv-server must be a 33-byte compressed public key (hex)");
+  }
+  return { satoshis, serverIdentityKey: serverHeader };
+}
+
+// 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 });
+  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);
+  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 transactionBase64;
+  if (result.tx && Array.isArray(result.tx) && result.tx.length > 0) {
+    transactionBase64 = numberArrayToBase642(result.tx);
+  } else if (result.rawTx && typeof result.rawTx === "string" && result.rawTx.length > 0) {
+    transactionBase64 = bytesToBase642(hexToBytes2(result.rawTx));
+  } else {
+    throw new Error("Wallet returned no transaction data (neither tx nor rawTx)");
+  }
+  const proof = {
+    beef: transactionBase64,
+    senderIdentityKey: clientIdentityKey,
+    nonce,
+    time,
+    vout: "0",
+    txid: result.txid
+  };
+  const abort = wallet.abortAction ? async () => {
+    try {
+      await wallet.abortAction({ reference: result.txid });
+    } catch (err) {
+      console.warn("[x402] abortAction failed:", err);
+    }
+  } : void 0;
+  return { proof, abort };
+}
+
 // src/challenge.ts
 function parseChallenge(header) {
   let parsed;
@@ -607,15 +699,15 @@ function parseChallenge(header) {
 }
 
 // src/x402-fetch.ts
-function bytesToBase642(bytes) {
+function bytesToBase643(bytes) {
   let binary = "";
   for (const b of bytes) binary += String.fromCharCode(b);
   return btoa(binary);
 }
-function numberArrayToBase642(arr) {
-  return bytesToBase642(new Uint8Array(arr));
+function numberArrayToBase643(arr) {
+  return bytesToBase643(new Uint8Array(arr));
 }
-function hexToBytes2(hex) {
+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) {
@@ -624,14 +716,14 @@ function hexToBytes2(hex) {
   return bytes;
 }
 var BASE58_ALPHABET = "123456789ABCDEFGHJKLMNPQRSTUVWXYZabcdefghijkmnopqrstuvwxyz";
-function base58DecodeCheck(address) {
+function base58ToBytes(encoded) {
   let leadingZeros = 0;
-  for (const c of address) {
+  for (const c of encoded) {
     if (c === "1") leadingZeros++;
     else break;
   }
   let n = BigInt(0);
-  for (const c of address) {
+  for (const c of encoded) {
     const i = BASE58_ALPHABET.indexOf(c);
     if (i < 0) throw new Error(`Invalid Base58 character: ${c}`);
     n = n * 58n + BigInt(i);
@@ -644,11 +736,14 @@ function base58DecodeCheck(address) {
   }
   const allBytes = new Uint8Array(leadingZeros + bigintBytes.length);
   allBytes.set(bigintBytes, leadingZeros);
+  return allBytes;
+}
+function base58DecodeCheck(address) {
+  const allBytes = base58ToBytes(address);
   if (allBytes.length !== 25) {
     throw new Error(`Invalid address length: expected 25 bytes, got ${allBytes.length}`);
   }
   const body = allBytes.slice(0, 21);
-  const checksum = allBytes.slice(21);
   const version = allBytes[0];
   if (version !== 0 && version !== 111) {
     throw new Error(`Unsupported address version: 0x${version.toString(16).padStart(2, "0")}`);
@@ -688,9 +783,9 @@ async function defaultConstructProof(challenge) {
   }
   let beef;
   if (result.tx && Array.isArray(result.tx) && result.tx.length > 0) {
-    beef = numberArrayToBase642(result.tx);
+    beef = numberArrayToBase643(result.tx);
   } else if (result.rawTx && typeof result.rawTx === "string" && result.rawTx.length > 0) {
-    beef = bytesToBase642(hexToBytes2(result.rawTx));
+    beef = bytesToBase643(hexToBytes3(result.rawTx));
   } else {
     throw new Error("Wallet returned no transaction data (neither tx nor rawTx)");
   }
@@ -703,9 +798,71 @@ function createX402Fetch(config = {}) {
   const constructProof = config.proofConstructor ?? defaultConstructProof;
   const brc105ProofConstructor = config.brc105ProofConstructor;
   const brc105Wallet = config.brc105Wallet;
+  const brc121ProofConstructor = config.brc121ProofConstructor;
+  const brc121Wallet = config.brc121Wallet;
+  const maxRetries = config.maxRetries ?? 2;
+  const ackWallet = config.ackWallet;
+  const serverIdentityKey = config.serverIdentityKey;
+  const ackedTxids = /* @__PURE__ */ new Set();
+  const internalisedTxids = /* @__PURE__ */ new Set();
+  function injectAckHeader(headers) {
+    if (ackedTxids.size > 0) {
+      headers.set("x-bsv-ack", [...ackedTxids].join(","));
+      ackedTxids.clear();
+    }
+  }
+  async function processPendingBeefs(response) {
+    if (!ackWallet) return;
+    let body;
+    try {
+      const clone = response.clone();
+      body = await clone.json();
+    } catch {
+      return;
+    }
+    if (!Array.isArray(body?.pendingBeefs)) return;
+    for (const entry of body.pendingBeefs) {
+      if (!entry?.txid || !entry?.beef) continue;
+      if (!entry.derivationPrefix || !entry.derivationSuffix) continue;
+      if (internalisedTxids.has(entry.txid)) {
+        ackedTxids.add(entry.txid);
+        continue;
+      }
+      const senderKey = entry.senderIdentityKey ?? serverIdentityKey;
+      if (!senderKey) {
+        console.warn(`[x402] Cannot internalise BEEF ${entry.txid}: no senderIdentityKey`);
+        continue;
+      }
+      try {
+        const txBytes = Array.from(atob(entry.beef), (c) => c.charCodeAt(0));
+        await ackWallet.internalizeAction({
+          tx: txBytes,
+          outputs: [{
+            outputIndex: entry.outputIndex ?? 0,
+            protocol: "wallet payment",
+            paymentRemittance: {
+              derivationPrefix: entry.derivationPrefix,
+              derivationSuffix: entry.derivationSuffix,
+              senderIdentityKey: senderKey
+            }
+          }],
+          description: "x402 refund receipt"
+        });
+        internalisedTxids.add(entry.txid);
+        ackedTxids.add(entry.txid);
+      } catch (err) {
+        console.warn(`[x402] Failed to internalise BEEF ${entry.txid}:`, err);
+      }
+    }
+  }
   return async function x402Fetch2(input, init) {
-    const response = await fetch(input, init);
-    if (response.status !== 402) return response;
+    const initialHeaders = new Headers(init?.headers);
+    injectAckHeader(initialHeaders);
+    const response = await fetch(input, { ...init, headers: initialHeaders });
+    if (response.status !== 402) {
+      await processPendingBeefs(response);
+      return response;
+    }
     const origin = extractOrigin(input);
     const challengeHeader = response.headers.get("X402-Challenge");
     if (challengeHeader) {
@@ -725,7 +882,10 @@ function createX402Fetch(config = {}) {
       }
       const headers = new Headers(init?.headers);
       headers.set("X402-Proof", JSON.stringify(proof));
-      return fetch(input, { ...init, headers });
+      injectAckHeader(headers);
+      const retryResp = await fetch(input, { ...init, headers });
+      await processPendingBeefs(retryResp);
+      return retryResp;
     }
     const brc105Version = response.headers.get("x-bsv-payment-version");
     if (brc105Version) {
@@ -736,42 +896,191 @@ function createX402Fetch(config = {}) {
       } catch {
         return response;
       }
+      const buildProof = async () => {
+        if (brc105ProofConstructor) {
+          return brc105ProofConstructor(brc105Challenge);
+        }
+        return constructBrc105Proof(brc105Challenge, brc105Wallet, origin);
+      };
+      const proofHeaders = (proof2) => {
+        const h = new Headers(init?.headers);
+        h.set("x-bsv-payment", JSON.stringify(proof2));
+        h.set("x-bsv-auth-identity-key", proof2.clientIdentityKey);
+        injectAckHeader(h);
+        return h;
+      };
       let proof;
       let abort;
       try {
-        if (brc105ProofConstructor) {
-          const result = await brc105ProofConstructor(brc105Challenge);
-          proof = result.proof;
-          abort = result.abort;
-        } else {
-          const result = await constructBrc105Proof(brc105Challenge, brc105Wallet, origin);
-          proof = result.proof;
-          abort = result.abort;
-        }
+        const result = await buildProof();
+        proof = result.proof;
+        abort = result.abort;
       } catch (err) {
         console.error("[x402] Proof construction failed (brc105):", err);
         config.onProofError?.(err, "brc105");
         return response;
       }
-      const headers = new Headers(init?.headers);
-      headers.set("x-bsv-payment", JSON.stringify(proof));
-      headers.set("x-bsv-auth-identity-key", proof.clientIdentityKey);
       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) });
+          networkError = false;
+          break;
+        } catch {
+          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) {
+        await processPendingBeefs(retryResponse);
+        return retryResponse;
+      }
+      if (abort) {
+        try {
+          await abort();
+          console.warn("[x402] Server rejected BRC-105 payment, UTXOs released via abortAction");
+        } catch (err) {
+          console.warn("[x402] abortAction failed during server rejection:", err);
+        }
+      }
+      let freshProof;
+      let freshAbort;
+      try {
+        const result = await buildProof();
+        freshProof = result.proof;
+        freshAbort = result.abort;
+      } catch (err) {
+        console.error("[x402] Fresh proof construction failed (brc105):", err);
+        config.onProofError?.(err, "brc105");
+        return retryResponse;
+      }
+      let freshResponse;
+      try {
+        freshResponse = await fetch(input, { ...init, headers: proofHeaders(freshProof) });
+      } 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 && freshAbort) {
+        try {
+          await freshAbort();
+          console.warn("[x402] Server rejected fresh BRC-105 payment, UTXOs released via abortAction");
+        } catch (err) {
+          console.warn("[x402] freshAbort failed during double rejection:", err);
+        }
+      }
+      await processPendingBeefs(freshResponse);
+      return freshResponse;
+    }
+    let brc121Challenge;
+    try {
+      brc121Challenge = parseBrc121Challenge(response);
+    } catch {
+      return response;
+    }
+    if (brc121Challenge) {
+      if (!brc121ProofConstructor && !brc121Wallet) {
+        await processPendingBeefs(response);
+        return response;
+      }
+      const buildProof = async () => {
+        if (brc121ProofConstructor) {
+          return brc121ProofConstructor(brc121Challenge);
+        }
+        return constructBrc121Proof(brc121Challenge, brc121Wallet, origin);
+      };
+      const proofHeaders = (proof2) => {
+        const h = new Headers(init?.headers);
+        h.set("x-bsv-beef", proof2.beef);
+        h.set("x-bsv-sender", proof2.senderIdentityKey);
+        h.set("x-bsv-nonce", proof2.nonce);
+        h.set("x-bsv-time", proof2.time);
+        h.set("x-bsv-vout", proof2.vout);
+        injectAckHeader(h);
+        return h;
+      };
+      let proof;
+      let abort;
       try {
-        retryResponse = await fetch(input, { ...init, headers });
+        const result = await buildProof();
+        proof = result.proof;
+        abort = result.abort;
       } catch (err) {
-        if (abort) {
+        console.error("[x402] Proof construction failed (brc121):", err);
+        config.onProofError?.(err, "brc121");
+        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) });
+          networkError = false;
+          break;
+        } catch {
+          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) {
+        await processPendingBeefs(retryResponse);
+        return retryResponse;
+      }
+      if (abort) {
+        try {
           await abort();
-          console.warn("[x402] BRC-105 retry fetch failed, UTXOs released via abortAction");
+          console.warn("[x402] Server rejected BRC-121 payment, UTXOs released via abortAction");
+        } catch (err) {
+          console.warn("[x402] abortAction failed during server rejection:", err);
         }
-        throw err;
       }
-      if (!retryResponse.ok && abort) {
-        await abort();
-        console.warn("[x402] Server rejected BRC-105 payment, UTXOs released via abortAction");
+      let freshProof;
+      let freshAbort;
+      try {
+        const result = await buildProof();
+        freshProof = result.proof;
+        freshAbort = result.abort;
+      } catch (err) {
+        console.error("[x402] Fresh proof construction failed (brc121):", err);
+        config.onProofError?.(err, "brc121");
+        return retryResponse;
+      }
+      let freshResponse;
+      try {
+        freshResponse = await fetch(input, { ...init, headers: proofHeaders(freshProof) });
+      } 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."
+        );
       }
-      return retryResponse;
+      if (!freshResponse.ok && freshAbort) {
+        try {
+          await freshAbort();
+          console.warn("[x402] Server rejected fresh BRC-121 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;
   };
 }
@@ -780,6 +1089,9 @@ async function x402Fetch(input, init) {
   if (!singleton) singleton = createX402Fetch();
   return singleton(input, init);
 }
+function delay(ms) {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}
 function resolveRelativeUrl(url) {
   const loc = globalThis.location;
   if (loc?.href) {
@@ -881,9 +1193,11 @@ function initialState(config, walletBalance) {
   checkPayment,
   clampBalanceToTier,
   constructBrc105Proof,
+  constructBrc121Proof,
   createX402Fetch,
   initialState,
   parseBrc105Challenge,
+  parseBrc121Challenge,
   parseChallenge,
   recordPayment,
   x402Fetch

package/dist/index.d.cts

@@ -55,7 +55,28 @@ interface Brc105ProofResult {
     abort?: () => Promise<void>;
 }
 type Brc105ProofConstructor = (challenge: Brc105Challenge) => Promise<Brc105ProofResult>;
-type PaymentProtocol = 'x402' | 'brc105';
+/** BRC-121 challenge parsed from 402 response headers. */
+interface Brc121Challenge {
+    satoshis: number;
+    serverIdentityKey: string;
+}
+/** BRC-121 proof — maps to 5 individual HTTP headers. */
+interface Brc121Proof {
+    beef: string;
+    senderIdentityKey: string;
+    nonce: string;
+    time: string;
+    vout: string;
+    txid: string;
+}
+/** Result from BRC-121 proof construction, with optional abort. */
+interface Brc121ProofResult {
+    proof: Brc121Proof;
+    abort?: () => Promise<void>;
+}
+/** Custom BRC-121 proof constructor. */
+type Brc121ProofConstructor = (challenge: Brc121Challenge) => Promise<Brc121ProofResult>;
+type PaymentProtocol = 'x402' | 'brc105' | 'brc121';
 interface PaymentRequest {
     amount: number;
     origin: string;
@@ -71,11 +92,49 @@ interface AutospendConfig {
 interface AutospendState {
     balance: number;
 }
+/** Shape of each entry in the server's `pendingBeefs` response array. */
+interface PendingBeef {
+    txid: string;
+    beef: string;
+    derivationPrefix: string;
+    derivationSuffix: string;
+    senderIdentityKey: string;
+    outputIndex: number;
+}
+/** Narrow wallet interface for BEEF acknowledgement (subset of CWIInterface). */
+interface AckWallet {
+    internalizeAction(params: {
+        tx: number[];
+        outputs: Array<{
+            outputIndex: number;
+            protocol: 'wallet payment';
+            paymentRemittance: {
+                derivationPrefix: string;
+                derivationSuffix: string;
+                senderIdentityKey: string;
+            };
+        }>;
+        description: string;
+        labels?: string[];
+    }): Promise<{
+        accepted: boolean;
+    }>;
+}
 interface X402Config {
     proofConstructor?: (challenge: Challenge) => Promise<Proof>;
     brc105ProofConstructor?: Brc105ProofConstructor;
     brc105Wallet?: Brc105Wallet;
+    /** Custom BRC-121 proof constructor. */
+    brc121ProofConstructor?: Brc121ProofConstructor;
+    /** Wallet for BRC-121 payments (reuses Brc105Wallet interface). */
+    brc121Wallet?: Brc105Wallet;
     onProofError?: (error: unknown, protocol: PaymentProtocol) => void;
+    /** Maximum number of retries for network errors during BRC-105 payment (default: 2). */
+    maxRetries?: number;
+    /** Wallet for internalising received BEEFs and enabling ack headers. */
+    ackWallet?: AckWallet;
+    /** Server identity key for paymentRemittance.senderIdentityKey (fallback when not per-entry). */
+    serverIdentityKey?: string;
 }
 interface CWICreateActionOutput {
     satoshis: number;
@@ -129,6 +188,31 @@ declare function parseBrc105Challenge(response: Response): Brc105Challenge;
  */
 declare function constructBrc105Proof(challenge: Brc105Challenge, wallet: Brc105Wallet, origin?: string): Promise<Brc105ProofResult>;
 
+/**
+ * Parses BRC-121 challenge headers from a 402 response.
+ *
+ * Returns `null` when the required headers are absent or when
+ * `x-bsv-payment-version` is present (indicating BRC-105, not BRC-121).
+ *
+ * Throws on malformed values once the headers are confirmed present,
+ * matching the validation pattern of `parseBrc105Challenge`.
+ */
+declare function parseBrc121Challenge(response: Response): Brc121Challenge | null;
+
+/**
+ * Construct a BRC-121 payment proof from a challenge using BRC-29 key derivation.
+ *
+ * Algorithm (matching @bsv/402-pay reference):
+ * 1. Get client's identity key
+ * 2. Generate nonce (derivation prefix): 8 random bytes → base64
+ * 3. Generate derivation suffix: btoa(Date.now().toString())
+ * 4. Derive payee public key using BRC-29 protocol
+ * 5. Build P2PKH locking script from derived public key
+ * 6. Create transaction via wallet with noSend: true
+ * 7. Convert transaction to base64
+ */
+declare function constructBrc121Proof(challenge: Brc121Challenge, wallet: Brc105Wallet, origin?: string): Promise<Brc121ProofResult>;
+
 /**
  * Autospend balance cap per tier (max sats that can be auto-spent without confirmation).
  * Doom II difficulty progression — each tier is 10x the previous.
@@ -169,4 +253,4 @@ declare function clampBalanceToTier(state: AutospendState, config: AutospendConf
  */
 declare function initialState(config: AutospendConfig, walletBalance: number): AutospendState;
 
-export { type AutospendConfig, type AutospendState, type Brc105Challenge, type Brc105Proof, type Brc105ProofConstructor, type Brc105Wallet, type CWICreateActionOutput, type CWICreateActionParams, type CWICreateActionResult, type Challenge, PICKUP_PERCENTAGES, type PaymentDecision, type PaymentProtocol, type PaymentRequest, type PickupName, type Proof, TIER_CAPS, type TierName, WEAPON_CAPS, type WeaponName, type X402Config, type X402FetchFn, applyPickup, checkPayment, clampBalanceToTier, constructBrc105Proof, createX402Fetch, initialState, parseBrc105Challenge, parseChallenge, recordPayment, x402Fetch };
+export { type AckWallet, type AutospendConfig, type AutospendState, type Brc105Challenge, type Brc105Proof, type Brc105ProofConstructor, type Brc105Wallet, type Brc121Challenge, type Brc121Proof, type Brc121ProofConstructor, type Brc121ProofResult, type CWICreateActionOutput, type CWICreateActionParams, type CWICreateActionResult, type Challenge, PICKUP_PERCENTAGES, type PaymentDecision, type PaymentProtocol, type PaymentRequest, type PendingBeef, type PickupName, type Proof, TIER_CAPS, type TierName, WEAPON_CAPS, type WeaponName, type X402Config, type X402FetchFn, applyPickup, checkPayment, clampBalanceToTier, constructBrc105Proof, constructBrc121Proof, createX402Fetch, initialState, parseBrc105Challenge, parseBrc121Challenge, parseChallenge, recordPayment, x402Fetch };

package/dist/index.d.ts

@@ -55,7 +55,28 @@ interface Brc105ProofResult {
     abort?: () => Promise<void>;
 }
 type Brc105ProofConstructor = (challenge: Brc105Challenge) => Promise<Brc105ProofResult>;
-type PaymentProtocol = 'x402' | 'brc105';
+/** BRC-121 challenge parsed from 402 response headers. */
+interface Brc121Challenge {
+    satoshis: number;
+    serverIdentityKey: string;
+}
+/** BRC-121 proof — maps to 5 individual HTTP headers. */
+interface Brc121Proof {
+    beef: string;
+    senderIdentityKey: string;
+    nonce: string;
+    time: string;
+    vout: string;
+    txid: string;
+}
+/** Result from BRC-121 proof construction, with optional abort. */
+interface Brc121ProofResult {
+    proof: Brc121Proof;
+    abort?: () => Promise<void>;
+}
+/** Custom BRC-121 proof constructor. */
+type Brc121ProofConstructor = (challenge: Brc121Challenge) => Promise<Brc121ProofResult>;
+type PaymentProtocol = 'x402' | 'brc105' | 'brc121';
 interface PaymentRequest {
     amount: number;
     origin: string;
@@ -71,11 +92,49 @@ interface AutospendConfig {
 interface AutospendState {
     balance: number;
 }
+/** Shape of each entry in the server's `pendingBeefs` response array. */
+interface PendingBeef {
+    txid: string;
+    beef: string;
+    derivationPrefix: string;
+    derivationSuffix: string;
+    senderIdentityKey: string;
+    outputIndex: number;
+}
+/** Narrow wallet interface for BEEF acknowledgement (subset of CWIInterface). */
+interface AckWallet {
+    internalizeAction(params: {
+        tx: number[];
+        outputs: Array<{
+            outputIndex: number;
+            protocol: 'wallet payment';
+            paymentRemittance: {
+                derivationPrefix: string;
+                derivationSuffix: string;
+                senderIdentityKey: string;
+            };
+        }>;
+        description: string;
+        labels?: string[];
+    }): Promise<{
+        accepted: boolean;
+    }>;
+}
 interface X402Config {
     proofConstructor?: (challenge: Challenge) => Promise<Proof>;
     brc105ProofConstructor?: Brc105ProofConstructor;
     brc105Wallet?: Brc105Wallet;
+    /** Custom BRC-121 proof constructor. */
+    brc121ProofConstructor?: Brc121ProofConstructor;
+    /** Wallet for BRC-121 payments (reuses Brc105Wallet interface). */
+    brc121Wallet?: Brc105Wallet;
     onProofError?: (error: unknown, protocol: PaymentProtocol) => void;
+    /** Maximum number of retries for network errors during BRC-105 payment (default: 2). */
+    maxRetries?: number;
+    /** Wallet for internalising received BEEFs and enabling ack headers. */
+    ackWallet?: AckWallet;
+    /** Server identity key for paymentRemittance.senderIdentityKey (fallback when not per-entry). */
+    serverIdentityKey?: string;
 }
 interface CWICreateActionOutput {
     satoshis: number;
@@ -129,6 +188,31 @@ declare function parseBrc105Challenge(response: Response): Brc105Challenge;
  */
 declare function constructBrc105Proof(challenge: Brc105Challenge, wallet: Brc105Wallet, origin?: string): Promise<Brc105ProofResult>;
 
+/**
+ * Parses BRC-121 challenge headers from a 402 response.
+ *
+ * Returns `null` when the required headers are absent or when
+ * `x-bsv-payment-version` is present (indicating BRC-105, not BRC-121).
+ *
+ * Throws on malformed values once the headers are confirmed present,
+ * matching the validation pattern of `parseBrc105Challenge`.
+ */
+declare function parseBrc121Challenge(response: Response): Brc121Challenge | null;
+
+/**
+ * Construct a BRC-121 payment proof from a challenge using BRC-29 key derivation.
+ *
+ * Algorithm (matching @bsv/402-pay reference):
+ * 1. Get client's identity key
+ * 2. Generate nonce (derivation prefix): 8 random bytes → base64
+ * 3. Generate derivation suffix: btoa(Date.now().toString())
+ * 4. Derive payee public key using BRC-29 protocol
+ * 5. Build P2PKH locking script from derived public key
+ * 6. Create transaction via wallet with noSend: true
+ * 7. Convert transaction to base64
+ */
+declare function constructBrc121Proof(challenge: Brc121Challenge, wallet: Brc105Wallet, origin?: string): Promise<Brc121ProofResult>;
+
 /**
  * Autospend balance cap per tier (max sats that can be auto-spent without confirmation).
  * Doom II difficulty progression — each tier is 10x the previous.
@@ -169,4 +253,4 @@ declare function clampBalanceToTier(state: AutospendState, config: AutospendConf
  */
 declare function initialState(config: AutospendConfig, walletBalance: number): AutospendState;
 
-export { type AutospendConfig, type AutospendState, type Brc105Challenge, type Brc105Proof, type Brc105ProofConstructor, type Brc105Wallet, type CWICreateActionOutput, type CWICreateActionParams, type CWICreateActionResult, type Challenge, PICKUP_PERCENTAGES, type PaymentDecision, type PaymentProtocol, type PaymentRequest, type PickupName, type Proof, TIER_CAPS, type TierName, WEAPON_CAPS, type WeaponName, type X402Config, type X402FetchFn, applyPickup, checkPayment, clampBalanceToTier, constructBrc105Proof, createX402Fetch, initialState, parseBrc105Challenge, parseChallenge, recordPayment, x402Fetch };
+export { type AckWallet, type AutospendConfig, type AutospendState, type Brc105Challenge, type Brc105Proof, type Brc105ProofConstructor, type Brc105Wallet, type Brc121Challenge, type Brc121Proof, type Brc121ProofConstructor, type Brc121ProofResult, type CWICreateActionOutput, type CWICreateActionParams, type CWICreateActionResult, type Challenge, PICKUP_PERCENTAGES, type PaymentDecision, type PaymentProtocol, type PaymentRequest, type PendingBeef, type PickupName, type Proof, TIER_CAPS, type TierName, WEAPON_CAPS, type WeaponName, type X402Config, type X402FetchFn, applyPickup, checkPayment, clampBalanceToTier, constructBrc105Proof, constructBrc121Proof, createX402Fetch, initialState, parseBrc105Challenge, parseBrc121Challenge, parseChallenge, recordPayment, x402Fetch };

package/dist/index.js

@@ -536,6 +536,96 @@ async function constructBrc105Proof(challenge, wallet, origin) {
   return { proof, abort };
 }
 
+// src/brc121-challenge.ts
+function parseBrc121Challenge(response) {
+  if (response.headers.get("x-bsv-payment-version") !== null) {
+    return null;
+  }
+  const satsHeader = response.headers.get("x-bsv-sats");
+  const serverHeader = response.headers.get("x-bsv-server");
+  if (!satsHeader || !serverHeader) {
+    return null;
+  }
+  const satoshis = Number(satsHeader);
+  if (!Number.isFinite(satoshis) || !Number.isInteger(satoshis) || satoshis <= 0) {
+    throw new Error(`BRC-121: x-bsv-sats must be a positive integer, got "${satsHeader}"`);
+  }
+  if (!/^0[23][0-9a-fA-F]{64}$/.test(serverHeader)) {
+    throw new Error("BRC-121: x-bsv-server must be a 33-byte compressed public key (hex)");
+  }
+  return { satoshis, serverIdentityKey: serverHeader };
+}
+
+// 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 });
+  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);
+  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 transactionBase64;
+  if (result.tx && Array.isArray(result.tx) && result.tx.length > 0) {
+    transactionBase64 = numberArrayToBase642(result.tx);
+  } else if (result.rawTx && typeof result.rawTx === "string" && result.rawTx.length > 0) {
+    transactionBase64 = bytesToBase642(hexToBytes2(result.rawTx));
+  } else {
+    throw new Error("Wallet returned no transaction data (neither tx nor rawTx)");
+  }
+  const proof = {
+    beef: transactionBase64,
+    senderIdentityKey: clientIdentityKey,
+    nonce,
+    time,
+    vout: "0",
+    txid: result.txid
+  };
+  const abort = wallet.abortAction ? async () => {
+    try {
+      await wallet.abortAction({ reference: result.txid });
+    } catch (err) {
+      console.warn("[x402] abortAction failed:", err);
+    }
+  } : void 0;
+  return { proof, abort };
+}
+
 // src/challenge.ts
 function parseChallenge(header) {
   let parsed;
@@ -569,15 +659,15 @@ function parseChallenge(header) {
 }
 
 // src/x402-fetch.ts
-function bytesToBase642(bytes) {
+function bytesToBase643(bytes) {
   let binary = "";
   for (const b of bytes) binary += String.fromCharCode(b);
   return btoa(binary);
 }
-function numberArrayToBase642(arr) {
-  return bytesToBase642(new Uint8Array(arr));
+function numberArrayToBase643(arr) {
+  return bytesToBase643(new Uint8Array(arr));
 }
-function hexToBytes2(hex) {
+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) {
@@ -586,14 +676,14 @@ function hexToBytes2(hex) {
   return bytes;
 }
 var BASE58_ALPHABET = "123456789ABCDEFGHJKLMNPQRSTUVWXYZabcdefghijkmnopqrstuvwxyz";
-function base58DecodeCheck(address) {
+function base58ToBytes(encoded) {
   let leadingZeros = 0;
-  for (const c of address) {
+  for (const c of encoded) {
     if (c === "1") leadingZeros++;
     else break;
   }
   let n = BigInt(0);
-  for (const c of address) {
+  for (const c of encoded) {
     const i = BASE58_ALPHABET.indexOf(c);
     if (i < 0) throw new Error(`Invalid Base58 character: ${c}`);
     n = n * 58n + BigInt(i);
@@ -606,11 +696,14 @@ function base58DecodeCheck(address) {
   }
   const allBytes = new Uint8Array(leadingZeros + bigintBytes.length);
   allBytes.set(bigintBytes, leadingZeros);
+  return allBytes;
+}
+function base58DecodeCheck(address) {
+  const allBytes = base58ToBytes(address);
   if (allBytes.length !== 25) {
     throw new Error(`Invalid address length: expected 25 bytes, got ${allBytes.length}`);
   }
   const body = allBytes.slice(0, 21);
-  const checksum = allBytes.slice(21);
   const version = allBytes[0];
   if (version !== 0 && version !== 111) {
     throw new Error(`Unsupported address version: 0x${version.toString(16).padStart(2, "0")}`);
@@ -650,9 +743,9 @@ async function defaultConstructProof(challenge) {
   }
   let beef;
   if (result.tx && Array.isArray(result.tx) && result.tx.length > 0) {
-    beef = numberArrayToBase642(result.tx);
+    beef = numberArrayToBase643(result.tx);
   } else if (result.rawTx && typeof result.rawTx === "string" && result.rawTx.length > 0) {
-    beef = bytesToBase642(hexToBytes2(result.rawTx));
+    beef = bytesToBase643(hexToBytes3(result.rawTx));
   } else {
     throw new Error("Wallet returned no transaction data (neither tx nor rawTx)");
   }
@@ -665,9 +758,71 @@ function createX402Fetch(config = {}) {
   const constructProof = config.proofConstructor ?? defaultConstructProof;
   const brc105ProofConstructor = config.brc105ProofConstructor;
   const brc105Wallet = config.brc105Wallet;
+  const brc121ProofConstructor = config.brc121ProofConstructor;
+  const brc121Wallet = config.brc121Wallet;
+  const maxRetries = config.maxRetries ?? 2;
+  const ackWallet = config.ackWallet;
+  const serverIdentityKey = config.serverIdentityKey;
+  const ackedTxids = /* @__PURE__ */ new Set();
+  const internalisedTxids = /* @__PURE__ */ new Set();
+  function injectAckHeader(headers) {
+    if (ackedTxids.size > 0) {
+      headers.set("x-bsv-ack", [...ackedTxids].join(","));
+      ackedTxids.clear();
+    }
+  }
+  async function processPendingBeefs(response) {
+    if (!ackWallet) return;
+    let body;
+    try {
+      const clone = response.clone();
+      body = await clone.json();
+    } catch {
+      return;
+    }
+    if (!Array.isArray(body?.pendingBeefs)) return;
+    for (const entry of body.pendingBeefs) {
+      if (!entry?.txid || !entry?.beef) continue;
+      if (!entry.derivationPrefix || !entry.derivationSuffix) continue;
+      if (internalisedTxids.has(entry.txid)) {
+        ackedTxids.add(entry.txid);
+        continue;
+      }
+      const senderKey = entry.senderIdentityKey ?? serverIdentityKey;
+      if (!senderKey) {
+        console.warn(`[x402] Cannot internalise BEEF ${entry.txid}: no senderIdentityKey`);
+        continue;
+      }
+      try {
+        const txBytes = Array.from(atob(entry.beef), (c) => c.charCodeAt(0));
+        await ackWallet.internalizeAction({
+          tx: txBytes,
+          outputs: [{
+            outputIndex: entry.outputIndex ?? 0,
+            protocol: "wallet payment",
+            paymentRemittance: {
+              derivationPrefix: entry.derivationPrefix,
+              derivationSuffix: entry.derivationSuffix,
+              senderIdentityKey: senderKey
+            }
+          }],
+          description: "x402 refund receipt"
+        });
+        internalisedTxids.add(entry.txid);
+        ackedTxids.add(entry.txid);
+      } catch (err) {
+        console.warn(`[x402] Failed to internalise BEEF ${entry.txid}:`, err);
+      }
+    }
+  }
   return async function x402Fetch2(input, init) {
-    const response = await fetch(input, init);
-    if (response.status !== 402) return response;
+    const initialHeaders = new Headers(init?.headers);
+    injectAckHeader(initialHeaders);
+    const response = await fetch(input, { ...init, headers: initialHeaders });
+    if (response.status !== 402) {
+      await processPendingBeefs(response);
+      return response;
+    }
     const origin = extractOrigin(input);
     const challengeHeader = response.headers.get("X402-Challenge");
     if (challengeHeader) {
@@ -687,7 +842,10 @@ function createX402Fetch(config = {}) {
       }
       const headers = new Headers(init?.headers);
       headers.set("X402-Proof", JSON.stringify(proof));
-      return fetch(input, { ...init, headers });
+      injectAckHeader(headers);
+      const retryResp = await fetch(input, { ...init, headers });
+      await processPendingBeefs(retryResp);
+      return retryResp;
     }
     const brc105Version = response.headers.get("x-bsv-payment-version");
     if (brc105Version) {
@@ -698,42 +856,191 @@ function createX402Fetch(config = {}) {
       } catch {
         return response;
       }
+      const buildProof = async () => {
+        if (brc105ProofConstructor) {
+          return brc105ProofConstructor(brc105Challenge);
+        }
+        return constructBrc105Proof(brc105Challenge, brc105Wallet, origin);
+      };
+      const proofHeaders = (proof2) => {
+        const h = new Headers(init?.headers);
+        h.set("x-bsv-payment", JSON.stringify(proof2));
+        h.set("x-bsv-auth-identity-key", proof2.clientIdentityKey);
+        injectAckHeader(h);
+        return h;
+      };
       let proof;
       let abort;
       try {
-        if (brc105ProofConstructor) {
-          const result = await brc105ProofConstructor(brc105Challenge);
-          proof = result.proof;
-          abort = result.abort;
-        } else {
-          const result = await constructBrc105Proof(brc105Challenge, brc105Wallet, origin);
-          proof = result.proof;
-          abort = result.abort;
-        }
+        const result = await buildProof();
+        proof = result.proof;
+        abort = result.abort;
       } catch (err) {
         console.error("[x402] Proof construction failed (brc105):", err);
         config.onProofError?.(err, "brc105");
         return response;
       }
-      const headers = new Headers(init?.headers);
-      headers.set("x-bsv-payment", JSON.stringify(proof));
-      headers.set("x-bsv-auth-identity-key", proof.clientIdentityKey);
       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) });
+          networkError = false;
+          break;
+        } catch {
+          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) {
+        await processPendingBeefs(retryResponse);
+        return retryResponse;
+      }
+      if (abort) {
+        try {
+          await abort();
+          console.warn("[x402] Server rejected BRC-105 payment, UTXOs released via abortAction");
+        } catch (err) {
+          console.warn("[x402] abortAction failed during server rejection:", err);
+        }
+      }
+      let freshProof;
+      let freshAbort;
+      try {
+        const result = await buildProof();
+        freshProof = result.proof;
+        freshAbort = result.abort;
+      } catch (err) {
+        console.error("[x402] Fresh proof construction failed (brc105):", err);
+        config.onProofError?.(err, "brc105");
+        return retryResponse;
+      }
+      let freshResponse;
+      try {
+        freshResponse = await fetch(input, { ...init, headers: proofHeaders(freshProof) });
+      } 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 && freshAbort) {
+        try {
+          await freshAbort();
+          console.warn("[x402] Server rejected fresh BRC-105 payment, UTXOs released via abortAction");
+        } catch (err) {
+          console.warn("[x402] freshAbort failed during double rejection:", err);
+        }
+      }
+      await processPendingBeefs(freshResponse);
+      return freshResponse;
+    }
+    let brc121Challenge;
+    try {
+      brc121Challenge = parseBrc121Challenge(response);
+    } catch {
+      return response;
+    }
+    if (brc121Challenge) {
+      if (!brc121ProofConstructor && !brc121Wallet) {
+        await processPendingBeefs(response);
+        return response;
+      }
+      const buildProof = async () => {
+        if (brc121ProofConstructor) {
+          return brc121ProofConstructor(brc121Challenge);
+        }
+        return constructBrc121Proof(brc121Challenge, brc121Wallet, origin);
+      };
+      const proofHeaders = (proof2) => {
+        const h = new Headers(init?.headers);
+        h.set("x-bsv-beef", proof2.beef);
+        h.set("x-bsv-sender", proof2.senderIdentityKey);
+        h.set("x-bsv-nonce", proof2.nonce);
+        h.set("x-bsv-time", proof2.time);
+        h.set("x-bsv-vout", proof2.vout);
+        injectAckHeader(h);
+        return h;
+      };
+      let proof;
+      let abort;
       try {
-        retryResponse = await fetch(input, { ...init, headers });
+        const result = await buildProof();
+        proof = result.proof;
+        abort = result.abort;
       } catch (err) {
-        if (abort) {
+        console.error("[x402] Proof construction failed (brc121):", err);
+        config.onProofError?.(err, "brc121");
+        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) });
+          networkError = false;
+          break;
+        } catch {
+          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) {
+        await processPendingBeefs(retryResponse);
+        return retryResponse;
+      }
+      if (abort) {
+        try {
           await abort();
-          console.warn("[x402] BRC-105 retry fetch failed, UTXOs released via abortAction");
+          console.warn("[x402] Server rejected BRC-121 payment, UTXOs released via abortAction");
+        } catch (err) {
+          console.warn("[x402] abortAction failed during server rejection:", err);
         }
-        throw err;
       }
-      if (!retryResponse.ok && abort) {
-        await abort();
-        console.warn("[x402] Server rejected BRC-105 payment, UTXOs released via abortAction");
+      let freshProof;
+      let freshAbort;
+      try {
+        const result = await buildProof();
+        freshProof = result.proof;
+        freshAbort = result.abort;
+      } catch (err) {
+        console.error("[x402] Fresh proof construction failed (brc121):", err);
+        config.onProofError?.(err, "brc121");
+        return retryResponse;
+      }
+      let freshResponse;
+      try {
+        freshResponse = await fetch(input, { ...init, headers: proofHeaders(freshProof) });
+      } 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."
+        );
       }
-      return retryResponse;
+      if (!freshResponse.ok && freshAbort) {
+        try {
+          await freshAbort();
+          console.warn("[x402] Server rejected fresh BRC-121 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;
   };
 }
@@ -742,6 +1049,9 @@ async function x402Fetch(input, init) {
   if (!singleton) singleton = createX402Fetch();
   return singleton(input, init);
 }
+function delay(ms) {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}
 function resolveRelativeUrl(url) {
   const loc = globalThis.location;
   if (loc?.href) {
@@ -842,9 +1152,11 @@ export {
   checkPayment,
   clampBalanceToTier,
   constructBrc105Proof,
+  constructBrc121Proof,
   createX402Fetch,
   initialState,
   parseBrc105Challenge,
+  parseBrc121Challenge,
   parseChallenge,
   recordPayment,
   x402Fetch

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "bsv-x402",
-  "version": "0.7.0",
+  "version": "0.8.0",
   "description": "x402 payment protocol client — a fetch() wrapper that handles 402 payment flows transparently",
   "type": "module",
   "main": "dist/index.cjs",