x402z-client 0.0.1

package/README.md

@@ -0,0 +1,47 @@
+# x402z-client
+
+Client-side helpers for the erc7984-mind-v1 x402 scheme.
+
+## Install
+
+```bash
+pnpm add x402z-client x402z-shared
+```
+
+## Usage
+
+```ts
+import { createX402zClient } from "x402z-client";
+import { createRelayerInstance, SepoliaConfig } from "x402z-shared";
+import { privateKeyToAccount } from "viem/accounts";
+
+const account = privateKeyToAccount("0x...");
+const relayer = await createRelayerInstance(SepoliaConfig);
+
+const client = createX402zClient({
+  signer: {
+    address: account.address,
+    signTypedData: account.signTypedData,
+  },
+  relayer,
+});
+
+const response = await client.pay("https://example.com/demo");
+console.log(response.status);
+```
+
+`createX402zClient` builds the confidential payment input automatically using the
+`confidential.facilitatorAddress` provided by the server’s payment requirements.
+
+## API
+
+- `createX402zClient(config)`
+  - `signer` (required): EIP-712 signer for x402 payloads
+  - `relayer` (required): Zama relayer instance used to build encrypted inputs
+  - `fetch` (optional): custom fetch implementation
+- `client.pay(url, options?)`: performs the 402 handshake and retries with payment headers
+
+## Notes
+
+- Scheme name: `erc7984-mind-v1`
+- The client does not expose balance helpers; use `x402z-shared` for that.

package/dist/index.d.mts

@@ -0,0 +1,46 @@
+import { SchemeNetworkClient, PaymentRequirements, PaymentPayload, Network } from '@x402/core/types';
+export * from '@x402/core/types';
+import { ClientEvmSigner } from '@x402/evm';
+import { ConfidentialPaymentInput, RelayerInstance } from 'x402z-shared';
+import { x402Client } from '@x402/core/client';
+export { AfterPaymentCreationHook, BeforePaymentCreationHook, OnPaymentCreationFailureHook, PaymentCreatedContext, PaymentCreationContext, PaymentCreationFailureContext, PaymentPolicy, SchemeRegistration, SelectPaymentRequirements, x402Client, x402ClientConfig, x402HTTPClient } from '@x402/core/client';
+
+type ConfidentialClientConfig = {
+    signer: ClientEvmSigner;
+    buildPayment: (requirements: PaymentRequirements) => ConfidentialPaymentInput | Promise<ConfidentialPaymentInput>;
+    eip712?: {
+        name: string;
+        version: string;
+    };
+    hashEncryptedAmountInput?: (encryptedAmountInput: `0x${string}`) => `0x${string}`;
+    clock?: () => number;
+};
+declare class ConfidentialEvmScheme implements SchemeNetworkClient {
+    private readonly config;
+    readonly scheme = "erc7984-mind-v1";
+    private readonly hashFn;
+    private readonly clock;
+    constructor(config: ConfidentialClientConfig);
+    createPaymentPayload(x402Version: number, paymentRequirements: PaymentRequirements): Promise<Pick<PaymentPayload, "x402Version" | "payload">>;
+}
+
+type ConfidentialClientRegisterConfig = ConfidentialClientConfig & {
+    networks?: Network[];
+};
+declare function registerConfidentialEvmScheme(client: x402Client, config: ConfidentialClientRegisterConfig): x402Client;
+
+declare function buildPaymentInputFromRelayer(relayer: RelayerInstance, requirements: PaymentRequirements, amount: number): Promise<ConfidentialPaymentInput>;
+
+type X402zClientConfig = Omit<ConfidentialClientRegisterConfig, "buildPayment"> & {
+    relayer: RelayerInstance;
+    fetch?: typeof fetch;
+    debug?: boolean;
+};
+type PayOptions = {
+    headers?: Record<string, string>;
+};
+declare function createX402zClient(config: X402zClientConfig): {
+    pay(url: string, options?: PayOptions): Promise<Response>;
+};
+
+export { type ConfidentialClientConfig, type ConfidentialClientRegisterConfig, ConfidentialEvmScheme, type PayOptions, type X402zClientConfig, buildPaymentInputFromRelayer, createX402zClient, registerConfidentialEvmScheme };

