@pafi-dev/issuer 0.1.2 → 0.3.0-alpha.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,6 +34,8 @@ __export(index_exports, {
   MintingGatewayError: () => MintingGatewayError,
   NonceManager: () => NonceManager,
   PAFI_ISSUER_SDK_VERSION: () => PAFI_ISSUER_SDK_VERSION,
+  PafiBackendClient: () => PafiBackendClient,
+  PafiBackendError: () => PafiBackendError,
   PointIndexer: () => PointIndexer,
   PrivateKeySigner: () => PrivateKeySigner,
   RelayError: () => RelayError,
@@ -57,19 +61,21 @@ var MemoryPointLedger = class {
   // -------------------------------------------------------------------------
   // Read
   // -------------------------------------------------------------------------
-  async getBalance(userAddress) {
-    const key = (0, import_viem.getAddress)(userAddress);
+  async getBalance(userAddress, tokenAddress) {
+    const user = (0, import_viem.getAddress)(userAddress);
+    const token = normalizeToken(tokenAddress);
     this.purgeExpired();
-    const total = this.balances.get(key) ?? 0n;
-    const locked = this.lockedTotalFor(key);
+    const total = this.balances.get(balanceKey(user, token)) ?? 0n;
+    const locked = this.lockedTotalFor(user, token);
     return total - locked;
   }
-  async getLockedRequests(userAddress) {
-    const key = (0, import_viem.getAddress)(userAddress);
+  async getLockedRequests(userAddress, tokenAddress) {
+    const user = (0, import_viem.getAddress)(userAddress);
+    const token = normalizeToken(tokenAddress);
     this.purgeExpired();
     const out = [];
     for (const lock of this.locks.values()) {
-      if (lock.userAddress === key && lock.status === "PENDING") {
+      if (lock.userAddress === user && lock.status === "PENDING" && (lock.tokenAddress ?? DEFAULT_TOKEN_KEY) === token) {
         out.push({ ...lock });
       }
     }
@@ -78,25 +84,28 @@ var MemoryPointLedger = class {
   // -------------------------------------------------------------------------
   // Write
   // -------------------------------------------------------------------------
-  async creditBalance(userAddress, amount, _reason) {
+  async creditBalance(userAddress, amount, _reason, tokenAddress) {
     if (amount <= 0n) {
       throw new Error("MemoryPointLedger: credit amount must be positive");
     }
-    const key = (0, import_viem.getAddress)(userAddress);
+    const user = (0, import_viem.getAddress)(userAddress);
+    const token = normalizeToken(tokenAddress);
+    const key = balanceKey(user, token);
     const current = this.balances.get(key) ?? 0n;
     this.balances.set(key, current + amount);
   }
-  async lockForMinting(userAddress, amount, lockDurationMs) {
+  async lockForMinting(userAddress, amount, lockDurationMs, tokenAddress) {
     if (amount <= 0n) {
       throw new Error("MemoryPointLedger: lock amount must be positive");
     }
     if (lockDurationMs <= 0) {
       throw new Error("MemoryPointLedger: lockDurationMs must be positive");
     }
-    const key = (0, import_viem.getAddress)(userAddress);
+    const user = (0, import_viem.getAddress)(userAddress);
+    const token = normalizeToken(tokenAddress);
     this.purgeExpired();
-    const total = this.balances.get(key) ?? 0n;
-    const alreadyLocked = this.lockedTotalFor(key);
+    const total = this.balances.get(balanceKey(user, token)) ?? 0n;
+    const alreadyLocked = this.lockedTotalFor(user, token);
     const available = total - alreadyLocked;
     if (available < amount) {
       throw new Error(
@@ -105,14 +114,18 @@ var MemoryPointLedger = class {
     }
     const lockId = `lock-${this.nextLockId++}`;
     const now = this.now();
-    this.locks.set(lockId, {
+    const lock = {
       lockId,
-      userAddress: key,
+      userAddress: user,
       amount,
       status: "PENDING",
       createdAt: now,
       expiresAt: now + lockDurationMs
-    });
+    };
+    if (tokenAddress !== void 0) {
+      lock.tokenAddress = (0, import_viem.getAddress)(tokenAddress);
+    }
+    this.locks.set(lockId, lock);
     return lockId;
   }
   async releaseLock(lockId) {
@@ -122,11 +135,13 @@ var MemoryPointLedger = class {
       this.locks.delete(lockId);
     }
   }
-  async deductBalance(userAddress, amount, txHash) {
+  async deductBalance(userAddress, amount, txHash, tokenAddress) {
     if (amount <= 0n) {
       throw new Error("MemoryPointLedger: deduct amount must be positive");
     }
-    const key = (0, import_viem.getAddress)(userAddress);
+    const user = (0, import_viem.getAddress)(userAddress);
+    const token = normalizeToken(tokenAddress);
+    const key = balanceKey(user, token);
     const current = this.balances.get(key) ?? 0n;
     if (current < amount) {
       throw new Error(
@@ -135,7 +150,7 @@ var MemoryPointLedger = class {
     }
     this.balances.set(key, current - amount);
     for (const lock of this.locks.values()) {
-      if (lock.userAddress === key && lock.status === "PENDING" && lock.amount === amount) {
+      if (lock.userAddress === user && lock.status === "PENDING" && lock.amount === amount && (lock.tokenAddress ?? DEFAULT_TOKEN_KEY) === token) {
         lock.status = "MINTED";
         lock.txHash = txHash;
         return;
@@ -151,6 +166,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
   // -------------------------------------------------------------------------
   /**
@@ -165,16 +228,23 @@ var MemoryPointLedger = class {
       }
     }
   }
-  lockedTotalFor(userAddress) {
+  lockedTotalFor(userAddress, tokenKey) {
     let total = 0n;
     for (const lock of this.locks.values()) {
-      if (lock.userAddress === userAddress && lock.status === "PENDING") {
+      if (lock.userAddress === userAddress && lock.status === "PENDING" && (lock.tokenAddress ?? DEFAULT_TOKEN_KEY) === tokenKey) {
         total += lock.amount;
       }
     }
     return total;
   }
 };
+var DEFAULT_TOKEN_KEY = "default";
+function normalizeToken(tokenAddress) {
+  return tokenAddress === void 0 ? DEFAULT_TOKEN_KEY : (0, import_viem.getAddress)(tokenAddress);
+}
+function balanceKey(user, tokenKey) {
+  return `${user}|${tokenKey}`;
+}
 
 // src/policy/defaultPolicy.ts
 var DefaultPolicyEngine = class {
@@ -196,7 +266,10 @@ var DefaultPolicyEngine = class {
     if (request.amount <= 0n) {
       return { approved: false, reason: "Amount must be positive" };
     }
-    const available = await this.ledger.getBalance(request.userAddress);
+    const available = await this.ledger.getBalance(
+      request.userAddress,
+      request.pointTokenAddress
+    );
     if (available < request.amount) {
       return {
         approved: false,
@@ -609,6 +682,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) {
@@ -687,84 +765,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);
   }
 };
 
@@ -810,6 +839,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) {
@@ -874,7 +909,8 @@ var MintingGateway = class {
       lockId = await this.ledger.lockForMinting(
         request.userAddress,
         receiverConsent.amount,
-        lockDurationMs
+        lockDurationMs,
+        request.pointTokenAddress
       );
     } catch (err) {
       throw new MintingGatewayError(
@@ -1164,11 +1200,19 @@ var PointIndexer = class {
    * issuer to mint without going through the gateway.
    */
   async finalize(evt) {
-    const locks = await this.ledger.getLockedRequests(evt.to);
+    const locks = await this.ledger.getLockedRequests(
+      evt.to,
+      this.pointTokenAddress
+    );
     const match = pickMatchingLock(locks, evt.amount);
     if (!match) return;
     try {
-      await this.ledger.deductBalance(evt.to, evt.amount, evt.txHash);
+      await this.ledger.deductBalance(
+        evt.to,
+        evt.amount,
+        evt.txHash,
+        this.pointTokenAddress
+      );
     } catch {
       return;
     }
@@ -1190,17 +1234,177 @@ function pickMatchingLock(locks, amount) {
   return best;
 }
 
-// src/api/handlers.ts
+// src/indexer/burnIndexer.ts
 var import_viem6 = require("viem");
+var TRANSFER_EVENT2 = (0, import_viem6.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_viem6.getAddress)(args.to) !== ZERO_ADDRESS2) continue;
+      if (log.blockNumber === null || log.transactionHash === null) continue;
+      out.push({
+        from: (0, import_viem6.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_viem7 = require("viem");
 var import_core5 = require("@pafi-dev/core");
 var IssuerApiHandlers = class {
   authService;
   gateway;
   ledger;
   provider;
-  pointTokenAddress;
+  /**
+   * Set of supported PointToken addresses (checksum-normalized). Handlers
+   * validate the request's `pointTokenAddress` against this set.
+   */
+  supportedTokens;
+  /** First supported token — used as default when a handler doesn't
+   * receive a `pointTokenAddress` in the request (shouldn't happen in
+   * practice, but keeps type-narrowing happy). */
+  defaultToken;
   chainId;
   contracts;
+  pafiWebUrl;
   feeManager;
   poolsProvider;
   constructor(config) {
@@ -1208,9 +1412,18 @@ var IssuerApiHandlers = class {
     this.gateway = config.gateway;
     this.ledger = config.ledger;
     this.provider = config.provider;
-    this.pointTokenAddress = config.pointTokenAddress;
+    const raw = config.pointTokenAddresses && config.pointTokenAddresses.length > 0 ? config.pointTokenAddresses : config.pointTokenAddress ? [config.pointTokenAddress] : [];
+    if (raw.length === 0) {
+      throw new Error(
+        "IssuerApiHandlers: pointTokenAddress or pointTokenAddresses required"
+      );
+    }
+    const normalized = raw.map((a) => (0, import_viem7.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;
   }
@@ -1246,7 +1459,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() {
@@ -1297,15 +1519,15 @@ 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_viem7.getAddress)(userAddress);
+    const normalizedRequest = (0, import_viem7.getAddress)(request.userAddress);
     if (normalizedAuthed !== normalizedRequest) {
       throw new Error(
         "handleUser: request userAddress must match authenticated user"
       );
     }
-    const pointToken = (0, import_viem6.getAddress)(request.pointTokenAddress);
-    if (pointToken !== this.pointTokenAddress) {
+    const pointToken = (0, import_viem7.getAddress)(request.pointTokenAddress);
+    if (!this.supportedTokens.has(pointToken)) {
       throw new Error(
         `handleUser: unsupported pointToken ${pointToken}`
       );
@@ -1313,7 +1535,7 @@ var IssuerApiHandlers = class {
     const [mintRequestNonce, receiverConsentNonce, offChainBalance, onChainBalance, minter] = await Promise.all([
       (0, import_core5.getMintRequestNonce)(this.provider, pointToken, normalizedAuthed),
       (0, import_core5.getReceiverConsentNonce)(this.provider, pointToken, normalizedAuthed),
-      this.ledger.getBalance(normalizedAuthed),
+      this.ledger.getBalance(normalizedAuthed, pointToken),
       (0, import_core5.getPointTokenBalance)(this.provider, pointToken, normalizedAuthed),
       (0, import_core5.isMinter)(this.provider, pointToken, normalizedAuthed)
     ]);
@@ -1347,8 +1569,8 @@ var IssuerApiHandlers = class {
         `handleBuildConsentTypedData: unsupported chainId ${request.chainId}`
       );
     }
-    const pointToken = (0, import_viem6.getAddress)(request.pointTokenAddress);
-    if (pointToken !== this.pointTokenAddress) {
+    const pointToken = (0, import_viem7.getAddress)(request.pointTokenAddress);
+    if (!this.supportedTokens.has(pointToken)) {
       throw new Error(
         `handleBuildConsentTypedData: unsupported pointToken ${pointToken}`
       );
@@ -1372,8 +1594,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) {
@@ -1381,14 +1609,14 @@ var IssuerApiHandlers = class {
         `handleClaimAndSwap: unsupported chainId ${request.chainId}`
       );
     }
-    const pointToken = (0, import_viem6.getAddress)(request.pointTokenAddress);
-    if (pointToken !== this.pointTokenAddress) {
+    const pointToken = (0, import_viem7.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_viem7.getAddress)(userAddress),
       pointTokenAddress: pointToken,
       chainId: request.chainId,
       domain: request.domain,
@@ -1619,7 +1847,274 @@ function toUsdtPerNative(priceFloat, usdtDecimals) {
   return BigInt(whole + padded);
 }
 
+// src/balance/balanceAggregator.ts
+var import_core6 = 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_core6.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_viem8 = require("viem");
 function createIssuerService(config) {
   if (!config.provider) {
     throw new Error("createIssuerService: provider is required");
@@ -1630,9 +2125,6 @@ function createIssuerService(config) {
   if (!config.signer) {
     throw new Error("createIssuerService: signer is required");
   }
-  if (!config.pointTokenAddress) {
-    throw new Error("createIssuerService: pointTokenAddress is required");
-  }
   if (!config.relayAddress) {
     throw new Error("createIssuerService: relayAddress is required");
   }
@@ -1642,6 +2134,13 @@ function createIssuerService(config) {
   if (!config.auth?.domain) {
     throw new Error("createIssuerService: auth.domain is required");
   }
+  const rawAddresses = config.pointTokenAddresses && config.pointTokenAddresses.length > 0 ? config.pointTokenAddresses : config.pointTokenAddress ? [config.pointTokenAddress] : [];
+  if (rawAddresses.length === 0) {
+    throw new Error(
+      "createIssuerService: at least one of pointTokenAddress / pointTokenAddresses is required"
+    );
+  }
+  const tokenAddresses = rawAddresses.map((a) => (0, import_viem8.getAddress)(a));
   const ledger = config.ledger ?? new MemoryPointLedger();
   const sessionStore = config.sessionStore ?? new MemorySessionStore();
   const policy = config.policy ?? new DefaultPolicyEngine({ ledger });
@@ -1671,8 +2170,7 @@ function createIssuerService(config) {
   if (config.fee) {
     feeManager = new FeeManager({
       ...config.fee,
-      provider: config.provider,
-      operatorWallet: config.operatorWallet
+      provider: config.provider
     });
   }
   const gatewayConfig = {
@@ -1685,33 +2183,37 @@ function createIssuerService(config) {
     gatewayConfig.defaultLockBufferMs = config.gateway.defaultLockBufferMs;
   }
   const gateway = new MintingGateway(gatewayConfig);
-  const indexerConfig = {
-    provider: config.provider,
-    pointTokenAddress: config.pointTokenAddress,
-    ledger
-  };
-  if (config.indexer?.fromBlock !== void 0) {
-    indexerConfig.fromBlock = config.indexer.fromBlock;
-  }
-  if (config.indexer?.cursorStore) {
-    indexerConfig.cursorStore = config.indexer.cursorStore;
-  }
-  if (config.indexer?.confirmations !== void 0) {
-    indexerConfig.confirmations = config.indexer.confirmations;
-  }
-  if (config.indexer?.batchSize !== void 0) {
-    indexerConfig.batchSize = config.indexer.batchSize;
-  }
-  if (config.indexer?.pollIntervalMs !== void 0) {
-    indexerConfig.pollIntervalMs = config.indexer.pollIntervalMs;
+  const indexers = /* @__PURE__ */ new Map();
+  for (const tokenAddress of tokenAddresses) {
+    const indexerConfig = {
+      provider: config.provider,
+      pointTokenAddress: tokenAddress,
+      ledger
+    };
+    if (config.indexer?.fromBlock !== void 0) {
+      indexerConfig.fromBlock = config.indexer.fromBlock;
+    }
+    if (config.indexer?.cursorStore) {
+      indexerConfig.cursorStore = config.indexer.cursorStore;
+    }
+    if (config.indexer?.confirmations !== void 0) {
+      indexerConfig.confirmations = config.indexer.confirmations;
+    }
+    if (config.indexer?.batchSize !== void 0) {
+      indexerConfig.batchSize = config.indexer.batchSize;
+    }
+    if (config.indexer?.pollIntervalMs !== void 0) {
+      indexerConfig.pollIntervalMs = config.indexer.pollIntervalMs;
+    }
+    indexers.set(tokenAddress, new PointIndexer(indexerConfig));
   }
-  const indexer = new PointIndexer(indexerConfig);
+  const firstIndexer = indexers.get(tokenAddresses[0]);
   const handlersConfig = {
     authService,
     gateway,
     ledger,
     provider: config.provider,
-    pointTokenAddress: config.pointTokenAddress,
+    pointTokenAddresses: tokenAddresses,
     chainId: config.chainId,
     contracts: config.contracts
   };
@@ -1719,7 +2221,9 @@ function createIssuerService(config) {
   if (config.poolsProvider) handlersConfig.poolsProvider = config.poolsProvider;
   const handlers = new IssuerApiHandlers(handlersConfig);
   if (config.indexer?.autoStart) {
-    indexer.start();
+    for (const idx of indexers.values()) {
+      idx.start();
+    }
   }
   return {
     authService,
@@ -1730,7 +2234,8 @@ function createIssuerService(config) {
     relayService,
     feeManager,
     gateway,
-    indexer,
+    indexers,
+    indexer: firstIndexer,
     handlers
   };
 }
@@ -1741,6 +2246,8 @@ var PAFI_ISSUER_SDK_VERSION = "0.1.0";
 0 && (module.exports = {
   AuthError,
   AuthService,
+  BalanceAggregator,
+  BurnIndexer,
   DefaultPolicyEngine,
   FeeManager,
   InMemoryCursorStore,
@@ -1751,6 +2258,8 @@ var PAFI_ISSUER_SDK_VERSION = "0.1.0";
   MintingGatewayError,
   NonceManager,
   PAFI_ISSUER_SDK_VERSION,
+  PafiBackendClient,
+  PafiBackendError,
   PointIndexer,
   PrivateKeySigner,
   RelayError,