@pafi-dev/issuer 0.5.34 → 0.5.36

package/dist/index.d.ts

@@ -1,5 +1,5 @@
 import { Address, Hex, PublicClient, WalletClient } from 'viem';
-import { PointTokenDomainConfig, PartialUserOperation, BurnRequest, PoolKey, ENTRY_POINT_V08, UserOpTypedData } from '@pafi-dev/core';
+import { PointTokenDomainConfig, PartialUserOperation, BurnRequest, PoolKey, UserOpTypedData, decodeBatchExecuteCalls, BROKER_HASHES, ENTRY_POINT_V08 } from '@pafi-dev/core';
 export { PAFI_SUBGRAPH_URL } from '@pafi-dev/core';
 
 /**
@@ -1527,6 +1527,548 @@ declare function handleClaimStatus(params: MintStatusParams): Promise<MintStatus
  */
 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;
+    };
+}
+/**
+ * Storage backend for pending UserOps in the mobile prepare/submit pattern.
+ *
+ * Implement this interface and wire it into your issuer backend:
+ *   - `save()` — called by `POST /claim/prepare` and `POST /redeem/prepare`
+ *   - `get()`  — called by `POST /claim/submit` and `POST /redeem/submit`
+ *   - `delete()` — called after successful submit or explicit cancellation
+ *
+ * The default implementation in the gg56 boilerplate uses Redis with
+ * a short TTL matching the MintRequest / BurnRequest deadline.
+ */
+interface IPendingUserOpStore {
+    save(lockId: string, entry: PendingUserOpEntry, ttlSeconds: number): Promise<void>;
+    get(lockId: string): Promise<PendingUserOpEntry | null>;
+    delete(lockId: string): Promise<void>;
+}
+
+/**
+ * Convert a stored `PendingUserOpEntry` (decimal-string fields) plus a
+ * signature into the JSON-RPC wire format for `eth_sendUserOperation`.
+ *
+ * Bridges the gap between the serialized storage format (decimal strings,
+ * safe for JSON/Redis) and `serializeUserOpToJsonRpc` which expects bigints.
+ */
+declare function serializeEntryToJsonRpc(entry: PendingUserOpEntry, signature: Hex, variant?: "sponsored" | "fallback"): Record<string, string | null>;
+
+/**
+ * Re-shape `UserOpTypedData` so all `bigint` fields become hex strings —
+ * required for JSON transport over HTTP. Mirrors the inverse of what
+ * `walletClient.signTypedData` accepts on the client (it auto-coerces hex
+ * strings back to bigints for `uint256` fields).
+ */
+type SerializedUserOpTypedData = {
+    domain: UserOpTypedData["domain"];
+    types: UserOpTypedData["types"];
+    primaryType: UserOpTypedData["primaryType"];
+    message: {
+        sender: Address;
+        nonce: Hex;
+        initCode: Hex;
+        callData: Hex;
+        accountGasLimits: Hex;
+        preVerificationGas: Hex;
+        gasFees: Hex;
+        paymasterAndData: Hex;
+    };
+};
+/**
+ * Convert a `UserOpTypedData` payload into the JSON-safe wire form
+ * (bigint → hex string). The mobile client passes this directly to
+ * `eth_signTypedData_v4` / viem's `signTypedData`.
+ */
+declare function serializeUserOpTypedData(td: UserOpTypedData): SerializedUserOpTypedData;
+/**
+ * Merge Pimlico's paymaster-sponsorship response into a UserOp
+ * skeleton, applying only fields that are actually defined.
+ *
+ * `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>;
+
+/**
+ * Mobile prepare/submit orchestrators — abstract the duplicate glue
+ * between `/claim/prepare`+`/claim/submit` and `/redeem/prepare`+
+ * `/redeem/submit`. Both share the same shape:
+ *
+ *   prepare:  fees + delegation check → paymaster → prepareMobileUserOp
+ *   submit:   fetch entry → serialize+sign → relay → bind hash → delete
+ *
+ * Issuer controllers shrink to ~30 LoC each — wire the handler that
+ * produces `partialUserOp[+ fallback]`, hand off to these.
+ */
+declare class PendingUserOpNotFoundError extends Error {
+    readonly code = "PENDING_USEROP_NOT_FOUND";
+    constructor(lockId: string);
+}
+interface HandleMobilePrepareParams {
+    /** User EOA — used for the delegation check. */
+    userAddress: Address;
+    chainId: number;
+    /** Lock id (issuer-generated) keying both store entry + ledger row. */
+    lockId: string;
+    /**
+     * Partial UserOp from the upstream handler (PTClaimHandler /
+     * PTRedeemHandler). The orchestrator will top up `maxFeePerGas` /
+     * `maxPriorityFeePerGas` from `provider.estimateFeesPerGas()` if the
+     * fields aren't already set, then request paymaster sponsorship.
+     */
+    partialUserOp: PartialUserOperation;
+    /** Optional fee-stripped fallback variant. */
+    partialUserOpFallback?: PartialUserOperation;
+    /**
+     * Scenario tag — passed to `requestSponsorship` so the relayer can
+     * apply per-scenario L1 enforcement (`mint`, `burn`, etc.).
+     */
+    scenario: string;
+    /** Target contract for the paymaster intent. */
+    pointTokenAddress: Address;
+    /** TTL the store entry should outlive. Typically the lock duration in seconds. */
+    ttlSeconds: number;
+    store: IPendingUserOpStore;
+    provider: PublicClient;
+    /** Optional — when omitted, paymaster is skipped and `sponsored: false` is returned. */
+    pafiBackendClient?: PafiBackendClient | null;
+    onWarning?: (msg: string) => void;
+}
+interface HandleMobilePrepareResult extends PrepareMobileUserOpResult {
+    /**
+     * True when paymaster sponsorship was applied to the sponsored variant.
+     * (Renamed from `sponsored` to avoid clashing with
+     * `PrepareMobileUserOpResult.sponsored` which is the PreparedUserOp object.)
+     */
+    isSponsored: boolean;
+    /**
+     * True when the user's EOA has no EIP-7702 delegation set on-chain.
+     * The mobile client must run the `/delegate/*` flow first.
+     */
+    needsDelegation: boolean;
+}
+/**
+ * Build the mobile prepare response. End-to-end:
+ *
+ *   1. Pull `estimateFeesPerGas` + `getCode(user)` in parallel.
+ *   2. Top up sponsored UserOp fees if the upstream handler left them
+ *      unset.
+ *   3. `requestPaymaster` — non-fatal: if PAFI declines, the sponsored
+ *      variant still works, the FE just falls back to the unsponsored
+ *      response.
+ *   4. `prepareMobileUserOp` — merge + hash + persist.
+ */
+declare function handleMobilePrepare(params: HandleMobilePrepareParams): Promise<HandleMobilePrepareResult>;
+interface HandleMobileSubmitParams {
+    lockId: string;
+    /** User signature over `userOpHash` (or `userOpHashFallback`). */
+    signature: Hex;
+    /** Which variant the user actually signed. Defaults to `'sponsored'`. */
+    variant?: "sponsored" | "fallback";
+    store: IPendingUserOpStore;
+    /**
+     * Bind the bundler-returned hash to the lock so `claim/redeem status`
+     * can fall back to the bundler receipt when the indexer's
+     * amount-based match races and resolves a sibling. Different ledgers
+     * use different methods (`bindMintUserOpHash` vs `bindCreditUserOpHash`),
+     * so the caller passes the correct one.
+     */
+    bindUserOpHash: (lockId: string, userOpHash: Hex) => Promise<void>;
+    pafiBackendClient?: PafiBackendClient | null;
+    /** Defaults to `ENTRY_POINT_V08`. */
+    entryPoint?: string;
+}
+/**
+ * Submit a previously-prepared mobile UserOp to the bundler.
+ *
+ * Throws:
+ *   - `PendingUserOpNotFoundError` — entry expired or already submitted.
+ *     Map to 404.
+ *   - `BundlerNotConfiguredError` — `pafiBackendClient` missing. Map to 503.
+ *   - `BundlerRejectedError` — bundler rejected the UserOp. Map to 422.
+ */
+declare function handleMobileSubmit(params: HandleMobileSubmitParams): Promise<{
+    userOpHash: Hex;
+}>;
+
+type DecodedCall$2 = 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>;
+}
+/**
+ * v1.4 sig-gated mint handler — mirrors `PTRedeemHandler` on the mint side.
+ *
+ * Pre-validates against IssuerRegistry + on-chain totalSupply, locks the
+ * off-chain balance, builds the sponsored UserOp (mint + PT fee
+ * transfer) plus an optional fallback variant (mint only — for
+ * paymaster-refused fallback).
+ *
+ * Caller fetches AA + mintRequest nonces (so issuers can plug in their
+ * own composer — gg56 uses a timestamp-key 2D nonce). Caller layers
+ * paymaster sponsorship + sponsorAuth on top of the returned UserOps.
+ */
+declare class PTClaimError extends Error {
+    code: "INVALID_AMOUNT" | "VALIDATION_FAILED" | "BUILD_FAILED";
+    details?: Record<string, unknown> | undefined;
+    constructor(code: "INVALID_AMOUNT" | "VALIDATION_FAILED" | "BUILD_FAILED", message: string, details?: Record<string, unknown> | undefined);
+}
+interface PTClaimHandlerConfig {
+    ledger: IPointLedger;
+    relayService: RelayService;
+    provider: PublicClient;
+    /** Issuer minter signer wallet — passed through to RelayService.prepareMint. */
+    issuerSignerWallet: WalletClient;
+    /**
+     * EIP-712 domain `name` for `MintRequest`. Typically the PointToken
+     * ERC-20 name. RelayService will set chainId + verifyingContract from
+     * the request.
+     */
+    pointTokenDomainName: string;
+    /** Optional — when wired, used to estimate the PT gas-reimbursement fee. */
+    feeService?: FeeManager;
+    /** Optional — pre-validates issuer status + cap before locking balance. */
+    issuerStateValidator?: 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;
+}
+interface PTClaimRequest {
+    authenticatedAddress: Address;
+    userAddress: Address;
+    amount: bigint;
+    pointTokenAddress: Address;
+    chainId: number;
+    /** ERC-4337 account nonce for the user's EOA. */
+    aaNonce: bigint;
+    /** Current `mintRequestNonces[userAddress]` from PointToken. */
+    mintRequestNonce: bigint;
+}
+interface PTClaimResponse {
+    /** Sponsored UserOp — mint + PT fee transfer (when feeAmount > 0). */
+    userOp: PartialUserOperation;
+    /**
+     * Fallback UserOp — mint only, no PT fee transfer. Present only when
+     * `feeAmount > 0`. User pays gas in ETH directly.
+     */
+    fallback?: PartialUserOperation;
+    lockId: string;
+    feeAmount: bigint;
+    signatureDeadline: bigint;
+    expiresInSeconds: number;
+    /** Decoded calls for the sponsored UserOp (convenience for FE-submit path). */
+    calls: DecodedCall$2[];
+    /** Decoded calls for the fallback UserOp (when present). */
+    callsFallback?: DecodedCall$2[];
+}
+declare class PTClaimHandler {
+    private readonly cfg;
+    constructor(config: PTClaimHandlerConfig);
+    handle(request: PTClaimRequest): Promise<PTClaimResponse>;
+}
+
+type DecodedCall$1 = ReturnType<typeof decodeBatchExecuteCalls>[number];
+
+/**
+ * PT → USDT swap handler.
+ *
+ * Quotes via V4 on-chain Quoter (`findBestQuote`), applies slippage,
+ * computes the PT gas-reimbursement fee from `FeeManager`, and builds
+ * two UserOps:
+ *
+ *   - **sponsored** — swap (amountIn − fee) + transfer(fee, PAFI). User
+ *     holds exactly `amountIn` PT.
+ *   - **fallback** — swap full `amountIn`, no PT fee transfer. Built
+ *     only when `feeAmount > 0`. User pays gas in ETH directly.
+ *
+ * Re-quotes the sponsored path on `(amountIn − feeAmount)` because the
+ * sponsored path actually swaps that much; the fallback uses the
+ * original quote.
+ *
+ * Caller (controller) layers `sponsorAuth` on top of the returned
+ * userOp. No off-chain ledger state is touched — swap is purely
+ * on-chain.
+ */
+declare class SwapError extends Error {
+    code: "QUOTE_UNAVAILABLE" | "FEE_EXCEEDS_AMOUNT" | "INVALID_AMOUNT";
+    constructor(code: "QUOTE_UNAVAILABLE" | "FEE_EXCEEDS_AMOUNT" | "INVALID_AMOUNT", message: string);
+}
+interface SwapHandlerConfig {
+    provider: PublicClient;
+    poolsProvider: PoolsProvider;
+    /** Optional — when wired, used to estimate the PT gas-reimbursement fee. */
+    feeService?: FeeManager;
+    /**
+     * Default slippage applied to the V4 quote when the request omits
+     * `slippageBps`. 50 bps = 0.5%.
+     */
+    defaultSlippageBps?: number;
+    /** Default deadline window in seconds applied when not passed in request. Default 300. */
+    defaultSwapDeadlineSeconds?: number;
+    now?: () => number;
+}
+interface SwapRequest {
+    userAddress: Address;
+    chainId: number;
+    pointTokenAddress: Address;
+    amountIn: bigint;
+    /** ERC-4337 account nonce for the user's EOA. */
+    aaNonce: bigint;
+    /** Optional override; falls back to `defaultSlippageBps`. */
+    slippageBps?: number;
+    /** Optional override; falls back to `now() + defaultSwapDeadlineSeconds`. */
+    deadline?: bigint;
+}
+interface SwapResponse {
+    /** Sponsored UserOp — swap (amountIn − fee) + PT.transfer(fee). */
+    userOp: PartialUserOperation;
+    /** Fallback UserOp — swap full amountIn, no PT fee transfer. Present only when fee > 0. */
+    fallback?: PartialUserOperation;
+    feeAmount: bigint;
+    /** Quote for the sponsored path (after fee deduction). */
+    estimatedUsdtOut: bigint;
+    minAmountOut: bigint;
+    /** Quote for the fallback path (full amountIn). Present only when fee > 0. */
+    estimatedUsdtOutFallback?: bigint;
+    minAmountOutFallback?: bigint;
+    deadline: bigint;
+    calls: DecodedCall$1[];
+    callsFallback?: DecodedCall$1[];
+}
+declare class SwapHandler {
+    private readonly cfg;
+    constructor(config: SwapHandlerConfig);
+    handle(request: SwapRequest): Promise<SwapResponse>;
+}
+
+type DecodedCall = ReturnType<typeof decodeBatchExecuteCalls>[number];
+
+/**
+ * Orderly perp-deposit handler — builds the sponsored + fallback
+ * UserOps for the PAFI Relay path.
+ *
+ * Resolves USDC + verifies the broker is whitelisted on the Vault,
+ * quotes the Relay's USDC fee (covers LayerZero msg.value out of the
+ * Relay's ETH reserve), then builds two UserOps:
+ *
+ *   - **sponsored** — PT.transfer(fee, PAFI) + USDC.approve(relay,
+ *     total) + Relay.deposit(req). User reimburses gas in PT.
+ *   - **fallback** — USDC.approve + Relay.deposit only. User pays
+ *     ERC-4337 gas in ETH. Built only when `feeAmount > 0`.
+ *
+ * `maxFee` is set to `quote × 1.5` — slippage cap on the Relay's
+ * USD-pricing during the inclusion window. If the actual fee at
+ * execution exceeds maxFee the Relay reverts (`FeeExceedsMax`).
+ */
+declare class PerpDepositError extends Error {
+    code: "PERP_DEPOSIT_UNAVAILABLE" | "BROKER_NOT_WHITELISTED" | "RELAY_FEE_EXCEEDS_AMOUNT" | "FEE_EXCEEDS_AMOUNT" | "INVALID_AMOUNT";
+    constructor(code: "PERP_DEPOSIT_UNAVAILABLE" | "BROKER_NOT_WHITELISTED" | "RELAY_FEE_EXCEEDS_AMOUNT" | "FEE_EXCEEDS_AMOUNT" | "INVALID_AMOUNT", message: string);
+}
+interface PerpDepositHandlerConfig {
+    provider: PublicClient;
+    /** Optional — when wired, used to estimate the PT gas-reimbursement fee. */
+    feeService?: FeeManager;
+    /** PointToken address used for the sponsored PT.transfer. */
+    pointTokenAddress: Address;
+    /**
+     * Slippage premium applied on top of the Relay quote when computing
+     * `maxFee`. Default 50% (factor 150). The Relay reverts if actual fee
+     * exceeds `maxFee` so a generous cap reduces re-quote churn.
+     */
+    maxFeePremiumBps?: number;
+}
+interface PerpDepositRequest {
+    userAddress: Address;
+    chainId: number;
+    amount: bigint;
+    brokerId: keyof typeof BROKER_HASHES;
+    /** ERC-4337 account nonce. */
+    aaNonce: bigint;
+}
+interface PerpDepositResponse {
+    userOp: PartialUserOperation;
+    fallback?: PartialUserOperation;
+    feeAmount: bigint;
+    relayTokenFee: bigint;
+    maxFee: bigint;
+    netDeposit: bigint;
+    accountId: `0x${string}`;
+    brokerHash: `0x${string}`;
+    usdcAddress: Address;
+    relayAddress: Address;
+    calls: DecodedCall[];
+    callsFallback?: DecodedCall[];
+}
+declare class PerpDepositHandler {
+    private readonly cfg;
+    constructor(config: PerpDepositHandlerConfig);
+    handle(request: PerpDepositRequest): Promise<PerpDepositResponse>;
+}
+
 /**
  * Config for `createSubgraphPoolsProvider`.
  */
