@bankofai/x402-core 2.6.0-beta.0

package/dist/cjs/facilitator/index.js

@@ -0,0 +1,625 @@
+"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/facilitator/index.ts
+var facilitator_exports = {};
+__export(facilitator_exports, {
+  x402Facilitator: () => x402Facilitator
+});
+module.exports = __toCommonJS(facilitator_exports);
+
+// src/registry/assetRegistry.ts
+var AssetRegistry = class {
+  /** Creates a new AssetRegistry pre-populated with built-in token data. */
+  constructor() {
+    this.assets = /* @__PURE__ */ new Map();
+    this.defaults = /* @__PURE__ */ new Map();
+    this.registerBuiltins();
+  }
+  /**
+   * Register a single asset for a network.
+   *
+   * @param network - The network identifier (e.g. "eip155:1")
+   * @param symbol - The token symbol (e.g. "USDT")
+   * @param info - Asset metadata
+   */
+  register(network, symbol, info) {
+    if (!this.assets.has(network)) {
+      this.assets.set(network, /* @__PURE__ */ new Map());
+    }
+    this.assets.get(network).set(symbol, info);
+  }
+  /**
+   * Batch-register multiple assets for a network.
+   *
+   * @param network - The network identifier
+   * @param assets - Map of symbol to AssetInfo
+   */
+  registerAll(network, assets) {
+    for (const [symbol, info] of Object.entries(assets)) {
+      this.register(network, symbol, info);
+    }
+  }
+  /**
+   * Set the default asset symbol for a network.
+   *
+   * @param network - The network identifier
+   * @param symbol - The symbol to set as default
+   */
+  setDefault(network, symbol) {
+    if (!this.has(network, symbol)) {
+      throw new Error(
+        `Cannot set default: asset "${symbol}" is not registered on network "${network}"`
+      );
+    }
+    this.defaults.set(network, symbol);
+  }
+  /**
+   * Resolve a symbol to its AssetInfo on a network.
+   *
+   * @param network - The network identifier
+   * @param symbol - The token symbol
+   * @returns The resolved AssetInfo
+   * @throws If the asset is not registered
+   */
+  resolve(network, symbol) {
+    const networkAssets = this.assets.get(network);
+    if (!networkAssets || !networkAssets.has(symbol)) {
+      throw new Error(
+        `Asset "${symbol}" is not registered on network "${network}". Available: ${networkAssets ? Array.from(networkAssets.keys()).join(", ") : "none"}`
+      );
+    }
+    return networkAssets.get(symbol);
+  }
+  /**
+   * Get the default asset for a network.
+   *
+   * @param network - The network identifier
+   * @returns The default symbol and its AssetInfo
+   * @throws If no default is configured
+   */
+  getDefault(network) {
+    const symbol = this.defaults.get(network);
+    if (!symbol) {
+      throw new Error(`No default asset configured for network "${network}"`);
+    }
+    return { symbol, info: this.resolve(network, symbol) };
+  }
+  /**
+   * List all registered symbols for a network.
+   *
+   * @param network - The network identifier
+   * @returns Array of registered symbols
+   */
+  getSymbols(network) {
+    const networkAssets = this.assets.get(network);
+    return networkAssets ? Array.from(networkAssets.keys()) : [];
+  }
+  /**
+   * Check if an asset is registered on a network.
+   *
+   * @param network - The network identifier
+   * @param symbol - The token symbol
+   * @returns True if the asset is registered
+   */
+  has(network, symbol) {
+    return this.assets.get(network)?.has(symbol) ?? false;
+  }
+  /**
+   * Register built-in known assets.
+   * Data sourced from mechanism defaults and built-in registry.
+   */
+  registerBuiltins() {
+    this.registerAll("eip155:1", {
+      USDC: {
+        address: "0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48",
+        decimals: 6,
+        name: "USD Coin",
+        version: "2"
+      },
+      USDT: {
+        address: "0xdAC17F958D2ee523a2206206994597C13D831ec7",
+        decimals: 6,
+        name: "Tether USD",
+        version: "1",
+        assetTransferMethod: "permit2"
+      }
+    });
+    this.defaults.set("eip155:1", "USDC");
+    this.registerAll("eip155:56", {
+      USDC: {
+        address: "0x8AC76a51cc950d9822D68b83fE1Ad97B32Cd580d",
+        decimals: 18,
+        name: "USD Coin",
+        version: "1",
+        assetTransferMethod: "permit2"
+      },
+      USDT: {
+        address: "0x55d398326f99059fF775485246999027B3197955",
+        decimals: 18,
+        name: "Tether USD",
+        version: "1",
+        assetTransferMethod: "permit2"
+      }
+    });
+    this.defaults.set("eip155:56", "USDC");
+    this.registerAll("eip155:97", {
+      USDT: {
+        address: "0x337610d27c682E347C9cD60BD4b3b107C9d34dDd",
+        decimals: 18,
+        name: "Tether USD",
+        version: "1",
+        assetTransferMethod: "permit2"
+      },
+      USDC: {
+        address: "0x64544969ed7EBf5f083679233325356EbE738930",
+        decimals: 18,
+        name: "USD Coin",
+        version: "1",
+        assetTransferMethod: "permit2"
+      }
+    });
+    this.defaults.set("eip155:97", "USDT");
+    this.registerAll("tron:mainnet", {
+      USDT: {
+        address: "TR7NHqjeKQxGTCi8q8ZY4pL8otSzgjLj6t",
+        decimals: 6,
+        name: "Tether USD",
+        version: "1",
+        assetTransferMethod: "permit2"
+      },
+      USDD: {
+        address: "TXDk8mbtRbXeYuMNS83CfKPaYYT8XWv9Hz",
+        decimals: 18,
+        name: "Decentralized USD",
+        version: "1",
+        supportsEip2612: true,
+        assetTransferMethod: "permit2"
+      }
+    });
+    this.defaults.set("tron:mainnet", "USDT");
+    this.register("tron:shasta", "USDT", {
+      address: "TG3XXyExBkPp9nzdajDZsozEu4BkaSJozs",
+      decimals: 6,
+      name: "Tether USD",
+      version: "1",
+      assetTransferMethod: "permit2"
+    });
+    this.defaults.set("tron:shasta", "USDT");
+    this.registerAll("tron:nile", {
+      USDT: {
+        address: "TXYZopYRdj2D9XRtbG411XZZ3kM5VkAeBf",
+        decimals: 6,
+        name: "Tether USD",
+        version: "1",
+        assetTransferMethod: "permit2"
+      },
+      USDD: {
+        address: "TGjgvdTWWrybVLaVeFqSyVqJQWjxqRYbaK",
+        decimals: 18,
+        name: "Decentralized USD",
+        version: "1",
+        supportsEip2612: true,
+        assetTransferMethod: "permit2"
+      }
+    });
+    this.defaults.set("tron:nile", "USDT");
+  }
+};
+
+// src/registry/index.ts
+var globalAssetRegistry = new AssetRegistry();
+
+// src/index.ts
+var x402Version = 2;
+
+// src/facilitator/x402Facilitator.ts
+var x402Facilitator = class {
+  constructor() {
+    this.registeredFacilitatorSchemes = /* @__PURE__ */ new Map();
+    this.extensions = /* @__PURE__ */ new Map();
+    this.beforeVerifyHooks = [];
+    this.afterVerifyHooks = [];
+    this.onVerifyFailureHooks = [];
+    this.beforeSettleHooks = [];
+    this.afterSettleHooks = [];
+    this.onSettleFailureHooks = [];
+  }
+  /**
+   * Registers a scheme facilitator for the current x402 version.
+   * Networks are stored and used for getSupported() - no need to specify them later.
+   *
+   * @param networks - Single network or array of networks this facilitator supports
+   * @param facilitator - The scheme network facilitator to register
+   * @returns The x402Facilitator instance for chaining
+   */
+  register(networks, facilitator) {
+    const networksArray = Array.isArray(networks) ? networks : [networks];
+    return this._registerScheme(x402Version, networksArray, facilitator);
+  }
+  /**
+   * Registers a scheme facilitator for x402 version 1.
+   * Networks are stored and used for getSupported() - no need to specify them later.
+   *
+   * @param networks - Single network or array of networks this facilitator supports
+   * @param facilitator - The scheme network facilitator to register
+   * @returns The x402Facilitator instance for chaining
+   */
+  registerV1(networks, facilitator) {
+    const networksArray = Array.isArray(networks) ? networks : [networks];
+    return this._registerScheme(1, networksArray, facilitator);
+  }
+  /**
+   * Registers a protocol extension.
+   *
+   * @param extension - The extension object to register
+   * @returns The x402Facilitator instance for chaining
+   */
+  registerExtension(extension) {
+    this.extensions.set(extension.key, extension);
+    return this;
+  }
+  /**
+   * Gets the list of registered extension keys.
+   *
+   * @returns Array of extension key strings
+   */
+  getExtensions() {
+    return Array.from(this.extensions.keys());
+  }
+  /**
+   * Gets a registered extension by key.
+   *
+   * @param key - The extension key to look up
+   * @returns The extension object, or undefined if not registered
+   */
+  getExtension(key) {
+    return this.extensions.get(key);
+  }
+  /**
+   * Register a hook to execute before facilitator payment verification.
+   * Can abort verification by returning { abort: true, reason: string }
+   *
+   * @param hook - The hook function to register
+   * @returns The x402Facilitator instance for chaining
+   */
+  onBeforeVerify(hook) {
+    this.beforeVerifyHooks.push(hook);
+    return this;
+  }
+  /**
+   * Register a hook to execute after successful facilitator payment verification (isValid: true).
+   * This hook is NOT called when verification fails (isValid: false) - use onVerifyFailure for that.
+   *
+   * @param hook - The hook function to register
+   * @returns The x402Facilitator instance for chaining
+   */
+  onAfterVerify(hook) {
+    this.afterVerifyHooks.push(hook);
+    return this;
+  }
+  /**
+   * Register a hook to execute when facilitator payment verification fails.
+   * Called when: verification returns isValid: false, or an exception is thrown during verification.
+   * Can recover from failure by returning { recovered: true, result: VerifyResponse }
+   *
+   * @param hook - The hook function to register
+   * @returns The x402Facilitator instance for chaining
+   */
+  onVerifyFailure(hook) {
+    this.onVerifyFailureHooks.push(hook);
+    return this;
+  }
+  /**
+   * Register a hook to execute before facilitator payment settlement.
+   * Can abort settlement by returning { abort: true, reason: string }
+   *
+   * @param hook - The hook function to register
+   * @returns The x402Facilitator instance for chaining
+   */
+  onBeforeSettle(hook) {
+    this.beforeSettleHooks.push(hook);
+    return this;
+  }
+  /**
+   * Register a hook to execute after successful facilitator payment settlement.
+   *
+   * @param hook - The hook function to register
+   * @returns The x402Facilitator instance for chaining
+   */
+  onAfterSettle(hook) {
+    this.afterSettleHooks.push(hook);
+    return this;
+  }
+  /**
+   * Register a hook to execute when facilitator payment settlement fails.
+   * Can recover from failure by returning { recovered: true, result: SettleResponse }
+   *
+   * @param hook - The hook function to register
+   * @returns The x402Facilitator instance for chaining
+   */
+  onSettleFailure(hook) {
+    this.onSettleFailureHooks.push(hook);
+    return this;
+  }
+  /**
+   * Gets supported payment kinds, extensions, and signers.
+   * Uses networks registered during register() calls - no parameters needed.
+   * Returns flat array format for backward compatibility with V1 clients.
+   *
+   * @returns Supported response with kinds as array (with version in each element), extensions, and signers
+   */
+  getSupported() {
+    const kinds = [];
+    const signersByFamily = {};
+    for (const [version, schemeDataArray] of this.registeredFacilitatorSchemes) {
+      for (const schemeData of schemeDataArray) {
+        const { facilitator, networks } = schemeData;
+        const scheme = facilitator.scheme;
+        for (const network of networks) {
+          const extra = facilitator.getExtra(network);
+          kinds.push({
+            x402Version: version,
+            scheme,
+            network,
+            ...extra && { extra }
+          });
+          const family = facilitator.caipFamily;
+          if (!signersByFamily[family]) {
+            signersByFamily[family] = /* @__PURE__ */ new Set();
+          }
+          facilitator.getSigners(network).forEach((signer) => signersByFamily[family].add(signer));
+        }
+      }
+    }
+    const signers = {};
+    for (const [family, signerSet] of Object.entries(signersByFamily)) {
+      signers[family] = Array.from(signerSet);
+    }
+    return {
+      kinds,
+      extensions: this.getExtensions(),
+      signers
+    };
+  }
+  /**
+   * Verifies a payment payload against requirements.
+   *
+   * @param paymentPayload - The payment payload to verify
+   * @param paymentRequirements - The payment requirements to verify against
+   * @returns Promise resolving to the verification response
+   */
+  async verify(paymentPayload, paymentRequirements) {
+    const context = {
+      paymentPayload,
+      requirements: paymentRequirements
+    };
+    for (const hook of this.beforeVerifyHooks) {
+      const result = await hook(context);
+      if (result && "abort" in result && result.abort) {
+        return {
+          isValid: false,
+          invalidReason: result.reason
+        };
+      }
+    }
+    try {
+      const schemeDataArray = this.registeredFacilitatorSchemes.get(paymentPayload.x402Version);
+      if (!schemeDataArray) {
+        throw new Error(
+          `No facilitator registered for x402 version: ${paymentPayload.x402Version}`
+        );
+      }
+      let schemeNetworkFacilitator;
+      for (const schemeData of schemeDataArray) {
+        if (schemeData.facilitator.scheme === paymentRequirements.scheme) {
+          if (schemeData.networks.has(paymentRequirements.network)) {
+            schemeNetworkFacilitator = schemeData.facilitator;
+            break;
+          }
+          const patternRegex = new RegExp("^" + schemeData.pattern.replace("*", ".*") + "$");
+          if (patternRegex.test(paymentRequirements.network)) {
+            schemeNetworkFacilitator = schemeData.facilitator;
+            break;
+          }
+        }
+      }
+      if (!schemeNetworkFacilitator) {
+        throw new Error(
+          `No facilitator registered for scheme: ${paymentRequirements.scheme} and network: ${paymentRequirements.network}`
+        );
+      }
+      const facilitatorContext = this.buildFacilitatorContext();
+      const verifyResult = await schemeNetworkFacilitator.verify(
+        paymentPayload,
+        paymentRequirements,
+        facilitatorContext
+      );
+      if (!verifyResult.isValid) {
+        const failureContext = {
+          ...context,
+          error: new Error(verifyResult.invalidReason || "Verification failed")
+        };
+        for (const hook of this.onVerifyFailureHooks) {
+          const result = await hook(failureContext);
+          if (result && "recovered" in result && result.recovered) {
+            const recoveredContext = {
+              ...context,
+              result: result.result
+            };
+            for (const hook2 of this.afterVerifyHooks) {
+              await hook2(recoveredContext);
+            }
+            return result.result;
+          }
+        }
+        return verifyResult;
+      }
+      const resultContext = {
+        ...context,
+        result: verifyResult
+      };
+      for (const hook of this.afterVerifyHooks) {
+        await hook(resultContext);
+      }
+      return verifyResult;
+    } catch (error) {
+      const failureContext = {
+        ...context,
+        error
+      };
+      for (const hook of this.onVerifyFailureHooks) {
+        const result = await hook(failureContext);
+        if (result && "recovered" in result && result.recovered) {
+          return result.result;
+        }
+      }
+      throw error;
+    }
+  }
+  /**
+   * Settles a payment based on the payload and requirements.
+   *
+   * @param paymentPayload - The payment payload to settle
+   * @param paymentRequirements - The payment requirements for settlement
+   * @returns Promise resolving to the settlement response
+   */
+  async settle(paymentPayload, paymentRequirements) {
+    const context = {
+      paymentPayload,
+      requirements: paymentRequirements
+    };
+    for (const hook of this.beforeSettleHooks) {
+      const result = await hook(context);
+      if (result && "abort" in result && result.abort) {
+        throw new Error(`Settlement aborted: ${result.reason}`);
+      }
+    }
+    try {
+      const schemeDataArray = this.registeredFacilitatorSchemes.get(paymentPayload.x402Version);
+      if (!schemeDataArray) {
+        throw new Error(
+          `No facilitator registered for x402 version: ${paymentPayload.x402Version}`
+        );
+      }
+      let schemeNetworkFacilitator;
+      for (const schemeData of schemeDataArray) {
+        if (schemeData.facilitator.scheme === paymentRequirements.scheme) {
+          if (schemeData.networks.has(paymentRequirements.network)) {
+            schemeNetworkFacilitator = schemeData.facilitator;
+            break;
+          }
+          const patternRegex = new RegExp("^" + schemeData.pattern.replace("*", ".*") + "$");
+          if (patternRegex.test(paymentRequirements.network)) {
+            schemeNetworkFacilitator = schemeData.facilitator;
+            break;
+          }
+        }
+      }
+      if (!schemeNetworkFacilitator) {
+        throw new Error(
+          `No facilitator registered for scheme: ${paymentRequirements.scheme} and network: ${paymentRequirements.network}`
+        );
+      }
+      const facilitatorContext = this.buildFacilitatorContext();
+      const settleResult = await schemeNetworkFacilitator.settle(
+        paymentPayload,
+        paymentRequirements,
+        facilitatorContext
+      );
+      const resultContext = {
+        ...context,
+        result: settleResult
+      };
+      for (const hook of this.afterSettleHooks) {
+        await hook(resultContext);
+      }
+      return settleResult;
+    } catch (error) {
+      const failureContext = {
+        ...context,
+        error
+      };
+      for (const hook of this.onSettleFailureHooks) {
+        const result = await hook(failureContext);
+        if (result && "recovered" in result && result.recovered) {
+          return result.result;
+        }
+      }
+      throw error;
+    }
+  }
+  /**
+   * Builds a FacilitatorContext from the registered extensions map.
+   * Passed to mechanism verify/settle so they can access extension capabilities.
+   *
+   * @returns A FacilitatorContext backed by this facilitator's registered extensions
+   */
+  buildFacilitatorContext() {
+    const extensionsMap = this.extensions;
+    return {
+      getExtension(key) {
+        return extensionsMap.get(key);
+      }
+    };
+  }
+  /**
+   * Internal method to register a scheme facilitator.
+   *
+   * @param x402Version - The x402 protocol version
+   * @param networks - Array of concrete networks this facilitator supports
+   * @param facilitator - The scheme network facilitator to register
+   * @returns The x402Facilitator instance for chaining
+   */
+  _registerScheme(x402Version2, networks, facilitator) {
+    if (!this.registeredFacilitatorSchemes.has(x402Version2)) {
+      this.registeredFacilitatorSchemes.set(x402Version2, []);
+    }
+    const schemeDataArray = this.registeredFacilitatorSchemes.get(x402Version2);
+    schemeDataArray.push({
+      facilitator,
+      networks: new Set(networks),
+      pattern: this.derivePattern(networks)
+    });
+    return this;
+  }
+  /**
+   * Derives a wildcard pattern from an array of networks.
+   * If all networks share the same namespace, returns wildcard pattern.
+   * Otherwise returns the first network for exact matching.
+   *
+   * @param networks - Array of networks
+   * @returns Derived pattern for matching
+   */
+  derivePattern(networks) {
+    if (networks.length === 0) return "";
+    if (networks.length === 1) return networks[0];
+    const namespaces = networks.map((n) => n.split(":")[0]);
+    const uniqueNamespaces = new Set(namespaces);
+    if (uniqueNamespaces.size === 1) {
+      return `${namespaces[0]}:*`;
+    }
+    return networks[0];
+  }
+};
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  x402Facilitator
+});
+//# sourceMappingURL=index.js.map