x402z-facilitator 0.0.10 → 0.0.12

package/README.md

@@ -23,8 +23,10 @@ Set env vars:
 - `FACILITATOR_EVM_CHAIN_ID` (default 11155111)
 - `FACILITATOR_NETWORKS` (default `eip155:11155111`)
 - `FACILITATOR_PORT` (default 8040)
-- `FACILITATOR_BATCHER_ADDRESS` (optional FHETokenBatcher address)
+- `FACILITATOR_BATCHER_ADDRESS` (required FHETokenBatcher address)
+- `FACILITATOR_BATCH_INTERVAL_MS` (default 15000)
 - `FACILITATOR_GAS_MULTIPLIER` (optional, e.g. `2` to double estimated gas)
+- `FACILITATOR_FEE_MULTIPLIER` (optional, scales estimated max fee + priority fee)
 
 Then run:
 
@@ -33,8 +35,26 @@ pnpm -C packages/x402z-facilitator build
 node packages/x402z-facilitator/dist/bootstrap.js
 ```
 
+## Examples
+
+See `examples/README.md` for the full-process facilitator + server setup.
+
 ## Notes
 
 - This service receives `/verify` and `/settle` HTTP calls from the server.
-- It submits `confidentialTransferWithAuthorization` transactions on-chain.
-- When `FACILITATOR_BATCHER_ADDRESS` is set, it uses the batcher contract and validates the per-item result from batch events.
+- It queues settle requests and submits `batchConfidentialTransferWithAuthorization` on an interval.
+- It validates per-item results from batch events and reports them back to the server.
+
+## API surface
+
+Exports:
+- `X402zEvmFacilitator`: facilitator scheme implementation for erc7984-mind-v1.
+- `registerX402zEvmFacilitatorScheme`: registers the scheme with facilitator.
+- `createFacilitatorService`: builds the facilitator HTTP service.
+- `startFacilitatorService`: starts the service with a config.
+- `startFacilitator`: CLI/bootstrap entrypoint.
+
+Types:
+- `X402zFacilitatorSchemeOptions`: scheme config for facilitator registration.
+- `X402zFacilitatorRegistrationOptions`: registration options for the scheme.
+- `FacilitatorServiceOptions`: service configuration options.

package/dist/bootstrap.js

@@ -4,14 +4,16 @@ 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 });
+  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") {
+  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 });
+        __defProp(to, key, {
+          get: () => from[key],
+          enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable,
+        });
   }
   return to;
 };
@@ -21,7 +23,7 @@ var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: tru
 var bootstrap_exports = {};
 __export(bootstrap_exports, {
   createConfidentialFacilitatorFromEnv: () => createConfidentialFacilitatorFromEnv,
-  startConfidentialFacilitator: () => startConfidentialFacilitator
+  startConfidentialFacilitator: () => startConfidentialFacilitator,
 });
 module.exports = __toCommonJS(bootstrap_exports);
 var import_facilitator = require("@x402/core/facilitator");
@@ -98,47 +100,47 @@ var batcherAbi = [
               { internalType: "uint48", name: "validAfter", type: "uint48" },
               { internalType: "uint48", name: "validBefore", type: "uint48" },
               { internalType: "bytes32", name: "nonce", type: "bytes32" },
-              { internalType: "bytes32", name: "encryptedAmountHash", type: "bytes32" }
+              { internalType: "bytes32", name: "encryptedAmountHash", type: "bytes32" },
             ],
             internalType: "struct IFHEToken.ConfidentialPayment",
             name: "p",
-            type: "tuple"
+            type: "tuple",
           },
           { internalType: "externalEuint64", name: "encryptedAmountInput", type: "bytes32" },
           { internalType: "bytes", name: "inputProof", type: "bytes" },
-          { internalType: "bytes", name: "sig", type: "bytes" }
+          { internalType: "bytes", name: "sig", type: "bytes" },
         ],
         internalType: "struct FHETokenBatcher.Request[]",
         name: "requests",
-        type: "tuple[]"
-      }
+        type: "tuple[]",
+      },
     ],
     name: "batchConfidentialTransferWithAuthorization",
     outputs: [
       { internalType: "bool[]", name: "successes", type: "bool[]" },
-      { internalType: "bytes32[]", name: "transferredHandles", type: "bytes32[]" }
+      { internalType: "bytes32[]", name: "transferredHandles", type: "bytes32[]" },
     ],
     stateMutability: "nonpayable",
-    type: "function"
+    type: "function",
   },
   {
     anonymous: false,
     inputs: [
       { indexed: true, internalType: "uint256", name: "index", type: "uint256" },
-      { indexed: false, internalType: "bytes32", name: "transferredHandle", type: "bytes32" }
+      { indexed: false, internalType: "bytes32", name: "transferredHandle", type: "bytes32" },
     ],
     name: "BatchItemSuccess",
-    type: "event"
+    type: "event",
   },
   {
     anonymous: false,
     inputs: [
       { indexed: true, internalType: "uint256", name: "index", type: "uint256" },
-      { indexed: false, internalType: "bytes", name: "reason", type: "bytes" }
+      { indexed: false, internalType: "bytes", name: "reason", type: "bytes" },
     ],
     name: "BatchItemFailure",
-    type: "event"
-  }
+    type: "event",
+  },
 ];
 var ConfidentialEvmFacilitator = class {
   constructor(config) {
@@ -166,14 +168,14 @@ var ConfidentialEvmFacilitator = class {
       return {
         isValid: false,
         invalidReason: "unsupported_scheme",
-        payer: confidentialPayload?.authorization?.holder
+        payer: confidentialPayload?.authorization?.holder,
       };
     }
     if (payload.accepted.network !== requirements.network) {
       return {
         isValid: false,
         invalidReason: "network_mismatch",
-        payer: confidentialPayload.authorization.holder
+        payer: confidentialPayload.authorization.holder,
       };
     }
     const extra = requirements.extra;
@@ -182,7 +184,7 @@ var ConfidentialEvmFacilitator = class {
       return {
         isValid: false,
         invalidReason: "missing_eip712_domain",
-        payer: confidentialPayload.authorization.holder
+        payer: confidentialPayload.authorization.holder,
       };
     }
     const now = this.clock();
@@ -192,21 +194,26 @@ var ConfidentialEvmFacilitator = class {
       return {
         isValid: false,
         invalidReason: "invalid_validity_window",
-        payer: confidentialPayload.authorization.holder
+        payer: confidentialPayload.authorization.holder,
       };
     }
     if (now < validAfter || now > validBefore) {
       return {
         isValid: false,
         invalidReason: "authorization_expired",
-        payer: confidentialPayload.authorization.holder
+        payer: confidentialPayload.authorization.holder,
       };
     }
-    if (!(0, import_viem.isAddressEqual)((0, import_viem.getAddress)(confidentialPayload.authorization.payee), (0, import_viem.getAddress)(requirements.payTo))) {
+    if (
+      !(0, import_viem.isAddressEqual)(
+        (0, import_viem.getAddress)(confidentialPayload.authorization.payee),
+        (0, import_viem.getAddress)(requirements.payTo),
+      )
+    ) {
       return {
         isValid: false,
         invalidReason: "recipient_mismatch",
-        payer: confidentialPayload.authorization.holder
+        payer: confidentialPayload.authorization.holder,
       };
     }
     const computedHash = this.hashFn(confidentialPayload.encryptedAmountInput);
@@ -214,7 +221,7 @@ var ConfidentialEvmFacilitator = class {
       return {
         isValid: false,
         invalidReason: "encrypted_amount_mismatch",
-        payer: confidentialPayload.authorization.holder
+        payer: confidentialPayload.authorization.holder,
       };
     }
     const chainId = parseInt(requirements.network.split(":")[1]);
@@ -224,7 +231,7 @@ var ConfidentialEvmFacilitator = class {
         name: eip712.name,
         version: eip712.version,
         chainId,
-        verifyingContract: (0, import_viem.getAddress)(requirements.asset)
+        verifyingContract: (0, import_viem.getAddress)(requirements.asset),
       },
       types: import_x402z_shared.confidentialPaymentTypes,
       primaryType: "ConfidentialPayment",
@@ -236,15 +243,15 @@ var ConfidentialEvmFacilitator = class {
         validAfter: BigInt(confidentialPayload.authorization.validAfter),
         validBefore: BigInt(confidentialPayload.authorization.validBefore),
         nonce: confidentialPayload.authorization.nonce,
-        encryptedAmountHash: confidentialPayload.authorization.encryptedAmountHash
+        encryptedAmountHash: confidentialPayload.authorization.encryptedAmountHash,
       },
-      signature: confidentialPayload.signature
+      signature: confidentialPayload.signature,
     });
     if (!isValidSignature) {
       return {
         isValid: false,
         invalidReason: "invalid_signature",
-        payer: confidentialPayload.authorization.holder
+        payer: confidentialPayload.authorization.holder,
       };
     }
     if (this.checkUsedNonces) {
@@ -252,19 +259,19 @@ var ConfidentialEvmFacilitator = class {
         address: (0, import_viem.getAddress)(requirements.asset),
         abi: import_x402z_shared.confidentialTokenAbi,
         functionName: "usedNonces",
-        args: [confidentialPayload.authorization.holder, confidentialPayload.authorization.nonce]
+        args: [confidentialPayload.authorization.holder, confidentialPayload.authorization.nonce],
       });
       if (used) {
         return {
           isValid: false,
           invalidReason: "nonce_already_used",
-          payer: confidentialPayload.authorization.holder
+          payer: confidentialPayload.authorization.holder,
         };
       }
     }
     return {
       isValid: true,
-      payer: confidentialPayload.authorization.holder
+      payer: confidentialPayload.authorization.holder,
     };
   }
   async settle(payload, requirements) {
@@ -276,7 +283,7 @@ var ConfidentialEvmFacilitator = class {
         errorReason: valid.invalidReason ?? "invalid_payment",
         payer: confidentialPayload.authorization.holder,
         transaction: "",
-        network: requirements.network
+        network: requirements.network,
       };
     }
     return new Promise((resolve) => {
@@ -321,14 +328,14 @@ var ConfidentialEvmFacilitator = class {
         p: confidentialPayload.authorization,
         encryptedAmountInput: confidentialPayload.encryptedAmountInput,
         inputProof: confidentialPayload.inputProof,
-        sig: confidentialPayload.signature
+        sig: confidentialPayload.signature,
       };
     });
     const txRequest = {
       address: this.batcherAddress,
       abi: batcherAbi,
       functionName: "batchConfidentialTransferWithAuthorization",
-      args: [tokenAddress, requests]
+      args: [tokenAddress, requests],
     };
     if (process.env.X402Z_DEBUG === "1") {
       console.debug("[x402z-facilitator] settle tx", {
@@ -336,7 +343,7 @@ var ConfidentialEvmFacilitator = class {
         tokenAddress,
         functionName: txRequest.functionName,
         to: txRequest.address,
-        size: requests.length
+        size: requests.length,
       });
     }
     let txHash;
@@ -350,7 +357,7 @@ var ConfidentialEvmFacilitator = class {
           errorReason: "settlement_failed",
           payer: confidentialPayload.authorization.holder,
           transaction: "",
-          network: entry.requirements.network
+          network: entry.requirements.network,
         });
       }
       return;
@@ -372,7 +379,7 @@ var ConfidentialEvmFacilitator = class {
             errorReason: "settlement_failed",
             payer: confidentialPayload.authorization.holder,
             transaction: txHash,
-            network: entry.requirements.network
+            network: entry.requirements.network,
           });
         }
         return;
@@ -385,7 +392,7 @@ var ConfidentialEvmFacilitator = class {
           success: true,
           payer: confidentialPayload.authorization.holder,
           transaction: txHash,
-          network: entry.requirements.network
+          network: entry.requirements.network,
         });
       });
       return;
@@ -402,7 +409,7 @@ var ConfidentialEvmFacilitator = class {
         const decoded = (0, import_viem.decodeEventLog)({
           abi: batcherAbi,
           data: log.data,
-          topics: log.topics
+          topics: log.topics,
         });
         if (process.env.X402Z_DEBUG === "1") {
           console.debug("[x402z-facilitator] batch log", decoded);
@@ -411,13 +418,13 @@ var ConfidentialEvmFacilitator = class {
           const args = decoded.args;
           batchResults.set(Number(args.index), {
             success: true,
-            transferredHandle: args.transferredHandle
+            transferredHandle: args.transferredHandle,
           });
         } else if (decoded.eventName === "BatchItemFailure") {
           const args = decoded.args;
           batchResults.set(Number(args.index), {
             success: false,
-            failureReason: args.reason
+            failureReason: args.reason,
           });
         }
       }
@@ -426,27 +433,23 @@ var ConfidentialEvmFacilitator = class {
       const confidentialPayload = entry.payload.payload;
       const batchResult = batchResults.get(index);
       if (!batchResult || !batchResult.success) {
-        entry.resolve(
-          {
-            success: false,
-            errorReason: "settlement_failed",
-            payer: confidentialPayload.authorization.holder,
-            transaction: txHash,
-            network: entry.requirements.network,
-            ...batchResult ? { batch: { index, ...batchResult } } : {}
-          }
-        );
-        return;
-      }
-      entry.resolve(
-        {
-          success: true,
+        entry.resolve({
+          success: false,
+          errorReason: "settlement_failed",
           payer: confidentialPayload.authorization.holder,
           transaction: txHash,
           network: entry.requirements.network,
-          batch: { index, ...batchResult }
-        }
-      );
+          ...(batchResult ? { batch: { index, ...batchResult } } : {}),
+        });
+        return;
+      }
+      entry.resolve({
+        success: true,
+        payer: confidentialPayload.authorization.holder,
+        transaction: txHash,
+        network: entry.requirements.network,
+        batch: { index, ...batchResult },
+      });
     });
   }
 };
@@ -463,17 +466,30 @@ function createConfidentialFacilitatorFromEnv() {
   const privateKey = requireEnv("FACILITATOR_EVM_PRIVATE_KEY");
   const chainId = Number(process.env.FACILITATOR_EVM_CHAIN_ID ?? "11155111");
   const rpcUrl = requireEnv("FACILITATOR_EVM_RPC_URL");
-  const networks = (process.env.FACILITATOR_NETWORKS ?? "eip155:11155111").split(",").map((network) => network.trim()).filter(Boolean);
+  const networks = (process.env.FACILITATOR_NETWORKS ?? "eip155:11155111")
+    .split(",")
+    .map((network) => network.trim())
+    .filter(Boolean);
   const waitForReceipt = (process.env.FACILITATOR_WAIT_FOR_RECEIPT ?? "true") === "true";
   const batcherAddress = process.env.FACILITATOR_BATCHER_ADDRESS;
   if (!batcherAddress) {
     throw new Error("FACILITATOR_BATCHER_ADDRESS is required");
   }
-  const batchIntervalMs = process.env.FACILITATOR_BATCH_INTERVAL_MS ? Number(process.env.FACILITATOR_BATCH_INTERVAL_MS) : void 0;
-  const receiptTimeoutMs = process.env.FACILITATOR_RECEIPT_TIMEOUT_MS ? Number(process.env.FACILITATOR_RECEIPT_TIMEOUT_MS) : void 0;
-  const receiptConfirmations = process.env.FACILITATOR_RECEIPT_CONFIRMATIONS ? Number(process.env.FACILITATOR_RECEIPT_CONFIRMATIONS) : void 0;
-  const receiptPollingIntervalMs = process.env.FACILITATOR_RECEIPT_POLLING_INTERVAL_MS ? Number(process.env.FACILITATOR_RECEIPT_POLLING_INTERVAL_MS) : void 0;
-  const gasMultiplier = process.env.FACILITATOR_GAS_MULTIPLIER ? Number(process.env.FACILITATOR_GAS_MULTIPLIER) : void 0;
+  const batchIntervalMs = process.env.FACILITATOR_BATCH_INTERVAL_MS
+    ? Number(process.env.FACILITATOR_BATCH_INTERVAL_MS)
+    : void 0;
+  const receiptTimeoutMs = process.env.FACILITATOR_RECEIPT_TIMEOUT_MS
+    ? Number(process.env.FACILITATOR_RECEIPT_TIMEOUT_MS)
+    : void 0;
+  const receiptConfirmations = process.env.FACILITATOR_RECEIPT_CONFIRMATIONS
+    ? Number(process.env.FACILITATOR_RECEIPT_CONFIRMATIONS)
+    : void 0;
+  const receiptPollingIntervalMs = process.env.FACILITATOR_RECEIPT_POLLING_INTERVAL_MS
+    ? Number(process.env.FACILITATOR_RECEIPT_POLLING_INTERVAL_MS)
+    : void 0;
+  const gasMultiplier = process.env.FACILITATOR_GAS_MULTIPLIER
+    ? Number(process.env.FACILITATOR_GAS_MULTIPLIER)
+    : void 0;
   const debugEnabled = process.env.X402Z_DEBUG === "1";
   const account = (0, import_accounts.privateKeyToAccount)(privateKey);
   if (debugEnabled) {
@@ -488,9 +504,9 @@ function createConfidentialFacilitatorFromEnv() {
       receipt: {
         confirmations: receiptConfirmations,
         timeoutMs: receiptTimeoutMs,
-        pollingIntervalMs: receiptPollingIntervalMs
+        pollingIntervalMs: receiptPollingIntervalMs,
       },
-      address: account.address
+      address: account.address,
     });
   }
   const client = (0, import_viem2.createWalletClient)({
@@ -499,17 +515,18 @@ function createConfidentialFacilitatorFromEnv() {
       id: chainId,
       name: "custom",
       nativeCurrency: { name: "native", symbol: "NATIVE", decimals: 18 },
-      rpcUrls: { default: { http: [rpcUrl] } }
+      rpcUrls: { default: { http: [rpcUrl] } },
     },
-    transport: (0, import_viem2.http)(rpcUrl)
+    transport: (0, import_viem2.http)(rpcUrl),
   }).extend(import_viem2.publicActions);
   const signer = (0, import_evm.toFacilitatorEvmSigner)({
     address: account.address,
-    readContract: (args) => client.readContract({
-      ...args,
-      args: args.args || []
-      // eslint-disable-next-line @typescript-eslint/no-explicit-any
-    }),
+    readContract: (args) =>
+      client.readContract({
+        ...args,
+        args: args.args || [],
+        // eslint-disable-next-line @typescript-eslint/no-explicit-any
+      }),
     verifyTypedData: (args) => client.verifyTypedData(args),
     writeContract: async (args) => {
       let gas;
@@ -518,11 +535,11 @@ function createConfidentialFacilitatorFromEnv() {
           const estimated = await client.estimateContractGas({
             ...args,
             args: args.args || [],
-            account
+            account,
             // eslint-disable-next-line @typescript-eslint/no-explicit-any
           });
           const scale = BigInt(Math.round(gasMultiplier * 1e3));
-          const scaled = estimated * scale / 1000n;
+          const scaled = (estimated * scale) / 1000n;
           gas = scaled > estimated ? scaled : estimated;
         } catch (error) {
           if (debugEnabled) {
@@ -533,16 +550,15 @@ function createConfidentialFacilitatorFromEnv() {
       return client.writeContract({
         ...args,
         args: args.args || [],
-        ...gas ? { gas } : {}
+        ...(gas ? { gas } : {}),
         // eslint-disable-next-line @typescript-eslint/no-explicit-any
       });
     },
-    sendTransaction: (args) => (
+    sendTransaction: (args) =>
       // eslint-disable-next-line @typescript-eslint/no-explicit-any
-      client.sendTransaction({ to: args.to, data: args.data })
-    ),
+      client.sendTransaction({ to: args.to, data: args.data }),
     waitForTransactionReceipt: (args) => client.waitForTransactionReceipt(args),
-    getCode: (args) => client.getCode(args)
+    getCode: (args) => client.getCode(args),
   });
   const facilitator = new import_facilitator.x402Facilitator();
   for (const network of networks) {
@@ -556,9 +572,9 @@ function createConfidentialFacilitatorFromEnv() {
         receipt: {
           confirmations: receiptConfirmations,
           timeoutMs: receiptTimeoutMs,
-          pollingIntervalMs: receiptPollingIntervalMs
-        }
-      })
+          pollingIntervalMs: receiptPollingIntervalMs,
+        },
+      }),
     );
   }
   return facilitator;
@@ -575,7 +591,8 @@ if (require.main === module) {
   console.log(`Confidential facilitator listening on :${port}`);
 }
 // Annotate the CommonJS export names for ESM import in node:
-0 && (module.exports = {
-  createConfidentialFacilitatorFromEnv,
-  startConfidentialFacilitator
-});
+0 &&
+  (module.exports = {
+    createConfidentialFacilitatorFromEnv,
+    startConfidentialFacilitator,
+  });