@pafi-dev/issuer 0.2.0 → 0.3.0-beta.0

package/dist/index.cjs

@@ -22,6 +22,8 @@ var index_exports = {};
 __export(index_exports, {
   AuthError: () => AuthError,
   AuthService: () => AuthService,
+  BalanceAggregator: () => BalanceAggregator,
+  BurnIndexer: () => BurnIndexer,
   DefaultPolicyEngine: () => DefaultPolicyEngine,
   FeeManager: () => FeeManager,
   InMemoryCursorStore: () => InMemoryCursorStore,
@@ -32,10 +34,16 @@ __export(index_exports, {
   MintingGatewayError: () => MintingGatewayError,
   NonceManager: () => NonceManager,
   PAFI_ISSUER_SDK_VERSION: () => PAFI_ISSUER_SDK_VERSION,
+  PTRedeemError: () => PTRedeemError,
+  PTRedeemHandler: () => PTRedeemHandler,
+  PafiBackendClient: () => PafiBackendClient,
+  PafiBackendError: () => PafiBackendError,
   PointIndexer: () => PointIndexer,
   PrivateKeySigner: () => PrivateKeySigner,
   RelayError: () => RelayError,
   RelayService: () => RelayService,
+  TopUpRedemptionError: () => TopUpRedemptionError,
+  TopUpRedemptionHandler: () => TopUpRedemptionHandler,
   authenticateRequest: () => authenticateRequest,
   createIssuerService: () => createIssuerService,
   createSubgraphNativeUsdtQuoter: () => createSubgraphNativeUsdtQuoter,
@@ -162,6 +170,54 @@ var MemoryPointLedger = class {
     if (txHash) lock.txHash = txHash;
   }
   // -------------------------------------------------------------------------
+  // v1.4 — Reverse flow (PT burn → off-chain credit)
+  // -------------------------------------------------------------------------
+  pendingCredits = /* @__PURE__ */ new Map();
+  nextCreditId = 1;
+  async reservePendingCredit(userAddress, amount, durationMs, tokenAddress) {
+    if (amount <= 0n) {
+      throw new Error(
+        "MemoryPointLedger: pending credit amount must be positive"
+      );
+    }
+    if (durationMs <= 0) {
+      throw new Error("MemoryPointLedger: durationMs must be positive");
+    }
+    const user = (0, import_viem.getAddress)(userAddress);
+    const lockId = `credit-${this.nextCreditId++}`;
+    const now = this.now();
+    this.pendingCredits.set(lockId, {
+      lockId,
+      userAddress: user,
+      amount,
+      tokenAddress: tokenAddress !== void 0 ? (0, import_viem.getAddress)(tokenAddress) : void 0,
+      createdAt: now,
+      expiresAt: now + durationMs,
+      status: "PENDING"
+    });
+    return lockId;
+  }
+  async resolveCreditByBurnTx(lockId, txHash) {
+    const credit = this.pendingCredits.get(lockId);
+    if (!credit) {
+      throw new Error(
+        `MemoryPointLedger: unknown pending credit lockId ${lockId}`
+      );
+    }
+    if (credit.status === "RESOLVED") {
+      if (credit.txHash === txHash) return;
+      throw new Error(
+        `MemoryPointLedger: credit ${lockId} already resolved with a different txHash`
+      );
+    }
+    const token = normalizeToken(credit.tokenAddress);
+    const key = balanceKey(credit.userAddress, token);
+    const current = this.balances.get(key) ?? 0n;
+    this.balances.set(key, current + credit.amount);
+    credit.status = "RESOLVED";
+    credit.txHash = txHash;
+  }
+  // -------------------------------------------------------------------------
   // Internal helpers
   // -------------------------------------------------------------------------
   /**
@@ -578,6 +634,7 @@ var RelayError = class extends Error {
 };
 
 // src/relay/relayService.ts
+var import_viem5 = require("viem");
 var import_core3 = require("@pafi-dev/core");
 var DEFAULT_CONFIRMATION_TIMEOUT_MS = 6e4;
 var RelayService = class {
@@ -630,6 +687,11 @@ var RelayService = class {
    * decide whether to release the ledger lock (`SUBMIT_FAILED` and
    * `SIMULATION_FAILED` are safe to release; `TX_REVERTED` and `TIMEOUT`
    * need manual review because the tx may still land).
+   *
+   * @deprecated Since 0.3.0 — will be replaced by `prepareMint()` +
+   * `prepareBurn()` in the v1.4 sponsored-UserOp flow. The SC team
+   * still needs to finalize Relayer v2 ABI before the replacements
+   * can ship (blocker B1). Kept for v0.2.x consumers. Removed in 2.0.
    */
   async submitMintAndSwap(params) {
     if (this.simulateBeforeSubmit && this.provider) {
@@ -698,6 +760,154 @@ var RelayService = class {
       );
     }
   }
+  // ==========================================================================
+  // v1.4 — Sponsored UserOp preparation (beta with mocked SC contracts)
+  // ==========================================================================
+  //
+  // These two methods build unsigned `PartialUserOperation` payloads for
+  // the Frontend to sign (via Privy) and submit to the Bundler. The
+  // Issuer Backend no longer broadcasts — that's the Frontend's job.
+  //
+  // Uses mocked Relayer v2 + PointToken ABIs from `@pafi-dev/core/contracts`.
+  // When SC delivers real ABIs, the imports swap but these method bodies
+  // stay the same (calldata encoder is ABI-driven).
+  // ==========================================================================
+  /**
+   * Build an unsigned UserOp for Scenario 1 (Mint).
+   *
+   * Flow:
+   *   1. Encode `Relayer.mint(request, userSig, issuerSig)` as the inner call
+   *   2. Optionally append a PT fee transfer from user → feeRecipient
+   *      (fee recovery happens on-chain via BatchExecutor, not via an
+   *      operator wallet)
+   *   3. Wrap all inner calls into `BatchExecutor.execute(calls[])`
+   *   4. Return a `PartialUserOperation` ready for:
+   *        - gas estimation (Bundler)
+   *        - paymaster sponsorship (PAFI Backend)
+   *        - user signature (Privy)
+   */
+  prepareMint(params) {
+    if (!params.relayerAddress) {
+      throw new RelayError("ENCODE_FAILED", "prepareMint: relayerAddress required");
+    }
+    if (!params.batchExecutorAddress) {
+      throw new RelayError(
+        "ENCODE_FAILED",
+        "prepareMint: batchExecutorAddress required"
+      );
+    }
+    if (!params.userAddress) {
+      throw new RelayError("ENCODE_FAILED", "prepareMint: userAddress required");
+    }
+    let mintCallData;
+    try {
+      mintCallData = (0, import_viem5.encodeFunctionData)({
+        abi: import_core3.RELAYER_V2_ABI,
+        functionName: "mint",
+        args: [params.mintRequest, params.userSignature, params.issuerSignature]
+      });
+    } catch (err) {
+      throw new RelayError(
+        "ENCODE_FAILED",
+        `prepareMint: failed to encode Relayer.mint: ${errorMessage(err)}`,
+        err
+      );
+    }
+    const operations = [
+      {
+        target: params.relayerAddress,
+        value: 0n,
+        data: mintCallData
+      }
+    ];
+    if (params.mintRequest.feeAmount > 0n) {
+      operations.push({
+        target: params.pointTokenAddress,
+        value: 0n,
+        data: (0, import_viem5.encodeFunctionData)({
+          abi: import_core3.POINT_TOKEN_V2_ABI,
+          functionName: "balanceOf",
+          // placeholder — real impl uses transfer
+          args: [params.mintRequest.feeRecipient]
+        })
+      });
+    }
+    return (0, import_core3.buildPartialUserOperation)({
+      sender: params.userAddress,
+      nonce: params.aaNonce,
+      operations,
+      gasLimits: {
+        callGasLimit: params.callGasLimit ?? 500000n,
+        verificationGasLimit: params.verificationGasLimit ?? 150000n,
+        preVerificationGas: params.preVerificationGas ?? 50000n
+      }
+    });
+  }
+  /**
+   * Build an unsigned UserOp for Scenario 2 (Burn/Redeem).
+   *
+   * Two modes:
+   *   - `mode: 'burn'` — direct `PointToken.burn(amount)`; `msg.sender`
+   *     via EIP-7702 delegation is the user, so no signature needed
+   *     on-chain (the BurnConsent was already verified off-chain by
+   *     the issuer backend before we got here)
+   *   - `mode: 'burnWithSig'` — `PointToken.burnWithSig(consent, sig)`;
+   *     used when the issuer hasn't verified the consent and the
+   *     contract has to do it on-chain
+   */
+  prepareBurn(params) {
+    if (!params.pointTokenAddress) {
+      throw new RelayError("ENCODE_FAILED", "prepareBurn: pointTokenAddress required");
+    }
+    if (!params.batchExecutorAddress) {
+      throw new RelayError(
+        "ENCODE_FAILED",
+        "prepareBurn: batchExecutorAddress required"
+      );
+    }
+    let burnCallData;
+    try {
+      if (params.mode === "burnWithSig") {
+        if (!params.burnConsent || !params.consentSignature) {
+          throw new Error("burnWithSig requires burnConsent + consentSignature");
+        }
+        burnCallData = (0, import_viem5.encodeFunctionData)({
+          abi: import_core3.POINT_TOKEN_V2_ABI,
+          functionName: "burnWithSig",
+          args: [params.burnConsent, params.consentSignature]
+        });
+      } else {
+        burnCallData = (0, import_viem5.encodeFunctionData)({
+          abi: import_core3.POINT_TOKEN_V2_ABI,
+          functionName: "burn",
+          args: [params.amount]
+        });
+      }
+    } catch (err) {
+      throw new RelayError(
+        "ENCODE_FAILED",
+        `prepareBurn: failed to encode burn call: ${errorMessage(err)}`,
+        err
+      );
+    }
+    const operations = [
+      {
+        target: params.pointTokenAddress,
+        value: 0n,
+        data: burnCallData
+      }
+    ];
+    return (0, import_core3.buildPartialUserOperation)({
+      sender: params.userAddress,
+      nonce: params.aaNonce,
+      operations,
+      gasLimits: {
+        callGasLimit: params.callGasLimit ?? 300000n,
+        verificationGasLimit: params.verificationGasLimit ?? 150000n,
+        preVerificationGas: params.preVerificationGas ?? 50000n
+      }
+    });
+  }
 };
 function errorMessage(err) {
   return err instanceof Error ? err.message : String(err);
@@ -708,84 +918,35 @@ var DEFAULT_GAS_UNITS = 500000n;
 var DEFAULT_PREMIUM_BPS = 12e3;
 var FeeManager = class {
   provider;
-  operatorWallet;
-  mintAndSwapGasUnits;
+  gasUnits;
   gasPremiumBps;
-  quoteNativeToUsdt;
-  rebalanceThresholdWei;
-  rebalanceUsdtAmount;
-  swapUsdtToNative;
+  quoteNativeToFee;
   constructor(config) {
     if (!config.provider) throw new Error("FeeManager: provider required");
-    if (!config.operatorWallet)
-      throw new Error("FeeManager: operatorWallet required");
-    if (!config.quoteNativeToUsdt)
-      throw new Error("FeeManager: quoteNativeToUsdt required");
+    if (!config.quoteNativeToFee)
+      throw new Error("FeeManager: quoteNativeToFee required");
     this.provider = config.provider;
-    this.operatorWallet = config.operatorWallet;
-    this.mintAndSwapGasUnits = config.mintAndSwapGasUnits ?? DEFAULT_GAS_UNITS;
+    this.gasUnits = config.gasUnits ?? DEFAULT_GAS_UNITS;
     this.gasPremiumBps = config.gasPremiumBps ?? DEFAULT_PREMIUM_BPS;
-    this.quoteNativeToUsdt = config.quoteNativeToUsdt;
-    if (config.rebalanceThresholdWei !== void 0) {
-      this.rebalanceThresholdWei = config.rebalanceThresholdWei;
-    }
-    if (config.rebalanceUsdtAmount !== void 0) {
-      this.rebalanceUsdtAmount = config.rebalanceUsdtAmount;
-    }
-    if (config.swapUsdtToNative) {
-      this.swapUsdtToNative = config.swapUsdtToNative;
-    }
-    const rebalanceFields = [
-      config.rebalanceThresholdWei,
-      config.rebalanceUsdtAmount,
-      config.swapUsdtToNative
-    ];
-    const someSet = rebalanceFields.some((v) => v !== void 0);
-    const allSet = rebalanceFields.every((v) => v !== void 0);
-    if (someSet && !allSet) {
-      throw new Error(
-        "FeeManager: rebalanceThresholdWei, rebalanceUsdtAmount, and swapUsdtToNative must all be set together"
-      );
-    }
+    this.quoteNativeToFee = config.quoteNativeToFee;
   }
   /**
-   * Estimate the USDT fee the operator should charge for a single
-   * `mintAndSwap`. Computed as:
+   * Estimate the fee (in the caller's fee currency) to charge for the
+   * next sponsored UserOp:
+   *
+   *   nativeCost    = gasUnits × gasPrice
+   *   withPremium   = nativeCost × premiumBps / 10_000
+   *   fee           = quoteNativeToFee(withPremium)
    *
-   *   nativeCost = gasUnits × gasPrice
-   *   premiumNativeCost = nativeCost × premiumBps / 10_000
-   *   usdtFee = quoteNativeToUsdt(premiumNativeCost)
+   * For backward compatibility with v0.2.x code that reads `gasFeeUsdt`
+   * from the response, the name `estimateGasFee` is kept — but the
+   * currency depends on how the caller wired `quoteNativeToFee`.
    */
   async estimateGasFee() {
     const gasPrice = await this.provider.getGasPrice();
-    const nativeCost = gasPrice * this.mintAndSwapGasUnits;
+    const nativeCost = gasPrice * this.gasUnits;
     const withPremium = nativeCost * BigInt(this.gasPremiumBps) / 10000n;
-    return this.quoteNativeToUsdt(withPremium);
-  }
-  /**
-   * Check the operator's native balance and, if it has dropped below the
-   * configured threshold, trigger a USDT→native rebalance via the injected
-   * `swapUsdtToNative` function.
-   *
-   * Returns `true` if a rebalance was performed, `false` otherwise.
-   * Silently no-ops when rebalance is not configured.
-   */
-  async rebalanceIfNeeded() {
-    if (this.rebalanceThresholdWei === void 0 || this.rebalanceUsdtAmount === void 0 || !this.swapUsdtToNative) {
-      return false;
-    }
-    const operatorAddress = this.operatorWallet.account?.address;
-    if (!operatorAddress) {
-      throw new Error(
-        "FeeManager: operator wallet has no account attached \u2014 cannot read balance"
-      );
-    }
-    const balance = await this.provider.getBalance({ address: operatorAddress });
-    if (balance >= this.rebalanceThresholdWei) {
-      return false;
-    }
-    await this.swapUsdtToNative(this.rebalanceUsdtAmount);
-    return true;
+    return this.quoteNativeToFee(withPremium);
   }
 };
 
@@ -831,6 +992,12 @@ var MintingGateway = class {
     this.now = config.now ?? (() => Date.now());
     this.defaultLockBufferMs = config.defaultLockBufferMs ?? DEFAULT_LOCK_BUFFER_MS;
   }
+  /**
+   * @deprecated Since 0.3.0 — will be renamed to `processMint()` once
+   * the SC team finalizes Relayer v2 ABI. The new flow drops the
+   * swap steps entirely (no more single-call mint+swap); users swap
+   * separately on PAFI Web. Kept here for v0.2.x consumers. Removed in 2.0.
+   */
   async processMintAndCashOut(request) {
     const { receiverConsent, receiverSignature } = request;
     if (!receiverConsent || !receiverSignature) {
@@ -1041,8 +1208,8 @@ var InMemoryCursorStore = class {
 };
 
 // src/indexer/pointIndexer.ts
-var import_viem5 = require("viem");
-var TRANSFER_EVENT = (0, import_viem5.parseAbiItem)(
+var import_viem6 = require("viem");
+var TRANSFER_EVENT = (0, import_viem6.parseAbiItem)(
   "event Transfer(address indexed from, address indexed to, uint256 value)"
 );
 var ZERO_ADDRESS = "0x0000000000000000000000000000000000000000";
@@ -1162,10 +1329,10 @@ var PointIndexer = class {
     for (const log of logs) {
       const args = log.args;
       if (!args.from || !args.to || args.value === void 0) continue;
-      if ((0, import_viem5.getAddress)(args.from) !== ZERO_ADDRESS) continue;
+      if ((0, import_viem6.getAddress)(args.from) !== ZERO_ADDRESS) continue;
       if (log.blockNumber === null || log.transactionHash === null) continue;
       out.push({
-        to: (0, import_viem5.getAddress)(args.to),
+        to: (0, import_viem6.getAddress)(args.to),
         amount: args.value,
         blockNumber: log.blockNumber,
         txHash: log.transactionHash,
@@ -1220,8 +1387,159 @@ function pickMatchingLock(locks, amount) {
   return best;
 }
 
+// src/indexer/burnIndexer.ts
+var import_viem7 = require("viem");
+var TRANSFER_EVENT2 = (0, import_viem7.parseAbiItem)(
+  "event Transfer(address indexed from, address indexed to, uint256 value)"
+);
+var ZERO_ADDRESS2 = "0x0000000000000000000000000000000000000000";
+var DEFAULT_CONFIRMATIONS2 = 3;
+var DEFAULT_BATCH_SIZE2 = 2000n;
+var DEFAULT_POLL_INTERVAL_MS2 = 5e3;
+var BurnIndexer = class {
+  provider;
+  pointTokenAddress;
+  ledger;
+  cursorStore;
+  startBlock;
+  confirmations;
+  batchSize;
+  pollIntervalMs;
+  /**
+   * Caller-supplied matcher. Return the lockId to resolve for a given
+   * burn event, or `undefined` to skip. Runs synchronously via the
+   * ledger's query path.
+   *
+   * Default: try `ledger.resolveCreditByBurnTx` keyed on a synthetic
+   * lock id `burn-${from}-${amount}` — the in-memory ledger assigns
+   * incrementing IDs so callers with the memory ledger must provide a
+   * custom matcher. Real DB-backed ledgers override this to JOIN on
+   * their `pending_credits` table.
+   */
+  matchLockId = async () => void 0;
+  running = false;
+  timer;
+  constructor(config) {
+    if (!config.provider) throw new Error("BurnIndexer: provider required");
+    if (!config.pointTokenAddress)
+      throw new Error("BurnIndexer: pointTokenAddress required");
+    if (!config.ledger) throw new Error("BurnIndexer: ledger required");
+    this.provider = config.provider;
+    this.pointTokenAddress = config.pointTokenAddress;
+    this.ledger = config.ledger;
+    this.cursorStore = config.cursorStore ?? new InMemoryCursorStore();
+    this.startBlock = config.fromBlock ?? 0n;
+    this.confirmations = BigInt(
+      config.confirmations ?? DEFAULT_CONFIRMATIONS2
+    );
+    this.batchSize = BigInt(config.batchSize ?? Number(DEFAULT_BATCH_SIZE2));
+    this.pollIntervalMs = config.pollIntervalMs ?? DEFAULT_POLL_INTERVAL_MS2;
+  }
+  start() {
+    if (this.running) return;
+    this.running = true;
+    void this.tick();
+  }
+  stop() {
+    this.running = false;
+    if (this.timer) {
+      clearTimeout(this.timer);
+      this.timer = void 0;
+    }
+  }
+  async tick() {
+    if (!this.running) return;
+    try {
+      const latest = await this.provider.getBlockNumber();
+      const safeHead = latest - this.confirmations;
+      if (safeHead < 0n) {
+        this.scheduleNext();
+        return;
+      }
+      const stored = await this.cursorStore.load();
+      const from = stored ?? this.startBlock;
+      if (from > safeHead) {
+        this.scheduleNext();
+        return;
+      }
+      await this.processBlockRange(from, safeHead);
+    } catch {
+    }
+    this.scheduleNext();
+  }
+  scheduleNext() {
+    if (!this.running) return;
+    this.timer = setTimeout(() => void this.tick(), this.pollIntervalMs);
+  }
+  /**
+   * Scan `[from, to]` inclusive for burn events. Callers can drive this
+   * directly to backfill a specific range without `start()`. Cursor is
+   * advanced to `to + 1` on completion.
+   */
+  async processBlockRange(from, to) {
+    if (from > to) return;
+    let cursor = from;
+    while (cursor <= to) {
+      const chunkEnd = cursor + this.batchSize - 1n > to ? to : cursor + this.batchSize - 1n;
+      const logs = await this.provider.getLogs({
+        address: this.pointTokenAddress,
+        event: TRANSFER_EVENT2,
+        args: { to: ZERO_ADDRESS2 },
+        // filter: burn = transfer to zero
+        fromBlock: cursor,
+        toBlock: chunkEnd
+      });
+      const events = this.decodeBurnEvents(logs);
+      events.sort((a, b) => {
+        if (a.blockNumber !== b.blockNumber) {
+          return a.blockNumber < b.blockNumber ? -1 : 1;
+        }
+        return a.logIndex - b.logIndex;
+      });
+      for (const evt of events) {
+        await this.finalize(evt);
+      }
+      await this.cursorStore.save(chunkEnd + 1n);
+      cursor = chunkEnd + 1n;
+    }
+  }
+  decodeBurnEvents(logs) {
+    const out = [];
+    for (const log of logs) {
+      const args = log.args;
+      if (!args.from || !args.to || args.value === void 0) continue;
+      if ((0, import_viem7.getAddress)(args.to) !== ZERO_ADDRESS2) continue;
+      if (log.blockNumber === null || log.transactionHash === null) continue;
+      out.push({
+        from: (0, import_viem7.getAddress)(args.from),
+        amount: args.value,
+        blockNumber: log.blockNumber,
+        txHash: log.transactionHash,
+        logIndex: log.logIndex ?? 0
+      });
+    }
+    return out;
+  }
+  /**
+   * Resolve a matching pending credit for this burn event and call
+   * `ledger.resolveCreditByBurnTx(lockId, txHash)`. If no match found,
+   * log + skip.
+   */
+  async finalize(evt) {
+    const lockId = await this.matchLockId(evt);
+    if (!lockId) return;
+    if (!this.ledger.resolveCreditByBurnTx) {
+      return;
+    }
+    try {
+      await this.ledger.resolveCreditByBurnTx(lockId, evt.txHash);
+    } catch {
+    }
+  }
+};
+
 // src/api/handlers.ts
-var import_viem6 = require("viem");
+var import_viem8 = require("viem");
 var import_core5 = require("@pafi-dev/core");
 var IssuerApiHandlers = class {
   authService;
@@ -1239,6 +1557,7 @@ var IssuerApiHandlers = class {
   defaultToken;
   chainId;
   contracts;
+  pafiWebUrl;
   feeManager;
   poolsProvider;
   constructor(config) {
@@ -1252,11 +1571,12 @@ var IssuerApiHandlers = class {
         "IssuerApiHandlers: pointTokenAddress or pointTokenAddresses required"
       );
     }
-    const normalized = raw.map((a) => (0, import_viem6.getAddress)(a));
+    const normalized = raw.map((a) => (0, import_viem8.getAddress)(a));
     this.supportedTokens = new Set(normalized);
     this.defaultToken = normalized[0];
     this.chainId = config.chainId;
     this.contracts = config.contracts;
+    if (config.pafiWebUrl) this.pafiWebUrl = config.pafiWebUrl;
     if (config.feeManager) this.feeManager = config.feeManager;
     if (config.poolsProvider) this.poolsProvider = config.poolsProvider;
   }
@@ -1292,7 +1612,16 @@ var IssuerApiHandlers = class {
         `handleConfig: unsupported chainId ${chainId}, issuer is configured for ${this.chainId}`
       );
     }
-    return { chainId: this.chainId, contracts: { ...this.contracts } };
+    const contracts = {
+      ...this.contracts,
+      pointTokens: Array.from(this.supportedTokens)
+    };
+    const response = {
+      chainId: this.chainId,
+      contracts
+    };
+    if (this.pafiWebUrl) response.pafiWebUrl = this.pafiWebUrl;
+    return response;
   }
   /** `GET /gas-fee` — quoted in USDT (6-decimal base units). */
   async handleGasFee() {
@@ -1343,14 +1672,14 @@ var IssuerApiHandlers = class {
         `handleUser: unsupported chainId ${request.chainId}`
       );
     }
-    const normalizedAuthed = (0, import_viem6.getAddress)(userAddress);
-    const normalizedRequest = (0, import_viem6.getAddress)(request.userAddress);
+    const normalizedAuthed = (0, import_viem8.getAddress)(userAddress);
+    const normalizedRequest = (0, import_viem8.getAddress)(request.userAddress);
     if (normalizedAuthed !== normalizedRequest) {
       throw new Error(
         "handleUser: request userAddress must match authenticated user"
       );
     }
-    const pointToken = (0, import_viem6.getAddress)(request.pointTokenAddress);
+    const pointToken = (0, import_viem8.getAddress)(request.pointTokenAddress);
     if (!this.supportedTokens.has(pointToken)) {
       throw new Error(
         `handleUser: unsupported pointToken ${pointToken}`
@@ -1393,7 +1722,7 @@ var IssuerApiHandlers = class {
         `handleBuildConsentTypedData: unsupported chainId ${request.chainId}`
       );
     }
-    const pointToken = (0, import_viem6.getAddress)(request.pointTokenAddress);
+    const pointToken = (0, import_viem8.getAddress)(request.pointTokenAddress);
     if (!this.supportedTokens.has(pointToken)) {
       throw new Error(
         `handleBuildConsentTypedData: unsupported pointToken ${pointToken}`
@@ -1418,8 +1747,14 @@ var IssuerApiHandlers = class {
   /**
    * `POST /claim-and-swap`
    *
-   * The terminal handler: forwards the verified consent to the
-   * MintingGateway, which runs the 11-step flow.
+   * @deprecated Since 0.3.0 — the single-call mint-then-swap flow is
+   * retired in v1.4. Use the new `handleClaim()` (mint only) and let
+   * the user swap separately on PAFI Web. See
+   * [V1.4_V1.5_OVERVIEW.md §4] for the new scenario model. Will be
+   * removed in 2.0.
+   *
+   * Legacy behavior: the terminal handler forwards the verified
+   * consent to the MintingGateway, which runs the 11-step flow.
    */
   async handleClaimAndSwap(userAddress, request) {
     if (request.chainId !== this.chainId) {
@@ -1427,14 +1762,14 @@ var IssuerApiHandlers = class {
         `handleClaimAndSwap: unsupported chainId ${request.chainId}`
       );
     }
-    const pointToken = (0, import_viem6.getAddress)(request.pointTokenAddress);
+    const pointToken = (0, import_viem8.getAddress)(request.pointTokenAddress);
     if (!this.supportedTokens.has(pointToken)) {
       throw new Error(
         `handleClaimAndSwap: unsupported pointToken ${pointToken}`
       );
     }
     const result = await this.gateway.processMintAndCashOut({
-      userAddress: (0, import_viem6.getAddress)(userAddress),
+      userAddress: (0, import_viem8.getAddress)(userAddress),
       pointTokenAddress: pointToken,
       chainId: request.chainId,
       domain: request.domain,
@@ -1454,6 +1789,183 @@ var IssuerApiHandlers = class {
   }
 };
 
+// src/api/handlers/ptRedeemHandler.ts
+var import_viem9 = require("viem");
+var import_core6 = require("@pafi-dev/core");
+var DEFAULT_REDEEM_LOCK_MS = 15 * 60 * 1e3;
+var PTRedeemError = class extends Error {
+  constructor(code, message) {
+    super(message);
+    this.code = code;
+    this.name = "PTRedeemError";
+  }
+  code;
+};
+var PTRedeemHandler = class {
+  ledger;
+  relayService;
+  pointTokenAddress;
+  batchExecutorAddress;
+  chainId;
+  domain;
+  redeemLockDurationMs;
+  now;
+  constructor(config) {
+    if (!config.ledger.reservePendingCredit) {
+      throw new PTRedeemError(
+        "LEDGER_NOT_SUPPORTED",
+        "PTRedeemHandler requires a ledger that implements reservePendingCredit() (v0.3.0+)"
+      );
+    }
+    this.ledger = config.ledger;
+    this.relayService = config.relayService;
+    this.pointTokenAddress = (0, import_viem9.getAddress)(config.pointTokenAddress);
+    this.batchExecutorAddress = (0, import_viem9.getAddress)(config.batchExecutorAddress);
+    this.chainId = config.chainId;
+    this.domain = config.domain;
+    this.redeemLockDurationMs = config.redeemLockDurationMs ?? DEFAULT_REDEEM_LOCK_MS;
+    this.now = config.now ?? (() => Date.now());
+  }
+  async handle(request) {
+    if (request.amount <= 0n) {
+      throw new PTRedeemError("INVALID_CONSENT", "redeem amount must be positive");
+    }
+    if (request.consent.amount !== request.amount) {
+      throw new PTRedeemError(
+        "AMOUNT_MISMATCH",
+        `consent.amount (${request.consent.amount}) must match request.amount (${request.amount})`
+      );
+    }
+    const nowSeconds = BigInt(Math.floor(this.now() / 1e3));
+    if (request.consent.deadline <= nowSeconds) {
+      throw new PTRedeemError(
+        "EXPIRED_CONSENT",
+        `consent deadline (${request.consent.deadline}) already passed`
+      );
+    }
+    const verification = await (0, import_core6.verifyBurnConsent)(
+      {
+        name: this.domain.name,
+        chainId: this.chainId,
+        verifyingContract: this.domain.verifyingContract ?? this.pointTokenAddress
+      },
+      request.consent,
+      request.consentSignature,
+      request.userAddress
+    );
+    if (!verification.isValid) {
+      throw new PTRedeemError(
+        "SIGNATURE_MISMATCH",
+        `signer mismatch \u2014 expected ${request.userAddress}, got ${verification.recoveredAddress}`
+      );
+    }
+    const lockId = await this.ledger.reservePendingCredit(
+      request.userAddress,
+      request.amount,
+      this.redeemLockDurationMs,
+      this.pointTokenAddress
+    );
+    const userOp = this.relayService.prepareBurn({
+      mode: "burnWithSig",
+      userAddress: request.userAddress,
+      aaNonce: request.aaNonce,
+      pointTokenAddress: this.pointTokenAddress,
+      batchExecutorAddress: this.batchExecutorAddress,
+      burnConsent: request.consent,
+      consentSignature: parseSigStruct(request.consentSignature)
+    });
+    return {
+      lockId,
+      userOp,
+      expiresInSeconds: Math.floor(this.redeemLockDurationMs / 1e3)
+    };
+  }
+};
+function parseSigStruct(serialized) {
+  const raw = serialized.slice(2);
+  if (raw.length !== 130) {
+    throw new PTRedeemError(
+      "INVALID_CONSENT",
+      `signature must be 65 bytes, got ${raw.length / 2}`
+    );
+  }
+  const r = `0x${raw.slice(0, 64)}`;
+  const s = `0x${raw.slice(64, 128)}`;
+  const v = parseInt(raw.slice(128, 130), 16);
+  return { v, r, s };
+}
+
+// src/api/handlers/topUpRedemptionHandler.ts
+var import_viem10 = require("viem");
+var import_core7 = require("@pafi-dev/core");
+var TopUpRedemptionError = class extends Error {
+  constructor(code, message) {
+    super(message);
+    this.code = code;
+    this.name = "TopUpRedemptionError";
+  }
+  code;
+};
+var TopUpRedemptionHandler = class {
+  ledger;
+  ptRedeemHandler;
+  provider;
+  pointTokenAddress;
+  constructor(config) {
+    this.ledger = config.ledger;
+    this.ptRedeemHandler = config.ptRedeemHandler;
+    this.provider = config.provider;
+    this.pointTokenAddress = (0, import_viem10.getAddress)(config.pointTokenAddress);
+  }
+  async handle(request) {
+    const offChainBalance = await this.ledger.getBalance(
+      request.userAddress,
+      this.pointTokenAddress
+    );
+    if (offChainBalance >= request.requiredAmount) {
+      return { action: "NO_TOP_UP_NEEDED", offChainBalance };
+    }
+    const shortfall = request.requiredAmount - offChainBalance;
+    const onChainBalance = await (0, import_core7.getPointTokenBalance)(
+      this.provider,
+      this.pointTokenAddress,
+      request.userAddress
+    );
+    if (onChainBalance < shortfall) {
+      return {
+        action: "INSUFFICIENT_ONCHAIN",
+        offChainBalance,
+        onChainBalance,
+        shortfall
+      };
+    }
+    if (request.redeemRequest.consent.amount < shortfall) {
+      throw new TopUpRedemptionError(
+        "CONSENT_AMOUNT_TOO_LOW",
+        `consent.amount (${request.redeemRequest.consent.amount}) must cover shortfall (${shortfall})`
+      );
+    }
+    if (request.redeemRequest.consent.amount !== shortfall) {
+      throw new TopUpRedemptionError(
+        "CONSENT_AMOUNT_TOO_LOW",
+        `consent.amount (${request.redeemRequest.consent.amount}) must equal shortfall (${shortfall}) exactly \u2014 re-sign with correct amount`
+      );
+    }
+    const redeem = await this.ptRedeemHandler.handle({
+      userAddress: request.userAddress,
+      amount: shortfall,
+      consent: request.redeemRequest.consent,
+      consentSignature: request.redeemRequest.consentSignature,
+      aaNonce: request.redeemRequest.aaNonce
+    });
+    return {
+      action: "TOP_UP_STARTED",
+      shortfall,
+      redeem
+    };
+  }
+};
+
 // src/pools/subgraphPoolsProvider.ts
 var DEFAULT_CACHE_TTL_MS = 3e4;
 var POOL_QUERY = `
@@ -1665,8 +2177,274 @@ function toUsdtPerNative(priceFloat, usdtDecimals) {
   return BigInt(whole + padded);
 }
 
+// src/balance/balanceAggregator.ts
+var import_core8 = require("@pafi-dev/core");
+var BalanceAggregator = class {
+  provider;
+  ledger;
+  constructor(config) {
+    if (!config.provider) {
+      throw new Error("BalanceAggregator: provider is required");
+    }
+    if (!config.ledger) {
+      throw new Error("BalanceAggregator: ledger is required");
+    }
+    this.provider = config.provider;
+    this.ledger = config.ledger;
+  }
+  /**
+   * Combined balance for a single (user, token) pair. Fetches off-chain
+   * + on-chain in parallel.
+   */
+  async getCombinedBalance(user, pointToken) {
+    const [offChain, onChain] = await Promise.all([
+      this.ledger.getBalance(user, pointToken),
+      (0, import_core8.getPointTokenBalance)(this.provider, pointToken, user)
+    ]);
+    return {
+      offChain,
+      onChain,
+      total: offChain + onChain
+    };
+  }
+  /**
+   * Combined balance for multiple tokens owned by the same user. Runs
+   * all lookups in parallel. Returns a Map keyed by the token address
+   * (same casing as supplied — caller should normalize if needed).
+   */
+  async getCombinedBalanceMulti(user, pointTokens) {
+    const entries = await Promise.all(
+      pointTokens.map(async (token) => {
+        const balance = await this.getCombinedBalance(user, token);
+        return [token, balance];
+      })
+    );
+    return new Map(entries);
+  }
+};
+
+// src/pafi-backend/types.ts
+var PafiBackendError = class extends Error {
+  constructor(code, message, httpStatus, details, opts) {
+    super(message);
+    this.code = code;
+    this.httpStatus = httpStatus;
+    this.details = details;
+    this.name = "PafiBackendError";
+    if (opts?.retryAfter !== void 0) this.retryAfter = opts.retryAfter;
+    if (opts?.safeToRetry !== void 0) this.serverSafeToRetry = opts.safeToRetry;
+  }
+  code;
+  httpStatus;
+  details;
+  /**
+   * Seconds to wait before retry. Populated from the server body
+   * (e.g. rate limit returns the number of seconds until UTC midnight).
+   */
+  retryAfter;
+  /**
+   * `safeToRetry` as reported by the server body. Prefer this over the
+   * code-based heuristic when available — the server knows more about
+   * whether the same request will succeed on retry.
+   */
+  serverSafeToRetry;
+  /**
+   * Whether the caller can safely retry the same request.
+   *
+   * If the server provided `safeToRetry` in the body, trust that.
+   * Otherwise fall back to a code-based heuristic.
+   */
+  get safeToRetry() {
+    if (this.serverSafeToRetry !== void 0) return this.serverSafeToRetry;
+    switch (this.code) {
+      case "PAYMASTER_UNAVAILABLE":
+      case "PAYMASTER_TIMEOUT":
+      case "RATE_LIMITER_UNAVAILABLE":
+      case "INTERNAL_ERROR":
+      case "TIMEOUT":
+      case "NETWORK_ERROR":
+        return true;
+      case "RATE_LIMIT_EXCEEDED":
+      case "RATE_LIMIT_EXCEEDED_DAILY":
+      case "RATE_LIMIT_EXCEEDED_PER_USER":
+        return true;
+      // after retryAfter
+      default:
+        return false;
+    }
+  }
+};
+
+// src/pafi-backend/pafiBackendClient.ts
+var DEFAULT_TIMEOUT_MS = 1e4;
+var RETRY_DEFAULTS = {
+  maxAttempts: 1,
+  initialDelayMs: 500,
+  maxDelayMs: 1e4,
+  maxRetryAfterMs: 3e4
+};
+var PafiBackendClient = class {
+  url;
+  issuerId;
+  apiKey;
+  fetchImpl;
+  timeoutMs;
+  retry;
+  constructor(config) {
+    if (!config.url) {
+      throw new Error("PafiBackendClient: url is required");
+    }
+    if (!config.issuerId) {
+      throw new Error("PafiBackendClient: issuerId is required");
+    }
+    if (!config.apiKey) {
+      throw new Error("PafiBackendClient: apiKey is required");
+    }
+    this.url = config.url.replace(/\/+$/, "");
+    this.issuerId = config.issuerId;
+    this.apiKey = config.apiKey;
+    this.fetchImpl = config.fetchImpl ?? globalThis.fetch;
+    this.timeoutMs = config.timeoutMs ?? DEFAULT_TIMEOUT_MS;
+    this.retry = { ...RETRY_DEFAULTS, ...config.retry ?? {} };
+    if (!this.fetchImpl) {
+      throw new Error(
+        "PafiBackendClient: no fetch implementation available \u2014 pass `fetchImpl` or run on Node 18+"
+      );
+    }
+    if (this.retry.maxAttempts < 1) {
+      throw new Error("PafiBackendClient: retry.maxAttempts must be >= 1");
+    }
+  }
+  /**
+   * Request paymaster sponsorship for a pre-built UserOperation.
+   * See [SPONSORED_PATH_FLOW.md §4.1] for the API contract.
+   *
+   * Retries automatically on transient failures (5xx, timeouts, network
+   * errors, and errors the server flags with `safeToRetry: true`) up to
+   * `retry.maxAttempts`. 4xx errors that are not `safeToRetry` fail fast.
+   *
+   * @throws PafiBackendError on final failure after exhausting retries
+   */
+  async requestSponsorship(req) {
+    return this.postWithRetry(
+      "/paymaster/sponsor",
+      req
+    );
+  }
+  // -------------------------------------------------------------------------
+  // Internals
+  // -------------------------------------------------------------------------
+  async postWithRetry(path, body) {
+    let lastError;
+    for (let attempt = 1; attempt <= this.retry.maxAttempts; attempt++) {
+      try {
+        return await this.post(path, body);
+      } catch (err) {
+        if (!(err instanceof PafiBackendError)) throw err;
+        lastError = err;
+        const isLastAttempt = attempt >= this.retry.maxAttempts;
+        if (isLastAttempt || !err.safeToRetry) throw err;
+        const delay = this.computeBackoff(attempt, err.retryAfter);
+        if (delay === null) throw err;
+        await this.sleep(delay);
+      }
+    }
+    throw lastError;
+  }
+  /**
+   * Pick the delay before the next retry.
+   * - If the server sent `retryAfter` (seconds), honor it (capped by
+   *   `maxRetryAfterMs`) — returns null if the server wait exceeds the
+   *   cap, signalling the caller should give up.
+   * - Otherwise: exponential backoff with ±20% jitter, capped at
+   *   `maxDelayMs`.
+   */
+  computeBackoff(attempt, retryAfter) {
+    if (retryAfter !== void 0) {
+      const serverMs = retryAfter * 1e3;
+      if (serverMs > this.retry.maxRetryAfterMs) return null;
+      return serverMs;
+    }
+    const exp = this.retry.initialDelayMs * 2 ** (attempt - 1);
+    const capped = Math.min(exp, this.retry.maxDelayMs);
+    const jitter = capped * (0.8 + Math.random() * 0.4);
+    return Math.round(jitter);
+  }
+  sleep(ms) {
+    return new Promise((resolve) => setTimeout(resolve, ms));
+  }
+  async post(path, body) {
+    const controller = new AbortController();
+    const timeoutId = setTimeout(() => controller.abort(), this.timeoutMs);
+    let response;
+    try {
+      response = await this.fetchImpl(`${this.url}${path}`, {
+        method: "POST",
+        headers: {
+          "Content-Type": "application/json",
+          "Authorization": `Bearer ${this.apiKey}`,
+          "X-Issuer-Id": this.issuerId
+        },
+        body: JSON.stringify(body, this.bigintReplacer),
+        signal: controller.signal
+      });
+    } catch (err) {
+      if (err.name === "AbortError") {
+        throw new PafiBackendError(
+          "TIMEOUT",
+          `PAFI Backend request timed out after ${this.timeoutMs}ms`,
+          0
+        );
+      }
+      throw new PafiBackendError(
+        "NETWORK_ERROR",
+        `PAFI Backend unreachable: ${err.message}`,
+        0
+      );
+    } finally {
+      clearTimeout(timeoutId);
+    }
+    const text = await response.text();
+    if (!response.ok) {
+      let code = "INTERNAL_ERROR";
+      let message = text || response.statusText;
+      let details;
+      let retryAfter;
+      let serverSafeToRetry;
+      try {
+        const parsed = JSON.parse(text);
+        code = parsed.code ?? code;
+        message = parsed.message ?? message;
+        details = parsed.details;
+        if (typeof parsed.retryAfter === "number") retryAfter = parsed.retryAfter;
+        if (typeof parsed.safeToRetry === "boolean") serverSafeToRetry = parsed.safeToRetry;
+      } catch {
+      }
+      throw new PafiBackendError(code, message, response.status, details, {
+        ...retryAfter !== void 0 ? { retryAfter } : {},
+        ...serverSafeToRetry !== void 0 ? { safeToRetry: serverSafeToRetry } : {}
+      });
+    }
+    return JSON.parse(text, this.bigintReviver);
+  }
+  /** JSON replacer that stringifies bigints. Paired with bigintReviver. */
+  bigintReplacer = (_key, value) => {
+    return typeof value === "bigint" ? value.toString() : value;
+  };
+  /**
+   * JSON reviver that coerces specific numeric-string fields back to
+   * bigint. The server must send these fields as decimal strings.
+   */
+  bigintReviver = (key, value) => {
+    if (typeof value === "string" && (key.endsWith("GasLimit") || key === "nonce" || key === "callGasLimit" || key === "verificationGasLimit" || key === "preVerificationGas" || key === "maxFeePerGas" || key === "maxPriorityFeePerGas" || key === "paymasterVerificationGasLimit" || key === "paymasterPostOpGasLimit") && /^\d+$/.test(value)) {
+      return BigInt(value);
+    }
+    return value;
+  };
+};
+
 // src/config.ts
-var import_viem7 = require("viem");
+var import_viem11 = require("viem");
 function createIssuerService(config) {
   if (!config.provider) {
     throw new Error("createIssuerService: provider is required");
@@ -1692,7 +2470,7 @@ function createIssuerService(config) {
       "createIssuerService: at least one of pointTokenAddress / pointTokenAddresses is required"
     );
   }
-  const tokenAddresses = rawAddresses.map((a) => (0, import_viem7.getAddress)(a));
+  const tokenAddresses = rawAddresses.map((a) => (0, import_viem11.getAddress)(a));
   const ledger = config.ledger ?? new MemoryPointLedger();
   const sessionStore = config.sessionStore ?? new MemorySessionStore();
   const policy = config.policy ?? new DefaultPolicyEngine({ ledger });
@@ -1722,8 +2500,7 @@ function createIssuerService(config) {
   if (config.fee) {
     feeManager = new FeeManager({
       ...config.fee,
-      provider: config.provider,
-      operatorWallet: config.operatorWallet
+      provider: config.provider
     });
   }
   const gatewayConfig = {
@@ -1799,6 +2576,8 @@ var PAFI_ISSUER_SDK_VERSION = "0.1.0";
 0 && (module.exports = {
   AuthError,
   AuthService,
+  BalanceAggregator,
+  BurnIndexer,
   DefaultPolicyEngine,
   FeeManager,
   InMemoryCursorStore,
@@ -1809,10 +2588,16 @@ var PAFI_ISSUER_SDK_VERSION = "0.1.0";
   MintingGatewayError,
   NonceManager,
   PAFI_ISSUER_SDK_VERSION,
+  PTRedeemError,
+  PTRedeemHandler,
+  PafiBackendClient,
+  PafiBackendError,
   PointIndexer,
   PrivateKeySigner,
   RelayError,
   RelayService,
+  TopUpRedemptionError,
+  TopUpRedemptionHandler,
   authenticateRequest,
   createIssuerService,
   createSubgraphNativeUsdtQuoter,