@pafi-dev/issuer 0.13.0 → 0.15.0

package/dist/index.d.cts

@@ -115,8 +115,18 @@ interface IPointLedger {
     /** List currently-pending locked mint requests for a user. */
     getLockedRequests(userAddress: Address, tokenAddress?: Address): Promise<LockedMintRequest[]>;
     /**
-     * Transition a lock to a new lifecycle status. The on-chain tx hash is
+     * Transition a lock from `PENDING` to a terminal status
+     * (`MINTED` | `EXPIRED` | `FAILED`). The on-chain tx hash is
      * supplied when the status is `MINTED`.
+     *
+     * Terminal states are immutable: once a lock leaves `PENDING` the
+     * status is fixed. Calling `updateMintStatus` on a non-PENDING lock
+     * is a silent no-op. This protects against late-arriving writes from
+     * different code paths (e.g. PointIndexer.finalize and the bundler-
+     * receipt fallback in statusHandlers) racing to overwrite each
+     * other — particularly the case where a stale `EXPIRED`/`FAILED`
+     * write would corrupt a `MINTED` lock whose balance has already
+     * been deducted.
      */
     updateMintStatus(lockId: string, status: MintingStatus, txHash?: Hex): Promise<void>;
     /**
@@ -204,7 +214,7 @@ interface DefaultPolicyEngineOptions {
     provider?: PublicClient;
     mintingOracleAddress?: Address;
     /**
-     * Override the on-chain cap check. Defaults to `@pafi/core`'s
+     * Override the on-chain cap check. Defaults to `@pafi-dev/core`'s
      * `verifyMintCap`, which reverts if the issuer's declared supply would
      * be exceeded. A rejected check should throw; returning normally is pass.
      */
@@ -561,7 +571,7 @@ interface RelayServiceConfig {
     chainId?: number;
 }
 /**
- * Builds unsigned `PartialUserOperation` payloads for the v1.4 sponsored
+ * Builds unsigned `PartialUserOperation` payloads for the sponsored
  * flow. The service is stateless and HTTP-client-free:
  *
  *   - `prepareMint` signs a `MintRequest` EIP-712 with the caller-supplied
@@ -573,7 +583,7 @@ interface RelayServiceConfig {
  *     deadline, burnerSig)`.
  *
  * There is no broadcasting, no operator wallet, no simulation — those
- * concerns moved to the Bundler + Paymaster in v1.4.
+ * concerns live in the Bundler + Paymaster.
  */
 declare class RelayService {
     private readonly provider;
@@ -607,13 +617,13 @@ declare class RelayService {
      * provides a pre-signed `BurnRequest` + sig bytes (typically from
      * `PTRedeemHandler`).
      *
-     * Direct burn (no sig) was dropped in v1.4 — every burn now goes
-     * through the issuer-signed `BurnRequest` path.
+     * Direct burn (no sig) is not used — every burn goes through the
+     * issuer-signed `BurnRequest` path.
      */
     prepareBurn(params: PrepareBurnParams): Promise<PartialUserOperation>;
 }
 /**
- * v1.4 — sig-gated `PointToken.mint(to, amount, deadline, minterSig)`.
+ * Sig-gated `PointToken.mint(to, amount, deadline, minterSig)`.
  *
  * The issuer backend validates off-chain (balance, policy, KYC), signs
  * a `MintRequest` EIP-712 with its minter signer, and packages the
@@ -645,16 +655,16 @@ interface PrepareMintParams {
     /** Unix timestamp after which the signature expires. */
     deadline: bigint;
     /**
-     * Optional v1.6+ — when set, mint is routed through MintFeeWrapper:
+     * Optional — when set, mint is routed through MintFeeWrapper:
      *   - sig.receiver = wrapper address (vs `userAddress` for direct path)
      *   - calldata target = wrapper.mintWithFee(pointToken, user, gross, ...)
      *   - the wrapper then mints `amount` to itself, splits per recipient list,
      *     and forwards net to the user.
      *
-     * Leave undefined to keep the v1.5 direct-mint behavior (no fee skim).
-     * Wrapper must be registered on the PointToken via
-     * `IssuerRegistry.addIssuer` cascade (or owner-only `wrapper.registerToken`)
-     * before this path works on-chain.
+     * Leave undefined for direct-mint behavior (no fee skim). Wrapper
+     * must be registered on the PointToken via `IssuerRegistry.addIssuer`
+     * cascade (or owner-only `wrapper.registerToken`) before this path
+     * works on-chain.
      */
     mintFeeWrapperAddress?: Address;
     /**
@@ -669,11 +679,10 @@ interface PrepareMintParams {
     preVerificationGas?: bigint;
 }
 /**
- * v1.4 — sig-gated burn only. Direct (no-sig) burn was dropped because
- * every burn now goes through `BurnRequest` EIP-712 signed by the
- * issuer burner. The `mode: 'burnWithSig'` discriminant is preserved
- * for backwards-compat with existing callers but is no longer
- * branched on internally.
+ * Sig-gated burn only — every burn goes through `BurnRequest` EIP-712
+ * signed by the issuer burner. The `mode: 'burnWithSig'` discriminant
+ * is preserved for backwards-compat with existing callers but is no
+ * longer branched on internally.
  */
 interface PrepareBurnParams {
     userAddress: Address;
@@ -715,8 +724,8 @@ interface FeeManagerConfig {
     gasPremiumBps?: number;
     /**
      * 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).
+     * equivalent amount in the fee currency (typically PT raw units;
+     * USDT 6-decimal for swap / perp deposit flows).
      *
      * Injected so the manager stays chain- and token-agnostic. Issuers
      * wire it to `@pafi-dev/core` V4 quoting, a subgraph query, or an
@@ -728,18 +737,14 @@ interface FeeManagerConfig {
  * Computes how much fee to collect from the user to cover the gas cost
  * of a sponsored UserOp.
  *
- * ## v1.4 scope change
- *
- * 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.
+ * The fee is expressed in the **fee currency** chosen by the caller
+ * (PT for mint/burn, USDT for swap/perp_deposit) — not hardcoded.
  *
- * **Operator rebalancing is gone.** In v1.4 the operator no longer holds
- * ETH directly — gas is paid by PAFI sponsor-relayer via the paymaster-proxy
- * (see [SPONSORED_PATH_FLOW.md]). The fee collected here is an
+ * **No operator rebalancing.** The operator does not hold ETH directly;
+ * gas is paid by PAFI sponsor-relayer 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;
@@ -815,8 +820,9 @@ interface PointIndexerConfig {
     pointTokenAddress: Address;
     ledger: IPointLedger;
     /**
-     * v1.6 — when set, indexer listens to `MintFeeWrapper.MintWithFee`
-     * (filtered by this `pointToken`) instead of `PointToken.Transfer(0x0)`.
+     * When set, indexer listens to `MintFeeWrapper.MintWithFee`
+     * (filtered by this `pointToken`) instead of
+     * `PointToken.Transfer(0x0)`.
      *
      * Required for wrapper-mediated mints because the on-chain Transfer
      * destination is the wrapper itself (not the end user), so a naive
@@ -874,15 +880,15 @@ interface PointIndexerConfig {
  *
  * **Two modes** — selected at construction by `mintFeeWrapperAddress`:
  *
- * 1. **Wrapper mode (v1.6, recommended for mainnet)**
+ * 1. **Wrapper mode (recommended for mainnet)**
  *    Listens to `MintFeeWrapper.MintWithFee(indexed pointToken, indexed to,
  *    grossAmount, netAmount, feeAmount)` filtered by `pointToken`. The
  *    `to` field is the actual end-user (not the wrapper), and `grossAmount`
  *    matches the off-chain lock's amount.
  *
- * 2. **Direct mode (legacy / chains without wrapper)**
- *    Listens to `PointToken.Transfer(from=0x0 → to)` — the original v1.5
- *    behavior. Used when the wrapper address is undefined / zero / dead.
+ * 2. **Direct mode (chains without wrapper)**
+ *    Listens to `PointToken.Transfer(from=0x0 → to)`. Used when the
+ *    wrapper address is undefined / zero / dead.
  *
  * Finalization strategy (per event):
  *   1. Find a PENDING locked mint request for `to` with matching amount.
@@ -934,7 +940,7 @@ declare class PointIndexer {
      */
     processBlockRange(from: bigint, to: bigint): Promise<void>;
     /**
-     * Wrapper mode (v1.6): listen for `MintWithFee` on the wrapper,
+     * Wrapper mode: listen for `MintWithFee` on the wrapper,
      * filtered to events for THIS pointToken only. The event's `to` field
      * is the actual end user, and `grossAmount` matches the lock amount.
      */
@@ -1079,22 +1085,13 @@ interface ApiConfigResponse {
          */
         batchExecutor?: Address;
         /**
-         * @deprecated Removed in v1.6. The Uniswap V4 PAFIHook (10%
-         * PT→USDT swap fee) was deleted in the 2026-05-07 redeploy — fee
-         * logic moved to `MintFeeWrapper` on the mint path, and v1.6 pools
-         * use `hooks = address(0)`. Field retained for ABI back-compat
-         * with v1.5 callers; `getContractAddresses(chainId)` returns a
-         * dead sentinel.
-         */
-        pafiHook?: Address;
-        /**
-         * v1.6 — single global MintFeeWrapper that skims a fee on every
+         * Single global MintFeeWrapper that skims a fee on every
          * sig-gated mint and distributes across the configured recipients.
          */
         mintFeeWrapper?: Address;
     };
     /**
-     * v1.6 — per-PointToken mint fee (in basis points, 0–10000) read from
+     * Per-PointToken mint fee (in basis points, 0–10000) read from
      * `MintFeeWrapper.totalFeeBps(pointToken)`. Frontend uses this to show
      * "you'll receive X PT (Y% mint fee)" before user signs.
      *
@@ -1169,10 +1166,8 @@ interface ApiUserResponse {
      */
     totalBalance: bigint;
     /**
-     * @deprecated Use `offChainBalance` instead. Originally slated for
-     * removal in v0.2.0; we kept it past that point because public
-     * mobile clients still read it. Will be removed in the next major
-     * bump (v1.0).
+     * @deprecated Use `offChainBalance` instead. Retained as a wire-level
+     * alias for older mobile clients that still read it.
      */
     balance: bigint;
     isMinter: boolean;
@@ -1356,10 +1351,10 @@ interface IssuerApiHandlersConfig {
      */
     pafiWebUrl?: string;
     /**
-     * v1.6 — MintFeeWrapper address used to read per-PointToken fee
-     * basis points for `/config`. When omitted, the response will not
-     * include `mintFeeBpsByToken` and FE must assume zero fee. Wrapper
-     * is shared across PointTokens; per-token recipients live inside it.
+     * MintFeeWrapper address used to read per-PointToken fee basis
+     * points for `/config`. When omitted, the response will not include
+     * `mintFeeBpsByToken` and FE must assume zero fee. Wrapper is shared
+     * across PointTokens; per-token recipients live inside it.
      */
     mintFeeWrapperAddress?: Address;
     /** Required by `handleGasFee`; omit to disable the endpoint. */
@@ -1388,7 +1383,7 @@ interface IssuerApiHandlersConfig {
  *
  * Every protected handler takes a pre-verified `userAddress` as its first
  * argument. The issuer's middleware wraps `authenticateRequest()` from
- * `@pafi/issuer` to extract that address from the Bearer token before
+ * `@pafi-dev/issuer` to extract that address from the Bearer token before
  * routing.
  */
 declare class IssuerApiHandlers {
@@ -1462,9 +1457,8 @@ declare class IssuerApiHandlers {
     /**
      * `GET /user?chainId=<id>&user=<addr>&pointToken=<addr>`
      *
-     * Returns per-user state the frontend needs to build a fresh
-     * `ReceiverConsent`: on-chain nonces + minter status + off-chain
-     * balance.
+     * Returns per-user state the frontend needs to build a fresh mint:
+     * on-chain nonces + minter status + off-chain balance.
      */
     handleUser(userAddress: Address, request: ApiUserRequest): Promise<ApiUserResponse>;
     /**
@@ -1490,7 +1484,7 @@ declare class IssuerApiHandlers {
 }
 
 /**
- * v1.4 reverse flow — user-initiated PT redeem.
+ * Reverse flow — user-initiated PT redeem.
  *
  * User has on-chain PT, wants to convert back to off-chain points. The
  * issuer backend signs a `BurnRequest` with its burner signer, reserves
@@ -2045,7 +2039,13 @@ declare function serializeUserOpTypedData(td: UserOpTypedData): SerializedUserOp
  * (without re-estimated gas) don't accidentally zero out the original
  * estimates.
  */
-declare function mergePaymasterFields<T extends object>(userOp: T, paymasterFields: {
+/**
+ * Subset of `SponsorshipResponse` consumed by the merge/hash helpers.
+ * Inlined as a structural type (rather than importing
+ * `SponsorshipResponse` from `pafi-backend/client`) to keep
+ * `userop-store` independent of the HTTP-client module.
+ */
+interface PaymasterGasEstimates {
     paymaster: Address;
     paymasterData: Hex;
     paymasterVerificationGasLimit: bigint;
@@ -2055,7 +2055,8 @@ declare function mergePaymasterFields<T extends object>(userOp: T, paymasterFiel
     preVerificationGas?: bigint;
     maxFeePerGas?: bigint;
     maxPriorityFeePerGas?: bigint;
-} | undefined): T;
+}
+declare function mergePaymasterFields<T extends object>(userOp: T, paymasterFields: PaymasterGasEstimates | undefined): T;
 interface PreparedUserOp {
     /** The bundler-ready UserOp (with paymaster + Pimlico-quoted gas). */
     userOp: PartialUserOperation & {
@@ -2071,6 +2072,51 @@ interface PreparedUserOp {
     /** Typed-data payload — pass directly to `eth_signTypedData_v4`. */
     typedData: SerializedUserOpTypedData;
 }
+/**
+ * Atomic "merge paymaster fields + compute hash + build typed data" —
+ * the only place the SDK should be doing all three operations.
+ *
+ * Why bundled into one call:
+ *
+ *   Pimlico's `pm_sponsorUserOperation` re-estimates
+ *   `callGasLimit` / `verificationGasLimit` / `preVerificationGas` and
+ *   the bundler fee fields (`maxFeePerGas` / `maxPriorityFeePerGas`),
+ *   then signs `paymasterData` over the new values. The EntryPoint
+ *   hashes the actual on-chain field values during validation, so
+ *   callers MUST overwrite the matching userOp fields BEFORE
+ *   computing the userOpHash. Forgetting any field triggers AA34
+ *   (paymaster signature mismatch) and/or AA24 (sender signature
+ *   mismatch) — opaque failures that take hours to debug.
+ *
+ *   Splitting "merge" and "hash" into two free functions invited
+ *   exactly this bug — each call site reinvented the merge logic,
+ *   and one was already drifting (see audit M-02). Returning all
+ *   three pieces (`userOp`, `userOpHash`, `typedData`) from a single
+ *   call makes "hash before merge" structurally impossible: there is
+ *   no intermediate userOp to compute a stale hash over.
+ *
+ * Behaviour:
+ *   - When `paymasterFields` is undefined (paymaster declined / Path
+ *     C self-pay), the result is just the hash + typed-data of the
+ *     caller's `partialUserOp` — no fields are touched.
+ *   - When provided, only defined keys in `paymasterFields` overwrite
+ *     the matching fields. Original gas/fee estimates survive when
+ *     the paymaster did not re-estimate.
+ *
+ * Replaces:
+ *   - manual spread merges (e.g. previous `delegateHandler.ts`)
+ *   - `mergePaymasterFields` + separate `computeUserOpHash` +
+ *     `buildUserOpTypedData` triplets in any new call site.
+ *
+ * Note: the original `mergePaymasterFields` and the raw
+ * `computeUserOpHash` / `buildUserOpTypedData` exports remain
+ * available — use this helper unless you have a specific reason to
+ * stage the operations.
+ */
+declare function applyPaymasterGasEstimates(partialUserOp: PartialUserOperation & {
+    maxFeePerGas: bigint;
+    maxPriorityFeePerGas: bigint;
+}, paymasterFields: PaymasterGasEstimates | undefined, chainId: number): PreparedUserOp;
 interface PrepareMobileUserOpParams {
     /** Lock id (issuer-generated) keying both store entry + ledger row. */
     lockId: string;
@@ -2284,7 +2330,7 @@ interface IssuerStateValidatorLike {
     preValidateMint(pointToken: Address, amount: bigint): Promise<unknown>;
 }
 /**
- * v1.4 sig-gated mint handler — mirrors `PTRedeemHandler` on the mint side.
+ * Sig-gated mint handler — mirrors `PTRedeemHandler` on the mint side.
  *
  * Pre-validates against IssuerRegistry + on-chain totalSupply, locks the
  * off-chain balance, builds the sponsored UserOp (mint + PT fee
@@ -2324,7 +2370,7 @@ interface PTClaimHandlerConfig {
     signatureDeadlineSeconds?: number;
     now?: () => number;
     /**
-     * Optional override for the v1.6+ MintFeeWrapper address. By default the
+     * Optional override for the MintFeeWrapper address. By default the
      * handler auto-resolves the wrapper from the request's `chainId` via
      * `getContractAddresses(chainId).mintFeeWrapper`. Set this only when:
      *   - testing against a non-canonical wrapper deploy, or
@@ -2565,12 +2611,12 @@ declare function createSdkErrorMapper(factories: SdkErrorMapperFactories): (err:
 /**
  * Top-level configuration for `createIssuerService`.
  *
- * In v1.4 the SDK is HTTP-client-free: it signs EIP-712 messages, reads
+ * The SDK is HTTP-client-free: it signs EIP-712 messages, reads
  * on-chain state, builds unsigned UserOperations, and maintains the
  * off-chain ledger. It never broadcasts transactions — that's the
  * frontend's responsibility via Bundler + Paymaster.
  *
- * **Multi-token (0.2.0+):** Pass `pointTokenAddresses: Address[]` to
+ * **Multi-token:** 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.
@@ -2584,8 +2630,8 @@ interface IssuerServiceConfig {
     /**
      * Issuer-specific contract addresses merged into the `/config` response.
      * PAFI-owned addresses (batchExecutor, usdt, issuerRegistry, mintingOracle,
-     * pafiHook) are auto-resolved from `getContractAddresses(chainId)` and
-     * can be omitted. Only `pointToken` / `pointTokens` must be provided.
+     * mintFeeWrapper, …) are auto-resolved from `getContractAddresses(chainId)`
+     * and can be omitted. Only `pointToken` / `pointTokens` must be provided.
      */
     contracts?: Pick<ApiConfigResponse["contracts"], "pointToken" | "pointTokens" | "relay">;
     /**
@@ -2637,11 +2683,11 @@ interface IssuerServiceConfig {
          */
         autoStart?: boolean;
         /**
-         * v1.6 — override the MintFeeWrapper address used by the indexer.
-         * When omitted, the factory auto-resolves from
+         * Override the MintFeeWrapper address used by the indexer. When
+         * omitted, the factory auto-resolves from
          * `getContractAddresses(chainId).mintFeeWrapper`. Pass the
          * dead-zero address (`0x...dEaD`) to force direct-Transfer mode
-         * (legacy v1.5, useful for local fork tests).
+         * (useful for local fork tests).
          */
         mintFeeWrapperAddress?: Address;
     };
@@ -2681,11 +2727,6 @@ interface IssuerService {
     fee: FeeManager | undefined;
     /** All indexers keyed by PointToken address. */
     indexers: Map<Address, PointIndexer>;
-    /**
-     * First indexer. Kept for backward compat with 0.1.x callers.
-     * @deprecated use `indexers.get(tokenAddress)` for multi-token.
-     */
-    indexer: PointIndexer;
     /** Framework-agnostic HTTP handlers — wire into Express / Fastify / Hono. */
     api: IssuerApiHandlers;
     /**
@@ -2993,12 +3034,22 @@ interface SubgraphPoolsProviderConfig {
      * Optional clock override for tests.
      */
     now?: () => number;
+    /**
+     * Optional error callback. Invoked on every recoverable error (subgraph
+     * unreachable, non-200 response, GraphQL errors, invalid pool payload).
+     * The provider continues to return `{ pools: [] }` on error and also
+     * logs via `console.warn`/`console.error`; this hook lets host apps
+     * forward errors to their own observability stack without parsing logs.
+     * Throwing inside this callback is swallowed so the provider remains
+     * total. (Addresses CODE_REVIEW issuer MEDIUM-5.)
+     */
+    onError?: (error: Error) => void;
 }
 /**
  * Create a `PoolsProvider` backed by the PAFI subgraph.
  *
  * Queries the `pafiTokens` entity for the given `pointTokenAddress`,
- * reads its linked `Pool`, and returns a single-element `PoolKey[]`.
+ * reads its linked V3 `Pool`, and returns a single-element `PoolKey[]`.
  * Multiple pools per token would require a subgraph schema change.
  *
  * The result is cached in-process with a short TTL (default 30s). Pool
@@ -3009,19 +3060,22 @@ interface SubgraphPoolsProviderConfig {
  *  - the token is not registered on PAFI yet (no PafiToken entity)
  *  - the token is registered but its pool has not been initialised
  *  - the subgraph is unreachable or returns an error (logs to console,
- *    does not throw — callers should handle empty pool list gracefully)
+ *    invokes `onError` if provided; does not throw — callers should
+ *    handle empty pool list gracefully)
  *
- * Assumes the PAFI subgraph schema. Issuers with a custom subgraph must
+ * Assumes the PAFI subgraph schema (`pafiToken { pool { id feeTier
+ * token0 { id } token1 { id } } }`). Issuers with a custom subgraph must
  * implement `PoolsProvider` themselves instead of using this helper.
  *
  * @example
  * ```ts
- * import { createSubgraphPoolsProvider, createIssuerService } from "@pafi/issuer";
+ * import { createSubgraphPoolsProvider, createIssuerService } from "@pafi-dev/issuer";
  *
  * const service = createIssuerService({
  *   // ...other config
  *   poolsProvider: createSubgraphPoolsProvider({
  *     subgraphUrl: "https://graph.pacificfinance.org/subgraphs/name/pafi",
+ *     onError: (err) => metrics.increment("issuer.pools.error", { reason: err.message }),
  *   }),
  * });
  * ```
@@ -3072,8 +3126,8 @@ interface SubgraphNativeUsdtQuoterConfig {
  * 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.
+ * `quoteNativeToFee` to `FeeManager` — the fee currency is configured
+ * at the integration layer, not hardcoded here.
  *
  * Used by `FeeManager.estimateGasFee()` to convert the gas cost into
  * an ERC-20 amount charged as part of the sponsored UserOp batch.
@@ -3142,50 +3196,6 @@ interface NativePtQuoterConfig {
  */
 declare function createNativePtQuoter(config: NativePtQuoterConfig): (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>>;
-}
-
 /**
  * Typed errors thrown by the helpers below — issuer controllers map
  * these to the appropriate HTTP status. We don't depend on @nestjs/common
@@ -3306,9 +3316,9 @@ interface IssuerRegistryRecord {
     mintingOracle: Address;
 }
 /**
- * v1.6 — per-token cap config read from `MintingOracle.tokenCaps()`.
- * Caps moved off the issuer record so a single issuer can run many
- * PointTokens with different supply policies.
+ * Per-token cap config read from `MintingOracle.tokenCaps()`. Caps
+ * live per PointToken (not per issuer), so a single issuer can run
+ * many PointTokens with different supply policies.
  */
 interface TokenCapRecord {
     declaredTotalSupply: bigint;
@@ -3477,4 +3487,4 @@ declare class MemoryRedemptionHistoryStore implements IRedemptionHistoryStore {
 
 declare const PAFI_ISSUER_SDK_VERSION: string;
 
-export { AdapterMisconfiguredError, type ApiConfigResponse, type ApiGasFeeResponse, type ApiLoginRequest, type ApiLoginResponse, type ApiNonceResponse, type ApiPoolsRequest, type ApiPoolsResponse, type ApiRedemptionEvaluateRequest, type ApiRedemptionEvaluateResponse, type ApiRedemptionPreviewRequest, type ApiRedemptionPreviewResponse, type ApiUserRequest, type ApiUserResponse, type AuthContext, AuthError, type AuthErrorCode, AuthService, type AuthServiceConfig, BalanceAggregator, type BalanceAggregatorConfig, BundlerNotConfiguredError, BundlerRejectedError, type BurnEvent, BurnIndexer, type BurnIndexerConfig, type BurnStatusParams, type BurnStatusResponse, type ClaimDto, type CombinedBalance, type ConfigDto, ConfigurationError, DEFAULT_REDEMPTION_POLICY, type DecodedCallDto, DefaultPolicyEngine, type DefaultPolicyEngineOptions, type DelegatePrepareDto, type DelegateStatusDto, type EvaluateInput, FeeManager, type FeeManagerConfig, type FetchFailureReason, type FetchResult, type GasFeeDto, type HandleDelegateSubmitParams, type HandleDelegateSubmitResult, type HandleMobilePrepareParams, type HandleMobilePrepareResult, type HandleMobileSubmitParams, type IIndexerCursorStore, type IPendingUserOpStore, type IPointLedger, type IPolicyEngine, type IRateLimiter, type IRedemptionHistoryStore, type ISessionStore, InMemoryCursorStore, IssuerApiAdapter, type IssuerApiAdapterConfig, IssuerApiHandlers, type IssuerApiHandlersConfig, type IssuerRegistryRecord, type IssuerService, type IssuerServiceConfig, IssuerStateError, IssuerStateValidator, LockNotFoundError, type LockedMintRequest, type LoginResult, MemoryPendingUserOpStore, MemoryRateLimiter, MemoryRedemptionHistoryStore, MemorySessionStore, type MemorySessionStoreOptions, type MintEvent, type MintStatusParams, type MintStatusResponse, type MintingStatus, type MobilePrepareDto, type MobileSubmitDto, type NativePtQuoterConfig, NonceManager, NoopRateLimiter, PAFI_ISSUER_SDK_VERSION, PTClaimError, PTClaimHandler, type PTClaimHandlerConfig, type PTClaimRequest, type PTClaimResponse, PTRedeemError, PTRedeemHandler, type PTRedeemHandlerConfig, type PTRedeemRequest, type PTRedeemResponse, PafiBackendClient, type PafiBackendConfig, PafiBackendError, type PafiBackendErrorCode, type PendingCredit, type PendingUserOpEntry, PendingUserOpForbiddenError, PendingUserOpNotFoundError, type PerpDepositDto, PerpDepositError, PerpDepositHandler, type PerpDepositHandlerConfig, type PerpDepositRequest, type PerpDepositResponse, PointIndexer, type PointIndexerConfig, type PolicyDecision, type PolicyEvalRequest, PolicyProvider, type PolicyProviderConfig, type PoolsDto, type PoolsProvider, type PreValidateMintResult, type PrepareBurnParams, type PrepareMintParams, type PrepareMobileUserOpParams, type PrepareMobileUserOpResult, type PreparedUserOp, REDEMPTION_HISTORY_WINDOW_SEC, type RateLimitAction, type RateLimiterConfig, type RedeemDto, type RedeemPrepareDto, RedemptionService, type RedemptionServiceConfig, RelayError, type RelayErrorCode, RelayService, type RelayUserOpParams, type RelayUserOpRequest, type RelayUserOpResponse, type RequestPaymasterParams, type ResolvedPolicy, type RetryConfig, type SdkErrorBody, type SdkErrorMapperFactories, type SdkErrorStatus, type SerializedUserOpTypedData, type Session, SettlementClient, type SettlementClientConfig, type SponsorshipRequest, type SponsorshipResponse, type SponsorshipTarget, type SponsorshipUserOp, type SubgraphNativeUsdtQuoterConfig, type SubgraphPoolsProviderConfig, type UserDto, type UserHistory, authenticateRequest, buildSdkErrorBody, createIssuerService, createNativePtQuoter, createSdkErrorMapper, createSubgraphNativeUsdtQuoter, createSubgraphPoolsProvider, defaultPolicyFor, evaluateRedemption, handleClaimStatus, handleDelegateSubmit, handleMobilePrepare, handleMobileSubmit, handleRedeemStatus, mergePaymasterFields, prepareMobileUserOp, relayUserOp, requestPaymaster, serializeEntryToJsonRpc, serializeUserOpTypedData };
+export { AdapterMisconfiguredError, type ApiConfigResponse, type ApiGasFeeResponse, type ApiLoginRequest, type ApiLoginResponse, type ApiNonceResponse, type ApiPoolsRequest, type ApiPoolsResponse, type ApiRedemptionEvaluateRequest, type ApiRedemptionEvaluateResponse, type ApiRedemptionPreviewRequest, type ApiRedemptionPreviewResponse, type ApiUserRequest, type ApiUserResponse, type AuthContext, AuthError, type AuthErrorCode, AuthService, type AuthServiceConfig, BundlerNotConfiguredError, BundlerRejectedError, type BurnEvent, BurnIndexer, type BurnIndexerConfig, type BurnStatusParams, type BurnStatusResponse, type ClaimDto, type ConfigDto, ConfigurationError, DEFAULT_REDEMPTION_POLICY, type DecodedCallDto, DefaultPolicyEngine, type DefaultPolicyEngineOptions, type DelegatePrepareDto, type DelegateStatusDto, type EvaluateInput, FeeManager, type FeeManagerConfig, type FetchFailureReason, type FetchResult, type GasFeeDto, type HandleDelegateSubmitParams, type HandleDelegateSubmitResult, type HandleMobilePrepareParams, type HandleMobilePrepareResult, type HandleMobileSubmitParams, type IIndexerCursorStore, type IPendingUserOpStore, type IPointLedger, type IPolicyEngine, type IRateLimiter, type IRedemptionHistoryStore, type ISessionStore, InMemoryCursorStore, IssuerApiAdapter, type IssuerApiAdapterConfig, IssuerApiHandlers, type IssuerApiHandlersConfig, type IssuerRegistryRecord, type IssuerService, type IssuerServiceConfig, IssuerStateError, IssuerStateValidator, LockNotFoundError, type LockedMintRequest, type LoginResult, MemoryPendingUserOpStore, MemoryRateLimiter, MemoryRedemptionHistoryStore, MemorySessionStore, type MemorySessionStoreOptions, type MintEvent, type MintStatusParams, type MintStatusResponse, type MintingStatus, type MobilePrepareDto, type MobileSubmitDto, type NativePtQuoterConfig, NonceManager, NoopRateLimiter, PAFI_ISSUER_SDK_VERSION, PTClaimError, PTClaimHandler, type PTClaimHandlerConfig, type PTClaimRequest, type PTClaimResponse, PTRedeemError, PTRedeemHandler, type PTRedeemHandlerConfig, type PTRedeemRequest, type PTRedeemResponse, PafiBackendClient, type PafiBackendConfig, PafiBackendError, type PafiBackendErrorCode, type PaymasterGasEstimates, type PendingCredit, type PendingUserOpEntry, PendingUserOpForbiddenError, PendingUserOpNotFoundError, type PerpDepositDto, PerpDepositError, PerpDepositHandler, type PerpDepositHandlerConfig, type PerpDepositRequest, type PerpDepositResponse, PointIndexer, type PointIndexerConfig, type PolicyDecision, type PolicyEvalRequest, PolicyProvider, type PolicyProviderConfig, type PoolsDto, type PoolsProvider, type PreValidateMintResult, type PrepareBurnParams, type PrepareMintParams, type PrepareMobileUserOpParams, type PrepareMobileUserOpResult, type PreparedUserOp, REDEMPTION_HISTORY_WINDOW_SEC, type RateLimitAction, type RateLimiterConfig, type RedeemDto, type RedeemPrepareDto, RedemptionService, type RedemptionServiceConfig, RelayError, type RelayErrorCode, RelayService, type RelayUserOpParams, type RelayUserOpRequest, type RelayUserOpResponse, type RequestPaymasterParams, type ResolvedPolicy, type RetryConfig, type SdkErrorBody, type SdkErrorMapperFactories, type SdkErrorStatus, type SerializedUserOpTypedData, type Session, SettlementClient, type SettlementClientConfig, type SponsorshipRequest, type SponsorshipResponse, type SponsorshipTarget, type SponsorshipUserOp, type SubgraphNativeUsdtQuoterConfig, type SubgraphPoolsProviderConfig, type UserDto, type UserHistory, applyPaymasterGasEstimates, authenticateRequest, buildSdkErrorBody, createIssuerService, createNativePtQuoter, createSdkErrorMapper, createSubgraphNativeUsdtQuoter, createSubgraphPoolsProvider, defaultPolicyFor, evaluateRedemption, handleClaimStatus, handleDelegateSubmit, handleMobilePrepare, handleMobileSubmit, handleRedeemStatus, mergePaymasterFields, prepareMobileUserOp, relayUserOp, requestPaymaster, serializeEntryToJsonRpc, serializeUserOpTypedData };