package/dist/index.d.ts

@@ -0,0 +1,46 @@
+import { SchemeNetworkClient, PaymentRequirements, PaymentPayload, Network } from '@x402/core/types';
+export * from '@x402/core/types';
+import { ClientEvmSigner } from '@x402/evm';
+import { ConfidentialPaymentInput, RelayerInstance } from 'x402z-shared';
+import { x402Client } from '@x402/core/client';
+export { AfterPaymentCreationHook, BeforePaymentCreationHook, OnPaymentCreationFailureHook, PaymentCreatedContext, PaymentCreationContext, PaymentCreationFailureContext, PaymentPolicy, SchemeRegistration, SelectPaymentRequirements, x402Client, x402ClientConfig, x402HTTPClient } from '@x402/core/client';
+
+type ConfidentialClientConfig = {
+    signer: ClientEvmSigner;
+    buildPayment: (requirements: PaymentRequirements) => ConfidentialPaymentInput | Promise<ConfidentialPaymentInput>;
+    eip712?: {
+        name: string;
+        version: string;
+    };
+    hashEncryptedAmountInput?: (encryptedAmountInput: `0x${string}`) => `0x${string}`;
+    clock?: () => number;
+};
+declare class ConfidentialEvmScheme implements SchemeNetworkClient {
+    private readonly config;
+    readonly scheme = "erc7984-mind-v1";
+    private readonly hashFn;
+    private readonly clock;
+    constructor(config: ConfidentialClientConfig);
+    createPaymentPayload(x402Version: number, paymentRequirements: PaymentRequirements): Promise<Pick<PaymentPayload, "x402Version" | "payload">>;
+}
+
+type ConfidentialClientRegisterConfig = ConfidentialClientConfig & {
+    networks?: Network[];
+};
+declare function registerConfidentialEvmScheme(client: x402Client, config: ConfidentialClientRegisterConfig): x402Client;
+
+declare function buildPaymentInputFromRelayer(relayer: RelayerInstance, requirements: PaymentRequirements, amount: number): Promise<ConfidentialPaymentInput>;
+
+type X402zClientConfig = Omit<ConfidentialClientRegisterConfig, "buildPayment"> & {
+    relayer: RelayerInstance;
+    fetch?: typeof fetch;
+    debug?: boolean;
+};
+type PayOptions = {
+    headers?: Record<string, string>;
+};
+declare function createX402zClient(config: X402zClientConfig): {
+    pay(url: string, options?: PayOptions): Promise<Response>;
+};
+
+export { type ConfidentialClientConfig, type ConfidentialClientRegisterConfig, ConfidentialEvmScheme, type PayOptions, type X402zClientConfig, buildPaymentInputFromRelayer, createX402zClient, registerConfidentialEvmScheme };

package/dist/index.js

