@pafi-dev/issuer 0.5.33 → 0.5.35

package/dist/index.d.cts

@@ -1,5 +1,5 @@
 import { Address, Hex, PublicClient, WalletClient } from 'viem';
-import { PointTokenDomainConfig, PartialUserOperation, BurnRequest, PoolKey, UserOpTypedData } from '@pafi-dev/core';
+import { PointTokenDomainConfig, PartialUserOperation, BurnRequest, PoolKey, UserOpTypedData, decodeBatchExecuteCalls, BROKER_HASHES, ENTRY_POINT_V08 } from '@pafi-dev/core';
 export { PAFI_SUBGRAPH_URL } from '@pafi-dev/core';
 
 /**
@@ -1528,444 +1528,105 @@ declare function handleClaimStatus(params: MintStatusParams): Promise<MintStatus
 declare function handleRedeemStatus(params: BurnStatusParams): Promise<BurnStatusResponse>;
 
 /**
- * Config for `createSubgraphPoolsProvider`.
+ * A pending UserOp serialized for persistent storage (Redis, Postgres, memory).
+ *
+ * All bigint fields are stored as decimal strings so the entry can be
+ * JSON-serialized without precision loss. Convert back to bigint before
+ * calling `computeUserOpHash` or `serializeUserOpToJsonRpc`.
  */