@@ -1958,224 +2500,6 @@ interface IssuerService {
  */
 declare function createIssuerService(config: IssuerServiceConfig): IssuerService;
 
-/**
- * A pending UserOp serialized for persistent storage (Redis, Postgres, memory).
- *
- * All bigint fields are stored as decimal strings so the entry can be
- * JSON-serialized without precision loss. Convert back to bigint before
- * calling `computeUserOpHash` or `serializeUserOpToJsonRpc`.
- */
-interface PendingUserOpEntry {
-    sender: Address;
-    nonce: string;
-    callData: Hex;
-    callGasLimit: string;
-    verificationGasLimit: string;
-    preVerificationGas: string;
-    maxFeePerGas: string;
-    maxPriorityFeePerGas: string;
-    paymaster?: Address;
-    paymasterVerificationGasLimit?: string;
-    paymasterPostOpGasLimit?: string;
-    paymasterData?: Hex;
-    chainId: number;
-    /** Hex-encoded userOpHash — the value the user signed via personal_sign. */
-    userOpHash: Hex;
-    /**
-     * Fee-stripped fallback variant. Set by `/claim/prepare` and
-     * `/redeem/prepare` when a PT operator fee is configured AND the
-     * paymaster sponsorship attached successfully — i.e. the user might
-     * still want to submit without paymaster (paying ETH gas), and in
-     * that case shouldn't be charged the PT fee. `/claim/submit` reads
-     * this branch when its request body specifies
-     * `variant: "fallback"`.
-     *
-     * Has a different `callData` (no PT.transfer prepended) and
-     * therefore a different `userOpHash`. Paymaster fields are NOT
-     * present — the fallback is by definition unsponsored.
-     */
-    fallback?: {
-        callData: Hex;
-        callGasLimit: string;
-        verificationGasLimit: string;
-        preVerificationGas: string;
-        userOpHash: Hex;
-    };
-}
-/**
- * Storage backend for pending UserOps in the mobile prepare/submit pattern.
- *
- * Implement this interface and wire it into your issuer backend:
- *   - `save()` — called by `POST /claim/prepare` and `POST /redeem/prepare`
- *   - `get()`  — called by `POST /claim/submit` and `POST /redeem/submit`
- *   - `delete()` — called after successful submit or explicit cancellation
- *
- * The default implementation in the gg56 boilerplate uses Redis with
- * a short TTL matching the MintRequest / BurnRequest deadline.
- */
-interface IPendingUserOpStore {
-    save(lockId: string, entry: PendingUserOpEntry, ttlSeconds: number): Promise<void>;
-    get(lockId: string): Promise<PendingUserOpEntry | null>;
-    delete(lockId: string): Promise<void>;
-}
-
-/**
- * Convert a stored `PendingUserOpEntry` (decimal-string fields) plus a
- * signature into the JSON-RPC wire format for `eth_sendUserOperation`.
- *
- * Bridges the gap between the serialized storage format (decimal strings,
- * safe for JSON/Redis) and `serializeUserOpToJsonRpc` which expects bigints.
- */
-declare function serializeEntryToJsonRpc(entry: PendingUserOpEntry, signature: Hex, variant?: "sponsored" | "fallback"): Record<string, string | null>;
-
-/**
- * Re-shape `UserOpTypedData` so all `bigint` fields become hex strings —
- * required for JSON transport over HTTP. Mirrors the inverse of what
- * `walletClient.signTypedData` accepts on the client (it auto-coerces hex
- * strings back to bigints for `uint256` fields).
- */
-type SerializedUserOpTypedData = {
-    domain: UserOpTypedData["domain"];
-    types: UserOpTypedData["types"];
-    primaryType: UserOpTypedData["primaryType"];
-    message: {
-        sender: Address;
-        nonce: Hex;
-        initCode: Hex;
-        callData: Hex;
-        accountGasLimits: Hex;
-        preVerificationGas: Hex;
-        gasFees: Hex;
-        paymasterAndData: Hex;
-    };
-};
-/**
- * Convert a `UserOpTypedData` payload into the JSON-safe wire form
- * (bigint → hex string). The mobile client passes this directly to
- * `eth_signTypedData_v4` / viem's `signTypedData`.
- */
-declare function serializeUserOpTypedData(td: UserOpTypedData): SerializedUserOpTypedData;
-/**
- * Merge Pimlico's paymaster-sponsorship response into a UserOp
- * skeleton, applying only fields that are actually defined.
- *
- * `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;
@@ -2269,4 +2593,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, BundlerNotConfiguredError, BundlerRejectedError, type BurnEvent, BurnIndexer, type BurnIndexerConfig, type BurnStatusParams, type BurnStatusResponse, type CombinedBalance, DefaultPolicyEngine, type DefaultPolicyEngineOptions, FeeManager, type FeeManagerConfig, type IIndexerCursorStore, type IPendingUserOpStore, type IPointLedger, type IPolicyEngine, type ISessionStore, InMemoryCursorStore, IssuerApiHandlers, type IssuerApiHandlersConfig, type IssuerRegistryRecord, type IssuerService, type IssuerServiceConfig, IssuerStateError, IssuerStateValidator, LockNotFoundError, type LockedMintRequest, type LoginResult, MemorySessionStore, type MemorySessionStoreOptions, type MintEvent, type MintStatusParams, type MintStatusResponse, type MintingStatus, type NativePtQuoterConfig, NonceManager, PAFI_ISSUER_SDK_VERSION, PTRedeemError, PTRedeemHandler, type PTRedeemHandlerConfig, type PTRedeemRequest, type PTRedeemResponse, PafiBackendClient, type PafiBackendConfig, PafiBackendError, type PafiBackendErrorCode, type PendingCredit, type PendingUserOpEntry, PointIndexer, type PointIndexerConfig, type PolicyDecision, type PolicyEvalRequest, type PoolsProvider, type PreValidateMintResult, type PrepareBurnDirectParams, type PrepareBurnParams, type PrepareBurnWithSigParams, type PrepareMintParams, type PrepareMobileUserOpParams, type PrepareMobileUserOpResult, type PreparedUserOp, RelayError, type RelayErrorCode, RelayService, type RelayUserOpParams, type RelayUserOpRequest, type RelayUserOpResponse, type RequestPaymasterParams, type RetryConfig, type SerializedUserOpTypedData, type Session, type SponsorshipRequest, type SponsorshipResponse, type SponsorshipTarget, type SponsorshipUserOp, type SubgraphNativeUsdtQuoterConfig, type SubgraphPoolsProviderConfig, TopUpRedemptionError, TopUpRedemptionHandler, type TopUpRedemptionHandlerConfig, type TopUpRedemptionRequest, type TopUpRedemptionResponse, authenticateRequest, createIssuerService, createNativePtQuoter, createSubgraphNativeUsdtQuoter, createSubgraphPoolsProvider, handleClaimStatus, handleRedeemStatus, mergePaymasterFields, prepareMobileUserOp, relayUserOp, requestPaymaster, serializeEntryToJsonRpc, serializeUserOpTypedData };
+export { type ApiClaimRequest, type ApiClaimResponse, type ApiConfigResponse, type ApiGasFeeResponse, type ApiLoginRequest, type ApiLoginResponse, type ApiNonceResponse, type ApiPoolsRequest, type ApiPoolsResponse, type ApiRedeemRequest, type ApiRedeemResponse, type ApiTopUpRequest, type ApiTopUpResponse, type ApiUserRequest, type ApiUserResponse, type AuthContext, AuthError, type AuthErrorCode, AuthService, type AuthServiceConfig, BalanceAggregator, type BalanceAggregatorConfig, BundlerNotConfiguredError, BundlerRejectedError, type BurnEvent, BurnIndexer, type BurnIndexerConfig, type BurnStatusParams, type BurnStatusResponse, type CombinedBalance, DefaultPolicyEngine, type DefaultPolicyEngineOptions, FeeManager, type FeeManagerConfig, type HandleMobilePrepareParams, type HandleMobilePrepareResult, type HandleMobileSubmitParams, type IIndexerCursorStore, type IPendingUserOpStore, type IPointLedger, type IPolicyEngine, type ISessionStore, InMemoryCursorStore, IssuerApiHandlers, type IssuerApiHandlersConfig, type IssuerRegistryRecord, type IssuerService, type IssuerServiceConfig, IssuerStateError, IssuerStateValidator, LockNotFoundError, type LockedMintRequest, type LoginResult, MemorySessionStore, type MemorySessionStoreOptions, type MintEvent, type MintStatusParams, type MintStatusResponse, type MintingStatus, type NativePtQuoterConfig, NonceManager, PAFI_ISSUER_SDK_VERSION, PTClaimError, PTClaimHandler, type PTClaimHandlerConfig, type PTClaimRequest, type PTClaimResponse, PTRedeemError, PTRedeemHandler, type PTRedeemHandlerConfig, type PTRedeemRequest, type PTRedeemResponse, PafiBackendClient, type PafiBackendConfig, PafiBackendError, type PafiBackendErrorCode, type PendingCredit, type PendingUserOpEntry, PendingUserOpNotFoundError, PerpDepositError, PerpDepositHandler, type PerpDepositHandlerConfig, type PerpDepositRequest, type PerpDepositResponse, PointIndexer, type PointIndexerConfig, type PolicyDecision, type PolicyEvalRequest, type PoolsProvider, type PreValidateMintResult, type PrepareBurnDirectParams, type PrepareBurnParams, type PrepareBurnWithSigParams, type PrepareMintParams, type PrepareMobileUserOpParams, type PrepareMobileUserOpResult, type PreparedUserOp, RelayError, type RelayErrorCode, RelayService, type RelayUserOpParams, type RelayUserOpRequest, type RelayUserOpResponse, type RequestPaymasterParams, type RetryConfig, type SerializedUserOpTypedData, type Session, type SponsorshipRequest, type SponsorshipResponse, type SponsorshipTarget, type SponsorshipUserOp, type SubgraphNativeUsdtQuoterConfig, type SubgraphPoolsProviderConfig, SwapError, SwapHandler, type SwapHandlerConfig, type SwapRequest, type SwapResponse, TopUpRedemptionError, TopUpRedemptionHandler, type TopUpRedemptionHandlerConfig, type TopUpRedemptionRequest, type TopUpRedemptionResponse, authenticateRequest, createIssuerService, createNativePtQuoter, createSubgraphNativeUsdtQuoter, createSubgraphPoolsProvider, handleClaimStatus, handleMobilePrepare, handleMobileSubmit, handleRedeemStatus, mergePaymasterFields, prepareMobileUserOp, relayUserOp, requestPaymaster, serializeEntryToJsonRpc, serializeUserOpTypedData };