@parallel-protocol/x402 0.5.0

package/dist/chunk-W3SMR5LQ.cjs

@@ -0,0 +1,465 @@
+'use strict';
+
+var zod = require('zod');
+var chains = require('@parallel-protocol/chains');
+
+// src/errors.ts
+var X402_ERROR_CODES = {
+  FACILITATOR_UNAVAILABLE: "FACILITATOR_UNAVAILABLE",
+  FACILITATOR_INVALID_RESPONSE: "FACILITATOR_INVALID_RESPONSE",
+  INVALID_PAYMENT: "INVALID_PAYMENT"
+};
+var X402ConfigError = class extends Error {
+  constructor(message, cause) {
+    super(message);
+    this.name = "X402ConfigError";
+    this.cause = cause;
+  }
+};
+var X402RuntimeError = class extends Error {
+  constructor(code) {
+    super(code);
+    this.code = code;
+    this.name = "X402RuntimeError";
+  }
+  code;
+};
+
+// src/utils.ts
+var EIP155_NETWORKS = {
+  ethereum: "eip155:1",
+  base: "eip155:8453",
+  avalanche: "eip155:43114",
+  hyperevm: "eip155:999"
+};
+function parseDecimalAmount(amount, decimals) {
+  const multiplier = 10n ** BigInt(decimals);
+  const parts = amount.split(".");
+  const whole = parts[0] ?? "0";
+  const fraction = (parts[1] ?? "").padEnd(decimals, "0").slice(0, decimals);
+  return BigInt(whole) * multiplier + BigInt(fraction || "0");
+}
+function parsePrice(price, decimals = 18) {
+  if (typeof price === "bigint") return price;
+  const match = price.match(/^(\d+(?:\.\d+)?)$/);
+  if (match?.[1]) return parseDecimalAmount(match[1], decimals);
+  throw new Error(
+    `Invalid price format: "${price}". Expected "0.01" or a bigint.`
+  );
+}
+function validateAddress(address) {
+  return /^0x[0-9a-fA-F]{40}$/.test(address);
+}
+function toEip155Network(network) {
+  if (network.startsWith("eip155:")) return network;
+  return EIP155_NETWORKS[network] ?? `eip155:${network}`;
+}
+function encodeBase64(obj) {
+  return Buffer.from(JSON.stringify(obj)).toString("base64");
+}
+function decodeBase64(str) {
+  return JSON.parse(Buffer.from(str, "base64").toString("utf8"));
+}
+function matchRoute(path, routes) {
+  if (routes[path]) return routes[path];
+  let bestMatch;
+  let bestLength = 0;
+  for (const [pattern, config] of Object.entries(routes)) {
+    if (path.startsWith(`${pattern}/`) && pattern.length > bestLength) {
+      bestMatch = config;
+      bestLength = pattern.length;
+    }
+  }
+  return bestMatch;
+}
+var ethereumAddressSchema = zod.z.string().regex(/^0x[0-9a-fA-F]{40}$/, "Invalid Ethereum address");
+var txHashSchema = zod.z.string().regex(/^0x[0-9a-fA-F]{64}$/);
+var priceSchema = zod.z.union([
+  zod.z.bigint().positive("Price must be greater than 0"),
+  zod.z.string().regex(/^\d+(?:\.\d+)?$/, 'Price must be in format "0.01"').refine((price) => Number(price) > 0, "Price must be greater than 0")
+]);
+var facilitatorConfigSchema = zod.z.object({
+  url: zod.z.string().refine((v) => URL.canParse(v), "Invalid facilitator URL"),
+  apiKey: zod.z.string().optional()
+});
+var routeConfigSchema = zod.z.object({
+  price: priceSchema,
+  network: zod.z.string().min(1, "Network is required"),
+  payTo: ethereumAddressSchema,
+  acceptedTokens: zod.z.array(ethereumAddressSchema).optional(),
+  description: zod.z.string().optional()
+});
+var paymentMiddlewareConfigSchema = zod.z.object({
+  facilitator: facilitatorConfigSchema,
+  routes: zod.z.record(zod.z.string(), routeConfigSchema).refine((r) => Object.keys(r).length > 0, "At least one route is required")
+});
+var facilitatorResponseSchema = zod.z.discriminatedUnion("success", [
+  zod.z.object({
+    success: zod.z.literal(true),
+    txHash: txHashSchema,
+    route: zod.z.string(),
+    chain: zod.z.string(),
+    gasSponsored: zod.z.boolean(),
+    networkId: zod.z.string()
+  }),
+  zod.z.object({
+    success: zod.z.literal(false),
+    error: zod.z.object({
+      code: zod.z.string(),
+      message: zod.z.string(),
+      hint: zod.z.string().optional()
+    })
+  })
+]);
+var verifyResponseSchema = zod.z.object({
+  isValid: zod.z.literal(true)
+});
+var settleSuccessSchema = zod.z.object({
+  txHash: txHashSchema,
+  route: zod.z.string(),
+  gasSponsored: zod.z.boolean()
+});
+var settleErrorSchema = zod.z.object({
+  error: zod.z.string(),
+  message: zod.z.string()
+});
+var settleResponseSchema = zod.z.union([
+  settleSuccessSchema,
+  settleErrorSchema
+]);
+
+// src/client.ts
+var FACILITATOR_TIMEOUT_MS = 1e4;
+var SETTLE_TIMEOUT_MS = 6e4;
+function decodePaymentHeader(paymentHeader) {
+  try {
+    return decodeBase64(paymentHeader);
+  } catch {
+    throw new X402RuntimeError(X402_ERROR_CODES.INVALID_PAYMENT);
+  }
+}
+var FacilitatorClient = class {
+  constructor(config) {
+    this.config = config;
+  }
+  config;
+  async verify(paymentHeader, paymentRequirements) {
+    const paymentPayload = decodePaymentHeader(paymentHeader);
+    let json;
+    try {
+      const response = await fetch(`${this.config.url}/x402/verify`, {
+        method: "POST",
+        headers: this.buildHeaders(),
+        body: JSON.stringify({ paymentPayload, paymentRequirements }),
+        signal: AbortSignal.timeout(FACILITATOR_TIMEOUT_MS)
+      });
+      if (!response.ok) {
+        const errorBody = await response.json().catch(() => null);
+        const code = errorBody?.error ?? X402_ERROR_CODES.FACILITATOR_UNAVAILABLE;
+        throw new X402RuntimeError(code);
+      }
+      json = await response.json();
+    } catch (e) {
+      if (e instanceof X402RuntimeError) throw e;
+      throw new X402RuntimeError(X402_ERROR_CODES.FACILITATOR_UNAVAILABLE);
+    }
+    try {
+      verifyResponseSchema.parse(json);
+    } catch {
+      throw new X402RuntimeError(X402_ERROR_CODES.FACILITATOR_INVALID_RESPONSE);
+    }
+  }
+  async settle(paymentHeader, paymentRequirements) {
+    const paymentPayload = decodePaymentHeader(paymentHeader);
+    let json;
+    try {
+      const response = await fetch(`${this.config.url}/x402/settle`, {
+        method: "POST",
+        headers: this.buildHeaders(),
+        body: JSON.stringify({ paymentPayload, paymentRequirements }),
+        signal: AbortSignal.timeout(SETTLE_TIMEOUT_MS)
+      });
+      if (!response.ok) {
+        const errorBody = await response.json().catch(() => null);
+        const code = errorBody?.error ?? "SUBMISSION_FAILED";
+        const message = errorBody?.message ?? "Settlement failed";
+        return { success: false, error: { code, message } };
+      }
+      json = await response.json();
+    } catch (e) {
+      if (e instanceof X402RuntimeError) throw e;
+      throw new X402RuntimeError(X402_ERROR_CODES.FACILITATOR_UNAVAILABLE);
+    }
+    try {
+      const parsed = settleResponseSchema.parse(json);
+      if ("txHash" in parsed) {
+        return {
+          success: true,
+          txHash: parsed.txHash,
+          route: parsed.route,
+          chain: paymentRequirements.network,
+          gasSponsored: parsed.gasSponsored,
+          networkId: toEip155Network(paymentRequirements.network)
+        };
+      }
+      return {
+        success: false,
+        error: { code: parsed.error, message: parsed.message }
+      };
+    } catch {
+      throw new X402RuntimeError(X402_ERROR_CODES.FACILITATOR_INVALID_RESPONSE);
+    }
+  }
+  async pay(paymentHeader) {
+    const headers = this.buildHeaders();
+    headers["X-PAYMENT"] = paymentHeader;
+    let json;
+    try {
+      const response = await fetch(`${this.config.url}/x402/pay`, {
+        method: "POST",
+        headers,
+        signal: AbortSignal.timeout(FACILITATOR_TIMEOUT_MS)
+      });
+      if (!response.ok) {
+        throw new X402RuntimeError(X402_ERROR_CODES.FACILITATOR_UNAVAILABLE);
+      }
+      json = await response.json();
+    } catch (e) {
+      if (e instanceof X402RuntimeError) throw e;
+      throw new X402RuntimeError(X402_ERROR_CODES.FACILITATOR_UNAVAILABLE);
+    }
+    try {
+      return facilitatorResponseSchema.parse(json);
+    } catch {
+      throw new X402RuntimeError(X402_ERROR_CODES.FACILITATOR_INVALID_RESPONSE);
+    }
+  }
+  buildHeaders() {
+    const headers = {
+      "Content-Type": "application/json"
+    };
+    if (this.config.apiKey) {
+      headers["X-API-Key"] = this.config.apiKey;
+    }
+    return headers;
+  }
+};
+var PARALLEL_TOKENS = {
+  ethereum: {
+    usdp: "0x9B3a8f7CEC208e247d97dEE13313690977e24459",
+    susdp: "0x0d45b129dc868963025Db79A9074EA9c9e32Cae4",
+    usdc: "0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48",
+    frxUSD: "0xCAcd6fd266aF91b8AeD52aCCc382b4e165586E29",
+    sfrxUSD: "0xcf62F905562626CfcDD2261162a51fd02Fc9c5b6",
+    USDe: "0x4c9EDD5852cd905f086C759E8383e09bff1E68B3",
+    sUSDe: "0x9D39A5DE30e57443BfF2A8307A4256c8797A3497"
+  },
+  base: {
+    usdp: "0x76A9A0062ec6712b99B4f63bD2b4270185759dd5",
+    susdp: "0x472eD57b376fE400259FB28e5C46eB53f0E3e7E7",
+    usdc: "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913",
+    USDS: "0x820C137fa70C8691f0e44Dc420a5e53c168921Dc",
+    sUSDS: "0x5875eEE11Cf8398102FdAd704C9E96607675467a"
+  },
+  avalanche: {
+    usdp: "0x9eE1963f05553eF838604Dd39403be21ceF26AA4",
+    susdp: "0x9d92c21205383651610f90722131655a5b8ed3e0",
+    usdc: "0xB97EF9Ef8734C71904D8002F8b6Bc66Dd9c48a6E",
+    ygamiUSDC: "0x9fD32FD5e32C6B95483d36C5E724C5C5250Ce010"
+  },
+  hyperevm: {
+    usdp: "0xBE65F0F410A72BeC163dC65d46c83699e957D588",
+    susdp: "0x9B3a8f7CEC208e247d97dEE13313690977e24459",
+    usdc: "0xb88339cb7199b77e23db6e890353e22632ba630f",
+    USDe: "0x5d3a1Ff2b6BAb83b63cd9AD0787074081a52ef34",
+    sUSDe: "0x211Cc4DD073734dA055fbF44a2b4667d5E5fE5d2"
+  }
+};
+function getDefaultAcceptedTokens(network) {
+  const entry = PARALLEL_TOKENS[network];
+  if (!entry) return void 0;
+  return [entry.usdp, entry.usdc, entry.susdp];
+}
+function getTokenDecimals(network, address) {
+  return chains.getTokenDecimals(network, address);
+}
+
+// src/middleware.ts
+function resolveAcceptedTokens(config) {
+  if (config.acceptedTokens?.length) {
+    return config.acceptedTokens;
+  }
+  const defaults = getDefaultAcceptedTokens(config.network);
+  if (defaults) return defaults;
+  throw new X402ConfigError(
+    `acceptedTokens is required for network "${config.network}" \u2014 no defaults available for this chain`
+  );
+}
+function resolveDecimals(config, asset) {
+  const decimals = config.decimals ?? getTokenDecimals(config.network, asset);
+  if (decimals === void 0) {
+    throw new X402ConfigError(
+      `Unknown decimals for token ${asset} on "${config.network}" \u2014 add it to the @parallel-protocol/chains catalog or set the route's \`decimals\` explicitly`
+    );
+  }
+  return decimals;
+}
+function buildPaymentRequired(url, config, resolvedTokens) {
+  const network = toEip155Network(config.network);
+  const accepts = resolvedTokens.map((asset) => {
+    const decimals = resolveDecimals(config, asset);
+    return {
+      scheme: "exact",
+      network,
+      asset,
+      amount: parsePrice(config.price, decimals).toString(),
+      payTo: config.payTo,
+      maxTimeoutSeconds: 300,
+      extra: { decimals }
+    };
+  });
+  return {
+    x402Version: 2,
+    resource: {
+      url,
+      description: config.description,
+      mimeType: "application/json"
+    },
+    accepts
+  };
+}
+function buildFacilitatorRequirements(config, resolvedTokens) {
+  const asset = resolvedTokens[0];
+  const decimals = resolveDecimals(config, asset);
+  return {
+    maxAmountRequired: parsePrice(config.price, decimals).toString(),
+    // Informational only: the facilitator validates the amount + the on-chain
+    // payload (the paid token lives in the payload / swapParams), and ignores
+    // `asset`. resolveAcceptedTokens guarantees at least one entry.
+    asset,
+    payTo: config.payTo,
+    network: config.network
+  };
+}
+function paymentRequiredResponse(url, config, resolvedTokens, error) {
+  const paymentRequired = buildPaymentRequired(url, config, resolvedTokens);
+  if (error) paymentRequired.error = error;
+  return {
+    status: 402,
+    headers: {
+      "Content-Type": "application/json",
+      "payment-required": encodeBase64(paymentRequired),
+      "access-control-expose-headers": "payment-required"
+    },
+    body: paymentRequired
+  };
+}
+function createPaymentGate(config) {
+  try {
+    paymentMiddlewareConfigSchema.parse(config);
+  } catch (cause) {
+    throw new X402ConfigError(
+      "Invalid paymentMiddleware config \u2014 check your routes, facilitator URL and payTo addresses",
+      cause
+    );
+  }
+  const client = new FacilitatorClient(config.facilitator);
+  return async (adapter) => {
+    if (adapter.getMethod().toUpperCase() === "OPTIONS")
+      return { type: "pass" };
+    const routeConfig = matchRoute(adapter.getPath(), config.routes);
+    if (!routeConfig) return { type: "pass" };
+    const resolvedTokens = resolveAcceptedTokens(routeConfig);
+    const paymentHeader = adapter.getHeader("payment-signature") ?? adapter.getHeader("x-payment");
+    if (!paymentHeader) {
+      return {
+        type: "error",
+        result: paymentRequiredResponse(
+          adapter.getUrl(),
+          routeConfig,
+          resolvedTokens
+        )
+      };
+    }
+    const requirements = buildFacilitatorRequirements(
+      routeConfig,
+      resolvedTokens
+    );
+    try {
+      await client.verify(paymentHeader, requirements);
+    } catch (e) {
+      const code = e instanceof X402RuntimeError ? e.code : X402_ERROR_CODES.FACILITATOR_UNAVAILABLE;
+      return {
+        type: "error",
+        result: paymentRequiredResponse(
+          adapter.getUrl(),
+          routeConfig,
+          resolvedTokens,
+          code
+        )
+      };
+    }
+    return {
+      type: "verified",
+      settle: () => client.settle(paymentHeader, requirements)
+    };
+  };
+}
+function createPaymentMiddleware(config) {
+  const gate = createPaymentGate(config);
+  return async (adapter) => {
+    const gateResult = await gate(adapter);
+    if (gateResult.type === "pass") return { pass: true };
+    if (gateResult.type === "error") return gateResult.result;
+    let handlerResult;
+    try {
+      handlerResult = await adapter.runHandler();
+    } catch {
+      return { pass: true, handlerRan: true };
+    }
+    if (handlerResult.status >= 200 && handlerResult.status < 300) {
+      let settled = false;
+      try {
+        const settleResponse = await gateResult.settle();
+        if (settleResponse.success) {
+          handlerResult.setResponseHeader(
+            "payment-response",
+            encodeBase64(settleResponse)
+          );
+          handlerResult.setResponseHeader(
+            "access-control-expose-headers",
+            "payment-response"
+          );
+          settled = true;
+        }
+      } catch {
+      }
+      if (!settled) {
+        handlerResult.discardResponse();
+        return {
+          status: 402,
+          headers: { "Content-Type": "application/json" },
+          body: {
+            error: "PAYMENT_SETTLEMENT_FAILED",
+            message: "Payment could not be confirmed after multiple attempts. Please retry."
+          }
+        };
+      }
+    }
+    handlerResult.sendResponse();
+    return { pass: true, handlerRan: true };
+  };
+}
+
+exports.FacilitatorClient = FacilitatorClient;
+exports.PARALLEL_TOKENS = PARALLEL_TOKENS;
+exports.X402ConfigError = X402ConfigError;
+exports.X402RuntimeError = X402RuntimeError;
+exports.X402_ERROR_CODES = X402_ERROR_CODES;
+exports.createPaymentGate = createPaymentGate;
+exports.createPaymentMiddleware = createPaymentMiddleware;
+exports.encodeBase64 = encodeBase64;
+exports.getDefaultAcceptedTokens = getDefaultAcceptedTokens;
+exports.parsePrice = parsePrice;
+exports.toEip155Network = toEip155Network;
+exports.validateAddress = validateAddress;