-interface SubgraphPoolsProviderConfig {
-    /**
-     * Fully qualified subgraph GraphQL endpoint.
-     * Defaults to the PAFI-hosted subgraph (`PAFI_SUBGRAPH_URL`).
-     * Override only when pointing at a staging or custom deployment.
-     */
-    subgraphUrl?: string;
-    /**
-     * Cache TTL in milliseconds. Pool discovery is near-static — a 30s
-     * cache removes subgraph load without meaningfully delaying UX.
-     * Set to 0 to disable caching. Default: 30_000.
-     */
-    cacheTtlMs?: number;
-    /**
-     * Optional fetch override for test harnesses. Defaults to global `fetch`.
-     */
-    fetchImpl?: typeof fetch;
+interface PendingUserOpEntry {
+    sender: Address;
+    nonce: string;
+    callData: Hex;
+    callGasLimit: string;
+    verificationGasLimit: string;
+    preVerificationGas: string;
+    maxFeePerGas: string;
+    maxPriorityFeePerGas: string;
+    paymaster?: Address;
+    paymasterVerificationGasLimit?: string;
+    paymasterPostOpGasLimit?: string;
+    paymasterData?: Hex;
+    chainId: number;
+    /** Hex-encoded userOpHash — the value the user signed via personal_sign. */
+    userOpHash: Hex;
     /**
-     * Optional clock override for tests.
+     * Fee-stripped fallback variant. Set by `/claim/prepare` and
+     * `/redeem/prepare` when a PT operator fee is configured AND the
+     * paymaster sponsorship attached successfully — i.e. the user might
+     * still want to submit without paymaster (paying ETH gas), and in
+     * that case shouldn't be charged the PT fee. `/claim/submit` reads
+     * this branch when its request body specifies
+     * `variant: "fallback"`.
+     *
+     * Has a different `callData` (no PT.transfer prepended) and
+     * therefore a different `userOpHash`. Paymaster fields are NOT
+     * present — the fallback is by definition unsponsored.
      */
-    now?: () => number;
+    fallback?: {
+        callData: Hex;
+        callGasLimit: string;
+        verificationGasLimit: string;
+        preVerificationGas: string;
+        userOpHash: Hex;
+    };
 }
 /**
- * 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[]`.
- * Multiple pools per token would require a subgraph schema change.
- *
- * The result is cached in-process with a short TTL (default 30s). Pool
- * discovery is near-static so this avoids hammering the subgraph without
- * blocking config changes for long.
- *
- * Returns `{ pools: [] }` if:
- *  - 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)
- *
- * Assumes the PAFI subgraph schema. Issuers with a custom subgraph must
- * implement `PoolsProvider` themselves instead of using this helper.
+ * Storage backend for pending UserOps in the mobile prepare/submit pattern.
  *
- * @example
- * ```ts
- * import { createSubgraphPoolsProvider, createIssuerService } from "@pafi/issuer";
+ * Implement this interface and wire it into your issuer backend:
+ *   - `save()` — called by `POST /claim/prepare` and `POST /redeem/prepare`
+ *   - `get()`  — called by `POST /claim/submit` and `POST /redeem/submit`
+ *   - `delete()` — called after successful submit or explicit cancellation
  *
- * const service = createIssuerService({
- *   // ...other config
- *   poolsProvider: createSubgraphPoolsProvider({
- *     subgraphUrl: "https://graph.pacificfinance.org/subgraphs/name/pafi",
- *   }),
- * });
- * ```
- */
-declare function createSubgraphPoolsProvider(config?: SubgraphPoolsProviderConfig): PoolsProvider;
-
-/**
- * Config for `createSubgraphNativeUsdtQuoter`.
+ * The default implementation in the gg56 boilerplate uses Redis with
+ * a short TTL matching the MintRequest / BurnRequest deadline.
  */
-interface SubgraphNativeUsdtQuoterConfig {
-    /**
-     * Fully qualified subgraph GraphQL endpoint.
-     * Defaults to the PAFI-hosted subgraph (`PAFI_SUBGRAPH_URL`).
-     * Override only when pointing at a staging or custom deployment.
-     */
-    subgraphUrl?: string;
-    /**
-     * Decimals of the USDT token. Defaults to 6 (standard USDT/USDC on
-     * Base, Ethereum, Polygon). Override for chains where USDT uses a
-     * different decimals value.
-     */
-    usdtDecimals?: number;
-    /**
-     * Decimals of the native token (ETH on Base/mainnet/Arbitrum/Optimism,
-     * MATIC on Polygon). Default: 18.
-     */
-    nativeDecimals?: number;
-    /**
-     * Cache TTL in milliseconds. ETH price drifts slowly relative to gas
-     * estimation needs — a 30s cache keeps fees stable across bursts of
-     * requests without letting them go stale during volatile markets.
-     * Set to 0 to disable caching. Default: 30_000.
-     */
-    cacheTtlMs?: number;
-    /**
-     * Fallback price (USDT per native token, human-readable float) used
-     * when the subgraph is unreachable. This keeps the backend operational
-     * during subgraph outages rather than bricking cashouts. The fee will
-     * be slightly off but the operator still gets paid. Default: 3000.
-     */
-    fallbackEthPriceUsd?: number;
-    /** Optional fetch override for test harnesses. */
-    fetchImpl?: typeof fetch;
-    /** Optional clock override for tests. */
-    now?: () => number;
+interface IPendingUserOpStore {
+    save(lockId: string, entry: PendingUserOpEntry, ttlSeconds: number): Promise<void>;
+    get(lockId: string): Promise<PendingUserOpEntry | null>;
+    delete(lockId: string): Promise<void>;
 }
+
 /**
- * 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 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 user flow during a subgraph outage.
- *
- * @example
- * ```ts
- * import { createSubgraphNativeUsdtQuoter, createIssuerService } from "@pafi-dev/issuer";
+ * Convert a stored `PendingUserOpEntry` (decimal-string fields) plus a
+ * signature into the JSON-RPC wire format for `eth_sendUserOperation`.
  *
- * const service = createIssuerService({
- *   // ...other config
- *   fee: {
- *     quoteNativeToFee: createSubgraphNativeUsdtQuoter({
- *       subgraphUrl: "https://graph.pacificfinance.org/subgraphs/name/pafi",
- *     }),
- *   },
- * });
- * ```
+ * Bridges the gap between the serialized storage format (decimal strings,
+ * safe for JSON/Redis) and `serializeUserOpToJsonRpc` which expects bigints.
  */
-declare function createSubgraphNativeUsdtQuoter(config?: SubgraphNativeUsdtQuoterConfig): (amountNative: bigint) => Promise<bigint>;
+declare function serializeEntryToJsonRpc(entry: PendingUserOpEntry, signature: Hex, variant?: "sponsored" | "fallback"): Record<string, string | null>;
 
-interface NativePtQuoterConfig {
-    /** Viem PublicClient — used to call Chainlink on-chain. */
-    provider: PublicClient;
-    /** Address of the PointToken being traded. */
-    pointTokenAddress: Address;
-    /** Chainlink ETH/USD feed address. Defaults to Base mainnet feed. */
-    chainlinkFeedAddress?: Address;
-    /** PAFI subgraph GraphQL endpoint. */
-    subgraphUrl?: string;
-    /** Cache TTL in ms. Default: 30_000. */
-    cacheTtlMs?: number;
-    /** Fallback ETH price (USD) when Chainlink is unreachable. Default: 3000. */
-    fallbackEthPriceUsd?: number;
-    /** Fallback PT price (USDT per 1 PT) when subgraph is unreachable. Default: 0.1. */
-    fallbackPtPriceUsdt?: number;
-    fetchImpl?: typeof fetch;
-    now?: () => number;
-}
 /**
- * Create a native→PT quoter for use as `FeeManager.quoteNativeToFee`.
- *
- * Converts ETH gas cost → USDT (via Chainlink ETH/USD) → PT (via subgraph
- * pool price), returning the fee amount in PT raw units (18 decimals).
- *
- * Formula:
- *   feeInPT = amountNative × ethPrice_8dec × ptPerUsdt_18dec / 10^26
- *
- * Both prices are cached in-process (default 30s TTL).
- *
- * @example
- * ```ts
- * fee: {
- *   quoteNativeToFee: createNativePtQuoter({
- *     provider,
- *     pointTokenAddress: "0x...",
- *     chainlinkFeedAddress: getContractAddresses(chainId).chainlinkEthUsd,
- *   }),
- * }
- * ```
+ * Re-shape `UserOpTypedData` so all `bigint` fields become hex strings —
+ * required for JSON transport over HTTP. Mirrors the inverse of what
+ * `walletClient.signTypedData` accepts on the client (it auto-coerces hex
+ * strings back to bigints for `uint256` fields).
  */
-declare function createNativePtQuoter(config: NativePtQuoterConfig): (amountNative: bigint) => Promise<bigint>;
-
+type SerializedUserOpTypedData = {
+    domain: UserOpTypedData["domain"];
+    types: UserOpTypedData["types"];
+    primaryType: UserOpTypedData["primaryType"];
+    message: {
+        sender: Address;
+        nonce: Hex;
+        initCode: Hex;
+        callData: Hex;
+        accountGasLimits: Hex;
+        preVerificationGas: Hex;
+        gasFees: Hex;
+        paymasterAndData: Hex;
+    };
+};
 /**
- * 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)
+ * Convert a `UserOpTypedData` payload into the JSON-safe wire form
+ * (bigint → hex string). The mobile client passes this directly to
+ * `eth_signTypedData_v4` / viem's `signTypedData`.
  */
-interface CombinedBalance {
-    offChain: bigint;
-    onChain: bigint;
-    total: bigint;
-}
-interface BalanceAggregatorConfig {
-    provider: PublicClient;
-    ledger: IPointLedger;
-}
+declare function serializeUserOpTypedData(td: UserOpTypedData): SerializedUserOpTypedData;
 /**
- * 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>>;
-}
-
-/**
- * Top-level configuration for `createIssuerService`.
- *
- * In v1.4 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
- * 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;
-    /** Legacy single-token shortcut; prefer `pointTokenAddresses`. */
-    pointTokenAddress?: Address;
-    /** All PointToken addresses this issuer supports. */
-    pointTokenAddresses?: Address[];
-    /**
-     * 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.
-     */
-    contracts?: Pick<ApiConfigResponse["contracts"], "pointToken" | "pointTokens" | "relay">;
-    /**
-     * Shared `PublicClient` used for on-chain reads, simulation, indexer
-     * polling, and gas-price lookups. Must be pointed at the target chain.
-     */
-    provider: PublicClient;
-    auth: {
-        jwtSecret: string;
-        /** SIWE-style login-message domain, e.g. `"app.example.com"`. */
-        domain: string;
-        /** Passed straight to `jose` (`"24h"`, `"7d"`, …). Default `"24h"`. */
-        jwtExpiresIn?: string;
-    };
-    /**
-     * Off-chain point ledger — the source of truth for user balances and
-     * in-flight minting locks. Every issuer provides their own database-backed
-     * implementation (Postgres, Redis, etc.) that implements `IPointLedger`.
-     * The SDK does not ship a production ledger; each issuer's data model and
-     * infrastructure are different.
-     */
-    ledger: IPointLedger;
-    /**
-     * Policy engine — optional, defaults to `DefaultPolicyEngine` which checks
-     * off-chain balance. Extend or replace to add KYC, volume caps, etc.
-     */
-    policy?: IPolicyEngine;
-    /** Session store — optional, defaults to `MemorySessionStore` (dev/test only). */
-    sessionStore?: ISessionStore;
-    /**
-     * Fee management config. If omitted the `handleGasFee` endpoint will
-     * throw "not configured" at request time.
-     */
-    fee?: Omit<FeeManagerConfig, "provider">;
-    /**
-     * Pool discovery function for `handlePools`. If omitted the endpoint
-     * throws "not configured" at request time.
-     */
-    poolsProvider?: PoolsProvider;
-    /**
-     * Enables `handleClaim`. The factory combines these with the shared
-     * `policy` + `relayService` instances already wired by the factory.
-     * Omit to disable the `/claim` endpoint.
-     */
-    claim?: {
-        issuerSignerWallet: WalletClient;
-        /** Defaults to the PAFI-deployed BatchExecutor for the target chain. */
-        batchExecutorAddress?: Address;
-        lockDurationMs?: number;
-    };
-    indexer?: {
-        fromBlock?: bigint;
-        cursorStore?: IIndexerCursorStore;
-        confirmations?: number;
-        batchSize?: number;
-        pollIntervalMs?: number;
-        /**
-         * If `true`, the factory calls `indexer.start()` before returning.
-         * Default: `false` — the caller decides when to begin polling.
-         */
-        autoStart?: boolean;
-    };
-}
-interface IssuerService {
-    /** AuthService — login, logout, nonce management. */
-    auth: AuthService;
-    /** Session store — nonce + JWT session persistence. */
-    session: ISessionStore;
-    ledger: IPointLedger;
-    policy: IPolicyEngine;
-    /** RelayService — prepareMint / prepareBurn UserOp builders. */
-    relay: RelayService;
-    /** FeeManager — gas fee estimation. Undefined if not configured. */
-    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;
-}
-/**
- * Wire a fully-functional issuer service from a single config object.
- *
- * Defaults:
- *  - `sessionStore`    → `MemorySessionStore` (dev/test only — replace in prod)
- *  - `policy`          → `DefaultPolicyEngine({ ledger })`
- *  - `feeManager`      → undefined (handleGasFee throws until configured)
- *  - `poolsProvider`   → undefined (handlePools throws until configured)
- *  - `indexer.autoStart` → false
- *
- * Throws synchronously if any required field is missing.
- */
-declare function createIssuerService(config: IssuerServiceConfig): IssuerService;
-
-/**
- * A pending UserOp serialized for persistent storage (Redis, Postgres, memory).
- *
- * All bigint fields are stored as decimal strings so the entry can be
- * JSON-serialized without precision loss. Convert back to bigint before
- * calling `computeUserOpHash` or `serializeUserOpToJsonRpc`.
- */
-interface PendingUserOpEntry {
-    sender: Address;
-    nonce: string;
-    callData: Hex;
-    callGasLimit: string;
-    verificationGasLimit: string;
-    preVerificationGas: string;
-    maxFeePerGas: string;
-    maxPriorityFeePerGas: string;
-    paymaster?: Address;
-    paymasterVerificationGasLimit?: string;
-    paymasterPostOpGasLimit?: string;
-    paymasterData?: Hex;
-    chainId: number;
-    /** Hex-encoded userOpHash — the value the user signed via personal_sign. */
-    userOpHash: Hex;
-    /**
-     * Fee-stripped fallback variant. Set by `/claim/prepare` and
-     * `/redeem/prepare` when a PT operator fee is configured AND the
-     * paymaster sponsorship attached successfully — i.e. the user might
-     * still want to submit without paymaster (paying ETH gas), and in
-     * that case shouldn't be charged the PT fee. `/claim/submit` reads
-     * this branch when its request body specifies
-     * `variant: "fallback"`.
-     *
-     * Has a different `callData` (no PT.transfer prepended) and
-     * therefore a different `userOpHash`. Paymaster fields are NOT
-     * present — the fallback is by definition unsponsored.
-     */
-    fallback?: {
-        callData: Hex;
-        callGasLimit: string;
-        verificationGasLimit: string;
-        preVerificationGas: string;
-        userOpHash: Hex;
-    };
-}
-/**
- * Storage backend for pending UserOps in the mobile prepare/submit pattern.
- *
- * Implement this interface and wire it into your issuer backend:
- *   - `save()` — called by `POST /claim/prepare` and `POST /redeem/prepare`
- *   - `get()`  — called by `POST /claim/submit` and `POST /redeem/submit`
- *   - `delete()` — called after successful submit or explicit cancellation
- *
- * The default implementation in the gg56 boilerplate uses Redis with
- * a short TTL matching the MintRequest / BurnRequest deadline.
- */
-interface IPendingUserOpStore {
-    save(lockId: string, entry: PendingUserOpEntry, ttlSeconds: number): Promise<void>;
-    get(lockId: string): Promise<PendingUserOpEntry | null>;
-    delete(lockId: string): Promise<void>;
-}
-
-/**
- * Convert a stored `PendingUserOpEntry` (decimal-string fields) plus a
- * signature into the JSON-RPC wire format for `eth_sendUserOperation`.
- *
- * Bridges the gap between the serialized storage format (decimal strings,
- * safe for JSON/Redis) and `serializeUserOpToJsonRpc` which expects bigints.
- */
-declare function serializeEntryToJsonRpc(entry: PendingUserOpEntry, signature: Hex, variant?: "sponsored" | "fallback"): Record<string, string | null>;
-
-/**
- * Re-shape `UserOpTypedData` so all `bigint` fields become hex strings —
- * required for JSON transport over HTTP. Mirrors the inverse of what
- * `walletClient.signTypedData` accepts on the client (it auto-coerces hex
- * strings back to bigints for `uint256` fields).
- */
-type SerializedUserOpTypedData = {
-    domain: UserOpTypedData["domain"];
-    types: UserOpTypedData["types"];
-    primaryType: UserOpTypedData["primaryType"];
-    message: {
-        sender: Address;
-        nonce: Hex;
-        initCode: Hex;
-        callData: Hex;
-        accountGasLimits: Hex;
-        preVerificationGas: Hex;
-        gasFees: Hex;
-        paymasterAndData: Hex;
-    };
-};
-/**
- * Convert a `UserOpTypedData` payload into the JSON-safe wire form
- * (bigint → hex string). The mobile client passes this directly to
- * `eth_signTypedData_v4` / viem's `signTypedData`.
- */
-declare function serializeUserOpTypedData(td: UserOpTypedData): SerializedUserOpTypedData;
-/**
- * Merge Pimlico's paymaster-sponsorship response into a UserOp
- * skeleton, applying only fields that are actually defined.
+ * Merge Pimlico's paymaster-sponsorship response into a UserOp
+ * skeleton, applying only fields that are actually defined.
  *
  * `pm_sponsorUserOperation` returns:
  * - `paymaster` / `paymasterData` — required for the sponsored sig
@@ -2052,129 +1713,875 @@ interface PrepareMobileUserOpParams {
     /** TTL the store entry should outlive — typically the MintRequest deadline. */
     ttlSeconds: number;
 }
