@pafi-dev/issuer 0.1.2 → 0.3.0-alpha.0

package/dist/index.d.ts

@@ -1,5 +1,5 @@
 import { Address, Hex, PublicClient, Chain } from 'viem';
-import { PointTokenDomainConfig, MintRequest, EIP712Signature, MintParams, SwapParams, ReceiverConsent, PathKey, PoolKey } from '@pafi-dev/core';
+import { PointTokenDomainConfig, MintRequest, EIP712Signature, MintParams, SwapParams, ReceiverConsent, PathKey, PoolKey, SponsorshipScenario, PartialUserOperation } from '@pafi-dev/core';
 export { encodeExtData } from '@pafi-dev/core';
 
 /**
@@ -18,6 +18,12 @@ interface LockedMintRequest {
     lockId: string;
     userAddress: Address;
     amount: bigint;
+    /**
+     * Which PointToken this lock belongs to. Added in 0.2.0 for multi-token
+     * issuer support. Optional for backward compat with 0.1.x ledgers —
+     * single-token consumers can ignore it.
+     */
+    tokenAddress?: Address;
     /** Lifecycle status */
     status: MintingStatus;
     /** When the lock was created (epoch ms) */
@@ -33,20 +39,28 @@ interface LockedMintRequest {
  *
  * Issuers replace the in-memory default with their own database-backed
  * implementation (Postgres, Redis, etc.).
+ *
+ * **Multi-token support (0.2.0):**
+ * Every mutating method accepts an optional `tokenAddress` parameter so
+ * balances can be scoped per `(user, token)`. Single-token issuers can
+ * ignore the parameter entirely — legacy 0.1.x implementations remain
+ * compatible. Multi-token issuers must persist + query balances keyed by
+ * `(userAddress, tokenAddress)`.
  */
 interface IPointLedger {
     /** Get a user's available off-chain point balance (excluding locked). */
-    getBalance(userAddress: Address): Promise<bigint>;
+    getBalance(userAddress: Address, tokenAddress?: Address): Promise<bigint>;
     /**
      * Lock an amount for a pending mint request. Locked amounts are reserved
      * but not yet deducted; they protect against double-spend during the
      * EIP-712 validity window.
      *
      * @param lockDurationMs how long the lock should be held before auto-expiry
+     * @param tokenAddress which PointToken this lock is for (0.2.0+)
      * @returns lockId — opaque handle used by `releaseLock` / `updateMintStatus`
      * @throws if the user's available balance is below `amount`
      */
-    lockForMinting(userAddress: Address, amount: bigint, lockDurationMs: number): Promise<string>;
+    lockForMinting(userAddress: Address, amount: bigint, lockDurationMs: number, tokenAddress?: Address): Promise<string>;
     /** Release a previously created lock (e.g. on tx failure / cancel). */
     releaseLock(lockId: string): Promise<void>;
     /**
@@ -54,16 +68,34 @@ interface IPointLedger {
      * mint has been observed by the indexer. Should also resolve any matching
      * lock so the funds aren't double-counted.
      */
-    deductBalance(userAddress: Address, amount: bigint, txHash: Hex): Promise<void>;
+    deductBalance(userAddress: Address, amount: bigint, txHash: Hex, tokenAddress?: Address): Promise<void>;
     /** Credit points to a user's balance (e.g. from merchant activity). */
-    creditBalance(userAddress: Address, amount: bigint, reason: string): Promise<void>;
+    creditBalance(userAddress: Address, amount: bigint, reason: string, tokenAddress?: Address): Promise<void>;
     /** List currently-pending locked mint requests for a user. */
-    getLockedRequests(userAddress: Address): Promise<LockedMintRequest[]>;
+    getLockedRequests(userAddress: Address, tokenAddress?: Address): Promise<LockedMintRequest[]>;
     /**
      * Transition a lock to a new lifecycle status. The on-chain tx hash is
      * supplied when the status is `MINTED`.
      */
     updateMintStatus(lockId: string, status: MintingStatus, txHash?: Hex): Promise<void>;
+    /**
+     * Reserve a pending off-chain credit before the burn tx is submitted.
+     *
+     * Returns a lockId that the burn indexer uses to correlate the
+     * on-chain burn event back to this credit request.
+     *
+     * Throws if the ledger doesn't support the reverse flow (legacy
+     * implementations) — callers should catch and fall back.
+     */
+    reservePendingCredit?(userAddress: Address, amount: bigint, durationMs: number, tokenAddress?: Address): Promise<string>;
+    /**
+     * Finalize a reserved credit when the on-chain Burn event is seen by
+     * the BurnIndexer. Idempotent — safe to call multiple times with the
+     * same txHash (no double-credit).
+     *
+     * Throws if the lockId is unknown or already resolved.
+     */
+    resolveCreditByBurnTx?(lockId: string, txHash: Hex): Promise<void>;
 }
 
 /**
@@ -75,6 +107,10 @@ interface IPointLedger {
  * Concurrency model: single-process, single-threaded (Node.js event loop).
  * The lock check + insert is atomic within a tick because no awaits sit
  * between balance read and lock write.
+ *
+ * **Multi-token (0.2.0):** Balances are keyed by `(user, token)`. If callers
+ * omit `tokenAddress`, the literal string "default" is used — that keeps
+ * single-token usage working exactly like 0.1.x.
  */
 declare class MemoryPointLedger implements IPointLedger {
     private balances;
@@ -84,13 +120,17 @@ declare class MemoryPointLedger implements IPointLedger {
     constructor(opts?: {
         now?: () => number;
     });
-    getBalance(userAddress: Address): Promise<bigint>;
-    getLockedRequests(userAddress: Address): Promise<LockedMintRequest[]>;
-    creditBalance(userAddress: Address, amount: bigint, _reason: string): Promise<void>;
-    lockForMinting(userAddress: Address, amount: bigint, lockDurationMs: number): Promise<string>;
+    getBalance(userAddress: Address, tokenAddress?: Address): Promise<bigint>;
+    getLockedRequests(userAddress: Address, tokenAddress?: Address): Promise<LockedMintRequest[]>;
+    creditBalance(userAddress: Address, amount: bigint, _reason: string, tokenAddress?: Address): Promise<void>;
+    lockForMinting(userAddress: Address, amount: bigint, lockDurationMs: number, tokenAddress?: Address): Promise<string>;
     releaseLock(lockId: string): Promise<void>;
-    deductBalance(userAddress: Address, amount: bigint, txHash: Hex): Promise<void>;
+    deductBalance(userAddress: Address, amount: bigint, txHash: Hex, tokenAddress?: Address): Promise<void>;
     updateMintStatus(lockId: string, status: MintingStatus, txHash?: Hex): Promise<void>;
+    private pendingCredits;
+    private nextCreditId;
+    reservePendingCredit(userAddress: Address, amount: bigint, durationMs: number, tokenAddress?: Address): Promise<string>;
+    resolveCreditByBurnTx(lockId: string, txHash: Hex): Promise<void>;
     /**
      * Auto-expire any PENDING lock past its expiry. Called lazily on every
      * read/write so the in-memory state stays self-cleaning without a timer.
@@ -518,93 +558,76 @@ declare class RelayService {
      * 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.
      */
     submitMintAndSwap(params: SubmitMintAndSwapParams): Promise<RelayResult>;
 }
 
 interface FeeManagerConfig {
-    /** Provider used for gas price + balance reads. */
+    /** Provider used for gas price reads. */
     provider: PublicClient;
-    /** Operator wallet whose native balance the manager monitors. */
-    operatorWallet: OperatorWalletLike;
-    /** USDT token address on the target chain (used for rebalance swaps). */
-    usdtAddress: Address;
-    /** Wrapped-native token address (WETH on Base/Ethereum, WMATIC, etc). */
-    nativeWrappedAddress: Address;
     /**
-     * Typical gas used by a `mintAndSwap` transaction. Default: 500_000. The
-     * manager multiplies this by current gas price to get the native cost,
-     * then converts to USDT via the injected `quoteNativeToUsdt`.
+     * Typical gas used by a single sponsored UserOp. Default: 500_000.
+     * The manager multiplies this by current gas price to get native
+     * cost, then converts via the injected `quoteNativeToFee`.
      */
-    mintAndSwapGasUnits?: bigint;
+    gasUnits?: bigint;
     /**
-     * Safety margin applied to the gas estimate before charging the user.
-     * Expressed as a basis-point multiplier, e.g. 12_000 = 120%. Default 12_000.
+     * Safety margin applied before charging the user, as basis points.
+     * 12_000 = 120%. Default: 12_000.
      */
     gasPremiumBps?: number;
     /**
-     * Price conversion: given an amount of native token (wei), return the
-     * equivalent amount of USDT. Injected so the manager is chain-agnostic —
-     * production wires this to `@pafi/core` V4 quoting or an oracle feed.
-     */
-    quoteNativeToUsdt: (amountNative: bigint) => Promise<bigint>;
-    /**
-     * Rebalance trigger: when the operator's native balance falls below
-     * `rebalanceThresholdWei`, `rebalanceIfNeeded()` swaps `rebalanceUsdtAmount`
-     * worth of USDT into native. Both optional — omit to disable rebalancing.
-     */
-    rebalanceThresholdWei?: bigint;
-    rebalanceUsdtAmount?: bigint;
-    /**
-     * Actual swap executor — the manager calls this when a rebalance is
-     * triggered. Injected so the SDK does not hard-code a DEX choice; the
-     * issuer wires it to the UniversalRouter (via `@pafi/core swap/`) or
-     * whatever liquidity venue they trust. Required iff the rebalance
-     * fields above are set.
+     * Quote function — given an amount of native wei, return the
+     * equivalent amount in the fee currency (PT raw units in v1.4,
+     * USDT 6-decimal in legacy v1.2 flows).
+     *
+     * Injected so the manager stays chain- and token-agnostic. Issuers
+     * wire it to `@pafi-dev/core` V4 quoting, a subgraph query, or an
+     * oracle feed.
      */
-    swapUsdtToNative?: (amountUsdt: bigint) => Promise<void>;
+    quoteNativeToFee: (amountNative: bigint) => Promise<bigint>;
 }
 /**
- * Manages the operator wallet's economics:
+ * Computes how much fee to collect from the user to cover the gas cost
+ * of a sponsored UserOp.
+ *
+ * ## v1.4 scope change
  *
- *   1. `estimateGasFee()` — how many USDT to deduct from the swap proceeds
- *      to cover the operator's gas cost for the upcoming `mintAndSwap`.
- *   2. `rebalanceIfNeeded()` — when the operator's native balance gets
- *      low, swap some of the accumulated USDT fee back into native gas
- *      token so the operator never runs dry.
+ * The fee is now expressed in the **fee currency** chosen by the caller
+ * (PT for mint/burn, USDT for swap/perp_deposit) — not hardcoded to USDT.
  *
- * Both calculations are intentionally injection-based: gas estimation and
- * USDT→native swapping both depend on DEX state, which the SDK deliberately
- * does not own. Issuers supply the conversion + swap functions.
+ * **Operator rebalancing is gone.** In v1.4 the operator no longer holds
+ * ETH directly — gas is paid by Coinbase Paymaster via the paymaster-proxy
+ * (see [SPONSORED_PATH_FLOW.md]). The fee collected here is an
+ * application-level ERC-20 transfer inside the same UserOp batch, not a
+ * reimbursement to a wallet that needs topping up.
+ *
+ * `rebalanceIfNeeded()` and `swapUsdtToNative` were removed in 0.3.0.
  */
 declare class FeeManager {
     private readonly provider;
-    private readonly operatorWallet;
-    private readonly mintAndSwapGasUnits;
+    private readonly gasUnits;
     private readonly gasPremiumBps;
-    private readonly quoteNativeToUsdt;
-    private readonly rebalanceThresholdWei?;
-    private readonly rebalanceUsdtAmount?;
-    private readonly swapUsdtToNative?;
+    private readonly quoteNativeToFee;
     constructor(config: FeeManagerConfig);
     /**
-     * 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
-     *   premiumNativeCost = nativeCost × premiumBps / 10_000
-     *   usdtFee = quoteNativeToUsdt(premiumNativeCost)
-     */
-    estimateGasFee(): Promise<bigint>;
-    /**
-     * 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.
+     *   nativeCost    = gasUnits × gasPrice
+     *   withPremium   = nativeCost × premiumBps / 10_000
+     *   fee           = quoteNativeToFee(withPremium)
      *
-     * Returns `true` if a rebalance was performed, `false` otherwise.
-     * Silently no-ops when rebalance is not configured.
+     * 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`.
      */
-    rebalanceIfNeeded(): Promise<boolean>;
+    estimateGasFee(): Promise<bigint>;
 }
 
 /**
@@ -733,6 +756,12 @@ declare class MintingGateway {
     private readonly now;
     private readonly defaultLockBufferMs;
     constructor(config: MintingGatewayConfig);
+    /**
+     * @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.
+     */
     processMintAndCashOut(request: MintAndCashOutRequest): Promise<MintAndCashOutResponse>;
     private computeLockDurationMs;
     /**
@@ -764,6 +793,16 @@ interface MintEvent {
     /** Log index within the tx, for deterministic ordering */
     logIndex: number;
 }
+/** Decoded Transfer(from=user → 0x0) event used to finalize a burn-for-credit. */
+interface BurnEvent {
+    /** The burner — user whose PT was burned. */
+    from: Address;
+    /** Amount burned. */
+    amount: bigint;
+    blockNumber: bigint;
+    txHash: Hex;
+    logIndex: number;
+}
 /**
  * Cursor persistence interface — the indexer reports the next block
  * number it is about to process so the caller can write it to Redis /
@@ -883,10 +922,102 @@ declare class PointIndexer {
     private finalize;
 }
 
+interface BurnIndexerConfig {
+    provider: PublicClient;
+    pointTokenAddress: Address;
+    ledger: IPointLedger;
+    /** Block to start from on first run. Ignored if cursor store has value. */
+    fromBlock?: bigint;
+    cursorStore?: IIndexerCursorStore;
+    /**
+     * Reorg safety — only treat events as final after this many
+     * confirmations. Default: 3.
+     */
+    confirmations?: number;
+    /** Blocks per getLogs call. Default: 2000. */
+    batchSize?: number;
+    /** Polling interval (ms). Default: 5000. */
+    pollIntervalMs?: number;
+    now?: () => number;
+}
+/**
+ * Mirror of `PointIndexer` for the reverse direction — watches
+ * `Transfer(user → 0x0)` events (ERC-20 burns) on the PointToken
+ * contract and finalizes pending off-chain credits.
+ *
+ * Finalization flow:
+ *   1. For each Burn event at `{from, amount, txHash}`:
+ *   2. Call `ledger.resolveCreditByBurnTx(lockId, txHash)` where `lockId`
+ *      is resolved by the caller's `onMatchCredit` hook or a
+ *      ledger-specific lookup. The SDK does not prescribe the matching
+ *      strategy — issuers with a Postgres ledger can JOIN by
+ *      `(from, amount, status=PENDING)`; the in-memory ledger matches
+ *      by `lockId` supplied out-of-band.
+ *
+ * When no pending credit matches an observed Burn event, the indexer
+ * logs + skips — **it never credits off-chain** from a Burn that was
+ * not first reserved via `reservePendingCredit()`. This prevents
+ * spurious credits from one-off admin burns or direct burn calls
+ * outside the issuer SDK.
+ */
+declare class BurnIndexer {
+    private readonly provider;
+    private readonly pointTokenAddress;
+    private readonly ledger;
+    private readonly cursorStore;
+    private readonly startBlock;
+    private readonly confirmations;
+    private readonly batchSize;
+    private readonly 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: (event: BurnEvent) => Promise<string | undefined>;
+    private running;
+    private timer;
+    constructor(config: BurnIndexerConfig);
+    start(): void;
+    stop(): void;
+    tick(): Promise<void>;
+    private scheduleNext;
+    /**
+     * 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.
+     */
+    processBlockRange(from: bigint, to: bigint): Promise<void>;
+    private decodeBurnEvents;
+    /**
+     * Resolve a matching pending credit for this burn event and call
+     * `ledger.resolveCreditByBurnTx(lockId, txHash)`. If no match found,
+     * log + skip.
+     */
+    private finalize;
+}
+
 interface ApiConfigResponse {
     chainId: number;
     contracts: {
+        /**
+         * Legacy single-token field — kept for backward compat with v0.1.x
+         * frontends. Prefer `pointTokens` for multi-token issuers.
+         */
         pointToken?: Address;
+        /**
+         * All supported PointToken addresses (v0.2.0+). Single-token issuers
+         * will have one entry that matches `pointToken`. Multi-token
+         * issuers expose the full list here so the frontend can render a
+         * token picker.
+         */
+        pointTokens?: Address[];
         relay?: Address;
         issuerRegistry?: Address;
         pointTokenFactory?: Address;
@@ -894,6 +1025,17 @@ interface ApiConfigResponse {
         poolManager?: Address;
         usdt?: Address;
     };
+    /**
+     * Absolute URL that the Issuer App opens after a successful claim to
+     * let the user swap PT → USDT or deposit into the perp DEX on PAFI
+     * Web. Mobile opens this in an in-app browser
+     * (SFSafariViewController / Chrome Custom Tabs). Desktop opens in a
+     * popup. See [MOBILE_SDK_INTEGRATION.md] "PAFI Web Handoff" section.
+     *
+     * Optional — if omitted, the Issuer App should hide the "Open PAFI"
+     * button.
+     */
+    pafiWebUrl?: string;
 }
 interface ApiNonceResponse {
     nonce: string;
@@ -949,6 +1091,7 @@ interface ApiUserResponse {
     balance: bigint;
     isMinter: boolean;
 }
+/** @deprecated Since 0.3.0 — use `ApiClaimRequest` (mint-only) instead. Removed in 2.0. */
 interface ApiClaimAndSwapRequest {
     chainId: number;
     pointTokenAddress: Address;
@@ -967,6 +1110,7 @@ interface ApiClaimAndSwapRequest {
     /** Unix seconds. */
     swapDeadline: bigint;
 }
+/** @deprecated Since 0.3.0 — use `ApiClaimResponse` instead. Removed in 2.0. */
 interface ApiClaimAndSwapResponse {
     txHash: Hex;
     lockId: string;
@@ -1002,9 +1146,24 @@ interface IssuerApiHandlersConfig {
     ledger: IPointLedger;
     /** Used by `handleUser` to read on-chain nonces and minter status. */
     provider: PublicClient;
-    pointTokenAddress: Address;
+    /**
+     * Legacy single-token config. Prefer `pointTokenAddresses` for multi-token
+     * issuers (0.2.0+).
+     */
+    pointTokenAddress?: Address;
+    /**
+     * All supported PointToken addresses. Handlers accept any address in this
+     * list; others are rejected with "unsupported pointToken".
+     */
+    pointTokenAddresses?: Address[];
     chainId: number;
     contracts: ApiConfigResponse["contracts"];
+    /**
+     * Optional — URL that the Issuer App opens for PT→USDT swap or perp
+     * deposit after a successful claim. Surfaced in `/config` response.
+     * See [MOBILE_SDK_INTEGRATION.md] "PAFI Web Handoff".
+     */
+    pafiWebUrl?: string;
     /** Required by `handleGasFee`; omit to disable the endpoint. */
     feeManager?: FeeManager;
     /** Required by `handlePools`; omit to disable the endpoint. */
@@ -1027,9 +1186,18 @@ declare class IssuerApiHandlers {
     private readonly gateway;
     private readonly ledger;
     private readonly provider;
-    private readonly pointTokenAddress;
+    /**
+     * Set of supported PointToken addresses (checksum-normalized). Handlers
+     * validate the request's `pointTokenAddress` against this set.
+     */
+    private readonly 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). */
+    private readonly defaultToken;
     private readonly chainId;
     private readonly contracts;
+    private readonly pafiWebUrl?;
     private readonly feeManager?;
     private readonly poolsProvider?;
     constructor(config: IssuerApiHandlersConfig);
@@ -1080,8 +1248,14 @@ declare class IssuerApiHandlers {
     /**
      * `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.
      */
     handleClaimAndSwap(userAddress: Address, request: ApiClaimAndSwapRequest): Promise<ApiClaimAndSwapResponse>;
 }
@@ -1184,26 +1358,29 @@ interface SubgraphNativeUsdtQuoterConfig {
     now?: () => number;
 }
 /**
- * Create a `quoteNativeToUsdt` function backed by the PAFI subgraph's
- * `Bundle.ethPriceUSD`.
+ * Create a native→USDT quoter backed by the PAFI subgraph's
+ * `Bundle.ethPriceUSD`. The returned function has the shape
+ * `(amountNative: bigint) => Promise<bigint>` and can be passed as
+ * `quoteNativeToFee` to `FeeManager` — in v1.4 the fee currency
+ * is configured at the integration layer, not hardcoded here.
  *
- * Used by `FeeManager.estimateGasFee()` to convert the operator's native
- * gas cost into the USDT amount deducted from the user's cashout. Price
- * precision is not critical here — a 1-2% drift is acceptable since
- * the operator already takes a `gasPremiumBps` buffer.
+ * Used by `FeeManager.estimateGasFee()` to convert the gas cost into
+ * an ERC-20 amount charged as part of the sponsored UserOp batch.
+ * Price precision is not critical — a 1-2% drift is acceptable since
+ * the fee manager applies a `gasPremiumBps` buffer.
  *
- * The result is cached in-process with a short TTL (default 30s). If the
- * subgraph is unreachable, falls back to `fallbackEthPriceUsd` so gas
- * estimation doesn't block cashouts during a subgraph outage.
+ * The result is cached in-process with a short TTL (default 30s). If
+ * the subgraph is unreachable, falls back to `fallbackEthPriceUsd` so
+ * gas estimation doesn't block user flow during a subgraph outage.
  *
  * @example
  * ```ts
- * import { createSubgraphNativeUsdtQuoter, createIssuerService } from "@pafi/issuer";
+ * import { createSubgraphNativeUsdtQuoter, createIssuerService } from "@pafi-dev/issuer";
  *
  * const service = createIssuerService({
  *   // ...other config
  *   fee: {
- *     quoteNativeToUsdt: createSubgraphNativeUsdtQuoter({
+ *     quoteNativeToFee: createSubgraphNativeUsdtQuoter({
  *       subgraphUrl: "https://graph.pacificfinance.org/subgraphs/name/pafi",
  *     }),
  *   },
@@ -1212,17 +1389,228 @@ interface SubgraphNativeUsdtQuoterConfig {
  */
 declare function createSubgraphNativeUsdtQuoter(config: SubgraphNativeUsdtQuoterConfig): (amountNative: bigint) => Promise<bigint>;
 
+/**
+ * Combined off-chain + on-chain balance for a single user / token pair.
+ *
+ * - `offChain` — the issuer's ledger balance (available, excluding locks)
+ * - `onChain`  — the user's ERC-20 balance from `PointToken.balanceOf`
+ * - `total`    — `offChain + onChain` (what the Issuer App displays)
+ */
+interface CombinedBalance {
+    offChain: bigint;
+    onChain: bigint;
+    total: bigint;
+}
+interface BalanceAggregatorConfig {
+    provider: PublicClient;
+    ledger: IPointLedger;
+}
+/**
+ * v1.4 utility — aggregates off-chain + on-chain point balances into a
+ * single view for the "combined balance" UI in the Issuer App.
+ *
+ * The `/user` API handler uses this internally; the helper is exposed
+ * publicly so Issuer Apps can call it directly without going through
+ * the HTTP layer (e.g., for server-rendered pages or admin dashboards).
+ *
+ * See [REQUIREMENTS_V2.md] §1 — "The Issuer App displays a combined
+ * balance (off-chain points + on-chain PT) and does not surface USDT."
+ */
+declare class BalanceAggregator {
+    private readonly provider;
+    private readonly ledger;
+    constructor(config: BalanceAggregatorConfig);
+    /**
+     * Combined balance for a single (user, token) pair. Fetches off-chain
+     * + on-chain in parallel.
+     */
+    getCombinedBalance(user: Address, pointToken: Address): Promise<CombinedBalance>;
+    /**
+     * 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).
+     */
+    getCombinedBalanceMulti(user: Address, pointTokens: Address[]): Promise<Map<Address, CombinedBalance>>;
+}
+
+interface RetryConfig {
+    /**
+     * Max total attempts including the first try. Default: 1 (no retry).
+     * Set to 3 to get 2 retries after the initial call.
+     *
+     * Only applies when the server error body carries `safeToRetry: true`
+     * or the failure is a transient network/timeout error.
+     */
+    maxAttempts?: number;
+    /**
+     * Initial backoff delay in ms. Default: 500. Each subsequent retry
+     * doubles this (exponential backoff) and adds ±20% jitter.
+     */
+    initialDelayMs?: number;
+    /**
+     * Hard ceiling for a single backoff (ms). Default: 10_000.
+     */
+    maxDelayMs?: number;
+    /**
+     * Upper bound on `retryAfter` from the server. If the server asks us
+     * to wait longer than this (e.g. rate limit until UTC midnight), the
+     * client gives up rather than blocking. Default: 30_000.
+     */
+    maxRetryAfterMs?: number;
+}
+interface PafiBackendConfig {
+    /**
+     * PAFI Backend API base URL. Example:
+     *   https://api.pacificfinance.org
+     *   https://staging-api.pacificfinance.org
+     */
+    url: string;
+    /** PAFI-assigned issuer ID (e.g., "gg56"). Sent in X-Issuer-Id header. */
+    issuerId: string;
+    /** Per-issuer API key (or JWT) for the Authorization header. */
+    apiKey: string;
+    /** Optional fetch override for tests. */
+    fetchImpl?: typeof fetch;
+    /**
+     * Timeout (ms) for each request. Default: 10_000. PAFI Backend should
+     * respond in <1s for the happy path; this is just the sanity bound.
+     */
+    timeoutMs?: number;
+    /**
+     * Retry policy for transient failures (5xx, 429, timeouts, network).
+     * Omit or pass `{ maxAttempts: 1 }` to disable retry entirely.
+     */
+    retry?: RetryConfig;
+}
+/** Paired with `POST /paymaster/sponsor`. See SPONSORED_PATH_FLOW.md §4.1 */
+interface SponsorshipRequest {
+    chainId: number;
+    scenario: SponsorshipScenario;
+    userOp: PartialUserOperation;
+    target: {
+        /** The allowlisted contract this batch call targets. */
+        contract: Address;
+        /** Function selector / name — validated against allowlist. */
+        function: string;
+        /** The PointToken involved (for scenario context). */
+        pointToken?: Address;
+    };
+}
+interface SponsorshipResponse {
+    paymaster: Address;
+    paymasterData: Hex;
+    paymasterVerificationGasLimit: bigint;
+    paymasterPostOpGasLimit: bigint;
+    /** Unix seconds when this sponsorship expires. Re-request after. */
+    expiresAt: number;
+}
+/**
+ * Machine-readable error codes returned by PAFI Backend.
+ *
+ * Source of truth: `apps/paymaster-proxy` `CalldataValidationError`,
+ * `RateLimitError`, `CoinbaseClientError`. Keep in sync.
+ */
+type PafiBackendErrorCode = "MISSING_ISSUER_ID" | "MISSING_API_KEY" | "ISSUER_UNAUTHORIZED" | "CALLDATA_INVALID" | "CALLDATA_EMPTY_BATCH" | "TARGET_NOT_ALLOWLISTED" | "FUNCTION_NOT_ALLOWED" | "SCENARIO_MISMATCH" | "SCENARIO_DISABLED" | "RATE_LIMIT_EXCEEDED" | "RATE_LIMIT_EXCEEDED_DAILY" | "RATE_LIMIT_EXCEEDED_PER_USER" | "RATE_LIMITER_UNAVAILABLE" | "PAYMASTER_REJECTED" | "PAYMASTER_UNAVAILABLE" | "PAYMASTER_TIMEOUT" | "BAD_REQUEST" | "INTERNAL_ERROR" | "TIMEOUT" | "NETWORK_ERROR";
+declare class PafiBackendError extends Error {
+    code: PafiBackendErrorCode;
+    httpStatus: number;
+    details?: unknown | undefined;
+    /**
+     * Seconds to wait before retry. Populated from the server body
+     * (e.g. rate limit returns the number of seconds until UTC midnight).
+     */
+    readonly retryAfter?: number;
+    /**
+     * `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.
+     */
+    private readonly serverSafeToRetry?;
+    constructor(code: PafiBackendErrorCode, message: string, httpStatus: number, details?: unknown | undefined, opts?: {
+        retryAfter?: number;
+        safeToRetry?: boolean;
+    });
+    /**
+     * 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(): boolean;
+}
+
+/**
+ * HTTP client for the PAFI Backend paymaster proxy service. See
+ * [SPONSORED_PATH_FLOW.md] for the full flow + API contract.
+ *
+ * This client sits between `@pafi/issuer`'s RelayService and the
+ * PAFI Backend. It does NOT talk to Coinbase Paymaster directly —
+ * PAFI Backend holds that integration.
+ */
+declare class PafiBackendClient {
+    private readonly url;
+    private readonly issuerId;
+    private readonly apiKey;
+    private readonly fetchImpl;
+    private readonly timeoutMs;
+    private readonly retry;
+    constructor(config: PafiBackendConfig);
+    /**
+     * 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
+     */
+    requestSponsorship(req: SponsorshipRequest): Promise<SponsorshipResponse>;
+    private postWithRetry;
+    /**
+     * 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`.
+     */
+    private computeBackoff;
+    private sleep;
+    private post;
+    /** JSON replacer that stringifies bigints. Paired with bigintReviver. */
+    private bigintReplacer;
+    /**
+     * JSON reviver that coerces specific numeric-string fields back to
+     * bigint. The server must send these fields as decimal strings.
+     */
+    private bigintReviver;
+}
+
 /**
  * Top-level configuration for `createIssuerService`. Everything except
  * the chain metadata, wallets, auth secret, and `signer` is optional and
  * falls back to the in-memory dev defaults — that makes the happy path
  * a single-call wire-up while still letting production issuers plug in
  * their own ledger, session store, policy engine, and KMS signer.
+ *
+ * **Multi-token (0.2.0):** Pass `pointTokenAddresses: Address[]` to
+ * support multiple PointTokens under a single issuer backend. Legacy
+ * `pointTokenAddress: Address` still works for single-token deployments.
+ * When both are provided, `pointTokenAddresses` takes precedence.
  */
 interface IssuerServiceConfig {
     chainId: number;
-    /** Address of the deployed PointToken (one per issuer instance). */
-    pointTokenAddress: Address;
+    /**
+     * Address of the deployed PointToken. Legacy single-token shortcut;
+     * prefer `pointTokenAddresses` for multi-token issuers.
+     */
+    pointTokenAddress?: Address;
+    /**
+     * All PointToken addresses this issuer supports. Takes precedence over
+     * `pointTokenAddress`. Factory creates one `PointIndexer` per address.
+     */
+    pointTokenAddresses?: Address[];
     /** Address of the deployed Relay contract. */
     relayAddress: Address;
     /**
@@ -1256,10 +1644,9 @@ interface IssuerServiceConfig {
     /**
      * Fee management config. If omitted the `handleGasFee` endpoint will
      * throw "not configured" at request time. Pass any subset of fields
-     * to opt in — provider + operatorWallet are inherited from the outer
-     * config automatically.
+     * to opt in — `provider` is inherited from the outer config.
      */
-    fee?: Omit<FeeManagerConfig, "provider" | "operatorWallet">;
+    fee?: Omit<FeeManagerConfig, "provider">;
     /**
      * Pool discovery function for `handlePools`. If omitted the endpoint
      * throws "not configured" at request time.
@@ -1295,6 +1682,16 @@ interface IssuerService {
     relayService: RelayService;
     feeManager: FeeManager | undefined;
     gateway: MintingGateway;
+    /**
+     * All indexers keyed by PointToken address. For multi-token issuers there
+     * is one per configured token. Single-token issuers will find one entry.
+     */
+    indexers: Map<Address, PointIndexer>;
+    /**
+     * First indexer. Kept for backward compat with 0.1.x callers that
+     * expected `service.indexer` to be a single instance.
+     * @deprecated use `indexers.get(tokenAddress)` for multi-token.
+     */
     indexer: PointIndexer;
     handlers: IssuerApiHandlers;
 }
@@ -1312,11 +1709,11 @@ interface IssuerService {
  *  - `indexer.autoStart` → false
  *
  * Throws synchronously if any required field (`signer`, `provider`,
- * `operatorWallet`, `auth.jwtSecret`, `pointTokenAddress`, …) is missing.
+ * `operatorWallet`, `auth.jwtSecret`, at least one point token) is missing.
  */
 declare function createIssuerService(config: IssuerServiceConfig): IssuerService;
 
 /** SDK package version — bumped on every release */
 declare const PAFI_ISSUER_SDK_VERSION = "0.1.0";
 
-export { type ApiBuildConsentTypedDataRequest, type ApiBuildConsentTypedDataResponse, type ApiClaimAndSwapRequest, type ApiClaimAndSwapResponse, type ApiConfigResponse, type ApiGasFeeResponse, type ApiLoginRequest, type ApiLoginResponse, type ApiNonceResponse, type ApiPoolsRequest, type ApiPoolsResponse, type ApiUserRequest, type ApiUserResponse, type AuthContext, AuthError, type AuthErrorCode, AuthService, type AuthServiceConfig, DefaultPolicyEngine, type DefaultPolicyEngineOptions, FeeManager, type FeeManagerConfig, type IIndexerCursorStore, type IIssuerSigner, type IPointLedger, type IPolicyEngine, type ISessionStore, InMemoryCursorStore, IssuerApiHandlers, type IssuerApiHandlersConfig, type IssuerService, type IssuerServiceConfig, type LockedMintRequest, type LoginResult, MemoryPointLedger, MemorySessionStore, type MemorySessionStoreOptions, type MintAndCashOutRequest, type MintAndCashOutResponse, type MintEvent, MintingGateway, type MintingGatewayConfig, MintingGatewayError, type MintingGatewayErrorCode, type MintingStatus, NonceManager, type OperatorWalletLike, PAFI_ISSUER_SDK_VERSION, PointIndexer, type PointIndexerConfig, type PolicyDecision, type PolicyEvalRequest, type PoolsProvider, PrivateKeySigner, type PrivateKeySignerOptions, RelayError, type RelayErrorCode, type RelayResult, RelayService, type RelayServiceConfig, type Session, type SubgraphNativeUsdtQuoterConfig, type SubgraphPoolsProviderConfig, type SubmitMintAndSwapParams, authenticateRequest, createIssuerService, createSubgraphNativeUsdtQuoter, createSubgraphPoolsProvider };
+export { type ApiBuildConsentTypedDataRequest, type ApiBuildConsentTypedDataResponse, type ApiClaimAndSwapRequest, type ApiClaimAndSwapResponse, type ApiConfigResponse, type ApiGasFeeResponse, type ApiLoginRequest, type ApiLoginResponse, type ApiNonceResponse, type ApiPoolsRequest, type ApiPoolsResponse, type ApiUserRequest, type ApiUserResponse, type AuthContext, AuthError, type AuthErrorCode, AuthService, type AuthServiceConfig, BalanceAggregator, type BalanceAggregatorConfig, type BurnEvent, BurnIndexer, type BurnIndexerConfig, type CombinedBalance, DefaultPolicyEngine, type DefaultPolicyEngineOptions, FeeManager, type FeeManagerConfig, type IIndexerCursorStore, type IIssuerSigner, type IPointLedger, type IPolicyEngine, type ISessionStore, InMemoryCursorStore, IssuerApiHandlers, type IssuerApiHandlersConfig, type IssuerService, type IssuerServiceConfig, type LockedMintRequest, type LoginResult, MemoryPointLedger, MemorySessionStore, type MemorySessionStoreOptions, type MintAndCashOutRequest, type MintAndCashOutResponse, type MintEvent, MintingGateway, type MintingGatewayConfig, MintingGatewayError, type MintingGatewayErrorCode, type MintingStatus, NonceManager, type OperatorWalletLike, PAFI_ISSUER_SDK_VERSION, PafiBackendClient, type PafiBackendConfig, PafiBackendError, type PafiBackendErrorCode, PointIndexer, type PointIndexerConfig, type PolicyDecision, type PolicyEvalRequest, type PoolsProvider, PrivateKeySigner, type PrivateKeySignerOptions, RelayError, type RelayErrorCode, type RelayResult, RelayService, type RelayServiceConfig, type Session, type SponsorshipRequest, type SponsorshipResponse, type SubgraphNativeUsdtQuoterConfig, type SubgraphPoolsProviderConfig, type SubmitMintAndSwapParams, authenticateRequest, createIssuerService, createSubgraphNativeUsdtQuoter, createSubgraphPoolsProvider };