@payai/x402-evm 2.4.1 → 2.4.3

package/dist/cjs/batch-settlement/server/file-storage.js

@@ -0,0 +1,181 @@
+"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/batch-settlement/server/fileStorage.ts
+var fileStorage_exports = {};
+__export(fileStorage_exports, {
+  FileChannelStorage: () => FileChannelStorage
+});
+module.exports = __toCommonJS(fileStorage_exports);
+var import_promises2 = require("fs/promises");
+var import_node_fs = require("fs");
+var import_node_path2 = require("path");
+
+// src/batch-settlement/storage-utils.ts
+var import_promises = require("fs/promises");
+var import_node_path = require("path");
+function isNodeEnoent(err) {
+  if (!err || typeof err !== "object" || !("code" in err)) return false;
+  return err.code === "ENOENT";
+}
+async function readJsonFile(filePath) {
+  try {
+    const raw = await (0, import_promises.readFile)(filePath, "utf8");
+    return JSON.parse(raw);
+  } catch (err) {
+    if (isNodeEnoent(err)) return void 0;
+    throw err;
+  }
+}
+async function writeJsonAtomic(filePath, value) {
+  const dir = (0, import_node_path.dirname)(filePath);
+  await (0, import_promises.mkdir)(dir, { recursive: true });
+  const tmp = (0, import_node_path.join)(dir, `.${process.pid}.${Date.now()}.${Math.random().toString(36).slice(2)}.tmp`);
+  const body = `${JSON.stringify(value, null, 2)}
+`;
+  await (0, import_promises.writeFile)(tmp, body, "utf8");
+  try {
+    await (0, import_promises.rename)(tmp, filePath);
+  } catch {
+    await (0, import_promises.unlink)(filePath).catch(() => {
+    });
+    await (0, import_promises.rename)(tmp, filePath);
+  }
+}
+
+// src/batch-settlement/server/fileStorage.ts
+var FileChannelStorage = class {
+  /**
+   * Creates file-backed server channel storage under the given root directory.
+   *
+   * @param options - Configuration including the storage root directory.
+   */
+  constructor(options) {
+    this.root = options.directory;
+  }
+  /**
+   * Loads a persisted channel record, if present.
+   *
+   * @param channelId - The channel identifier (path segment is lowercased).
+   * @returns Parsed channel record or `undefined` when the file is missing.
+   */
+  async get(channelId) {
+    return readJsonFile(this.filePath(channelId));
+  }
+  /**
+   * Lists all stored channel records by reading the server directory.
+   *
+   * @returns Channel records sorted by channelId; empty array if the directory is missing.
+   */
+  async list() {
+    const dir = (0, import_node_path2.join)(this.root, "server");
+    let names;
+    try {
+      names = await (0, import_promises2.readdir)(dir);
+    } catch (err) {
+      if (isNodeEnoent(err)) return [];
+      throw err;
+    }
+    const channels = [];
+    for (const name of names) {
+      if (!name.endsWith(".json")) continue;
+      const path = (0, import_node_path2.join)(dir, name);
+      try {
+        const raw = await (0, import_promises2.readFile)(path, "utf8");
+        channels.push(JSON.parse(raw));
+      } catch (err) {
+        if (isNodeEnoent(err)) continue;
+        throw err;
+      }
+    }
+    return channels.sort((a, b) => a.channelId.localeCompare(b.channelId));
+  }
+  /**
+   * Atomically inspects and mutates a channel record under a cross-process file lock.
+   *
+   * @param channelId - The channel identifier.
+   * @param update - Mutation callback. Return `undefined` to delete, or `current` to leave unchanged.
+   * @returns The final stored channel and whether storage updated, stayed unchanged, or deleted.
+   */
+  async updateChannel(channelId, update) {
+    const lockPath = this.filePath(channelId) + ".lock";
+    await (0, import_promises2.mkdir)((0, import_node_path2.dirname)(lockPath), { recursive: true });
+    const lockHandle = await this.acquireLock(lockPath);
+    try {
+      const path = this.filePath(channelId);
+      let current;
+      try {
+        const raw = await (0, import_promises2.readFile)(path, "utf8");
+        current = JSON.parse(raw);
+      } catch (err) {
+        if (!isNodeEnoent(err)) throw err;
+      }
+      const next = update(current);
+      if (next === current) {
+        return { channel: current, status: "unchanged" };
+      }
+      if (!next) {
+        try {
+          await (0, import_promises2.unlink)(path);
+        } catch (err) {
+          if (!isNodeEnoent(err)) throw err;
+        }
+        return { channel: void 0, status: current ? "deleted" : "unchanged" };
+      }
+      await writeJsonAtomic(path, next);
+      return { channel: next, status: "updated" };
+    } finally {
+      await lockHandle.close();
+      await (0, import_promises2.unlink)(lockPath).catch(() => {
+      });
+    }
+  }
+  /**
+   * Absolute path to the JSON file for a channel.
+   *
+   * @param channelId - The channel identifier.
+   * @returns Filesystem path under `{root}/server/...`.
+   */
+  filePath(channelId) {
+    return (0, import_node_path2.join)(this.root, "server", `${channelId.toLowerCase()}.json`);
+  }
+  /**
+   * Creates an exclusive lock file, polling until no other process holds it.
+   *
+   * @param lockPath - Absolute path for the lock file (created with `O_EXCL`).
+   * @returns Writable file handle for the lock file; caller must close it to release.
+   */
+  async acquireLock(lockPath) {
+    while (true) {
+      try {
+        return await (0, import_promises2.open)(lockPath, import_node_fs.constants.O_CREAT | import_node_fs.constants.O_EXCL | import_node_fs.constants.O_WRONLY);
+      } catch (err) {
+        if (err.code !== "EEXIST") {
+          throw err;
+        }
+        await new Promise((resolve) => setTimeout(resolve, 10));
+      }
+    }
+  }
+};
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  FileChannelStorage
+});
+//# sourceMappingURL=file-storage.js.map

