@pafi-dev/issuer 0.5.29 → 0.5.31

package/dist/index.d.cts

@@ -369,6 +369,23 @@ declare class RelayError extends Error {
     constructor(code: RelayErrorCode, message: string, cause?: unknown);
 }
 
+/**
+ * Optional config that lets `RelayService` auto-quote the operator fee
+ * + auto-resolve the recipient when callers don't pass `feeAmount` /
+ * `feeRecipient`. When both `provider` + `chainId` are set, callers can
+ * omit the fee params entirely; the service will:
+ *
+ *  1. Resolve `feeRecipient = getContractAddresses(chainId).pafiFeeRecipient`
+ *  2. If `feeAmount` is undefined → run `quoteOperatorFeePt(...)` against
+ *     Chainlink + V4 subgraph to compute the PT amount.
+ *
+ * When unset, the legacy "caller passes feeAmount + feeRecipient or no
+ * fee" behavior applies, so existing integrations keep working.
+ */
+interface RelayServiceConfig {
+    provider?: PublicClient;
+    chainId?: number;
+}
 /**
  * Builds unsigned `PartialUserOperation` payloads for the v1.4 sponsored
  * flow. The service is stateless and HTTP-client-free:
@@ -385,6 +402,26 @@ declare class RelayError extends Error {
  * concerns moved to the Bundler + Paymaster in v1.4.
  */
 declare class RelayService {
+    private readonly provider;
+    private readonly chainId;
+    constructor(config?: RelayServiceConfig);
+    /**
+     * Resolve the fee recipient + amount applied to the next UserOp:
+     *
+     *  - If caller passed an explicit `feeRecipient`, use it (testing
+     *    only — sponsor-relayer's L1 will reject any non-canonical
+     *    recipient with `INSUFFICIENT_FEE`). Otherwise, default to
+     *    `getContractAddresses(chainId).pafiFeeRecipient` when the
+     *    service has a `chainId` configured.
+     *  - If caller passed `feeAmount`, use it. Otherwise, when the
+     *    service has both `provider` + `chainId`, auto-quote via
+     *    `quoteOperatorFeePt`.
+     *  - When the service is unconfigured AND caller passed nothing,
+     *    return `{ feeAmount: 0n, feeRecipient: undefined }` — legacy
+     *    "no fee" behavior, caller must opt in for the gas-reimbursement
+     *    transfer to be added to the batch.
+     */
+    private resolveFee;
     /**
      * Build an unsigned UserOp for Scenario 1 (Mint) — sig-gated
      * `PointToken.mint(to, amount, deadline, minterSig)`.
@@ -401,7 +438,7 @@ declare class RelayService {
      *     burnerSig)`. Caller provides a pre-signed `BurnRequest` + sig
      *     bytes (typically from `PTRedeemHandler`).
      */
-    prepareBurn(params: PrepareBurnParams): PartialUserOperation;
+    prepareBurn(params: PrepareBurnParams): Promise<PartialUserOperation>;
 }
 /**
  * v1.4 — sig-gated `PointToken.mint(to, amount, deadline, minterSig)`.
@@ -1730,6 +1767,26 @@ interface PendingUserOpEntry {
     chainId: number;
     /** Hex-encoded userOpHash — the value the user signed via personal_sign. */
     userOpHash: Hex;
+    /**
+     * Fee-stripped fallback variant. Set by `/claim/prepare` and
+     * `/redeem/prepare` when a PT operator fee is configured AND the
+     * paymaster sponsorship attached successfully — i.e. the user might
+     * still want to submit without paymaster (paying ETH gas), and in
+     * that case shouldn't be charged the PT fee. `/claim/submit` reads
+     * this branch when its request body specifies
+     * `variant: "fallback"`.
+     *
+     * Has a different `callData` (no PT.transfer prepended) and
+     * therefore a different `userOpHash`. Paymaster fields are NOT
+     * present — the fallback is by definition unsponsored.
+     */
+    fallback?: {
+        callData: Hex;
+        callGasLimit: string;
+        verificationGasLimit: string;
+        preVerificationGas: string;
+        userOpHash: Hex;
+    };
 }
 /**
  * Storage backend for pending UserOps in the mobile prepare/submit pattern.
@@ -1755,7 +1812,7 @@ interface IPendingUserOpStore {
  * Bridges the gap between the serialized storage format (decimal strings,
  * safe for JSON/Redis) and `serializeUserOpToJsonRpc` which expects bigints.
  */
