moltspay 1.6.0 → 2.4.0

package/dist/facilitators/index.mjs

@@ -851,12 +851,12 @@ var BNBFacilitator = class extends BaseFacilitator {
     return this.spenderAddress;
   }
   async getServerAddress() {
-    const { ethers: ethers2 } = await import("ethers");
-    const wallet = new ethers2.Wallet(this.serverPrivateKey);
+    const { ethers: ethers3 } = await import("ethers");
+    const wallet = new ethers3.Wallet(this.serverPrivateKey);
     return wallet.address;
   }
   async recoverIntentSigner(intent, chainId) {
-    const { ethers: ethers2 } = await import("ethers");
+    const { ethers: ethers3 } = await import("ethers");
     const domain = {
       ...EIP712_DOMAIN,
       chainId
@@ -870,7 +870,7 @@ var BNBFacilitator = class extends BaseFacilitator {
       nonce: intent.nonce,
       deadline: intent.deadline
     };
-    const recoveredAddress = ethers2.verifyTypedData(
+    const recoveredAddress = ethers3.verifyTypedData(
       domain,
       INTENT_TYPES,
       message,
@@ -914,10 +914,10 @@ var BNBFacilitator = class extends BaseFacilitator {
     return result.result || "0x0";
   }
   async executeTransferFrom(from, to, amount, token, rpcUrl) {
-    const { ethers: ethers2 } = await import("ethers");
-    const provider = new ethers2.JsonRpcProvider(rpcUrl);
-    const wallet = new ethers2.Wallet(this.serverPrivateKey, provider);
-    const tokenContract = new ethers2.Contract(token, [
+    const { ethers: ethers3 } = await import("ethers");
+    const provider = new ethers3.JsonRpcProvider(rpcUrl);
+    const wallet = new ethers3.Wallet(this.serverPrivateKey, provider);
+    const tokenContract = new ethers3.Contract(token, [
       "function transferFrom(address from, address to, uint256 amount) returns (bool)"
     ], wallet);
     const tx = await tokenContract.transferFrom(from, to, amount);
@@ -1218,6 +1218,1239 @@ async function createSolanaPaymentTransaction(senderPubkey, recipientPubkey, amo
   return transaction;
 }
 
+// src/facilitators/alipay.ts
+import crypto2 from "crypto";
+
+// src/facilitators/alipay/rsa2.ts
+import crypto from "crypto";
+function rsa2Sign(data, privateKeyPem) {
+  const signer = crypto.createSign("RSA-SHA256");
+  signer.update(data, "utf-8");
+  signer.end();
+  return signer.sign(privateKeyPem, "base64");
+}
+
+// src/facilitators/alipay/encoding.ts
+function base64url(input) {
+  return Buffer.from(input, "utf-8").toString("base64url");
+}
+function decodeBase64UrlWithPadFix(input) {
+  const normalized = input.replace(/-/g, "+").replace(/_/g, "/");
+  const padded = normalized + "=".repeat((4 - normalized.length % 4) % 4);
+  return Buffer.from(padded, "base64").toString("utf-8");
+}
+
+// src/facilitators/alipay/openapi.ts
+function formatAlipayTimestamp(d = /* @__PURE__ */ new Date()) {
+  const pad = (n) => String(n).padStart(2, "0");
+  return `${d.getFullYear()}-${pad(d.getMonth() + 1)}-${pad(d.getDate())} ${pad(d.getHours())}:${pad(d.getMinutes())}:${pad(d.getSeconds())}`;
+}
+function buildSigningString(params) {
+  return Object.keys(params).sort().map((k) => `${k}=${params[k]}`).join("&");
+}
+function responseWrapperKey(method) {
+  return `${method.replace(/\./g, "_")}_response`;
+}
+async function alipayOpenApiCall(method, bizContent, config) {
+  const publicParams = {
+    app_id: config.app_id,
+    method,
+    format: "JSON",
+    charset: "utf-8",
+    sign_type: config.sign_type ?? "RSA2",
+    timestamp: formatAlipayTimestamp(),
+    version: "1.0",
+    biz_content: JSON.stringify(bizContent)
+  };
+  const signingString = buildSigningString(publicParams);
+  const sign = rsa2Sign(signingString, config.private_key_pem);
+  const body = new URLSearchParams({ ...publicParams, sign }).toString();
+  const response = await fetch(config.gateway_url, {
+    method: "POST",
+    headers: {
+      "Content-Type": "application/x-www-form-urlencoded;charset=utf-8"
+    },
+    body
+  });
+  if (!response.ok) {
+    const text = await response.text().catch(() => "<unreadable>");
+    throw new Error(
+      `Alipay Open API HTTP ${response.status} for ${method}: ${text.slice(0, 500)}`
+    );
+  }
+  const json = await response.json();
+  const wrapperKey = responseWrapperKey(method);
+  const business = json[wrapperKey];
+  if (business === void 0 || business === null || typeof business !== "object") {
+    throw new Error(
+      `Alipay Open API response missing "${wrapperKey}" wrapper for ${method}: ${JSON.stringify(json).slice(0, 500)}`
+    );
+  }
+  return business;
+}
+
+// src/facilitators/alipay.ts
+var ALIPAY_NETWORK = "alipay";
+var ALIPAY_SCHEME = "alipay-aipay";
+var ALIPAY_GATEWAY_PROD = "https://openapi.alipay.com/gateway.do";
+var ALIPAY_GATEWAY_SANDBOX = "https://openapi.alipaydev.com/gateway.do";
+var ALIPAY_AMOUNT_REGEX = /^\d+(\.\d{1,2})?$/;
+var ALIPAY_PAY_BEFORE_MS = 30 * 60 * 1e3;
+var ALIPAY_SIGNING_FIELDS = [
+  "amount",
+  "currency",
+  "goods_name",
+  "out_trade_no",
+  "pay_before",
+  "resource_id",
+  "seller_id",
+  "service_id"
+];
+var AlipayFacilitator = class extends BaseFacilitator {
+  name = "alipay";
+  displayName = "Alipay AI Pay";
+  supportedNetworks = [ALIPAY_NETWORK];
+  config;
+  constructor(config) {
+    super();
+    this.config = {
+      gateway_url: ALIPAY_GATEWAY_PROD,
+      sign_type: "RSA2",
+      ...config
+    };
+  }
+  /**
+   * Build the 402 challenge for a service: signs the 8-field payload with
+   * RSA2, packages the nested `{protocol, method}` JSON as Base64URL for
+   * `Payment-Needed`, and emits the parallel x402 `accepts[]` entry.
+   */
+  async createPaymentRequirements(opts) {
+    if (!ALIPAY_AMOUNT_REGEX.test(opts.priceCny)) {
+      throw new Error(
+        `AlipayFacilitator.createPaymentRequirements: priceCny "${opts.priceCny}" does not match /^\\d+(\\.\\d{1,2})?$/ (unit is yuan, not fen; e.g. "1.00" not "100")`
+      );
+    }
+    const now = /* @__PURE__ */ new Date();
+    const outTradeNo = opts.outTradeNo ?? generateOutTradeNo();
+    const payBefore = formatPayBefore(now);
+    const signedFields = {
+      amount: opts.priceCny,
+      currency: "CNY",
+      goods_name: opts.goodsName,
+      out_trade_no: outTradeNo,
+      pay_before: payBefore,
+      resource_id: opts.resourceId,
+      seller_id: this.config.seller_id,
+      service_id: opts.serviceId
+    };
+    const signingString = ALIPAY_SIGNING_FIELDS.map((k) => `${k}=${signedFields[k]}`).join("&");
+    const seller_signature = rsa2Sign(signingString, this.config.private_key_pem);
+    const challenge = {
+      protocol: {
+        out_trade_no: outTradeNo,
+        amount: signedFields.amount,
+        currency: signedFields.currency,
+        resource_id: signedFields.resource_id,
+        pay_before: payBefore,
+        seller_signature,
+        seller_sign_type: this.config.sign_type ?? "RSA2",
+        seller_unique_id: this.config.seller_id
+      },
+      method: {
+        seller_name: this.config.seller_name,
+        seller_id: this.config.seller_id,
+        seller_app_id: this.config.app_id,
+        goods_name: signedFields.goods_name,
+        seller_unique_id_key: "seller_id",
+        service_id: signedFields.service_id
+      }
+    };
+    const paymentNeededHeader = base64url(JSON.stringify(challenge));
+    const x402Accepts = {
+      scheme: ALIPAY_SCHEME,
+      network: ALIPAY_NETWORK,
+      asset: "CNY",
+      amount: opts.priceCny,
+      payTo: this.config.seller_id,
+      maxTimeoutSeconds: ALIPAY_PAY_BEFORE_MS / 1e3,
+      extra: {
+        payment_needed_header: paymentNeededHeader,
+        out_trade_no: outTradeNo,
+        pay_before: payBefore,
+        service_id: signedFields.service_id
+      }
+    };
+    return { x402Accepts, paymentNeededHeader };
+  }
+  /**
+   * Verify a `Payment-Proof` by calling
+   * `alipay.aipay.agent.payment.verify` against the Alipay Open API.
+   *
+   * The proof is conveyed via `paymentPayload.payload`, which may be:
+   * - a raw Base64URL string (the `Payment-Proof` header value), or
+   * - an object `{ paymentProof: string }` / `{ proofHeader: string }`.
+   *
+   * All failure modes (malformed payload, network errors, Alipay
+   * `code != 10000`) return `{ valid: false, error }`. No exception
+   * escapes, regardless of client-supplied input.
+   */
+  async verify(paymentPayload, _requirements) {
+    try {
+      const proofHeader = extractProofHeader(paymentPayload.payload);
+      const decoded = decodeProof(proofHeader);
+      const response = await alipayOpenApiCall(
+        "alipay.aipay.agent.payment.verify",
+        {
+          payment_proof: decoded.protocol.payment_proof,
+          trade_no: decoded.protocol.trade_no,
+          client_session: decoded.method.client_session
+        },
+        this.getOpenApiConfig()
+      );
+      if (response.code !== "10000") {
+        return {
+          valid: false,
+          error: `alipay verify ${response.code}: ${response.sub_msg ?? response.msg ?? "unknown"}`,
+          details: {
+            code: response.code,
+            sub_code: response.sub_code,
+            sub_msg: response.sub_msg
+          }
+        };
+      }
+      return {
+        valid: true,
+        details: {
+          trade_no: response.trade_no ?? decoded.protocol.trade_no,
+          amount: response.amount,
+          out_trade_no: response.out_trade_no,
+          resource_id: response.resource_id,
+          active: response.active
+        }
+      };
+    } catch (e) {
+      return {
+        valid: false,
+        error: e instanceof Error ? e.message : String(e)
+      };
+    }
+  }
+  /**
+   * Settle by calling `alipay.aipay.agent.fulfillment.confirm` after the
+   * service resource has been returned to the buyer.
+   *
+   * Per the design (see ALIPAY-INTEGRATION-DESIGN.md §5.1, risk row
+   * (a fulfillment-confirm failure), this is **fire-and-forget**: the caller (registry /
+   * server) is expected to log fulfillment failures but NOT roll back
+   * the already-delivered resource.
+   *
+   * Re-decodes `paymentPayload.payload` to extract `trade_no` (verify
+   * does the same; the redundant Base64URL decode is negligible).
+   */
+  async settle(paymentPayload, _requirements) {
+    try {
+      const proofHeader = extractProofHeader(paymentPayload.payload);
+      const decoded = decodeProof(proofHeader);
+      const tradeNo = decoded.protocol.trade_no;
+      const response = await alipayOpenApiCall(
+        "alipay.aipay.agent.fulfillment.confirm",
+        { trade_no: tradeNo },
+        this.getOpenApiConfig()
+      );
+      if (response.code !== "10000") {
+        return {
+          success: false,
+          transaction: tradeNo,
+          error: `alipay fulfillment ${response.code}: ${response.sub_msg ?? response.msg ?? "unknown"}`,
+          status: "fulfillment_failed"
+        };
+      }
+      return {
+        success: true,
+        transaction: tradeNo,
+        status: "fulfilled"
+      };
+    } catch (e) {
+      return {
+        success: false,
+        error: e instanceof Error ? e.message : String(e)
+      };
+    }
+  }
+  /**
+   * Validate that the configured RSA keys parse and that the Open API
+   * gateway is reachable. Does NOT make a real business API call (would
+   * burn quota and could appear as a legitimate verify attempt in logs).
+   */
+  async healthCheck() {
+    const start = Date.now();
+    try {
+      crypto2.createPrivateKey(this.config.private_key_pem);
+    } catch (e) {
+      return {
+        healthy: false,
+        error: `merchant private_key_pem parse failed: ${e instanceof Error ? e.message : String(e)}`
+      };
+    }
+    try {
+      crypto2.createPublicKey(this.config.alipay_public_key_pem);
+    } catch (e) {
+      return {
+        healthy: false,
+        error: `alipay_public_key_pem parse failed: ${e instanceof Error ? e.message : String(e)}`
+      };
+    }
+    const gatewayUrl = this.config.gateway_url ?? ALIPAY_GATEWAY_PROD;
+    const controller = new AbortController();
+    const timeout = setTimeout(() => controller.abort(), 5e3);
+    const response = await fetch(gatewayUrl, {
+      method: "HEAD",
+      signal: controller.signal
+    }).catch(() => null);
+    clearTimeout(timeout);
+    const latencyMs = Date.now() - start;
+    if (!response) {
+      return { healthy: false, error: `gateway unreachable: ${gatewayUrl}`, latencyMs };
+    }
+    return { healthy: true, latencyMs };
+  }
+  /** Bundle the facilitator config into the shape openapi.ts wants. */
+  getOpenApiConfig() {
+    return {
+      gateway_url: this.config.gateway_url ?? ALIPAY_GATEWAY_PROD,
+      app_id: this.config.app_id,
+      private_key_pem: this.config.private_key_pem,
+      alipay_public_key_pem: this.config.alipay_public_key_pem,
+      sign_type: this.config.sign_type
+    };
+  }
+};
+function generateOutTradeNo() {
+  return "VID" + crypto2.randomBytes(22).toString("base64url").slice(0, 29);
+}
+function formatPayBefore(now) {
+  const expiry = new Date(now.getTime() + ALIPAY_PAY_BEFORE_MS);
+  return expiry.toISOString().replace(/\.\d{3}Z$/, "Z");
+}
+function extractProofHeader(payload) {
+  if (typeof payload === "string") {
+    if (payload.length === 0) {
+      throw new Error("alipay Payment-Proof is empty");
+    }
+    return payload;
+  }
+  if (payload !== null && typeof payload === "object") {
+    const obj = payload;
+    const candidate = obj.paymentProof ?? obj.proofHeader;
+    if (typeof candidate === "string" && candidate.length > 0) {
+      return candidate;
+    }
+  }
+  throw new Error(
+    "alipay payment payload must be a Base64URL string or {paymentProof: string} / {proofHeader: string}"
+  );
+}
+function decodeProof(proofHeader) {
+  let parsed;
+  try {
+    parsed = JSON.parse(decodeBase64UrlWithPadFix(proofHeader));
+  } catch (e) {
+    throw new Error(
+      `failed to decode Payment-Proof: ${e instanceof Error ? e.message : String(e)}`
+    );
+  }
+  if (parsed === null || typeof parsed !== "object") {
+    throw new Error("decoded Payment-Proof is not an object");
+  }
+  const obj = parsed;
+  const protocol = obj.protocol;
+  const method = obj.method;
+  if (!protocol || typeof protocol.payment_proof !== "string") {
+    throw new Error("decoded Payment-Proof missing protocol.payment_proof");
+  }
+  if (typeof protocol.trade_no !== "string") {
+    throw new Error("decoded Payment-Proof missing protocol.trade_no");
+  }
+  if (!method || typeof method.client_session !== "string") {
+    throw new Error("decoded Payment-Proof missing method.client_session");
+  }
+  return parsed;
+}
+
+// src/facilitators/wechat.ts
+import crypto4 from "crypto";
+
+// src/facilitators/wechat/sign.ts
+import crypto3 from "crypto";
+var WECHAT_AUTH_SCHEMA = "WECHATPAY2-SHA256-RSA2048";
+function buildRequestMessage(method, urlPath, timestamp, nonce, body) {
+  return `${method.toUpperCase()}
+${urlPath}
+${timestamp}
+${nonce}
+${body}
+`;
+}
+function wechatV3Sign(method, urlPath, timestamp, nonce, body, privateKeyPem) {
+  const message = buildRequestMessage(method, urlPath, timestamp, nonce, body);
+  const signer = crypto3.createSign("RSA-SHA256");
+  signer.update(message, "utf-8");
+  signer.end();
+  return signer.sign(privateKeyPem, "base64");
+}
+function buildAuthorizationToken(args) {
+  const fields = [
+    `mchid="${args.mchid}"`,
+    `nonce_str="${args.nonce}"`,
+    `signature="${args.signature}"`,
+    `timestamp="${args.timestamp}"`,
+    `serial_no="${args.serialNo}"`
+  ].join(",");
+  return `${WECHAT_AUTH_SCHEMA} ${fields}`;
+}
+function wechatV3VerifyResponse(timestamp, nonce, body, signature, platformPublicKeyPem) {
+  try {
+    const message = `${timestamp}
+${nonce}
+${body}
+`;
+    const verifier = crypto3.createVerify("RSA-SHA256");
+    verifier.update(message, "utf-8");
+    verifier.end();
+    return verifier.verify(platformPublicKeyPem, signature, "base64");
+  } catch {
+    return false;
+  }
+}
+function generateNonce() {
+  return crypto3.randomBytes(16).toString("hex");
+}
+
+// src/facilitators/wechat/api.ts
+var WECHAT_API_BASE = "https://api.mch.weixin.qq.com";
+var WechatApiError = class extends Error {
+  status;
+  code;
+  constructor(message, status, code) {
+    super(message);
+    this.name = "WechatApiError";
+    this.status = status;
+    this.code = code;
+  }
+};
+async function wechatV3Call(method, urlPath, body, config) {
+  const base = config.api_base ?? WECHAT_API_BASE;
+  const bodyStr = body === null ? "" : JSON.stringify(body);
+  const timestamp = String(Math.floor(Date.now() / 1e3));
+  const nonce = generateNonce();
+  const signature = wechatV3Sign(
+    method,
+    urlPath,
+    timestamp,
+    nonce,
+    bodyStr,
+    config.private_key_pem
+  );
+  const authorization = buildAuthorizationToken({
+    mchid: config.mchid,
+    serialNo: config.serial_no,
+    nonce,
+    timestamp,
+    signature
+  });
+  const response = await fetch(`${base}${urlPath}`, {
+    method,
+    headers: {
+      Authorization: authorization,
+      Accept: "application/json",
+      "Content-Type": "application/json",
+      // WeChat requires a non-empty UA; some edge nodes 403 a blank one.
+      "User-Agent": "moltspay-wechat/1.0"
+    },
+    body: method === "GET" ? void 0 : bodyStr
+  });
+  const text = await response.text();
+  if (config.platform_public_key_pem && text.length > 0) {
+    const ts = response.headers.get("Wechatpay-Timestamp");
+    const nc = response.headers.get("Wechatpay-Nonce");
+    const sig = response.headers.get("Wechatpay-Signature");
+    if (!ts || !nc || !sig) {
+      throw new Error(
+        `WeChat v3 ${method} ${urlPath}: response missing Wechatpay-Signature headers`
+      );
+    }
+    if (!wechatV3VerifyResponse(ts, nc, text, sig, config.platform_public_key_pem)) {
+      throw new Error(
+        `WeChat v3 ${method} ${urlPath}: response signature verification failed`
+      );
+    }
+  }
+  let json = {};
+  if (text.length > 0) {
+    try {
+      json = JSON.parse(text);
+    } catch {
+      throw new Error(
+        `WeChat v3 ${method} ${urlPath}: non-JSON response (HTTP ${response.status}): ${text.slice(0, 300)}`
+      );
+    }
+  }
+  if (!response.ok) {
+    const code = typeof json.code === "string" ? json.code : void 0;
+    const message = typeof json.message === "string" ? json.message : text.slice(0, 300);
+    throw new WechatApiError(
+      `WeChat v3 ${method} ${urlPath} failed: HTTP ${response.status}${code ? ` ${code}` : ""}: ${message}`,
+      response.status,
+      code
+    );
+  }
+  return { status: response.status, body: json };
+}
+
+// src/facilitators/wechat.ts
+var WECHAT_NETWORK = "wechat";
+var WECHAT_SCHEME = "wechatpay-native";
+var WECHAT_AMOUNT_REGEX = /^\d+(\.\d{1,2})?$/;
+var WECHAT_TIME_EXPIRE_MS = 5 * 60 * 1e3;
+var WechatFacilitator = class extends BaseFacilitator {
+  name = "wechat";
+  displayName = "WeChat Pay";
+  supportedNetworks = [WECHAT_NETWORK];
+  config;
+  constructor(config) {
+    super();
+    this.config = { api_base: WECHAT_API_BASE, ...config };
+  }
+  /**
+   * Place a Native order and build the 402 challenge. The returned
+   * `code_url` is payer-agnostic — any WeChat user may scan it.
+   */
+  async createPaymentRequirements(opts) {
+    if (!WECHAT_AMOUNT_REGEX.test(opts.priceCny)) {
+      throw new Error(
+        `WechatFacilitator.createPaymentRequirements: priceCny "${opts.priceCny}" does not match /^\\d+(\\.\\d{1,2})?$/ (unit is yuan; e.g. "10.00")`
+      );
+    }
+    const total = cnyToFen(opts.priceCny);
+    if (total < 1) {
+      throw new Error(
+        `WechatFacilitator.createPaymentRequirements: amount ${total} fen is below the 1 fen minimum`
+      );
+    }
+    const outTradeNo = opts.outTradeNo ?? generateOutTradeNo2();
+    const expiresInMs = opts.expiresInMs ?? WECHAT_TIME_EXPIRE_MS;
+    const body = {
+      appid: this.config.appid,
+      mchid: this.config.mchid,
+      description: opts.description,
+      out_trade_no: outTradeNo,
+      notify_url: this.config.notify_url,
+      time_expire: formatTimeExpire(new Date(Date.now() + expiresInMs)),
+      amount: { total, currency: "CNY" }
+    };
+    if (opts.attach) {
+      const attachStr = JSON.stringify(opts.attach);
+      if (Buffer.byteLength(attachStr, "utf8") > 128) {
+        throw new Error(
+          `WechatFacilitator.createPaymentRequirements: attach exceeds WeChat's 128-byte limit (${Buffer.byteLength(attachStr, "utf8")} bytes)`
+        );
+      }
+      body.attach = attachStr;
+    }
+    const { body: resp } = await wechatV3Call(
+      "POST",
+      "/v3/pay/transactions/native",
+      body,
+      this.getApiConfig()
+    );
+    const codeUrl = resp.code_url;
+    if (typeof codeUrl !== "string" || codeUrl.length === 0) {
+      throw new Error(
+        `WeChat Native order returned no code_url: ${JSON.stringify(resp).slice(0, 300)}`
+      );
+    }
+    const x402Accepts = {
+      scheme: WECHAT_SCHEME,
+      network: WECHAT_NETWORK,
+      asset: "CNY",
+      amount: opts.priceCny,
+      payTo: this.config.mchid,
+      maxTimeoutSeconds: Math.floor(expiresInMs / 1e3),
+      extra: {
+        code_url: codeUrl,
+        out_trade_no: outTradeNo
+      }
+    };
+    return { x402Accepts, codeUrl, outTradeNo };
+  }
+  /**
+   * Poll an order: `trade_state === 'SUCCESS'` ⇒ paid. All failure modes
+   * (missing out_trade_no, gateway error, not-yet-paid) return
+   * `{ valid: false, error }`; no exception escapes.
+   */
+  async verify(paymentPayload, requirements) {
+    try {
+      const outTradeNo = extractOutTradeNo(paymentPayload, requirements);
+      const resp = await this.queryOrder(outTradeNo);
+      const tradeState = resp.trade_state;
+      if (tradeState !== "SUCCESS") {
+        return {
+          valid: false,
+          error: `wechat trade_state ${tradeState ?? "UNKNOWN"}`,
+          details: { trade_state: tradeState, out_trade_no: outTradeNo }
+        };
+      }
+      return {
+        valid: true,
+        details: {
+          trade_state: tradeState,
+          transaction_id: resp.transaction_id,
+          out_trade_no: resp.out_trade_no ?? outTradeNo,
+          amount: resp.amount,
+          attach: resp.attach,
+          // Payer identity, gateway-attested. Present on a SUCCESS Native
+          // order even though order creation was payer-agnostic; anchors the
+          // custodial balance to a real WeChat user. @see WECHAT fiat auth design.
+          openid: resp.payer?.openid
+        }
+      };
+    } catch (e) {
+      return { valid: false, error: e instanceof Error ? e.message : String(e) };
+    }
+  }
+  /**
+   * Confirm settlement. Native captures funds at SUCCESS, so this is an
+   * idempotent re-confirm that returns the `transaction_id`. Like Alipay's
+   * fulfillment confirm, failures are surfaced but non-fatal to an
+   * already-delivered resource (caller logs, does not roll back).
+   */
+  async settle(paymentPayload, requirements) {
+    try {
+      const outTradeNo = extractOutTradeNo(paymentPayload, requirements);
+      const resp = await this.queryOrder(outTradeNo);
+      const tradeState = resp.trade_state;
+      const transactionId = resp.transaction_id;
+      if (tradeState !== "SUCCESS") {
+        return {
+          success: false,
+          transaction: transactionId,
+          error: `wechat trade_state ${tradeState ?? "UNKNOWN"} (expected SUCCESS)`,
+          status: tradeState
+        };
+      }
+      return { success: true, transaction: transactionId, status: "fulfilled" };
+    } catch (e) {
+      return { success: false, error: e instanceof Error ? e.message : String(e) };
+    }
+  }
+  /**
+   * Validate keys parse, apiv3 key length, and gateway reachability. Does
+   * NOT make a business API call.
+   */
+  async healthCheck() {
+    const start = Date.now();
+    try {
+      crypto4.createPrivateKey(this.config.private_key_pem);
+    } catch (e) {
+      return {
+        healthy: false,
+        error: `merchant private_key_pem parse failed: ${e instanceof Error ? e.message : String(e)}`
+      };
+    }
+    if (this.config.platform_public_key_pem) {
+      try {
+        crypto4.createPublicKey(this.config.platform_public_key_pem);
+      } catch (e) {
+        return {
+          healthy: false,
+          error: `platform_public_key_pem parse failed: ${e instanceof Error ? e.message : String(e)}`
+        };
+      }
+    }
+    if (this.config.apiv3_key !== void 0 && Buffer.byteLength(this.config.apiv3_key, "utf-8") !== 32) {
+      return { healthy: false, error: "apiv3_key must be exactly 32 bytes" };
+    }
+    const base = this.config.api_base ?? WECHAT_API_BASE;
+    const controller = new AbortController();
+    const timeout = setTimeout(() => controller.abort(), 5e3);
+    const response = await fetch(base, { method: "HEAD", signal: controller.signal }).catch(() => null);
+    clearTimeout(timeout);
+    const latencyMs = Date.now() - start;
+    if (!response) {
+      return { healthy: false, error: `gateway unreachable: ${base}`, latencyMs };
+    }
+    return { healthy: true, latencyMs };
+  }
+  /** Query a Native order by out_trade_no. The query string is part of the signed path. */
+  async queryOrder(outTradeNo) {
+    const path2 = `/v3/pay/transactions/out-trade-no/${encodeURIComponent(outTradeNo)}?mchid=${encodeURIComponent(this.config.mchid)}`;
+    const { body } = await wechatV3Call("GET", path2, null, this.getApiConfig());
+    return body;
+  }
+  /** Project the facilitator config down to what api.ts needs. */
+  getApiConfig() {
+    return {
+      mchid: this.config.mchid,
+      serial_no: this.config.serial_no,
+      private_key_pem: this.config.private_key_pem,
+      platform_public_key_pem: this.config.platform_public_key_pem,
+      api_base: this.config.api_base
+    };
+  }
+};
+function cnyToFen(cny) {
+  return Math.round(parseFloat(cny) * 100);
+}
+function generateOutTradeNo2() {
+  return "WX" + crypto4.randomBytes(15).toString("hex");
+}
+function parseWechatAttach(attach) {
+  if (typeof attach !== "string" || attach.length === 0) return null;
+  try {
+    const parsed = JSON.parse(attach);
+    return parsed && typeof parsed === "object" && !Array.isArray(parsed) ? parsed : null;
+  } catch {
+    return null;
+  }
+}
+function formatTimeExpire(d) {
+  const pad = (n) => String(n).padStart(2, "0");
+  const offMin = -d.getTimezoneOffset();
+  const sign = offMin >= 0 ? "+" : "-";
+  const abs = Math.abs(offMin);
+  return `${d.getFullYear()}-${pad(d.getMonth() + 1)}-${pad(d.getDate())}T${pad(d.getHours())}:${pad(d.getMinutes())}:${pad(d.getSeconds())}${sign}${pad(Math.floor(abs / 60))}:${pad(abs % 60)}`;
+}
+function extractOutTradeNo(paymentPayload, requirements) {
+  const p = paymentPayload?.payload;
+  if (typeof p === "string" && p.length > 0) return p;
+  if (p !== null && typeof p === "object") {
+    const obj = p;
+    const cand = obj.out_trade_no ?? obj.outTradeNo;
+    if (typeof cand === "string" && cand.length > 0) return cand;
+  }
+  const fromReq = requirements?.extra?.out_trade_no;
+  if (typeof fromReq === "string" && fromReq.length > 0) return fromReq;
+  throw new Error(
+    "wechat payment payload must carry out_trade_no (string, {out_trade_no}/{outTradeNo}, or requirements.extra.out_trade_no)"
+  );
+}
+
+// src/facilitators/balance/ledger.ts
+import { randomUUID } from "crypto";
+var DEFAULT_SINGLE_LIMIT_SAT = 500;
+var DEFAULT_DAILY_LIMIT_SAT = 1e3;
+function toSat(amount) {
+  const s = typeof amount === "number" ? amount.toFixed(2) : amount.trim();
+  if (!/^\d+(\.\d{1,2})?$/.test(s)) {
+    throw new Error(`Invalid amount "${amount}": expected a non-negative decimal with <= 2 places`);
+  }
+  const [whole, frac = ""] = s.split(".");
+  return parseInt(whole, 10) * 100 + parseInt(frac.padEnd(2, "0") || "0", 10);
+}
+function fromSat(sat) {
+  return (sat / 100).toFixed(2);
+}
+var BalanceLedger = class {
+  db;
+  defaultSingleLimitSat;
+  defaultDailyLimitSat;
+  constructor(config) {
+    const getBuiltin = process.getBuiltinModule;
+    const sqlite = getBuiltin?.("node:sqlite");
+    if (!sqlite?.DatabaseSync) {
+      throw new Error(
+        `The balance rail requires the node:sqlite module (Node.js >= 22.5). Current version: ${process.version}. Upgrade Node or disable provider.balance.`
+      );
+    }
+    const { DatabaseSync } = sqlite;
+    this.db = new DatabaseSync(config.dbPath);
+    this.defaultSingleLimitSat = config.defaultSingleLimitSat ?? DEFAULT_SINGLE_LIMIT_SAT;
+    this.defaultDailyLimitSat = config.defaultDailyLimitSat ?? DEFAULT_DAILY_LIMIT_SAT;
+    this.db.exec("PRAGMA journal_mode = WAL");
+    this.db.exec(`
+      CREATE TABLE IF NOT EXISTS buyers (
+        buyer_id TEXT PRIMARY KEY,
+        display_name TEXT,
+        balance_sat INTEGER NOT NULL DEFAULT 0,
+        total_topup_sat INTEGER NOT NULL DEFAULT 0,
+        total_spent_sat INTEGER NOT NULL DEFAULT 0,
+        daily_limit_sat INTEGER NOT NULL,
+        single_limit_sat INTEGER NOT NULL,
+        status TEXT NOT NULL DEFAULT 'active',
+        created_at TEXT NOT NULL DEFAULT (datetime('now')),
+        updated_at TEXT NOT NULL DEFAULT (datetime('now'))
+      );
+      CREATE TABLE IF NOT EXISTS ledger_transactions (
+        id TEXT PRIMARY KEY,
+        buyer_id TEXT NOT NULL REFERENCES buyers(buyer_id),
+        type TEXT NOT NULL,
+        amount_sat INTEGER NOT NULL,
+        service TEXT,
+        description TEXT,
+        request_id TEXT,
+        external_ref TEXT,
+        refunds_tx_id TEXT,
+        status TEXT NOT NULL DEFAULT 'completed',
+        created_at TEXT NOT NULL DEFAULT (datetime('now'))
+      );
+      CREATE UNIQUE INDEX IF NOT EXISTS idx_ledger_request_id
+        ON ledger_transactions(request_id) WHERE request_id IS NOT NULL;
+      CREATE UNIQUE INDEX IF NOT EXISTS idx_ledger_external_ref
+        ON ledger_transactions(external_ref) WHERE external_ref IS NOT NULL;
+      CREATE UNIQUE INDEX IF NOT EXISTS idx_ledger_refunds_tx
+        ON ledger_transactions(refunds_tx_id) WHERE refunds_tx_id IS NOT NULL;
+      CREATE INDEX IF NOT EXISTS idx_ledger_buyer_time
+        ON ledger_transactions(buyer_id, created_at);
+      CREATE TABLE IF NOT EXISTS ledger_meta (
+        key TEXT PRIMARY KEY,
+        value TEXT NOT NULL
+      );
+    `);
+    const cols = this.db.prepare("PRAGMA table_info(buyers)").all().map((c) => c.name);
+    if (!cols.includes("signer_address")) {
+      this.db.exec("ALTER TABLE buyers ADD COLUMN signer_address TEXT");
+    }
+    if (!cols.includes("wechat_openid")) {
+      this.db.exec("ALTER TABLE buyers ADD COLUMN wechat_openid TEXT");
+    }
+    const currency = config.currency ?? "USD";
+    const existingCurrency = this.db.prepare(`SELECT value FROM ledger_meta WHERE key = 'currency'`).get();
+    if (existingCurrency) {
+      if (existingCurrency.value !== currency) {
+        throw new Error(
+          `Balance ledger currency mismatch: db=${existingCurrency.value} config=${currency}. Use a separate db_path for a different currency; do not reinterpret an existing ledger.`
+        );
+      }
+    } else {
+      this.db.prepare(`INSERT INTO ledger_meta (key, value) VALUES ('currency', ?)`).run(currency);
+    }
+  }
+  /** Fetch a buyer, or null. */
+  getBuyer(buyerId) {
+    const row = this.db.prepare("SELECT * FROM buyers WHERE buyer_id = ?").get(buyerId);
+    return row ?? null;
+  }
+  /** Fetch a buyer, creating an empty active account on first sight. */
+  getOrCreateBuyer(buyerId, displayName) {
+    const existing = this.getBuyer(buyerId);
+    if (existing) return existing;
+    this.db.prepare(
+      `INSERT INTO buyers (buyer_id, display_name, daily_limit_sat, single_limit_sat)
+         VALUES (?, ?, ?, ?)`
+    ).run(buyerId, displayName ?? null, this.defaultDailyLimitSat, this.defaultSingleLimitSat);
+    return this.getBuyer(buyerId);
+  }
+  /**
+   * Record the gateway-attested WeChat payer openid that funded a buyer, on
+   * top-up confirm. Idempotent and observational (stage 1a): it never
+   * overwrites an existing binding with a *different* openid — a conflict is
+   * reported to the caller (possible account sharing / spoof) but not
+   * enforced here. Creates the buyer if absent.
+   */
+  bindOpenid(buyerId, openid) {
+    const buyer = this.getOrCreateBuyer(buyerId);
+    if (buyer.wechat_openid === openid) {
+      return { bound: true, conflict: false, existing: openid };
+    }
+    if (buyer.wechat_openid && buyer.wechat_openid !== openid) {
+      return { bound: false, conflict: true, existing: buyer.wechat_openid };
+    }
+    this.db.prepare(`UPDATE buyers SET wechat_openid = ?, updated_at = datetime('now') WHERE buyer_id = ?`).run(openid, buyerId);
+    return { bound: true, conflict: false, existing: null };
+  }
+  /**
+   * TOFU-bind the account's spending signer address (EVM, lowercase). First
+   * signed request records it; later requests must match. A mismatch is
+   * reported (`conflict`) so the caller can reject under `enforce` — it is
+   * never silently overwritten. Creates the buyer if absent.
+   */
+  bindSigner(buyerId, address) {
+    const a = address.toLowerCase();
+    const buyer = this.getOrCreateBuyer(buyerId);
+    if (buyer.signer_address === a) return { bound: true, conflict: false, existing: a };
+    if (buyer.signer_address && buyer.signer_address !== a) {
+      return { bound: false, conflict: true, existing: buyer.signer_address };
+    }
+    this.db.prepare(`UPDATE buyers SET signer_address = ?, updated_at = datetime('now') WHERE buyer_id = ?`).run(a, buyerId);
+    return { bound: true, conflict: false, existing: null };
+  }
+  /** Sum of today's (UTC) completed deducts minus refunds issued against them. */
+  spentTodaySat(buyerId) {
+    const row = this.db.prepare(
+      `SELECT COALESCE(SUM(CASE type WHEN 'deduct' THEN amount_sat ELSE -amount_sat END), 0) AS spent
+         FROM ledger_transactions
+         WHERE buyer_id = ? AND type IN ('deduct','refund') AND date(created_at) = date('now')`
+    ).get(buyerId);
+    return Math.max(0, row.spent);
+  }
+  /**
+   * Read-only deduction precheck (the rail's `verify`). Never mutates.
+   * Returns the same error codes `deduct` would.
+   */
+  checkDeduct(buyerId, amountSat) {
+    const buyer = this.getBuyer(buyerId);
+    if (!buyer) return { success: false, error: "buyer_not_found" };
+    if (buyer.status !== "active") return { success: false, error: "buyer_not_active" };
+    if (amountSat > buyer.single_limit_sat) {
+      return { success: false, error: "exceeds_single_limit", limitSat: buyer.single_limit_sat };
+    }
+    const spent = this.spentTodaySat(buyerId);
+    if (spent + amountSat > buyer.daily_limit_sat) {
+      return { success: false, error: "exceeds_daily_limit", limitSat: buyer.daily_limit_sat };
+    }
+    if (buyer.balance_sat < amountSat) {
+      return { success: false, error: "insufficient_balance", balanceSat: buyer.balance_sat };
+    }
+    return { success: true, balanceSat: buyer.balance_sat };
+  }
+  /**
+   * Atomic deduction (the rail's `settle`). Check + UPDATE run inside one
+   * SQLite transaction; a `request_id` replay returns the original tx
+   * without charging again.
+   */
+  deduct(opts) {
+    if (!Number.isInteger(opts.amountSat) || opts.amountSat <= 0) {
+      throw new Error(`deduct amountSat must be a positive integer, got ${opts.amountSat}`);
+    }
+    if (opts.requestId) {
+      const prior = this.db.prepare(`SELECT * FROM ledger_transactions WHERE request_id = ?`).get(opts.requestId);
+      if (prior) {
+        const buyer = this.getBuyer(prior.buyer_id);
+        return { success: true, txId: prior.id, replayed: true, balanceSat: buyer.balance_sat };
+      }
+    }
+    this.db.exec("BEGIN IMMEDIATE");
+    try {
+      const check = this.checkDeduct(opts.buyerId, opts.amountSat);
+      if (!check.success) {
+        this.db.exec("ROLLBACK");
+        return check;
+      }
+      const updated = this.db.prepare(
+        `UPDATE buyers SET
+             balance_sat = balance_sat - ?,
+             total_spent_sat = total_spent_sat + ?,
+             updated_at = datetime('now')
+           WHERE buyer_id = ? AND balance_sat >= ? AND status = 'active'`
+      ).run(opts.amountSat, opts.amountSat, opts.buyerId, opts.amountSat);
+      if (Number(updated.changes) !== 1) {
+        this.db.exec("ROLLBACK");
+        return { success: false, error: "insufficient_balance" };
+      }
+      const txId = `btx_${randomUUID()}`;
+      this.db.prepare(
+        `INSERT INTO ledger_transactions (id, buyer_id, type, amount_sat, service, description, request_id)
+           VALUES (?, ?, 'deduct', ?, ?, ?, ?)`
+      ).run(txId, opts.buyerId, opts.amountSat, opts.service ?? null, opts.description ?? null, opts.requestId ?? null);
+      this.db.exec("COMMIT");
+      const buyer = this.getBuyer(opts.buyerId);
+      return { success: true, txId, balanceSat: buyer.balance_sat };
+    } catch (err) {
+      try {
+        this.db.exec("ROLLBACK");
+      } catch {
+      }
+      throw err;
+    }
+  }
+  /**
+   * Credit a top-up. `externalRef` is the settlement proof reference
+   * (on-chain tx hash / fiat trade number) and is unique: replaying the same
+   * reference returns the original row without crediting twice.
+   */
+  topup(opts) {
+    if (!Number.isInteger(opts.amountSat) || opts.amountSat <= 0) {
+      throw new Error(`topup amountSat must be a positive integer, got ${opts.amountSat}`);
+    }
+    const prior = this.db.prepare(`SELECT * FROM ledger_transactions WHERE external_ref = ?`).get(opts.externalRef);
+    if (prior) {
+      const buyer2 = this.getBuyer(prior.buyer_id);
+      return { txId: prior.id, balanceSat: buyer2.balance_sat, replayed: true };
+    }
+    this.getOrCreateBuyer(opts.buyerId);
+    const txId = `btx_${randomUUID()}`;
+    this.db.exec("BEGIN IMMEDIATE");
+    try {
+      this.db.prepare(
+        `UPDATE buyers SET
+             balance_sat = balance_sat + ?,
+             total_topup_sat = total_topup_sat + ?,
+             updated_at = datetime('now')
+           WHERE buyer_id = ?`
+      ).run(opts.amountSat, opts.amountSat, opts.buyerId);
+      this.db.prepare(
+        `INSERT INTO ledger_transactions (id, buyer_id, type, amount_sat, description, external_ref)
+           VALUES (?, ?, 'topup', ?, ?, ?)`
+      ).run(txId, opts.buyerId, opts.amountSat, opts.description ?? null, opts.externalRef);
+      this.db.exec("COMMIT");
+    } catch (err) {
+      try {
+        this.db.exec("ROLLBACK");
+      } catch {
+      }
+      throw err;
+    }
+    const buyer = this.getBuyer(opts.buyerId);
+    return { txId, balanceSat: buyer.balance_sat };
+  }
+  /**
+   * Reverse a deduct (service failed after the charge). Idempotent: the
+   * unique index on `refunds_tx_id` means a second refund of the same deduct
+   * returns the original refund row.
+   */
+  refund(deductTxId, reason) {
+    const deductRow = this.db.prepare(`SELECT * FROM ledger_transactions WHERE id = ?`).get(deductTxId);
+    if (!deductRow) return { success: false, error: "tx_not_found" };
+    if (deductRow.type !== "deduct") return { success: false, error: "not_a_deduct" };
+    const priorRefund = this.db.prepare(`SELECT * FROM ledger_transactions WHERE refunds_tx_id = ?`).get(deductTxId);
+    if (priorRefund) {
+      const buyer = this.getBuyer(deductRow.buyer_id);
+      return { success: true, txId: priorRefund.id, balanceSat: buyer.balance_sat, replayed: true };
+    }
+    this.db.exec("BEGIN IMMEDIATE");
+    try {
+      this.db.prepare(
+        `UPDATE buyers SET
+             balance_sat = balance_sat + ?,
+             total_spent_sat = total_spent_sat - ?,
+             updated_at = datetime('now')
+           WHERE buyer_id = ?`
+      ).run(deductRow.amount_sat, deductRow.amount_sat, deductRow.buyer_id);
+      this.db.prepare(`UPDATE ledger_transactions SET status = 'refunded' WHERE id = ?`).run(deductTxId);
+      const txId = `btx_${randomUUID()}`;
+      this.db.prepare(
+        `INSERT INTO ledger_transactions (id, buyer_id, type, amount_sat, description, refunds_tx_id)
+           VALUES (?, ?, 'refund', ?, ?, ?)`
+      ).run(txId, deductRow.buyer_id, deductRow.amount_sat, reason ?? null, deductTxId);
+      this.db.exec("COMMIT");
+      const buyer = this.getBuyer(deductRow.buyer_id);
+      return { success: true, txId, balanceSat: buyer.balance_sat };
+    } catch (err) {
+      try {
+        this.db.exec("ROLLBACK");
+      } catch {
+      }
+      throw err;
+    }
+  }
+  /** Paged transaction history, newest first (rowid breaks same-second ties). */
+  listTransactions(buyerId, limit = 20, offset = 0) {
+    return this.db.prepare(
+      `SELECT * FROM ledger_transactions WHERE buyer_id = ?
+         ORDER BY created_at DESC, rowid DESC LIMIT ? OFFSET ?`
+    ).all(buyerId, limit, offset);
+  }
+  /** Quick integrity probe for healthCheck(). */
+  integrityOk() {
+    const row = this.db.prepare(`PRAGMA quick_check`).get();
+    return row.quick_check === "ok";
+  }
+  close() {
+    this.db.close();
+  }
+};
+
+// src/facilitators/balance/auth.ts
+import { ethers as ethers2 } from "ethers";
+var BALANCE_AUTH_DOMAIN = "moltspay-balance-auth:v1";
+var BALANCE_AUTH_MAX_SKEW_MS = 5 * 60 * 1e3;
+function extractBalanceAuth(raw) {
+  if (!raw || typeof raw !== "object") return null;
+  const a = raw;
+  if (typeof a.signature === "string" && a.signature && typeof a.timestamp === "number" && Number.isFinite(a.timestamp)) {
+    return { timestamp: a.timestamp, signature: a.signature };
+  }
+  return null;
+}
+function buildDeductMessage(f) {
+  return [BALANCE_AUTH_DOMAIN, "balance-deduct", f.buyerId, f.requestId, f.service, String(f.timestamp)].join("\n");
+}
+function verifyDeductAuth(opts) {
+  const { auth } = opts;
+  if (!auth) return { ok: false, reason: "no_signature" };
+  if (!auth.signature || !Number.isFinite(auth.timestamp)) return { ok: false, reason: "malformed" };
+  if (Math.abs(opts.nowMs - auth.timestamp * 1e3) > BALANCE_AUTH_MAX_SKEW_MS) {
+    return { ok: false, reason: "timestamp_skew" };
+  }
+  const message = buildDeductMessage({
+    buyerId: opts.buyerId,
+    requestId: opts.requestId,
+    service: opts.service,
+    timestamp: auth.timestamp
+  });
+  try {
+    const recovered = ethers2.verifyMessage(message, auth.signature).toLowerCase();
+    return { ok: true, recovered };
+  } catch {
+    return { ok: false, reason: "bad_signature" };
+  }
+}
+
+// src/facilitators/balance.ts
+var BALANCE_NETWORK = "balance";
+var BALANCE_SCHEME = "balance";
+function extractBalancePayload(payment) {
+  const p = payment.payload;
+  if (p && typeof p.buyer_id === "string" && p.buyer_id.length > 0) {
+    return {
+      buyer_id: p.buyer_id,
+      request_id: typeof p.request_id === "string" ? p.request_id : void 0,
+      auth: extractBalanceAuth(p.auth) ?? void 0
+    };
+  }
+  return null;
+}
+var BalanceFacilitator = class extends BaseFacilitator {
+  name = "balance";
+  displayName = "Custodial Balance";
+  supportedNetworks = [BALANCE_NETWORK];
+  currency;
+  /** User-auth rollout gate for deductions (off | shadow | enforce). */
+  authMode;
+  ledger;
+  constructor(config) {
+    super();
+    this.currency = config.currency ?? "USD";
+    this.authMode = config.auth_mode ?? "off";
+    const ledgerConfig = {
+      dbPath: config.db_path,
+      defaultSingleLimitSat: config.single_limit ? toSat(config.single_limit) : DEFAULT_SINGLE_LIMIT_SAT,
+      defaultDailyLimitSat: config.daily_limit ? toSat(config.daily_limit) : DEFAULT_DAILY_LIMIT_SAT,
+      currency: this.currency
+    };
+    this.ledger = new BalanceLedger(ledgerConfig);
+  }
+  /** Direct ledger access for the server's balance-management endpoints. */
+  getLedger() {
+    return this.ledger;
+  }
+  /**
+   * Build the `accepts[]` entry for a service. Pure — no I/O, nothing minted.
+   */
+  createPaymentRequirements(opts) {
+    toSat(opts.price);
+    return {
+      scheme: BALANCE_SCHEME,
+      network: BALANCE_NETWORK,
+      asset: this.currency,
+      amount: opts.price,
+      payTo: "custodial",
+      maxTimeoutSeconds: 30,
+      extra: opts.serviceId ? { service_id: opts.serviceId } : void 0
+    };
+  }
+  /** Read-only funds/limits precheck. Never mutates the ledger. */
+  async verify(paymentPayload, requirements) {
+    const payload = extractBalancePayload(paymentPayload);
+    if (!payload) {
+      return { valid: false, error: "Missing buyer_id in balance payment payload" };
+    }
+    let amountSat;
+    try {
+      amountSat = toSat(requirements.amount);
+    } catch (err) {
+      return { valid: false, error: err.message };
+    }
+    const check = this.ledger.checkDeduct(payload.buyer_id, amountSat);
+    if (!check.success) {
+      return {
+        valid: false,
+        error: this.describeDeductError(check),
+        details: { code: check.error, balance: check.balanceSat !== void 0 ? fromSat(check.balanceSat) : void 0 }
+      };
+    }
+    return { valid: true, details: { balance: fromSat(check.balanceSat) } };
+  }
+  /**
+   * The atomic deduction. Idempotent on `request_id`; the returned
+   * `transaction` is the ledger tx id (usable for `refund`).
+   */
+  async settle(paymentPayload, requirements) {
+    const payload = extractBalancePayload(paymentPayload);
+    if (!payload) {
+      return { success: false, error: "Missing buyer_id in balance payment payload" };
+    }
+    let amountSat;
+    try {
+      amountSat = toSat(requirements.amount);
+    } catch (err) {
+      return { success: false, error: err.message };
+    }
+    const serviceId = typeof requirements.extra?.service_id === "string" ? requirements.extra.service_id : void 0;
+    let result;
+    try {
+      result = this.ledger.deduct({
+        buyerId: payload.buyer_id,
+        amountSat,
+        requestId: payload.request_id,
+        service: serviceId
+      });
+    } catch (err) {
+      return { success: false, error: `Ledger deduct failed: ${err.message}` };
+    }
+    if (!result.success) {
+      return { success: false, error: this.describeDeductError(result), status: result.error };
+    }
+    return {
+      success: true,
+      transaction: result.txId,
+      status: result.replayed ? "replayed" : "deducted"
+    };
+  }
+  /** Reverse a deduct after a downstream failure. Idempotent per deduct. */
+  refund(deductTxId, reason) {
+    return this.ledger.refund(deductTxId, reason);
+  }
+  /**
+   * Credit a gateway-verified external settlement to a buyer's balance. The
+   * single entry point for every funding path -- WeChat callback, WeChat
+   * polling, and the operator `/balance/topup` endpoint -- so they share one
+   * idempotency boundary: `externalRef` is unique in the ledger, so a replay
+   * credits nothing and returns the original transaction (`replayed: true`).
+   * Callers must pass a gateway-verified `amountSat`, never a client-declared
+   * amount.
+   */
+  credit(opts) {
+    const result = this.ledger.topup({
+      buyerId: opts.buyerId,
+      amountSat: opts.amountSat,
+      externalRef: opts.externalRef,
+      description: opts.description
+    });
+    return {
+      txId: result.txId,
+      balance: fromSat(result.balanceSat),
+      balanceSat: result.balanceSat,
+      replayed: result.replayed ?? false
+    };
+  }
+  async healthCheck() {
+    const start = Date.now();
+    try {
+      const ok = this.ledger.integrityOk();
+      return ok ? { healthy: true, latencyMs: Date.now() - start } : { healthy: false, error: "SQLite quick_check failed" };
+    } catch (err) {
+      return { healthy: false, error: err.message };
+    }
+  }
+  describeDeductError(result) {
+    switch (result.error) {
+      case "buyer_not_found":
+        return "Unknown buyer: top up first to create an account";
+      case "buyer_not_active":
+        return "Buyer account is frozen or banned";
+      case "insufficient_balance":
+        return `Insufficient balance${result.balanceSat !== void 0 ? ` (have ${fromSat(result.balanceSat)})` : ""}`;
+      case "exceeds_single_limit":
+        return `Amount exceeds the per-transaction limit${result.limitSat !== void 0 ? ` of ${fromSat(result.limitSat)}` : ""}`;
+      case "exceeds_daily_limit":
+        return `Amount exceeds the daily spending limit${result.limitSat !== void 0 ? ` of ${fromSat(result.limitSat)}` : ""}`;
+      default:
+        return "Deduction failed";
+    }
+  }
+};
+
 // src/facilitators/registry.ts
 import { Keypair as Keypair2 } from "@solana/web3.js";
 import bs58 from "bs58";
@@ -1242,6 +2475,9 @@ var FacilitatorRegistry = class {
       }
       return new SolanaFacilitator({ feePayerKeypair });
     });
+    this.registerFactory("alipay", (config) => new AlipayFacilitator(config));
+    this.registerFactory("wechat", (config) => new WechatFacilitator(config));
+    this.registerFactory("balance", (config) => new BalanceFacilitator(config));
     this.selection = selection || { primary: "cdp", fallback: ["tempo", "bnb", "solana"], strategy: "failover" };
   }
   /**
@@ -1468,15 +2704,38 @@ function createRegistry(selection) {
   return new FacilitatorRegistry(selection);
 }
 export {
+  ALIPAY_GATEWAY_PROD,
+  ALIPAY_GATEWAY_SANDBOX,
+  ALIPAY_NETWORK,
+  ALIPAY_SCHEME,
+  AlipayFacilitator,
+  BALANCE_AUTH_DOMAIN,
+  BALANCE_AUTH_MAX_SKEW_MS,
+  BALANCE_NETWORK,
+  BALANCE_SCHEME,
   BNBFacilitator,
+  BalanceFacilitator,
+  BalanceLedger,
   BaseFacilitator,
   CDPFacilitator,
   FacilitatorRegistry,
   SolanaFacilitator,
   TempoFacilitator,
+  WECHAT_AMOUNT_REGEX,
+  WECHAT_API_BASE,
+  WECHAT_NETWORK,
+  WECHAT_SCHEME,
+  WECHAT_TIME_EXPIRE_MS,
+  WechatFacilitator,
+  buildDeductMessage,
   createIntentTypedData,
   createRegistry,
   createSolanaPaymentTransaction,
-  getDefaultRegistry
+  extractBalancePayload,
+  fromSat,
+  getDefaultRegistry,
+  parseWechatAttach,
+  toSat,
+  verifyDeductAuth
 };
 //# sourceMappingURL=index.mjs.map