package/dist/cjs/batch-settlement/server/file-storage.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../../../src/batch-settlement/server/fileStorage.ts","../../../../src/batch-settlement/storage-utils.ts"],"sourcesContent":["import { mkdir, open, readdir, readFile, unlink } from \"node:fs/promises\";\nimport { constants } from \"node:fs\";\nimport { dirname, join } from \"node:path\";\n\nimport { isNodeEnoent, readJsonFile, writeJsonAtomic } from \"../storage-utils\";\nimport type { FileChannelStorageOptions } from \"../types\";\nimport type { ChannelStorage, Channel, ChannelUpdateResult } from \"./storage\";\n\nexport type { FileChannelStorageOptions };\n\n/**\n * Node.js file-backed {@link ChannelStorage} for the batched server scheme.\n */\nexport class FileChannelStorage implements ChannelStorage {\n  private readonly root: string;\n\n  /**\n   * Creates file-backed server channel storage under the given root directory.\n   *\n   * @param options - Configuration including the storage root directory.\n   */\n  constructor(options: FileChannelStorageOptions) {\n    this.root = options.directory;\n  }\n\n  /**\n   * Loads a persisted channel record, if present.\n   *\n   * @param channelId - The channel identifier (path segment is lowercased).\n   * @returns Parsed channel record or `undefined` when the file is missing.\n   */\n  async get(channelId: string): Promise<Channel | undefined> {\n    return readJsonFile<Channel>(this.filePath(channelId));\n  }\n\n  /**\n   * Lists all stored channel records by reading the server directory.\n   *\n   * @returns Channel records sorted by channelId; empty array if the directory is missing.\n   */\n  async list(): Promise<Channel[]> {\n    const dir = join(this.root, \"server\");\n    let names: string[];\n    try {\n      names = await readdir(dir);\n    } catch (err: unknown) {\n      if (isNodeEnoent(err)) return [];\n      throw err;\n    }\n\n    const channels: Channel[] = [];\n    for (const name of names) {\n      if (!name.endsWith(\".json\")) continue;\n      const path = join(dir, name);\n      try {\n        const raw = await readFile(path, \"utf8\");\n        channels.push(JSON.parse(raw) as Channel);\n      } catch (err: unknown) {\n        // Skip files that disappeared between readdir and readFile (e.g. concurrent delete).\n        // Rethrow other failures (corrupt JSON, permission denied) so callers see them.\n        if (isNodeEnoent(err)) continue;\n        throw err;\n      }\n    }\n    return channels.sort((a, b) => a.channelId.localeCompare(b.channelId));\n  }\n\n  /**\n   * Atomically inspects and mutates a channel record under a cross-process file lock.\n   *\n   * @param channelId - The channel identifier.\n   * @param update - Mutation callback. Return `undefined` to delete, or `current` to leave unchanged.\n   * @returns The final stored channel and whether storage updated, stayed unchanged, or deleted.\n   */\n  async updateChannel(\n    channelId: string,\n    update: (current: Channel | undefined) => Channel | undefined,\n  ): Promise<ChannelUpdateResult> {\n    const lockPath = this.filePath(channelId) + \".lock\";\n    await mkdir(dirname(lockPath), { recursive: true });\n    const lockHandle = await this.acquireLock(lockPath);\n\n    try {\n      const path = this.filePath(channelId);\n      let current: Channel | undefined;\n      try {\n        const raw = await readFile(path, \"utf8\");\n        current = JSON.parse(raw) as Channel;\n      } catch (err: unknown) {\n        if (!isNodeEnoent(err)) throw err;\n      }\n\n      const next = update(current);\n      if (next === current) {\n        return { channel: current, status: \"unchanged\" };\n      }\n\n      if (!next) {\n        try {\n          await unlink(path);\n        } catch (err: unknown) {\n          if (!isNodeEnoent(err)) throw err;\n        }\n        return { channel: undefined, status: current ? \"deleted\" : \"unchanged\" };\n      }\n\n      await writeJsonAtomic(path, next);\n      return { channel: next, status: \"updated\" };\n    } finally {\n      await lockHandle.close();\n      await unlink(lockPath).catch(() => {});\n    }\n  }\n\n  /**\n   * Absolute path to the JSON file for a channel.\n   *\n   * @param channelId - The channel identifier.\n   * @returns Filesystem path under `{root}/server/...`.\n   */\n  private filePath(channelId: string): string {\n    return join(this.root, \"server\", `${channelId.toLowerCase()}.json`);\n  }\n\n  /**\n   * Creates an exclusive lock file, polling until no other process holds it.\n   *\n   * @param lockPath - Absolute path for the lock file (created with `O_EXCL`).\n   * @returns Writable file handle for the lock file; caller must close it to release.\n   */\n  private async acquireLock(lockPath: string) {\n    while (true) {\n      try {\n        return await open(lockPath, constants.O_CREAT | constants.O_EXCL | constants.O_WRONLY);\n      } catch (err: unknown) {\n        if ((err as NodeJS.ErrnoException).code !== \"EEXIST\") {\n          throw err;\n        }\n        await new Promise(resolve => setTimeout(resolve, 10));\n      }\n    }\n  }\n}\n","import { mkdir, readFile, rename, unlink, writeFile } from \"node:fs/promises\";\nimport { dirname, join } from \"node:path\";\n\n/**\n * Returns true when `err` is a Node.js `ENOENT` filesystem error (file does not exist).\n *\n * @param err - The thrown value to inspect.\n * @returns `true` for `ENOENT`, `false` for any other value or error code.\n */\nexport function isNodeEnoent(err: unknown): boolean {\n  if (!err || typeof err !== \"object\" || !(\"code\" in err)) return false;\n  return (err as NodeJS.ErrnoException).code === \"ENOENT\";\n}\n\n/**\n * Reads a JSON file and parses it. Returns `undefined` if the file does not exist.\n * Other errors (permission, malformed JSON) are rethrown.\n *\n * @param filePath - Path to the JSON file.\n * @returns Parsed value, or `undefined` for `ENOENT`.\n */\nexport async function readJsonFile<T>(filePath: string): Promise<T | undefined> {\n  try {\n    const raw = await readFile(filePath, \"utf8\");\n    return JSON.parse(raw) as T;\n  } catch (err: unknown) {\n    if (isNodeEnoent(err)) return undefined;\n    throw err;\n  }\n}\n\n/**\n * Writes JSON to `filePath` atomically (temp file in the same directory, then rename).\n * Creates parent directories as needed.\n *\n * @param filePath - Destination file path; parent dirs are created if missing.\n * @param value - JSON-serializable value to persist.\n */\nexport async function writeJsonAtomic(filePath: string, value: unknown): Promise<void> {\n  const dir = dirname(filePath);\n  await mkdir(dir, { recursive: true });\n  const tmp = join(dir, `.${process.pid}.${Date.now()}.${Math.random().toString(36).slice(2)}.tmp`);\n  const body = `${JSON.stringify(value, null, 2)}\\n`;\n  await writeFile(tmp, body, \"utf8\");\n  try {\n    await rename(tmp, filePath);\n  } catch {\n    // On Windows, rename() onto an existing file throws EEXIST; unlink + rename is intentional.\n    await unlink(filePath).catch(() => {});\n    await rename(tmp, filePath);\n  }\n}\n"],"mappings":"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","names":["import_promises","import_node_path"]}

