x402-bch-axios 1.1.2 → 2.0.0

package/README.md

@@ -4,6 +4,10 @@ JavaScript helpers for handling HTTP 402 responses against Bitcoin Cash powered
 x402 endpoints. This package ports the `withPaymentInterceptor` experience from
 the TypeScript `x402-axios` client and adapts it for BCH UTXO payments.
 
+**Version 2.0+**: This library now supports x402-bch protocol v2, which includes
+CAIP-2 network identifiers, updated header names, and restructured payment payloads.
+Backward compatibility with v1 responses is maintained.
+
 ## Installation
 
 ```bash
@@ -50,11 +54,84 @@ console.log(response.data)
   - waits for a 402 response,
   - selects the BCH `utxo` payment requirement (or uses your selector),
   - funds or reuses a tracked UTXO,
-  - replays the request with the `X-PAYMENT` header.
+  - replays the request with the `PAYMENT-SIGNATURE` header (v2) or `X-PAYMENT` header (v1).
 - `selectPaymentRequirements(accepts)` — utility for filtering BCH
-  requirements.
-- `createPaymentHeader(...)` — exposed for advanced integrations that need
-  direct x402 payload handling.
+  requirements. Supports both v1 (`bch`) and v2 CAIP-2 (`bip122:*`) network formats.
+- `createPaymentHeader(signer, paymentRequirements, x402Version, txid, vout, resource?, extensions?)` — exposed for advanced integrations that need
+  direct x402 payload handling. Returns v2 format by default.
+
+## Protocol Version 2 Changes
+
+This library supports x402-bch protocol v2 with the following changes:
+
+### Header Names
+- **v2**: `PAYMENT-SIGNATURE` (replaces `X-PAYMENT`)
+- **v2**: `PAYMENT-RESPONSE` (replaces `X-PAYMENT-RESPONSE`)
+
+### Network Identifiers
+- **v1**: `bch` (simple string)
+- **v2**: `bip122:000000000000000000651ef99cb9fcbe` (CAIP-2 format for BCH mainnet)
+
+The library automatically detects and supports both formats.
+
+### Payment Payload Structure
+
+**v2 Format:**
+```json
+{
+  "x402Version": 2,
+  "resource": {
+    "url": "http://localhost:4021/weather",
+    "description": "Access to weather data",
+    "mimeType": "application/json"
+  },
+  "accepted": {
+    "scheme": "utxo",
+    "network": "bip122:000000000000000000651ef99cb9fcbe",
+    "amount": "1000",
+    "asset": "0x0000000000000000000000000000000000000001",
+    "payTo": "bitcoincash:...",
+    "maxTimeoutSeconds": 60,
+    "extra": {}
+  },
+  "payload": {
+    "signature": "...",
+    "authorization": {
+      "from": "bitcoincash:...",
+      "to": "bitcoincash:...",
+      "value": "1000",
+      "txid": "...",
+      "vout": 0,
+      "amount": "2000"
+    }
+  },
+  "extensions": {}
+}
+```
+
+**Key differences from v1:**
+- Removed top-level `scheme` and `network` fields
+- Added `accepted` field containing the selected PaymentRequirements
+- Added optional `resource` and `extensions` fields
+- Field name change: `minAmountRequired` → `amount` (library supports both for compatibility)
+
+### Response Parsing
+
+The library supports both v1 and v2 response formats:
+- **v2**: Parses from `PAYMENT-REQUIRED` header (base64-encoded JSON)
+- **v1**: Falls back to response body format
+
+## Migration from v1
+
+If you're upgrading from v1, the library maintains backward compatibility:
+- v1 responses are automatically detected and handled
+- v1 field names (`minAmountRequired`, `bch` network) are supported
+- No code changes required for basic usage
+
+However, for full v2 support:
+- Update your server to send v2 responses
+- Use CAIP-2 network identifiers in payment requirements
+- Expect `PAYMENT-SIGNATURE` and `PAYMENT-RESPONSE` headers
 
 ## Licence
 

package/index.js

@@ -62,15 +62,34 @@ export function createSigner (privateKeyWIF, paymentAmountSats) {
 
 export const createBCHSigner = createSigner
 
+/**
+ * Normalizes network identifier to support both v1 and v2 formats.
+ * v1 uses 'bch', v2 uses CAIP-2 format 'bip122:000000000000000000651ef99cb9fcbe'
+ *
+ * @param {string} network - Network identifier
+ * @returns {boolean} True if the network is BCH (mainnet)
+ */
+function isBCHNetwork (network) {
+  if (!network) return false
+  // v1 format
+  if (network === 'bch') return true
+  // v2 CAIP-2 format for BCH mainnet
+  if (network === 'bip122:000000000000000000651ef99cb9fcbe') return true
+  // v2 CAIP-2 format pattern matching (bip122:*)
+  if (network.startsWith('bip122:')) return true
+  return false
+}
+
 /**
  * Selects BCH `utxo` payment requirements from a 402 accepts array.
+ * Supports both v1 ('bch') and v2 (CAIP-2 'bip122:*') network formats.
  *
  * @param {Array} accepts - Array of payment requirements objects
  * @returns {Object} First BCH `utxo` payment requirement
  */
 export function selectPaymentRequirements (accepts = []) {
   const bchRequirements = accepts.filter(req => {
-    return req?.network === 'bch' && req?.scheme === 'utxo'
+    return isBCHNetwork(req?.network) && req?.scheme === 'utxo'
   })
 
   if (bchRequirements.length === 0) {
@@ -81,26 +100,33 @@ export function selectPaymentRequirements (accepts = []) {
 }
 
 /**
- * Builds the X-PAYMENT header payload for BCH transfers.
+ * Builds the PAYMENT-SIGNATURE header payload for BCH transfers.
  *
  * @param {ReturnType<typeof createSigner>} signer
  * @param {Object} paymentRequirements
  * @param {number} x402Version
  * @param {string|null} txid
  * @param {number|null} vout
+ * @param {Object|null} resource - Optional ResourceInfo object
+ * @param {Object|null} extensions - Optional extensions object
  * @returns {Promise<string>}
  */
 export async function createPaymentHeader (
   signer,
   paymentRequirements,
-  x402Version = 1,
+  x402Version = 2,
   txid = null,
-  vout = null
+  vout = null,
+  resource = null,
+  extensions = null
 ) {
+  // Support both v1 (minAmountRequired) and v2 (amount) field names
+  const amountRequired = paymentRequirements.amount || paymentRequirements.minAmountRequired
+
   const authorization = {
     from: signer.address,
     to: paymentRequirements.payTo,
-    value: paymentRequirements.minAmountRequired,
+    value: amountRequired,
     txid,
     vout,
     amount: signer.paymentAmountSats
@@ -109,14 +135,27 @@ export async function createPaymentHeader (
   const messageToSign = JSON.stringify(authorization)
   const signature = signer.signMessage(messageToSign)
 
+  // Build accepted PaymentRequirements object
+  const accepted = {
+    scheme: paymentRequirements.scheme || 'utxo',
+    network: paymentRequirements.network || 'bip122:000000000000000000651ef99cb9fcbe',
+    amount: amountRequired,
+    asset: paymentRequirements.asset,
+    payTo: paymentRequirements.payTo,
+    maxTimeoutSeconds: paymentRequirements.maxTimeoutSeconds,
+    extra: paymentRequirements.extra || {}
+  }
+
+  // Build v2 PaymentPayload structure
   const paymentHeader = {
     x402Version,
-    scheme: paymentRequirements.scheme || 'utxo',
-    network: paymentRequirements.network || 'bch',
+    ...(resource && { resource }),
+    accepted,
     payload: {
       signature,
       authorization
-    }
+    },
+    ...(extensions && { extensions })
   }
 
   return JSON.stringify(paymentHeader)
@@ -124,7 +163,9 @@ export async function createPaymentHeader (
 
 async function sendPayment (signer, paymentRequirements, bchServerConfig = {}) {
   const { apiType, bchServerURL } = bchServerConfig
-  const paymentAmountSats = signer.paymentAmountSats || paymentRequirements.minAmountRequired
+  // Support both v1 (minAmountRequired) and v2 (amount) field names
+  const amountRequired = paymentRequirements.amount || paymentRequirements.minAmountRequired
+  const paymentAmountSats = signer.paymentAmountSats || amountRequired
 
   const bchWallet = new dependencies.BCHWallet(signer.wif, {
     interface: apiType,
@@ -195,13 +236,46 @@ export function withPaymentInterceptor (
           return Promise.reject(error)
         }
 
-        const { x402Version, accepts } = error.response.data || {}
+        // Parse payment requirements - v2 can come from header, v1 from body
+        let paymentRequired = null
+        let x402Version = 1
+        let accepts = []
+        let resource = null
+        let extensions = null
+
+        // Try v2 PAYMENT-REQUIRED header first (base64-encoded)
+        const paymentRequiredHeader = error.response.headers['payment-required'] ||
+                                      error.response.headers['PAYMENT-REQUIRED']
+        if (paymentRequiredHeader) {
+          try {
+            const decoded = Buffer.from(paymentRequiredHeader, 'base64').toString('utf-8')
+            paymentRequired = JSON.parse(decoded)
+            x402Version = paymentRequired.x402Version || 2
+            accepts = paymentRequired.accepts || []
+            resource = paymentRequired.resource
+            extensions = paymentRequired.extensions
+          } catch (parseError) {
+            // If header parsing fails, fall back to body
+          }
+        }
+
+        // Fall back to body format (v1 or v2)
+        if (!paymentRequired) {
+          const body = error.response.data || {}
+          x402Version = body.x402Version || 1
+          accepts = body.accepts || []
+          resource = body.resource
+          extensions = body.extensions
+        }
+
         if (!accepts || !Array.isArray(accepts) || accepts.length === 0) {
           return Promise.reject(new Error('No payment requirements found in 402 response'))
         }
 
         const paymentRequirements = paymentRequirementsSelector(accepts)
-        const cost = paymentRequirements.minAmountRequired
+        // Support both v1 (minAmountRequired) and v2 (amount) field names
+        // Convert to number for calculations (v2 uses strings, v1 uses numbers)
+        const cost = Number(paymentRequirements.amount || paymentRequirements.minAmountRequired)
 
         let txid = null
         let vout = null
@@ -229,14 +303,16 @@ export function withPaymentInterceptor (
         const paymentHeader = await createPaymentHeader(
           signer,
           paymentRequirements,
-          x402Version || 1,
+          x402Version || 2,
           txid,
-          vout
+          vout,
+          resource,
+          extensions
         )
 
         originalConfig.__is402Retry = true
-        originalConfig.headers['X-PAYMENT'] = paymentHeader
-        originalConfig.headers['Access-Control-Expose-Headers'] = 'X-PAYMENT-RESPONSE'
+        originalConfig.headers['PAYMENT-SIGNATURE'] = paymentHeader
+        originalConfig.headers['Access-Control-Expose-Headers'] = 'PAYMENT-RESPONSE'
 
         const secondResponse = await axiosInstance.request(originalConfig)
         return secondResponse

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "x402-bch-axios",
-  "version": "1.1.2",
+  "version": "2.0.0",
   "description": "Axios wrapper for x402 payment protocol with Bitcoin Cash (BCH) support.",
   "main": "index.js",
   "type": "module",

package/test/unit/index-unit.js

@@ -73,7 +73,7 @@ describe('#index.js', () => {
   })
 
   describe('#selectPaymentRequirements', () => {
-    it('should select the first BCH utxo requirement', () => {
+    it('should select the first BCH utxo requirement (v1 format)', () => {
       const accepts = [
         { network: 'eth', scheme: 'account' },
         { network: 'bch', scheme: 'utxo', payTo: 'addr1' },
@@ -84,6 +84,17 @@ describe('#index.js', () => {
       assert.deepEqual(req, { network: 'bch', scheme: 'utxo', payTo: 'addr1' })
     })
 
+    it('should select the first BCH utxo requirement (v2 CAIP-2 format)', () => {
+      const accepts = [
+        { network: 'eip155:84532', scheme: 'exact' },
+        { network: 'bip122:000000000000000000651ef99cb9fcbe', scheme: 'utxo', payTo: 'addr1' },
+        { network: 'bch', scheme: 'utxo', payTo: 'addr2' }
+      ]
+
+      const req = selectPaymentRequirements(accepts)
+      assert.deepEqual(req, { network: 'bip122:000000000000000000651ef99cb9fcbe', scheme: 'utxo', payTo: 'addr1' })
+    })
+
     it('should throw if no BCH utxo requirement exists', () => {
       assert.throws(
         () => selectPaymentRequirements([{ network: 'btc', scheme: 'utxo' }]),
@@ -93,7 +104,7 @@ describe('#index.js', () => {
   })
 
   describe('#createPaymentHeader', () => {
-    it('should build a valid payment header payload', async () => {
+    it('should build a valid v2 payment header payload', async () => {
       const signer = {
         address: 'bitcoincash:qptest',
         paymentAmountSats: 2000,
@@ -102,9 +113,18 @@ describe('#index.js', () => {
 
       const paymentRequirements = {
         payTo: 'bitcoincash:qprecv',
-        minAmountRequired: 1500,
+        amount: '1500',
         scheme: 'utxo',
-        network: 'bch'
+        network: 'bip122:000000000000000000651ef99cb9fcbe',
+        asset: '0x0000000000000000000000000000000000000001',
+        maxTimeoutSeconds: 60,
+        extra: {}
+      }
+
+      const resource = {
+        url: 'http://localhost:4021/weather',
+        description: 'Access to weather data',
+        mimeType: 'application/json'
       }
 
       const header = await createPaymentHeader(
@@ -112,28 +132,65 @@ describe('#index.js', () => {
         paymentRequirements,
         2,
         'tx123',
-        0
+        0,
+        resource
       )
 
       const parsed = JSON.parse(header)
-      assert.deepEqual(parsed, {
-        x402Version: 2,
+      assert.equal(parsed.x402Version, 2)
+      assert.deepEqual(parsed.resource, resource)
+      assert.deepEqual(parsed.accepted, {
         scheme: 'utxo',
-        network: 'bch',
-        payload: {
-          signature: 'mock-signature',
-          authorization: {
-            from: 'bitcoincash:qptest',
-            to: 'bitcoincash:qprecv',
-            value: 1500,
-            txid: 'tx123',
-            vout: 0,
-            amount: 2000
-          }
+        network: 'bip122:000000000000000000651ef99cb9fcbe',
+        amount: '1500',
+        asset: '0x0000000000000000000000000000000000000001',
+        payTo: 'bitcoincash:qprecv',
+        maxTimeoutSeconds: 60,
+        extra: {}
+      })
+      assert.deepEqual(parsed.payload, {
+        signature: 'mock-signature',
+        authorization: {
+          from: 'bitcoincash:qptest',
+          to: 'bitcoincash:qprecv',
+          value: '1500',
+          txid: 'tx123',
+          vout: 0,
+          amount: 2000
         }
       })
+      // v2 should not have top-level scheme/network
+      assert.isUndefined(parsed.scheme)
+      assert.isUndefined(parsed.network)
       assert.isTrue(signer.signMessage.calledOnce)
     })
+
+    it('should support v1 minAmountRequired field for backward compatibility', async () => {
+      const signer = {
+        address: 'bitcoincash:qptest',
+        paymentAmountSats: 2000,
+        signMessage: sandbox.stub().returns('mock-signature')
+      }
+
+      const paymentRequirements = {
+        payTo: 'bitcoincash:qprecv',
+        minAmountRequired: 1500, // v1 field name
+        scheme: 'utxo',
+        network: 'bch'
+      }
+
+      const header = await createPaymentHeader(
+        signer,
+        paymentRequirements,
+        2,
+        'tx123',
+        0
+      )
+
+      const parsed = JSON.parse(header)
+      assert.equal(parsed.accepted.amount, 1500)
+      assert.equal(parsed.payload.authorization.value, 1500)
+    })
   })
 
   describe('#withPaymentInterceptor', () => {
@@ -157,19 +214,31 @@ describe('#index.js', () => {
     }
 
     const basePaymentRequirements = {
-      network: 'bch',
+      network: 'bip122:000000000000000000651ef99cb9fcbe',
       scheme: 'utxo',
       payTo: 'bitcoincash:qprecv',
-      minAmountRequired: 1500
+      amount: '1500',
+      asset: '0x0000000000000000000000000000000000000001',
+      maxTimeoutSeconds: 60,
+      extra: {}
+    }
+
+    const baseResource = {
+      url: 'http://localhost:4021/weather',
+      description: 'Access to weather data',
+      mimeType: 'application/json'
     }
 
     function create402Error (overrides = {}) {
       const defaultError = {
         response: {
           status: 402,
+          headers: {},
           data: {
-            x402Version: 1,
-            accepts: [cloneDeep(basePaymentRequirements)]
+            x402Version: 2,
+            resource: cloneDeep(baseResource),
+            accepts: [cloneDeep(basePaymentRequirements)],
+            extensions: {}
           }
         },
         config: {
@@ -223,14 +292,16 @@ describe('#index.js', () => {
 
       const [, errorHandler] = axiosInstance.interceptors.response.use.firstCall.args
       const error = create402Error({
-        response: { status: 402, data: { accepts: [] } }
+        response: { status: 402, headers: {}, data: { accepts: [] } }
       })
 
       try {
         await errorHandler(error)
         assert.fail('Expected rejection')
       } catch (err) {
-        assert.match(err.message, /No payment requirements/)
+        // Should reject with "No payment requirements found in 402 response"
+        // or "No BCH payment requirements found in 402 response" from selector
+        assert.match(err.message, /No.*payment requirements/)
       }
     })
 
@@ -259,14 +330,16 @@ describe('#index.js', () => {
 
       const updatedConfig = axiosInstance.request.firstCall.args[0]
       assert.isTrue(updatedConfig.__is402Retry)
-      assert.property(updatedConfig.headers, 'X-PAYMENT')
+      assert.property(updatedConfig.headers, 'PAYMENT-SIGNATURE')
       assert.propertyVal(
         updatedConfig.headers,
         'Access-Control-Expose-Headers',
-        'X-PAYMENT-RESPONSE'
+        'PAYMENT-RESPONSE'
       )
 
-      const headerPayload = JSON.parse(updatedConfig.headers['X-PAYMENT'])
+      const headerPayload = JSON.parse(updatedConfig.headers['PAYMENT-SIGNATURE'])
+      assert.equal(headerPayload.x402Version, 2)
+      assert.deepEqual(headerPayload.accepted, basePaymentRequirements)
       assert.equal(headerPayload.payload.authorization.txid, 'tx123')
       assert.equal(__internals.currentUtxo.txid, 'tx123')
       assert.equal(__internals.currentUtxo.satsLeft, 500)
@@ -298,5 +371,97 @@ describe('#index.js', () => {
       assert.equal(__internals.currentUtxo.txid, 'cached')
       assert.equal(__internals.currentUtxo.satsLeft, 500)
     })
+
+    it('should parse v2 response from PAYMENT-REQUIRED header', async () => {
+      const axiosInstance = createAxiosInstance()
+      const signer = createSignerStub()
+      signer.signMessage.returns('signed')
+
+      const sendPaymentStub = sandbox
+        .stub()
+        .resolves({ txid: 'tx123', vout: 0, satsSent: 2000 })
+      __internals.sendPayment = sendPaymentStub
+
+      axiosInstance.request.resolves({ data: 'ok' })
+
+      withPaymentInterceptor(axiosInstance, signer)
+
+      const [, errorHandler] = axiosInstance.interceptors.response.use.firstCall.args
+
+      // Create v2 response with PAYMENT-REQUIRED header
+      const paymentRequired = {
+        x402Version: 2,
+        resource: baseResource,
+        accepts: [cloneDeep(basePaymentRequirements)],
+        extensions: {}
+      }
+      const headerValue = Buffer.from(JSON.stringify(paymentRequired)).toString('base64')
+
+      const error = {
+        response: {
+          status: 402,
+          headers: {
+            'payment-required': headerValue
+          },
+          data: {}
+        },
+        config: {
+          headers: {}
+        }
+      }
+
+      const response = await errorHandler(error)
+
+      assert.deepEqual(response, { data: 'ok' })
+      assert.isTrue(sendPaymentStub.calledOnce)
+      assert.isTrue(axiosInstance.request.calledOnce)
+
+      const updatedConfig = axiosInstance.request.firstCall.args[0]
+      const headerPayload = JSON.parse(updatedConfig.headers['PAYMENT-SIGNATURE'])
+      assert.equal(headerPayload.x402Version, 2)
+      assert.deepEqual(headerPayload.resource, baseResource)
+    })
+
+    it('should support v1 response format for backward compatibility', async () => {
+      const axiosInstance = createAxiosInstance()
+      const signer = createSignerStub()
+      signer.signMessage.returns('signed')
+
+      const sendPaymentStub = sandbox
+        .stub()
+        .resolves({ txid: 'tx123', vout: 0, satsSent: 2000 })
+      __internals.sendPayment = sendPaymentStub
+
+      axiosInstance.request.resolves({ data: 'ok' })
+
+      withPaymentInterceptor(axiosInstance, signer)
+
+      const [, errorHandler] = axiosInstance.interceptors.response.use.firstCall.args
+
+      // Create v1 response format
+      const error = {
+        response: {
+          status: 402,
+          headers: {},
+          data: {
+            x402Version: 1,
+            accepts: [{
+              network: 'bch',
+              scheme: 'utxo',
+              payTo: 'bitcoincash:qprecv',
+              minAmountRequired: 1500
+            }]
+          }
+        },
+        config: {
+          headers: {}
+        }
+      }
+
+      const response = await errorHandler(error)
+
+      assert.deepEqual(response, { data: 'ok' })
+      assert.isTrue(sendPaymentStub.calledOnce)
+    })
   })
 })