-interface PrepareMobileUserOpResult {
-    sponsored: PreparedUserOp;
-    /**
-     * Set when `partialUserOpFallback` was supplied AND the PT fee was
-     * non-zero (i.e. sponsored ≠ fallback). Mobile client picks which
-     * variant to sign + submit; SDK's `serializeEntryToJsonRpc` reads
-     * the `variant` flag to dispatch.
-     */
-    fallback?: PreparedUserOp;
-    /** What got persisted into the pending-userop store. */
-    entry: PendingUserOpEntry;
+interface PrepareMobileUserOpResult {
+    sponsored: PreparedUserOp;
+    /**
+     * Set when `partialUserOpFallback` was supplied AND the PT fee was
+     * non-zero (i.e. sponsored ≠ fallback). Mobile client picks which
+     * variant to sign + submit; SDK's `serializeEntryToJsonRpc` reads
+     * the `variant` flag to dispatch.
+     */
+    fallback?: PreparedUserOp;
+    /** What got persisted into the pending-userop store. */
+    entry: PendingUserOpEntry;
+}
+/**
+ * Build the sponsored UserOp + (optional) fee-stripped fallback for the
+ * mobile prepare/submit flow.
+ *
+ * What this does, end-to-end:
+ *   1. Merge Pimlico's paymaster sponsorship + re-quoted gas into the
+ *      caller's `partialUserOp` skeleton.
+ *   2. Compute the EIP-712 userOpHash + the typed-data payload (in
+ *      JSON-safe form for HTTP transport).
+ *   3. (Optional) Repeat for the `partialUserOpFallback` skeleton with
+ *      no paymaster fields — produces a separate hash + typed-data so
+ *      the client can re-sign if it falls back.
+ *   4. Persist a single store entry containing BOTH callData variants
+ *      keyed by lockId. `serializeEntryToJsonRpc` reads the `variant`
+ *      param at submit time.
+ *
+ * Replaces ~100 LoC of glue per scenario in issuer controllers.
+ */
+declare function prepareMobileUserOp(params: PrepareMobileUserOpParams): Promise<PrepareMobileUserOpResult>;
+
+/**
+ * Mobile prepare/submit orchestrators — abstract the duplicate glue
+ * between `/claim/prepare`+`/claim/submit` and `/redeem/prepare`+
+ * `/redeem/submit`. Both share the same shape:
+ *
+ *   prepare:  fees + delegation check → paymaster → prepareMobileUserOp
+ *   submit:   fetch entry → serialize+sign → relay → bind hash → delete
+ *
+ * Issuer controllers shrink to ~30 LoC each — wire the handler that
+ * produces `partialUserOp[+ fallback]`, hand off to these.
+ */
+declare class PendingUserOpNotFoundError extends Error {
+    readonly code = "PENDING_USEROP_NOT_FOUND";
+    constructor(lockId: string);
+}
+interface HandleMobilePrepareParams {
+    /** User EOA — used for the delegation check. */
+    userAddress: Address;
+    chainId: number;
+    /** Lock id (issuer-generated) keying both store entry + ledger row. */
+    lockId: string;
+    /**
+     * Partial UserOp from the upstream handler (PTClaimHandler /
+     * PTRedeemHandler). The orchestrator will top up `maxFeePerGas` /
+     * `maxPriorityFeePerGas` from `provider.estimateFeesPerGas()` if the
+     * fields aren't already set, then request paymaster sponsorship.
+     */
+    partialUserOp: PartialUserOperation;
+    /** Optional fee-stripped fallback variant. */
+    partialUserOpFallback?: PartialUserOperation;
+    /**
+     * Scenario tag — passed to `requestSponsorship` so the relayer can
+     * apply per-scenario L1 enforcement (`mint`, `burn`, etc.).
+     */
+    scenario: string;
+    /** Target contract for the paymaster intent. */
+    pointTokenAddress: Address;
+    /** TTL the store entry should outlive. Typically the lock duration in seconds. */
+    ttlSeconds: number;
+    store: IPendingUserOpStore;
+    provider: PublicClient;
+    /** Optional — when omitted, paymaster is skipped and `sponsored: false` is returned. */
+    pafiBackendClient?: PafiBackendClient | null;
+    onWarning?: (msg: string) => void;
+}
+interface HandleMobilePrepareResult extends PrepareMobileUserOpResult {
+    /**
+     * True when paymaster sponsorship was applied to the sponsored variant.
+     * (Renamed from `sponsored` to avoid clashing with
+     * `PrepareMobileUserOpResult.sponsored` which is the PreparedUserOp object.)
+     */
+    isSponsored: boolean;
+    /**
+     * True when the user's EOA has no EIP-7702 delegation set on-chain.
+     * The mobile client must run the `/delegate/*` flow first.
+     */
+    needsDelegation: boolean;
+}
+/**
+ * Build the mobile prepare response. End-to-end:
+ *
+ *   1. Pull `estimateFeesPerGas` + `getCode(user)` in parallel.
+ *   2. Top up sponsored UserOp fees if the upstream handler left them
+ *      unset.
+ *   3. `requestPaymaster` — non-fatal: if PAFI declines, the sponsored
+ *      variant still works, the FE just falls back to the unsponsored
+ *      response.
+ *   4. `prepareMobileUserOp` — merge + hash + persist.
+ */
+declare function handleMobilePrepare(params: HandleMobilePrepareParams): Promise<HandleMobilePrepareResult>;
+interface HandleMobileSubmitParams {
+    lockId: string;
+    /** User signature over `userOpHash` (or `userOpHashFallback`). */
+    signature: Hex;
+    /** Which variant the user actually signed. Defaults to `'sponsored'`. */
+    variant?: "sponsored" | "fallback";
+    store: IPendingUserOpStore;
+    /**
+     * Bind the bundler-returned hash to the lock so `claim/redeem status`
+     * can fall back to the bundler receipt when the indexer's
+     * amount-based match races and resolves a sibling. Different ledgers
+     * use different methods (`bindMintUserOpHash` vs `bindCreditUserOpHash`),
+     * so the caller passes the correct one.
+     */
+    bindUserOpHash: (lockId: string, userOpHash: Hex) => Promise<void>;
+    pafiBackendClient?: PafiBackendClient | null;
+    /** Defaults to `ENTRY_POINT_V08`. */
+    entryPoint?: string;
+}
+/**
+ * Submit a previously-prepared mobile UserOp to the bundler.
+ *
+ * Throws:
+ *   - `PendingUserOpNotFoundError` — entry expired or already submitted.
+ *     Map to 404.
+ *   - `BundlerNotConfiguredError` — `pafiBackendClient` missing. Map to 503.
+ *   - `BundlerRejectedError` — bundler rejected the UserOp. Map to 422.
+ */
+declare function handleMobileSubmit(params: HandleMobileSubmitParams): Promise<{
+    userOpHash: Hex;
+}>;
+
+interface IssuerRegistryRecord {
+    issuerAddress: Address;
+    signerAddress: Address;
+    name: string;
+    symbol: string;
+    declaredTotalSupply: bigint;
+    capBasisPoints: number;
+    active: boolean;
+    pointToken: Address;
+    mintingOracle: Address;
+}
+interface PreValidateMintResult {
+    /** Registry record read at pre-validation time. */
+    issuer: IssuerRegistryRecord;
+    /** Current on-chain PointToken.totalSupply(). */
+    totalSupply: bigint;
+    /** declaredTotalSupply × capBasisPoints / 10000. */
+    hardCap: bigint;
+    /** hardCap − totalSupply (clamped to 0). */
+    remaining: bigint;
+}
+/**
+ * Thrown by `IssuerStateValidator.preValidateMint()`.
+ * `code` maps 1:1 to the HTTP error the issuer API surfaces to clients.
+ */
+declare class IssuerStateError extends Error {
+    readonly code: "ISSUER_NOT_REGISTERED" | "ISSUER_INACTIVE" | "MINT_CAP_EXCEEDED";
+    readonly details?: Record<string, unknown> | undefined;
+    constructor(code: "ISSUER_NOT_REGISTERED" | "ISSUER_INACTIVE" | "MINT_CAP_EXCEEDED", message: string, details?: Record<string, unknown> | undefined);
+}
+
+/**
+ * Pure (framework-agnostic) validator for issuer state.
+ *
+ * Reads IssuerRegistry + PointToken on-chain state and pre-validates
+ * mint requests before the user submits a UserOp. Catching these
+ * off-chain lets issuers fail fast with a clear error rather than
+ * wasting gas on a revert.
+ *
+ * Caching:
+ *   - `PointToken.issuer()` — memoized for the process lifetime (immutable)
+ *   - Full state (registry + totalSupply) — 30s TTL per PointToken
+ *   - Burst calls while a fetch is in-flight share the same Promise
+ *     (thundering-herd protection)
+ *
+ * Usage in NestJS: wrap this in an `@Injectable()` service; pass
+ * `PublicClient` and `registryAddress` from your DI container.
+ */
+declare class IssuerStateValidator {
+    private readonly provider;
+    private readonly registryAddress;
+    private readonly pointTokenIssuerCache;
+    private readonly stateCache;
+    private readonly inflight;
+    constructor(provider: PublicClient, registryAddress: Address);
+    /**
+     * Convenience factory — reads `registryAddress` from the SDK
+     * `CONTRACT_ADDRESSES` map for the given chain.
+     */
+    static forChain(provider: PublicClient, chainId: number): IssuerStateValidator;
+    /**
+     * Invalidate cached state for one PointToken, or everything if omitted.
+     * Call after admin txs that change registry or cap settings.
+     */
+    invalidate(pointToken?: Address): void;
+    /**
+     * Resolve `PointToken.issuer()` once per token and memoize.
+     * The issuer field is set at `initialize()` and never changes.
+     */
+    getIssuerAddressForPointToken(pointToken: Address): Promise<Address>;
+    /**
+     * Read registry record + totalSupply, with 30s cache and in-flight
+     * deduplication. Does NOT throw on inactive/missing — returns raw state.
+     */
+    getIssuerState(pointToken: Address): Promise<PreValidateMintResult>;
+    /**
+     * Validate that `amount` PT can be minted on `pointToken` right now.
+     *
+     * Throws `IssuerStateError` with:
+     *   - `ISSUER_NOT_REGISTERED` — registry has no record for this issuer
+     *   - `ISSUER_INACTIVE`       — issuer.active is false
+     *   - `MINT_CAP_EXCEEDED`     — totalSupply + amount would exceed hardCap
+     *
+     * Returns the fetched state on success so callers can log without a
+     * second RPC round-trip.
+     */
+    preValidateMint(pointToken: Address, amount: bigint): Promise<PreValidateMintResult>;
+    private fetchIssuerState;
+}
+
+type DecodedCall$2 = ReturnType<typeof decodeBatchExecuteCalls>[number];
+
+/**
+ * v1.4 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
+ * transfer) plus an optional fallback variant (mint only — for
+ * paymaster-refused fallback).
+ *
+ * Caller fetches AA + mintRequest nonces (so issuers can plug in their
+ * own composer — gg56 uses a timestamp-key 2D nonce). Caller layers
+ * paymaster sponsorship + sponsorAuth on top of the returned UserOps.
+ */
+declare class PTClaimError extends Error {
+    code: "INVALID_AMOUNT" | "VALIDATION_FAILED" | "BUILD_FAILED";
+    details?: Record<string, unknown> | undefined;
+    constructor(code: "INVALID_AMOUNT" | "VALIDATION_FAILED" | "BUILD_FAILED", message: string, details?: Record<string, unknown> | undefined);
+}
+interface PTClaimHandlerConfig {
+    ledger: IPointLedger;
+    relayService: RelayService;
+    provider: PublicClient;
+    /** Issuer minter signer wallet — passed through to RelayService.prepareMint. */
+    issuerSignerWallet: WalletClient;
+    /**
+     * EIP-712 domain `name` for `MintRequest`. Typically the PointToken
+     * ERC-20 name. RelayService will set chainId + verifyingContract from
+     * the request.
+     */
+    pointTokenDomainName: string;
+    /** Optional — when wired, used to estimate the PT gas-reimbursement fee. */
+    feeService?: FeeManager;
+    /** Optional — pre-validates issuer status + cap before locking balance. */
+    issuerStateValidator?: IssuerStateValidator;
+    /** How long the off-chain balance lock survives if the mint never lands. Default 15 min. */
+    lockDurationMs?: number;
+    /** How far ahead of `now` to set the MintRequest deadline. Default 15 min. */
+    signatureDeadlineSeconds?: number;
+    now?: () => number;
+}
+interface PTClaimRequest {
+    authenticatedAddress: Address;
+    userAddress: Address;
+    amount: bigint;
+    pointTokenAddress: Address;
+    chainId: number;
+    /** ERC-4337 account nonce for the user's EOA. */
+    aaNonce: bigint;
+    /** Current `mintRequestNonces[userAddress]` from PointToken. */
+    mintRequestNonce: bigint;
+}
+interface PTClaimResponse {
+    /** Sponsored UserOp — mint + PT fee transfer (when feeAmount > 0). */
+    userOp: PartialUserOperation;
+    /**
+     * Fallback UserOp — mint only, no PT fee transfer. Present only when
+     * `feeAmount > 0`. User pays gas in ETH directly.
+     */
+    fallback?: PartialUserOperation;
+    lockId: string;
+    feeAmount: bigint;
+    signatureDeadline: bigint;
+    expiresInSeconds: number;
+    /** Decoded calls for the sponsored UserOp (convenience for FE-submit path). */
+    calls: DecodedCall$2[];
+    /** Decoded calls for the fallback UserOp (when present). */
+    callsFallback?: DecodedCall$2[];
+}
+declare class PTClaimHandler {
+    private readonly cfg;
+    constructor(config: PTClaimHandlerConfig);
+    handle(request: PTClaimRequest): Promise<PTClaimResponse>;
+}
+
+type DecodedCall$1 = ReturnType<typeof decodeBatchExecuteCalls>[number];
+
+/**
+ * PT → USDT swap handler.
+ *
+ * Quotes via V4 on-chain Quoter (`findBestQuote`), applies slippage,
+ * computes the PT gas-reimbursement fee from `FeeManager`, and builds
+ * two UserOps:
+ *
+ *   - **sponsored** — swap (amountIn − fee) + transfer(fee, PAFI). User
+ *     holds exactly `amountIn` PT.
+ *   - **fallback** — swap full `amountIn`, no PT fee transfer. Built
+ *     only when `feeAmount > 0`. User pays gas in ETH directly.
+ *
+ * Re-quotes the sponsored path on `(amountIn − feeAmount)` because the
+ * sponsored path actually swaps that much; the fallback uses the
+ * original quote.
+ *
+ * Caller (controller) layers `sponsorAuth` on top of the returned
+ * userOp. No off-chain ledger state is touched — swap is purely
+ * on-chain.
+ */
+declare class SwapError extends Error {
+    code: "QUOTE_UNAVAILABLE" | "FEE_EXCEEDS_AMOUNT" | "INVALID_AMOUNT";
+    constructor(code: "QUOTE_UNAVAILABLE" | "FEE_EXCEEDS_AMOUNT" | "INVALID_AMOUNT", message: string);
+}
+interface SwapHandlerConfig {
+    provider: PublicClient;
+    poolsProvider: PoolsProvider;
+    /** Optional — when wired, used to estimate the PT gas-reimbursement fee. */
+    feeService?: FeeManager;
+    /**
+     * Default slippage applied to the V4 quote when the request omits
+     * `slippageBps`. 50 bps = 0.5%.
+     */
+    defaultSlippageBps?: number;
+    /** Default deadline window in seconds applied when not passed in request. Default 300. */
+    defaultSwapDeadlineSeconds?: number;
+    now?: () => number;
+}
+interface SwapRequest {
+    userAddress: Address;
+    chainId: number;
+    pointTokenAddress: Address;
+    amountIn: bigint;
+    /** ERC-4337 account nonce for the user's EOA. */
+    aaNonce: bigint;
+    /** Optional override; falls back to `defaultSlippageBps`. */
+    slippageBps?: number;
+    /** Optional override; falls back to `now() + defaultSwapDeadlineSeconds`. */
+    deadline?: bigint;
+}
+interface SwapResponse {
+    /** Sponsored UserOp — swap (amountIn − fee) + PT.transfer(fee). */
+    userOp: PartialUserOperation;
+    /** Fallback UserOp — swap full amountIn, no PT fee transfer. Present only when fee > 0. */
+    fallback?: PartialUserOperation;
+    feeAmount: bigint;
+    /** Quote for the sponsored path (after fee deduction). */
+    estimatedUsdtOut: bigint;
+    minAmountOut: bigint;
+    /** Quote for the fallback path (full amountIn). Present only when fee > 0. */
+    estimatedUsdtOutFallback?: bigint;
+    minAmountOutFallback?: bigint;
+    deadline: bigint;
+    calls: DecodedCall$1[];
+    callsFallback?: DecodedCall$1[];
+}
+declare class SwapHandler {
+    private readonly cfg;
+    constructor(config: SwapHandlerConfig);
+    handle(request: SwapRequest): Promise<SwapResponse>;
+}
+
+type DecodedCall = ReturnType<typeof decodeBatchExecuteCalls>[number];
+
+/**
+ * Orderly perp-deposit handler — builds the sponsored + fallback
+ * UserOps for the PAFI Relay path.
+ *
+ * Resolves USDC + verifies the broker is whitelisted on the Vault,
+ * quotes the Relay's USDC fee (covers LayerZero msg.value out of the
+ * Relay's ETH reserve), then builds two UserOps:
+ *
+ *   - **sponsored** — PT.transfer(fee, PAFI) + USDC.approve(relay,
+ *     total) + Relay.deposit(req). User reimburses gas in PT.
+ *   - **fallback** — USDC.approve + Relay.deposit only. User pays
+ *     ERC-4337 gas in ETH. Built only when `feeAmount > 0`.
+ *
+ * `maxFee` is set to `quote × 1.5` — slippage cap on the Relay's
+ * USD-pricing during the inclusion window. If the actual fee at
+ * execution exceeds maxFee the Relay reverts (`FeeExceedsMax`).
+ */
+declare class PerpDepositError extends Error {
+    code: "PERP_DEPOSIT_UNAVAILABLE" | "BROKER_NOT_WHITELISTED" | "RELAY_FEE_EXCEEDS_AMOUNT" | "FEE_EXCEEDS_AMOUNT" | "INVALID_AMOUNT";
+    constructor(code: "PERP_DEPOSIT_UNAVAILABLE" | "BROKER_NOT_WHITELISTED" | "RELAY_FEE_EXCEEDS_AMOUNT" | "FEE_EXCEEDS_AMOUNT" | "INVALID_AMOUNT", message: string);
+}
+interface PerpDepositHandlerConfig {
+    provider: PublicClient;
+    /** Optional — when wired, used to estimate the PT gas-reimbursement fee. */
+    feeService?: FeeManager;
+    /** PointToken address used for the sponsored PT.transfer. */
+    pointTokenAddress: Address;
+    /**
+     * Slippage premium applied on top of the Relay quote when computing
+     * `maxFee`. Default 50% (factor 150). The Relay reverts if actual fee
+     * exceeds `maxFee` so a generous cap reduces re-quote churn.
+     */
+    maxFeePremiumBps?: number;
+}
+interface PerpDepositRequest {
+    userAddress: Address;
+    chainId: number;
+    amount: bigint;
+    brokerId: keyof typeof BROKER_HASHES;
+    /** ERC-4337 account nonce. */
+    aaNonce: bigint;
+}
+interface PerpDepositResponse {
+    userOp: PartialUserOperation;
+    fallback?: PartialUserOperation;
+    feeAmount: bigint;
+    relayTokenFee: bigint;
+    maxFee: bigint;
+    netDeposit: bigint;
+    accountId: `0x${string}`;
+    brokerHash: `0x${string}`;
+    usdcAddress: Address;
+    relayAddress: Address;
+    calls: DecodedCall[];
+    callsFallback?: DecodedCall[];
+}
+declare class PerpDepositHandler {
+    private readonly cfg;
+    constructor(config: PerpDepositHandlerConfig);
+    handle(request: PerpDepositRequest): Promise<PerpDepositResponse>;
+}
+
+/**
+ * Config for `createSubgraphPoolsProvider`.
+ */
+interface SubgraphPoolsProviderConfig {
+    /**
+     * Fully qualified subgraph GraphQL endpoint.
+     * Defaults to the PAFI-hosted subgraph (`PAFI_SUBGRAPH_URL`).
+     * Override only when pointing at a staging or custom deployment.
+     */
+    subgraphUrl?: string;
+    /**
+     * Cache TTL in milliseconds. Pool discovery is near-static — a 30s
+     * cache removes subgraph load without meaningfully delaying UX.
+     * Set to 0 to disable caching. Default: 30_000.
+     */
+    cacheTtlMs?: number;
+    /**
+     * Optional fetch override for test harnesses. Defaults to global `fetch`.
+     */
+    fetchImpl?: typeof fetch;
+    /**
+     * Optional clock override for tests.
+     */
+    now?: () => number;
+}
+/**
+ * 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[]`.
+ * Multiple pools per token would require a subgraph schema change.
+ *
+ * The result is cached in-process with a short TTL (default 30s). Pool
+ * discovery is near-static so this avoids hammering the subgraph without
+ * blocking config changes for long.
+ *
+ * Returns `{ pools: [] }` if:
+ *  - 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)
+ *
+ * Assumes the PAFI subgraph schema. Issuers with a custom subgraph must
+ * implement `PoolsProvider` themselves instead of using this helper.
+ *
+ * @example
+ * ```ts
+ * import { createSubgraphPoolsProvider, createIssuerService } from "@pafi/issuer";
+ *
+ * const service = createIssuerService({
+ *   // ...other config
+ *   poolsProvider: createSubgraphPoolsProvider({
+ *     subgraphUrl: "https://graph.pacificfinance.org/subgraphs/name/pafi",
+ *   }),
+ * });
+ * ```
+ */
+declare function createSubgraphPoolsProvider(config?: SubgraphPoolsProviderConfig): PoolsProvider;
+
+/**
+ * Config for `createSubgraphNativeUsdtQuoter`.
+ */
+interface SubgraphNativeUsdtQuoterConfig {
+    /**
+     * Fully qualified subgraph GraphQL endpoint.
+     * Defaults to the PAFI-hosted subgraph (`PAFI_SUBGRAPH_URL`).
+     * Override only when pointing at a staging or custom deployment.
+     */
+    subgraphUrl?: string;
+    /**
+     * Decimals of the USDT token. Defaults to 6 (standard USDT/USDC on
+     * Base, Ethereum, Polygon). Override for chains where USDT uses a
+     * different decimals value.
+     */
+    usdtDecimals?: number;
+    /**
+     * Decimals of the native token (ETH on Base/mainnet/Arbitrum/Optimism,
+     * MATIC on Polygon). Default: 18.
+     */
+    nativeDecimals?: number;
+    /**
+     * Cache TTL in milliseconds. ETH price drifts slowly relative to gas
+     * estimation needs — a 30s cache keeps fees stable across bursts of
+     * requests without letting them go stale during volatile markets.
+     * Set to 0 to disable caching. Default: 30_000.
+     */
+    cacheTtlMs?: number;
+    /**
+     * Fallback price (USDT per native token, human-readable float) used
+     * when the subgraph is unreachable. This keeps the backend operational
+     * during subgraph outages rather than bricking cashouts. The fee will
+     * be slightly off but the operator still gets paid. Default: 3000.
+     */
+    fallbackEthPriceUsd?: number;
+    /** Optional fetch override for test harnesses. */
+    fetchImpl?: typeof fetch;
+    /** Optional clock override for tests. */
+    now?: () => number;
+}
+/**
+ * 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 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 user flow during a subgraph outage.
+ *
+ * @example
+ * ```ts
+ * import { createSubgraphNativeUsdtQuoter, createIssuerService } from "@pafi-dev/issuer";
+ *
+ * const service = createIssuerService({
+ *   // ...other config
+ *   fee: {
+ *     quoteNativeToFee: createSubgraphNativeUsdtQuoter({
+ *       subgraphUrl: "https://graph.pacificfinance.org/subgraphs/name/pafi",
+ *     }),
+ *   },
+ * });
+ * ```
+ */
+declare function createSubgraphNativeUsdtQuoter(config?: SubgraphNativeUsdtQuoterConfig): (amountNative: bigint) => Promise<bigint>;
+
+interface NativePtQuoterConfig {
+    /** Viem PublicClient — used to call Chainlink on-chain. */
+    provider: PublicClient;
+    /** Address of the PointToken being traded. */
+    pointTokenAddress: Address;
+    /** Chainlink ETH/USD feed address. Defaults to Base mainnet feed. */
+    chainlinkFeedAddress?: Address;
+    /** PAFI subgraph GraphQL endpoint. */
+    subgraphUrl?: string;
+    /** Cache TTL in ms. Default: 30_000. */
+    cacheTtlMs?: number;
+    /** Fallback ETH price (USD) when Chainlink is unreachable. Default: 3000. */
+    fallbackEthPriceUsd?: number;
+    /** Fallback PT price (USDT per 1 PT) when subgraph is unreachable. Default: 0.1. */
+    fallbackPtPriceUsdt?: number;
+    fetchImpl?: typeof fetch;
+    now?: () => number;
+}
+/**
+ * Create a native→PT quoter for use as `FeeManager.quoteNativeToFee`.
+ *
+ * Converts ETH gas cost → USDT (via Chainlink ETH/USD) → PT (via subgraph
+ * pool price), returning the fee amount in PT raw units (18 decimals).
+ *
+ * Formula:
+ *   feeInPT = amountNative × ethPrice_8dec × ptPerUsdt_18dec / 10^26
+ *
+ * Both prices are cached in-process (default 30s TTL).
+ *
+ * @example
+ * ```ts
+ * fee: {
+ *   quoteNativeToFee: createNativePtQuoter({
+ *     provider,
+ *     pointTokenAddress: "0x...",
+ *     chainlinkFeedAddress: getContractAddresses(chainId).chainlinkEthUsd,
+ *   }),
+ * }
+ * ```
+ */
+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;
 }
 /**
- * Build the sponsored UserOp + (optional) fee-stripped fallback for the
- * mobile prepare/submit flow.
+ * v1.4 utility — aggregates off-chain + on-chain point balances into a
+ * single view for the "combined balance" UI in the Issuer App.
  *
- * What this does, end-to-end:
- *   1. Merge Pimlico's paymaster sponsorship + re-quoted gas into the
- *      caller's `partialUserOp` skeleton.
- *   2. Compute the EIP-712 userOpHash + the typed-data payload (in
- *      JSON-safe form for HTTP transport).
- *   3. (Optional) Repeat for the `partialUserOpFallback` skeleton with
- *      no paymaster fields — produces a separate hash + typed-data so
- *      the client can re-sign if it falls back.
- *   4. Persist a single store entry containing BOTH callData variants
- *      keyed by lockId. `serializeEntryToJsonRpc` reads the `variant`
- *      param at submit time.
+ * 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).
  *
- * Replaces ~100 LoC of glue per scenario in issuer controllers.
+ * See [REQUIREMENTS_V2.md] §1 — "The Issuer App displays a combined
+ * balance (off-chain points + on-chain PT) and does not surface USDT."
  */
