@pafi-dev/issuer 0.5.34 → 0.5.35

package/dist/index.d.cts

@@ -1,5 +1,5 @@
 import { Address, Hex, PublicClient, WalletClient } from 'viem';
-import { PointTokenDomainConfig, PartialUserOperation, BurnRequest, PoolKey, ENTRY_POINT_V08, 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,745 +1528,1060 @@ 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)
+ * Storage backend for pending UserOps in the mobile prepare/submit pattern.
  *
- * Assumes the PAFI subgraph schema. Issuers with a custom subgraph must
- * implement `PoolsProvider` themselves instead of using this helper.
+ * 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
  *
- * @example
- * ```ts
- * import { createSubgraphPoolsProvider, createIssuerService } from "@pafi/issuer";
+ * 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`.
  *
- * const service = createIssuerService({
- *   // ...other config
- *   poolsProvider: createSubgraphPoolsProvider({
- *     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 createSubgraphPoolsProvider(config?: SubgraphPoolsProviderConfig): PoolsProvider;
+declare function serializeEntryToJsonRpc(entry: PendingUserOpEntry, signature: Hex, variant?: "sponsored" | "fallback"): Record<string, string | null>;
 
 /**
- * Config for `createSubgraphNativeUsdtQuoter`.
+ * 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).
  */
-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;
-}
+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;
+    };
+};
 /**
- * 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.
+ * 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.
  *
- * 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.
+ * `pm_sponsorUserOperation` returns:
+ * - `paymaster` / `paymasterData` — required for the sponsored sig
+ * - `paymasterVerificationGasLimit` / `paymasterPostOpGasLimit`
+ * - **re-estimated** `callGasLimit` / `verificationGasLimit` /
+ *   `preVerificationGas` — the paymaster signature is computed over
+ *   these new values
+ * - **bundler-required** `maxFeePerGas` / `maxPriorityFeePerGas` —
+ *   Base RPC's `eth_feeHistory` underestimates, bundler rejects
  *
- * @example
- * ```ts
- * import { createSubgraphNativeUsdtQuoter, createIssuerService } from "@pafi-dev/issuer";
+ * Callers MUST re-merge ALL of these into the userOp BEFORE computing
+ * the EIP-712 userOpHash — otherwise both the paymaster signature
+ * (AA34) and the user signature (AA24, recovered against a different
+ * hash) fail at validation.
  *
- * const service = createIssuerService({
- *   // ...other config
- *   fee: {
- *     quoteNativeToFee: createSubgraphNativeUsdtQuoter({
- *       subgraphUrl: "https://graph.pacificfinance.org/subgraphs/name/pafi",
- *     }),
- *   },
- * });
- * ```
+ * Skips fields that are undefined so legacy paymaster responses
+ * (without re-estimated gas) don't accidentally zero out the original
+ * estimates.
  */
-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;
+declare function mergePaymasterFields<T extends object>(userOp: T, paymasterFields: {
+    paymaster: Address;
+    paymasterData: Hex;
+    paymasterVerificationGasLimit: bigint;
+    paymasterPostOpGasLimit: bigint;
+    callGasLimit?: bigint;
+    verificationGasLimit?: bigint;
+    preVerificationGas?: bigint;
+    maxFeePerGas?: bigint;
+    maxPriorityFeePerGas?: bigint;
+} | undefined): T;
+interface PreparedUserOp {
+    /** The bundler-ready UserOp (with paymaster + Pimlico-quoted gas). */
+    userOp: PartialUserOperation & {
+        maxFeePerGas: bigint;
+        maxPriorityFeePerGas: bigint;
+        paymaster?: Address;
+        paymasterData?: Hex;
+        paymasterVerificationGasLimit?: bigint;
+        paymasterPostOpGasLimit?: bigint;
+    };
+    /** Hex-encoded EIP-712 digest. Equals `EntryPoint.getUserOpHash`. */
+    userOpHash: Hex;
+    /** Typed-data payload — pass directly to `eth_signTypedData_v4`. */
+    typedData: SerializedUserOpTypedData;
 }
-/**
- * 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
+interface PrepareMobileUserOpParams {
+    /** Lock id (issuer-generated) keying both store entry + ledger row. */
+    lockId: string;
+    /**
+     * Sponsored variant — built with the PT operator-fee transfer
+     * included. SDK or caller should set `partialUserOp.maxFeePerGas` /
+     * `maxPriorityFeePerGas` from `provider.estimateFeesPerGas()` before
+     * calling — they get overridden by Pimlico's quote anyway, but
+     * they must be valid bigints for the merge.
+     */
+    partialUserOp: PartialUserOperation & {
+        maxFeePerGas: bigint;
+        maxPriorityFeePerGas: bigint;
+    };
+    /**
+     * Optional fee-stripped fallback variant — built with `gasFeePt: 0n`
+     * (no PT operator-fee transfer). Submitted when paymaster refuses
+     * sponsorship and the user pays ETH gas directly.
+     */
+    partialUserOpFallback?: PartialUserOperation & {
+        maxFeePerGas?: bigint;
+        maxPriorityFeePerGas?: bigint;
+    };
+    /** Paymaster sponsorship response, or `undefined` if PAFI declined. */
+    paymasterFields?: {
+        paymaster: Address;
+        paymasterData: Hex;
+        paymasterVerificationGasLimit: bigint;
+        paymasterPostOpGasLimit: bigint;
+        callGasLimit?: bigint;
+        verificationGasLimit?: bigint;
+        preVerificationGas?: bigint;
+        maxFeePerGas?: bigint;
+        maxPriorityFeePerGas?: bigint;
+    };
+    chainId: number;
+    /** Pending-userop store implementation (Redis/Postgres/Memory). */
+    store: IPendingUserOpStore;
+    /** 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;
+}
+/**
+ * Build the sponsored UserOp + (optional) fee-stripped fallback for the
+ * mobile prepare/submit flow.
  *
- * Both prices are cached in-process (default 30s TTL).
+ * 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.
  *
- * @example
- * ```ts
- * fee: {
- *   quoteNativeToFee: createNativePtQuoter({
- *     provider,
- *     pointTokenAddress: "0x...",
- *     chainlinkFeedAddress: getContractAddresses(chainId).chainlinkEthUsd,
- *   }),
- * }
- * ```
+ * Replaces ~100 LoC of glue per scenario in issuer controllers.
  */
-declare function createNativePtQuoter(config: NativePtQuoterConfig): (amountNative: bigint) => Promise<bigint>;
+declare function prepareMobileUserOp(params: PrepareMobileUserOpParams): Promise<PrepareMobileUserOpResult>;
 
 /**
- * Combined off-chain + on-chain balance for a single user / token pair.
+ * Mobile prepare/submit orchestrators — abstract the duplicate glue
+ * between `/claim/prepare`+`/claim/submit` and `/redeem/prepare`+
+ * `/redeem/submit`. Both share the same shape:
  *
- * - `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)
+ *   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.
  */
-interface CombinedBalance {
-    offChain: bigint;
-    onChain: bigint;
-    total: bigint;
+declare class PendingUserOpNotFoundError extends Error {
+    readonly code = "PENDING_USEROP_NOT_FOUND";
+    constructor(lockId: string);
 }
-interface BalanceAggregatorConfig {
+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;
-    ledger: IPointLedger;
+    /** 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;
 }
 /**
- * v1.4 utility — aggregates off-chain + on-chain point balances into a
- * single view for the "combined balance" UI in the Issuer App.
+ * 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.
  *
- * 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).
+ * 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.
  *
- * See [REQUIREMENTS_V2.md] §1 — "The Issuer App displays a combined
- * balance (off-chain points + on-chain PT) and does not surface USDT."
+ * 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 BalanceAggregator {
+declare class IssuerStateValidator {
     private readonly provider;
-    private readonly ledger;
-    constructor(config: BalanceAggregatorConfig);
+    private readonly registryAddress;
+    private readonly pointTokenIssuerCache;
+    private readonly stateCache;
+    private readonly inflight;
+    constructor(provider: PublicClient, registryAddress: Address);
     /**
-     * Combined balance for a single (user, token) pair. Fetches off-chain
-     * + on-chain in parallel.
+     * Convenience factory — reads `registryAddress` from the SDK
+     * `CONTRACT_ADDRESSES` map for the given chain.
      */
-    getCombinedBalance(user: Address, pointToken: Address): Promise<CombinedBalance>;
+    static forChain(provider: PublicClient, chainId: number): IssuerStateValidator;
     /**
-     * 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).
+     * Invalidate cached state for one PointToken, or everything if omitted.
+     * Call after admin txs that change registry or cap settings.
      */
-    getCombinedBalanceMulti(user: Address, pointTokens: Address[]): Promise<Map<Address, CombinedBalance>>;
+    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];
+
 /**
- * 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.
+ * 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 BundlerNotConfiguredError extends Error {
-    readonly code = "BUNDLER_NOT_CONFIGURED";
-    constructor();
+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);
 }
-declare class BundlerRejectedError extends Error {
-    readonly code = "BUNDLER_REJECTED";
-    readonly cause: unknown;
-    constructor(message: string, cause: unknown);
+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 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). */
+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;
     /**
-     * Function name to surface in audit / paymaster context. Defaults to
-     * a per-scenario sensible value (`mint` / `burn` / `swap` / generic
-     * scenario name).
+     * Fallback UserOp — mint only, no PT fee transfer. Present only when
+     * `feeAmount > 0`. User pays gas in ETH directly.
      */
-    functionName?: string;
-    /** Optional logger for the "sponsorship declined" warning. */
-    onWarning?: (msg: string) => void;
+    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[];
 }
-/**
- * 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 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;
-    };
+declare class PTClaimHandler {
+    private readonly cfg;
+    constructor(config: PTClaimHandlerConfig);
+    handle(request: PTClaimRequest): Promise<PTClaimResponse>;
 }
+
+type DecodedCall$1 = ReturnType<typeof decodeBatchExecuteCalls>[number];
+
 /**
- * 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.
+ * PT → USDT swap handler.
  *
- * Every issuer mobile flow has this exact wrapper — moved into SDK
- * to drop ~30 LoC of try/catch + error-shape boilerplate per
- * controller.
+ * Quotes via V4 on-chain Quoter (`findBestQuote`), applies slippage,
+ * computes the PT gas-reimbursement fee from `FeeManager`, and builds
+ * two UserOps:
  *
- * 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.).
+ *   - **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 function relayUserOp(params: RelayUserOpParams): Promise<{
-    userOpHash: Hex;
-}>;
+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];
 
 /**
- * Top-level configuration for `createIssuerService`.
+ * Orderly perp-deposit handler — builds the sponsored + fallback
+ * UserOps for the PAFI Relay path.
  *
- * 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.
+ * 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:
  *
- * **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.
+ *   - **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`).
  */
-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.
-     */
+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;
-    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;
+    /** Optional — when wired, used to estimate the PT gas-reimbursement fee. */
+    feeService?: FeeManager;
+    /** PointToken address used for the sponsored PT.transfer. */
+    pointTokenAddress: Address;
     /**
-     * Policy engine — optional, defaults to `DefaultPolicyEngine` which checks
-     * off-chain balance. Extend or replace to add KYC, volume caps, etc.
+     * 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.
      */
-    policy?: IPolicyEngine;
-    /** Session store — optional, defaults to `MemorySessionStore` (dev/test only). */
-    sessionStore?: ISessionStore;
+    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 {
     /**
-     * Fee management config. If omitted the `handleGasFee` endpoint will
-     * throw "not configured" at request time.
+     * Fully qualified subgraph GraphQL endpoint.
+     * Defaults to the PAFI-hosted subgraph (`PAFI_SUBGRAPH_URL`).
+     * Override only when pointing at a staging or custom deployment.
      */
-    fee?: Omit<FeeManagerConfig, "provider">;
+    subgraphUrl?: string;
     /**
-     * Pool discovery function for `handlePools`. If omitted the endpoint
-     * throws "not configured" at request time.
+     * 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.
      */
-    poolsProvider?: PoolsProvider;
+    cacheTtlMs?: number;
     /**
-     * Enables `handleClaim`. The factory combines these with the shared
-     * `policy` + `relayService` instances already wired by the factory.
-     * Omit to disable the `/claim` endpoint.
+     * Optional fetch override for test harnesses. Defaults to global `fetch`.
      */
-    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>;
+    fetchImpl?: typeof fetch;
     /**
-     * First indexer. Kept for backward compat with 0.1.x callers.
-     * @deprecated use `indexers.get(tokenAddress)` for multi-token.
+     * Optional clock override for tests.
      */
-    indexer: PointIndexer;
-    /** Framework-agnostic HTTP handlers — wire into Express / Fastify / Hono. */
-    api: IssuerApiHandlers;
+    now?: () => number;
 }
 /**
- * Wire a fully-functional issuer service from a single config object.
+ * Create a `PoolsProvider` backed by the PAFI subgraph.
  *
- * 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
+ * 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.
  *
- * Throws synchronously if any required field is missing.
+ * 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 createIssuerService(config: IssuerServiceConfig): IssuerService;
+declare function createSubgraphPoolsProvider(config?: SubgraphPoolsProviderConfig): PoolsProvider;
 
 /**
- * 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`.
+ * Config for `createSubgraphNativeUsdtQuoter`.
  */
-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;
+interface SubgraphNativeUsdtQuoterConfig {
     /**
-     * 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.
+     * Fully qualified subgraph GraphQL endpoint.
+     * Defaults to the PAFI-hosted subgraph (`PAFI_SUBGRAPH_URL`).
+     * Override only when pointing at a staging or custom deployment.
      */
-    fallback?: {
-        callData: Hex;
-        callGasLimit: string;
-        verificationGasLimit: string;
-        preVerificationGas: string;
-        userOpHash: Hex;
-    };
+    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;
 }
 /**
- * Storage backend for pending UserOps in the mobile prepare/submit pattern.
+ * 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.
  *
- * 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
+ * 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 default implementation in the gg56 boilerplate uses Redis with
- * a short TTL matching the MintRequest / BurnRequest deadline.
+ * 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",
+ *     }),
+ *   },
+ * });
+ * ```
  */
-interface IPendingUserOpStore {
-    save(lockId: string, entry: PendingUserOpEntry, ttlSeconds: number): Promise<void>;
-    get(lockId: string): Promise<PendingUserOpEntry | null>;
-    delete(lockId: string): Promise<void>;
-}
+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;
+}
 /**
- * Convert a stored `PendingUserOpEntry` (decimal-string fields) plus a
- * signature into the JSON-RPC wire format for `eth_sendUserOperation`.
+ * Create a native→PT quoter for use as `FeeManager.quoteNativeToFee`.
  *
- * Bridges the gap between the serialized storage format (decimal strings,
- * safe for JSON/Redis) and `serializeUserOpToJsonRpc` which expects bigints.
+ * 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 serializeEntryToJsonRpc(entry: PendingUserOpEntry, signature: Hex, variant?: "sponsored" | "fallback"): Record<string, string | null>;
+declare function createNativePtQuoter(config: NativePtQuoterConfig): (amountNative: bigint) => Promise<bigint>;
 
 /**
- * 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`.
+ * 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)
  */