package/dist/chunk-XUNNMCO5.cjs

@@ -0,0 +1,20 @@
+'use strict';
+
+// src/timeout.ts
+var HANDLER_TIMEOUT_MS = 3e4;
+var HANDLER_TIMEOUT = /* @__PURE__ */ Symbol("x402:handler-timeout");
+async function raceTimeout(promise, ms = HANDLER_TIMEOUT_MS) {
+  let timer;
+  const timeout = new Promise((resolve) => {
+    timer = setTimeout(() => resolve(HANDLER_TIMEOUT), ms);
+    timer.unref?.();
+  });
+  try {
+    return await Promise.race([promise, timeout]);
+  } finally {
+    clearTimeout(timer);
+  }
+}
+
+exports.HANDLER_TIMEOUT = HANDLER_TIMEOUT;
+exports.raceTimeout = raceTimeout;

package/dist/express.cjs

@@ -0,0 +1,131 @@
+'use strict';
+
+var chunkXUNNMCO5_cjs = require('./chunk-XUNNMCO5.cjs');
+var chunkW3SMR5LQ_cjs = require('./chunk-W3SMR5LQ.cjs');
+
+// src/express/adapter.ts
+var TIMEOUT_BODY = JSON.stringify({
+  error: "HANDLER_TIMEOUT",
+  message: "The resource handler did not respond in time."
+});
+var ExpressAdapter = class {
+  constructor(req, res, next) {
+    this.req = req;
+    this.res = res;
+    this.next = next;
+  }
+  req;
+  res;
+  next;
+  getHeader(name) {
+    const value = this.req.header(name);
+    return Array.isArray(value) ? value[0] : value;
+  }
+  getMethod() {
+    return this.req.method;
+  }
+  getPath() {
+    return this.req.path;
+  }
+  getUrl() {
+    return `${this.req.protocol}://${this.req.headers.host}${this.req.originalUrl}`;
+  }
+  async runHandler() {
+    const res = this.res;
+    const next = this.next;
+    const originalWriteHead = res.writeHead.bind(res);
+    const originalWrite = res.write.bind(res);
+    const originalEnd = res.end.bind(res);
+    const buffered = [];
+    let settled = false;
+    let discarded = false;
+    let endCalled;
+    const endPromise = new Promise((resolve) => {
+      endCalled = resolve;
+    });
+    const restore = () => {
+      res.writeHead = originalWriteHead;
+      res.write = originalWrite;
+      res.end = originalEnd;
+    };
+    res.writeHead = ((...args) => {
+      if (discarded) return res;
+      if (!settled) {
+        buffered.push(["writeHead", args]);
+        return res;
+      }
+      return originalWriteHead(...args);
+    });
+    res.write = ((...args) => {
+      if (discarded) return true;
+      if (!settled) {
+        buffered.push(["write", args]);
+        return true;
+      }
+      return originalWrite(...args);
+    });
+    res.end = ((...args) => {
+      if (discarded) return res;
+      if (!settled) {
+        buffered.push(["end", args]);
+        endCalled();
+        return res;
+      }
+      return originalEnd(...args);
+    });
+    next();
+    const outcome = await chunkXUNNMCO5_cjs.raceTimeout(endPromise);
+    if (outcome === chunkXUNNMCO5_cjs.HANDLER_TIMEOUT) {
+      discarded = true;
+      return {
+        status: 504,
+        setResponseHeader: (name, value) => {
+          if (!res.headersSent) res.setHeader(name, value);
+        },
+        sendResponse: () => {
+          if (res.headersSent) return;
+          originalWriteHead(504, { "Content-Type": "application/json" });
+          originalEnd(TIMEOUT_BODY);
+        },
+        discardResponse: () => {
+        }
+      };
+    }
+    return {
+      status: res.statusCode,
+      setResponseHeader: (name, value) => res.setHeader(name, value),
+      sendResponse: () => {
+        settled = true;
+        restore();
+        for (const [method, args] of buffered) {
+          if (method === "writeHead") originalWriteHead(...args);
+          else if (method === "write") originalWrite(...args);
+          else if (method === "end") originalEnd(...args);
+        }
+      },
+      discardResponse: () => {
+        settled = true;
+        restore();
+      }
+    };
+  }
+};
+
+// src/express/index.ts
+function paymentMiddleware(config) {
+  const middleware = chunkW3SMR5LQ_cjs.createPaymentMiddleware(config);
+  return async (req, res, next) => {
+    const result = await middleware(new ExpressAdapter(req, res, next));
+    if ("pass" in result) {
+      if (result.handlerRan) return;
+      return next();
+    }
+    for (const [key, value] of Object.entries(result.headers)) {
+      res.setHeader(key, value);
+    }
+    res.status(result.status).json(result.body);
+  };
+}
+
+exports.ExpressAdapter = ExpressAdapter;
+exports.paymentMiddleware = paymentMiddleware;

