@bankofai/x402-evm 1.0.0-beta.0

package/dist/esm/batch-settlement/facilitator/index.mjs

@@ -0,0 +1,1252 @@
+import {
+  erc3009AuthorizationTimeInvalidReason,
+  readChannelState,
+  signClaimBatch,
+  signRefund,
+  toContractChannelConfig,
+  validateChannelConfig,
+  verifyBatchSettlementVoucherTypedData
+} from "../../chunk-SHJFA25H.mjs";
+import {
+  buildEip2612PermitData,
+  buildErc3009CollectorData,
+  buildErc3009DepositNonce,
+  buildPermit2CollectorData
+} from "../../chunk-W6ON4LG2.mjs";
+import {
+  BATCH_SETTLEMENT_ADDRESS,
+  BATCH_SETTLEMENT_SCHEME,
+  ERC3009_DEPOSIT_COLLECTOR_ADDRESS,
+  ErrAuthorizerAddressMismatch,
+  ErrChannelIdMismatch,
+  ErrChannelNotFound,
+  ErrClaimSimulationFailed,
+  ErrClaimTransactionFailed,
+  ErrCumulativeAmountBelowClaimed,
+  ErrCumulativeExceedsBalance,
+  ErrDepositSimulationFailed,
+  ErrDepositTransactionFailed,
+  ErrEip2612AmountMismatch,
+  ErrErc20ApprovalUnavailable,
+  ErrErc3009AuthorizationRequired,
+  ErrInsufficientBalance,
+  ErrInvalidPayloadType,
+  ErrInvalidReceiveAuthorizationSignature,
+  ErrInvalidScheme,
+  ErrInvalidVoucherSignature,
+  ErrMissingEip712Domain,
+  ErrNetworkMismatch,
+  ErrNothingToSettle,
+  ErrPermit2AllowanceRequired,
+  ErrPermit2AmountMismatch,
+  ErrPermit2AuthorizationRequired,
+  ErrPermit2DeadlineExpired,
+  ErrPermit2InvalidSignature,
+  ErrPermit2InvalidSpender,
+  ErrRefundNoBalance,
+  ErrRefundSimulationFailed,
+  ErrRefundTransactionFailed,
+  ErrRpcReadFailed,
+  ErrSettleSimulationFailed,
+  ErrSettleTransactionFailed,
+  ErrTokenMismatch,
+  PERMIT2_DEPOSIT_COLLECTOR_ADDRESS,
+  batchPermit2WitnessTypes,
+  batchSettlementABI,
+  computeChannelId,
+  erc20BalanceOfABI,
+  receiveAuthorizationTypes
+} from "../../chunk-HYABYUBD.mjs";
+import {
+  isBatchSettlementClaimPayload,
+  isBatchSettlementDepositPayload,
+  isBatchSettlementEnrichedRefundPayload,
+  isBatchSettlementRefundPayload,
+  isBatchSettlementSettlePayload,
+  isBatchSettlementVoucherPayload
+} from "../../chunk-U4HCGTLU.mjs";
+import {
+  splitEip2612Signature,
+  validateEip2612PermitForPayment,
+  validateErc20ApprovalForPayment
+} from "../../chunk-H2EYJIZL.mjs";
+import "../../chunk-P3QOX3QZ.mjs";
+import {
+  ERC20_APPROVAL_GAS_SPONSORING_KEY,
+  appendDataSuffix,
+  extractEip2612GasSponsoringInfo,
+  extractErc20ApprovalGasSponsoringInfo,
+  resolveDataSuffix,
+  resolveErc20ApprovalExtensionSigner
+} from "../../chunk-JNT7C46S.mjs";
+import {
+  PERMIT2_ADDRESS,
+  erc20AllowanceAbi
+} from "../../chunk-MACPBXCT.mjs";
+import {
+  multicall
+} from "../../chunk-VS3RYAYE.mjs";
+import {
+  getEvmChainId
+} from "../../chunk-TW7Z65AO.mjs";
+
+// src/batch-settlement/facilitator/deposit.ts
+import { getAddress as getAddress3 } from "viem";
+
+// src/batch-settlement/facilitator/deposit-eip3009.ts
+import { getAddress, parseErc6492Signature } from "viem";
+function getEip3009DepositCollectorAddress() {
+  return getAddress(ERC3009_DEPOSIT_COLLECTOR_ADDRESS);
+}
+function buildEip3009DepositCollectorData(payload) {
+  const auth = payload.deposit.authorization.erc3009Authorization;
+  if (!auth) {
+    throw new Error(ErrErc3009AuthorizationRequired);
+  }
+  const { signature } = parseErc6492Signature(auth.signature);
+  return buildErc3009CollectorData(auth.validAfter, auth.validBefore, auth.salt, signature);
+}
+async function verifyEip3009DepositAuthorization(signer, payload, requirements, chainId) {
+  const { deposit, voucher } = payload;
+  const payer = payload.channelConfig.payer;
+  const auth = deposit.authorization.erc3009Authorization;
+  if (!auth) {
+    return { isValid: false, invalidReason: ErrErc3009AuthorizationRequired, payer };
+  }
+  const extra = requirements.extra;
+  if (!extra?.name || !extra?.version) {
+    return { isValid: false, invalidReason: ErrMissingEip712Domain, payer };
+  }
+  const validAfter = BigInt(auth.validAfter);
+  const validBefore = BigInt(auth.validBefore);
+  const timeInvalid = erc3009AuthorizationTimeInvalidReason(validAfter, validBefore);
+  if (timeInvalid) {
+    return { isValid: false, invalidReason: timeInvalid, payer };
+  }
+  const erc3009Nonce = buildErc3009DepositNonce(voucher.channelId, auth.salt);
+  const receiveAuthOk = await verifyReceiveAuth(signer, {
+    payer,
+    asset: requirements.asset,
+    name: extra.name,
+    version: extra.version,
+    chainId,
+    amount: deposit.amount,
+    validAfter,
+    validBefore,
+    nonce: erc3009Nonce,
+    signature: auth.signature
+  });
+  if (!receiveAuthOk) {
+    return { isValid: false, invalidReason: ErrInvalidReceiveAuthorizationSignature, payer };
+  }
+  return null;
+}
+async function verifyReceiveAuth(signer, params) {
+  try {
+    return await signer.verifyTypedData({
+      address: getAddress(params.payer),
+      domain: {
+        name: params.name,
+        version: params.version,
+        chainId: params.chainId,
+        verifyingContract: getAddress(params.asset)
+      },
+      types: receiveAuthorizationTypes,
+      primaryType: "ReceiveWithAuthorization",
+      message: {
+        from: getAddress(params.payer),
+        to: getAddress(ERC3009_DEPOSIT_COLLECTOR_ADDRESS),
+        value: BigInt(params.amount),
+        validAfter: params.validAfter,
+        validBefore: params.validBefore,
+        nonce: params.nonce
+      },
+      signature: params.signature
+    });
+  } catch {
+    return false;
+  }
+}
+
+// src/batch-settlement/facilitator/deposit-permit2.ts
+import { encodeFunctionData, getAddress as getAddress2, parseErc6492Signature as parseErc6492Signature2 } from "viem";
+function getPermit2DepositCollectorAddress() {
+  return getAddress2(PERMIT2_DEPOSIT_COLLECTOR_ADDRESS);
+}
+function buildPermit2DepositCollectorData(payload, eip2612PermitData = "0x") {
+  const auth = payload.deposit.authorization.permit2Authorization;
+  if (!auth) {
+    throw new Error(ErrPermit2AuthorizationRequired);
+  }
+  const { signature } = parseErc6492Signature2(auth.signature);
+  return buildPermit2CollectorData(auth.nonce, auth.deadline, signature, eip2612PermitData);
+}
+async function verifyPermit2DepositAuthorization(signer, payment, payload, requirements, chainId, context) {
+  const authResult = await verifyPermit2TypedData(signer, payload, requirements, chainId);
+  if (authResult) {
+    return authResult;
+  }
+  const branchResult = await resolvePermit2DepositBranch(
+    signer,
+    payment,
+    payload,
+    requirements,
+    context
+  );
+  if ("isValid" in branchResult) {
+    return branchResult;
+  }
+  if (branchResult.kind !== "erc20Approval" || !branchResult.extensionSigner.simulateTransactions) {
+    return null;
+  }
+  const ok = await branchResult.extensionSigner.simulateTransactions([
+    branchResult.signedTransaction,
+    buildDepositTransaction(payload, branchResult.collectorData)
+  ]);
+  if (!ok) {
+    return {
+      isValid: false,
+      invalidReason: ErrDepositSimulationFailed,
+      payer: payload.channelConfig.payer
+    };
+  }
+  return null;
+}
+async function resolvePermit2DepositBranch(signer, payment, payload, requirements, context) {
+  const payer = payload.channelConfig.payer;
+  const tokenAddress = getAddress2(requirements.asset);
+  const eip2612Info = extractEip2612GasSponsoringInfo(payment);
+  if (eip2612Info) {
+    const result = validateBatchEip2612Permit(
+      eip2612Info,
+      payer,
+      tokenAddress,
+      payload.deposit.amount
+    );
+    if (!result.isValid) {
+      return { isValid: false, invalidReason: result.invalidReason, payer };
+    }
+    const { v, r, s } = splitEip2612Signature(eip2612Info.signature);
+    return {
+      kind: "eip2612",
+      collectorData: buildPermit2DepositCollectorData(
+        payload,
+        buildEip2612PermitData({
+          value: eip2612Info.amount,
+          deadline: eip2612Info.deadline,
+          v,
+          r,
+          s
+        })
+      )
+    };
+  }
+  const erc20Info = extractErc20ApprovalGasSponsoringInfo(payment);
+  if (erc20Info) {
+    const extensionSigner = resolveErc20ApprovalExtensionSigner(
+      context?.getExtension(
+        ERC20_APPROVAL_GAS_SPONSORING_KEY
+      ),
+      requirements.network
+    );
+    if (!extensionSigner) {
+      return { isValid: false, invalidReason: ErrErc20ApprovalUnavailable, payer };
+    }
+    const result = await validateErc20ApprovalForPayment(erc20Info, payer, tokenAddress);
+    if (!result.isValid) {
+      return {
+        isValid: false,
+        invalidReason: result.invalidReason,
+        invalidMessage: result.invalidMessage,
+        payer
+      };
+    }
+    return {
+      kind: "erc20Approval",
+      collectorData: buildPermit2DepositCollectorData(payload),
+      signedTransaction: erc20Info.signedTransaction,
+      extensionSigner
+    };
+  }
+  try {
+    const allowance = await signer.readContract({
+      address: tokenAddress,
+      abi: erc20AllowanceAbi,
+      functionName: "allowance",
+      args: [payer, PERMIT2_ADDRESS]
+    });
+    if (allowance < BigInt(payload.deposit.amount)) {
+      return { isValid: false, invalidReason: ErrPermit2AllowanceRequired, payer };
+    }
+  } catch {
+    return { isValid: false, invalidReason: ErrPermit2AllowanceRequired, payer };
+  }
+  return {
+    kind: "standard",
+    collectorData: buildPermit2DepositCollectorData(payload)
+  };
+}
+function buildDepositTransaction(payload, collectorData, dataSuffix) {
+  const data = encodeFunctionData({
+    abi: batchSettlementABI,
+    functionName: "deposit",
+    args: [
+      toContractChannelConfig(payload.channelConfig),
+      BigInt(payload.deposit.amount),
+      getPermit2DepositCollectorAddress(),
+      collectorData
+    ]
+  });
+  return {
+    to: getAddress2(BATCH_SETTLEMENT_ADDRESS),
+    data: appendDataSuffix(data, dataSuffix),
+    gas: 300000n
+  };
+}
+async function verifyPermit2TypedData(signer, payload, requirements, chainId) {
+  const auth = payload.deposit.authorization.permit2Authorization;
+  const payer = payload.channelConfig.payer;
+  if (!auth) {
+    return { isValid: false, invalidReason: ErrPermit2AuthorizationRequired, payer };
+  }
+  if (getAddress2(auth.from) !== getAddress2(payer)) {
+    return { isValid: false, invalidReason: ErrPermit2InvalidSignature, payer };
+  }
+  if (getAddress2(auth.spender) !== getPermit2DepositCollectorAddress()) {
+    return { isValid: false, invalidReason: ErrPermit2InvalidSpender, payer };
+  }
+  if (getAddress2(auth.permitted.token) !== getAddress2(requirements.asset)) {
+    return { isValid: false, invalidReason: ErrTokenMismatch, payer };
+  }
+  if (BigInt(auth.permitted.amount) !== BigInt(payload.deposit.amount)) {
+    return { isValid: false, invalidReason: ErrPermit2AmountMismatch, payer };
+  }
+  if (auth.witness.channelId !== payload.voucher.channelId) {
+    return { isValid: false, invalidReason: ErrChannelIdMismatch, payer };
+  }
+  const now = Math.floor(Date.now() / 1e3);
+  if (BigInt(auth.deadline) < BigInt(now + 6)) {
+    return { isValid: false, invalidReason: ErrPermit2DeadlineExpired, payer };
+  }
+  try {
+    const ok = await signer.verifyTypedData({
+      address: getAddress2(auth.from),
+      domain: { name: "Permit2", chainId, verifyingContract: PERMIT2_ADDRESS },
+      types: batchPermit2WitnessTypes,
+      primaryType: "PermitWitnessTransferFrom",
+      message: {
+        permitted: {
+          token: getAddress2(auth.permitted.token),
+          amount: BigInt(auth.permitted.amount)
+        },
+        spender: getAddress2(auth.spender),
+        nonce: BigInt(auth.nonce),
+        deadline: BigInt(auth.deadline),
+        witness: {
+          channelId: auth.witness.channelId
+        }
+      },
+      signature: auth.signature
+    });
+    if (!ok) {
+      return { isValid: false, invalidReason: ErrPermit2InvalidSignature, payer };
+    }
+  } catch {
+    return { isValid: false, invalidReason: ErrPermit2InvalidSignature, payer };
+  }
+  return null;
+}
+function validateBatchEip2612Permit(info, payer, tokenAddress, depositAmount) {
+  const baseline = validateEip2612PermitForPayment(info, payer, tokenAddress);
+  if (!baseline.isValid) {
+    return {
+      isValid: false,
+      invalidReason: baseline.invalidReason ?? ErrInvalidPayloadType
+    };
+  }
+  if (BigInt(info.amount) !== BigInt(depositAmount)) {
+    return { isValid: false, invalidReason: ErrEip2612AmountMismatch };
+  }
+  return { isValid: true };
+}
+
+// src/batch-settlement/facilitator/deposit.ts
+async function verifyDeposit(signer, payment, payload, requirements, context) {
+  const payer = payload.channelConfig.payer;
+  const chainId = getEvmChainId(requirements.network);
+  const configErr = validateChannelConfig(
+    payload.channelConfig,
+    payload.voucher.channelId,
+    requirements
+  );
+  if (configErr) {
+    return { isValid: false, invalidReason: configErr, payer };
+  }
+  const transferMethod = resolveDepositTransferMethod(payload, requirements);
+  if (transferMethod === "permit2" && !payload.deposit.authorization.permit2Authorization) {
+    return { isValid: false, invalidReason: ErrInvalidPayloadType, payer };
+  }
+  const methodErr = transferMethod === "permit2" ? await verifyPermit2DepositAuthorization(
+    signer,
+    payment,
+    payload,
+    requirements,
+    chainId,
+    context
+  ) : await verifyEip3009DepositAuthorization(signer, payload, requirements, chainId);
+  if (methodErr) {
+    return methodErr;
+  }
+  const shared = await verifySharedDepositState(signer, payload, requirements);
+  if (!shared.ok) {
+    return shared.response;
+  }
+  const { depositAmount, chBalance, chTotalClaimed, wdInitiatedAt, refundNonceVal } = shared;
+  const execution = await resolveDepositExecution(signer, payment, payload, requirements, context);
+  if ("isValid" in execution) {
+    return execution;
+  }
+  if (!execution.skipDirectSimulation) {
+    try {
+      await signer.readContract({
+        address: getAddress3(BATCH_SETTLEMENT_ADDRESS),
+        abi: batchSettlementABI,
+        functionName: "deposit",
+        args: [
+          toContractChannelConfig(payload.channelConfig),
+          depositAmount,
+          execution.collector,
+          execution.collectorData
+        ]
+      });
+    } catch (e) {
+      return {
+        isValid: false,
+        invalidReason: ErrDepositSimulationFailed,
+        invalidMessage: e instanceof Error ? e.message : String(e),
+        payer
+      };
+    }
+  }
+  return {
+    isValid: true,
+    payer,
+    extra: {
+      channelId: payload.voucher.channelId,
+      balance: chBalance.toString(),
+      totalClaimed: chTotalClaimed.toString(),
+      withdrawRequestedAt: Number(wdInitiatedAt),
+      refundNonce: refundNonceVal.toString()
+    }
+  };
+}
+async function verifySharedDepositState(signer, payload, requirements) {
+  const { deposit, voucher } = payload;
+  const config = payload.channelConfig;
+  const payer = config.payer;
+  const chainId = getEvmChainId(requirements.network);
+  const configErr = validateChannelConfig(config, voucher.channelId, requirements);
+  if (configErr) {
+    return { ok: false, response: { isValid: false, invalidReason: configErr, payer } };
+  }
+  const voucherOk = await verifyBatchSettlementVoucherTypedData(
+    signer,
+    {
+      channelId: voucher.channelId,
+      maxClaimableAmount: voucher.maxClaimableAmount,
+      payerAuthorizer: config.payerAuthorizer,
+      payer: config.payer,
+      signature: voucher.signature
+    },
+    chainId
+  );
+  if (!voucherOk) {
+    return {
+      ok: false,
+      response: { isValid: false, invalidReason: ErrInvalidVoucherSignature, payer }
+    };
+  }
+  const mcResults = await multicall(signer.readContract.bind(signer), [
+    {
+      address: getAddress3(BATCH_SETTLEMENT_ADDRESS),
+      abi: batchSettlementABI,
+      functionName: "channels",
+      args: [voucher.channelId]
+    },
+    {
+      address: getAddress3(requirements.asset),
+      abi: erc20BalanceOfABI,
+      functionName: "balanceOf",
+      args: [getAddress3(payer)]
+    },
+    {
+      address: getAddress3(BATCH_SETTLEMENT_ADDRESS),
+      abi: batchSettlementABI,
+      functionName: "pendingWithdrawals",
+      args: [voucher.channelId]
+    },
+    {
+      address: getAddress3(BATCH_SETTLEMENT_ADDRESS),
+      abi: batchSettlementABI,
+      functionName: "refundNonce",
+      args: [voucher.channelId]
+    }
+  ]);
+  const [chRes, balRes, wdRes, rnRes] = mcResults;
+  if (chRes.status === "failure" || balRes.status === "failure" || wdRes.status === "failure" || rnRes.status === "failure") {
+    return {
+      ok: false,
+      response: { isValid: false, invalidReason: ErrRpcReadFailed, payer }
+    };
+  }
+  const [chBalance, chTotalClaimed] = chRes.result;
+  const payerBalance = balRes.result;
+  const [, wdInitiatedAt] = wdRes.result;
+  const refundNonceVal = rnRes.result;
+  const depositAmount = BigInt(deposit.amount);
+  if (payerBalance < depositAmount) {
+    return {
+      ok: false,
+      response: { isValid: false, invalidReason: ErrInsufficientBalance, payer }
+    };
+  }
+  const effectiveBalance = chBalance + depositAmount;
+  const maxClaimableAmount = BigInt(voucher.maxClaimableAmount);
+  if (maxClaimableAmount > effectiveBalance) {
+    return {
+      ok: false,
+      response: { isValid: false, invalidReason: ErrCumulativeExceedsBalance, payer }
+    };
+  }
+  if (maxClaimableAmount <= chTotalClaimed) {
+    return {
+      ok: false,
+      response: { isValid: false, invalidReason: ErrCumulativeAmountBelowClaimed, payer }
+    };
+  }
+  return {
+    ok: true,
+    chainId,
+    depositAmount,
+    payer,
+    chBalance,
+    chTotalClaimed,
+    wdInitiatedAt,
+    refundNonceVal
+  };
+}
+async function settleDeposit(signer, payment, payload, requirements, context, dataSuffix) {
+  const { deposit, voucher } = payload;
+  const config = payload.channelConfig;
+  const payer = config.payer;
+  const verified = await verifyDeposit(signer, payment, payload, requirements, context);
+  if (!verified.isValid) {
+    const reason = verified.invalidReason ?? ErrInvalidPayloadType;
+    return {
+      success: false,
+      errorReason: reason,
+      errorMessage: verified.invalidMessage ?? reason,
+      transaction: "",
+      network: requirements.network,
+      payer: verified.payer
+    };
+  }
+  try {
+    const execution = await resolveDepositExecution(
+      signer,
+      payment,
+      payload,
+      requirements,
+      context
+    );
+    if ("isValid" in execution) {
+      const reason = execution.invalidReason ?? ErrInvalidPayloadType;
+      return {
+        success: false,
+        errorReason: reason,
+        errorMessage: execution.invalidMessage ?? reason,
+        transaction: "",
+        network: requirements.network,
+        payer: execution.payer
+      };
+    }
+    const depositTx = buildDepositTransaction(payload, execution.collectorData, dataSuffix);
+    const tx = execution.kind === "erc20Approval" ? (await execution.extensionSigner.sendTransactions([
+      execution.signedTransaction,
+      depositTx
+    ]))[1] : await signer.writeContract({
+      address: getAddress3(BATCH_SETTLEMENT_ADDRESS),
+      abi: batchSettlementABI,
+      functionName: "deposit",
+      args: [
+        toContractChannelConfig(config),
+        BigInt(deposit.amount),
+        execution.collector,
+        execution.collectorData
+      ],
+      dataSuffix
+    });
+    const receipt = await signer.waitForTransactionReceipt({ hash: tx });
+    if (receipt.status !== "success") {
+      return {
+        success: false,
+        errorReason: ErrDepositTransactionFailed,
+        errorMessage: `transaction reverted (receipt status ${receipt.status})`,
+        transaction: tx,
+        network: requirements.network,
+        payer
+      };
+    }
+    const optimisticExtra = {
+      channelState: {
+        channelId: voucher.channelId,
+        balance: (BigInt(String(verified.extra?.balance ?? "0")) + BigInt(deposit.amount)).toString(),
+        totalClaimed: String(verified.extra?.totalClaimed ?? "0"),
+        withdrawRequestedAt: Number(verified.extra?.withdrawRequestedAt ?? 0),
+        refundNonce: String(verified.extra?.refundNonce ?? "0")
+      }
+    };
+    const expectedMinBalance = BigInt(optimisticExtra.channelState.balance);
+    const rpcDeadline = Date.now() + 2e3;
+    let postState = await readChannelState(signer, voucher.channelId);
+    while (postState.balance < expectedMinBalance && Date.now() < rpcDeadline) {
+      await new Promise((resolve) => setTimeout(resolve, 150));
+      postState = await readChannelState(signer, voucher.channelId);
+    }
+    const rpcCaughtUp = postState.balance >= expectedMinBalance;
+    return {
+      success: true,
+      transaction: tx,
+      network: requirements.network,
+      payer,
+      amount: deposit.amount,
+      extra: rpcCaughtUp ? {
+        ...optimisticExtra,
+        channelState: {
+          channelId: voucher.channelId,
+          balance: postState.balance.toString(),
+          totalClaimed: postState.totalClaimed.toString(),
+          withdrawRequestedAt: postState.withdrawRequestedAt,
+          refundNonce: postState.refundNonce.toString()
+        }
+      } : optimisticExtra
+    };
+  } catch (e) {
+    return {
+      success: false,
+      errorReason: ErrDepositTransactionFailed,
+      errorMessage: e instanceof Error ? e.message : String(e),
+      transaction: "",
+      network: requirements.network,
+      payer
+    };
+  }
+}
+async function resolveDepositExecution(signer, payment, payload, requirements, context) {
+  const transferMethod = resolveDepositTransferMethod(payload, requirements);
+  if (transferMethod === "eip3009") {
+    return {
+      kind: "direct",
+      collector: getEip3009DepositCollectorAddress(),
+      collectorData: buildEip3009DepositCollectorData(payload)
+    };
+  }
+  const branch = await resolvePermit2DepositBranch(signer, payment, payload, requirements, context);
+  if ("isValid" in branch) {
+    return branch;
+  }
+  if (branch.kind === "erc20Approval") {
+    return {
+      kind: "erc20Approval",
+      collector: getPermit2DepositCollectorAddress(),
+      collectorData: branch.collectorData,
+      signedTransaction: branch.signedTransaction,
+      extensionSigner: branch.extensionSigner,
+      skipDirectSimulation: true
+    };
+  }
+  return {
+    kind: "direct",
+    collector: getPermit2DepositCollectorAddress(),
+    collectorData: branch.collectorData
+  };
+}
+function resolveDepositTransferMethod(payload, requirements) {
+  const hinted = requirements.extra?.assetTransferMethod;
+  if (hinted) {
+    return hinted;
+  }
+  return payload.deposit.authorization.permit2Authorization ? "permit2" : "eip3009";
+}
+
+// src/batch-settlement/facilitator/voucher.ts
+async function verifyVoucher(signer, payload, requirements, channelConfig) {
+  const { voucher } = payload;
+  const channelId = voucher.channelId;
+  const chainId = getEvmChainId(requirements.network);
+  const configErr = validateChannelConfig(channelConfig, channelId, requirements);
+  if (configErr) {
+    return { isValid: false, invalidReason: configErr, payer: channelConfig.payer };
+  }
+  const voucherOk = await verifyBatchSettlementVoucherTypedData(
+    signer,
+    {
+      channelId,
+      maxClaimableAmount: voucher.maxClaimableAmount,
+      payerAuthorizer: channelConfig.payerAuthorizer,
+      payer: channelConfig.payer,
+      signature: voucher.signature
+    },
+    chainId
+  );
+  if (!voucherOk) {
+    return {
+      isValid: false,
+      invalidReason: ErrInvalidVoucherSignature,
+      payer: channelConfig.payer
+    };
+  }
+  const state = await readChannelState(signer, channelId);
+  if (state.balance === 0n) {
+    return { isValid: false, invalidReason: ErrChannelNotFound, payer: channelConfig.payer };
+  }
+  const maxClaimableAmount = BigInt(voucher.maxClaimableAmount);
+  if (maxClaimableAmount > state.balance) {
+    return {
+      isValid: false,
+      invalidReason: ErrCumulativeExceedsBalance,
+      payer: channelConfig.payer
+    };
+  }
+  const belowClaimed = payload.type === "refund" ? maxClaimableAmount < state.totalClaimed : maxClaimableAmount <= state.totalClaimed;
+  if (belowClaimed) {
+    return {
+      isValid: false,
+      invalidReason: ErrCumulativeAmountBelowClaimed,
+      payer: channelConfig.payer
+    };
+  }
+  return {
+    isValid: true,
+    payer: channelConfig.payer,
+    extra: {
+      channelId,
+      balance: state.balance.toString(),
+      totalClaimed: state.totalClaimed.toString(),
+      withdrawRequestedAt: state.withdrawRequestedAt,
+      refundNonce: state.refundNonce.toString()
+    }
+  };
+}
+
+// src/batch-settlement/facilitator/claim.ts
+import { getAddress as getAddress4 } from "viem";
+function buildVoucherClaimArgs(claims) {
+  return claims.map((c) => ({
+    voucher: {
+      channel: toContractChannelConfig(c.voucher.channel),
+      maxClaimableAmount: BigInt(c.voucher.maxClaimableAmount)
+    },
+    signature: c.signature,
+    totalClaimed: BigInt(c.totalClaimed)
+  }));
+}
+async function executeClaimWithSignature(signer, payload, requirements, authorizerSigner, dataSuffix) {
+  const network = requirements.network;
+  const claimArgs = buildVoucherClaimArgs(payload.claims);
+  let sig = payload.claimAuthorizerSignature;
+  if (!sig) {
+    for (const claim of payload.claims) {
+      if (getAddress4(claim.voucher.channel.receiverAuthorizer) !== getAddress4(authorizerSigner.address)) {
+        return {
+          success: false,
+          errorReason: ErrAuthorizerAddressMismatch,
+          transaction: "",
+          network
+        };
+      }
+    }
+    sig = await signClaimBatch(authorizerSigner, payload.claims, network);
+  }
+  try {
+    await signer.readContract({
+      address: getAddress4(BATCH_SETTLEMENT_ADDRESS),
+      abi: batchSettlementABI,
+      functionName: "claimWithSignature",
+      args: [claimArgs, sig]
+    });
+  } catch (e) {
+    return {
+      success: false,
+      errorReason: ErrClaimSimulationFailed,
+      errorMessage: e instanceof Error ? e.message : String(e),
+      transaction: "",
+      network
+    };
+  }
+  try {
+    const tx = await signer.writeContract({
+      address: getAddress4(BATCH_SETTLEMENT_ADDRESS),
+      abi: batchSettlementABI,
+      functionName: "claimWithSignature",
+      args: [claimArgs, sig],
+      dataSuffix
+    });
+    const receipt = await signer.waitForTransactionReceipt({ hash: tx });
+    if (receipt.status !== "success") {
+      return {
+        success: false,
+        errorReason: ErrClaimTransactionFailed,
+        errorMessage: `transaction reverted (receipt status ${receipt.status})`,
+        transaction: tx,
+        network
+      };
+    }
+    return {
+      success: true,
+      transaction: tx,
+      network,
+      amount: ""
+    };
+  } catch (e) {
+    return {
+      success: false,
+      errorReason: ErrClaimTransactionFailed,
+      errorMessage: e instanceof Error ? e.message : String(e),
+      transaction: "",
+      network
+    };
+  }
+}
+
+// src/batch-settlement/facilitator/settle.ts
+import { getAddress as getAddress5, isAddressEqual, parseEventLogs } from "viem";
+var SETTLE_GAS_LIMIT = 120000n;
+async function executeSettle(signer, payload, requirements, dataSuffix) {
+  const network = requirements.network;
+  const contractAddr = getAddress5(BATCH_SETTLEMENT_ADDRESS);
+  const receiver = getAddress5(payload.receiver);
+  const token = getAddress5(payload.token);
+  try {
+    const [totalClaimed, totalSettled] = await signer.readContract({
+      address: contractAddr,
+      abi: batchSettlementABI,
+      functionName: "receivers",
+      args: [receiver, token]
+    });
+    if (totalClaimed <= totalSettled) {
+      return {
+        success: false,
+        errorReason: ErrNothingToSettle,
+        errorMessage: "nothing to settle for receiver and token",
+        transaction: "",
+        network
+      };
+    }
+  } catch (e) {
+    return {
+      success: false,
+      errorReason: ErrRpcReadFailed,
+      errorMessage: e instanceof Error ? e.message : String(e),
+      transaction: "",
+      network
+    };
+  }
+  try {
+    await signer.readContract({
+      address: contractAddr,
+      abi: batchSettlementABI,
+      functionName: "settle",
+      args: [receiver, token]
+    });
+  } catch (e) {
+    return {
+      success: false,
+      errorReason: ErrSettleSimulationFailed,
+      errorMessage: e instanceof Error ? e.message : String(e),
+      transaction: "",
+      network
+    };
+  }
+  try {
+    const tx = await signer.writeContract({
+      address: contractAddr,
+      abi: batchSettlementABI,
+      functionName: "settle",
+      args: [receiver, token],
+      gas: SETTLE_GAS_LIMIT,
+      dataSuffix
+    });
+    const receipt = await signer.waitForTransactionReceipt({ hash: tx });
+    if (receipt.status !== "success") {
+      return {
+        success: false,
+        errorReason: ErrSettleTransactionFailed,
+        errorMessage: `transaction reverted (receipt status ${receipt.status})`,
+        transaction: tx,
+        network
+      };
+    }
+    let amount = "";
+    if (receipt.logs) {
+      const logs = parseEventLogs({
+        abi: batchSettlementABI,
+        eventName: "Settled",
+        logs: receipt.logs.filter((log) => isAddressEqual(log.address, contractAddr))
+      });
+      const settledLog = logs.find(
+        (log) => isAddressEqual(log.args.receiver, receiver) && isAddressEqual(log.args.token, token)
+      );
+      amount = settledLog?.args.amount.toString() ?? "0";
+    }
+    return {
+      success: true,
+      transaction: tx,
+      network,
+      amount
+    };
+  } catch (e) {
+    return {
+      success: false,
+      errorReason: ErrSettleTransactionFailed,
+      errorMessage: e instanceof Error ? e.message : String(e),
+      transaction: "",
+      network
+    };
+  }
+}
+
+// src/batch-settlement/facilitator/refund.ts
+import { encodeFunctionData as encodeFunctionData2, getAddress as getAddress6 } from "viem";
+var REFUND_STATE_POLL_MS = 2e3;
+var REFUND_STATE_POLL_INTERVAL_MS = 150;
+function getRefundableAmount(payload, preState, channelId, network) {
+  const postClaimTotalClaimed = payload.claims.reduce((max, claim) => {
+    const claimChannelId = computeChannelId(claim.voucher.channel, network);
+    if (claimChannelId.toLowerCase() !== channelId.toLowerCase()) {
+      return max;
+    }
+    const totalClaimed = BigInt(claim.totalClaimed);
+    return totalClaimed > max ? totalClaimed : max;
+  }, preState.totalClaimed);
+  if (postClaimTotalClaimed > preState.balance) {
+    return null;
+  }
+  const requestedAmount = BigInt(payload.amount);
+  if (requestedAmount === 0n) {
+    return null;
+  }
+  const available = preState.balance - postClaimTotalClaimed;
+  return requestedAmount > available ? available : requestedAmount;
+}
+function buildRefundExtra(payload, channelId, preState) {
+  const preTotalClaimed = preState?.totalClaimed ?? 0n;
+  const preBalance = preState?.balance ?? 0n;
+  const lastClaimTotal = payload.claims.length > 0 ? BigInt(payload.claims[payload.claims.length - 1].totalClaimed) : preTotalClaimed;
+  const postClaimTotalClaimed = lastClaimTotal > preTotalClaimed ? lastClaimTotal : preTotalClaimed;
+  const available = preBalance - postClaimTotalClaimed;
+  const requestedAmount = BigInt(payload.amount);
+  const actualRefund = requestedAmount > available ? available : requestedAmount;
+  return {
+    amount: actualRefund.toString(),
+    extra: {
+      channelState: {
+        channelId,
+        balance: (preBalance - actualRefund).toString(),
+        totalClaimed: postClaimTotalClaimed.toString(),
+        withdrawRequestedAt: 0,
+        refundNonce: String((preState?.refundNonce ?? 0n) + 1n)
+      }
+    }
+  };
+}
+async function readPostRefundState(signer, channelId, submittedNonce) {
+  const expectedNonce = BigInt(submittedNonce) + 1n;
+  const deadline = Date.now() + REFUND_STATE_POLL_MS;
+  do {
+    let state;
+    try {
+      state = await readChannelState(signer, channelId);
+    } catch {
+      return null;
+    }
+    if (state.refundNonce >= expectedNonce) {
+      return state;
+    }
+    await new Promise((resolve) => setTimeout(resolve, REFUND_STATE_POLL_INTERVAL_MS));
+  } while (Date.now() < deadline);
+  return null;
+}
+function buildRefundExtraFromPostState(channelId, preState, postState) {
+  const actualRefund = preState.balance > postState.balance ? preState.balance - postState.balance : 0n;
+  return {
+    amount: actualRefund.toString(),
+    extra: {
+      channelState: {
+        channelId,
+        balance: postState.balance.toString(),
+        totalClaimed: postState.totalClaimed.toString(),
+        withdrawRequestedAt: postState.withdrawRequestedAt,
+        refundNonce: postState.refundNonce.toString()
+      }
+    }
+  };
+}
+async function executeRefundWithSignature(signer, payload, requirements, authorizerSigner, dataSuffix) {
+  const network = requirements.network;
+  try {
+    const channelId = computeChannelId(payload.channelConfig, network);
+    const preState = await readChannelState(signer, channelId);
+    const contractAddr = getAddress6(BATCH_SETTLEMENT_ADDRESS);
+    const refundableAmount = getRefundableAmount(payload, preState, channelId, network);
+    if (refundableAmount === 0n) {
+      return {
+        success: false,
+        errorReason: ErrRefundNoBalance,
+        errorMessage: "Nothing to refund",
+        transaction: "",
+        network
+      };
+    }
+    const hasClientSig = payload.refundAuthorizerSignature !== void 0;
+    const authorizerMismatch = getAddress6(payload.channelConfig.receiverAuthorizer) !== getAddress6(authorizerSigner.address);
+    if (!hasClientSig && authorizerMismatch) {
+      return {
+        success: false,
+        errorReason: ErrAuthorizerAddressMismatch,
+        transaction: "",
+        network
+      };
+    }
+    const refundSig = payload.refundAuthorizerSignature ?? await signRefund(authorizerSigner, channelId, payload.amount, payload.refundNonce, network);
+    const refundCalldata = encodeFunctionData2({
+      abi: batchSettlementABI,
+      functionName: "refundWithSignature",
+      args: [
+        toContractChannelConfig(payload.channelConfig),
+        BigInt(payload.amount),
+        BigInt(payload.refundNonce),
+        refundSig
+      ]
+    });
+    let tx;
+    if (payload.claims.length > 0) {
+      let claimSig = payload.claimAuthorizerSignature;
+      if (!claimSig) {
+        claimSig = await signClaimBatch(authorizerSigner, payload.claims, network);
+      }
+      const claimCalldata = encodeFunctionData2({
+        abi: batchSettlementABI,
+        functionName: "claimWithSignature",
+        args: [buildVoucherClaimArgs(payload.claims), claimSig]
+      });
+      try {
+        await signer.readContract({
+          address: contractAddr,
+          abi: batchSettlementABI,
+          functionName: "multicall",
+          args: [[claimCalldata, refundCalldata]]
+        });
+      } catch (e) {
+        return {
+          success: false,
+          errorReason: ErrRefundSimulationFailed,
+          errorMessage: e instanceof Error ? e.message : String(e),
+          transaction: "",
+          network
+        };
+      }
+      tx = await signer.writeContract({
+        address: contractAddr,
+        abi: batchSettlementABI,
+        functionName: "multicall",
+        args: [[claimCalldata, refundCalldata]],
+        dataSuffix
+      });
+    } else {
+      try {
+        await signer.readContract({
+          address: contractAddr,
+          abi: batchSettlementABI,
+          functionName: "refundWithSignature",
+          args: [
+            toContractChannelConfig(payload.channelConfig),
+            BigInt(payload.amount),
+            BigInt(payload.refundNonce),
+            refundSig
+          ]
+        });
+      } catch (e) {
+        return {
+          success: false,
+          errorReason: ErrRefundSimulationFailed,
+          errorMessage: e instanceof Error ? e.message : String(e),
+          transaction: "",
+          network
+        };
+      }
+      tx = await signer.writeContract({
+        address: contractAddr,
+        abi: batchSettlementABI,
+        functionName: "refundWithSignature",
+        args: [
+          toContractChannelConfig(payload.channelConfig),
+          BigInt(payload.amount),
+          BigInt(payload.refundNonce),
+          refundSig
+        ],
+        dataSuffix
+      });
+    }
+    const receipt = await signer.waitForTransactionReceipt({ hash: tx });
+    if (receipt.status !== "success") {
+      return {
+        success: false,
+        errorReason: ErrRefundTransactionFailed,
+        errorMessage: `transaction reverted (receipt status ${receipt.status})`,
+        transaction: tx,
+        network
+      };
+    }
+    const postState = preState && preState.withdrawRequestedAt !== 0 ? await readPostRefundState(signer, channelId, payload.refundNonce) : null;
+    const refundDetails = preState && postState ? buildRefundExtraFromPostState(channelId, preState, postState) : buildRefundExtra(payload, channelId, preState);
+    return {
+      success: true,
+      transaction: tx,
+      network,
+      payer: payload.channelConfig.payer,
+      amount: refundDetails.amount,
+      extra: refundDetails.extra
+    };
+  } catch (e) {
+    return {
+      success: false,
+      errorReason: ErrRefundTransactionFailed,
+      errorMessage: e instanceof Error ? e.message : String(e),
+      transaction: "",
+      network
+    };
+  }
+}
+
+// src/batch-settlement/facilitator/scheme.ts
+var BatchSettlementEvmScheme = class {
+  /**
+   * Creates a facilitator scheme for verifying and settling batch-settlement payments.
+   *
+   * @param signer - Facilitator EVM signer(s) used for tx submission and onchain reads.
+   * @param authorizerSigner - Dedicated key that provides EIP-712 signatures for
+   *   `claimWithSignature` / `refundWithSignature`.  The facilitator will sign missing
+   *   authorizer signatures using this key when the server omits them.
+   */
+  constructor(signer, authorizerSigner) {
+    this.signer = signer;
+    this.authorizerSigner = authorizerSigner;
+    this.scheme = BATCH_SETTLEMENT_SCHEME;
+    this.caipFamily = "eip155:*";
+  }
+  /**
+   * Returns facilitator-specific extra fields to be merged into payment requirements.
+   *
+   * Exposes the configured `receiverAuthorizer` address so the server and client can
+   * embed it in `ChannelConfig`.
+   *
+   * @param _ - Network identifier (unused).
+   * @returns Extra fields containing `receiverAuthorizer`.
+   */
+  getExtra(_) {
+    return { receiverAuthorizer: this.authorizerSigner.address };
+  }
+  /**
+   * Returns all facilitator signer addresses available for the given network.
+   *
+   * @param _ - Network identifier (unused).
+   * @returns Array of hex addresses.
+   */
+  getSigners(_) {
+    return [...this.signer.getAddresses()];
+  }
+  /**
+   * Verifies a payment payload (deposit or voucher) without executing settlement.
+   *
+   * @param payload - The x402 payment payload envelope.
+   * @param requirements - Server payment requirements (scheme, network, asset, amount).
+   * @param context - Optional facilitator extension context.
+   * @param _ - Payment required extensions (unused; reserved for interface parity)
+   * @returns A {@link VerifyResponse} indicating validity with payer and channel state in `extra`.
+   */
+  async verify(payload, requirements, context, _) {
+    const rawPayload = payload.payload;
+    if (payload.accepted.scheme !== BATCH_SETTLEMENT_SCHEME || requirements.scheme !== BATCH_SETTLEMENT_SCHEME) {
+      return { isValid: false, invalidReason: ErrInvalidScheme };
+    }
+    if (payload.accepted.network !== requirements.network) {
+      return { isValid: false, invalidReason: ErrNetworkMismatch };
+    }
+    if (isBatchSettlementDepositPayload(rawPayload)) {
+      return verifyDeposit(this.signer, payload, rawPayload, requirements, context);
+    }
+    if (isBatchSettlementVoucherPayload(rawPayload)) {
+      return verifyVoucher(this.signer, rawPayload, requirements, rawPayload.channelConfig);
+    }
+    if (isBatchSettlementRefundPayload(rawPayload)) {
+      return verifyVoucher(this.signer, rawPayload, requirements, rawPayload.channelConfig);
+    }
+    return { isValid: false, invalidReason: ErrInvalidPayloadType };
+  }
+  /**
+   * Executes settlement for a payment payload.
+   *
+   * Dispatches to the correct handler based on payload settle action:
+   * - `deposit` → onchain `deposit(config, amount, collector, collectorData)`
+   * - `claim` → onchain `claimWithSignature(VoucherClaim[], bytes)`
+   * - `settle` → onchain `settle(receiver, token)`
+   * - `refund` → optional claim + onchain `refundWithSignature(config, amount, nonce, sig)`
+   *
+   * @param payload - The x402 payment payload envelope.
+   * @param requirements - Server payment requirements.
+   * @param context - Optional facilitator extension context.
+   * @returns A {@link SettleResponse} with the transaction hash on success.
+   */
+  async settle(payload, requirements, context) {
+    const rawPayload = payload.payload;
+    const dataSuffix = await resolveDataSuffix(context, {
+      paymentPayload: payload,
+      paymentRequirements: requirements
+    });
+    if (isBatchSettlementDepositPayload(rawPayload)) {
+      return settleDeposit(this.signer, payload, rawPayload, requirements, context, dataSuffix);
+    }
+    if (isBatchSettlementClaimPayload(rawPayload)) {
+      return executeClaimWithSignature(
+        this.signer,
+        rawPayload,
+        requirements,
+        this.authorizerSigner,
+        dataSuffix
+      );
+    }
+    if (isBatchSettlementEnrichedRefundPayload(rawPayload)) {
+      return executeRefundWithSignature(
+        this.signer,
+        rawPayload,
+        requirements,
+        this.authorizerSigner,
+        dataSuffix
+      );
+    }
+    if (isBatchSettlementSettlePayload(rawPayload)) {
+      return executeSettle(this.signer, rawPayload, requirements, dataSuffix);
+    }
+    return {
+      success: false,
+      errorReason: ErrInvalidPayloadType,
+      transaction: "",
+      network: requirements.network
+    };
+  }
+};
+export {
+  BatchSettlementEvmScheme
+};
+//# sourceMappingURL=index.mjs.map