-declare function serializeEntryToJsonRpc(entry: PendingUserOpEntry, signature: Hex): Record<string, string | null>;
+declare function serializeEntryToJsonRpc(entry: PendingUserOpEntry, signature: Hex, variant?: "sponsored" | "fallback"): Record<string, string | null>;
 
 interface IssuerRegistryRecord {
     issuerAddress: Address;

package/dist/index.d.ts

@@ -369,6 +369,23 @@ declare class RelayError extends Error {
     constructor(code: RelayErrorCode, message: string, cause?: unknown);
 }
 
+/**
+ * Optional config that lets `RelayService` auto-quote the operator fee
+ * + auto-resolve the recipient when callers don't pass `feeAmount` /
+ * `feeRecipient`. When both `provider` + `chainId` are set, callers can
+ * omit the fee params entirely; the service will:
+ *
+ *  1. Resolve `feeRecipient = getContractAddresses(chainId).pafiFeeRecipient`
+ *  2. If `feeAmount` is undefined → run `quoteOperatorFeePt(...)` against
+ *     Chainlink + V4 subgraph to compute the PT amount.
+ *
+ * When unset, the legacy "caller passes feeAmount + feeRecipient or no
+ * fee" behavior applies, so existing integrations keep working.
+ */
+interface RelayServiceConfig {
+    provider?: PublicClient;
+    chainId?: number;
+}
 /**
  * Builds unsigned `PartialUserOperation` payloads for the v1.4 sponsored
  * flow. The service is stateless and HTTP-client-free:
@@ -385,6 +402,26 @@ declare class RelayError extends Error {
  * concerns moved to the Bundler + Paymaster in v1.4.
  */
 declare class RelayService {
+    private readonly provider;
+    private readonly chainId;
+    constructor(config?: RelayServiceConfig);
+    /**
+     * Resolve the fee recipient + amount applied to the next UserOp:
+     *
+     *  - If caller passed an explicit `feeRecipient`, use it (testing
+     *    only — sponsor-relayer's L1 will reject any non-canonical
+     *    recipient with `INSUFFICIENT_FEE`). Otherwise, default to
+     *    `getContractAddresses(chainId).pafiFeeRecipient` when the
+     *    service has a `chainId` configured.
+     *  - If caller passed `feeAmount`, use it. Otherwise, when the
+     *    service has both `provider` + `chainId`, auto-quote via
+     *    `quoteOperatorFeePt`.
+     *  - When the service is unconfigured AND caller passed nothing,
+     *    return `{ feeAmount: 0n, feeRecipient: undefined }` — legacy
+     *    "no fee" behavior, caller must opt in for the gas-reimbursement
+     *    transfer to be added to the batch.
+     */
+    private resolveFee;
     /**
      * Build an unsigned UserOp for Scenario 1 (Mint) — sig-gated
      * `PointToken.mint(to, amount, deadline, minterSig)`.
@@ -401,7 +438,7 @@ declare class RelayService {
      *     burnerSig)`. Caller provides a pre-signed `BurnRequest` + sig
      *     bytes (typically from `PTRedeemHandler`).
      */
-    prepareBurn(params: PrepareBurnParams): PartialUserOperation;
+    prepareBurn(params: PrepareBurnParams): Promise<PartialUserOperation>;
 }
 /**
  * v1.4 — sig-gated `PointToken.mint(to, amount, deadline, minterSig)`.
@@ -1730,6 +1767,26 @@ interface PendingUserOpEntry {
     chainId: number;
     /** Hex-encoded userOpHash — the value the user signed via personal_sign. */
     userOpHash: Hex;
+    /**
+     * Fee-stripped fallback variant. Set by `/claim/prepare` and
+     * `/redeem/prepare` when a PT operator fee is configured AND the
+     * paymaster sponsorship attached successfully — i.e. the user might
+     * still want to submit without paymaster (paying ETH gas), and in
+     * that case shouldn't be charged the PT fee. `/claim/submit` reads
+     * this branch when its request body specifies
+     * `variant: "fallback"`.
+     *
+     * Has a different `callData` (no PT.transfer prepended) and
+     * therefore a different `userOpHash`. Paymaster fields are NOT
+     * present — the fallback is by definition unsponsored.
+     */
+    fallback?: {
+        callData: Hex;
+        callGasLimit: string;
+        verificationGasLimit: string;
+        preVerificationGas: string;
+        userOpHash: Hex;
+    };
 }
 /**
  * Storage backend for pending UserOps in the mobile prepare/submit pattern.
@@ -1755,7 +1812,7 @@ interface IPendingUserOpStore {
  * Bridges the gap between the serialized storage format (decimal strings,
  * safe for JSON/Redis) and `serializeUserOpToJsonRpc` which expects bigints.
  */