@@ -0,0 +1,219 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/index.ts
+var index_exports = {};
+__export(index_exports, {
+  ConfidentialEvmScheme: () => ConfidentialEvmScheme,
+  buildPaymentInputFromRelayer: () => buildPaymentInputFromRelayer,
+  createX402zClient: () => createX402zClient,
+  registerConfidentialEvmScheme: () => registerConfidentialEvmScheme,
+  x402Client: () => import_client2.x402Client,
+  x402HTTPClient: () => import_client2.x402HTTPClient
+});
+module.exports = __toCommonJS(index_exports);
+
+// src/scheme.ts
+var import_viem = require("viem");
+var import_x402z_shared = require("x402z-shared");
+var ZERO_BYTES32 = "0x0000000000000000000000000000000000000000000000000000000000000000";
+var ConfidentialEvmScheme = class {
+  constructor(config) {
+    this.config = config;
+    this.scheme = "erc7984-mind-v1";
+    this.hashFn = config.hashEncryptedAmountInput ?? import_x402z_shared.hashEncryptedAmountInput;
+    this.clock = config.clock ?? (() => Math.floor(Date.now() / 1e3));
+  }
+  async createPaymentPayload(x402Version, paymentRequirements) {
+    const input = await this.config.buildPayment(paymentRequirements);
+    const extra = paymentRequirements.extra;
+    const eip712 = extra?.eip712 ?? this.config.eip712;
+    if (!eip712?.name || !eip712?.version) {
+      throw new Error("Missing EIP-712 domain parameters (name, version) in requirements or config");
+    }
+    const now = this.clock();
+    const validAfter = input.validAfter ?? Math.max(0, now - 60);
+    const validBefore = input.validBefore ?? now + paymentRequirements.maxTimeoutSeconds;
+    const nonce = input.nonce ?? (0, import_x402z_shared.createNonce)();
+    const maxClearAmount = input.maxClearAmount ?? extra?.confidential?.maxClearAmount ?? (0, import_x402z_shared.normalizeAmount)(paymentRequirements.amount);
+    const resourceHash = input.resourceHash ?? extra?.confidential?.resourceHash ?? ZERO_BYTES32;
+    const authorization = {
+      holder: this.config.signer.address,
+      payee: (0, import_viem.getAddress)(paymentRequirements.payTo),
+      maxClearAmount,
+      resourceHash,
+      validAfter: (0, import_x402z_shared.normalizeAmount)(validAfter),
+      validBefore: (0, import_x402z_shared.normalizeAmount)(validBefore),
+      nonce,
+      encryptedAmountHash: this.hashFn(input.encryptedAmountInput)
+    };
+    const chainId = parseInt(paymentRequirements.network.split(":")[1]);
+    const signature = await this.config.signer.signTypedData({
+      domain: {
+        name: eip712.name,
+        version: eip712.version,
+        chainId,
+        verifyingContract: (0, import_viem.getAddress)(paymentRequirements.asset)
+      },
+      types: import_x402z_shared.confidentialPaymentTypes,
+      primaryType: "ConfidentialPayment",
+      message: {
+        holder: (0, import_viem.getAddress)(authorization.holder),
+        payee: (0, import_viem.getAddress)(authorization.payee),
+        maxClearAmount: BigInt(authorization.maxClearAmount),
+        resourceHash: authorization.resourceHash,
+        validAfter: BigInt(authorization.validAfter),
+        validBefore: BigInt(authorization.validBefore),
+        nonce: authorization.nonce,
+        encryptedAmountHash: authorization.encryptedAmountHash
+      }
+    });
+    const payload = {
+      authorization,
+      signature,
+      encryptedAmountInput: input.encryptedAmountInput,
+      inputProof: input.inputProof
+    };
+    return {
+      x402Version,
+      payload
+    };
+  }
+};
+
+// src/register.ts
+function registerConfidentialEvmScheme(client, config) {
+  if (config.networks && config.networks.length > 0) {
+    for (const network of config.networks) {
+      client.register(network, new ConfidentialEvmScheme(config));
+    }
+    return client;
+  }
+  client.register("eip155:*", new ConfidentialEvmScheme(config));
+  return client;
+}
+
+// src/relayer.ts
+var import_x402z_shared2 = require("x402z-shared");
+async function buildPaymentInputFromRelayer(relayer, requirements, amount) {
+  const extra = requirements.extra;
+  const facilitatorAddress = extra?.confidential?.facilitatorAddress;
+  if (!facilitatorAddress) {
+    throw new Error("Missing confidential.facilitatorAddress in payment requirements");
+  }
+  const encrypted = await (0, import_x402z_shared2.createEncryptedAmountInput)(
+    relayer,
+    requirements.asset,
+    facilitatorAddress,
+    amount
+  );
+  return {
+    encryptedAmountInput: encrypted.handle,
+    inputProof: encrypted.inputProof
+  };
+}
+
+// src/http.ts
+var import_client = require("@x402/core/client");
+var import_http = require("@x402/core/http");
+var import_viem2 = require("viem");
+var import_x402z_shared3 = require("x402z-shared");
+function createX402zClient(config) {
+  const { fetch: fetchOverride, ...registerConfig } = config;
+  const fetchFn = fetchOverride ?? globalThis.fetch;
+  const debugEnabled = config.debug ?? process.env.X402Z_DEBUG === "1";
+  if (!fetchFn) {
+    throw new Error("fetch is not available; provide a fetch implementation");
+  }
+  const buildPayment = async (requirements) => {
+    if (!(0, import_viem2.isAddress)(requirements.asset)) {
+      throw new Error(`Invalid TOKEN_ADDRESS from requirements: ${requirements.asset}`);
+    }
+    const extra = requirements.extra;
+    const facilitatorAddress = extra?.confidential?.facilitatorAddress;
+    if (!facilitatorAddress) {
+      throw new Error("Missing confidential.facilitatorAddress in payment requirements");
+    }
+    const encrypted = await (0, import_x402z_shared3.createEncryptedAmountInput)(
+      config.relayer,
+      requirements.asset,
+      facilitatorAddress,
+      Number(requirements.amount)
+    );
+    return {
+      encryptedAmountInput: encrypted.handle,
+      inputProof: encrypted.inputProof
+    };
+  };
+  const client = new import_client.x402Client();
+  registerConfidentialEvmScheme(client, {
+    ...registerConfig,
+    buildPayment
+  });
+  const httpClient = new import_http.x402HTTPClient(client);
+  return {
+    async pay(url, options) {
+      const initial = await fetchFn(url, { headers: options?.headers });
+      if (initial.status !== 402) {
+        return initial;
+      }
+      const paymentRequired = httpClient.getPaymentRequiredResponse(
+        (name) => initial.headers.get(name),
+        await initial.json().catch(() => ({}))
+      );
+      const payload = await httpClient.createPaymentPayload(paymentRequired);
+      const payHeaders = httpClient.encodePaymentSignatureHeader(payload);
+      if (debugEnabled) {
+        console.debug("[x402z-client] payment payload", payload);
+        console.debug("[x402z-client] payment headers", payHeaders);
+      }
+      const mergedHeaders = { ...options?.headers ?? {}, ...payHeaders };
+      const paidResponse = await fetchFn(url, { headers: mergedHeaders });
+      if (debugEnabled) {
+        try {
+          const body = await paidResponse.clone().text();
+          console.debug("[x402z-client] response", {
+            status: paidResponse.status,
+            headers: Object.fromEntries(paidResponse.headers.entries()),
+            body
+          });
+        } catch (error) {
+          console.debug("[x402z-client] response", {
+            status: paidResponse.status,
+            headers: Object.fromEntries(paidResponse.headers.entries()),
+            body: "<unavailable>"
+          });
+        }
+      }
+      return paidResponse;
+    }
+  };
+}
+
+// src/index.ts
+var import_client2 = require("@x402/core/client");
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  ConfidentialEvmScheme,
+  buildPaymentInputFromRelayer,
+  createX402zClient,
+  registerConfidentialEvmScheme,
+  x402Client,
+  x402HTTPClient
+});

