@pafi-dev/issuer 0.2.0 → 0.3.0-beta.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, MintRequestV2, SignatureStruct, PartialUserOperation, BurnConsent, ReceiverConsent, PathKey, PoolKey, SponsorshipScenario } from '@pafi-dev/core';
 export { encodeExtData } from '@pafi-dev/core';
 
 /**
@@ -78,6 +78,24 @@ interface IPointLedger {
      * 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>;
 }
 
 /**
@@ -109,6 +127,10 @@ declare class MemoryPointLedger implements IPointLedger {
     releaseLock(lockId: string): 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.
@@ -536,93 +558,145 @@ 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>;
+    /**
+     * 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: PrepareMintParams): PartialUserOperation;
+    /**
+     * 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: PrepareBurnParams): PartialUserOperation;
+}
+interface PrepareMintParams {
+    /** User EOA that will send the UserOp (via EIP-7702 delegation). */
+    userAddress: Address;
+    /** ERC-4337 account nonce (not the MintRequest nonce — different namespace). */
+    aaNonce: bigint;
+    /** Deployed Relayer v2 contract address (chain-specific). */
+    relayerAddress: Address;
+    /** BatchExecutor delegation target (chain-specific). */
+    batchExecutorAddress: Address;
+    /** PointToken being minted — used for optional fee transfer call. */
+    pointTokenAddress: Address;
+    /** EIP-712-signed MintRequest fields. */
+    mintRequest: MintRequestV2;
+    /** User's EIP-712 signature over `mintRequest`. */
+    userSignature: SignatureStruct;
+    /** Issuer's EIP-712 signature over `mintRequest`. */
+    issuerSignature: SignatureStruct;
+    /** Gas limits — defaults are conservative; caller can tighten. */
+    callGasLimit?: bigint;
+    verificationGasLimit?: bigint;
+    preVerificationGas?: bigint;
+}
+type PrepareBurnParams = PrepareBurnDirectParams | PrepareBurnWithSigParams;
+interface PrepareBurnCommonParams {
+    userAddress: Address;
+    aaNonce: bigint;
+    pointTokenAddress: Address;
+    batchExecutorAddress: Address;
+    callGasLimit?: bigint;
+    verificationGasLimit?: bigint;
+    preVerificationGas?: bigint;
+}
+interface PrepareBurnDirectParams extends PrepareBurnCommonParams {
+    mode: "burn";
+    amount: bigint;
+}
+interface PrepareBurnWithSigParams extends PrepareBurnCommonParams {
+    mode: "burnWithSig";
+    burnConsent: BurnConsent;
+    consentSignature: SignatureStruct;
 }
 
 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>;
 }
 
 /**
@@ -751,6 +825,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;
     /**
@@ -782,6 +862,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 /
@@ -901,10 +991,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;
@@ -912,6 +1094,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;
@@ -967,6 +1160,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;
@@ -985,6 +1179,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;
@@ -1032,6 +1227,12 @@ interface IssuerApiHandlersConfig {
     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. */
@@ -1065,6 +1266,7 @@ declare class IssuerApiHandlers {
     private readonly defaultToken;
     private readonly chainId;
     private readonly contracts;
+    private readonly pafiWebUrl?;
     private readonly feeManager?;
     private readonly poolsProvider?;
     constructor(config: IssuerApiHandlersConfig);
@@ -1115,12 +1317,155 @@ 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>;
 }
 