-declare function serializeEntryToJsonRpc(entry: PendingUserOpEntry, signature: Hex): Record<string, string | null>;
+declare function serializeEntryToJsonRpc(entry: PendingUserOpEntry, signature: Hex, variant?: "sponsored" | "fallback"): Record<string, string | null>;
 
 interface IssuerRegistryRecord {
     issuerAddress: Address;

package/dist/index.js

@@ -388,9 +388,48 @@ import {
 import {
   POINT_TOKEN_V2_ABI,
   buildPartialUserOperation,
-  signMintRequest
+  signMintRequest,
+  getContractAddresses,
+  quoteOperatorFeePt
 } from "@pafi-dev/core";
 var RelayService = class {
+  provider;
+  chainId;
+  constructor(config = {}) {
+    this.provider = config.provider;
+    this.chainId = config.chainId;
+  }
+  /**
+   * Resolve the fee recipient + amount applied to the next UserOp:
+   *
+   *  - If caller passed an explicit `feeRecipient`, use it (testing
+   *    only — sponsor-relayer's L1 will reject any non-canonical
+   *    recipient with `INSUFFICIENT_FEE`). Otherwise, default to
+   *    `getContractAddresses(chainId).pafiFeeRecipient` when the
+   *    service has a `chainId` configured.
+   *  - If caller passed `feeAmount`, use it. Otherwise, when the
+   *    service has both `provider` + `chainId`, auto-quote via
+   *    `quoteOperatorFeePt`.
+   *  - When the service is unconfigured AND caller passed nothing,
+   *    return `{ feeAmount: 0n, feeRecipient: undefined }` — legacy
+   *    "no fee" behavior, caller must opt in for the gas-reimbursement
+   *    transfer to be added to the batch.
+   */
+  async resolveFee(params) {
+    const feeRecipient = params.feeRecipient ?? (this.chainId !== void 0 ? getContractAddresses(this.chainId).pafiFeeRecipient : void 0);
+    if (params.feeAmount !== void 0) {
+      return { feeAmount: params.feeAmount, feeRecipient };
+    }
+    if (this.provider && this.chainId !== void 0) {
+      const feeAmount = await quoteOperatorFeePt({
+        provider: this.provider,
+        chainId: this.chainId,
+        pointTokenAddress: params.pointTokenAddress
+      });
+      return { feeAmount, feeRecipient };
+    }
+    return { feeAmount: 0n, feeRecipient };
+  }
   /**
    * Build an unsigned UserOp for Scenario 1 (Mint) — sig-gated
    * `PointToken.mint(to, amount, deadline, minterSig)`.
@@ -475,14 +514,19 @@ var RelayService = class {
         data: mintCallData
       }
     ];
-    if (params.feeAmount && params.feeAmount > 0n) {
-      if (!params.feeRecipient) {
+    const { feeAmount, feeRecipient } = await this.resolveFee({
+      feeAmount: params.feeAmount,
+      feeRecipient: params.feeRecipient,
+      pointTokenAddress: params.pointTokenAddress
+    });
+    if (feeAmount > 0n) {
+      if (!feeRecipient) {
         throw new RelayError(
           "ENCODE_FAILED",
-          "prepareMint: feeRecipient required when feeAmount > 0"
+          "prepareMint: feeRecipient could not be resolved \u2014 pass `feeRecipient` explicitly or construct RelayService with a `chainId`."
         );
       }
-      if (params.feeRecipient === "0x0000000000000000000000000000000000000000") {
+      if (feeRecipient === "0x0000000000000000000000000000000000000000") {
         throw new RelayError(
           "ENCODE_FAILED",
           "prepareMint: feeRecipient must not be zero address"
@@ -494,7 +538,7 @@ var RelayService = class {
         data: encodeFunctionData({
           abi: erc20Abi,
           functionName: "transfer",
-          args: [params.feeRecipient, params.feeAmount]
+          args: [feeRecipient, feeAmount]
         })
       });
     }
@@ -520,7 +564,7 @@ var RelayService = class {
    *     burnerSig)`. Caller provides a pre-signed `BurnRequest` + sig
    *     bytes (typically from `PTRedeemHandler`).
    */
-  prepareBurn(params) {
+  async prepareBurn(params) {
     if (!params.pointTokenAddress) {
       throw new RelayError("ENCODE_FAILED", "prepareBurn: pointTokenAddress required");
     }
@@ -561,14 +605,19 @@ var RelayService = class {
       );
     }
     const operations = [];
-    if (params.feeAmount && params.feeAmount > 0n) {
-      if (!params.feeRecipient) {
+    const { feeAmount, feeRecipient } = await this.resolveFee({
+      feeAmount: params.feeAmount,
+      feeRecipient: params.feeRecipient,
+      pointTokenAddress: params.pointTokenAddress
+    });
+    if (feeAmount > 0n) {
+      if (!feeRecipient) {
         throw new RelayError(
           "ENCODE_FAILED",
-          "prepareBurn: feeRecipient required when feeAmount > 0"
+          "prepareBurn: feeRecipient could not be resolved \u2014 pass `feeRecipient` explicitly or construct RelayService with a `chainId`."
         );
       }
-      if (params.feeRecipient === "0x0000000000000000000000000000000000000000") {
+      if (feeRecipient === "0x0000000000000000000000000000000000000000") {
         throw new RelayError(
           "ENCODE_FAILED",
           "prepareBurn: feeRecipient must not be zero address"
@@ -580,7 +629,7 @@ var RelayService = class {
         data: encodeFunctionData({
           abi: erc20Abi,
           functionName: "transfer",
-          args: [params.feeRecipient, params.feeAmount]
+          args: [feeRecipient, feeAmount]
         })
       });
     }
@@ -1420,7 +1469,7 @@ var PTRedeemHandler = class {
       this.redeemLockDurationMs,
       this.pointTokenAddress
     );
-    const sponsoredUserOp = this.relayService.prepareBurn({
+    const sponsoredUserOp = await this.relayService.prepareBurn({
       mode: "burnWithSig",
       userAddress: request.userAddress,
       aaNonce: request.aaNonce,
@@ -1454,15 +1503,19 @@ var PTRedeemHandler = class {
         this.redeemLockDurationMs,
         this.pointTokenAddress
       );
-      const fallbackUserOp = this.relayService.prepareBurn({
+      const fallbackUserOp = await this.relayService.prepareBurn({
         mode: "burnWithSig",
         userAddress: request.userAddress,
         aaNonce: request.aaNonce,
         pointTokenAddress: this.pointTokenAddress,
         batchExecutorAddress: this.batchExecutorAddress,
         burnRequest: fallbackBurnRequest,
-        burnerSignature: fallbackSig
-        // No feeAmount/feeRecipient — fallback is fee-free.
+        burnerSignature: fallbackSig,
+        // Explicit 0n — fallback is fee-free regardless of how
+        // RelayService is configured. Without this, an
+        // auto-quoting RelayService would try to quote a fee here
+        // and re-add the PT.transfer we're trying to strip.
+        feeAmount: 0n
       });
       fallback = {
         lockId: fallbackLockId,
@@ -2164,7 +2217,7 @@ var PafiBackendClient = class {
 
 // src/config.ts
 import { getAddress as getAddress8 } from "viem";
-import { getContractAddresses } from "@pafi-dev/core";
+import { getContractAddresses as getContractAddresses2 } from "@pafi-dev/core";
 function createIssuerService(config) {
   if (!config.provider) {
     throw new Error("createIssuerService: provider is required");
@@ -2198,7 +2251,10 @@ function createIssuerService(config) {
     authServiceConfig.jwtExpiresIn = config.auth.jwtExpiresIn;
   }
   const authService = new AuthService(authServiceConfig);
-  const relayService = new RelayService();
+  const relayService = new RelayService({
+    provider: config.provider,
+    chainId: config.chainId
+  });
   let feeManager;
   if (config.fee) {
     feeManager = new FeeManager({
@@ -2231,7 +2287,7 @@ function createIssuerService(config) {
     indexers.set(tokenAddress, new PointIndexer(indexerConfig));
   }
   const firstIndexer = indexers.get(tokenAddresses[0]);
-  const chainAddresses = getContractAddresses(config.chainId);
+  const chainAddresses = getContractAddresses2(config.chainId);
   const resolvedContracts = {
     batchExecutor: chainAddresses.batchExecutor,
     usdt: chainAddresses.usdt,
@@ -2280,7 +2336,28 @@ function createIssuerService(config) {
 
 // src/userop-store/serialize.ts
 import { serializeUserOpToJsonRpc } from "@pafi-dev/core";
-function serializeEntryToJsonRpc(entry, signature) {
+function serializeEntryToJsonRpc(entry, signature, variant = "sponsored") {
+  if (variant === "fallback") {
+    if (!entry.fallback) {
+      throw new Error(
+        "serializeEntryToJsonRpc: variant=fallback requested but the stored entry has no `fallback` branch \u2014 caller should resubmit with variant='sponsored' or re-prepare with a fee configured."
+      );
+    }
+    return serializeUserOpToJsonRpc(
+      {
+        sender: entry.sender,
+        nonce: BigInt(entry.nonce),
+        callData: entry.fallback.callData,
+        callGasLimit: BigInt(entry.fallback.callGasLimit),
+        verificationGasLimit: BigInt(entry.fallback.verificationGasLimit),
+        preVerificationGas: BigInt(entry.fallback.preVerificationGas),
+        maxFeePerGas: BigInt(entry.maxFeePerGas),
+        maxPriorityFeePerGas: BigInt(entry.maxPriorityFeePerGas)
+        // intentionally no paymaster — user pays ETH gas
+      },
+      signature
+    );
+  }
   return serializeUserOpToJsonRpc(
     {
       sender: entry.sender,
@@ -2305,7 +2382,7 @@ import { getAddress as getAddress9 } from "viem";
 import {
   POINT_TOKEN_V2_ABI as POINT_TOKEN_V2_ABI3,
   issuerRegistryGetIssuerFlatAbi,
-  getContractAddresses as getContractAddresses2
+  getContractAddresses as getContractAddresses3
 } from "@pafi-dev/core";
 
 // src/issuer-state/types.ts
@@ -2337,7 +2414,7 @@ var IssuerStateValidator = class _IssuerStateValidator {
    * `CONTRACT_ADDRESSES` map for the given chain.
    */
   static forChain(provider, chainId) {
-    const { issuerRegistry } = getContractAddresses2(chainId);
+    const { issuerRegistry } = getContractAddresses3(chainId);
     return new _IssuerStateValidator(provider, issuerRegistry);
   }
   /**