package/dist/index.mjs

@@ -0,0 +1,197 @@
+// src/scheme.ts
+import { getAddress } from "viem";
+import {
+  confidentialPaymentTypes,
+  createNonce,
+  hashEncryptedAmountInput,
+  normalizeAmount
+} from "x402z-shared";
+var ZERO_BYTES32 = "0x0000000000000000000000000000000000000000000000000000000000000000";
+var ConfidentialEvmScheme = class {
+  constructor(config) {
+    this.config = config;
+    this.scheme = "erc7984-mind-v1";
+    this.hashFn = config.hashEncryptedAmountInput ?? hashEncryptedAmountInput;
+    this.clock = config.clock ?? (() => Math.floor(Date.now() / 1e3));
+  }
+  async createPaymentPayload(x402Version, paymentRequirements) {
+    const input = await this.config.buildPayment(paymentRequirements);
+    const extra = paymentRequirements.extra;
+    const eip712 = extra?.eip712 ?? this.config.eip712;
+    if (!eip712?.name || !eip712?.version) {
+      throw new Error("Missing EIP-712 domain parameters (name, version) in requirements or config");
+    }
+    const now = this.clock();
+    const validAfter = input.validAfter ?? Math.max(0, now - 60);
+    const validBefore = input.validBefore ?? now + paymentRequirements.maxTimeoutSeconds;
+    const nonce = input.nonce ?? createNonce();
+    const maxClearAmount = input.maxClearAmount ?? extra?.confidential?.maxClearAmount ?? normalizeAmount(paymentRequirements.amount);
+    const resourceHash = input.resourceHash ?? extra?.confidential?.resourceHash ?? ZERO_BYTES32;
+    const authorization = {
+      holder: this.config.signer.address,
+      payee: getAddress(paymentRequirements.payTo),
+      maxClearAmount,
+      resourceHash,
+      validAfter: normalizeAmount(validAfter),
+      validBefore: normalizeAmount(validBefore),
+      nonce,
+      encryptedAmountHash: this.hashFn(input.encryptedAmountInput)
+    };
+    const chainId = parseInt(paymentRequirements.network.split(":")[1]);
+    const signature = await this.config.signer.signTypedData({
+      domain: {
+        name: eip712.name,
+        version: eip712.version,
+        chainId,
+        verifyingContract: getAddress(paymentRequirements.asset)
+      },
+      types: confidentialPaymentTypes,
+      primaryType: "ConfidentialPayment",
+      message: {
+        holder: getAddress(authorization.holder),
+        payee: getAddress(authorization.payee),
+        maxClearAmount: BigInt(authorization.maxClearAmount),
+        resourceHash: authorization.resourceHash,
+        validAfter: BigInt(authorization.validAfter),
+        validBefore: BigInt(authorization.validBefore),
+        nonce: authorization.nonce,
+        encryptedAmountHash: authorization.encryptedAmountHash
+      }
+    });
+    const payload = {
+      authorization,
+      signature,
+      encryptedAmountInput: input.encryptedAmountInput,
+      inputProof: input.inputProof
+    };
+    return {
+      x402Version,
+      payload
+    };
+  }
+};
+
+// src/register.ts
+function registerConfidentialEvmScheme(client, config) {
+  if (config.networks && config.networks.length > 0) {
+    for (const network of config.networks) {
+      client.register(network, new ConfidentialEvmScheme(config));
+    }
+    return client;
+  }
+  client.register("eip155:*", new ConfidentialEvmScheme(config));
+  return client;
+}
+
+// src/relayer.ts
+import { createEncryptedAmountInput } from "x402z-shared";
+async function buildPaymentInputFromRelayer(relayer, requirements, amount) {
+  const extra = requirements.extra;
+  const facilitatorAddress = extra?.confidential?.facilitatorAddress;
+  if (!facilitatorAddress) {
+    throw new Error("Missing confidential.facilitatorAddress in payment requirements");
+  }
+  const encrypted = await createEncryptedAmountInput(
+    relayer,
+    requirements.asset,
+    facilitatorAddress,
+    amount
+  );
+  return {
+    encryptedAmountInput: encrypted.handle,
+    inputProof: encrypted.inputProof
+  };
+}
+
+// src/http.ts
+import { x402Client } from "@x402/core/client";
+import { x402HTTPClient } from "@x402/core/http";
+import { isAddress } from "viem";
+import {
+  createEncryptedAmountInput as createEncryptedAmountInput2
+} from "x402z-shared";
+function createX402zClient(config) {
+  const { fetch: fetchOverride, ...registerConfig } = config;
+  const fetchFn = fetchOverride ?? globalThis.fetch;
+  const debugEnabled = config.debug ?? process.env.X402Z_DEBUG === "1";
+  if (!fetchFn) {
+    throw new Error("fetch is not available; provide a fetch implementation");
+  }
+  const buildPayment = async (requirements) => {
+    if (!isAddress(requirements.asset)) {
+      throw new Error(`Invalid TOKEN_ADDRESS from requirements: ${requirements.asset}`);
+    }
+    const extra = requirements.extra;
+    const facilitatorAddress = extra?.confidential?.facilitatorAddress;
+    if (!facilitatorAddress) {
+      throw new Error("Missing confidential.facilitatorAddress in payment requirements");
+    }
+    const encrypted = await createEncryptedAmountInput2(
+      config.relayer,
+      requirements.asset,
+      facilitatorAddress,
+      Number(requirements.amount)
+    );
+    return {
+      encryptedAmountInput: encrypted.handle,
+      inputProof: encrypted.inputProof
+    };
+  };
+  const client = new x402Client();
+  registerConfidentialEvmScheme(client, {
+    ...registerConfig,
+    buildPayment
+  });
+  const httpClient = new x402HTTPClient(client);
+  return {
+    async pay(url, options) {
+      const initial = await fetchFn(url, { headers: options?.headers });
+      if (initial.status !== 402) {
+        return initial;
+      }
+      const paymentRequired = httpClient.getPaymentRequiredResponse(
+        (name) => initial.headers.get(name),
+        await initial.json().catch(() => ({}))
+      );
+      const payload = await httpClient.createPaymentPayload(paymentRequired);
+      const payHeaders = httpClient.encodePaymentSignatureHeader(payload);
+      if (debugEnabled) {
+        console.debug("[x402z-client] payment payload", payload);
+        console.debug("[x402z-client] payment headers", payHeaders);
+      }
+      const mergedHeaders = { ...options?.headers ?? {}, ...payHeaders };
+      const paidResponse = await fetchFn(url, { headers: mergedHeaders });
+      if (debugEnabled) {
+        try {
+          const body = await paidResponse.clone().text();
+          console.debug("[x402z-client] response", {
+            status: paidResponse.status,
+            headers: Object.fromEntries(paidResponse.headers.entries()),
+            body
+          });
+        } catch (error) {
+          console.debug("[x402z-client] response", {
+            status: paidResponse.status,
+            headers: Object.fromEntries(paidResponse.headers.entries()),
+            body: "<unavailable>"
+          });
+        }
+      }
+      return paidResponse;
+    }
+  };
+}
+
+// src/index.ts
+import {
+  x402Client as x402Client2,
+  x402HTTPClient as x402HTTPClient2
+} from "@x402/core/client";
+export {
+  ConfidentialEvmScheme,
+  buildPaymentInputFromRelayer,
+  createX402zClient,
+  registerConfidentialEvmScheme,
+  x402Client2 as x402Client,
+  x402HTTPClient2 as x402HTTPClient
+};

package/package.json

@@ -0,0 +1,25 @@
+{
+  "name": "x402z-client",
+  "version": "0.0.1",
+  "main": "./dist/index.js",
+  "module": "./dist/index.mjs",
+  "types": "./dist/index.d.ts",
+  "files": [
+    "dist"
+  ],
+  "dependencies": {
+    "@x402/core": "^2.0.0",
+    "@x402/evm": "^2.0.0",
+    "viem": "^2.39.3",
+    "x402z-shared": "0.0.1"
+  },
+  "devDependencies": {
+    "jest": "^29.7.0",
+    "ts-jest": "^29.2.5",
+    "@types/jest": "^29.5.12"
+  },
+  "scripts": {
+    "build": "tsup src/index.ts --format cjs,esm --dts",
+    "test": "jest"
+  }
+}