+/**
+ * v1.4 reverse flow — **Variant A**: user-initiated PT redeem.
+ *
+ * User has on-chain PT, wants to convert back to off-chain points. They
+ * sign a `BurnConsent`, the issuer backend verifies it, reserves an
+ * off-chain credit, and returns an unsigned UserOp that the frontend
+ * submits via the Bundler. When the burn lands, the `BurnIndexer`
+ * (elsewhere) resolves the credit.
+ *
+ * **Mocked SC contracts** — this handler compiles + wires end-to-end
+ * against `@pafi-dev/core/contracts` mock ABIs. When SC ships real
+ * ABIs, no changes here — only `contracts/index.ts` re-export flips.
+ */
+interface PTRedeemHandlerConfig {
+    ledger: IPointLedger;
+    relayService: RelayService;
+    provider: PublicClient;
+    /** PointToken contract address (chain-specific). */
+    pointTokenAddress: Address;
+    /** BatchExecutor delegation target (chain-specific). */
+    batchExecutorAddress: Address;
+    /** Chain id — used for domain separator when verifying BurnConsent. */
+    chainId: number;
+    /**
+     * EIP-712 domain fields. Must match the on-chain PointToken's domain
+     * separator exactly, or signature verification fails. `name` is
+     * typically the PointToken's ERC-20 name (e.g. "PAFI Starbucks
+     * Points"). `verifyingContract` defaults to `pointTokenAddress`.
+     */
+    domain: {
+        name: string;
+        verifyingContract?: Address;
+    };
+    /**
+     * How long the pending credit stays reserved if the burn never lands.
+     * Default: 15 min — long enough for a bundler submission + confirmation.
+     */
+    redeemLockDurationMs?: number;
+    /** Clock injection for tests; defaults to `Date.now`. */
+    now?: () => number;
+}
+interface PTRedeemRequest {
+    userAddress: Address;
+    amount: bigint;
+    /** Serialized EIP-712 signature over the BurnConsent. */
+    consentSignature: Hex;
+    consent: BurnConsent;
+    /** ERC-4337 account nonce for the user's EOA. */
+    aaNonce: bigint;
+}
+interface PTRedeemResponse {
+    /** Lock id from the ledger — client polls status with this. */
+    lockId: string;
+    /** Unsigned UserOp — FE attaches paymaster + user signature + submits. */
+    userOp: PartialUserOperation;
+    /** Seconds until the lock expires if the burn doesn't land. */
+    expiresInSeconds: number;
+}
+declare class PTRedeemError extends Error {
+    code: "INVALID_CONSENT" | "SIGNATURE_MISMATCH" | "AMOUNT_MISMATCH" | "EXPIRED_CONSENT" | "LEDGER_NOT_SUPPORTED";
+    constructor(code: "INVALID_CONSENT" | "SIGNATURE_MISMATCH" | "AMOUNT_MISMATCH" | "EXPIRED_CONSENT" | "LEDGER_NOT_SUPPORTED", message: string);
+}
+declare class PTRedeemHandler {
+    private readonly ledger;
+    private readonly relayService;
+    private readonly pointTokenAddress;
+    private readonly batchExecutorAddress;
+    private readonly chainId;
+    private readonly domain;
+    private readonly redeemLockDurationMs;
+    private readonly now;
+    constructor(config: PTRedeemHandlerConfig);
+    handle(request: PTRedeemRequest): Promise<PTRedeemResponse>;
+}
+
+/**
+ * v1.4 reverse flow — **Variant B**: auto top-up on voucher redemption.
+ *
+ * User tries to redeem a voucher for `requiredAmount` off-chain points
+ * but their off-chain balance is short. If their on-chain PT balance is
+ * enough to cover the shortfall, this handler auto-triggers a burn for
+ * exactly the shortfall amount so the voucher can proceed.
+ *
+ *   Required off-chain:   500
+ *   Available off-chain:  300
+ *   Shortfall:            200
+ *   On-chain PT:          250    ← enough, top-up fires
+ *   → burn 200 PT, credit 200 off-chain, voucher proceeds with 500
+ *
+ * Delegates the actual burn construction to {@link PTRedeemHandler}
+ * — this handler is pure business logic (calculating shortfall +
+ * checking on-chain balance) on top.
+ */
+interface TopUpRedemptionHandlerConfig {
+    ledger: IPointLedger;
+    ptRedeemHandler: PTRedeemHandler;
+    provider: PublicClient;
+    /** PointToken contract address (chain-specific). */
+    pointTokenAddress: Address;
+}
+interface TopUpRedemptionRequest {
+    userAddress: Address;
+    /** Total points the voucher redemption requires off-chain. */
+    requiredAmount: bigint;
+    /**
+     * The user's pre-signed `BurnConsent` + signature, prepared by the FE
+     * with amount set to a worst-case upper bound. Handler inspects the
+     * shortfall and uses the consent if the shortfall ≤ consent.amount.
+     */
+    redeemRequest: Pick<PTRedeemRequest, "consent" | "consentSignature" | "aaNonce">;
+}
+type TopUpRedemptionResponse = {
+    action: "NO_TOP_UP_NEEDED";
+    offChainBalance: bigint;
+} | {
+    action: "INSUFFICIENT_ONCHAIN";
+    offChainBalance: bigint;
+    onChainBalance: bigint;
+    shortfall: bigint;
+} | {
+    action: "TOP_UP_STARTED";
+    shortfall: bigint;
+    redeem: PTRedeemResponse;
+};
+declare class TopUpRedemptionError extends Error {
+    code: "INSUFFICIENT_ONCHAIN_BALANCE" | "CONSENT_AMOUNT_TOO_LOW" | "LEDGER_NOT_SUPPORTED";
+    constructor(code: "INSUFFICIENT_ONCHAIN_BALANCE" | "CONSENT_AMOUNT_TOO_LOW" | "LEDGER_NOT_SUPPORTED", message: string);
+}
+declare class TopUpRedemptionHandler {
+    private readonly ledger;
+    private readonly ptRedeemHandler;
+    private readonly provider;
+    private readonly pointTokenAddress;
+    constructor(config: TopUpRedemptionHandlerConfig);
+    handle(request: TopUpRedemptionRequest): Promise<TopUpRedemptionResponse>;
+}
+
 /**
  * Config for `createSubgraphPoolsProvider`.
  */
@@ -1219,26 +1564,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",
  *     }),
  *   },
@@ -1247,6 +1595,204 @@ 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
@@ -1304,10 +1850,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.
@@ -1377,4 +1922,4 @@ 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, PTRedeemError, PTRedeemHandler, type PTRedeemHandlerConfig, type PTRedeemRequest, type PTRedeemResponse, 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, TopUpRedemptionError, TopUpRedemptionHandler, type TopUpRedemptionHandlerConfig, type TopUpRedemptionRequest, type TopUpRedemptionResponse, authenticateRequest, createIssuerService, createSubgraphNativeUsdtQuoter, createSubgraphPoolsProvider };