@pafi-dev/issuer 0.5.32 → 0.5.34

package/dist/index.d.ts

@@ -1,5 +1,5 @@
 import { Address, Hex, PublicClient, WalletClient } from 'viem';
-import { PointTokenDomainConfig, PartialUserOperation, BurnRequest, PoolKey } from '@pafi-dev/core';
+import { PointTokenDomainConfig, PartialUserOperation, BurnRequest, PoolKey, ENTRY_POINT_V08, UserOpTypedData } from '@pafi-dev/core';
 export { PAFI_SUBGRAPH_URL } from '@pafi-dev/core';
 
 /**
@@ -32,6 +32,28 @@ interface LockedMintRequest {
     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
@@ -92,6 +114,29 @@ interface IPointLedger {
      * 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>;
 }
 
 /**
@@ -1294,6 +1339,194 @@ declare class TopUpRedemptionHandler {
     handle(request: TopUpRedemptionRequest): Promise<TopUpRedemptionResponse>;
 }
 
+interface RetryConfig {
+    maxAttempts?: number;
+    initialDelayMs?: number;
+    maxDelayMs?: number;
+    maxRetryAfterMs?: number;
+}
+interface PafiBackendConfig {
+    url: 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;
+}
+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;
+    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, 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;
+    /** Optional logger for "ledger update failed" warnings. */
+    onWarning?: (msg: string) => void;
+}
+interface BurnStatusParams {
+    lockId: string;
+    userAddress: Address;
+    ledger: IPointLedger;
+    pafiBackendClient?: PafiBackendClient;
+    onWarning?: (msg: string) => void;
+}
+declare class LockNotFoundError extends Error {
+    readonly code = "LOCK_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>;
+
 /**
  * Config for `createSubgraphPoolsProvider`.
  */
@@ -1511,37 +1744,70 @@ declare class BalanceAggregator {
     getCombinedBalanceMulti(user: Address, pointTokens: Address[]): Promise<Map<Address, CombinedBalance>>;
 }
 
-interface RetryConfig {
-    maxAttempts?: number;
-    initialDelayMs?: number;
-    maxDelayMs?: number;
-    maxRetryAfterMs?: number;
-}
-interface PafiBackendConfig {
-    url: 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;
+/**
+ * Typed errors thrown by the helpers below — issuer controllers map
+ * these to the appropriate HTTP status. We don't depend on @nestjs/common
+ * here because the SDK is framework-agnostic; the consuming controller
+ * wraps each one in its preferred exception class.
+ */
+declare class BundlerNotConfiguredError extends Error {
+    readonly code = "BUNDLER_NOT_CONFIGURED";
+    constructor();
+}
+declare class BundlerRejectedError extends Error {
+    readonly code = "BUNDLER_REJECTED";
+    readonly cause: unknown;
+    constructor(message: string, cause: unknown);
+}
+interface RequestPaymasterParams {
+    /** PAFI backend client. When `null` / `undefined` → returns `undefined`. */
+    client: PafiBackendClient | null | undefined;
+    chainId: number;
+    scenario: string;
+    /** UserOp skeleton — must have all gas + fee fields set. */
+    userOp: {
+        sender: Address;
+        nonce: bigint;
+        callData: Hex;
+        callGasLimit: bigint;
+        verificationGasLimit: bigint;
+        preVerificationGas: bigint;
+        maxFeePerGas: bigint;
+        maxPriorityFeePerGas: bigint;
+    };
+    /** Target contract (typically the PointToken). */
+    pointTokenAddress: Address;
+    /**
+     * Function name to surface in audit / paymaster context. Defaults to
+     * a per-scenario sensible value (`mint` / `burn` / `swap` / generic
+     * scenario name).
+     */
+    functionName?: string;
+    /** Optional logger for the "sponsorship declined" warning. */
+    onWarning?: (msg: string) => void;
 }
-
-interface RelayUserOpRequest {
+/**
+ * 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>;
-    entryPoint: string;
+    /** EIP-7702 authorization (delegation UserOps only). */
     eip7702Auth?: {
         chainId: string;
         address: string;
@@ -1551,76 +1817,24 @@ interface RelayUserOpRequest {
         yParity: string;
     };
 }
-interface RelayUserOpResponse {
+/**
+ * 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;
-}
-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;
-}
-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;
-    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;
-}
+}>;
 
 /**
  * Top-level configuration for `createIssuerService`.
@@ -1814,6 +2028,154 @@ interface IPendingUserOpStore {
  */
 declare function serializeEntryToJsonRpc(entry: PendingUserOpEntry, signature: Hex, variant?: "sponsored" | "fallback"): Record<string, string | null>;
 
+/**
+ * Re-shape `UserOpTypedData` so all `bigint` fields become hex strings —
+ * required for JSON transport over HTTP. Mirrors the inverse of what
+ * `walletClient.signTypedData` accepts on the client (it auto-coerces hex
+ * strings back to bigints for `uint256` fields).
+ */
+type SerializedUserOpTypedData = {
+    domain: UserOpTypedData["domain"];
+    types: UserOpTypedData["types"];
+    primaryType: UserOpTypedData["primaryType"];
+    message: {
+        sender: Address;
+        nonce: Hex;
+        initCode: Hex;
+        callData: Hex;
+        accountGasLimits: Hex;
+        preVerificationGas: Hex;
+        gasFees: Hex;
+        paymasterAndData: Hex;
+    };
+};
+/**
+ * Convert a `UserOpTypedData` payload into the JSON-safe wire form
+ * (bigint → hex string). The mobile client passes this directly to
+ * `eth_signTypedData_v4` / viem's `signTypedData`.
+ */
+declare function serializeUserOpTypedData(td: UserOpTypedData): SerializedUserOpTypedData;
+/**
+ * Merge Pimlico's paymaster-sponsorship response into a UserOp
+ * skeleton, applying only fields that are actually defined.
+ *
+ * `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.
+ */
+declare function mergePaymasterFields<T extends object>(userOp: T, paymasterFields: {
+    paymaster: Address;
+    paymasterData: Hex;
+    paymasterVerificationGasLimit: bigint;
+    paymasterPostOpGasLimit: bigint;
+    callGasLimit?: bigint;
+    verificationGasLimit?: bigint;
+    preVerificationGas?: bigint;
+    maxFeePerGas?: bigint;
+    maxPriorityFeePerGas?: bigint;
+} | undefined): T;
+interface PreparedUserOp {
+    /** The bundler-ready UserOp (with paymaster + Pimlico-quoted gas). */
+    userOp: PartialUserOperation & {
+        maxFeePerGas: bigint;
+        maxPriorityFeePerGas: bigint;
+        paymaster?: Address;
+        paymasterData?: Hex;
+        paymasterVerificationGasLimit?: bigint;
+        paymasterPostOpGasLimit?: bigint;
+    };
+    /** Hex-encoded EIP-712 digest. Equals `EntryPoint.getUserOpHash`. */
+    userOpHash: Hex;
+    /** Typed-data payload — pass directly to `eth_signTypedData_v4`. */
+    typedData: SerializedUserOpTypedData;
+}
+interface PrepareMobileUserOpParams {
+    /** Lock id (issuer-generated) keying both store entry + ledger row. */
+    lockId: string;
+    /**
+     * Sponsored variant — built with the PT operator-fee transfer
+     * included. SDK or caller should set `partialUserOp.maxFeePerGas` /
+     * `maxPriorityFeePerGas` from `provider.estimateFeesPerGas()` before
+     * calling — they get overridden by Pimlico's quote anyway, but
+     * they must be valid bigints for the merge.
+     */
+    partialUserOp: PartialUserOperation & {
+        maxFeePerGas: bigint;
+        maxPriorityFeePerGas: bigint;
+    };
+    /**
+     * Optional fee-stripped fallback variant — built with `gasFeePt: 0n`
+     * (no PT operator-fee transfer). Submitted when paymaster refuses
+     * sponsorship and the user pays ETH gas directly.
+     */
+    partialUserOpFallback?: PartialUserOperation & {
+        maxFeePerGas?: bigint;
+        maxPriorityFeePerGas?: bigint;
+    };
+    /** Paymaster sponsorship response, or `undefined` if PAFI declined. */
+    paymasterFields?: {
+        paymaster: Address;
+        paymasterData: Hex;
+        paymasterVerificationGasLimit: bigint;
+        paymasterPostOpGasLimit: bigint;
+        callGasLimit?: bigint;
+        verificationGasLimit?: bigint;
+        preVerificationGas?: bigint;
+        maxFeePerGas?: bigint;
+        maxPriorityFeePerGas?: bigint;
+    };
+    chainId: number;
+    /** Pending-userop store implementation (Redis/Postgres/Memory). */
+    store: IPendingUserOpStore;
+    /** TTL the store entry should outlive — typically the MintRequest deadline. */
+    ttlSeconds: number;
+}
+interface PrepareMobileUserOpResult {
+    sponsored: PreparedUserOp;
+    /**
+     * Set when `partialUserOpFallback` was supplied AND the PT fee was
+     * non-zero (i.e. sponsored ≠ fallback). Mobile client picks which
+     * variant to sign + submit; SDK's `serializeEntryToJsonRpc` reads
+     * the `variant` flag to dispatch.
+     */
+    fallback?: PreparedUserOp;
+    /** What got persisted into the pending-userop store. */
+    entry: PendingUserOpEntry;
+}
+/**
+ * Build the sponsored UserOp + (optional) fee-stripped fallback for the
+ * mobile prepare/submit flow.
+ *
+ * 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>;
+
 interface IssuerRegistryRecord {
     issuerAddress: Address;
     signerAddress: Address;
@@ -1907,4 +2269,4 @@ declare class IssuerStateValidator {
 /** SDK package version — bumped on every release */
 declare const PAFI_ISSUER_SDK_VERSION = "0.4.0";
 
-export { type ApiClaimRequest, type ApiClaimResponse, type ApiConfigResponse, type ApiGasFeeResponse, type ApiLoginRequest, type ApiLoginResponse, type ApiNonceResponse, type ApiPoolsRequest, type ApiPoolsResponse, type ApiRedeemRequest, type ApiRedeemResponse, type ApiTopUpRequest, type ApiTopUpResponse, type ApiUserRequest, type ApiUserResponse, type AuthContext, AuthError, type AuthErrorCode, AuthService, type AuthServiceConfig, BalanceAggregator, type BalanceAggregatorConfig, type BurnEvent, BurnIndexer, type BurnIndexerConfig, type CombinedBalance, DefaultPolicyEngine, type DefaultPolicyEngineOptions, FeeManager, type FeeManagerConfig, type IIndexerCursorStore, type IPendingUserOpStore, type IPointLedger, type IPolicyEngine, type ISessionStore, InMemoryCursorStore, IssuerApiHandlers, type IssuerApiHandlersConfig, type IssuerRegistryRecord, type IssuerService, type IssuerServiceConfig, IssuerStateError, IssuerStateValidator, type LockedMintRequest, type LoginResult, MemorySessionStore, type MemorySessionStoreOptions, type MintEvent, type MintingStatus, type NativePtQuoterConfig, NonceManager, PAFI_ISSUER_SDK_VERSION, PTRedeemError, PTRedeemHandler, type PTRedeemHandlerConfig, type PTRedeemRequest, type PTRedeemResponse, PafiBackendClient, type PafiBackendConfig, PafiBackendError, type PafiBackendErrorCode, type PendingUserOpEntry, PointIndexer, type PointIndexerConfig, type PolicyDecision, type PolicyEvalRequest, type PoolsProvider, type PreValidateMintResult, type PrepareBurnDirectParams, type PrepareBurnParams, type PrepareBurnWithSigParams, type PrepareMintParams, RelayError, type RelayErrorCode, RelayService, type RelayUserOpRequest, type RelayUserOpResponse, type RetryConfig, type Session, type SponsorshipRequest, type SponsorshipResponse, type SponsorshipTarget, type SponsorshipUserOp, type SubgraphNativeUsdtQuoterConfig, type SubgraphPoolsProviderConfig, TopUpRedemptionError, TopUpRedemptionHandler, type TopUpRedemptionHandlerConfig, type TopUpRedemptionRequest, type TopUpRedemptionResponse, authenticateRequest, createIssuerService, createNativePtQuoter, createSubgraphNativeUsdtQuoter, createSubgraphPoolsProvider, serializeEntryToJsonRpc };
+export { type ApiClaimRequest, type ApiClaimResponse, type ApiConfigResponse, type ApiGasFeeResponse, type ApiLoginRequest, type ApiLoginResponse, type ApiNonceResponse, type ApiPoolsRequest, type ApiPoolsResponse, type ApiRedeemRequest, type ApiRedeemResponse, type ApiTopUpRequest, type ApiTopUpResponse, type ApiUserRequest, type ApiUserResponse, type AuthContext, AuthError, type AuthErrorCode, AuthService, type AuthServiceConfig, BalanceAggregator, type BalanceAggregatorConfig, BundlerNotConfiguredError, BundlerRejectedError, type BurnEvent, BurnIndexer, type BurnIndexerConfig, type BurnStatusParams, type BurnStatusResponse, type CombinedBalance, DefaultPolicyEngine, type DefaultPolicyEngineOptions, FeeManager, type FeeManagerConfig, type IIndexerCursorStore, type IPendingUserOpStore, type IPointLedger, type IPolicyEngine, type ISessionStore, InMemoryCursorStore, IssuerApiHandlers, type IssuerApiHandlersConfig, type IssuerRegistryRecord, type IssuerService, type IssuerServiceConfig, IssuerStateError, IssuerStateValidator, LockNotFoundError, type LockedMintRequest, type LoginResult, MemorySessionStore, type MemorySessionStoreOptions, type MintEvent, type MintStatusParams, type MintStatusResponse, type MintingStatus, type NativePtQuoterConfig, NonceManager, PAFI_ISSUER_SDK_VERSION, PTRedeemError, PTRedeemHandler, type PTRedeemHandlerConfig, type PTRedeemRequest, type PTRedeemResponse, PafiBackendClient, type PafiBackendConfig, PafiBackendError, type PafiBackendErrorCode, type PendingCredit, type PendingUserOpEntry, PointIndexer, type PointIndexerConfig, type PolicyDecision, type PolicyEvalRequest, type PoolsProvider, type PreValidateMintResult, type PrepareBurnDirectParams, type PrepareBurnParams, type PrepareBurnWithSigParams, type PrepareMintParams, type PrepareMobileUserOpParams, type PrepareMobileUserOpResult, type PreparedUserOp, RelayError, type RelayErrorCode, RelayService, type RelayUserOpParams, type RelayUserOpRequest, type RelayUserOpResponse, type RequestPaymasterParams, type RetryConfig, type SerializedUserOpTypedData, type Session, type SponsorshipRequest, type SponsorshipResponse, type SponsorshipTarget, type SponsorshipUserOp, type SubgraphNativeUsdtQuoterConfig, type SubgraphPoolsProviderConfig, TopUpRedemptionError, TopUpRedemptionHandler, type TopUpRedemptionHandlerConfig, type TopUpRedemptionRequest, type TopUpRedemptionResponse, authenticateRequest, createIssuerService, createNativePtQuoter, createSubgraphNativeUsdtQuoter, createSubgraphPoolsProvider, handleClaimStatus, handleRedeemStatus, mergePaymasterFields, prepareMobileUserOp, relayUserOp, requestPaymaster, serializeEntryToJsonRpc, serializeUserOpTypedData };