package/dist/cjs/batch-settlement/server/index.d.ts

@@ -0,0 +1,491 @@
+import { Network, SchemePaymentRequiredContext, SchemeNetworkServer, SchemeServerHooks, PaymentRequirements, DeepReadonly, PaymentPayload, MoneyParser, Price, AssetAmount } from '@payai/x402/types';
+import { FacilitatorClient, SettleContext, SettleResultContext } from '@payai/x402/server';
+import { h as BatchSettlementVoucherClaim, A as AuthorizerSigner } from '../../types-CF8P2-NM.js';
+import { a as Channel, C as ChannelStorage } from '../../storage-Bl6aD0Xg.js';
+export { b as ChannelUpdateResult, I as InMemoryChannelStorage, P as PendingRequest } from '../../storage-Bl6aD0Xg.js';
+import 'viem';
+
+interface ChannelManagerConfig {
+    scheme: BatchSettlementEvmScheme;
+    facilitator: FacilitatorClient;
+    receiver: `0x${string}`;
+    token: `0x${string}`;
+    network: Network;
+}
+type ClaimChannelSelector = (channels: Channel[], context: AutoSettlementContext) => Channel[] | Promise<Channel[]>;
+interface ClaimOptions {
+    maxClaimsPerBatch?: number;
+    idleSecs?: number;
+    selectClaimChannels?: ClaimChannelSelector;
+}
+interface AutoSettlementConfig {
+    claimIntervalSecs?: number;
+    settleIntervalSecs?: number;
+    refundIntervalSecs?: number;
+    maxClaimsPerBatch?: number;
+    selectClaimChannels?: ClaimChannelSelector;
+    shouldSettle?: (context: AutoSettlementContext) => boolean | Promise<boolean>;
+    selectRefundChannels?: (channels: Channel[], context: AutoSettlementContext) => Channel[] | Promise<Channel[]>;
+    onClaim?: (result: ClaimResult) => void;
+    onSettle?: (result: SettleResult) => void;
+    onRefund?: (result: RefundResult) => void;
+    onError?: (error: unknown) => void;
+}
+interface AutoSettlementContext {
+    now: number;
+    lastClaimTime: number;
+    lastSettleTime: number;
+    pendingSettle: boolean;
+}
+interface ClaimResult {
+    vouchers: number;
+    transaction: string;
+}
+interface SettleResult {
+    transaction: string;
+}
+interface RefundResult {
+    channel: string;
+    transaction: string;
+}
+/**
+ * Manages the server-side channel lifecycle for the `batch-settlement` scheme:
+ * batch claiming of vouchers, settlement of claimed funds, and cooperative refund.
+ *
+ * Provides one-shot operations (`claim()`, `settle()`, `claimAndSettle()`,
+ * `refundIdleChannels()`) and an optional interval runner.
+ */
+declare class BatchSettlementChannelManager {
+    private readonly scheme;
+    private readonly facilitator;
+    private readonly receiver;
+    private readonly token;
+    private readonly network;
+    private timers;
+    private lastClaimTime;
+    private lastSettleTime;
+    private pendingSettle;
+    private running;
+    private pendingJobs;
+    private drainingJobs;
+    private autoSettleConfig;
+    /**
+     * Creates a new channel manager.
+     *
+     * @param config - Manager configuration: scheme, facilitator, receiver, token, network.
+     */
+    constructor(config: ChannelManagerConfig);
+    /**
+     * Collects claimable vouchers and submits them in batches to the facilitator via `claim()`.
+     *
+     * @param opts - Optional claim execution and target selection options.
+     * @param opts.maxClaimsPerBatch - Max vouchers per facilitator `claim` batch.
+     * @param opts.idleSecs - When set, only include channels idle for at least this many seconds.
+     * @param opts.selectClaimChannels - Optional selector for choosing channels before claimability checks.
+     * @returns Array of claim results (one per batch).
+     */
+    claim(opts?: ClaimOptions): Promise<ClaimResult[]>;
+    /**
+     * Transfers claimed (but unsettled) funds to the receiver by calling `settle(receiver, token)`.
+     *
+     * @returns Settle result with the transaction hash.
+     */
+    settle(): Promise<SettleResult>;
+    /**
+     * Convenience: claims all eligible vouchers then settles in one call.
+     *
+     * @param opts - Optional claim execution and target selection options.
+     * @param opts.maxClaimsPerBatch - Max vouchers per claim batch before settling.
+     * @param opts.idleSecs - When set, only include channels idle for at least this many seconds.
+     * @param opts.selectClaimChannels - Optional selector for choosing channels before claimability checks.
+     * @returns Combined claim and settle results.
+     */
+    claimAndSettle(opts?: ClaimOptions): Promise<{
+        claims: ClaimResult[];
+        settle?: SettleResult;
+    }>;
+    /**
+     * Initiates cooperative refunds for one or more channels.
+     *
+     * @param channelIds - Specific channels to refund; defaults to all sessions.
+     * @returns One result per successfully refunded channel.
+     */
+    refund(channelIds?: string[]): Promise<RefundResult[]>;
+    /**
+     * Refunds idle channels with non-zero balances.
+     *
+     * @param opts - Idle refund options.
+     * @param opts.idleSecs - Minimum seconds since the last request.
+     * @returns One result per successfully refunded channel.
+     */
+    refundIdleChannels(opts: {
+        idleSecs: number;
+    }): Promise<RefundResult[]>;
+    /**
+     * Collects vouchers that are eligible for onchain claiming.
+     *
+     * A voucher is claimable when its `chargedCumulativeAmount` exceeds what has already
+     * been claimed onchain.  An optional idle filter skips sessions that received a
+     * request within the last `idleSecs` seconds.
+     *
+     * @param opts - Optional filtering: `idleSecs` to only return idle channels.
+     * @param opts.idleSecs - Minimum seconds since last request for a channel to be included.
+     * @returns Array of {@link BatchSettlementVoucherClaim} entries for batch submission.
+     */
+    getClaimableVouchers(opts?: {
+        idleSecs?: number;
+    }): Promise<BatchSettlementVoucherClaim[]>;
+    /**
+     * Returns channels that have a pending payer-initiated withdrawal.
+     *
+     * @returns All stored channel records with `withdrawRequestedAt` set.
+     */
+    getWithdrawalPendingSessions(): Promise<Channel[]>;
+    /**
+     * Starts auto-settlement jobs for configured claim, settle, and refund intervals.
+     *
+     * @param config - Auto-settlement policy configuration.
+     */
+    start(config?: AutoSettlementConfig): void;
+    /**
+     * Stops the auto-settlement loop.
+     *
+     * @param opts - Stop options.
+     * @param opts.flush - When true, run `claimAndSettle` before stopping.
+     * @returns Resolves when the loop is stopped (and flush work completes, if requested).
+     */
+    stop(opts?: {
+        flush?: boolean;
+    }): Promise<void>;
+    /**
+     * Refunds a single channel and removes it from storage after success.
+     *
+     * @param target - Channel to refund.
+     * @returns Successful refund transaction.
+     */
+    private refundChannel;
+    /**
+     * Starts a recurring timer for one auto job.
+     *
+     * @param job - Job to enqueue when the interval fires.
+     * @param intervalSecs - Timer interval in seconds.
+     */
+    private startAutoTimer;
+    /**
+     * Adds an auto job to the coalescing queue.
+     *
+     * @param job - Job to run.
+     */
+    private enqueueJob;
+    /**
+     * Drains queued auto jobs in priority order.
+     */
+    private drainJobs;
+    /**
+     * Returns the highest-priority queued auto job.
+     *
+     * @returns Next job to run.
+     */
+    private nextPendingJob;
+    /**
+     * Runs one auto job.
+     *
+     * @param job - Job to run.
+     */
+    private runAutoJob;
+    /**
+     * Runs the claim auto job.
+     */
+    private runClaimJob;
+    /**
+     * Runs the settlement auto job.
+     */
+    private runSettleJob;
+    /**
+     * Runs the refund auto job.
+     */
+    private runRefundJob;
+    /**
+     * Claims vouchers from a provided channel snapshot.
+     *
+     * @param channels - Channels to inspect for claimable vouchers.
+     * @param opts - Claim batching and filtering options.
+     * @param opts.maxClaimsPerBatch - Max vouchers per facilitator claim transaction.
+     * @param opts.idleSecs - Optional idle filter.
+     * @returns Claim results, one per submitted batch.
+     */
+    private claimFromChannels;
+    /**
+     * Loads stored channels and applies the configured claim selector, if any.
+     *
+     * @param opts - Claim options containing an optional target selector.
+     * @returns The channel snapshot that should be inspected for claimable vouchers.
+     */
+    private selectClaimTargets;
+    /**
+     * Refunds each eligible channel independently.
+     *
+     * @param channels - Channels to refund.
+     * @returns Successful refund results.
+     */
+    private refundChannels;
+    /**
+     * Builds an outstanding voucher claim for a refund payload.
+     *
+     * @param channel - Channel being refunded.
+     * @returns Claim payloads needed before refunding unclaimed balance.
+     */
+    private buildRefundClaims;
+    /**
+     * Builds the policy context passed to interval hooks.
+     *
+     * @param now - Current wall-clock time in milliseconds.
+     * @returns Auto-settlement policy context.
+     */
+    private buildAutoSettlementContext;
+    /**
+     * Collects claimable vouchers from a provided channel snapshot.
+     *
+     * @param channels - Channels to inspect.
+     * @param opts - Optional idle filter.
+     * @param opts.idleSecs - Minimum seconds since last request.
+     * @returns Claimable voucher payloads.
+     */
+    private getClaimableVouchersFromChannels;
+    /**
+     * Filters idle channels that can be cooperatively refunded.
+     *
+     * @param channels - Channels to inspect.
+     * @param idleSecs - Minimum seconds since the last request.
+     * @returns Idle refundable channels.
+     */
+    private getIdleChannelsForRefundFromChannels;
+    /**
+     * Returns channels that have been idle longer than `idleSecs` and still have
+     * a non-zero balance (candidates for cooperative refund).
+     *
+     * @param idleSecs - Minimum seconds since last request for a session to count as idle.
+     * @returns Channels meeting the idle and balance criteria.
+     */
+    private getIdleChannelsForRefund;
+    /**
+     * Submits a batch of voucher claims to the facilitator.
+     *
+     * @param claims - Voucher claims to send in one `type: "claim"` payload.
+     * @returns Per-batch claim summary (count and transaction hash).
+     */
+    private submitClaim;
+    /**
+     * Builds a settlement payment payload for `settle(receiver, token)`.
+     *
+     * @returns Payload with `type: "settle"` and receiver/token fields.
+     */
+    private buildSettlePaymentPayload;
+    /**
+     * Builds a minimal {@link PaymentRequirements} for channel manager operations.
+     *
+     * @returns Requirements describing batched operations for this manager.
+     */
+    private buildPaymentRequirements;
+    /**
+     * Updates session records after a successful claim submission so that
+     * `getClaimableVouchers` no longer returns already-claimed vouchers.
+     *
+     * @param claims - Voucher claims that were included in the submitted settlement transaction.
+     */
+    private updateClaimedSessions;
+}
+
+/**
+ * Adds server channel state to corrective 402 responses for cumulative mismatches.
+ *
+ * @param scheme - Owning `BatchSettlementEvmScheme` instance for storage access.
+ * @param ctx - Payment-required response context.
+ */
+declare function handleEnrichPaymentRequiredResponse(scheme: BatchSettlementEvmScheme, ctx: SchemePaymentRequiredContext): Promise<void>;
+
+interface BatchSettlementEvmSchemeServerConfig {
+    storage?: ChannelStorage;
+    receiverAuthorizerSigner?: AuthorizerSigner;
+    withdrawDelay?: number;
+    onchainStateTtlMs?: number;
+}
+interface BatchSettlementRequestContext {
+    channelId?: string;
+    pendingId?: string;
+    channelSnapshot?: Channel;
+    localVerify?: boolean;
+}
+/**
+ * Server-side implementation of the `batch-settlement` scheme for EVM networks.
+ */
+declare class BatchSettlementEvmScheme implements SchemeNetworkServer {
+    readonly scheme: "batch-settlement";
+    readonly schemeHooks: SchemeServerHooks;
+    private readonly requestContexts;
+    private moneyParsers;
+    private readonly storage;
+    private readonly receiverAuthorizerSigner;
+    private readonly receiverAddress;
+    private readonly withdrawDelay;
+    private readonly onchainStateTtlMs;
+    /**
+     * Constructs a batched server scheme.
+     *
+     * @param receiverAddress - The server's receiver address (payTo).
+     * @param config - Optional configuration for storage, receiver-authorizer signer, and withdraw delay.
+     */
+    constructor(receiverAddress: `0x${string}`, config?: BatchSettlementEvmSchemeServerConfig);
+    /**
+     * Adds server-owned settlement fields before facilitator settlement.
+     *
+     * @param ctx - Settlement context for the current payment.
+     * @returns Additive payload fields, or nothing when no enrichment is needed.
+     */
+    enrichSettlementPayload: (ctx: SettleContext) => Promise<Record<string, unknown> | void>;
+    /**
+     * Adds corrective channel state to payment-required responses when available.
+     *
+     * @param ctx - Payment-required response context for the current request.
+     * @returns Updated payment requirements, or nothing when no enrichment is needed.
+     */
+    enrichPaymentRequiredResponse: (ctx: Parameters<typeof handleEnrichPaymentRequiredResponse>[1]) => Promise<PaymentRequirements[] | void>;
+    /**
+     * Adds server-owned extra fields after facilitator settlement.
+     *
+     * @param ctx - Settlement result context for the current payment.
+     * @returns Additive response extra fields, or nothing when no enrichment is needed.
+     */
+    enrichSettlementResponse: (ctx: SettleResultContext) => Promise<Record<string, unknown> | void>;
+    /**
+     * Merges batch-settlement state into the current request context.
+     *
+     * @param payload - Request-scoped payment payload object.
+     * @param context - Partial context fields to merge.
+     */
+    mergeRequestContext(payload: DeepReadonly<PaymentPayload>, context: BatchSettlementRequestContext): void;
+    /**
+     * Reads batch-settlement state for the current request without clearing it.
+     *
+     * @param payload - Request-scoped payment payload object.
+     * @returns Request context, if one was recorded.
+     */
+    readRequestContext(payload: DeepReadonly<PaymentPayload>): BatchSettlementRequestContext | undefined;
+    /**
+     * Reads and clears batch-settlement state for the current request.
+     *
+     * @param payload - Request-scoped payment payload object.
+     * @returns Request context, if one was recorded.
+     */
+    takeRequestContext(payload: DeepReadonly<PaymentPayload>): BatchSettlementRequestContext | undefined;
+    /**
+     * Stores a channel snapshot for the current settlement request.
+     *
+     * @param payload - Request-scoped payment payload object.
+     * @param channel - Channel state to use during response enrichment.
+     */
+    rememberChannelSnapshot(payload: DeepReadonly<PaymentPayload>, channel: Channel): void;
+    /**
+     * Reads and clears a channel snapshot for the current settlement request.
+     *
+     * @param payload - Request-scoped payment payload object.
+     * @returns Stored channel state, if one was recorded.
+     */
+    takeChannelSnapshot(payload: DeepReadonly<PaymentPayload>): Channel | undefined;
+    /**
+     * Clears this request's pending reservation without touching newer reservations.
+     *
+     * @param payload - Request-scoped payment payload object.
+     */
+    clearPendingRequest(payload: DeepReadonly<PaymentPayload>): Promise<void>;
+    /**
+     * Registers a custom money parser for converting price strings to token amounts.
+     *
+     * @param parser - A parser function to try before the default USD→token conversion.
+     * @returns `this` for chaining.
+     */
+    registerMoneyParser(parser: MoneyParser): BatchSettlementEvmScheme;
+    /**
+     * Resolves a human-readable price (e.g. `"$0.01"`) into an onchain token amount.
+     *
+     * @param price - A price string, number, or explicit {@link AssetAmount}.
+     * @param network - CAIP-2 network identifier for looking up the default asset.
+     * @returns Token amount with asset address and metadata.
+     */
+    parsePrice(price: Price, network: Network): Promise<AssetAmount>;
+    /**
+     * Injects batched-specific fields into the payment requirements returned to
+     * the client (receiverAuthorizer, withdrawDelay, EIP-712 domain info).
+     *
+     * @param paymentRequirements - Base payment requirements from the middleware.
+     * @param supportedKind - Matched scheme/network kind (extra may contain overrides).
+     * @param supportedKind.x402Version - Protocol version from the matched kind.
+     * @param supportedKind.scheme - Scheme name from the matched kind.
+     * @param supportedKind.network - Network identifier from the matched kind.
+     * @param supportedKind.extra - Optional extra fields on the matched kind.
+     * @param _extensionKeys - Extension keys (unused).
+     * @returns Enhanced payment requirements with batched fields in `extra`.
+     */
+    enhancePaymentRequirements(paymentRequirements: PaymentRequirements, supportedKind: {
+        x402Version: number;
+        scheme: string;
+        network: Network;
+        extra?: Record<string, unknown>;
+    }, _extensionKeys: string[]): Promise<PaymentRequirements>;
+    /**
+     * Returns the underlying channel storage instance.
+     *
+     * @returns The configured {@link ChannelStorage} backend.
+     */
+    getStorage(): ChannelStorage;
+    /**
+     * Returns the server's receiver address.
+     *
+     * @returns Receiver wallet address for the payment channel.
+     */
+    getReceiverAddress(): `0x${string}`;
+    /**
+     * Returns the configured withdraw delay (seconds).
+     *
+     * @returns Withdraw delay in seconds before uncooperative withdrawal is allowed.
+     */
+    getWithdrawDelay(): number;
+    /**
+     * Returns how long mirrored onchain channel state is trusted for local voucher verification.
+     *
+     * @returns Freshness window in milliseconds.
+     */
+    getOnchainStateTtlMs(): number;
+    /**
+     * Returns the receiver-authorizer signer, if configured.
+     *
+     * @returns Receiver-authorizer signer, or `undefined` when not set.
+     */
+    getReceiverAuthorizerSigner(): AuthorizerSigner | undefined;
+    /**
+     * Creates a {@link BatchSettlementChannelManager} pre-configured with this scheme's
+     * receiver, default token for the given network, and the provided facilitator.
+     *
+     * @param facilitator - Facilitator client for submitting onchain claims/settlements.
+     * @param network - CAIP-2 network identifier (e.g. `"eip155:84532"`).
+     * @returns A ready-to-use channel manager.
+     */
+    createChannelManager(facilitator: FacilitatorClient, network: Network): BatchSettlementChannelManager;
+    /**
+     * Parses a human-readable money string (e.g. `"$1.50"`) into a decimal number.
+     *
+     * @param money - Money string (may include `$`) or numeric amount.
+     * @returns Parsed finite number.
+     */
+    private parseMoneyToDecimal;
+    /**
+     * Converts a decimal dollar amount to the network's default token amount.
+     *
+     * @param amount - Decimal amount in display units.
+     * @param network - Target chain/network for default asset resolution.
+     * @returns {@link AssetAmount} with integer token amount, contract address, and metadata.
+     */
+    private defaultMoneyConversion;
+}
+
+export { AuthorizerSigner, type AutoSettlementConfig, type AutoSettlementContext, BatchSettlementChannelManager, BatchSettlementEvmScheme, type BatchSettlementEvmSchemeServerConfig, type BatchSettlementRequestContext, Channel, type ChannelManagerConfig, ChannelStorage, type ClaimChannelSelector, type ClaimOptions, type ClaimResult, type RefundResult, type SettleResult };