uvd-x402-sdk 2.85.0 → 2.86.0

package/dist/backend/index.mjs

@@ -1,4 +1,4 @@
-import 'ethers';
+import { ethers } from 'ethers';
 
 var __require = /* @__PURE__ */ ((x) => typeof require !== "undefined" ? require : typeof Proxy !== "undefined" ? new Proxy(x, {
   get: (a, b) => (typeof require !== "undefined" ? require : a)[b]
@@ -46,6 +46,19 @@ var CAIP2_IDENTIFIERS = {
 var CAIP2_TO_CHAIN = Object.fromEntries(
   Object.entries(CAIP2_IDENTIFIERS).map(([k, v]) => [v, k])
 );
+var X402Error = class _X402Error extends Error {
+  code;
+  details;
+  constructor(message, code, details) {
+    super(message);
+    this.name = "X402Error";
+    this.code = code;
+    this.details = details;
+    if (Error.captureStackTrace) {
+      Error.captureStackTrace(this, _X402Error);
+    }
+  }
+};
 
 // src/chains/index.ts
 var DEFAULT_FACILITATOR_URL = "https://facilitator.ultravioletadao.xyz";
@@ -1113,6 +1126,188 @@ var DEFAULT_MIN_FEE_BPS = 0;
 var DEFAULT_MAX_FEE_BPS = OPERATOR_FEE_BPS + MAX_PROTOCOL_FEE_BPS;
 var REVIEW_WINDOW_SEC = 7 * 24 * 3600;
 var REFUND_WINDOW_SEC = 7 * 24 * 3600;
+var LIFECYCLE_DOMAIN_NAME = "x402 escrow lifecycle";
+var LIFECYCLE_DOMAIN_VERSION = "1";
+var LIFECYCLE_MAX_DEADLINE_SECS = 900;
+var LIFECYCLE_DEFAULT_DEADLINE_SECS = 600;
+var LIFECYCLE_ACTIONS = ["release", "refundInEscrow"];
+var LIFECYCLE_ORDER_TYPES = {
+  LifecycleOrder: [
+    { name: "action", type: "string" },
+    { name: "amount", type: "uint256" },
+    { name: "deadline", type: "uint256" },
+    { name: "nonce", type: "bytes32" },
+    { name: "paymentInfo", type: "PaymentInfo" }
+  ],
+  PaymentInfo: [
+    { name: "operator", type: "address" },
+    { name: "payer", type: "address" },
+    { name: "receiver", type: "address" },
+    { name: "token", type: "address" },
+    { name: "maxAmount", type: "uint120" },
+    { name: "preApprovalExpiry", type: "uint48" },
+    { name: "authorizationExpiry", type: "uint48" },
+    { name: "refundExpiry", type: "uint48" },
+    { name: "minFeeBps", type: "uint16" },
+    { name: "maxFeeBps", type: "uint16" },
+    { name: "feeReceiver", type: "address" },
+    { name: "salt", type: "uint256" }
+  ]
+};
+var LIFECYCLE_PI_KEYS = [
+  "operator",
+  "receiver",
+  "token",
+  "maxAmount",
+  "preApprovalExpiry",
+  "authorizationExpiry",
+  "refundExpiry",
+  "minFeeBps",
+  "maxFeeBps",
+  "feeReceiver",
+  "salt"
+];
+function saltToBigInt(salt) {
+  if (typeof salt === "bigint") return salt;
+  if (typeof salt === "number") {
+    if (!Number.isInteger(salt) || salt < 0) {
+      throw new X402Error(`paymentInfo.salt invalid: ${String(salt)}`, "INVALID_CONFIG");
+    }
+    return BigInt(salt);
+  }
+  if (typeof salt === "string") {
+    const trimmed = salt.trim();
+    const hex = trimmed.startsWith("0x") || trimmed.startsWith("0X") ? trimmed : `0x${trimmed}`;
+    try {
+      return BigInt(hex);
+    } catch {
+      throw new X402Error(`paymentInfo.salt invalid: ${salt}`, "INVALID_CONFIG");
+    }
+  }
+  throw new X402Error(`paymentInfo.salt invalid: ${String(salt)}`, "INVALID_CONFIG");
+}
+function nonceToBytes32(nonce) {
+  if (typeof nonce !== "string") {
+    throw new X402Error(`lifecycleAuth.nonce invalid: ${String(nonce)}`, "INVALID_CONFIG");
+  }
+  const raw = nonce.startsWith("0x") || nonce.startsWith("0X") ? nonce.slice(2) : nonce;
+  if (!/^[0-9a-fA-F]*$/.test(raw)) {
+    throw new X402Error(`lifecycleAuth.nonce is not hex: ${nonce}`, "INVALID_CONFIG");
+  }
+  if (raw.length !== 64) {
+    throw new X402Error(
+      `lifecycleAuth.nonce must be 32 bytes, got ${raw.length / 2}`,
+      "INVALID_CONFIG"
+    );
+  }
+  return `0x${raw.toLowerCase()}`;
+}
+function randomNonce() {
+  const webCrypto = globalThis.crypto;
+  if (webCrypto?.getRandomValues) {
+    const bytes = new Uint8Array(32);
+    webCrypto.getRandomValues(bytes);
+    return ethers.hexlify(bytes);
+  }
+  return ethers.hexlify(ethers.randomBytes(32));
+}
+function toUintString(value, field) {
+  let n;
+  try {
+    n = typeof value === "bigint" ? value : BigInt(value);
+  } catch {
+    throw new X402Error(`${field} must be a non-negative integer, got ${String(value)}`, "INVALID_CONFIG");
+  }
+  if (n < 0n) {
+    throw new X402Error(`${field} must be a non-negative integer, got ${String(value)}`, "INVALID_CONFIG");
+  }
+  return n.toString();
+}
+function buildLifecycleTypedData(params) {
+  const { action, paymentInfo, payer, amount, chainId, deadline, nonce } = params;
+  if (!LIFECYCLE_ACTIONS.includes(action)) {
+    throw new X402Error(
+      `unknown lifecycle action ${String(action)}; the facilitator only signs ${LIFECYCLE_ACTIONS.join(", ")}`,
+      "INVALID_CONFIG"
+    );
+  }
+  let amountBig;
+  try {
+    amountBig = typeof amount === "bigint" ? amount : BigInt(amount);
+  } catch {
+    throw new X402Error(`amount must be an integer >= 0, got ${String(amount)}`, "INVALID_AMOUNT");
+  }
+  if (amountBig < 0n) {
+    throw new X402Error(`amount must be an integer >= 0, got ${String(amount)}`, "INVALID_AMOUNT");
+  }
+  const pi = paymentInfo ?? {};
+  const missing = LIFECYCLE_PI_KEYS.filter((k) => pi[k] === void 0);
+  if (missing.length > 0) {
+    throw new X402Error(
+      `paymentInfo is missing fields that enter the signature: ${missing.join(", ")}. The paymentInfo that is SENT is the one that is signed; defaulting a field would sign a different struct than the one that reaches the facilitator.`,
+      "INVALID_CONFIG"
+    );
+  }
+  return {
+    domain: {
+      name: LIFECYCLE_DOMAIN_NAME,
+      version: LIFECYCLE_DOMAIN_VERSION,
+      chainId: Number(chainId)
+    },
+    types: LIFECYCLE_ORDER_TYPES,
+    primaryType: "LifecycleOrder",
+    message: {
+      action,
+      amount: amountBig.toString(),
+      deadline: toUintString(deadline, "deadline"),
+      nonce: nonceToBytes32(nonce),
+      paymentInfo: {
+        operator: ethers.getAddress(paymentInfo.operator),
+        payer: ethers.getAddress(payer),
+        receiver: ethers.getAddress(paymentInfo.receiver),
+        token: ethers.getAddress(paymentInfo.token),
+        maxAmount: toUintString(paymentInfo.maxAmount, "paymentInfo.maxAmount"),
+        preApprovalExpiry: toUintString(paymentInfo.preApprovalExpiry, "paymentInfo.preApprovalExpiry"),
+        authorizationExpiry: toUintString(
+          paymentInfo.authorizationExpiry,
+          "paymentInfo.authorizationExpiry"
+        ),
+        refundExpiry: toUintString(paymentInfo.refundExpiry, "paymentInfo.refundExpiry"),
+        minFeeBps: toUintString(paymentInfo.minFeeBps, "paymentInfo.minFeeBps"),
+        maxFeeBps: toUintString(paymentInfo.maxFeeBps, "paymentInfo.maxFeeBps"),
+        feeReceiver: ethers.getAddress(paymentInfo.feeReceiver),
+        // uint256 in the signature, bytes32 on the wire — see saltToBigInt.
+        salt: saltToBigInt(paymentInfo.salt).toString()
+      }
+    }
+  };
+}
+async function buildLifecycleAuth(params) {
+  const { wallet, deadline, nonce, now, ...rest } = params;
+  const nowSec = now === void 0 ? Math.floor(Date.now() / 1e3) : Math.floor(now);
+  const dl = deadline === void 0 ? nowSec + LIFECYCLE_DEFAULT_DEADLINE_SECS : Math.floor(deadline);
+  const nonceHex = nonce === void 0 ? randomNonce() : nonce;
+  if (dl < nowSec) {
+    throw new X402Error(
+      `deadline ${dl} is in the past (now ${nowSec}): the facilitator discards it as \`expired\``,
+      "INVALID_CONFIG"
+    );
+  }
+  if (dl - nowSec > LIFECYCLE_MAX_DEADLINE_SECS) {
+    throw new X402Error(
+      `deadline ${dl} is ${dl - nowSec} s ahead and the facilitator's ceiling is ${LIFECYCLE_MAX_DEADLINE_SECS} s (\`deadline_too_far\`): a leaked order cannot be a standing permission`,
+      "INVALID_CONFIG"
+    );
+  }
+  const typed = buildLifecycleTypedData({ ...rest, deadline: dl, nonce: nonceHex });
+  const signed = await wallet.signTypedData(JSON.stringify(typed));
+  return {
+    signer: wallet.getAddress(),
+    deadline: dl,
+    nonce: nonceToBytes32(nonceHex),
+    signature: signed.signature
+  };
+}
 
 // src/backend/facilitator-error.ts
 var WRITER_LEASE_REASONS = [
@@ -4202,8 +4397,8 @@ var AdvancedEscrowClient = class {
    * Matches the on-chain AuthCaptureEscrow nonce derivation.
    */
   async computeNonce(paymentInfo) {
-    const { ethers: ethers3 } = await import('ethers');
-    const piTuple = ethers3.AbiCoder.defaultAbiCoder().encode(
+    const { ethers: ethers4 } = await import('ethers');
+    const piTuple = ethers4.AbiCoder.defaultAbiCoder().encode(
       ["bytes32", "tuple(address,address,address,address,uint120,uint48,uint48,uint48,uint16,uint16,address,uint256)"],
       [
         PAYMENT_INFO_TYPEHASH,
@@ -4224,12 +4419,12 @@ var AdvancedEscrowClient = class {
         ]
       ]
     );
-    const piHash = ethers3.keccak256(piTuple);
-    const finalEncoded = ethers3.AbiCoder.defaultAbiCoder().encode(
+    const piHash = ethers4.keccak256(piTuple);
+    const finalEncoded = ethers4.AbiCoder.defaultAbiCoder().encode(
       ["uint256", "address", "bytes32"],
       [this.chainId, this.contracts.escrow, piHash]
     );
-    return ethers3.keccak256(finalEncoded);
+    return ethers4.keccak256(finalEncoded);
   }
   /**
    * Sign ReceiveWithAuthorization for ERC-3009.
@@ -4386,17 +4581,17 @@ var AdvancedEscrowClient = class {
   async release(paymentInfo, amount) {
     if (!this.payerAddress) await this.init();
     try {
-      const { ethers: ethers3 } = await import('ethers');
+      const { ethers: ethers4 } = await import('ethers');
       const isCreate3 = CREATE3_CHAIN_IDS.has(this.chainId);
       const abi = isCreate3 ? OPERATOR_ABI_CREATE3 : OPERATOR_ABI;
       const amt = amount || paymentInfo.maxAmount;
       const tuple = this.buildTuple(paymentInfo);
       if (this.walletAdapter) {
-        return this.sendViaAdapter(ethers3, abi, (iface) => {
+        return this.sendViaAdapter(ethers4, abi, (iface) => {
           return isCreate3 ? iface.encodeFunctionData("release", [tuple, amt, "0x"]) : iface.encodeFunctionData("release", [tuple, amt]);
         });
       }
-      const contract = new ethers3.Contract(this.contracts.operator, abi, this.signer);
+      const contract = new ethers4.Contract(this.contracts.operator, abi, this.signer);
       const tx = isCreate3 ? await contract.release(tuple, amt, "0x", { gasLimit: this.gasLimit }) : await contract.release(tuple, amt, { gasLimit: this.gasLimit });
       const receipt = await tx.wait();
       return {
@@ -4420,17 +4615,17 @@ var AdvancedEscrowClient = class {
   async refundInEscrow(paymentInfo, amount) {
     if (!this.payerAddress) await this.init();
     try {
-      const { ethers: ethers3 } = await import('ethers');
+      const { ethers: ethers4 } = await import('ethers');
       const isCreate3 = CREATE3_CHAIN_IDS.has(this.chainId);
       const abi = isCreate3 ? OPERATOR_ABI_CREATE3 : OPERATOR_ABI;
       const amt = amount || paymentInfo.maxAmount;
       const tuple = this.buildTuple(paymentInfo);
       if (this.walletAdapter) {
-        return this.sendViaAdapter(ethers3, abi, (iface) => {
+        return this.sendViaAdapter(ethers4, abi, (iface) => {
           return isCreate3 ? iface.encodeFunctionData("refundInEscrow", [tuple, amt, "0x"]) : iface.encodeFunctionData("refundInEscrow", [tuple, amt]);
         });
       }
-      const contract = new ethers3.Contract(this.contracts.operator, abi, this.signer);
+      const contract = new ethers4.Contract(this.contracts.operator, abi, this.signer);
       const tx = isCreate3 ? await contract.refundInEscrow(tuple, amt, "0x", { gasLimit: this.gasLimit }) : await contract.refundInEscrow(tuple, amt, { gasLimit: this.gasLimit });
       const receipt = await tx.wait();
       return {
@@ -4465,30 +4660,49 @@ var AdvancedEscrowClient = class {
    * const result = await client.releaseViaFacilitator(pi);
    * console.log(result.transactionHash);
    * ```
+   *
+   * @example Signed release (the payer proves the release is theirs to ask for)
+   * ```typescript
+   * await client.releaseViaFacilitator(pi, undefined, {
+   *   lifecycleSigner: payerWallet,   // EnvKeyAdapter, OWS, wagmiLifecycleSigner(...)
+   * });
+   * ```
    */
-  async releaseViaFacilitator(paymentInfo, amount) {
+  async releaseViaFacilitator(paymentInfo, amount, options) {
     if (!this.payerAddress) await this.init();
     try {
+      const wirePaymentInfo = {
+        operator: paymentInfo.operator,
+        receiver: paymentInfo.receiver,
+        token: paymentInfo.token,
+        maxAmount: paymentInfo.maxAmount,
+        preApprovalExpiry: paymentInfo.preApprovalExpiry,
+        authorizationExpiry: paymentInfo.authorizationExpiry,
+        refundExpiry: paymentInfo.refundExpiry,
+        minFeeBps: paymentInfo.minFeeBps,
+        maxFeeBps: paymentInfo.maxFeeBps,
+        feeReceiver: paymentInfo.feeReceiver,
+        salt: paymentInfo.salt
+      };
+      const releaseAmount = amount || paymentInfo.maxAmount;
+      const lifecycleAuth = options?.lifecycleSigner ? await buildLifecycleAuth({
+        action: "release",
+        paymentInfo: wirePaymentInfo,
+        payer: this.payerAddress,
+        amount: releaseAmount,
+        chainId: this.chainId,
+        wallet: options.lifecycleSigner,
+        deadline: options.lifecycleDeadline
+      }) : void 0;
       const payload = {
         x402Version: 2,
         scheme: "escrow",
         action: "release",
         payload: {
-          paymentInfo: {
-            operator: paymentInfo.operator,
-            receiver: paymentInfo.receiver,
-            token: paymentInfo.token,
-            maxAmount: paymentInfo.maxAmount,
-            preApprovalExpiry: paymentInfo.preApprovalExpiry,
-            authorizationExpiry: paymentInfo.authorizationExpiry,
-            refundExpiry: paymentInfo.refundExpiry,
-            minFeeBps: paymentInfo.minFeeBps,
-            maxFeeBps: paymentInfo.maxFeeBps,
-            feeReceiver: paymentInfo.feeReceiver,
-            salt: paymentInfo.salt
-          },
+          paymentInfo: wirePaymentInfo,
           payer: this.payerAddress,
-          amount: amount || paymentInfo.maxAmount
+          amount: releaseAmount,
+          ...lifecycleAuth ? { lifecycleAuth } : {}
         },
         paymentRequirements: {
           scheme: "escrow",
@@ -4591,29 +4805,41 @@ var AdvancedEscrowClient = class {
    * }
    * ```
    */
-  async refundViaFacilitator(paymentInfo, amount) {
+  async refundViaFacilitator(paymentInfo, amount, options) {
     if (!this.payerAddress) await this.init();
     try {
+      const wirePaymentInfo = {
+        operator: paymentInfo.operator,
+        receiver: paymentInfo.receiver,
+        token: paymentInfo.token,
+        maxAmount: paymentInfo.maxAmount,
+        preApprovalExpiry: paymentInfo.preApprovalExpiry,
+        authorizationExpiry: paymentInfo.authorizationExpiry,
+        refundExpiry: paymentInfo.refundExpiry,
+        minFeeBps: paymentInfo.minFeeBps,
+        maxFeeBps: paymentInfo.maxFeeBps,
+        feeReceiver: paymentInfo.feeReceiver,
+        salt: paymentInfo.salt
+      };
+      const refundAmount = amount || paymentInfo.maxAmount;
+      const lifecycleAuth = options?.lifecycleSigner ? await buildLifecycleAuth({
+        action: "refundInEscrow",
+        paymentInfo: wirePaymentInfo,
+        payer: this.payerAddress,
+        amount: refundAmount,
+        chainId: this.chainId,
+        wallet: options.lifecycleSigner,
+        deadline: options.lifecycleDeadline
+      }) : void 0;
       const payload = {
         x402Version: 2,
         scheme: "escrow",
         action: "refundInEscrow",
         payload: {
-          paymentInfo: {
-            operator: paymentInfo.operator,
-            receiver: paymentInfo.receiver,
-            token: paymentInfo.token,
-            maxAmount: paymentInfo.maxAmount,
-            preApprovalExpiry: paymentInfo.preApprovalExpiry,
-            authorizationExpiry: paymentInfo.authorizationExpiry,
-            refundExpiry: paymentInfo.refundExpiry,
-            minFeeBps: paymentInfo.minFeeBps,
-            maxFeeBps: paymentInfo.maxFeeBps,
-            feeReceiver: paymentInfo.feeReceiver,
-            salt: paymentInfo.salt
-          },
+          paymentInfo: wirePaymentInfo,
           payer: this.payerAddress,
-          amount: amount || paymentInfo.maxAmount
+          amount: refundAmount,
+          ...lifecycleAuth ? { lifecycleAuth } : {}
         },
         paymentRequirements: {
           scheme: "escrow",
@@ -4733,7 +4959,7 @@ var AdvancedEscrowClient = class {
   async charge(paymentInfo, amount) {
     if (!this.payerAddress) await this.init();
     try {
-      const { ethers: ethers3 } = await import('ethers');
+      const { ethers: ethers4 } = await import('ethers');
       const nonce = await this.computeNonce(paymentInfo);
       const amt = amount || paymentInfo.maxAmount;
       const auth = {
@@ -4745,10 +4971,10 @@ var AdvancedEscrowClient = class {
         nonce
       };
       const signature = await this.signErc3009(auth);
-      const collectorData = ethers3.getBytes(signature);
+      const collectorData = ethers4.getBytes(signature);
       const tuple = this.buildTuple(paymentInfo);
       if (this.walletAdapter) {
-        return this.sendViaAdapter(ethers3, OPERATOR_ABI, (iface) => {
+        return this.sendViaAdapter(ethers4, OPERATOR_ABI, (iface) => {
           return iface.encodeFunctionData("charge", [
             tuple,
             amt,
@@ -4757,7 +4983,7 @@ var AdvancedEscrowClient = class {
           ]);
         });
       }
-      const contract = new ethers3.Contract(this.contracts.operator, OPERATOR_ABI, this.signer);
+      const contract = new ethers4.Contract(this.contracts.operator, OPERATOR_ABI, this.signer);
       const tx = await contract.charge(
         tuple,
         amt,
@@ -4799,11 +5025,11 @@ var AdvancedEscrowClient = class {
   async refundPostEscrow(paymentInfo, amount, tokenCollector, collectorData) {
     if (!this.payerAddress) await this.init();
     try {
-      const { ethers: ethers3 } = await import('ethers');
+      const { ethers: ethers4 } = await import('ethers');
       const amt = amount || paymentInfo.maxAmount;
       const tuple = this.buildTuple(paymentInfo);
       if (this.walletAdapter) {
-        return this.sendViaAdapter(ethers3, OPERATOR_ABI, (iface) => {
+        return this.sendViaAdapter(ethers4, OPERATOR_ABI, (iface) => {
           return iface.encodeFunctionData("refundPostEscrow", [
             tuple,
             amt,
@@ -4812,7 +5038,7 @@ var AdvancedEscrowClient = class {
           ]);
         });
       }
-      const contract = new ethers3.Contract(this.contracts.operator, OPERATOR_ABI, this.signer);
+      const contract = new ethers4.Contract(this.contracts.operator, OPERATOR_ABI, this.signer);
       const tx = await contract.refundPostEscrow(
         tuple,
         amt,