@pafi-dev/issuer 0.35.0 → 0.36.0

package/dist/index.d.cts

@@ -0,0 +1,4093 @@
+import { PafiSdkError, SdkErrorHttpStatus, PointTokenDomainConfig, PartialUserOperation, BurnRequest, PoolKey, RedemptionPolicy, RedemptionPolicySource, RedemptionPreview, RedemptionDecision, RedemptionDenialCode, UserOpTypedData, decodeBatchExecuteCalls, BROKER_HASHES, PafiErrorType, BuiltSponsorAuth, ENTRY_POINT_V08 } from '@pafi-dev/core';
+export { PAFI_SUBGRAPH_URL, PafiErrorType, PafiSdkError, SDK_ERROR_HTTP_STATUS_CODE, SdkErrorHttpStatus, ValidationError, defaultErrorTypeForStatus } from '@pafi-dev/core';
+export { GenericHttpExceptionDescriptor, NormalizeContext, PafiErrorEnvelope, PafiErrorPayload, buildErrorEnvelope, payloadFromGenericError, payloadFromHttpException, payloadFromPafiSdkError } from './http/index.cjs';
+import { Address, Hex, PublicClient, WalletClient } from 'viem';
+
+/**
+ * `PafiSdkError` + `SdkErrorHttpStatus` are exported from
+ * `@pafi-dev/core/errors` so core-level errors (e.g. `OracleStaleError`)
+ * can extend the same base. Issuer re-exports the canonical types here
+ * for back-compat — `instanceof PafiSdkError` from EITHER package
+ * catches errors thrown from EITHER package.
+ */
+
+/**
+ * Issuer wired the SDK without a dependency the requested endpoint
+ * needs (e.g. `/gas-fee` called but `feeManager` not configured;
+ * `/pools` called but `poolsProvider` not configured). 503 because
+ * the endpoint genuinely can't serve the request — caller's payload
+ * is fine, the issuer's deployment is incomplete.
+ */
+declare class ConfigurationError extends PafiSdkError {
+    readonly httpStatus: "service_unavailable";
+    readonly code: string;
+    readonly details?: Record<string, unknown>;
+    constructor(code: string, message: string, details?: Record<string, unknown>);
+}
+
+/**
+ * Lifecycle of a minting request as tracked by the issuer's point ledger.
+ *
+ *   PENDING ── on-chain mint confirmed ──▶ MINTED
+ *      │
+ *      ├── deadline elapsed without mint ─▶ EXPIRED
+ *      │
+ *      └── tx reverted / cancelled ──────▶ FAILED
+ */
+type MintingStatus = "PENDING" | "MINTED" | "EXPIRED" | "FAILED";
+/** A locked-amount entry tracking an in-flight mint request. */
+interface LockedMintRequest {
+    /** Opaque lock id (used to release / update later) */
+    lockId: string;
+    userAddress: Address;
+    amount: bigint;
+    /**
+     * Which PointToken this lock belongs to. Added in 0.2.0 for multi-token
+     * issuer support. Optional for backward compat with 0.1.x ledgers —
+     * single-token consumers can ignore it.
+     */
+    tokenAddress?: Address;
+    /** Lifecycle status */
+    status: MintingStatus;
+    /** When the lock was created (epoch ms) */
+    createdAt: number;
+    /** When the lock auto-expires if not resolved (epoch ms) */
+    expiresAt: number;
+    /** On-chain transaction hash, set once the mint is confirmed */
+    txHash?: Hex;
+    /**
+     * ERC-4337 userOpHash returned by the bundler at submit time. Bound
+     * to the lock by `bindMintUserOpHash` so status endpoints can poll
+     * the bundler receipt directly — bypasses `PointIndexer`'s
+     * amount-based matching, which races when several PENDING locks
+     * share the same amount.
+     */
+    userOpHash?: Hex;
+}
+/** A pending off-chain credit (burn → credit reverse flow). */
+interface PendingCredit {
+    lockId: string;
+    userAddress: Address;
+    amount: bigint;
+    tokenAddress?: Address;
+    status: "PENDING" | "RESOLVED" | "EXPIRED";
+    createdAt: number;
+    expiresAt: number;
+    txHash?: Hex;
+    resolvedAt?: number;
+    /** Bundler-returned userOpHash. See `LockedMintRequest.userOpHash`. */
+    userOpHash?: Hex;
+}
+/**
+ * Issuer point ledger interface — the source of truth for off-chain user
+ * point balances and in-flight minting requests.
+ *
+ * Issuers replace the in-memory default with their own database-backed
+ * implementation (Postgres, Redis, etc.).
+ *
+ * **Multi-token support (0.2.0):**
+ * Every mutating method accepts an optional `tokenAddress` parameter so
+ * balances can be scoped per `(user, token)`. Single-token issuers can
+ * ignore the parameter entirely — legacy 0.1.x implementations remain
+ * compatible. Multi-token issuers must persist + query balances keyed by
+ * `(userAddress, tokenAddress)`.
+ */
+interface IPointLedger {
+    /** Get a user's available off-chain point balance (excluding locked). */
+    getBalance(userAddress: Address, tokenAddress?: Address): Promise<bigint>;
+    /**
+     * Lock an amount for a pending mint request. Locked amounts are reserved
+     * but not yet deducted; they protect against double-spend during the
+     * EIP-712 validity window.
+     *
+     * @param lockDurationMs how long the lock should be held before auto-expiry
+     * @param tokenAddress which PointToken this lock is for (0.2.0+)
+     * @returns lockId — opaque handle used by `releaseLock` / `updateMintStatus`
+     * @throws if the user's available balance is below `amount`
+     */
+    lockForMinting(userAddress: Address, amount: bigint, lockDurationMs: number, tokenAddress?: Address): Promise<string>;
+    /** Release a previously created lock (e.g. on tx failure / cancel). */
+    releaseLock(lockId: string): Promise<void>;
+    /** Deduct balance after a confirmed on-chain mint. Idempotent on `txHash`. */
+    deductBalance(userAddress: Address, amount: bigint, txHash: Hex, tokenAddress?: Address): Promise<void>;
+    /** Credit points to a user's balance (e.g. from merchant activity). */
+    creditBalance(userAddress: Address, amount: bigint, reason: string, tokenAddress?: Address): Promise<void>;
+    /** List currently-pending locked mint requests for a user. */
+    getLockedRequests(userAddress: Address, tokenAddress?: Address): Promise<LockedMintRequest[]>;
+    /**
+     * Transition a lock from `PENDING` to a terminal status
+     * (`MINTED` | `EXPIRED` | `FAILED`). The on-chain tx hash is
+     * supplied when the status is `MINTED`.
+     *
+     * Terminal states are immutable: once a lock leaves `PENDING` the
+     * status is fixed. Calling `updateMintStatus` on a non-PENDING lock
+     * is a silent no-op. This protects against late-arriving writes from
+     * different code paths (e.g. PointIndexer.finalize and the bundler-
+     * receipt fallback in statusHandlers) racing to overwrite each
+     * other — particularly the case where a stale `EXPIRED`/`FAILED`
+     * write would corrupt a `MINTED` lock whose balance has already
+     * been deducted.
+     */
+    updateMintStatus(lockId: string, status: MintingStatus, txHash?: Hex): Promise<void>;
+    /**
+     * Reserve a pending off-chain credit before the burn tx is submitted.
+     *
+     * Returns a lockId that the burn indexer uses to correlate the
+     * on-chain burn event back to this credit request.
+     *
+     * Throws if the ledger doesn't support the reverse flow (legacy
+     * implementations) — callers should catch and fall back.
+     */
+    reservePendingCredit?(userAddress: Address, amount: bigint, durationMs: number, tokenAddress?: Address): Promise<string>;
+    /**
+     * Finalize a reserved credit when the on-chain Burn event is seen by
+     * the BurnIndexer. Idempotent — safe to call multiple times with the
+     * same txHash (no double-credit).
+     *
+     * Throws if the lockId is unknown or already resolved.
+     */
+    resolveCreditByBurnTx?(lockId: string, txHash: Hex): Promise<void>;
+    /**
+     * Persist the bundler-returned userOpHash for a mint lock at
+     * submit time. Called once per `/claim/submit` after the bundler
+     * accepts the UserOp.
+     */
+    bindMintUserOpHash?(lockId: string, userOpHash: Hex): Promise<void>;
+    /**
+     * Persist the bundler-returned userOpHash for a pending credit at
+     * `/redeem/submit` time.
+     */
+    bindCreditUserOpHash?(lockId: string, userOpHash: Hex): Promise<void>;
+    /**
+     * Look up a mint lock by id. Returns `null` if the lock doesn't
+     * exist or doesn't belong to the supplied user (when provided).
+     * Used by `handleClaimStatus` for status polling. OPTIONAL — when
+     * absent, callers must implement status endpoints themselves.
+     */
+    getMintLock?(lockId: string, userAddress?: Address): Promise<LockedMintRequest | null>;
+    /**
+     * Look up a pending credit by id. Symmetric counterpart of
+     * `getMintLock` for the burn/redeem flow.
+     */
+    getPendingCredit?(lockId: string, userAddress?: Address): Promise<PendingCredit | null>;
+}
+
+/**
+ * Input to a policy evaluation. Policy engines use this to decide whether
+ * a user's mint request should be approved.
+ */
+interface PolicyEvalRequest {
+    userAddress: Address;
+    amount: bigint;
+    pointTokenAddress: Address;
+    chainId: number;
+}
+/** Outcome of a policy evaluation. */
+interface PolicyDecision {
+    approved: boolean;
+    /**
+     * Human-readable reason for rejection (empty on approval). Callers surface
+     * this back to the user, so keep it short and non-leaky.
+     */
+    reason?: string;
+}
+/**
+ * Policy engine — evaluates whether a minting request passes issuer rules.
+ * Issuers extend the default implementation to add KYC, volume caps, claim
+ * budgets, etc.
+ */
+interface IPolicyEngine {
+    evaluate(request: PolicyEvalRequest): Promise<PolicyDecision>;
+}
+
+/**
+ * Options for constructing a DefaultPolicyEngine.
+ *
+ * `mintingOracleAddress` and `provider` are optional — if omitted, the
+ * engine skips the on-chain cap check (useful for dev/testing).
+ *
+ * `verifyMintCap` is injectable so tests can simulate cap rejections
+ * without needing a real contract.
+ */
+interface DefaultPolicyEngineOptions {
+    ledger: IPointLedger;
+    provider?: PublicClient;
+    mintingOracleAddress?: Address;
+    /**
+     * Override the on-chain cap check. Defaults to `@pafi-dev/core`'s
+     * `verifyMintCap`, which reverts if the issuer's declared supply would
+     * be exceeded. A rejected check should throw; returning normally is pass.
+     */
+    verifyMintCap?: (client: PublicClient, oracle: Address, issuer: Address, amount: bigint) => Promise<void>;
+    /**
+     * Resolve a point-token address to the issuer address for the cap check.
+     * Required iff `mintingOracleAddress + provider` are supplied.
+     */
+    resolveIssuer?: (pointToken: Address) => Promise<Address>;
+}
+/**
+ * Default policy engine — performs two checks:
+ *
+ *  1. **Off-chain balance** — the user must have at least `amount` of
+ *     unlocked point balance in the issuer ledger.
+ *  2. **On-chain cap** — (optional) calls the MintingOracle via
+ *     `verifyMintCap` to confirm that minting this amount would not exceed
+ *     the issuer's declared total supply.
+ *
+ * Issuers extend this class (or implement `IPolicyEngine` directly) to add
+ * KYC, volume caps, claim budgets, or anti-abuse rules.
+ */
+declare class DefaultPolicyEngine implements IPolicyEngine {
+    private readonly ledger;
+    private readonly provider?;
+    private readonly mintingOracleAddress?;
+    private readonly verifyMintCap?;
+    private readonly resolveIssuer?;
+    constructor(opts: DefaultPolicyEngineOptions);
+    evaluate(request: PolicyEvalRequest): Promise<PolicyDecision>;
+}
+
+/**
+ * A server-issued session created after a successful wallet login. The
+ * token id is embedded in the JWT so sessions can be revoked without
+ * invalidating the JWT signing key.
+ */
+interface Session {
+    tokenId: string;
+    userAddress: Address;
+    chainId: number;
+    issuedAt: Date;
+    expiresAt: Date;
+}
+/**
+ * Backend store for login nonces and active sessions.
+ *
+ * The default in-memory implementation is fine for local development but
+ * production issuers should plug in Redis / a SQL table so sessions
+ * survive restarts and are visible across replicas.
+ */
+interface ISessionStore {
+    /**
+     * Create a single-use login nonce and return it to the caller. Consumers
+     * must call {@link consumeNonce} exactly once when the client returns a
+     * signed login message quoting this nonce.
+     */
+    createNonce(): Promise<string>;
+    /**
+     * Atomically validate + consume a login nonce. Returns `true` if the
+     * nonce was known and unexpired (and is now removed); `false` otherwise.
+     */
+    consumeNonce(nonce: string): Promise<boolean>;
+    /** Persist a newly issued session. */
+    createSession(session: Session): Promise<void>;
+    /** Look up a session by token id, or `null` if unknown / revoked / expired. */
+    getSession(tokenId: string): Promise<Session | null>;
+    /** Revoke a session by token id (logout). No-op if not found. */
+    revokeSession(tokenId: string): Promise<void>;
+    /**
+     * Revoke every session for a user address. Used when an issuer needs to
+     * force re-login (e.g. after a permissions change or suspected abuse).
+     */
+    revokeAllSessions(userAddress: Address): Promise<void>;
+}
+
+interface MemorySessionStoreOptions {
+    /**
+     * How long a login nonce is valid before auto-expiry. Defaults to 5 min,
+     * matching typical SIWE recommendations.
+     */
+    nonceTtlMs?: number;
+    /** Clock override for tests. */
+    now?: () => number;
+    /**
+     * Bypass the production-safety guard. By default, instantiating
+     * `MemorySessionStore` when `process.env.NODE_ENV === "production"`
+     * THROWS — multi-pod K8s deploys do not share Map state, so sessions
+     * are not revocable across replicas, and tokens remain valid on pod
+     * B after `logout` on pod A. Only set this `true` for single-pod
+     * deployments where you've consciously accepted the trade-off.
+     */
+    dangerouslyAllowMemoryStoreInProduction?: boolean;
+}
+/**
+ * In-memory `ISessionStore` — Map-backed nonces and sessions with lazy
+ * expiry sweeps on every read/write.
+ *
+ * Not safe across processes or restarts; intended for dev/test only.
+ */
+declare class MemorySessionStore implements ISessionStore {
+    private nonces;
+    private sessions;
+    private readonly nonceTtlMs;
+    private readonly now;
+    constructor(opts?: MemorySessionStoreOptions);
+    createNonce(): Promise<string>;
+    consumeNonce(nonce: string): Promise<boolean>;
+    createSession(session: Session): Promise<void>;
+    getSession(tokenId: string): Promise<Session | null>;
+    revokeSession(tokenId: string): Promise<void>;
+    revokeAllSessions(userAddress: Address): Promise<void>;
+    private purgeExpiredNonces;
+    private purgeExpiredSessions;
+}
+
+/**
+ * Thin wrapper around an `ISessionStore` exposing nonce generation and
+ * single-use consumption as its own named surface. AuthService uses it
+ * internally, and issuers can also use it directly for other flows that
+ * need replay protection (e.g. a CSRF-style challenge).
+ */
+declare class NonceManager {
+    private readonly store;
+    constructor(store: ISessionStore);
+    /** Generate a fresh login nonce. The store is responsible for TTL. */
+    generate(): Promise<string>;
+    /**
+     * Atomically validate + consume a nonce. Returns `true` iff the nonce
+     * was known and unexpired (and is now removed from the store).
+     */
+    consume(nonce: string): Promise<boolean>;
+}
+
+interface AuthServiceConfig {
+    sessionStore: ISessionStore;
+    /** HMAC secret for signing JWTs (HS256). At least 32 bytes recommended. */
+    jwtSecret: string;
+    /**
+     * JWT lifetime passed to `jose`. Accepts any of `jose`'s time strings
+     * (`"24h"`, `"7d"`, `"45m"`, …). Defaults to `"24h"`.
+     */
+    jwtExpiresIn?: string;
+    /**
+     * Expected domain in the login message, e.g. `"app.example.com"`. The
+     * SIWE spec requires the frontend to build the message with this exact
+     * domain; the backend rejects any mismatch.
+     */
+    domain: string;
+    /** Expected chain id. */
+    chainId: number;
+    /**
+     * Optional `iss` (issuer) claim baked into JWTs and validated on
+     * verify. Recommended for multi-issuer deployments to prevent
+     * cross-validation if a JWT secret is accidentally shared. Examples:
+     * `"gg56-issuer"`, `"issuer.gg56.com"`. When unset, no `iss` is
+     * written or required (back-compat).
+     */
+    issuer?: string;
+    /**
+     * Optional `aud` (audience) claim baked into JWTs and validated on
+     * verify. Recommended to bind tokens to a specific consumer, e.g.
+     * `"gg56-mobile"` or `"gg56-web"`. When unset, no `aud` is written
+     * or required (back-compat).
+     */
+    audience?: string;
+    /** Clock override for tests. */
+    now?: () => Date;
+}
+interface LoginResult {
+    token: string;
+    userAddress: Address;
+    tokenId: string;
+    expiresAt: Date;
+}
+interface AuthContext {
+    userAddress: Address;
+    chainId: number;
+    tokenId: string;
+}
+/**
+ * Wallet-based authentication service implementing the EIP-4361 (Sign-In
+ * With Ethereum) login flow with server-issued JWTs.
+ *
+ * Flow:
+ *   1. `getNonce()` — client fetches a nonce, stores it locally
+ *   2. Client constructs a login message with the nonce + signs with wallet
+ *   3. `login(message, signature)` — server validates fields + signature,
+ *      consumes the nonce, persists a session, returns a JWT
+ *   4. Protected endpoints call `verifyToken(token)` to resolve the user
+ *      context; the session is re-checked on every call, so `logout()`
+ *      revokes access immediately.
+ */
+declare class AuthService {
+    private readonly sessionStore;
+    private readonly jwtSecret;
+    private readonly jwtExpiresIn;
+    private readonly domain;
+    private readonly chainId;
+    private readonly issuer?;
+    private readonly audience?;
+    private readonly nonceManager;
+    private readonly now;
+    constructor(config: AuthServiceConfig);
+    /** Generate a fresh login nonce. */
+    getNonce(): Promise<string>;
+    /**
+     * Verify a signed login message and issue a JWT on success.
+     * Throws an `AuthError` on any validation failure.
+     */
+    login(message: string, signature: Hex): Promise<LoginResult>;
+    /** Revoke the session backing the given JWT (logout). */
+    logout(token: string): Promise<void>;
+    private logSessionStoreError;
+    /**
+     * Verify a JWT and return the authenticated user context. Throws an
+     * `AuthError` if the token is missing, malformed, expired, revoked, or
+     * signed by a different key.
+     */
+    verifyToken(token: string): Promise<AuthContext>;
+}
+
+/**
+ * Extracts a Bearer token from an `Authorization` header value and verifies
+ * it via the supplied `AuthService`. Framework-agnostic — issuers wrap this
+ * in their framework's middleware pattern (Express, Fastify, Hono, …).
+ *
+ * Throws an `AuthError` if the header is missing, malformed, or the token
+ * fails verification. Callers should translate the `err.code` into an
+ * appropriate HTTP status (401 for auth failures, 500 for anything else).
+ */
+declare function authenticateRequest(authHeader: string | undefined, authService: AuthService): Promise<AuthContext>;
+
+/**
+ * Error codes surfaced by the auth subsystem. Issuers can pattern-match on
+ * `err.code` to translate into framework-specific HTTP responses.
+ */
+type AuthErrorCode = "INVALID_MESSAGE" | "DOMAIN_MISMATCH" | "CHAIN_MISMATCH" | "NONCE_INVALID" | "MESSAGE_EXPIRED" | "MESSAGE_NOT_YET_VALID" | "SIGNATURE_INVALID" | "MISSING_TOKEN" | "MALFORMED_TOKEN" | "TOKEN_INVALID" | "TOKEN_EXPIRED" | "SESSION_REVOKED";
+/**
+ * Extends `PafiSdkError` so issuer controllers can route auth failures
+ * through the same `createSdkErrorMapper` as everything else (no
+ * separate `instanceof AuthError` check needed).
+ */
+declare class AuthError extends PafiSdkError {
+    readonly code: AuthErrorCode;
+    readonly httpStatus: SdkErrorHttpStatus;
+    constructor(code: AuthErrorCode, message: string);
+}
+
+/**
+ * Per-key rate limiting for unauthenticated public endpoints.
+ *
+ * `/auth/nonce` and `/auth/login` are unauthenticated and CPU-bound
+ * (SIWE message parsing + ECDSA `recover`), so without rate limiting
+ * an attacker can saturate the issuer at low cost. Worse, on
+ * `/auth/nonce` they can flood the session store with single-use
+ * nonces; with `MemorySessionStore` this is a pure DoS.
+ *
+ * Issuers wire a `IRateLimiter` impl in `IssuerApiHandlersConfig` —
+ * `MemoryRateLimiter` is the default reference impl (single-pod, dev).
+ * Production deployments use a Redis-backed impl that shares state
+ * across replicas (similar pattern to `ISessionStore`).
+ *
+ * The "key" is up to the caller — typically the client IP, but the
+ * issuer's HTTP layer chooses (could be userAddress on POST /login).
+ */
+interface IRateLimiter {
+    /**
+     * Check + increment a counter under `key`. Returns `{ allowed: false,
+     * retryAfterMs }` when the caller has exceeded its quota for this
+     * window. Default config is action-specific (see
+     * `RateLimiterConfig`).
+     *
+     * Idempotent in the sense that successive calls with the same `key`
+     * within the same window count toward the limit; a separate window
+     * starts after `windowMs` elapses.
+     */
+    consume(key: string, action: RateLimitAction): Promise<{
+        allowed: boolean;
+        retryAfterMs?: number;
+    }>;
+}
+type RateLimitAction = "auth_nonce" | "auth_login";
+interface RateLimiterConfig {
+    /**
+     * Per-key max requests per `windowMs`. Defaults:
+     *   - auth_nonce:  1 per 2s (30/min)
+     *   - auth_login:  5 per minute
+     *
+     * Issuers can tune per their threat model.
+     */
+    limits?: Partial<Record<RateLimitAction, {
+        max: number;
+        windowMs: number;
+    }>>;
+    /** Clock override for tests. */
+    now?: () => number;
+}
+/**
+ * In-memory `IRateLimiter` — Map of `{key, action}` → count + window
+ * start. Lazy expiry on read. Single-process: NOT safe for multi-pod
+ * deployments. Use a Redis impl in production.
+ */
+declare class MemoryRateLimiter implements IRateLimiter {
+    private buckets;
+    private readonly limits;
+    private readonly now;
+    constructor(config?: RateLimiterConfig);
+    consume(key: string, action: RateLimitAction): Promise<{
+        allowed: boolean;
+        retryAfterMs?: number;
+    }>;
+    /**
+     * Test helper — clear all buckets. Not part of `IRateLimiter`; only
+     * exposed on the in-memory impl for unit tests.
+     */
+    reset(): void;
+}
+/**
+ * Convenience: a no-op `IRateLimiter` that lets every request through.
+ * Useful as a default in `IssuerApiHandlersConfig` when the issuer
+ * hasn't wired a rate limiter yet (back-compat) — emits a one-time
+ * warning at construction so consumers notice.
+ */
+declare class NoopRateLimiter implements IRateLimiter {
+    private warned;
+    consume(): Promise<{
+        allowed: boolean;
+    }>;
+}
+
+type RelayErrorCode = "ENCODE_FAILED";
+declare class RelayError extends PafiSdkError {
+    readonly httpStatus: "unprocessable";
+    readonly code: RelayErrorCode;
+    constructor(code: RelayErrorCode, message: string, cause?: unknown);
+}
+
+/**
+ * Optional config that lets `RelayService` auto-quote the operator fee
+ * + auto-resolve the recipient when callers don't pass `feeAmount` /
+ * `feeRecipient`. When both `provider` + `chainId` are set, callers can
+ * omit the fee params entirely; the service will:
+ *
+ *  1. Resolve `feeRecipient = getContractAddresses(chainId).pafiFeeRecipient`
+ *  2. If `feeAmount` is undefined → run `quoteOperatorFeePt(...)` against
+ *     Chainlink + PAFI subgraph to compute the PT amount.
+ *
+ * When unset, the legacy "caller passes feeAmount + feeRecipient or no
+ * fee" behavior applies, so existing integrations keep working.
+ */
+interface RelayServiceConfig {
+    provider?: PublicClient;
+    chainId?: number;
+}
+/**
+ * Builds unsigned `PartialUserOperation` payloads for the sponsored
+ * flow. The service is stateless and HTTP-client-free:
+ *
+ *   - `prepareMint` signs a `MintRequest` EIP-712 with the caller-supplied
+ *     issuer signer wallet, then encodes `PointToken.mint(to, amount,
+ *     deadline, minterSig)` into a UserOp the frontend submits via
+ *     EIP-7702 + Paymaster.
+ *   - `prepareBurn` mirrors the above on the burn side using a
+ *     pre-signed `BurnRequest` + `PointToken.burn(from, amount,
+ *     deadline, burnerSig)`.
+ *
+ * There is no broadcasting, no operator wallet, no simulation — those
+ * concerns live in the Bundler + Paymaster.
+ */
+declare class RelayService {
+    private readonly provider;
+    private readonly chainId;
+    constructor(config?: RelayServiceConfig);
+    /**
+     * Resolve the fee recipient + amount applied to the next UserOp:
+     *
+     *  - If caller passed an explicit `feeRecipient`, use it (testing
+     *    only — sponsor-relayer's L1 will reject any non-canonical
+     *    recipient with `INSUFFICIENT_FEE`). Otherwise, default to
+     *    `getContractAddresses(chainId).pafiFeeRecipient` when the
+     *    service has a `chainId` configured.
+     *  - If caller passed `feeAmount`, use it. Otherwise, when the
+     *    service has both `provider` + `chainId`, auto-quote via
+     *    `quoteOperatorFeePt`.
+     *  - When the service is unconfigured AND caller passed nothing,
+     *    return `{ feeAmount: 0n, feeRecipient: undefined }` — legacy
+     *    "no fee" behavior, caller must opt in for the gas-reimbursement
+     *    transfer to be added to the batch.
+     */
+    private resolveFee;
+    /**
+     * Build an unsigned UserOp for Scenario 1 (Mint) — sig-gated
+     * `PointToken.mint(to, amount, deadline, minterSig)`.
+     */
+    prepareMint(params: PrepareMintParams): Promise<PartialUserOperation>;
+    /**
+     * Build an unsigned UserOp for Scenario 2 (Burn/Redeem) — sig-gated
+     * `PointToken.burn(from, amount, deadline, burnerSig)`. Caller
+     * provides a pre-signed `BurnRequest` + sig bytes (typically from
+     * `PTRedeemHandler`).
+     *
+     * Direct burn (no sig) is not used — every burn goes through the
+     * issuer-signed `BurnRequest` path.
+     */
+    prepareBurn(params: PrepareBurnParams): Promise<PartialUserOperation>;
+    /**
+     * Build a dummy `PartialUserOperation` for the mint scenario, suitable
+     * for `feeManager.estimateGasFee({ partialUserOp, ... })`. NO signing —
+     * uses a 65-byte zero signature placeholder.
+     */
+    previewMintUserOp(params: PreviewMintParams): PartialUserOperation;
+    /** Burn-side mirror of `previewMintUserOp`. */
+    previewBurnUserOp(params: PreviewBurnParams): PartialUserOperation;
+}
+/**
+ * Inputs for `previewMintUserOp` — strict subset of `PrepareMintParams`
+ * that excludes the signing wallet, EIP-712 domain, and on-chain
+ * `mintRequestNonces` lookup since those don't affect calldata shape
+ * (the bundler estimate is shape-invariant under their values).
+ */
+interface PreviewMintParams {
+    userAddress: Address;
+    aaNonce: bigint;
+    pointTokenAddress: Address;
+    amount: bigint;
+    deadline: bigint;
+    mintFeeWrapperAddress?: Address;
+}
+interface PreviewBurnParams {
+    userAddress: Address;
+    aaNonce: bigint;
+    pointTokenAddress: Address;
+    amount: bigint;
+    deadline: bigint;
+}
+/**
+ * Sig-gated `PointToken.mint(to, amount, deadline, minterSig)`.
+ *
+ * The issuer backend validates off-chain (balance, policy, KYC), signs
+ * a `MintRequest` EIP-712 with its minter signer, and packages the
+ * whole thing into a UserOp for the user to submit via EIP-7702 +
+ * Paymaster. On confirmation, PointIndexer watches `Transfer(0x0, user,
+ * amount)` and resolves the ledger lock.
+ */
+interface PrepareMintParams {
+    /** User EOA that will send the UserOp (via EIP-7702 delegation). */
+    userAddress: Address;
+    /** ERC-4337 account nonce. Caller fetches from EntryPoint v0.7. */
+    aaNonce: bigint;
+    /** BatchExecutor delegation target (chain-specific). */
+    batchExecutorAddress: Address;
+    /** PointToken contract — the call target + EIP-712 verifying contract. */
+    pointTokenAddress: Address;
+    /** PT amount to mint to `userAddress`. */
+    amount: bigint;
+    /**
+     * Issuer minter signer wallet — signs the `MintRequest` EIP-712.
+     * Must be added to `PointToken.minters[]` via `addMinter(signerAddr)`
+     * at provisioning time. Typically HSM/KMS-backed in prod.
+     */
+    issuerSignerWallet: WalletClient;
+    /** EIP-712 domain for MintRequest. */
+    domain: PointTokenDomainConfig;
+    /** Current `mintRequestNonces[userAddress]` — caller reads from contract. */
+    mintRequestNonce: bigint;
+    /** Unix timestamp after which the signature expires. */
+    deadline: bigint;
+    /**
+     * Optional — when set, mint is routed through MintFeeWrapper:
+     *   - sig.receiver = wrapper address (vs `userAddress` for direct path)
+     *   - calldata target = wrapper.mintWithFee(pointToken, user, gross, ...)
+     *   - the wrapper then mints `amount` to itself, splits per recipient list,
+     *     and forwards net to the user.
+     *
+     * Leave undefined for direct-mint behavior (no fee skim). Wrapper
+     * must be registered on the PointToken via `IssuerRegistry.addIssuer`
+     * cascade (or owner-only `wrapper.registerToken`) before this path
+     * works on-chain.
+     */
+    mintFeeWrapperAddress?: Address;
+    /**
+     * Optional — application-level fee transfer appended after mint.
+     * Set both `feeAmount` and `feeRecipient` together.
+     */
+    feeAmount?: bigint;
+    feeRecipient?: Address;
+    /** Gas limits — defaults are conservative; caller can tighten. */
+    callGasLimit?: bigint;
+    verificationGasLimit?: bigint;
+    preVerificationGas?: bigint;
+}
+/**
+ * Sig-gated burn only — every burn goes through `BurnRequest` EIP-712
+ * signed by the issuer burner. The `mode: 'burnWithSig'` discriminant
+ * is preserved for backwards-compat with existing callers but is no
+ * longer branched on internally.
+ */
+interface PrepareBurnParams {
+    userAddress: Address;
+    aaNonce: bigint;
+    pointTokenAddress: Address;
+    batchExecutorAddress: Address;
+    /** Discriminant kept for backwards compat. Always `'burnWithSig'`. */
+    mode?: "burnWithSig";
+    /** BurnRequest message the issuer burner signer signed. */
+    burnRequest: BurnRequest;
+    /** Serialized EIP-712 signature (bytes) over `burnRequest`. */
+    burnerSignature: Hex;
+    /**
+     * Optional — application-level PT fee transfer appended after burn.
+     * Used for gas reimbursement on the sponsored path. Set both
+     * `feeAmount` and `feeRecipient` together. User must hold
+     * `burnAmount + feeAmount` PT.
+     */
+    feeAmount?: bigint;
+    feeRecipient?: Address;
+    callGasLimit?: bigint;
+    verificationGasLimit?: bigint;
+    preVerificationGas?: bigint;
+}
+
+/**
+ * Caller-supplied fetch implementation, matching the WHATWG Fetch API
+ * shape. Defaults to `globalThis.fetch` when omitted; tests and
+ * non-browser/node environments can plug in their own.
+ */
+type FetchImpl = (input: string, init?: RequestInit) => Promise<Response>;
+/**
+ * Duck-typed estimator interface. `FeeManager` accepts any object
+ * satisfying this surface so the SDK stays decoupled from where the
+ * bundler estimate physically lives (PAFI sponsor-relayer in production,
+ * a mock in tests, a local Pimlico proxy in dev).
+ *
+ * The estimator's job: given the preview UserOp shape, return the gas
+ * units to multiply by `gasPrice` and feed into the caller's fee
+ * quoter. Premium and PM overhead are the estimator's responsibility,
+ * NOT the SDK's — preventing double-padding.
+ */
+interface BundlerEstimatorClient {
+    /**
+     * Resolve gas units for a sponsored UserOp.
+     *
+     * @throws — implementations should throw on transport / auth /
+     *   protocol errors so `FeeManager` can degrade to its hardcoded
+     *   fallback. Network failures must NOT silently return a default,
+     *   since that would mask a misconfiguration as a successful estimate.
+     */
+    getGasUnits(input: {
+        scenario: string;
+        contractAddress: Address;
+        paymasterAddress?: Address;
+        partialUserOp: {
+            sender: Address;
+            nonce: bigint;
+            callData: Hex;
+            signature?: Hex;
+        };
+    }): Promise<{
+        gasUnits: bigint;
+        source: "cache" | "bundler" | "fallback";
+        expiresAt: number;
+    }>;
+}
+interface PafiEstimatorClientConfig {
+    /**
+     * Base URL of the PAFI sponsor-relayer (no trailing slash). The
+     * adapter appends `/v1/estimate-gas-fee` — issuer infrastructure
+     * never talks to Pimlico directly.
+     */
+    baseUrl: string;
+    /** Issuer's PAFI API key — the same one used for `/paymaster/sponsor`. */
+    apiKey: string;
+    /** Issuer ID used in `X-Issuer-Id` header. */
+    issuerId: string;
+    /** Custom fetch (e.g. `undici` in tests). Defaults to `globalThis.fetch`. */
+    fetchImpl?: FetchImpl;
+}
+declare class PafiEstimatorHttpError extends Error {
+    readonly status: number;
+    readonly body: unknown;
+    constructor(status: number, body: unknown, message?: string);
+}
+/**
+ * HTTP adapter that hits PAFI sponsor-relayer's `/v1/estimate-gas-fee`
+ * endpoint. The SDK never imports Pimlico-specific code or holds the
+ * Pimlico API key — the bundler call happens server-side at PAFI.
+ *
+ * Authentication mirrors `/paymaster/sponsor`:
+ *   - `Authorization: Bearer <apiKey>`
+ *   - `X-Issuer-Id: <issuerId>`
+ *
+ * Issuers wire this once at boot via `createPafiEstimatorClient({
+ * baseUrl, apiKey, issuerId })` and pass it to `FeeManager` as
+ * `bundlerClient`. The same `baseUrl`/`apiKey`/`issuerId` already
+ * authenticate other PAFI calls — no new secrets required.
+ */
+declare function createPafiEstimatorClient(config: PafiEstimatorClientConfig): BundlerEstimatorClient;
+
+type GasFeeSource = "estimator" | "fallback" | "cached-fee";
+/**
+ * Hooks for observability. Sync, best-effort — errors thrown by hooks
+ * are swallowed so they cannot break the user-facing fee flow.
+ */
+interface FeeManagerMetrics {
+    onEstimate?: (info: {
+        source: GasFeeSource;
+        scenario?: string;
+        gasUnits: bigint;
+        latencyMs: number;
+    }) => void;
+    onEstimatorError?: (info: {
+        scenario?: string;
+        reason: string;
+    }) => void;
+}
+interface FeeManagerConfig {
+    /** Provider used for gas-price reads. */
+    provider: PublicClient;
+    /**
+     * Hardcoded fallback gas units, used when (a) no `bundlerClient` is
+     * configured, OR (b) the bundler call fails and `partialUserOp` was
+     * not supplied. Default: 500_000n. Sized as a safe over-estimate vs
+     * the historically observed mint/burn cost so a fallback never
+     * under-charges the sponsor.
+     */
+    gasUnits?: bigint;
+    /**
+     * SDK-side premium in basis points. Default: 10_000 (100% = no extra
+     * padding). Pimlico's bundler pads ~10-15% internally, and PAFI
+     * sponsor-relayer applies its own premium (110%) before returning
+     * gasUnits, so adding more here would compound the over-charge that
+     * the v0.20 refactor was designed to remove. Override only when the
+     * caller's `bundlerClient` returns raw bundler values without a
+     * premium applied.
+     */
+    gasPremiumBps?: number;
+    /**
+     * Quote function — given an amount of native wei, return the
+     * equivalent amount in the fee currency (PT raw units for mint/burn,
+     * USDT/USDC 6-decimal for swap / perp deposit). Chain- and
+     * token-agnostic by design; wire to `createNativePtQuoter` for PT or
+     * `quoteOperatorFeeUsdt` for stables.
+     */
+    quoteNativeToFee: (amountNative: bigint) => Promise<bigint>;
+    /**
+     * Optional bundler-driven gas-units estimator. When set,
+     * `estimateGasFee({ partialUserOp, scenario, contractAddress })` calls
+     * the estimator for per-UserOp accuracy. When unset, the legacy
+     * hardcoded path runs — backward-compatible with v0.16/0.19 callers.
+     */
+    bundlerClient?: BundlerEstimatorClient;
+    /** Optional observability hooks. Throws inside hooks are swallowed. */
+    metrics?: FeeManagerMetrics;
+}
+/**
+ * Parameters for a single bundler-driven `estimateGasFee` call. All
+ * fields optional for backwards compatibility — when `partialUserOp` is
+ * absent the SDK falls back to the hardcoded path.
+ */
+interface EstimateGasFeeOptions {
+    partialUserOp?: {
+        sender: Address;
+        nonce: bigint;
+        callData: Hex;
+        signature?: Hex;
+    };
+    scenario?: string;
+    contractAddress?: Address;
+    paymasterAddress?: Address;
+}
+/**
+ * Computes the operator fee the issuer charges users for sponsored gas.
+ *
+ * Fee currency is whatever the injected `quoteNativeToFee` returns —
+ * PT for mint/burn, USDT/USDC for swap & perp deposit.
+ *
+ * Two execution paths:
+ *
+ *   1. **Estimator path** (recommended) — caller wires `bundlerClient`
+ *      (typically `createPafiEstimatorClient`). Each call hits the PAFI
+ *      sponsor-relayer's `/v1/estimate-gas-fee` which caches by
+ *      `(scenario, contract codehash, paymaster)` and applies its own
+ *      premium. Result is the most accurate fee available and matches
+ *      what sponsor-relayer's verify path expects, eliminating
+ *      `INSUFFICIENT_FEE` rejects from formula drift.
+ *
+ *   2. **Fallback path** — no bundler client OR estimator threw. Use
+ *      hardcoded `gasUnits × premium`. Same shape as v0.16/0.19 so
+ *      legacy integrations get identical behaviour.
+ *
+ * **No operator rebalancing**: the operator does NOT hold ETH; gas is
+ * paid by PAFI's Pimlico paymaster. The fee here is an
+ * application-level ERC-20 transfer in the same UserOp batch.
+ */
+declare class FeeManager {
+    private readonly provider;
+    private readonly fallbackGasUnits;
+    private readonly gasPremiumBps;
+    private readonly quoteNativeToFee;
+    private readonly bundlerClient;
+    private readonly metrics;
+    private cachedFee;
+    private cacheExpiresAt;
+    private static readonly FEE_CACHE_TTL_MS;
+    constructor(config: FeeManagerConfig);
+    /**
+     * Estimate the operator fee for the next sponsored UserOp.
+     *
+     * Without `opts` → legacy path: `gasUnits × gasPrice × premium →
+     * quoteNativeToFee`. Cached for 10 s to absorb bursts.
+     *
+     * With `opts` AND `bundlerClient` → estimator path. Each call may
+     * hit a different bundler-cached result; the SDK does NOT add its
+     * own value cache because the estimator's cache TTL is the source
+     * of truth for "how long is this estimate good for".
+     */
+    estimateGasFee(opts?: EstimateGasFeeOptions): Promise<bigint>;
+    /** Manually purge the legacy 10s fee cache. */
+    invalidateCache(): void;
+    private resolveGasUnits;
+    private safeEmit;
+}
+
+/** Decoded Transfer(from=0x0 → to) event used to finalize a mint. */
+interface MintEvent {
+    /** Destination address (the user who received the minted points) */
+    to: Address;
+    /** Amount minted (in wei / base units) */
+    amount: bigint;
+    /** Block number the mint was included in */
+    blockNumber: bigint;
+    /** Transaction hash that emitted the event */
+    txHash: Hex;
+    /** Log index within the tx, for deterministic ordering */
+    logIndex: number;
+}
+/** Decoded Transfer(from=user → 0x0) event used to finalize a burn-for-credit. */
+interface BurnEvent {
+    /** The burner — user whose PT was burned. */
+    from: Address;
+    /** Amount burned. */
+    amount: bigint;
+    blockNumber: bigint;
+    txHash: Hex;
+    logIndex: number;
+}
+/**
+ * Cursor persistence interface — the indexer reports the next block
+ * number it is about to process so the caller can write it to Redis /
+ * Postgres / a file. The SDK does not own persistence because every
+ * issuer has their own storage stack.
+ *
+ * **Per-token keying.** When multiple PointTokens are wired through a
+ * single `createIssuerService` call, each `PointIndexer` MUST get its
+ * own cursor — otherwise token A advances the shared cursor past
+ * token B's events and token B's mints are never finalized (off-chain
+ * balance never deducts → on-chain PT supply for token B exceeds
+ * off-chain backing). Combined with the monotonic-save invariant this
+ * becomes a catastrophic-and-stable state where token B's cursor can
+ * never catch up. Implementations SHOULD expose `forKey(key)`
+ * returning a derived store keyed under a distinct namespace; the SDK
+ * factory calls it once per token.
+ *
+ * When `forKey` is absent, the SDK falls back to the bare store and
+ * emits a runtime warning if more than one token is configured. New
+ * implementations are strongly encouraged to add `forKey`.
+ */
+interface IIndexerCursorStore {
+    /** Return the last persisted cursor (`undefined` on first run). */
+    load(): Promise<bigint | undefined>;
+    /** Persist a new cursor value. Called after each successful batch. */
+    save(blockNumber: bigint): Promise<void>;
+    /**
+     * Return a derived store keyed under `key`. The returned store is
+     * an independent `IIndexerCursorStore` so the same persistence
+     * backend can serve N indexers with N distinct cursors.
+     *
+     * Optional for backwards compatibility, but REQUIRED in practice
+     * whenever more than one PointToken is wired through the SDK
+     * factory (per-token keying section above).
+     */
+    forKey?(key: string): IIndexerCursorStore;
+}
+/**
+ * No-op cursor store. Useful when the caller wants to drive the cursor
+ * entirely via `processBlockRange()` and doesn't need persistence.
+ */
+declare class InMemoryCursorStore implements IIndexerCursorStore {
+    private cursor;
+    /**
+     * Child stores keyed by `forKey()`. Each child has its own cursor,
+     * so a single InMemoryCursorStore can back N PointIndexers in tests
+     * / single-process callers.
+     */
+    private readonly children;
+    load(): Promise<bigint | undefined>;
+    save(blockNumber: bigint): Promise<void>;
+    forKey(key: string): IIndexerCursorStore;
+}
+interface SingletonLockHandle {
+    release(): Promise<void>;
+}
+interface ISingletonLock {
+    /**
+     * Attempt to acquire the lock for `key`. Returns a handle on success
+     * (caller is the leader), or `null` if another holder owns it.
+     *
+     * Implementations MUST be non-blocking — if the lock is held, return
+     * null immediately. The factory polls / retries at a higher layer.
+     */
+    acquire(key: string): Promise<SingletonLockHandle | null>;
+}
+
+declare class PointIndexerFinalizeError extends Error {
+    readonly context: {
+        pointToken: Address;
+        to: Address;
+        amount: bigint;
+        txHash: `0x${string}`;
+        blockNumber: bigint;
+    };
+    readonly cause: unknown;
+    constructor(message: string, context: {
+        pointToken: Address;
+        to: Address;
+        amount: bigint;
+        txHash: `0x${string}`;
+        blockNumber: bigint;
+    }, cause: unknown);
+}
+interface PointIndexerConfig {
+    provider: PublicClient;
+    pointTokenAddress: Address;
+    ledger: IPointLedger;
+    /**
+     * When set, indexer listens to `MintFeeWrapper.MintWithFee`
+     * (filtered by this `pointToken`) instead of
+     * `PointToken.Transfer(0x0)`.
+     *
+     * Required for wrapper-mediated mints because the on-chain Transfer
+     * destination is the wrapper itself (not the end user), so a naive
+     * `Transfer(0x0 → user)` watch would leave PENDING locks unresolved.
+     *
+     * `MintWithFee(indexed pointToken, indexed to, grossAmount, netAmount,
+     * feeAmount)` carries the actual recipient + the gross amount that
+     * matches the off-chain lock.
+     *
+     * Pass `undefined` (or the dead-zero address) for direct-mint chains
+     * without a wrapper — indexer falls back to legacy Transfer mode.
+     */
+    mintFeeWrapperAddress?: Address;
+    /**
+     * Block to start from on first run. Ignored if the cursor store already
+     * has a value. Defaults to `0n`.
+     */
+    fromBlock?: bigint;
+    /**
+     * Persistent cursor store. Defaults to an `InMemoryCursorStore` which
+     * only survives inside the current process.
+     */
+    cursorStore?: IIndexerCursorStore;
+    /**
+     * Reorg safety: only treat events as final after this many confirmations.
+     * The indexer reads `latestBlock - confirmations` as its high-water mark.
+     * Default: 3 (a conservative number for Base L2).
+     */
+    confirmations?: number;
+    /**
+     * How many blocks to scan per `getLogs` call. Keeps RPC pages bounded.
+     * Default: 2000 (comfortably under most provider page limits).
+     */
+    batchSize?: number;
+    /**
+     * Polling interval (ms) used by `start()`. Default: 5000 (5s).
+     */
+    pollIntervalMs?: number;
+    /** Clock override for tests. */
+    now?: () => number;
+    /**
+     * Observability hook fired on EVERY tick error (RPC failure, ledger
+     * write failure, etc). Issuers MUST wire this to their alert
+     * pipeline (Sentry / Datadog / PagerDuty) — without it, the indexer
+     * silently swallows errors via `console.error`, and indexer outage
+     * means PENDING mint locks never resolve (user balances stuck).
+     *
+     * When omitted, falls back to `console.error` for back-compat.
+     */
+    onTickError?: (err: unknown) => void;
+}
+/**
+ * Watches mint events on PointToken and finalizes the issuer ledger when
+ * a confirmed mint matches a PENDING lock.
+ *
+ * **Two modes** — selected at construction by `mintFeeWrapperAddress`:
+ *
+ * 1. **Wrapper mode (recommended for mainnet)**
+ *    Listens to `MintFeeWrapper.MintWithFee(indexed pointToken, indexed to,
+ *    grossAmount, netAmount, feeAmount)` filtered by `pointToken`. The
+ *    `to` field is the actual end-user (not the wrapper), and `grossAmount`
+ *    matches the off-chain lock's amount.
+ *
+ * 2. **Direct mode (chains without wrapper)**
+ *    Listens to `PointToken.Transfer(from=0x0 → to)`. Used when the
+ *    wrapper address is undefined / zero / dead.
+ *
+ * Finalization strategy (per event):
+ *   1. Find a PENDING locked mint request for `to` with matching amount.
+ *   2. Call `ledger.deductBalance(to, amount, txHash)` — this is idempotent
+ *      in the default `MemoryPointLedger` because deducting also resolves
+ *      the matching lock.
+ *   3. If no matching lock is found (e.g. a manual `PointToken.mint()` call
+ *      or a race where the lock already expired), log and skip — this
+ *      intentionally does NOT credit the ledger, because the gateway is
+ *      the only sanctioned way to spawn a mint.
+ *
+ * Reorg safety: events are only processed when they are at least
+ * `confirmations` blocks deep. A new `getLogs` call on every poll picks
+ * up finalized blocks from the persisted cursor.
+ *
+ * Pure-polling design (rather than `watchContractEvent`) keeps the SDK
+ * compatible with HTTP-only providers and with RPC rotation.
+ */
+declare class PointIndexer {
+    private readonly provider;
+    private readonly pointTokenAddress;
+    private readonly mintFeeWrapperAddress;
+    private readonly ledger;
+    private readonly cursorStore;
+    private readonly startBlock;
+    private readonly confirmations;
+    private readonly batchSize;
+    private readonly pollIntervalMs;
+    private readonly onTickError?;
+    private running;
+    private timer;
+    constructor(config: PointIndexerConfig);
+    /** Begin polling. Schedules `tick()` on a loop. */
+    start(): void;
+    /** Stop polling. Safe to call multiple times. */
+    stop(): void;
+    /**
+     * Run one poll cycle: load cursor → scan [cursor, safeHead] in
+     * `batchSize` chunks → persist new cursor. Swallows any error and
+     * schedules the next tick. Visible for test harnesses via a public name.
+     */
+    tick(): Promise<void>;
+    private handleTickError;
+    private scheduleNext;
+    /**
+     * Scan `[from, to]` inclusive for mint events in `batchSize` chunks.
+     * Callers can use this directly to backfill a specific range without
+     * engaging `start()`. On completion, the cursor is advanced to `to + 1`.
+     */
+    processBlockRange(from: bigint, to: bigint): Promise<void>;
+    /**
+     * Wrapper mode: listen for `MintWithFee` on the wrapper,
+     * filtered to events for THIS pointToken only. The event's `to` field
+     * is the actual end user, and `grossAmount` matches the lock amount.
+     */
+    private fetchWrapperMintEvents;
+    /**
+     * Direct mode (legacy / chains without wrapper): listen for
+     * `Transfer(from=0x0 → to)` on the PointToken itself.
+     */
+    private fetchTransferMintEvents;
+    private decodeTransferMintEvents;
+    /**
+     * Finalize a single mint event: match it to a PENDING lock in the
+     * ledger, then call `deductBalance` (which also resolves the lock in
+     * the default `MemoryPointLedger`).
+     *
+     * No-matching-lock is a valid state: it means either the lock already
+     * expired, or the mint was authorized out-of-band (e.g. a direct
+     * `PointToken.mint()` from an EOA minter for testing). In that case we
+     * do NOT touch the ledger — crediting here would silently allow the
+     * issuer to mint without going through the gateway.
+     */
+    private finalize;
+}
+
+/**
+ * Mirror of `PointIndexerFinalizeError` — raised when
+ * `ledger.resolveCreditByBurnTx` rejects. Silently swallowing this
+ * error and advancing the cursor anyway would permanently drop
+ * confirmed on-chain burns from the off-chain credit pipeline. The
+ * error therefore propagates, the chunk's cursor save is skipped,
+ * and the next tick retries.
+ */
+declare class BurnIndexerFinalizeError extends Error {
+    readonly context: {
+        pointToken: Address;
+        from: Address;
+        amount: bigint;
+        txHash: `0x${string}`;
+        blockNumber: bigint;
+        lockId: string;
+    };
+    readonly cause: unknown;
+    constructor(message: string, context: {
+        pointToken: Address;
+        from: Address;
+        amount: bigint;
+        txHash: `0x${string}`;
+        blockNumber: bigint;
+        lockId: string;
+    }, cause: unknown);
+}
+interface BurnIndexerConfig {
+    provider: PublicClient;
+    pointTokenAddress: Address;
+    ledger: IPointLedger;
+    /** Block to start from on first run. Ignored if cursor store has value. */
+    fromBlock?: bigint;
+    cursorStore?: IIndexerCursorStore;
+    /**
+     * Reorg safety — only treat events as final after this many
+     * confirmations. Default: 3.
+     */
+    confirmations?: number;
+    /** Blocks per getLogs call. Default: 2000. */
+    batchSize?: number;
+    /** Polling interval (ms). Default: 5000. */
+    pollIntervalMs?: number;
+    now?: () => number;
+    /**
+     * Map a burn event to the pending credit lockId that should be resolved.
+     * Return `undefined` to skip this burn event (no credit granted).
+     *
+     * REQUIRED — there is no default implementation. Issuers with a Postgres
+     * ledger typically JOIN on `(from, amount, status=PENDING)`. The in-memory
+     * ledger uses a lookup by lockId supplied out-of-band from the claim flow.
+     */
+    matchLockId: (event: BurnEvent) => Promise<string | undefined>;
+    /**
+     * Observability hook — see PointIndexerConfig.onTickError for full
+     * rationale. Critical for burn indexer too: silent failure means
+     * pending credits never resolve, user reports "I burned my PT but
+     * never got my off-chain credit".
+     */
+    onTickError?: (err: unknown) => void;
+}
+/**
+ * Mirror of `PointIndexer` for the reverse direction — watches
+ * `Transfer(user → 0x0)` events (ERC-20 burns) on the PointToken
+ * contract and finalizes pending off-chain credits.
+ *
+ * Finalization flow:
+ *   1. For each Burn event at `{from, amount, txHash}`:
+ *   2. Call `ledger.resolveCreditByBurnTx(lockId, txHash)` where `lockId`
+ *      is resolved by the caller's `onMatchCredit` hook or a
+ *      ledger-specific lookup. The SDK does not prescribe the matching
+ *      strategy — issuers with a Postgres ledger can JOIN by
+ *      `(from, amount, status=PENDING)`; the in-memory ledger matches
+ *      by `lockId` supplied out-of-band.
+ *
+ * When no pending credit matches an observed Burn event, the indexer
+ * logs + skips — **it never credits off-chain** from a Burn that was
+ * not first reserved via `reservePendingCredit()`. This prevents
+ * spurious credits from one-off admin burns or direct burn calls
+ * outside the issuer SDK.
+ */
+declare class BurnIndexer {
+    private readonly provider;
+    /**
+     * The PointToken this indexer watches. Exposed so callers can key
+     * leader-election locks / cursor stores by token
+     */
+    readonly pointTokenAddress: Address;
+    private readonly ledger;
+    private readonly cursorStore;
+    private readonly startBlock;
+    private readonly confirmations;
+    private readonly batchSize;
+    private readonly pollIntervalMs;
+    private readonly onTickError?;
+    matchLockId: (event: BurnEvent) => Promise<string | undefined>;
+    private running;
+    private timer;
+    constructor(config: BurnIndexerConfig);
+    start(): void;
+    stop(): void;
+    tick(): Promise<void>;
+    private handleTickError;
+    private scheduleNext;
+    /**
+     * Scan `[from, to]` inclusive for burn events. Callers can drive this
+     * directly to backfill a specific range without `start()`. Cursor is
+     * advanced to `to + 1` on completion.
+     */
+    processBlockRange(from: bigint, to: bigint): Promise<void>;
+    private decodeBurnEvents;
+    /**
+     * Resolve a matching pending credit for this burn event and call
+     * `ledger.resolveCreditByBurnTx(lockId, txHash)`. If no match found,
+     * log + skip.
+     */
+    private finalize;
+}
+
+/**
+ * Minimal duck-typed adapter so we don't drag a TypeORM / pg dep into
+ * the SDK. The caller passes anything that can execute a parameterised
+ * query and yield `{ got: boolean }` rows — TypeORM `DataSource.query`,
+ * a raw `pg` client, knex's `raw`, kysely, etc.
+ *
+ * The helper requires `int8` (signed 64-bit) lock IDs. We derive them
+ * from the lock `key` via a deterministic hash so different replicas
+ * agree on the int regardless of casing / whitespace drift.
+ */
+interface PostgresQueryRunner {
+    query(sql: string, params?: unknown[]): Promise<unknown>;
+}
+/**
+ * Build an `ISingletonLock` backed by PostgreSQL session-level advisory
+ * locks (`pg_try_advisory_lock`).
+ *
+ * Why advisory locks (vs. row-level locks or a leases table):
+ *   1. **Non-blocking** — `pg_try_advisory_lock` returns immediately;
+ *      perfect for the "try then idle" pattern the SDK uses on boot.
+ *   2. **Auto-release on connection drop** — if the leader pod crashes,
+ *      its PG connection closes, and the lock is freed automatically.
+ *      No timeout tuning, no lease renewal loops, no zombie locks.
+ *   3. **Zero schema** — no extra table, no migration, no contention
+ *      with application reads.
+ *
+ * **Caveat — long-lived connection required.** Session-level locks are
+ * held only for the lifetime of the PG connection that called
+ * `pg_try_advisory_lock`. PgBouncer in `transaction` pooling mode will
+ * release the lock between statements; you MUST run in `session`
+ * pooling or skip the bouncer for the indexer process. The advisory
+ * `transaction` variant exists but doesn't fit the "hold while polling"
+ * pattern — for that you'd need a periodic re-acquire, which we don't
+ * implement here.
+ *
+ * @example
+ *   import { DataSource } from "typeorm";
+ *   import { makePostgresSingletonLock } from "@pafi-dev/issuer";
+ *
+ *   const dataSource = new DataSource({ ... });
+ *   const lock = makePostgresSingletonLock({
+ *     query: (sql, params) => dataSource.query(sql, params),
+ *   });
+ *
+ *   createIssuerService({
+ *     ...,
+ *     indexer: {
+ *       autoStart: true,
+ *       singletonLock: lock,
+ *     },
+ *   });
+ */
+declare function makePostgresSingletonLock(runner: PostgresQueryRunner): ISingletonLock;
+
+interface ApiConfigResponse {
+    chainId: number;
+    contracts: {
+        /**
+         * Legacy single-token field — kept for backward compat with v0.1.x
+         * frontends. Prefer `pointTokens` for multi-token issuers.
+         */
+        pointToken?: Address;
+        /**
+         * All supported PointToken addresses (v0.2.0+). Single-token issuers
+         * will have one entry that matches `pointToken`. Multi-token
+         * issuers expose the full list here so the frontend can render a
+         * token picker.
+         */
+        pointTokens?: Address[];
+        relay?: Address;
+        issuerRegistry?: Address;
+        pointTokenFactory?: Address;
+        mintingOracle?: Address;
+        poolManager?: Address;
+        usdt?: Address;
+        /**
+         * EIP-7702 delegation target — the single contract every user's
+         * EOA must delegate to before submitting sponsored UserOps. On
+         * Base mainnet this is Pimlico's `Simple7702Account` at
+         * `0xe6Cae83BdE06E4c305530e199D7217f42808555B` (swapped in
+         * 2026-04-27 to replace the earlier Coinbase Smart Wallet v2
+         * BatchExecutor, which had a SignatureWrapper incompatibility
+         * surfacing as AA23 0x3c10b94e during validateUserOp).
+         */
+        batchExecutor?: Address;
+        /**
+         * Single global MintFeeWrapper that skims a fee on every
+         * sig-gated mint and distributes across the configured recipients.
+         */
+        mintFeeWrapper?: Address;
+    };
+    /**
+     * Per-PointToken mint fee (in basis points, 0–10000) read from
+     * `MintFeeWrapper.totalFeeBps(pointToken)`. Frontend uses this to show
+     * "you'll receive X PT (Y% mint fee)" before user signs.
+     *
+     * Map keyed by lower-cased PointToken address (JSON-friendly) so the
+     * FE can look up the fee without iterating. Omitted (or with zero
+     * values) when the chain has no wrapper deployed or recipients are
+     * not configured.
+     */
+    mintFeeBpsByToken?: Record<string, number>;
+    /**
+     * Absolute URL that the Issuer App opens after a successful claim to
+     * let the user swap PT → USDT or deposit into the perp DEX on PAFI
+     * Web. Mobile opens this in an in-app browser
+     * (SFSafariViewController / Chrome Custom Tabs). Desktop opens in a
+     * popup. See [MOBILE_SDK_INTEGRATION.md] "PAFI Web Handoff" section.
+     *
+     * Optional — if omitted, the Issuer App should hide the "Open PAFI"
+     * button.
+     */
+    pafiWebUrl?: string;
+}
+interface ApiNonceResponse {
+    nonce: string;
+    /**
+     * Complete EIP-4361 message, ready to pass directly to `wallet.signMessage()`.
+     * Built by the controller using `createLoginMessage()` — requires the caller's
+     * `walletAddress`, so it cannot be constructed inside the handler itself.
+     */
+    message?: string;
+}
+interface ApiLoginRequest {
+    message: string;
+    signature: Hex;
+}
+interface ApiLoginResponse {
+    token: string;
+    userAddress: Address;
+    /** Unix ms when the JWT (and backing session) expires. */
+    expiresAt: number;
+}
+interface ApiGasFeeResponse {
+    /** Gas fee quoted in USDT (6-decimal base units). */
+    gasFeeUsdt: bigint;
+}
+interface ApiPoolsRequest {
+    chainId: number;
+    pointTokenAddress: Address;
+}
+interface ApiPoolsResponse {
+    pools: PoolKey[];
+}
+interface ApiUserRequest {
+    chainId: number;
+    userAddress: Address;
+    pointTokenAddress: Address;
+}
+interface ApiUserResponse {
+    /**
+     * Off-chain point balance from the issuer's ledger (excludes PENDING locks).
+     * This is what the user can claim into on-chain PT via `/claim`.
+     */
+    offChainBalance: bigint;
+    /**
+     * On-chain ERC-20 balance from `PointToken.balanceOf(user)`.
+     * Points the user has already claimed but hasn't swapped or redeemed.
+     */
+    onChainBalance: bigint;
+    /**
+     * Sum of off-chain + on-chain balance. FE renders this as a single
+     * "your points" number, per the unified-balance UX spec.
+     */
+    totalBalance: bigint;
+    /**
+     * @deprecated Use `offChainBalance` instead. Retained as a wire-level
+     * alias for older mobile clients that still read it.
+     */
+    balance: bigint;
+    isMinter: boolean;
+}
+interface ApiRedemptionPreviewRequest {
+    pointTokenAddress?: Address;
+}
+interface ApiRedemptionPreviewResponse {
+    availableAmountPt: bigint;
+    dailyRemainingPt: bigint;
+    cooldownUntilUnixSec: number | null;
+    nextBlackoutEndsAtUnixSec: number | null;
+    perTxMinPt: bigint;
+    perTxMaxPt: bigint;
+    policyVersion: string;
+    policySource: "settlement" | "cache" | "default";
+}
+interface ApiRedemptionEvaluateRequest {
+    amountPt: bigint;
+    pointTokenAddress?: Address;
+}
+interface ApiRedemptionEvaluateResponse {
+    allowed: boolean;
+    denial?: {
+        code: "AMOUNT_BELOW_MIN" | "AMOUNT_ABOVE_MAX" | "DAILY_LIMIT_EXCEEDED" | "COOLDOWN_ACTIVE" | "BLACKOUT_WINDOW";
+        message: string;
+    };
+    preview: ApiRedemptionPreviewResponse;
+}
+type PoolsProvider = (request: ApiPoolsRequest) => Promise<ApiPoolsResponse>;
+
+/**
+ * Per-user redemption history needed by the evaluator. The issuer can
+ * implement this with their existing burn journal table (preferred) or
+ * use the bundled MemoryRedemptionHistoryStore for tests.
+ */
+interface IRedemptionHistoryStore {
+    /**
+     * Sum of PT redeemed by `user` from `sinceUnixSec` onwards. Used for
+     * the rolling 24h daily-limit check. MUST count both confirmed burns
+     * and currently-reserved-pending entries — the policy treats reserved
+     * burns as "spent" so a flood of pending requests can't bypass the cap.
+     */
+    sumRedeemedSince(user: Address, sinceUnixSec: number, pointTokenAddress?: Address): Promise<bigint>;
+    /**
+     * Unix-second timestamp of the user's last redemption attempt
+     * (confirmed or reserved). null if never. Used for cooldown.
+     */
+    getLastRedeemedAtUnixSec(user: Address, pointTokenAddress?: Address): Promise<number | null>;
+    /**
+     * Record a new redemption attempt. Called by handleRedemptionInitiate
+     * AFTER policy.evaluate() returns ALLOW and the BurnRequest is signed.
+     * Implementations may persist this row in a redemption_history table or
+     * derive from existing pending-credit reservations.
+     */
+    recordRedemption(entry: {
+        user: Address;
+        amountPt: bigint;
+        pointTokenAddress?: Address;
+        unixSec: number;
+        /** Optional pointer back to the reservation lock id. */
+        reservationId?: string;
+    }): Promise<void>;
+}
+interface SettlementClientConfig {
+    /**
+     * chainId — used to derive the issuer-api base URL via
+     * `getPafiServiceUrls(chainId).issuerApi`. SDK ships with the URL
+     */
+    chainId: number;
+    baseUrl?: string;
+    /** PAFI-assigned issuer id used in `X-Issuer-Id` header. */
+    issuerId: string;
+    /** Raw API key sent as `Authorization: Bearer <apiKey>`. */
+    apiKey: string;
+    /** Per-request timeout in milliseconds. Default 1000. */
+    fetchTimeoutMs?: number;
+    /** Override fetch (testing). */
+    fetchImpl?: typeof fetch;
+}
+interface PolicyProviderConfig extends SettlementClientConfig {
+    /** Cache TTL in milliseconds. Default 5 * 60 * 1000 (5min). */
+    cacheTtlMs?: number;
+    onFetchFailure?: "fail-closed" | "permissive-default";
+    onWarning?: (msg: string, ctx: Record<string, unknown>) => void;
+    /**
+     * Optional clock for testability. Returns unix milliseconds.
+     * Defaults to () => Date.now().
+     */
+    now?: () => number;
+}
+
+interface ResolvedPolicy {
+    policy: RedemptionPolicy;
+    source: RedemptionPolicySource;
+}
+/**
+ * Wraps SettlementClient with a 5-minute TTL cache and a hardcoded
+ * default fallback. Single-flight: concurrent getPolicy() calls during
+ * a cache miss share the same in-flight request.
+ *
+ * Resolution order:
+ *   1. fresh cache hit            → return cached
+ *   2. cache miss → fetch ok      → cache + return (source=settlement)
+ *   3. cache miss → fetch failed  → DEFAULT_REDEMPTION_POLICY (source=default)
+ *
+ * Stale cache is NEVER returned — once the TTL expires we either fetch
+ * fresh data or fall through to default. This keeps behavior predictable:
+ * "default" means "we couldn't talk to settlement RIGHT NOW", not "we got
+ * lucky with a stale entry".
+ */
+declare class PolicyProvider {
+    private readonly client;
+    private readonly issuerId;
+    private readonly cacheTtlMs;
+    private readonly onFetchFailure;
+    private readonly onWarning?;
+    private readonly now;
+    private cache;
+    private inflight;
+    constructor(config: PolicyProviderConfig);
+    getPolicy(): Promise<ResolvedPolicy>;
+    /** Drop cached policy. Next getPolicy() will refetch. */
+    invalidate(): void;
+    private readCache;
+    private fetchAndStore;
+}
+
+interface RedemptionServiceConfig {
+    policyProvider: PolicyProvider | PolicyProviderConfig;
+    historyStore: IRedemptionHistoryStore;
+    /** Defaults to () => Math.floor(Date.now() / 1000). */
+    nowUnixSec?: () => number;
+}
+/**
+ * High-level facade used by HTTP handlers. Combines PolicyProvider +
+ * IRedemptionHistoryStore into preview/evaluate operations.
+ *
+ *   preview(user)                → RedemptionPreview (no amount required)
+ *   evaluate(user, amount)       → RedemptionDecision
+ *   recordSuccessfulInitiate(..) → call AFTER signing the BurnRequest
+ *
+ * Note: this service does NOT mutate anything during evaluate(). The
+ * caller must call recordSuccessfulInitiate() after the BurnRequest is
+ * signed and the pending credit is reserved on the ledger. Splitting
+ * "decide" from "record" lets the handler atomically reserve + record
+ * under one DB transaction if it wants.
+ */
+declare class RedemptionService {
+    private readonly policyProvider;
+    private readonly historyStore;
+    private readonly nowUnixSec;
+    constructor(config: RedemptionServiceConfig);
+    preview(user: Address, pointTokenAddress?: Address): Promise<RedemptionPreview>;
+    evaluate(user: Address, amountPt: bigint, pointTokenAddress?: Address): Promise<RedemptionDecision>;
+    recordSuccessfulInitiate(entry: {
+        user: Address;
+        amountPt: bigint;
+        pointTokenAddress?: Address;
+        reservationId?: string;
+    }): Promise<void>;
+}
+
+interface IssuerApiHandlersConfig {
+    authService: AuthService;
+    ledger: IPointLedger;
+    /** Used by `handleUser` to read on-chain nonces and minter status. */
+    provider: PublicClient;
+    /**
+     * Legacy single-token config. Prefer `pointTokenAddresses` for multi-token
+     * issuers (0.2.0+).
+     */
+    pointTokenAddress?: Address;
+    /**
+     * All supported PointToken addresses. Handlers accept any address in this
+     * list; others are rejected with "unsupported pointToken".
+     */
+    pointTokenAddresses?: Address[];
+    chainId: number;
+    contracts: ApiConfigResponse["contracts"];
+    /**
+     * Optional — URL that the Issuer App opens for PT→USDT swap or perp
+     * deposit after a successful claim. Surfaced in `/config` response.
+     * See [MOBILE_SDK_INTEGRATION.md] "PAFI Web Handoff".
+     */
+    pafiWebUrl?: string;
+    /**
+     * MintFeeWrapper address used to read per-PointToken fee basis
+     * points for `/config`. When omitted, the response will not include
+     * `mintFeeBpsByToken` and FE must assume zero fee. Wrapper is shared
+     * across PointTokens; per-token recipients live inside it.
+     */
+    mintFeeWrapperAddress?: Address;
+    /** Required by `handleGasFee`; omit to disable the endpoint. */
+    feeManager?: FeeManager;
+    /** Required by `handlePools`; omit to disable the endpoint. */
+    poolsProvider?: PoolsProvider;
+    /**
+     * Required by `handleRedemptionPreview` / `handleRedemptionEvaluate`;
+     * omit to disable both. Wired by createIssuerService when the top-level
+     * `redemption` config is provided.
+     */
+    redemption?: RedemptionService;
+    /**
+     * Rate limiter for `/auth/nonce` and `/auth/login` (both unauthenticated +
+     * CPU-bound). When omitted, defaults to a `NoopRateLimiter` that lets
+     * every request through (with a one-time prod warning) — issuers MUST
+     * wire a real impl in production.
+     */
+    rateLimiter?: IRateLimiter;
+}
+/**
+ * Framework-agnostic HTTP handlers that match the endpoints a `PafiSDK`
+ * frontend expects to call. Issuers wrap these in Express / Fastify /
+ * Hono / whatever — the handlers take plain inputs and return plain
+ * outputs, with `AuthError` surfaced as typed exceptions.
+ *
+ * Every protected handler takes a pre-verified `userAddress` as its first
+ * argument. The issuer's middleware wraps `authenticateRequest()` from
+ * `@pafi-dev/issuer` to extract that address from the Bearer token before
+ * routing.
+ */
+declare class IssuerApiHandlers {
+    private readonly authService;
+    private readonly ledger;
+    private readonly provider;
+    /**
+     * Set of supported PointToken addresses (checksum-normalized). Handlers
+     * validate the request's `pointTokenAddress` against this set.
+     */
+    private readonly supportedTokens;
+    private readonly chainId;
+    private readonly contracts;
+    private readonly pafiWebUrl?;
+    private readonly feeManager?;
+    private readonly poolsProvider?;
+    private readonly redemption?;
+    private readonly rateLimiter;
+    private readonly mintFeeWrapperAddress?;
+    /**
+     * Per-token feeBps cache. Refreshed on /config when stale. feeBps
+     * changes only when ops calls `wrapper.setRecipients`, so 5-min TTL
+     * is more than safe for FE display purposes.
+     */
+    private readonly feeBpsCache;
+    private static readonly FEE_BPS_TTL_MS;
+    constructor(config: IssuerApiHandlersConfig);
+    /**
+     * `GET /auth/nonce`
+     *
+     * @param rateLimitKey  Caller-side rate-limit key (typically client IP).
+     *                      The HTTP layer (controller/middleware) extracts
+     *                      this from the request and passes it through.
+     *                      When omitted, no rate limit applies — production
+     *                      callers SHOULD always pass a key.
+     */
+    handleGetNonce(rateLimitKey?: string): Promise<ApiNonceResponse>;
+    /**
+     * `POST /auth/login`
+     *
+     * @param body          Login message + signature.
+     * @param rateLimitKey  Caller-side rate-limit key (typically client IP
+     *                      or `body.userAddress` if known). See `handleGetNonce`.
+     */
+    handleLogin(body: ApiLoginRequest, rateLimitKey?: string): Promise<ApiLoginResponse>;
+    /**
+     * `GET /config?chainId=<id>`
+     *
+     * Returns the contract addresses and chain id that the frontend SDK
+     * needs to build EIP-712 messages and interact with on-chain.
+     */
+    handleConfig(chainId: number): Promise<ApiConfigResponse>;
+    /**
+     * Read `totalFeeBps(pointToken)` for every supported PointToken from
+     * the wrapper. Cached per-token for 5 minutes. Returns `undefined`
+     * (caller drops the field) if every read fails — FE must treat
+     * "field missing" as "fee unknown, do not display".
+     */
+    private resolveFeeBpsByToken;
+    /** `GET /gas-fee` — quoted in USDT (6-decimal base units). */
+    handleGasFee(): Promise<ApiGasFeeResponse>;
+    /** `POST /auth/logout` */
+    handleLogout(token: string): Promise<void>;
+    /**
+     * `GET /pools?chainId=<id>&pointToken=<addr>`
+     *
+     * Delegates to the injected `PoolsProvider`. The handler itself does
+     * not know where pools come from — that's an issuer decision.
+     */
+    handlePools(_userAddress: Address, request: ApiPoolsRequest): Promise<ApiPoolsResponse>;
+    /**
+     * `GET /user?chainId=<id>&user=<addr>&pointToken=<addr>`
+     *
+     * Returns per-user state the frontend needs to build a fresh mint:
+     * on-chain nonces + minter status + off-chain balance.
+     */
+    handleUser(userAddress: Address, request: ApiUserRequest): Promise<ApiUserResponse>;
+    /**
+     * `GET /redemption/preview?pointToken=<addr>`
+     *
+     * Returns the headroom currently available to `userAddress` under the
+     * configured RedemptionPolicy. Pure read — does not record anything.
+     * Use this for UI to render "X PT redeemable now / next available at …".
+     */
+    handleRedemptionPreview(userAddress: Address, request: ApiRedemptionPreviewRequest): Promise<ApiRedemptionPreviewResponse>;
+    /**
+     * `POST /redemption/evaluate`
+     *
+     * Pre-flight check before the issuer signs a BurnRequest. Returns
+     * { allowed, denial?, preview }. Caller (the burn-orchestrator) MUST
+     * re-check on the actual initiate path — evaluate is read-only and a
+     * caller could race two requests under the same headroom. The intended
+     * write path is: evaluate → sign BurnRequest → reserve pending credit
+     * → call `service.redemption.recordSuccessfulInitiate()`.
+     */
+    handleRedemptionEvaluate(userAddress: Address, request: ApiRedemptionEvaluateRequest): Promise<ApiRedemptionEvaluateResponse>;
+    private requireSupportedToken;
+}
+
+/**
+ * Resolves the EIP-712 domain `name` for a PointToken. Used by handlers
+ * (PTClaimHandler / PTRedeemHandler) that sign requests for multiple
+ * PointTokens within the same issuer backend.
+ *
+ * Resolution order per address:
+ *   1. Cache hit → return immediately (no RPC)
+ *   2. Static override map (config.overrides) → cache + return
+ *   3. On-chain `name()` lookup → cache + return
+ *
+ * Cache is per-instance — share one resolver across handlers so mint +
+ * redeem paths amortise the same set of lookups.
+ *
+ * Why the override map: production issuers often know their PTs at
+ * boot (env / DB) and want to avoid RPC quota churn + tolerate transient
+ * RPC failures. The on-chain fallback handles ad-hoc PTs not in the map
+ * (e.g. newly deployed during the process lifetime).
+ */
+interface PointTokenDomainResolverConfig {
+    provider: PublicClient;
+    /**
+     * Optional pre-configured map — checksummed (or lowercased) PointToken
+     * address → ERC-20 `name()` value. When a PT's address is in this map,
+     * the resolver short-circuits without an RPC call.
+     */
+    overrides?: Record<string, string>;
+}
+declare class PointTokenDomainResolver {
+    private readonly provider;
+    private readonly overrides;
+    private readonly cache;
+    constructor(config: PointTokenDomainResolverConfig);
+    resolve(pointTokenAddress: Address): Promise<string>;
+    /** Invalidate one address (after deploy / proxy upgrade) or all. */
+    invalidate(pointTokenAddress?: Address): void;
+}
+
+/**
+ * Reverse flow — user-initiated PT redeem.
+ *
+ * User has on-chain PT, wants to convert back to off-chain points. The
+ * issuer backend signs a `BurnRequest` with its burner signer, reserves
+ * an off-chain pending credit, and returns an unsigned UserOp. The FE
+ * submits the UserOp via EIP-7702 + PAFI sponsor-relayer. On confirmation,
+ * `Transfer(user → 0x0)` is emitted; `BurnIndexer` resolves the pending
+ * credit to a real off-chain credit.
+ *
+ * Contract path (mock ABI — matches deployed PointToken):
+ *
+ *   burn(address from, uint256 amount, uint256 deadline, bytes burnerSig)
+ *
+ * On-chain checks:
+ *   - msg.sender == from (enforced via EIP-7702 delegation on user EOA)
+ *   - burnerSig signer ∈ burners[]
+ *   - nonce == burnRequestNonces[from]
+ *   - now <= deadline
+ *
+ * The user never signs an EIP-712 message in this flow. Their only
+ * signature is the ERC-4337 UserOp signature, which the AA wallet
+ * handles. Consent is implicit: by submitting the UserOp they authorize
+ * the burn.
+ */
+interface PTRedeemHandlerConfig {
+    ledger: IPointLedger;
+    relayService: RelayService;
+    provider: PublicClient;
+    /** BatchExecutor delegation target (chain-specific). */
+    batchExecutorAddress: Address;
+    /** Chain id — used for the BurnRequest EIP-712 domain. */
+    chainId: number;
+    /**
+     * Resolver for the EIP-712 domain `name` (= PointToken.name() on-chain).
+     * Required because mint/redeem now route the `pointTokenAddress` per
+     * request — the handler can't bind a single domain at construction.
+     * Pass a shared resolver instance so mint + redeem amortise the same
+     * cache. The handler always uses `pointTokenAddress` as the EIP-712
+     * `verifyingContract` — no override (per-PT domain separator is
+     * isolated by contract address).
+     */
+    domainResolver: PointTokenDomainResolver;
+    /**
+     * Issuer burner signer wallet — signs the `BurnRequest` EIP-712.
+     * Must be whitelisted via `PointToken.addBurner(signerAddr)` at
+     * provisioning time. Typically HSM/KMS-backed in prod.
+     */
+    burnerSignerWallet: WalletClient;
+    /**
+     * Issuer's allow-listed PointToken contracts (checksummed EIP-55).
+     * Every `handle()` call validates the request's `pointTokenAddress`
+     * against this set BEFORE any chain read, signer call, or pending
+     * credit reservation.
+     * Pass the SAME set used to construct `IssuerApiHandlers` and
+     * `PTClaimHandler` so the read, claim, and redeem paths agree on
+     * what this issuer is willing to sign for.
+     */
+    supportedTokens: ReadonlySet<Address>;
+    /**
+     * Optional — when wired, used to estimate the PT gas-reimbursement
+     * fee. The handler self-computes `feeAmount` + `feeRecipient` so the
+     * caller doesn't repeat the boilerplate at each endpoint. Pass
+     * `feeAmount` on `PTRedeemRequest` to override.
+     */
+    feeService?: FeeManager;
+    /**
+     * How long the pending credit stays reserved if the burn never lands.
+     * Default: 15 min — long enough for a bundler submission + confirmation.
+     */
+    redeemLockDurationMs?: number;
+    /**
+     * How far ahead of `now` to set the BurnRequest deadline. Default:
+     * 15 min. Must be long enough for Bundler + EntryPoint to execute;
+     * short enough to prevent replay if the UserOp is abandoned.
+     */
+    signatureDeadlineSeconds?: number;
+    /** Clock injection for tests; defaults to `Date.now`. */
+    now?: () => number;
+    /**
+     * Optional — when wired, the handler enforces the per-issuer
+     * RedemptionPolicy (daily limit / cooldown / blackout / per-tx range)
+     * BEFORE signing the BurnRequest. On denial it throws
+     * PTRedeemError("REDEMPTION_POLICY_DENIED", ...) with the policy
+     * denial code in `policyDenialCode`. After a successful sign+reserve,
+     * the handler records the redemption against the user's history so
+     * the next preview reflects the spend.
+     */
+    redemptionService?: RedemptionService;
+}
+interface PTRedeemRequest {
+    /** Address extracted from the verified JWT — must match `userAddress`. */
+    authenticatedAddress: Address;
+    userAddress: Address;
+    amount: bigint;
+    /** PointToken contract to redeem. The handler resolves the EIP-712
+     *  domain (name + verifyingContract) from this address via the
+     *  configured `domainResolver`. */
+    pointTokenAddress: Address;
+    /** ERC-4337 account nonce for the user's EOA. */
+    aaNonce: bigint;
+    /**
+     * Optional override — explicit PT fee transfer appended after the
+     * burn (sponsored path). When omitted, the handler auto-computes
+     * via `feeService.estimateGasFee()` (if configured) and resolves
+     * the recipient from `getContractAddresses(chainId).pafiFeeRecipient`.
+     */
+    feeAmount?: bigint;
+    feeRecipient?: Address;
+    /**
+     * Optional — required only when the handler self-computes the
+     * recipient. When the caller passes an explicit `feeRecipient`, this
+     * is ignored.
+     */
+    chainId?: number;
+}
+interface PTRedeemResponse {
+    /**
+     * Sponsored path — UserOp with PT fee transfer. BurnRequest signed for
+     * `request.amount - feeAmount`. User holds exactly `request.amount` PT
+     * and the fee comes out of the redeem amount, NOT on top.
+     */
+    lockId: string;
+    userOp: PartialUserOperation;
+    /** = request.amount - feeAmount. What BurnIndexer credits off-chain on sponsored fire. */
+    netCreditAmount: bigint;
+    /**
+     * Resolved fee — computed via `feeService.estimateGasFee()` when the
+     * caller didn't override on the request, else echoed back from the
+     * request override. Useful for the FE confirmation screen.
+     */
+    feeAmount: bigint;
+    /**
+     * Fallback path — UserOp with NO fee transfer. BurnRequest signed for
+     * full `request.amount`. User pays gas in ETH directly. Present only
+     * when `feeAmount > 0`.
+     *
+     * Same nonce as sponsored: only one of the two can fire on-chain;
+     * the other lock auto-expires after `expiresInSeconds`. BurnIndexer
+     * matches by burn amount and resolves the correct lock.
+     */
+    fallback?: {
+        lockId: string;
+        userOp: PartialUserOperation;
+        /** = request.amount. Full credit when fallback fires. */
+        netCreditAmount: bigint;
+    };
+    /** Seconds until the lock expires if the burn doesn't land. */
+    expiresInSeconds: number;
+    /** The BurnRequest deadline (unix seconds) — FE uses this to surface a countdown. */
+    signatureDeadline: bigint;
+}
+type PTRedeemErrorCode = "UNAUTHORIZED" | "INVALID_AMOUNT" | "NONCE_READ_FAILED" | "NONCE_IN_FLIGHT" | "LEDGER_NOT_SUPPORTED" | "SIGNING_FAILED" | "REDEMPTION_POLICY_DENIED" | "REDEMPTION_POLICY_UNAVAILABLE" | "UNSUPPORTED_POINT_TOKEN";
+declare class PTRedeemError extends PafiSdkError {
+    readonly httpStatus: "unprocessable";
+    readonly code: PTRedeemErrorCode;
+    readonly policyDenialCode?: RedemptionDenialCode;
+    constructor(code: PTRedeemErrorCode, message: string, options?: {
+        policyDenialCode?: RedemptionDenialCode;
+    });
+}
+declare class PTRedeemHandler {
+    private readonly ledger;
+    private readonly relayService;
+    private readonly provider;
+    private readonly feeService?;
+    private readonly batchExecutorAddress;
+    private readonly chainId;
+    private readonly domainResolver;
+    private readonly burnerSignerWallet;
+    private readonly supportedTokens;
+    private readonly redeemLockDurationMs;
+    private readonly signatureDeadlineSeconds;
+    private readonly now;
+    private readonly redemptionService?;
+    /**
+     * Per-user in-flight nonce guard (single-process only).
+     *
+     * Prevents two concurrent requests from reading the same on-chain
+     * burnRequestNonce before either has completed, which would produce two
+     * signed UserOps with the same nonce — only one succeeds on-chain; the
+     * other leaves an orphaned pending credit and a wasted signer call.
+     *
+     * NOTE: This guard is effective only within a single Node.js process. For
+     * multi-instance deployments (k8s, PM2 cluster), enforce mutual exclusion
+     * via a distributed lock (Redis SETNX / Postgres advisory lock) keyed on
+     * `(userAddress, pointTokenAddress)` BEFORE calling `handle()`.
+     */
+    private readonly inFlightNonces;
+    constructor(config: PTRedeemHandlerConfig);
+    handle(request: PTRedeemRequest): Promise<PTRedeemResponse>;
+    private _handleAfterNonceLock;
+}
+
+interface RetryConfig {
+    maxAttempts?: number;
+    initialDelayMs?: number;
+    maxDelayMs?: number;
+    maxRetryAfterMs?: number;
+}
+interface PafiBackendConfig {
+    /**
+     * chainId — used to derive the sponsor-relayer base URL via
+     * `getPafiServiceUrls(chainId).sponsorRelayer`. SDK ships with the
+     */
+    chainId: number;
+    baseUrl?: string;
+    issuerId: string;
+    apiKey: string;
+    fetchImpl?: typeof fetch;
+    timeoutMs?: number;
+    retry?: RetryConfig;
+}
+type PafiBackendErrorCode = "MISSING_ISSUER_ID" | "MISSING_API_KEY" | "ISSUER_UNAUTHORIZED" | "USER_UNAUTHORIZED" | "INTENT_REJECTED" | "MINT_CAP_EXCEEDED" | "ISSUER_INACTIVE" | "BROKER_NOT_WHITELISTED" | "RATE_LIMIT_EXCEEDED" | "RATE_LIMIT_EXCEEDED_DAILY" | "RATE_LIMIT_EXCEEDED_PER_USER" | "ISSUER_BUDGET_EXCEEDED" | "RATE_LIMITER_UNAVAILABLE" | "PAYMASTER_UNAVAILABLE" | "TARGET_NOT_ALLOWLISTED" | "BAD_REQUEST" | "INTERNAL_ERROR" | "TIMEOUT" | "NETWORK_ERROR" | (string & {});
+declare class PafiBackendError extends Error {
+    code: PafiBackendErrorCode;
+    httpStatus: number;
+    details?: unknown | undefined;
+    readonly retryAfter?: number;
+    private readonly serverSafeToRetry?;
+    constructor(code: PafiBackendErrorCode, message: string, httpStatus: number, details?: unknown | undefined, opts?: {
+        retryAfter?: number;
+        safeToRetry?: boolean;
+    });
+    get safeToRetry(): boolean;
+}
+
+interface RelayUserOpRequest {
+    userOp: Record<string, string | null>;
+    entryPoint: string;
+    eip7702Auth?: {
+        chainId: string;
+        address: string;
+        nonce: string;
+        r: string;
+        s: string;
+        yParity: string;
+    };
+}
+interface RelayUserOpResponse {
+    userOpHash: Hex;
+}
+interface SponsorshipUserOp {
+    sender: Address;
+    nonce: bigint;
+    callData: Hex;
+    callGasLimit: bigint;
+    verificationGasLimit: bigint;
+    preVerificationGas: bigint;
+    maxFeePerGas: bigint;
+    maxPriorityFeePerGas: bigint;
+}
+interface SponsorshipTarget {
+    contract: Address;
+    function: string;
+    pointToken: Address;
+}
+interface SponsorshipRequest {
+    chainId: number;
+    scenario: string;
+    userOp: SponsorshipUserOp;
+    target: SponsorshipTarget;
+    /**
+     * EIP-7702 authorization tuple — REQUIRED for the `delegate`
+     * scenario so Pimlico's `pm_sponsorUserOperation` can simulate the
+     * UserOp with the EOA already delegated. Without it, simulator
+     * reverts `AA20 account not deployed` (chicken-and-egg: the same
+     * UserOp anchors the delegation).
+     *
+     * Optional for non-delegate scenarios where the sender already
+     * has bytecode (i.e. delegated previously). v0.7.5 added.
+     */
+    eip7702Auth?: {
+        chainId: string;
+        address: string;
+        nonce: string;
+        r: string;
+        s: string;
+        yParity: string;
+    };
+}
+interface SponsorshipResponse {
+    paymaster: Address;
+    paymasterData: Hex;
+    paymasterVerificationGasLimit: bigint;
+    paymasterPostOpGasLimit: bigint;
+    /**
+     * Pimlico's `pm_sponsorUserOperation` re-estimates these gas fields
+     * and signs its paymaster signature over the new values. Callers
+     * MUST overwrite the matching userOp fields with these BEFORE
+     * computing the EIP-712 userOpHash and submitting to the bundler.
+     * Otherwise both `AA34` (paymaster sig) and `AA24` (sender sig) will
+     * fire — the EntryPoint hashes the actual on-chain field values, and
+     * a mismatch invalidates every sig over the hash.
+     */
+    callGasLimit?: bigint;
+    verificationGasLimit?: bigint;
+    preVerificationGas?: bigint;
+    /**
+     * Bundler-required gas price (Pimlico's `pimlico_getUserOperationGasPrice`
+     * fast tier). Pimlico's paymaster signs over these — caller MUST apply
+     * to the userOp before computing the EIP-712 userOpHash. Base RPC's
+     * `eth_feeHistory` underestimates the bundler floor by 10-15 %, so
+     * relying on it produces "maxFeePerGas must be at least ..." rejections.
+     */
+    maxFeePerGas?: bigint;
+    maxPriorityFeePerGas?: bigint;
+    expiresAt: number;
+}
+declare class PafiBackendClient {
+    private readonly config;
+    private readonly baseUrl;
+    constructor(config: PafiBackendConfig);
+    requestSponsorship(request: SponsorshipRequest): Promise<SponsorshipResponse>;
+    /**
+     * Fetch ERC-4337 UserOp receipt via PAFI's authenticated bundler proxy.
+     * Returns `null` when the bundler hasn't seen the userOp yet — caller
+     * should keep polling. Used by status endpoints to short-circuit the
+     * on-chain indexer when several PENDING locks share the same amount.
+     */
+    getUserOpReceipt(userOpHash: Hex): Promise<{
+        success: boolean;
+        txHash: Hex;
+        blockNumber: string;
+    } | null>;
+    relayUserOperation(request: RelayUserOpRequest): Promise<RelayUserOpResponse>;
+    private _doRequest;
+}
+
+/**
+ * Status snapshot returned to mobile clients polling a mint lock.
+ * Matches the legacy gg56 shape so existing FE code keeps working.
+ */
+interface MintStatusResponse {
+    lockId: string;
+    status: "PENDING" | "MINTED" | "EXPIRED" | "FAILED";
+    txHash: Hex | null;
+    amount: string;
+    createdAt: string;
+    expiresAt: string;
+}
+interface BurnStatusResponse {
+    lockId: string;
+    status: "PENDING" | "RESOLVED" | "EXPIRED";
+    txHash: Hex | null;
+    amount: string;
+    createdAt: string;
+    expiresAt: string;
+    resolvedAt?: string | null;
+}
+interface MintStatusParams {
+    lockId: string;
+    /** User EOA from auth — handler returns 404 if the lock isn't theirs. */
+    userAddress: Address;
+    ledger: IPointLedger;
+    /**
+     * PAFI backend client for the bundler-receipt fallback. Optional —
+     * when omitted, status only reflects what the on-chain `PointIndexer`
+     * has finalized into the ledger. With it, the handler queries the
+     * bundler receipt when:
+     *   - lock.status === "PENDING"
+     *   - lock.userOpHash is bound (set by `/claim/submit`)
+     *
+     * If the bundler reports the UserOp confirmed AND the receipt block
+     * is past the configured `confirmations` depth, the handler updates
+     * the ledger lock + returns `MINTED` immediately, bypassing
+     * `PointIndexer`'s amount-based race (multiple PENDING locks with
+     * the same amount can be matched to the wrong tx_hash).
+     */
+    pafiBackendClient?: PafiBackendClient | null;
+    /**
+     * Guard for the bundler-receipt fallback. The bundler returns success at zero
+     * confs, but `PointIndexer` enforces a 3-block reorg window;
+     * crediting / debiting off-chain at 0 confs while the indexer waits
+     * for finality leaves an unbacked durable mutation if the tx is
+     * reorged out. Pass the SAME PublicClient that the indexer uses so
+     * both paths see consistent chain head. Optional only for legacy
+     * callers that don't supply `pafiBackendClient`; required whenever
+     * the receipt-fallback path can run.
+     */
+    provider?: PublicClient;
+    /**
+     * Confirmation depth required before the receipt
+     * fallback applies the credit / debit. MUST match
+     * `PointIndexer.confirmations` (default 3). Operators who reduce
+     * the indexer depth must set this to the same value.
+     */
+    confirmations?: number;
+    /** Optional logger for "ledger update failed" warnings. */
+    onWarning?: (msg: string) => void;
+}
+interface BurnStatusParams {
+    lockId: string;
+    userAddress: Address;
+    ledger: IPointLedger;
+    pafiBackendClient?: PafiBackendClient | null;
+    /**
+     * BurnStatusParams.provider` for full
+     * rationale. The receipt-fallback path applies a spendable
+     * off-chain credit; without a confirmation-depth gate a reorg
+     * before `BurnIndexer.confirmations` leaves durable unbacked
+     * credit with no reversal mechanism.
+     */
+    provider?: PublicClient;
+    /**
+     * Confirmation depth required before the receipt
+     * fallback applies the credit. MUST match
+     * `BurnIndexer.confirmations` (default 3).
+     */
+    confirmations?: number;
+    onWarning?: (msg: string) => void;
+}
+declare class LockNotFoundError extends PafiSdkError {
+    readonly code = "LOCK_NOT_FOUND";
+    readonly httpStatus: "not_found";
+    constructor();
+}
+
+/**
+ * Handle GET /claim/status/:lockId.
+ *
+ * Returns the lock's current state from the ledger. When the ledger
+ * supports `userOpHash` binding AND the lock is still PENDING, falls
+ * back to the bundler receipt — the canonical truth that bypasses
+ * `PointIndexer`'s amount-based matching race.
+ *
+ * Throws `LockNotFoundError` when the lock doesn't exist or doesn't
+ * belong to `userAddress`. Caller maps to HTTP 404.
+ */
+declare function handleClaimStatus(params: MintStatusParams): Promise<MintStatusResponse>;
+/**
+ * Handle GET /redeem/status/:lockId. Symmetric to `handleClaimStatus`
+ * for the burn → off-chain credit flow.
+ *
+ * Bundler-receipt fallback resolves the credit via
+ * `ledger.resolveCreditByBurnTx` when the bundler reports the burn
+ * UserOp succeeded.
+ */
+declare function handleRedeemStatus(params: BurnStatusParams): Promise<BurnStatusResponse>;
+
+/**
+ * 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;
+        /**
+         * Lock id (PendingCredit on redeem, LockedMint on claim) reserved
+         * for the FALLBACK path — distinct from the outer entry's
+         * sponsored lock because the on-chain amount the user burns/mints
+         * differs between variants.
+         *
+         * If `handleMobileSubmit.bindUserOpHash` bound the submitted
+         * userOpHash to the SPONSORED lockId even when the user submitted
+         * the fallback variant, the bundler-receipt fallback in
+         * `handleRedeemStatus` would resolve the sponsored credit
+         * (`amount - fee`) against the on-chain burn of the FULL `amount`
+         * — every fee-bearing fallback redeem would permanently
+         * under-credit the user by exactly the fee. Surface the fallback
+         * lockId here so submit can route the bind to the correct ledger
+         * row.
+         */
+        lockId?: string;
+    };
+    /**
+     * EIP-7702 authorization tuple — present only on the `delegate`
+     * scenario where the UserOp anchors the EOA's one-time delegation
+     * to a 7702 implementation. Embedded into the eth_sendUserOperation
+     * payload at submit time so Pimlico bundler applies the bytecode
+     * atomically with the UserOp execution. Pre-computed at prepare
+     * time from the user's `signAuthorization` signature so submit
+     * doesn't need to re-derive it.
+     *
+     * v0.7.7 — added per delegate-flow refactor (mobile prepare/submit).
+     */
+    eip7702Auth?: {
+        chainId: string;
+        address: string;
+        nonce: string;
+        r: string;
+        s: string;
+        yParity: string;
+    };
+}
+/**
+ * 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>;
+
+/**
+ * In-memory `IPendingUserOpStore` for **single-instance dev / test
+ * harnesses only**.
+ *
+ * Multi-instance deployments (k8s, PM2 cluster) MUST use a shared store
+ * — typically Redis with a TTL key or Postgres with `expires_at`. If
+ * `prepare` lands on instance A and `submit` on instance B, an
+ * in-memory store on A loses the entry.
+ *
+ * Entries are evicted lazily on `get()` if expired. Periodic sweep is
+ * not implemented — the in-memory map's footprint scales with
+ * outstanding pending UserOps, which is bounded by the issuer's lock
+ * duration (default 15 min).
+ */
+declare class MemoryPendingUserOpStore implements IPendingUserOpStore {
+    private readonly entries;
+    private readonly now;
+    constructor(now?: () => number);
+    save(lockId: string, entry: PendingUserOpEntry, ttlSeconds: number): Promise<void>;
+    get(lockId: string): Promise<PendingUserOpEntry | null>;
+    delete(lockId: string): Promise<void>;
+}
+
+/**
+ * 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.
+ *
+ * `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
+ *
+ * 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.
+ *
+ * Skips fields that are undefined so legacy paymaster responses
+ * (without re-estimated gas) don't accidentally zero out the original
+ * estimates.
+ */
+/**
+ * Subset of `SponsorshipResponse` consumed by the merge/hash helpers.
+ * Inlined as a structural type (rather than importing
+ * `SponsorshipResponse` from `pafi-backend/client`) to keep
+ * `userop-store` independent of the HTTP-client module.
+ */
+interface PaymasterGasEstimates {
+    paymaster: Address;
+    paymasterData: Hex;
+    paymasterVerificationGasLimit: bigint;
+    paymasterPostOpGasLimit: bigint;
+    callGasLimit?: bigint;
+    verificationGasLimit?: bigint;
+    preVerificationGas?: bigint;
+    maxFeePerGas?: bigint;
+    maxPriorityFeePerGas?: bigint;
+}
+declare function mergePaymasterFields<T extends object>(userOp: T, paymasterFields: PaymasterGasEstimates | undefined): T;
+interface PreparedUserOp {
+    /** The bundler-ready UserOp (with paymaster + Pimlico-quoted gas). */
+    userOp: PartialUserOperation & {
+        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;
+}
+/**
+ * Atomic "merge paymaster fields + compute hash + build typed data" —
+ * the only place the SDK should be doing all three operations.
+ *
+ * Why bundled into one call:
+ *
+ *   Pimlico's `pm_sponsorUserOperation` re-estimates
+ *   `callGasLimit` / `verificationGasLimit` / `preVerificationGas` and
+ *   the bundler fee fields (`maxFeePerGas` / `maxPriorityFeePerGas`),
+ *   then signs `paymasterData` over the new values. The EntryPoint
+ *   hashes the actual on-chain field values during validation, so
+ *   callers MUST overwrite the matching userOp fields BEFORE
+ *   computing the userOpHash. Forgetting any field triggers AA34
+ *   (paymaster signature mismatch) and/or AA24 (sender signature
+ *   mismatch) — opaque failures that take hours to debug.
+ *
+ *   Splitting "merge" and "hash" into two free functions invites
+ *   exactly this bug: each call site has to reinvent the merge logic,
+ *   and any drift between sites silently produces stale hashes.
+ *   Returning all three pieces (`userOp`, `userOpHash`, `typedData`)
+ *   from a single call makes "hash before merge" structurally
+ *   impossible: there is no intermediate userOp to compute a stale
+ *   hash over.
+ *
+ * Behaviour:
+ *   - When `paymasterFields` is undefined (paymaster declined / Path
+ *     C self-pay), the result is just the hash + typed-data of the
+ *     caller's `partialUserOp` — no fields are touched.
+ *   - When provided, only defined keys in `paymasterFields` overwrite
+ *     the matching fields. Original gas/fee estimates survive when
+ *     the paymaster did not re-estimate.
+ *
+ * Replaces:
+ *   - manual spread merges (e.g. previous `delegateHandler.ts`)
+ *   - `mergePaymasterFields` + separate `computeUserOpHash` +
+ *     `buildUserOpTypedData` triplets in any new call site.
+ *
+ * Note: the original `mergePaymasterFields` and the raw
+ * `computeUserOpHash` / `buildUserOpTypedData` exports remain
+ * available — use this helper unless you have a specific reason to
+ * stage the operations.
+ */
+declare function applyPaymasterGasEstimates(partialUserOp: PartialUserOperation & {
+    maxFeePerGas: bigint;
+    maxPriorityFeePerGas: bigint;
+}, paymasterFields: PaymasterGasEstimates | undefined, chainId: number): PreparedUserOp;
+interface PrepareMobileUserOpParams {
+    /** Lock id (issuer-generated) keying both store entry + ledger row. */
+    lockId: string;
+    /**
+     * 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;
+    };
+    /**
+     * Optional separate lock id for the FALLBACK path — required when
+     * the upstream handler reserves a DIFFERENT ledger row for the
+     * fallback variant (PTRedeemHandler reserves
+     * `amount` for fallback vs `amount - fee` for sponsored).
+     *
+     * When omitted, `handleMobileSubmit` binds the fallback userOpHash
+     * to the outer sponsored `lockId`, which makes
+     * `handleRedeemStatus`'s bundler-receipt fallback resolve the
+     * SMALLER sponsored credit against the on-chain burn of the FULL
+     * amount — every fee-bearing fallback redeem then permanently
+     * under-credits the user by exactly the fee. Pass the fallback
+     * lockId here so submit can route the bind to the correct row.
+     */
+    lockIdFallback?: string;
+    /** 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;
+    /**
+     * Optional EIP-7702 authorization tuple. Persisted in the store entry
+     * so `handleMobileSubmit` can replay it to the bundler at submit time.
+     * NOT folded into the UserOp hash — Pimlico applies SetCode atomically
+     * but the authorization itself is a top-level field of
+     * `eth_sendUserOperation`, not part of `PackedUserOperation`. Hash
+     * stays stable so the user's typed-data signature remains valid.
+     */
+    eip7702Auth?: {
+        chainId: string;
+        address: string;
+        nonce: string;
+        r: string;
+        s: string;
+        yParity: string;
+    };
+}
+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 PafiSdkError {
+    readonly code = "PENDING_USEROP_NOT_FOUND";
+    readonly httpStatus: "not_found";
+    constructor(lockId: string);
+}
+/**
+ * Thrown when the authenticated user attempts to submit a pending
+ * UserOp that belongs to a different sender. Map to 403.
+ *
+ * The pending-userop store is keyed by `lockId` (a UUID), but lockIds
+ * are predictable by anyone who logs them — without this check, user A
+ * could submit user B's UserOp once they leak/guess the lockId. The
+ * UserOp signature itself recovers to user B (so on-chain it would
+ * fail), but the issuer would still bind the bundler hash to user B's
+ * lock and consume relay quota, enabling DoS / state pollution.
+ */
+declare class PendingUserOpForbiddenError extends PafiSdkError {
+    readonly code = "PENDING_USEROP_FORBIDDEN";
+    readonly httpStatus: "forbidden";
+    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;
+    /**
+     * Optional separate lock id for the fallback path. Required when the
+     * upstream handler (e.g. PTRedeemHandler) reserves a DIFFERENT
+     * ledger row for the fallback variant. See `prepareMobileUserOp`
+     * for the full rationale.
+     */
+    lockIdFallback?: string;
+    /**
+     * 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;
+    /**
+     * Optional EIP-7702 authorization tuple supplied by an FE that wants
+     * atomic activation — the user signs the auth alongside the UserOp
+     * typed-data, and the bundler applies SetCode + handleOps in one
+     * bundler tx. When provided:
+     *   - `needsDelegation` is forced false (the bundler will activate
+     *     delegation regardless of current on-chain code).
+     *   - The auth is persisted in the pending-userop entry and replayed
+     *     to the bundler at submit time.
+     *
+     * Format matches Pimlico's `eth_sendUserOperation` `eip7702Auth` field.
+     * The FE typically derives it from `useSign7702Authorization()` and
+     * normalises with `attachDelegationIfNeeded()` in `@pafi-dev/core`.
+     */
+    eip7702Auth?: {
+        chainId: string;
+        address: string;
+        nonce: string;
+        r: string;
+        s: string;
+        yParity: string;
+    };
+}
+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;
+    /**
+     * Authenticated user EOA — extracted from the JWT / session by the
+     * caller. Enforces ownership: the helper rejects with
+     * `PendingUserOpForbiddenError` when `entry.sender !==
+     * authenticatedAddress`.
+     */
+    authenticatedAddress: Address;
+    /** 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.
+ *   - `PendingUserOpForbiddenError` — `entry.sender` doesn't match the
+ *     authenticated user. Map to 403.
+ *   - `BundlerNotConfiguredError` — `pafiBackendClient` missing. Map to 503.
+ *   - `BundlerRejectedError` — bundler rejected the UserOp. Map to 422.
+ */
+declare function handleMobileSubmit(params: HandleMobileSubmitParams): Promise<{
+    userOpHash: Hex;
+}>;
+
+type DecodedCall$1 = ReturnType<typeof decodeBatchExecuteCalls>[number];
+
+/**
+ * Structural shape — accepts both the raw `IssuerStateValidator` from
+ * `@pafi-dev/issuer/issuer-state` and any host-framework wrapper (e.g.
+ * a NestJS Injectable that delegates to it). Only `preValidateMint`
+ * is needed on this surface.
+ */
+interface IssuerStateValidatorLike {
+    preValidateMint(pointToken: Address, amount: bigint): Promise<unknown>;
+}
+/**
+ * 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.
+ */
+type PTClaimErrorCode = "INVALID_AMOUNT" | "VALIDATION_FAILED" | "BUILD_FAILED" | "NONCE_READ_FAILED" | "NONCE_IN_FLIGHT" | "UNSUPPORTED_POINT_TOKEN";
+declare class PTClaimError extends PafiSdkError {
+    readonly httpStatus: "unprocessable";
+    readonly code: PTClaimErrorCode;
+    readonly details?: Record<string, unknown>;
+    constructor(code: PTClaimErrorCode, message: string, details?: Record<string, unknown>);
+}
+interface PTClaimHandlerConfig {
+    ledger: IPointLedger;
+    relayService: RelayService;
+    provider: PublicClient;
+    /** Issuer minter signer wallet — passed through to RelayService.prepareMint. */
+    issuerSignerWallet: WalletClient;
+    /**
+     * Resolver for the EIP-712 domain `name` (= PointToken.name() on-chain).
+     * Required because mint routes the `pointTokenAddress` per request —
+     * the handler can't bind a single domain at construction. Pass a
+     * shared resolver instance so mint + redeem amortise the same cache.
+     * `chainId` + `verifyingContract` are derived from the request's
+     * `chainId` + `pointTokenAddress` respectively.
+     */
+    domainResolver: PointTokenDomainResolver;
+    /**
+     * Issuer's allow-listed PointToken contracts (checksummed EIP-55).
+     * Every `handle()` call validates the request's `pointTokenAddress`
+     * against this set BEFORE any chain read or signer call.
+     *
+     * write surface (claim/redeem) previously skipped it. The asymmetry
+     * meant an issuer signer whitelisted as minter on PointTokens
+     * outside the configured indexer set could be coerced into signing
+     * a valid `MintForRequest` for an off-set token — the on-chain
+     * mint would succeed, but no PointIndexer was watching to debit the
+     * off-chain ledger. Silent supply-invariant violation.
+     *
+     * Pass the SAME set used to construct `IssuerApiHandlers` so the
+     * read and write paths agree on what this issuer is willing to
+     * sign for.
+     */
+    supportedTokens: ReadonlySet<Address>;
+    /** Optional — when wired, used to estimate the PT gas-reimbursement fee. */
+    feeService?: FeeManager;
+    /** Optional — pre-validates issuer status + cap before locking balance. */
+    issuerStateValidator?: IssuerStateValidatorLike;
+    /** 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;
+    /**
+     * Optional override for the MintFeeWrapper address. By default the
+     * handler auto-resolves the wrapper from the request's `chainId` via
+     * `getContractAddresses(chainId).mintFeeWrapper`. Set this only when:
+     *   - testing against a non-canonical wrapper deploy, or
+     *   - the SDK's hardcoded address is stale and you can't bump the SDK yet
+     *
+     * Pass the dead-zero address to opt OUT of the wrapper path (force direct
+     * mint with no fee). Pass `undefined` (default) to use SDK's lookup.
+     *
+     * Caller responsibility either way:
+     *   - DAO must have called `IssuerRegistry.setMintFeeWrapper(...)` so
+     *     `addIssuer` cascades the recipient list.
+     *   - The PointToken must have been registered with the wrapper (via
+     *     `addIssuer` cascade or owner-only `wrapper.registerToken`).
+     */
+    mintFeeWrapperAddress?: Address;
+}
+interface PTClaimRequest {
+    authenticatedAddress: Address;
+    userAddress: Address;
+    amount: bigint;
+    pointTokenAddress: Address;
+    chainId: number;
+    /** ERC-4337 account nonce for the user's EOA. */
+    aaNonce: 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$1[];
+    /** Decoded calls for the fallback UserOp (when present). */
+    callsFallback?: DecodedCall$1[];
+}
+declare class PTClaimHandler {
+    private readonly cfg;
+    private readonly inFlightNonces;
+    constructor(config: PTClaimHandlerConfig);
+    handle(request: PTClaimRequest): Promise<PTClaimResponse>;
+}
+
+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** — USDC.transfer(fee, PAFI) + USDC.approve(relay,
+ *     total) + Relay.deposit(req). User reimburses gas in USDC
+ *     (input-token rule — user holds USDC at start of batch).
+ *   - **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`).
+ *
+ * v0.7 — Switched gas fee from PT (output-side, mixed token UX) to
+ * USDC (input-side, single token UX). User now only needs USDC to
+ * complete the deposit, no separate PT balance required.
+ */
+type PerpDepositErrorCode = "PERP_DEPOSIT_UNAVAILABLE" | "BROKER_NOT_WHITELISTED" | "RELAY_FEE_EXCEEDS_AMOUNT" | "FEE_EXCEEDS_AMOUNT" | "INVALID_AMOUNT";
+declare class PerpDepositError extends PafiSdkError {
+    readonly httpStatus: "unprocessable";
+    readonly code: PerpDepositErrorCode;
+    readonly safeToRetry: boolean;
+    constructor(code: PerpDepositErrorCode, message: string);
+}
+interface PerpDepositHandlerConfig {
+    provider: PublicClient;
+    /**
+     * 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;
+    /**
+     * Gas units used by `quoteOperatorFeeUsdt` to size the USDC gas
+     * reimbursement. Default 500_000 (covers approve + Relay.deposit
+     * + LayerZero call). Pass a tighter Pimlico estimate if available.
+     */
+    gasUnits?: bigint;
+    /** Premium bps for `quoteOperatorFeeUsdt`. Default 12_000 (1.2×). */
+    gasPremiumBps?: 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>;
+}
+
+interface HandleDelegateSubmitParams {
+    lockId: string;
+    /** Authenticated user EOA — must match the entry's `sender`. */
+    authenticatedAddress: Address;
+    /** User signature over the persisted userOpHash. */
+    userOpSig: Hex;
+    store: IPendingUserOpStore;
+    pafiBackendClient?: PafiBackendClient | null;
+    /** Defaults to `ENTRY_POINT_V08`. */
+    entryPoint?: string;
+}
+interface HandleDelegateSubmitResult {
+    userOpHash: Hex;
+}
+/**
+ * Retrieve the persisted delegate UserOp, embed the user's signature,
+ * and submit to the bundler with the cached `eip7702Auth` field.
+ *
+ * Throws:
+ *   - `PendingUserOpNotFoundError` — entry expired or already submitted (404)
+ *   - `PendingUserOpForbiddenError` — sender mismatch (403)
+ *   - `BundlerNotConfiguredError` — `pafiBackendClient` missing (503)
+ *   - `BundlerRejectedError` — bundler rejected the UserOp (422)
+ */
+declare function handleDelegateSubmit(params: HandleDelegateSubmitParams): Promise<HandleDelegateSubmitResult>;
+
+/**
+ * Normalized HTTP status the issuer controller should surface for a
+ * given SDK error. Mirrors `SdkErrorHttpStatus` on `PafiSdkError`.
+ */
+type SdkErrorStatus = SdkErrorHttpStatus;
+/**
+ * Structured body the issuer controller passes to its
+ * framework-specific exception class. Stripe-style envelope:
+ *
+ * ```json
+ * {
+ *   "type": "business_logic_error",
+ *   "code": "REDEMPTION_POLICY_DENIED",
+ *   "message": "...",
+ *   "param": null,
+ *   "metadata": { "policyDenialCode": "PER_TX_MIN" },
+ *   "safeToRetry": false
+ * }
+ * ```
+ *
+ * Carries enough fields for the global HTTP filter to emit the final
+ * envelope without losing any SDK-side context.
+ */
+interface SdkErrorBody {
+    /** Stripe-style taxonomy slot — drives UI branching. */
+    type: PafiErrorType;
+    /** Machine-readable code, e.g. `"REDEMPTION_POLICY_DENIED"`. */
+    code: string;
+    /** Human-readable message. */
+    message: string;
+    /** Field name that triggered the error, when applicable. */
+    param?: string;
+    /** UI-facing structured context. */
+    metadata?: Record<string, unknown>;
+    /** Raw debug context. */
+    details?: unknown;
+    /** True when retry is safe (no side effects yet). */
+    safeToRetry: boolean;
+}
+/**
+ * Per-status exception factories. The issuer's controller wires one
+ * factory per status to its preferred framework's exception class
+ * (NestJS `UnprocessableEntityException`, Fastify `httpErrors.badData`,
+ * etc). The factory must return an Error — `createSdkErrorMapper`
+ * uses `throw factory(body)`.
+ */
+interface SdkErrorMapperFactories {
+    notFound: (body: SdkErrorBody) => Error;
+    forbidden: (body: SdkErrorBody) => Error;
+    unprocessable: (body: SdkErrorBody) => Error;
+    serviceUnavailable: (body: SdkErrorBody) => Error;
+}
+/**
+ * Build the Stripe-style body from any `PafiSdkError`. Exposed for
+ * frameworks that don't fit the four-factory shape (e.g. a Hono error
+ * handler that builds its own response object).
+ */
+declare function buildSdkErrorBody(err: PafiSdkError): SdkErrorBody;
+/**
+ * Build a single error-mapping function that converts any `PafiSdkError`
+ * into the issuer's framework-specific HTTP exception. Status, code,
+ * `safeToRetry`, and `details` come straight off the error class —
+ * the mapper is a dumb funnel, no per-error business logic.
+ *
+ * Any non-`PafiSdkError` is re-thrown unchanged so unexpected runtime
+ * errors propagate to the framework's default 500 handler.
+ *
+ * Usage (NestJS):
+ *
+ * ```ts
+ * const mapSdkError = createSdkErrorMapper({
+ *   notFound: (body) => new NotFoundException(body),
+ *   forbidden: (body) => new ForbiddenException(body),
+ *   unprocessable: (body) => new UnprocessableEntityException(body),
+ *   serviceUnavailable: (body) => new ServiceUnavailableException(body),
+ * });
+ *
+ * try { ... } catch (err) { mapSdkError(err); }
+ * ```
+ *
+ * Returns `never` so call sites in `try/catch` propagate the throw
+ * without a redundant `throw` keyword.
+ */
+declare function createSdkErrorMapper(factories: SdkErrorMapperFactories): (err: unknown) => never;
+
+/**
+ * Top-level configuration for `createIssuerService`.
+ *
+ * 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:** 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,
+     * mintFeeWrapper, …) 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;
+    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.
+         *
+         * **SAFETY:** in a multi-replica deployment, ALWAYS pair
+         * `autoStart: true` with `singletonLock` below. Without leader
+         * election, every replica starts its own indexer fleet and races
+         * against the others — see `ISingletonLock` docs for the
+         * consequences.
+         */
+        autoStart?: boolean;
+        /**
+         * Leader-election primitive. When provided, the factory wraps
+         * `indexer.start()` with a `singletonLock.acquire(key)` call and
+         * only starts the indexer if it wins the lock. Non-leaders stay
+         * idle and take over on the next acquire attempt (when the leader
+         * pod's connection drops, the lock auto-releases).
+         *
+         * The lock key includes the indexer kind + the PointToken address,
+         * so different tokens can be sharded across replicas if desired.
+         *
+         * Recommended: `makePostgresSingletonLock(dataSource)`.
+         */
+        singletonLock?: ISingletonLock;
+        /**
+         * Override the MintFeeWrapper address used by the indexer. When
+         * omitted, the factory auto-resolves from
+         * `getContractAddresses(chainId).mintFeeWrapper`. Pass the
+         * dead-zero address (`0x...dEaD`) to force direct-Transfer mode
+         * (useful for local fork tests).
+         */
+        mintFeeWrapperAddress?: Address;
+    };
+    /**
+     * Redemption restriction config. When provided, the SDK fetches the
+     * per-issuer policy from PAFI issuer-api (with 5min cache + default
+     * fallback) and exposes preview/evaluate via `service.redemption`.
+     * The handler endpoints `handleRedemptionPreview` / `handleRedemptionEvaluate`
+     * are wired only when this is configured.
+     *
+     * `chainId` is taken from the top-level config; the issuer-api URL
+     * is looked up via `getPafiServiceUrls(chainId)`. Only credentials
+     * + the history store are required here.
+     */
+    redemption?: {
+        issuerId: string;
+        apiKey: string;
+        historyStore: IRedemptionHistoryStore;
+        /**
+         * Optional override for the PAFI issuer-api base URL. Audit
+         * env var (e.g. `PAFI_ISSUER_API_URL`) so policy fetch hits the
+         * canonical environment for the deploy. Undefined → SDK
+         * ship-default per chainId.
+         */
+        baseUrl?: string;
+        /**
+         * Behavior khi settlement-api fetch fail. Default `'fail-closed'`
+         * Opt in to `'permissive-default'` ONLY when paired with an alert
+         * on the `policy_provider_fallback` event surfaced via
+         * `onPolicyWarning`.
+         */
+        onFetchFailure?: "fail-closed" | "permissive-default";
+        /**
+         * Observability hook for `policy_provider_fallback` events. Wire
+         * to your logger / Sentry / Datadog so the on-call dashboard sees
+         * settlement-api degradation.
+         */
+        onPolicyWarning?: (msg: string, ctx: Record<string, unknown>) => void;
+        /** Override fetch (testing). */
+        fetchImpl?: typeof fetch;
+        /** Per-fetch timeout in ms. Default 1000. */
+        fetchTimeoutMs?: number;
+        /** Cache TTL in ms. Default 5 * 60 * 1000. */
+        cacheTtlMs?: number;
+    };
+}
+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>;
+    /**
+     * Lock handles for the indexers this replica was elected leader for.
+     * Empty when `autoStart` is false, or when no `singletonLock` was
+     * provided. Call `release()` on each during graceful shutdown so
+     * peers can take over without waiting for the connection to die.
+     */
+    indexerLeaderLocks: SingletonLockHandle[];
+    /** Framework-agnostic HTTP handlers — wire into Express / Fastify / Hono. */
+    api: IssuerApiHandlers;
+    /**
+     * Redemption restriction service. Undefined when `redemption` is not
+     * configured — the corresponding handlers throw "not configured" at
+     * request time.
+     */
+    redemption: RedemptionService | undefined;
+}
+/**
+ * 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): Promise<IssuerService>;
+
+/**
+ * Adapter that absorbs every "framework-agnostic" endpoint body into a
+ * single class so issuer controllers stay thin (one line per endpoint).
+ *
+ * What this absorbs:
+ *   - Reading + reshaping IssuerApiHandlers responses into wire DTOs
+ *     (bigint → string, etc.)
+ *   - Composing handler.handle() output with sponsorAuth + decoded calls
+ *   - Wiring handleMobilePrepare / handleMobileSubmit / handleClaimStatus
+ *   - Building the EIP-7702 delegate UserOp + relay
+ *   - Quoting PT → USDT for the cashout preview
+ *
+ * What stays in the issuer controller:
+ *   - HTTP routing decorators (`@Get`, `@Post`, `@UseGuards`)
+ *   - Auth context extraction (`@User() user: AuthContext`)
+ *   - Body DTO classes (with framework-specific decorators)
+ *   - Nonce composer (issuer-specific; e.g. gg56 uses 2D timestamp keys)
+ *
+ * Every method that can throw a typed SDK error throws `PafiSdkError` —
+ * the controller wraps every call with `try/catch + mapSdkError`, or
+ * the adapter pre-binds an `errorMapper` and auto-translates.
+ */
+interface IssuerApiAdapterConfig {
+    issuerService: IssuerService;
+    ledger: IPointLedger;
+    provider: PublicClient;
+    /** Issuer signer wallet — used for `buildSponsorAuth` (EIP-712 sign). */
+    issuerSignerWallet: WalletClient;
+    /** Optional issuer id — when omitted, sponsorAuth is skipped (returns `undefined`). */
+    pafiIssuerId?: string;
+    /** Sig-gated mint handler. Required for `claim` / `claimPrepare`. */
+    ptClaimHandler?: PTClaimHandler | null;
+    /** Reverse-flow handler. Required for `redeem` / `redeemPrepare`. */
+    ptRedeemHandler?: PTRedeemHandler | null;
+    /** Orderly perp-deposit handler. Required for `perpDeposit`. */
+    perpHandler?: PerpDepositHandler | null;
+    /** Pending UserOp store — required for mobile prepare/submit. */
+    pendingUserOpStore: IPendingUserOpStore;
+    /** PAFI backend client — required for mobile submit + delegate submit + status fallback. */
+    pafiBackendClient?: PafiBackendClient | null;
+    /** Optional logger surface for non-fatal warnings. */
+    onWarning?: (msg: string) => void;
+}
+interface ConfigDto {
+    chainId: number;
+    contracts: Record<string, string | undefined>;
+}
+interface GasFeeDto {
+    gasFeeUsdt: string;
+}
+interface PoolsDto {
+    pools: unknown[];
+}
+interface UserDto {
+    offChainBalance: string;
+    onChainBalance: string;
+    totalBalance: string;
+    /** @deprecated alias for `offChainBalance` */
+    balance: string;
+    isMinter: boolean;
+}
+interface DecodedCallDto {
+    to: string;
+    data: string;
+    value: string;
+}
+interface ClaimDto {
+    calls: DecodedCallDto[];
+    callsFallback?: DecodedCallDto[];
+    feeAmount: string;
+    lockId: string;
+    signatureDeadline: string;
+    sponsorAuth?: BuiltSponsorAuth;
+}
+interface RedeemDto {
+    calls: DecodedCallDto[];
+    callsFallback?: DecodedCallDto[];
+    feeAmount: string;
+    lockId: string;
+    lockIdFallback?: string;
+    netCreditAmount: string;
+    netCreditAmountFallback?: string;
+    expiresInSeconds: number;
+    signatureDeadline: string;
+    sponsorAuth?: BuiltSponsorAuth;
+}
+interface PerpDepositDto {
+    calls: DecodedCallDto[];
+    callsFallback?: DecodedCallDto[];
+    relayTokenFee: string;
+    maxFee: string;
+    netDeposit: string;
+    ptGasFee: string;
+    accountId: Hex;
+    brokerHash: Hex;
+    usdcAddress: Address;
+    relayAddress: Address;
+    sponsorAuth?: BuiltSponsorAuth;
+}
+interface MobilePrepareDto {
+    lockId: string;
+    userOpHash: Hex;
+    typedData: SerializedUserOpTypedData;
+    userOpHashFallback?: Hex;
+    typedDataFallback?: SerializedUserOpTypedData;
+    feeAmount: string;
+    signatureDeadline: string;
+    expiresInSeconds: number;
+    sponsored: boolean;
+    needsDelegation: boolean;
+}
+interface RedeemPrepareDto extends MobilePrepareDto {
+    netCreditAmount: string;
+    netCreditAmountFallback?: string;
+    /**
+     * Lock id reserved for the FALLBACK redeem path (= full `amount`).
+     * Mobile FE polls `/redeem/status/:lockIdFallback` when it submits
+     * the fallback variant (`variant: 'fallback'` on `/redeem/submit`).
+     */
+    lockIdFallback?: string;
+}
+interface MobileSubmitDto {
+    userOpHash: Hex;
+}
+interface DelegateStatusDto {
+    isDelegated: boolean;
+    batchExecutorAddress: Address;
+    /**
+     * EOA tx count fetched on-chain via `getTransactionCount(blockTag: 'pending')`.
+     * Mobile passes this VERBATIM into Privy `signAuthorization({ ..., nonce })` —
+     * MUST NOT hardcode `0` or fetch independently. For a fresh embedded wallet
+     * it will be `"0"`, but re-delegation or post-activity wallets will be > 0.
+     * Returned as decimal string (preserves bigint precision over JSON).
+     */
+    delegationNonce: string;
+    chainId: number;
+}
+interface DelegatePrepareDto {
+    /**
+     * v0.7.7 — refactored to mobile prepare/submit pattern. Mobile signs
+     * the EIP-7702 authorization LOCALLY (Privy `signAuthorization`),
+     * then signs `userOpHash` (or `typedData`) BEFORE submit. See
+     * `handleDelegatePrepare` for rationale.
+     *
+     * Pre-v0.7.7 callers expected `{ authorizationHash, delegationNonce,
+     * batchExecutorAddress, chainId }` — `delegationNonce` +
+     * `batchExecutorAddress` retained for back-compat so mobile can
+     * compute the authorization hash if needed; `authorizationHash`
+     * removed (mobile's Privy hook computes it locally).
+     */
+    lockId: string;
+    userOpHash: Hex;
+    typedData: SerializedUserOpTypedData;
+    expiresInSeconds: number;
+    isSponsored: boolean;
+    /** Echoed for mobile to recompute the authorization hash if desired. */
+    delegationNonce: string;
+    batchExecutorAddress: Address;
+    chainId: number;
+}
+declare class AdapterMisconfiguredError extends Error {
+    readonly code: "ADAPTER_MISCONFIGURED";
+    constructor(message: string);
+}
+declare class IssuerApiAdapter {
+    private readonly cfg;
+    constructor(config: IssuerApiAdapterConfig);
+    config(chainId: number): Promise<ConfigDto>;
+    gasFee(): Promise<GasFeeDto>;
+    pools(authenticatedAddress: Address, chainId: number, pointTokenAddress: Address): Promise<PoolsDto>;
+    user(authenticatedAddress: Address, chainId: number, userAddress: Address, pointTokenAddress: Address): Promise<UserDto>;
+    claim(input: {
+        authenticatedAddress: Address;
+        chainId: number;
+        pointTokenAddress: Address;
+        amount: bigint;
+        aaNonce: bigint;
+    }): Promise<ClaimDto>;
+    redeem(input: {
+        authenticatedAddress: Address;
+        chainId: number;
+        pointTokenAddress: Address;
+        amount: bigint;
+        aaNonce: bigint;
+    }): Promise<RedeemDto>;
+    perpDeposit(input: {
+        authenticatedAddress: Address;
+        chainId: number;
+        amount: bigint;
+        brokerId: Parameters<PerpDepositHandler["handle"]>[0]["brokerId"];
+        aaNonce: bigint;
+    }): Promise<PerpDepositDto>;
+    claimPrepare(input: {
+        authenticatedAddress: Address;
+        chainId: number;
+        pointTokenAddress: Address;
+        amount: bigint;
+        aaNonce: bigint;
+        /**
+         * Optional EIP-7702 authorization tuple for atomic activation. When
+         * present, the mobile flow merges SetCode + UserOp into one bundler
+         * tx — no separate /delegate call required. See
+         * `attachDelegationIfNeeded` in `@pafi-dev/core`.
+         */
+        eip7702Auth?: {
+            chainId: string;
+            address: string;
+            nonce: string;
+            r: string;
+            s: string;
+            yParity: string;
+        };
+    }): Promise<MobilePrepareDto>;
+    claimSubmit(input: {
+        authenticatedAddress: Address;
+        lockId: string;
+        signature: Hex;
+        variant?: "sponsored" | "fallback";
+    }): Promise<MobileSubmitDto>;
+    redeemPrepare(input: {
+        authenticatedAddress: Address;
+        chainId: number;
+        pointTokenAddress: Address;
+        amount: bigint;
+        aaNonce: bigint;
+        /**
+         * Optional EIP-7702 authorization for atomic activation — see
+         * `claimPrepare` for the full rationale + Privy hook reference.
+         */
+        eip7702Auth?: {
+            chainId: string;
+            address: string;
+            nonce: string;
+            r: string;
+            s: string;
+            yParity: string;
+        };
+    }): Promise<RedeemPrepareDto>;
+    redeemSubmit(input: {
+        authenticatedAddress: Address;
+        lockId: string;
+        signature: Hex;
+        variant?: "sponsored" | "fallback";
+    }): Promise<MobileSubmitDto>;
+    claimStatus(authenticatedAddress: Address, lockId: string): Promise<MintStatusResponse>;
+    redeemStatus(authenticatedAddress: Address, lockId: string): Promise<BurnStatusResponse>;
+    delegateStatus(authenticatedAddress: Address, chainId: number): Promise<DelegateStatusDto>;
+    /**
+     * Build the delegation-anchor UserOp + obtain paymaster sponsorship
+     * + persist as a pending entry. Mobile must:
+     *
+     *   1. Sign EIP-7702 authorization LOCALLY (Privy `signAuthorization`
+     *      with `{contractAddress: batchExecutorAddress, chainId,
+     *      nonce: delegationNonce}`) → 65-byte authSig hex.
+     *   2. POST `/delegate/prepare` with `{ chainId, delegationNonce,
+     *      authSig }` → this method.
+     *   3. Sign returned `userOpHash` LOCALLY (`signTypedData(typedData)`).
+     *   4. POST `/delegate/submit` with `{ lockId, userOpSig }`.
+     *
+     * v0.7.7 — replaces single-shot delegateSubmit that tried to relay
+     * a UserOp with empty `signature: "0x"` (Simple7702Account's
+     * validateUserOp reverts `ECDSAInvalidSignatureLength` 0xfce698f7).
+     */
+    delegatePrepare(authenticatedAddress: Address, input: {
+        chainId: number;
+        delegationNonce: bigint;
+        authSig: Hex | string;
+        aaNonce: bigint;
+    }): Promise<DelegatePrepareDto>;
+    delegateSubmit(input: {
+        authenticatedAddress: Address;
+        lockId: string;
+        userOpSig: Hex;
+    }): Promise<MobileSubmitDto>;
+    /**
+     * Build + sign a SponsorAuth payload. Returns `undefined` when no
+     * issuer id is configured, so the controller can skip the field.
+     */
+    private buildSponsorAuth;
+    private runMobilePrepare;
+    private assertRedeemHandler;
+    /**
+     * Narrow an optional handler to non-null and throw a clear error when
+     * the issuer wired the adapter without it. Lets issuers opt out of
+     * flows they don't expose (gg56 ships only mobile claim/redeem, so
+     * `swapHandler` + `perpHandler` aren't constructed).
+     */
+    private assertHandler;
+}
+
+/**
+ * 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;
+    /**
+     * Optional error callback. Invoked on every recoverable error (subgraph
+     * unreachable, non-200 response, GraphQL errors, invalid pool payload).
+     * The provider continues to return `{ pools: [] }` on error and also
+     * logs via `console.warn`/`console.error`; this hook lets host apps
+     * forward errors to their own observability stack without parsing logs.
+     * Throwing inside this callback is swallowed so the provider remains
+     * total. (Addresses CODE_REVIEW issuer MEDIUM-5.)
+     */
+    onError?: (error: Error) => void;
+}
+/**
+ * Create a `PoolsProvider` backed by the PAFI subgraph.
+ *
+ * Queries the `pafiTokens` entity for the given `pointTokenAddress`,
+ * reads its linked V3 `Pool`, and returns a single-element `PoolKey[]`.
+ * Multiple pools per token would require a subgraph schema change.
+ *
+ * The result is cached in-process with a short TTL (default 30s). Pool
+ * 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,
+ *    invokes `onError` if provided; does not throw — callers should
+ *    handle empty pool list gracefully)
+ *
+ * Assumes the PAFI subgraph schema (`pafiToken { pool { id feeTier
+ * token0 { id } token1 { id } } }`). Issuers with a custom subgraph must
+ * implement `PoolsProvider` themselves instead of using this helper.
+ *
+ * @example
+ * ```ts
+ * import { createSubgraphPoolsProvider, createIssuerService } from "@pafi-dev/issuer";
+ *
+ * const service = createIssuerService({
+ *   // ...other config
+ *   poolsProvider: createSubgraphPoolsProvider({
+ *     subgraphUrl: "https://graph.pacificfinance.org/subgraphs/name/pafi",
+ *     onError: (err) => metrics.increment("issuer.pools.error", { reason: err.message }),
+ *   }),
+ * });
+ * ```
+ */
+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` — 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;
+    /**
+     * When true, the quoter throws on subgraph/Chainlink miss instead
+     * of returning the fallback price. Security-sensitive callers
+     * (e.g. sponsor-relayer's fee gate) MUST opt in so an attacker-
+     * supplied token with no indexed pool cannot ride the default
+     * fallback to a near-zero required fee. Issuer mint/burn paths
+     * default to the legacy fallback behavior for resilience against
+     * transient oracle hiccups.
+     */
+    failClosed?: boolean;
+    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>;
+
+/**
+ * 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 PafiSdkError {
+    readonly code = "BUNDLER_NOT_CONFIGURED";
+    readonly httpStatus: "service_unavailable";
+    constructor();
+}
+declare class BundlerRejectedError extends PafiSdkError {
+    readonly code = "BUNDLER_REJECTED";
+    readonly httpStatus: "unprocessable";
+    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 logs / paymaster context. Defaults to
+     * a per-scenario sensible value (`mint` / `burn` / `swap` / generic
+     * scenario name).
+     */
+    functionName?: string;
+    /**
+     * EIP-7702 authorization tuple — REQUIRED for the `delegate`
+     * scenario. Forwarded to sponsor-relayer's `/paymaster/sponsor`
+     * which embeds it into the UserOp before `pm_sponsorUserOperation`,
+     * letting Pimlico simulate the delegation atomically with the
+     * sponsored UserOp. Without this, simulator throws
+     * `AA20 account not deployed`. v0.7.5 added.
+     */
+    eip7702Auth?: {
+        chainId: string;
+        address: string;
+        nonce: string;
+        r: string;
+        s: string;
+        yParity: string;
+    };
+    /** Optional logger for the "sponsorship declined" warning. */
+    onWarning?: (msg: string) => void;
+}
+/**
+ * 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;
+    };
+}
+/**
+ * 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;
+}>;
+
+/**
+ * Registry record returned by `IssuerRegistry.getIssuer()` in V2
+ * dual-bucket. Schema reshape from V1:
+ *
+ *   V1: { issuerAddress, signerAddress, name, symbol, active, pointToken, mintingOracle }
+ *   V2: { signerAddress, name, active, capitalBase, basisPoints }
+ *
+ * `issuerAddress` is the lookup key the caller passed; we don't
+ * re-emit it here because the caller already has it. `capitalBase` +
+ * `basisPoints` drive the EQUITY-bucket cap (`capitalBase *
+ * basisPoints / 10000`).
+ */
+interface IssuerRegistryRecord {
+    signerAddress: Address;
+    name: string;
+    active: boolean;
+    capitalBase: bigint;
+    basisPoints: number;
+}
+/**
+ * Equity-bucket cap snapshot computed from the `IssuerRegistryRecord`.
+ *
+ * V1 had a separate `TokenCapRecord` sourced from
+ * `MintingOracle.tokenCaps`; in V2 the oracle is stateless and the
+ * EQUITY cap derives from the registry's `capitalBase` + `basisPoints`.
+ * Kept as a distinct shape (rather than inlining into
+ * `PreValidateMintResult`) so admin tooling can read it without
+ * re-deriving the multiplication.
+ */
+interface EquityCapRecord {
+    capitalBase: bigint;
+    basisPoints: number;
+    hardCap: bigint;
+}
+interface PreValidateMintResult {
+    /** Registry record read at pre-validation time. */
+    issuer: IssuerRegistryRecord;
+    /** Equity-bucket cap derived from issuer.capitalBase × basisPoints. */
+    equityCap: EquityCapRecord;
+    /** Current on-chain `PointToken.equitySupply()`. */
+    equitySupply: bigint;
+    /** equityCap.hardCap − equitySupply (clamped to 0). */
+    remaining: bigint;
+}
+/**
+ * Thrown by `IssuerStateValidator.preValidateMint()`.
+ * `code` maps 1:1 to the HTTP error the issuer API surfaces to clients.
+ *
+ * `MINT_CAP_EXCEEDED` is `safeToRetry: true` because the cap may free
+ * up between requests as other mints expire or settle. The other two
+ * codes are configuration-time states — the FE can't recover by retry.
+ */
+type IssuerStateErrorCode = "ISSUER_NOT_REGISTERED" | "ISSUER_INACTIVE" | "MINT_CAP_EXCEEDED";
+declare class IssuerStateError extends PafiSdkError {
+    readonly httpStatus: "unprocessable";
+    readonly code: IssuerStateErrorCode;
+    readonly details?: Record<string, unknown>;
+    readonly safeToRetry: boolean;
+    constructor(code: IssuerStateErrorCode, message: string, details?: Record<string, unknown>);
+}
+
+/**
+ * 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) — 10s TTL per PointToken
+ *     (see `ISSUER_RECORD_TTL_MS` comment)
+ *   - Burst calls while a fetch is in-flight share the same Promise
+ *     (thundering-herd protection)
+ *   - Operators can call `invalidate()` after admin txs land to bust
+ *     the cache immediately instead of waiting up to TTL.
+ *
+ * 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 — closes
+     * the split-brain window described
+     * passive TTL. Idempotent: safe to call when no entry exists.
+     */
+    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;
+}
+
+/**
+ * SDK-side fallback used when settlement-api is unreachable, returns
+ * 404, or returns 5xx. Keep it permissive enough that an outage doesn't
+ * lock all users out, but tight enough that it's not an abuse vector.
+ */
+declare const DEFAULT_REDEMPTION_POLICY: RedemptionPolicy;
+declare function defaultPolicyFor(issuerId: string): RedemptionPolicy;
+
+/**
+ * Either a successful policy fetch or a structured failure. We never
+ * throw from `fetchPolicy()` — callers fall back to cache/default on
+ * any failure mode, so a thrown error would just force every caller
+ * to wrap in try/catch.
+ */
+type FetchResult = {
+    ok: true;
+    policy: RedemptionPolicy;
+} | {
+    ok: false;
+    reason: FetchFailureReason;
+    status?: number;
+};
+type FetchFailureReason = "TIMEOUT" | "NETWORK" | "NOT_FOUND" | "UNAUTHORIZED" | "SERVER_ERROR" | "INVALID_RESPONSE";
+declare class SettlementClient {
+    private readonly config;
+    constructor(config: SettlementClientConfig);
+    fetchPolicy(): Promise<FetchResult>;
+}
+
+interface UserHistory {
+    /** Total PT redeemed by user in the rolling 24h window. */
+    redeemedLast24hPt: bigint;
+    /** Last redemption timestamp (unix seconds), or null if never. */
+    lastRedeemedAtUnixSec: number | null;
+}
+interface EvaluateInput {
+    policy: RedemptionPolicy;
+    policySource: RedemptionPolicySource;
+    history: UserHistory;
+    /** Amount being requested. Pass 0n for a pure preview. */
+    amountPt: bigint;
+    /** Current unix time in seconds (caller-controlled for testability). */
+    nowUnixSec: number;
+}
+/**
+ * Pure evaluator. Given a policy + user history snapshot + requested
+ * amount, returns either ALLOW + a preview of the user's remaining
+ * headroom, or DENY + the first failing rule.
+ *
+ * Preview is always populated, even on denial — UI uses it to render
+ * "X PT redeemable now" / "next available at HH:MM" regardless.
+ */
+declare function evaluateRedemption(input: EvaluateInput): RedemptionDecision;
+declare const REDEMPTION_HISTORY_WINDOW_SEC: number;
+
+/**
+ * In-memory IRedemptionHistoryStore for tests + the bundled NestJS
+ * example. Production issuers should implement this against their
+ * existing burn/journal table — sumRedeemedSince is hot path on every
+ * redemption preview.
+ */
+declare class MemoryRedemptionHistoryStore implements IRedemptionHistoryStore {
+    private readonly entries;
+    sumRedeemedSince(user: Address, sinceUnixSec: number, pointTokenAddress?: Address): Promise<bigint>;
+    getLastRedeemedAtUnixSec(user: Address, pointTokenAddress?: Address): Promise<number | null>;
+    recordRedemption(entry: {
+        user: Address;
+        amountPt: bigint;
+        pointTokenAddress?: Address;
+        unixSec: number;
+    }): Promise<void>;
+}
+
+declare const PAFI_ISSUER_SDK_VERSION: string;
+
+export { AdapterMisconfiguredError, type ApiConfigResponse, type ApiGasFeeResponse, type ApiLoginRequest, type ApiLoginResponse, type ApiNonceResponse, type ApiPoolsRequest, type ApiPoolsResponse, type ApiRedemptionEvaluateRequest, type ApiRedemptionEvaluateResponse, type ApiRedemptionPreviewRequest, type ApiRedemptionPreviewResponse, type ApiUserRequest, type ApiUserResponse, type AuthContext, AuthError, type AuthErrorCode, AuthService, type AuthServiceConfig, type BundlerEstimatorClient, BundlerNotConfiguredError, BundlerRejectedError, type BurnEvent, BurnIndexer, type BurnIndexerConfig, BurnIndexerFinalizeError, type BurnStatusParams, type BurnStatusResponse, type ClaimDto, type ConfigDto, ConfigurationError, DEFAULT_REDEMPTION_POLICY, type DecodedCallDto, DefaultPolicyEngine, type DefaultPolicyEngineOptions, type DelegatePrepareDto, type DelegateStatusDto, type EstimateGasFeeOptions, type EvaluateInput, FeeManager, type FeeManagerConfig, type FeeManagerMetrics, type FetchFailureReason, type FetchImpl, type FetchResult, type GasFeeDto, type GasFeeSource, type HandleDelegateSubmitParams, type HandleDelegateSubmitResult, type HandleMobilePrepareParams, type HandleMobilePrepareResult, type HandleMobileSubmitParams, type IIndexerCursorStore, type IPendingUserOpStore, type IPointLedger, type IPolicyEngine, type IRateLimiter, type IRedemptionHistoryStore, type ISessionStore, type ISingletonLock, InMemoryCursorStore, IssuerApiAdapter, type IssuerApiAdapterConfig, IssuerApiHandlers, type IssuerApiHandlersConfig, type IssuerRegistryRecord, type IssuerService, type IssuerServiceConfig, IssuerStateError, IssuerStateValidator, LockNotFoundError, type LockedMintRequest, type LoginResult, MemoryPendingUserOpStore, MemoryRateLimiter, MemoryRedemptionHistoryStore, MemorySessionStore, type MemorySessionStoreOptions, type MintEvent, type MintStatusParams, type MintStatusResponse, type MintingStatus, type MobilePrepareDto, type MobileSubmitDto, type NativePtQuoterConfig, NonceManager, NoopRateLimiter, PAFI_ISSUER_SDK_VERSION, PTClaimError, PTClaimHandler, type PTClaimHandlerConfig, type PTClaimRequest, type PTClaimResponse, PTRedeemError, PTRedeemHandler, type PTRedeemHandlerConfig, type PTRedeemRequest, type PTRedeemResponse, PafiBackendClient, type PafiBackendConfig, PafiBackendError, type PafiBackendErrorCode, type PafiEstimatorClientConfig, PafiEstimatorHttpError, type PaymasterGasEstimates, type PendingCredit, type PendingUserOpEntry, PendingUserOpForbiddenError, PendingUserOpNotFoundError, type PerpDepositDto, PerpDepositError, PerpDepositHandler, type PerpDepositHandlerConfig, type PerpDepositRequest, type PerpDepositResponse, PointIndexer, type PointIndexerConfig, PointIndexerFinalizeError, PointTokenDomainResolver, type PointTokenDomainResolverConfig, type PolicyDecision, type PolicyEvalRequest, PolicyProvider, type PolicyProviderConfig, type PoolsDto, type PoolsProvider, type PostgresQueryRunner, type PreValidateMintResult, type PrepareBurnParams, type PrepareMintParams, type PrepareMobileUserOpParams, type PrepareMobileUserOpResult, type PreparedUserOp, type PreviewBurnParams, type PreviewMintParams, REDEMPTION_HISTORY_WINDOW_SEC, type RateLimitAction, type RateLimiterConfig, type RedeemDto, type RedeemPrepareDto, RedemptionService, type RedemptionServiceConfig, RelayError, type RelayErrorCode, RelayService, type RelayUserOpParams, type RelayUserOpRequest, type RelayUserOpResponse, type RequestPaymasterParams, type ResolvedPolicy, type RetryConfig, type SdkErrorBody, type SdkErrorMapperFactories, type SdkErrorStatus, type SerializedUserOpTypedData, type Session, SettlementClient, type SettlementClientConfig, type SingletonLockHandle, type SponsorshipRequest, type SponsorshipResponse, type SponsorshipTarget, type SponsorshipUserOp, type SubgraphNativeUsdtQuoterConfig, type SubgraphPoolsProviderConfig, type UserDto, type UserHistory, applyPaymasterGasEstimates, authenticateRequest, buildSdkErrorBody, createIssuerService, createNativePtQuoter, createPafiEstimatorClient, createSdkErrorMapper, createSubgraphNativeUsdtQuoter, createSubgraphPoolsProvider, defaultPolicyFor, evaluateRedemption, handleClaimStatus, handleDelegateSubmit, handleMobilePrepare, handleMobileSubmit, handleRedeemStatus, makePostgresSingletonLock, mergePaymasterFields, prepareMobileUserOp, relayUserOp, requestPaymaster, serializeEntryToJsonRpc, serializeUserOpTypedData };