Scope facilitator memo to V2 in 2.0.2

README.md

@@ -317,6 +317,10 @@ import {
   getDefaultSBTCContract,
   networkToCAIP2,
   caip2ToNetwork,
+  createFacilitatorNonce,
+  createFacilitatorMemo,
+  isFacilitatorMemo,
+  parsePaymentMemo,
 } from 'x402-stacks';
 
 // Convert amounts
@@ -425,6 +429,31 @@ app.get('/api/market-data/:tier',
 );
 ```
 
+## Facilitator Memo Convention (V2)
+
+When the SDK signs a facilitator-bound transaction in the default V2 flow, it writes the memo before signing using:
+
+```text
+x402:<24-char-base64url-nonce>
+```
+
+- STX transfers store the memo in the transaction memo field.
+- sBTC and USDCx transfers store the same value in the SIP-010 optional memo argument.
+- Legacy V1 flows keep their existing memo behavior and do not use this convention automatically.
+- The prefix is intended for analytics and transaction attribution only.
+- The prefix is not cryptographic proof that the facilitator handled the payment.
+
+The SDK exports the following helpers from the root module:
+
+```ts
+import {
+  createFacilitatorNonce,
+  createFacilitatorMemo,
+  isFacilitatorMemo,
+  parsePaymentMemo,
+} from 'x402-stacks';
+```
+
 ## sBTC Support
 
 x402-stacks supports **sBTC** (Bitcoin on Stacks) for payments in addition to STX! sBTC is a 1:1 Bitcoin-backed asset on Stacks, allowing users to pay with Bitcoin while leveraging Stacks' fast settlement.

jest.config.cjs

@@ -0,0 +1,7 @@
+module.exports = {
+  preset: 'ts-jest',
+  testEnvironment: 'node',
+  roots: ['<rootDir>/test'],
+  moduleFileExtensions: ['ts', 'js', 'json'],
+  clearMocks: true,
+};

package.json

@@ -1,6 +1,6 @@
 {
   "name": "x402-stacks",
-  "version": "2.0.1",
+  "version": "2.0.3",
   "description": "TypeScript library for implementing x402 payment protocol on Stacks blockchain",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
@@ -9,7 +9,7 @@
     "dev": "tsc --watch",
     "dev:server": "ts-node examples/server.ts",
     "dev:client": "ts-node examples/client.ts",
-    "test": "jest",
+    "test": "jest --runInBand",
     "prepublishOnly": "npm run build"
   },
   "keywords": [
@@ -38,15 +38,18 @@
   "dependencies": {
     "@stacks/transactions": "^6.13.0",
     "@stacks/network": "^6.13.0",
-    "axios": "^1.6.0"
+    "axios": "1.15.2"
   },
   "devDependencies": {
-    "@types/node": "^20.0.0",
     "@types/express": "^4.17.0",
-    "typescript": "^5.3.0",
-    "ts-node": "^10.9.0",
+    "@types/jest": "^29.5.14",
+    "@types/node": "^20.0.0",
+    "dotenv": "^16.3.0",
     "express": "^4.18.0",
-    "dotenv": "^16.3.0"
+    "jest": "^29.7.0",
+    "ts-jest": "^29.2.5",
+    "ts-node": "^10.9.0",
+    "typescript": "^5.3.0"
   },
   "peerDependencies": {
     "express": "^4.18.0"

src/client.ts

@@ -30,6 +30,7 @@ import {
   TokenType,
 } from './types';
 
+
 /**
  * Payment client for making x402 payments on Stacks
  */

src/index.ts

@@ -172,6 +172,9 @@ export {
   formatPaymentAmount,
   parsePaymentMemo,
   createPaymentMemo,
+  createFacilitatorNonce,
+  createFacilitatorMemo,
+  isFacilitatorMemo,
   estimateFee,
 
   // Timing utilities

src/interceptor-v2.ts

@@ -28,7 +28,7 @@ import {
   STACKS_NETWORKS,
   NetworkV2,
 } from './types-v2';
-import { networkFromCAIP2, assetFromV2 } from './utils';
+import { networkFromCAIP2, assetFromV2, createFacilitatorMemo, createFacilitatorNonce } from './utils';
 
 /**
  * Create a Stacks account from a private key
@@ -133,8 +133,7 @@ async function signPaymentV2(
   const network = getNetworkInstanceFromCAIP2(paymentRequirements.network);
   const v1Network = networkFromCAIP2(paymentRequirements.network);
 
-  // Generate a short memo (max 34 bytes for Stacks)
-  const memo = `x402:${Date.now().toString(36)}`.substring(0, 34);
+  const memo = createFacilitatorMemo(createFacilitatorNonce());
 
   if (tokenType === 'sBTC' || tokenType === 'USDCx') {
     // SIP-010 token transfer

src/interceptor.ts

@@ -26,6 +26,7 @@ import {
   NetworkType,
 } from './types';
 
+
 /**
  * Create a Stacks account from a private key (V1)
  * @deprecated Use privateKeyToAccount from the main exports instead

src/middleware.ts

@@ -4,13 +4,13 @@
  * Note: For new projects, use paymentMiddleware from middleware-v2.ts
  */
 
+import { randomBytes } from 'crypto';
 import { Request, Response, NextFunction } from 'express';
 import { X402PaymentVerifierV1, SettleOptionsV1 } from './verifier';
 import {
   X402MiddlewareConfig,
   X402PaymentRequired,
 } from './types';
-import { randomBytes } from 'crypto';
 
 /**
  * Express middleware for x402 V1 payment requirements

src/utils.ts

@@ -3,11 +3,50 @@
  * Helper functions for working with x402 payments on Stacks
  */
 
+import { createHash, randomBytes } from 'crypto';
 import { makeRandomPrivKey, getPublicKey, publicKeyToAddress, AddressVersion } from '@stacks/transactions';
 import { StacksMainnet, StacksTestnet } from '@stacks/network';
 import { NetworkType, TokenType, TokenContract } from './types';
 import { NetworkV2, STACKS_NETWORKS } from './types-v2';
 
+const FACILITATOR_MEMO_PREFIX = 'x402:';
+const FACILITATOR_NONCE_BYTES = 18;
+const STACKS_MEMO_MAX_BYTES = 34;
+const FACILITATOR_NONCE_PATTERN = /^[A-Za-z0-9_-]{24}$/;
+
+function normalizeFacilitatorNonce(nonce: string): string {
+  if (FACILITATOR_NONCE_PATTERN.test(nonce)) {
+    return nonce;
+  }
+
+  return createHash('sha256')
+    .update(nonce)
+    .digest()
+    .subarray(0, FACILITATOR_NONCE_BYTES)
+    .toString('base64url');
+}
+
+export function createFacilitatorNonce(
+  generator: (size: number) => Buffer = randomBytes
+): string {
+  return generator(FACILITATOR_NONCE_BYTES).toString('base64url');
+}
+
+export function createFacilitatorMemo(nonce: string): string {
+  const memo = `${FACILITATOR_MEMO_PREFIX}${normalizeFacilitatorNonce(nonce)}`;
+
+  if (Buffer.byteLength(memo, 'utf8') > STACKS_MEMO_MAX_BYTES) {
+    throw new Error('Facilitator memo exceeds the 34-byte Stacks memo limit');
+  }
+
+  return memo;
+}
+
+export function isFacilitatorMemo(memo: string): boolean {
+  return memo.startsWith(FACILITATOR_MEMO_PREFIX)
+    && FACILITATOR_NONCE_PATTERN.test(memo.substring(FACILITATOR_MEMO_PREFIX.length));
+}
+
 /**
  * Convert microSTX to STX
  */
@@ -162,27 +201,37 @@ export function parsePaymentMemo(memo: string): {
     custom?: Record<string, string>;
   } = {};
 
-  if (!memo.startsWith('x402:')) {
+  if (!memo.startsWith(FACILITATOR_MEMO_PREFIX)) {
     return result;
   }
 
-  // Remove x402: prefix
-  const content = memo.substring(5);
+  const content = memo.substring(FACILITATOR_MEMO_PREFIX.length);
+
+  if (!content.includes('=')) {
+    if (!FACILITATOR_NONCE_PATTERN.test(content)) {
+      return result;
+    }
+
+    result.nonce = content;
+    return result;
+  }
 
-  // Split by comma
   const parts = content.split(',');
 
-  for (const part of parts) {
+  for (const [index, part] of parts.entries()) {
+    if (!part.includes('=') && index === 0) {
+      result.resource = part;
+      continue;
+    }
+
     const [key, value] = part.split('=');
     if (key && value) {
       if (key === 'resource') {
         result.resource = value;
       } else if (key === 'nonce') {
         result.nonce = value;
       } else {
-        if (!result.custom) {
-          result.custom = {};
-        }
+        result.custom = result.custom || {};
         result.custom[key] = value;
       }
     }

src/verifier-v2.ts

@@ -44,7 +44,7 @@ export class X402PaymentVerifier {
     this.facilitatorUrl = facilitatorUrl.replace(/\/$/, ''); // Remove trailing slash
 
     this.httpClient = axios.create({
-      timeout: 30000, // V2 may need longer timeout for settlement
+      timeout: 50000, // V2 settlement can take longer while facilitator confirms
       headers: {
         'Content-Type': 'application/json',
       },

test/interceptor-v2.memo.test.ts

@@ -0,0 +1,120 @@
+jest.mock('@stacks/network', () => ({
+  StacksMainnet: class { url = 'https://stacks-node-api.mainnet.stacks.co'; },
+  StacksTestnet: class { url = 'https://stacks-node-api.testnet.stacks.co'; },
+}));
+
+import type { AxiosInstance } from 'axios';
+import { wrapAxiosWithPayment, X402_HEADERS } from '../src';
+
+const mockMakeSTXTokenTransfer = jest.fn();
+const mockMakeContractCall = jest.fn();
+const mockBufferCVFromString = jest.fn((value: string) => value);
+const mockSomeCV = jest.fn((value: unknown) => ({ type: 'some', value }));
+
+jest.mock('@stacks/transactions', () => ({
+  makeSTXTokenTransfer: (opts: any) => mockMakeSTXTokenTransfer(opts),
+  makeContractCall: (opts: any) => mockMakeContractCall(opts),
+  AnchorMode: { Any: 3 },
+  PostConditionMode: { Allow: 1 },
+  uintCV: (value: string) => value,
+  principalCV: (value: string) => value,
+  someCV: (value: any) => mockSomeCV(value),
+  noneCV: () => ({ type: 'none' }),
+  bufferCVFromString: (value: string) => mockBufferCVFromString(value),
+  getAddressFromPrivateKey: () => 'ST2J6ZY48GV1EZ5V2V5RB9MP66SW86PYKKNRV9EJ7',
+  TransactionVersion: { Mainnet: 0, Testnet: 1 },
+}));
+
+function createAxiosHarness() {
+  let rejected!: (error: any) => Promise<any>;
+
+  const instance = {
+    interceptors: {
+      response: {
+        use: (_fulfilled: unknown, onRejected: typeof rejected) => {
+          rejected = onRejected;
+          return 0;
+        },
+      },
+    },
+    request: jest.fn().mockResolvedValue({ status: 200, data: { ok: true } }),
+  } as unknown as AxiosInstance & { request: jest.Mock };
+
+  wrapAxiosWithPayment(instance, {
+    address: 'ST2J6ZY48GV1EZ5V2V5RB9MP66SW86PYKKNRV9EJ7',
+    privateKey: '1'.repeat(64),
+    network: 'testnet',
+  });
+
+  return { instance, rejected };
+}
+
+describe('wrapAxiosWithPayment facilitator memo', () => {
+  beforeEach(() => {
+    mockMakeSTXTokenTransfer.mockResolvedValue({ serialize: () => Uint8Array.from([0xde, 0xad]) });
+    mockMakeContractCall.mockResolvedValue({ serialize: () => Uint8Array.from([0xca, 0xfe]) });
+  });
+
+  it('signs STX retries with an x402-prefixed memo', async () => {
+    const { rejected } = createAxiosHarness();
+
+    const paymentRequired = {
+      x402Version: 2,
+      resource: { url: 'https://api.example.com/premium' },
+      accepts: [{
+        scheme: 'exact',
+        network: 'stacks:2147483648',
+        amount: '1000',
+        asset: 'STX',
+        payTo: 'ST1PQHQKV0RJXZFY1DGX8MNSNYVE3VGZJSRTPGZGM',
+        maxTimeoutSeconds: 300,
+      }],
+    };
+
+    await rejected({
+      config: { headers: {} },
+      response: {
+        status: 402,
+        headers: {
+          [X402_HEADERS.PAYMENT_REQUIRED]: Buffer.from(JSON.stringify(paymentRequired)).toString('base64'),
+        },
+        data: null,
+      },
+    });
+
+    expect(mockMakeSTXTokenTransfer).toHaveBeenCalledWith(expect.objectContaining({
+      memo: expect.stringMatching(/^x402:[A-Za-z0-9_-]{24}$/),
+    }));
+  });
+
+  it('passes the same memo pattern into SIP-010 contract calls', async () => {
+    const { rejected } = createAxiosHarness();
+
+    const paymentRequired = {
+      x402Version: 2,
+      resource: { url: 'https://api.example.com/premium' },
+      accepts: [{
+        scheme: 'exact',
+        network: 'stacks:2147483648',
+        amount: '1000',
+        asset: 'SBTC',
+        payTo: 'ST1PQHQKV0RJXZFY1DGX8MNSNYVE3VGZJSRTPGZGM',
+        maxTimeoutSeconds: 300,
+      }],
+    };
+
+    await rejected({
+      config: { headers: {} },
+      response: {
+        status: 402,
+        headers: {
+          [X402_HEADERS.PAYMENT_REQUIRED]: Buffer.from(JSON.stringify(paymentRequired)).toString('base64'),
+        },
+        data: null,
+      },
+    });
+
+    expect(mockBufferCVFromString).toHaveBeenCalledWith(expect.stringMatching(/^x402:[A-Za-z0-9_-]{24}$/));
+    expect(mockSomeCV).toHaveBeenCalled();
+  });
+});