-declare function prepareMobileUserOp(params: PrepareMobileUserOpParams): Promise<PrepareMobileUserOpResult>;
+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 IssuerRegistryRecord {
-    issuerAddress: Address;
-    signerAddress: Address;
-    name: string;
-    symbol: string;
-    declaredTotalSupply: bigint;
-    capBasisPoints: number;
-    active: boolean;
-    pointToken: Address;
-    mintingOracle: Address;
+/**
+ * Typed errors thrown by the helpers below — issuer controllers map
+ * these to the appropriate HTTP status. We don't depend on @nestjs/common
+ * here because the SDK is framework-agnostic; the consuming controller
+ * wraps each one in its preferred exception class.
+ */
+declare class BundlerNotConfiguredError extends Error {
+    readonly code = "BUNDLER_NOT_CONFIGURED";
+    constructor();
 }
-interface PreValidateMintResult {
-    /** Registry record read at pre-validation time. */
-    issuer: IssuerRegistryRecord;
-    /** Current on-chain PointToken.totalSupply(). */
-    totalSupply: bigint;
-    /** declaredTotalSupply × capBasisPoints / 10000. */
-    hardCap: bigint;
-    /** hardCap − totalSupply (clamped to 0). */
-    remaining: bigint;
+declare class BundlerRejectedError extends Error {
+    readonly code = "BUNDLER_REJECTED";
+    readonly cause: unknown;
+    constructor(message: string, cause: unknown);
+}
+interface RequestPaymasterParams {
+    /** PAFI backend client. When `null` / `undefined` → returns `undefined`. */
+    client: PafiBackendClient | null | undefined;
+    chainId: number;
+    scenario: string;
+    /** UserOp skeleton — must have all gas + fee fields set. */
+    userOp: {
+        sender: Address;
+        nonce: bigint;
+        callData: Hex;
+        callGasLimit: bigint;
+        verificationGasLimit: bigint;
+        preVerificationGas: bigint;
+        maxFeePerGas: bigint;
+        maxPriorityFeePerGas: bigint;
+    };
+    /** Target contract (typically the PointToken). */
+    pointTokenAddress: Address;
+    /**
+     * Function name to surface in audit / paymaster context. Defaults to
+     * a per-scenario sensible value (`mint` / `burn` / `swap` / generic
+     * scenario name).
+     */
+    functionName?: string;
+    /** Optional logger for the "sponsorship declined" warning. */
+    onWarning?: (msg: string) => void;
 }
 /**
- * Thrown by `IssuerStateValidator.preValidateMint()`.
- * `code` maps 1:1 to the HTTP error the issuer API surfaces to clients.
+ * Thin wrapper around `PafiBackendClient.requestSponsorship` with the
+ * "non-fatal on failure" semantics every issuer wants:
+ *
+ * - When the client is missing → returns `undefined` (the caller falls
+ *   back to a self-funded UserOp).
+ * - When the network call throws OR PAFI declines (rate limit, intent
+ *   rejection, paymaster outage) → returns `undefined` after logging,
+ *   so the controller doesn't hard-fail. The caller's
+ *   `prepareMobileUserOp` / `mergePaymasterFields` will gracefully
+ *   produce the unsponsored variant.
+ *
+ * Replaces ~30 LoC of try/catch + scenario-to-function mapping every
+ * issuer would copy.
  */
-declare class IssuerStateError extends Error {
-    readonly code: "ISSUER_NOT_REGISTERED" | "ISSUER_INACTIVE" | "MINT_CAP_EXCEEDED";
-    readonly details?: Record<string, unknown> | undefined;
-    constructor(code: "ISSUER_NOT_REGISTERED" | "ISSUER_INACTIVE" | "MINT_CAP_EXCEEDED", message: string, details?: Record<string, unknown> | undefined);
+declare function requestPaymaster(params: RequestPaymasterParams): Promise<Awaited<ReturnType<PafiBackendClient["requestSponsorship"]>> | undefined>;
+interface RelayUserOpParams {
+    client: PafiBackendClient | null | undefined;
+    /** EntryPoint address — typically `ENTRY_POINT_V08` from core. */
+    entryPoint: typeof ENTRY_POINT_V08 | string;
+    userOp: Record<string, string | null>;
+    /** EIP-7702 authorization (delegation UserOps only). */
+    eip7702Auth?: {
+        chainId: string;
+        address: string;
+        nonce: string;
+        r: string;
+        s: string;
+        yParity: string;
+    };
 }
+/**
+ * Submit a serialized UserOp to the Pimlico bundler via PAFI's
+ * sponsor-relayer. Handles the "client missing" / "bundler rejected"
+ * branches as typed errors so the controller can map to HTTP cleanly.
+ *
+ * Every issuer mobile flow has this exact wrapper — moved into SDK
+ * to drop ~30 LoC of try/catch + error-shape boilerplate per
+ * controller.
+ *
+ * Throws:
+ * - `BundlerNotConfiguredError` — caller didn't configure
+ *   `PafiBackendClient`. Map to 503.
+ * - `BundlerRejectedError` — bundler returned an error. Map to 422
+ *   (the FE can show the reason — usually `AA21` / `AA34` / etc.).
+ */
+declare function relayUserOp(params: RelayUserOpParams): Promise<{
+    userOpHash: Hex;
+}>;
 
 /**
- * Pure (framework-agnostic) validator for issuer state.
- *
- * Reads IssuerRegistry + PointToken on-chain state and pre-validates
- * mint requests before the user submits a UserOp. Catching these
- * off-chain lets issuers fail fast with a clear error rather than
- * wasting gas on a revert.
+ * Top-level configuration for `createIssuerService`.
  *
- * Caching:
- *   - `PointToken.issuer()` — memoized for the process lifetime (immutable)
- *   - Full state (registry + totalSupply) — 30s TTL per PointToken
- *   - Burst calls while a fetch is in-flight share the same Promise
- *     (thundering-herd protection)
+ * In v1.4 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.
  *
- * Usage in NestJS: wrap this in an `@Injectable()` service; pass
- * `PublicClient` and `registryAddress` from your DI container.
+ * **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.
  */
-declare class IssuerStateValidator {
-    private readonly provider;
-    private readonly registryAddress;
-    private readonly pointTokenIssuerCache;
-    private readonly stateCache;
-    private readonly inflight;
-    constructor(provider: PublicClient, registryAddress: Address);
+interface IssuerServiceConfig {
+    chainId: number;
+    /** Legacy single-token shortcut; prefer `pointTokenAddresses`. */
+    pointTokenAddress?: Address;
+    /** All PointToken addresses this issuer supports. */
+    pointTokenAddresses?: Address[];
     /**
-     * Convenience factory — reads `registryAddress` from the SDK
-     * `CONTRACT_ADDRESSES` map for the given chain.
+     * 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.
      */
-    static forChain(provider: PublicClient, chainId: number): IssuerStateValidator;
+    contracts?: Pick<ApiConfigResponse["contracts"], "pointToken" | "pointTokens" | "relay">;
     /**
-     * Invalidate cached state for one PointToken, or everything if omitted.
-     * Call after admin txs that change registry or cap settings.
+     * Shared `PublicClient` used for on-chain reads, simulation, indexer
+     * polling, and gas-price lookups. Must be pointed at the target chain.
      */
-    invalidate(pointToken?: Address): void;
+    provider: PublicClient;
+    auth: {
+        jwtSecret: string;
+        /** SIWE-style login-message domain, e.g. `"app.example.com"`. */
+        domain: string;
+        /** Passed straight to `jose` (`"24h"`, `"7d"`, …). Default `"24h"`. */
+        jwtExpiresIn?: string;
+    };
     /**
-     * Resolve `PointToken.issuer()` once per token and memoize.
-     * The issuer field is set at `initialize()` and never changes.
+     * Off-chain point ledger — the source of truth for user balances and
+     * in-flight minting locks. Every issuer provides their own database-backed
+     * implementation (Postgres, Redis, etc.) that implements `IPointLedger`.
+     * The SDK does not ship a production ledger; each issuer's data model and
+     * infrastructure are different.
      */
-    getIssuerAddressForPointToken(pointToken: Address): Promise<Address>;
+    ledger: IPointLedger;
     /**
-     * Read registry record + totalSupply, with 30s cache and in-flight
-     * deduplication. Does NOT throw on inactive/missing — returns raw state.
+     * Policy engine — optional, defaults to `DefaultPolicyEngine` which checks
+     * off-chain balance. Extend or replace to add KYC, volume caps, etc.
      */
-    getIssuerState(pointToken: Address): Promise<PreValidateMintResult>;
+    policy?: IPolicyEngine;
+    /** Session store — optional, defaults to `MemorySessionStore` (dev/test only). */
+    sessionStore?: ISessionStore;
     /**
-     * Validate that `amount` PT can be minted on `pointToken` right now.
-     *
-     * Throws `IssuerStateError` with:
-     *   - `ISSUER_NOT_REGISTERED` — registry has no record for this issuer
-     *   - `ISSUER_INACTIVE`       — issuer.active is false
-     *   - `MINT_CAP_EXCEEDED`     — totalSupply + amount would exceed hardCap
-     *
-     * Returns the fetched state on success so callers can log without a
-     * second RPC round-trip.
+     * Fee management config. If omitted the `handleGasFee` endpoint will
+     * throw "not configured" at request time.
      */
-    preValidateMint(pointToken: Address, amount: bigint): Promise<PreValidateMintResult>;
-    private fetchIssuerState;
+    fee?: Omit<FeeManagerConfig, "provider">;
+    /**
+     * Pool discovery function for `handlePools`. If omitted the endpoint
+     * throws "not configured" at request time.
+     */
+    poolsProvider?: PoolsProvider;
+    /**
+     * Enables `handleClaim`. The factory combines these with the shared
+     * `policy` + `relayService` instances already wired by the factory.
+     * Omit to disable the `/claim` endpoint.
+     */
+    claim?: {
+        issuerSignerWallet: WalletClient;
+        /** Defaults to the PAFI-deployed BatchExecutor for the target chain. */
+        batchExecutorAddress?: Address;
+        lockDurationMs?: number;
+    };
+    indexer?: {
+        fromBlock?: bigint;
+        cursorStore?: IIndexerCursorStore;
+        confirmations?: number;
+        batchSize?: number;
+        pollIntervalMs?: number;
+        /**
+         * If `true`, the factory calls `indexer.start()` before returning.
+         * Default: `false` — the caller decides when to begin polling.
+         */
+        autoStart?: boolean;
+    };
+}
+interface IssuerService {
+    /** AuthService — login, logout, nonce management. */
+    auth: AuthService;
+    /** Session store — nonce + JWT session persistence. */
+    session: ISessionStore;
+    ledger: IPointLedger;
+    policy: IPolicyEngine;
+    /** RelayService — prepareMint / prepareBurn UserOp builders. */
+    relay: RelayService;
+    /** FeeManager — gas fee estimation. Undefined if not configured. */
+    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;
 }
+/**
+ * Wire a fully-functional issuer service from a single config object.
+ *
+ * Defaults:
+ *  - `sessionStore`    → `MemorySessionStore` (dev/test only — replace in prod)
+ *  - `policy`          → `DefaultPolicyEngine({ ledger })`
+ *  - `feeManager`      → undefined (handleGasFee throws until configured)
+ *  - `poolsProvider`   → undefined (handlePools throws until configured)
+ *  - `indexer.autoStart` → false
+ *
+ * Throws synchronously if any required field is missing.
+ */
+declare function createIssuerService(config: IssuerServiceConfig): IssuerService;
 
 /** SDK package version — bumped on every release */
 declare const PAFI_ISSUER_SDK_VERSION = "0.4.0";
 
-export { type ApiClaimRequest, type ApiClaimResponse, type ApiConfigResponse, type ApiGasFeeResponse, type ApiLoginRequest, type ApiLoginResponse, type ApiNonceResponse, type ApiPoolsRequest, type ApiPoolsResponse, type ApiRedeemRequest, type ApiRedeemResponse, type ApiTopUpRequest, type ApiTopUpResponse, type ApiUserRequest, type ApiUserResponse, type AuthContext, AuthError, type AuthErrorCode, AuthService, type AuthServiceConfig, BalanceAggregator, type BalanceAggregatorConfig, type BurnEvent, BurnIndexer, type BurnIndexerConfig, type BurnStatusParams, type BurnStatusResponse, type CombinedBalance, DefaultPolicyEngine, type DefaultPolicyEngineOptions, FeeManager, type FeeManagerConfig, type IIndexerCursorStore, type IPendingUserOpStore, type IPointLedger, type IPolicyEngine, type ISessionStore, InMemoryCursorStore, IssuerApiHandlers, type IssuerApiHandlersConfig, type IssuerRegistryRecord, type IssuerService, type IssuerServiceConfig, IssuerStateError, IssuerStateValidator, LockNotFoundError, type LockedMintRequest, type LoginResult, MemorySessionStore, type MemorySessionStoreOptions, type MintEvent, type MintStatusParams, type MintStatusResponse, type MintingStatus, type NativePtQuoterConfig, NonceManager, PAFI_ISSUER_SDK_VERSION, PTRedeemError, PTRedeemHandler, type PTRedeemHandlerConfig, type PTRedeemRequest, type PTRedeemResponse, PafiBackendClient, type PafiBackendConfig, PafiBackendError, type PafiBackendErrorCode, type PendingCredit, type PendingUserOpEntry, PointIndexer, type PointIndexerConfig, type PolicyDecision, type PolicyEvalRequest, type PoolsProvider, type PreValidateMintResult, type PrepareBurnDirectParams, type PrepareBurnParams, type PrepareBurnWithSigParams, type PrepareMintParams, type PrepareMobileUserOpParams, type PrepareMobileUserOpResult, type PreparedUserOp, RelayError, type RelayErrorCode, RelayService, type RelayUserOpRequest, type RelayUserOpResponse, type RetryConfig, type SerializedUserOpTypedData, type Session, type SponsorshipRequest, type SponsorshipResponse, type SponsorshipTarget, type SponsorshipUserOp, type SubgraphNativeUsdtQuoterConfig, type SubgraphPoolsProviderConfig, TopUpRedemptionError, TopUpRedemptionHandler, type TopUpRedemptionHandlerConfig, type TopUpRedemptionRequest, type TopUpRedemptionResponse, authenticateRequest, createIssuerService, createNativePtQuoter, createSubgraphNativeUsdtQuoter, createSubgraphPoolsProvider, handleClaimStatus, handleRedeemStatus, mergePaymasterFields, prepareMobileUserOp, serializeEntryToJsonRpc, serializeUserOpTypedData };
+export { type ApiClaimRequest, type ApiClaimResponse, type ApiConfigResponse, type ApiGasFeeResponse, type ApiLoginRequest, type ApiLoginResponse, type ApiNonceResponse, type ApiPoolsRequest, type ApiPoolsResponse, type ApiRedeemRequest, type ApiRedeemResponse, type ApiTopUpRequest, type ApiTopUpResponse, 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 CombinedBalance, DefaultPolicyEngine, type DefaultPolicyEngineOptions, FeeManager, type FeeManagerConfig, type HandleMobilePrepareParams, type HandleMobilePrepareResult, type HandleMobileSubmitParams, type IIndexerCursorStore, type IPendingUserOpStore, type IPointLedger, type IPolicyEngine, type ISessionStore, InMemoryCursorStore, IssuerApiHandlers, type IssuerApiHandlersConfig, type IssuerRegistryRecord, type IssuerService, type IssuerServiceConfig, IssuerStateError, IssuerStateValidator, LockNotFoundError, type LockedMintRequest, type LoginResult, MemorySessionStore, type MemorySessionStoreOptions, type MintEvent, type MintStatusParams, type MintStatusResponse, type MintingStatus, type NativePtQuoterConfig, NonceManager, 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, PendingUserOpNotFoundError, PerpDepositError, PerpDepositHandler, type PerpDepositHandlerConfig, type PerpDepositRequest, type PerpDepositResponse, PointIndexer, type PointIndexerConfig, type PolicyDecision, type PolicyEvalRequest, type PoolsProvider, type PreValidateMintResult, type PrepareBurnDirectParams, type PrepareBurnParams, type PrepareBurnWithSigParams, type PrepareMintParams, type PrepareMobileUserOpParams, type PrepareMobileUserOpResult, type PreparedUserOp, RelayError, type RelayErrorCode, RelayService, type RelayUserOpParams, type RelayUserOpRequest, type RelayUserOpResponse, type RequestPaymasterParams, type RetryConfig, type SerializedUserOpTypedData, type Session, type SponsorshipRequest, type SponsorshipResponse, type SponsorshipTarget, type SponsorshipUserOp, type SubgraphNativeUsdtQuoterConfig, type SubgraphPoolsProviderConfig, SwapError, SwapHandler, type SwapHandlerConfig, type SwapRequest, type SwapResponse, TopUpRedemptionError, TopUpRedemptionHandler, type TopUpRedemptionHandlerConfig, type TopUpRedemptionRequest, type TopUpRedemptionResponse, authenticateRequest, createIssuerService, createNativePtQuoter, createSubgraphNativeUsdtQuoter, createSubgraphPoolsProvider, handleClaimStatus, handleMobilePrepare, handleMobileSubmit, handleRedeemStatus, mergePaymasterFields, prepareMobileUserOp, relayUserOp, requestPaymaster, serializeEntryToJsonRpc, serializeUserOpTypedData };