add e2e tests

Author: phdargen

e2e/README.md

@@ -53,6 +53,7 @@ Launches an interactive CLI where you can select:
 - **Clients** - Payment-capable HTTP clients (axios, fetch, httpx, requests, etc.)
 - **Extensions** - Additional features like Bazaar discovery
 - **Protocols** - EVM, SVM, and/or Aptos networks
+- **Payment schemes** (when multiple apply) - `exact`, `upto`, or `batch-settlement`
 
 Every valid combination of your selections will be tested. For example, selecting 2 facilitators, 3 servers, and 2 clients will generate and run all compatible test scenarios.
 
@@ -129,6 +130,13 @@ FACILITATOR_APTOS_PRIVATE_KEY=...   # Aptos private key for facilitator (hex str
 FACILITATOR_STELLAR_PRIVATE_KEY=... # Stellar private key for facilitator
 ```
 
+Optional environment variables (batch-settlement scheme):
+
+```bash
+SERVER_EVM_RECEIVER_AUTHORIZER_PRIVATE_KEY=0x... # server-side self-managed claim/refund signer
+CLIENT_EVM_VOUCHER_SIGNER_PRIVATE_KEY=0x...      # EOA the client uses to sign vouchers 
+```
+
 ### Account Setup Instructions
 
 #### Stellar Testnet

e2e/clients/axios/index.ts

@@ -6,6 +6,7 @@ import { privateKeyToAccount } from "viem/accounts";
 import { base, baseSepolia } from "viem/chains";
 import { ExactEvmScheme, type ExactEvmSchemeOptions } from "@x402/evm/exact/client";
 import { UptoEvmScheme as UptoEvmClientScheme, type UptoEvmSchemeOptions } from "@x402/evm/upto/client";
+import { BatchSettlementEvmScheme } from "@x402/evm/batch-settlement/client";
 import { ExactEvmSchemeV1 } from "@x402/evm/v1";
 import { toClientEvmSigner } from "@x402/evm";
 import { ExactSvmScheme } from "@x402/svm/exact/client";
@@ -49,6 +50,23 @@ const uptoSchemeOptions: UptoEvmSchemeOptions | undefined = process.env.EVM_RPC_
   ? { rpcUrl: process.env.EVM_RPC_URL }
   : undefined;
 
+// Batch-settlement scheme uses a per-scenario salt (CHANNEL_SALT) so concurrent
+// e2e runs don't collide on the same on-chain channel id. An optional voucher
+// signer (EVM_VOUCHER_SIGNER_PRIVATE_KEY) exercises the alt-EOA voucher branch
+// while deposits keep using the main client signer.
+const channelSalt = process.env.CHANNEL_SALT as `0x${string}` | undefined;
+const voucherSignerKey = process.env.EVM_VOUCHER_SIGNER_PRIVATE_KEY as
+  | `0x${string}`
+  | undefined;
+const voucherSigner = voucherSignerKey
+  ? toClientEvmSigner(privateKeyToAccount(voucherSignerKey), publicClient)
+  : undefined;
+const batchSettlementOptions =
+  channelSalt || voucherSigner
+    ? { ...(channelSalt ? { salt: channelSalt } : {}), ...(voucherSigner ? { voucherSigner } : {}) }
+    : undefined;
+const batchSettlementScheme = new BatchSettlementEvmScheme(evmSigner, batchSettlementOptions);
+
 // Initialize Aptos signer if key is provided
 let aptosAccount: Account | undefined;
 if (process.env.APTOS_PRIVATE_KEY) {
@@ -75,6 +93,7 @@ if (process.env.AVM_PRIVATE_KEY) {
 const client = new x402Client()
   .register("eip155:*", new ExactEvmScheme(evmSigner, evmSchemeOptions))
   .register("eip155:*", new UptoEvmClientScheme(evmSigner, uptoSchemeOptions))
+  .register("eip155:*", batchSettlementScheme)
   .registerV1("base-sepolia", new ExactEvmSchemeV1(evmSigner))
   .registerV1("base", new ExactEvmSchemeV1(evmSigner))
   .register("solana:*", new ExactSvmScheme(svmSigner))
@@ -92,44 +111,75 @@ if (avmSigner) {
 
 const axiosWithPayment = wrapAxiosWithPayment(axios.create(), client);
 
-axiosWithPayment
-  .get(url)
-  .then(async (response) => {
-    const data = response.data;
-    // Check both v2 (PAYMENT-RESPONSE) and v1 (X-PAYMENT-RESPONSE) headers
-    const paymentResponse =
-      response.headers["payment-response"] || response.headers["x-payment-response"];
-
-    if (!paymentResponse) {
-      // No payment was required
-      const result = {
-        success: true,
-        data: data,
-        status_code: response.status,
-      };
-      console.log(JSON.stringify(result));
-      process.exit(0);
-      return;
+// Multi-request scenarios (used by batch-settlement) issue several paid requests
+// against the same endpoint so the server can amortise on-chain claims, then
+// optionally signal a cooperative refund on the last request.
+const numberOfRequests = Number.parseInt(process.env.MULTI_REQUEST_COUNT ?? "1", 10);
+const refundOnLastRequest = process.env.REFUND_ON_LAST === "true";
+
+/**
+ * Issues a single paid request and returns the parsed result.
+ *
+ * @returns Structured result with response data and decoded payment-response.
+ */
+async function issueRequest(): Promise<{
+  success: boolean;
+  data: unknown;
+  status_code: number;
+  payment_response?: ReturnType<typeof decodePaymentResponseHeader>;
+}> {
+  const response = await axiosWithPayment.get(url);
+  const paymentResponseHeader =
+    response.headers["payment-response"] || response.headers["x-payment-response"];
+
+  if (!paymentResponseHeader) {
+    return { success: true, data: response.data, status_code: response.status };
+  }
+
+  const decodedPaymentResponse = decodePaymentResponseHeader(paymentResponseHeader);
+  return {
+    success: decodedPaymentResponse.success,
+    data: response.data,
+    status_code: response.status,
+    payment_response: decodedPaymentResponse,
+  };
+}
+
+try {
+  const results: Awaited<ReturnType<typeof issueRequest>>[] = [];
+  let lastChannelId: string | undefined;
+  for (let i = 0; i < numberOfRequests; i++) {
+    const isLast = i === numberOfRequests - 1;
+
+    if (isLast && refundOnLastRequest && lastChannelId) {
+      batchSettlementScheme.requestRefund(lastChannelId);
     }
 
-    const decodedPaymentResponse = decodePaymentResponseHeader(paymentResponse);
-
-    const result = {
-      success: decodedPaymentResponse.success,
-      data: data,
-      status_code: response.status,
-      payment_response: decodedPaymentResponse,
-    };
-
-    // Output structured result as JSON for proxy to parse
-    console.log(JSON.stringify(result));
-    process.exit(0);
-  })
-  .catch((error) => {
-    console.error(JSON.stringify({
+    const result = await issueRequest();
+    results.push(result);
+
+    const channelId = result.payment_response?.extra?.channelId;
+    if (typeof channelId === "string" && channelId.length > 0) {
+      lastChannelId = channelId;
+    }
+  }
+
+  const last = results[results.length - 1]!;
+  const aggregate =
+    numberOfRequests > 1
+      ? { ...last, requests: results, request_count: numberOfRequests }
+      : last;
+
+  console.log(JSON.stringify(aggregate));
+  process.exit(0);
+} catch (error: unknown) {
+  const err = error as { message?: string; response?: { status?: number } };
+  console.error(
+    JSON.stringify({
       success: false,
-      error: error.message || "Request failed",
-      status_code: error.response?.status || 500,
-    }));
-    process.exit(1);
-  });
+      error: err.message || "Request failed",
+      status_code: err.response?.status || 500,
+    }),
+  );
+  process.exit(1);
+}

e2e/clients/axios/test.config.json

@@ -17,7 +17,8 @@
     "transferMethods": [
       "eip3009",
       "permit2",
-      "upto"
+      "upto",
+      "batch-settlement"
     ]
   },
   "extensions": [
@@ -34,7 +35,11 @@
     "optional": [
       "AVM_PRIVATE_KEY",
       "APTOS_PRIVATE_KEY",
-      "STELLAR_PRIVATE_KEY"
+      "STELLAR_PRIVATE_KEY",
+      "CHANNEL_SALT",
+      "MULTI_REQUEST_COUNT",
+      "REFUND_ON_LAST",
+      "EVM_VOUCHER_SIGNER_PRIVATE_KEY"
     ]
   }
 }

e2e/clients/fetch/index.ts

@@ -5,6 +5,7 @@ import { privateKeyToAccount } from "viem/accounts";
 import { base, baseSepolia } from "viem/chains";
 import { ExactEvmScheme, type ExactEvmSchemeOptions } from "@x402/evm/exact/client";
 import { UptoEvmScheme as UptoEvmClientScheme, type UptoEvmSchemeOptions } from "@x402/evm/upto/client";
+import { BatchSettlementEvmScheme } from "@x402/evm/batch-settlement/client";
 import { ExactEvmSchemeV1 } from "@x402/evm/v1";
 import { toClientEvmSigner } from "@x402/evm";
 import { ExactSvmScheme } from "@x402/svm/exact/client";
@@ -46,6 +47,23 @@ const uptoSchemeOptions: UptoEvmSchemeOptions | undefined = process.env.EVM_RPC_
   ? { rpcUrl: process.env.EVM_RPC_URL }
   : undefined;
 
+// Batch-settlement scheme uses a per-scenario salt (CHANNEL_SALT) so concurrent
+// e2e runs don't collide on the same on-chain channel id. An optional voucher
+// signer (EVM_VOUCHER_SIGNER_PRIVATE_KEY) exercises the alt-EOA voucher branch
+// while deposits keep using the main client signer.
+const channelSalt = process.env.CHANNEL_SALT as `0x${string}` | undefined;
+const voucherSignerKey = process.env.EVM_VOUCHER_SIGNER_PRIVATE_KEY as
+  | `0x${string}`
+  | undefined;
+const voucherSigner = voucherSignerKey
+  ? toClientEvmSigner(privateKeyToAccount(voucherSignerKey), publicClient)
+  : undefined;
+const batchSettlementOptions =
+  channelSalt || voucherSigner
+    ? { ...(channelSalt ? { salt: channelSalt } : {}), ...(voucherSigner ? { voucherSigner } : {}) }
+    : undefined;
+const batchSettlementScheme = new BatchSettlementEvmScheme(evmSigner, batchSettlementOptions);
+
 // Initialize Aptos signer if key is provided
 let aptosAccount: Account | undefined;
 if (process.env.APTOS_PRIVATE_KEY) {
@@ -69,6 +87,7 @@ if (process.env.AVM_PRIVATE_KEY) {
 const client = new x402Client()
   .register("eip155:*", new ExactEvmScheme(evmSigner, evmSchemeOptions))
   .register("eip155:*", new UptoEvmClientScheme(evmSigner, uptoSchemeOptions))
+  .register("eip155:*", batchSettlementScheme)
   .registerV1("base-sepolia", new ExactEvmSchemeV1(evmSigner))
   .registerV1("base", new ExactEvmSchemeV1(evmSigner))
   .register("solana:*", new ExactSvmScheme(svmSigner))
@@ -85,33 +104,64 @@ if (avmSigner) {
 }
 
 const fetchWithPayment = wrapFetchWithPayment(fetch, client);
-
-fetchWithPayment(url, {
-  method: "GET",
-}).then(async response => {
+const httpClient = new x402HTTPClient(client);
+
+// Multi-request scenarios (used by batch-settlement) issue several paid requests
+// against the same endpoint so the server can amortise on-chain claims, then
+// optionally signal a cooperative refund on the last request.
+const numberOfRequests = Number.parseInt(process.env.MULTI_REQUEST_COUNT ?? "1", 10);
+const refundOnLastRequest = process.env.REFUND_ON_LAST === "true";
+
+/**
+ * Issues a single paid request and returns the parsed result.
+ *
+ * @returns Structured result with response data and decoded payment-response.
+ */
+async function issueRequest(): Promise<{
+  success: boolean;
+  data: unknown;
+  status_code: number;
+  payment_response?: ReturnType<x402HTTPClient["getPaymentSettleResponse"]>;
+}> {
+  const response = await fetchWithPayment(url, { method: "GET" });
   const data = await response.json();
-  const paymentResponse = new x402HTTPClient(client).getPaymentSettleResponse((name) => response.headers.get(name));
+  const paymentResponse = httpClient.getPaymentSettleResponse(name => response.headers.get(name));
 
   if (!paymentResponse) {
-    // No payment was required
-    const result = {
-      success: true,
-      data: data,
-      status_code: response.status,
-    };
-    console.log(JSON.stringify(result));
-    process.exit(0);
-    return;
+    return { success: true, data, status_code: response.status };
   }
 
-  const result = {
+  return {
     success: paymentResponse.success,
-    data: data,
+    data,
     status_code: response.status,
     payment_response: paymentResponse,
   };
+}
 
-  // Output structured result as JSON for proxy to parse
-  console.log(JSON.stringify(result));
-  process.exit(0);
-});
+const results: Awaited<ReturnType<typeof issueRequest>>[] = [];
+let lastChannelId: string | undefined;
+for (let i = 0; i < numberOfRequests; i++) {
+  const isLast = i === numberOfRequests - 1;
+
+  if (isLast && refundOnLastRequest && lastChannelId) {
+    batchSettlementScheme.requestRefund(lastChannelId);
+  }
+
+  const result = await issueRequest();
+  results.push(result);
+
+  const channelId = result.payment_response?.extra?.channelId;
+  if (typeof channelId === "string" && channelId.length > 0) {
+    lastChannelId = channelId;
+  }
+}
+
+const last = results[results.length - 1]!;
+const aggregate =
+  numberOfRequests > 1
+    ? { ...last, requests: results, request_count: numberOfRequests }
+    : last;
+
+console.log(JSON.stringify(aggregate));
+process.exit(0);

e2e/clients/fetch/test.config.json

@@ -17,7 +17,8 @@
     "transferMethods": [
       "eip3009",
       "permit2",
-      "upto"
+      "upto",
+      "batch-settlement"
     ]
   },
   "extensions": [
@@ -34,7 +35,11 @@
     "optional": [
       "AVM_PRIVATE_KEY",
       "APTOS_PRIVATE_KEY",
-      "STELLAR_PRIVATE_KEY"
+      "STELLAR_PRIVATE_KEY",
+      "CHANNEL_SALT",
+      "MULTI_REQUEST_COUNT",
+      "REFUND_ON_LAST",
+      "EVM_VOUCHER_SIGNER_PRIVATE_KEY"
     ]
   }
 }