package/dist/express.d.cts

@@ -0,0 +1,19 @@
+import { Request, Response, NextFunction } from 'express';
+import { H as HTTPAdapter, R as RunHandlerResult, P as PaymentMiddlewareConfig } from './types-CUi55YSx.cjs';
+import 'viem';
+
+declare class ExpressAdapter implements HTTPAdapter {
+    private readonly req;
+    private readonly res;
+    private readonly next;
+    constructor(req: Request, res: Response, next: NextFunction);
+    getHeader(name: string): string | undefined;
+    getMethod(): string;
+    getPath(): string;
+    getUrl(): string;
+    runHandler(): Promise<RunHandlerResult>;
+}
+
+declare function paymentMiddleware(config: PaymentMiddlewareConfig): (req: Request, res: Response, next: NextFunction) => Promise<void>;
+
+export { ExpressAdapter, paymentMiddleware };

package/dist/express.d.ts

@@ -0,0 +1,19 @@
+import { Request, Response, NextFunction } from 'express';
+import { H as HTTPAdapter, R as RunHandlerResult, P as PaymentMiddlewareConfig } from './types-CUi55YSx.js';
+import 'viem';
+
+declare class ExpressAdapter implements HTTPAdapter {
+    private readonly req;
+    private readonly res;
+    private readonly next;
+    constructor(req: Request, res: Response, next: NextFunction);
+    getHeader(name: string): string | undefined;
+    getMethod(): string;
+    getPath(): string;
+    getUrl(): string;
+    runHandler(): Promise<RunHandlerResult>;
+}
+
+declare function paymentMiddleware(config: PaymentMiddlewareConfig): (req: Request, res: Response, next: NextFunction) => Promise<void>;
+
+export { ExpressAdapter, paymentMiddleware };