-declare function serializeUserOpTypedData(td: UserOpTypedData): SerializedUserOpTypedData;
+interface CombinedBalance {
+    offChain: bigint;
+    onChain: bigint;
+    total: bigint;
+}
+interface BalanceAggregatorConfig {
+    provider: PublicClient;
+    ledger: IPointLedger;
+}
 /**
- * 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
- * - `paymasterVerificationGasLimit` / `paymasterPostOpGasLimit`
- * - **re-estimated** `callGasLimit` / `verificationGasLimit` /
- *   `preVerificationGas` — the paymaster signature is computed over
- *   these new values
- * - **bundler-required** `maxFeePerGas` / `maxPriorityFeePerGas` —
- *   Base RPC's `eth_feeHistory` underestimates, bundler rejects
+ * v1.4 utility — aggregates off-chain + on-chain point balances into a
+ * single view for the "combined balance" UI in the Issuer App.
  *
- * Callers MUST re-merge ALL of these into the userOp BEFORE computing
- * the EIP-712 userOpHash — otherwise both the paymaster signature
- * (AA34) and the user signature (AA24, recovered against a different
- * hash) fail at validation.
+ * 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).
  *
- * Skips fields that are undefined so legacy paymaster responses
- * (without re-estimated gas) don't accidentally zero out the original
- * estimates.
+ * 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 mergePaymasterFields<T extends object>(userOp: T, paymasterFields: {
-    paymaster: Address;
-    paymasterData: Hex;
-    paymasterVerificationGasLimit: bigint;
-    paymasterPostOpGasLimit: bigint;
-    callGasLimit?: bigint;
-    verificationGasLimit?: bigint;
-    preVerificationGas?: bigint;
-    maxFeePerGas?: bigint;
-    maxPriorityFeePerGas?: bigint;
-} | undefined): T;
-interface PreparedUserOp {
-    /** The bundler-ready UserOp (with paymaster + Pimlico-quoted gas). */
-    userOp: PartialUserOperation & {
-        maxFeePerGas: bigint;
-        maxPriorityFeePerGas: bigint;
-        paymaster?: Address;
-        paymasterData?: Hex;
-        paymasterVerificationGasLimit?: bigint;
-        paymasterPostOpGasLimit?: bigint;
-    };
-    /** Hex-encoded EIP-712 digest. Equals `EntryPoint.getUserOpHash`. */
-    userOpHash: Hex;
-    /** Typed-data payload — pass directly to `eth_signTypedData_v4`. */
-    typedData: SerializedUserOpTypedData;
-}
-interface PrepareMobileUserOpParams {
-    /** Lock id (issuer-generated) keying both store entry + ledger row. */
-    lockId: string;
+declare class BalanceAggregator {
+    private readonly provider;
+    private readonly ledger;
+    constructor(config: BalanceAggregatorConfig);
     /**
-     * Sponsored variant — built with the PT operator-fee transfer
-     * included. SDK or caller should set `partialUserOp.maxFeePerGas` /
-     * `maxPriorityFeePerGas` from `provider.estimateFeesPerGas()` before
-     * calling — they get overridden by Pimlico's quote anyway, but
-     * they must be valid bigints for the merge.
+     * Combined balance for a single (user, token) pair. Fetches off-chain
+     * + on-chain in parallel.
      */
-    partialUserOp: PartialUserOperation & {
-        maxFeePerGas: bigint;
-        maxPriorityFeePerGas: bigint;
-    };
+    getCombinedBalance(user: Address, pointToken: Address): Promise<CombinedBalance>;
     /**
-     * Optional fee-stripped fallback variant — built with `gasFeePt: 0n`
-     * (no PT operator-fee transfer). Submitted when paymaster refuses
-     * sponsorship and the user pays ETH gas directly.
+     * 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).
      */
-    partialUserOpFallback?: PartialUserOperation & {
-        maxFeePerGas?: bigint;
-        maxPriorityFeePerGas?: bigint;
-    };
-    /** Paymaster sponsorship response, or `undefined` if PAFI declined. */
-    paymasterFields?: {
-        paymaster: Address;
-        paymasterData: Hex;
-        paymasterVerificationGasLimit: bigint;
-        paymasterPostOpGasLimit: bigint;
-        callGasLimit?: bigint;
-        verificationGasLimit?: bigint;
-        preVerificationGas?: bigint;
-        maxFeePerGas?: bigint;
-        maxPriorityFeePerGas?: bigint;
-    };
-    chainId: number;
-    /** Pending-userop store implementation (Redis/Postgres/Memory). */
-    store: IPendingUserOpStore;
-    /** TTL the store entry should outlive — typically the MintRequest deadline. */
-    ttlSeconds: number;
+    getCombinedBalanceMulti(user: Address, pointTokens: Address[]): Promise<Map<Address, CombinedBalance>>;
 }
-interface PrepareMobileUserOpResult {
-    sponsored: PreparedUserOp;
+
+/**
+ * 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();
+}
+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;
     /**
-     * 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.
+     * Function name to surface in audit / paymaster context. Defaults to
+     * a per-scenario sensible value (`mint` / `burn` / `swap` / generic
+     * scenario name).
      */
-    fallback?: PreparedUserOp;
-    /** What got persisted into the pending-userop store. */
-    entry: PendingUserOpEntry;
+    functionName?: string;
+    /** Optional logger for the "sponsorship declined" warning. */
+    onWarning?: (msg: string) => void;
 }
 /**
- * Build the sponsored UserOp + (optional) fee-stripped fallback for the
- * mobile prepare/submit flow.
+ * Thin wrapper around `PafiBackendClient.requestSponsorship` with the
+ * "non-fatal on failure" semantics every issuer wants:
  *
- * 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.
+ * - 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 ~100 LoC of glue per scenario in issuer controllers.
+ * Replaces ~30 LoC of try/catch + scenario-to-function mapping every
+ * issuer would copy.
  */
-declare function prepareMobileUserOp(params: PrepareMobileUserOpParams): Promise<PrepareMobileUserOpResult>;
-
-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;
+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;
+    };
 }
 /**
- * Thrown by `IssuerStateValidator.preValidateMint()`.
- * `code` maps 1:1 to the HTTP error the issuer API surfaces to clients.
+ * 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 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 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, BundlerNotConfiguredError, BundlerRejectedError, 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 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, TopUpRedemptionError, TopUpRedemptionHandler, type TopUpRedemptionHandlerConfig, type TopUpRedemptionRequest, type TopUpRedemptionResponse, authenticateRequest, createIssuerService, createNativePtQuoter, createSubgraphNativeUsdtQuoter, createSubgraphPoolsProvider, handleClaimStatus, handleRedeemStatus, mergePaymasterFields, prepareMobileUserOp, relayUserOp, requestPaymaster, 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 };