@pafi-dev/issuer 0.5.35 → 0.5.37

package/dist/index.d.cts

@@ -1,5 +1,5 @@
 import { Address, Hex, PublicClient, WalletClient } from 'viem';
-import { PointTokenDomainConfig, PartialUserOperation, BurnRequest, PoolKey, UserOpTypedData, decodeBatchExecuteCalls, BROKER_HASHES, ENTRY_POINT_V08 } from '@pafi-dev/core';
+import { PointTokenDomainConfig, PartialUserOperation, BurnRequest, PoolKey, UserOpTypedData, decodeBatchExecuteCalls, BROKER_HASHES, Eip7702AuthorizationJsonRpc, ENTRY_POINT_V08 } from '@pafi-dev/core';
 export { PAFI_SUBGRAPH_URL } from '@pafi-dev/core';
 
 /**
@@ -1847,98 +1847,17 @@ declare function handleMobileSubmit(params: HandleMobileSubmitParams): Promise<{
     userOpHash: Hex;
 }>;
 
-interface IssuerRegistryRecord {
-    issuerAddress: Address;
-    signerAddress: Address;
-    name: string;
-    symbol: string;
-    declaredTotalSupply: bigint;
-    capBasisPoints: number;
-    active: boolean;
-    pointToken: Address;
-    mintingOracle: Address;
-}
-interface PreValidateMintResult {
-    /** Registry record read at pre-validation time. */
-    issuer: IssuerRegistryRecord;
-    /** Current on-chain PointToken.totalSupply(). */
-    totalSupply: bigint;
-    /** declaredTotalSupply × capBasisPoints / 10000. */
-    hardCap: bigint;
-    /** hardCap − totalSupply (clamped to 0). */
-    remaining: bigint;
-}
-/**
- * Thrown by `IssuerStateValidator.preValidateMint()`.
- * `code` maps 1:1 to the HTTP error the issuer API surfaces to clients.
- */
-declare class IssuerStateError extends Error {
-    readonly code: "ISSUER_NOT_REGISTERED" | "ISSUER_INACTIVE" | "MINT_CAP_EXCEEDED";
-    readonly details?: Record<string, unknown> | undefined;
-    constructor(code: "ISSUER_NOT_REGISTERED" | "ISSUER_INACTIVE" | "MINT_CAP_EXCEEDED", message: string, details?: Record<string, unknown> | undefined);
-}
+type DecodedCall$2 = ReturnType<typeof decodeBatchExecuteCalls>[number];
 
 /**
- * Pure (framework-agnostic) validator for issuer state.
- *
- * Reads IssuerRegistry + PointToken on-chain state and pre-validates
- * mint requests before the user submits a UserOp. Catching these
- * off-chain lets issuers fail fast with a clear error rather than
- * wasting gas on a revert.
- *
- * Caching:
- *   - `PointToken.issuer()` — memoized for the process lifetime (immutable)
- *   - Full state (registry + totalSupply) — 30s TTL per PointToken
- *   - Burst calls while a fetch is in-flight share the same Promise
- *     (thundering-herd protection)
- *
- * Usage in NestJS: wrap this in an `@Injectable()` service; pass
- * `PublicClient` and `registryAddress` from your DI container.
+ * 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.
  */
-declare class IssuerStateValidator {
-    private readonly provider;
-    private readonly registryAddress;
-    private readonly pointTokenIssuerCache;
-    private readonly stateCache;
-    private readonly inflight;
-    constructor(provider: PublicClient, registryAddress: Address);
-    /**
-     * Convenience factory — reads `registryAddress` from the SDK
-     * `CONTRACT_ADDRESSES` map for the given chain.
-     */
-    static forChain(provider: PublicClient, chainId: number): IssuerStateValidator;
-    /**
-     * Invalidate cached state for one PointToken, or everything if omitted.
-     * Call after admin txs that change registry or cap settings.
-     */
-    invalidate(pointToken?: Address): void;
-    /**
-     * Resolve `PointToken.issuer()` once per token and memoize.
-     * The issuer field is set at `initialize()` and never changes.
-     */
-    getIssuerAddressForPointToken(pointToken: Address): Promise<Address>;
-    /**
-     * Read registry record + totalSupply, with 30s cache and in-flight
-     * deduplication. Does NOT throw on inactive/missing — returns raw state.
-     */
-    getIssuerState(pointToken: Address): Promise<PreValidateMintResult>;
-    /**
-     * Validate that `amount` PT can be minted on `pointToken` right now.
-     *
-     * Throws `IssuerStateError` with:
-     *   - `ISSUER_NOT_REGISTERED` — registry has no record for this issuer
-     *   - `ISSUER_INACTIVE`       — issuer.active is false
-     *   - `MINT_CAP_EXCEEDED`     — totalSupply + amount would exceed hardCap
-     *
-     * Returns the fetched state on success so callers can log without a
-     * second RPC round-trip.
-     */
-    preValidateMint(pointToken: Address, amount: bigint): Promise<PreValidateMintResult>;
-    private fetchIssuerState;
+interface IssuerStateValidatorLike {
+    preValidateMint(pointToken: Address, amount: bigint): Promise<unknown>;
 }
-
-type DecodedCall$2 = ReturnType<typeof decodeBatchExecuteCalls>[number];
-
 /**
  * v1.4 sig-gated mint handler — mirrors `PTRedeemHandler` on the mint side.
  *
@@ -1971,7 +1890,7 @@ interface PTClaimHandlerConfig {
     /** Optional — when wired, used to estimate the PT gas-reimbursement fee. */
     feeService?: FeeManager;
     /** Optional — pre-validates issuer status + cap before locking balance. */
-    issuerStateValidator?: IssuerStateValidator;
+    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. */
@@ -2150,6 +2069,93 @@ declare class PerpDepositHandler {
     handle(request: PerpDepositRequest): Promise<PerpDepositResponse>;
 }
 
+/**
+ * Pure mechanics for the EIP-7702 delegation submit flow. Builds the
+ * empty-batch UserOp, attaches paymaster sponsorship, splits the user's
+ * authorization signature into the JSON-RPC tuple, and relays via the
+ * PAFI sponsor-relayer.
+ *
+ * The UserOp itself is a no-op — `BatchExecutor.execute([])` does
+ * nothing. The work is in the `eip7702Auth` object: the bundler picks
+ * it up, runs the EIP-7702 path, and installs the delegation on the
+ * user's EOA atomically with the (empty) UserOp.
+ *
+ * Throws the same `BundlerNotConfiguredError` / `BundlerRejectedError`
+ * as other relay paths so issuer controllers can use one error mapper.
+ */
+interface HandleDelegateSubmitParams {
+    userAddress: Address;
+    chainId: number;
+    /** Account nonce read at `delegate/prepare` time and signed by the user. */
+    delegationNonce: bigint;
+    /** ERC-4337 account nonce. Caller fetches via EntryPoint.getNonce. */
+    aaNonce: bigint;
+    /** 65-byte secp256k1 signature over the EIP-7702 authorization hash. */
+    authSig: Hex | string;
+    /** EIP-1559 fees from `provider.estimateFeesPerGas()` (or RPC equivalent). */
+    fees: {
+        maxFeePerGas?: bigint;
+        maxPriorityFeePerGas?: bigint;
+    };
+    pafiBackendClient?: PafiBackendClient | null;
+    onWarning?: (msg: string) => void;
+    /** Override gas limits for the empty-batch UserOp. */
+    gasLimits?: {
+        callGasLimit?: bigint;
+        verificationGasLimit?: bigint;
+        preVerificationGas?: bigint;
+    };
+}
+interface HandleDelegateSubmitResult {
+    userOpHash: Hex;
+    /** True when paymaster sponsorship was applied (gas is free). */
+    isSponsored: boolean;
+    /** The authorization tuple actually sent to the bundler. */
+    authorization: Eip7702AuthorizationJsonRpc;
+}
+declare function handleDelegateSubmit(params: HandleDelegateSubmitParams): Promise<HandleDelegateSubmitResult>;
+
+/**
+ * Quote PT → USDT for the cashout preview screen.
+ *
+ * Three branches the FE needs distinct handling for:
+ *   - `pointAmount = 0`           → all zeros, no RPC call.
+ *   - no pool / no path           → `quoteError: 'QUOTE_UNAVAILABLE'`.
+ *   - amountOut < gas reimbursement → `quoteError: 'AMOUNT_TOO_SMALL_FOR_GAS'`.
+ *
+ * Returns derived `netUsdtOut`, `exchangeRate`, and a `suggestedDeadline`
+ * so callers don't need to compute those locally.
+ *
+ * Replaces ~50 LoC of inline quote-handling in issuer controllers.
+ */
+interface QuotePointTokenToUsdtParams {
+    provider: PublicClient;
+    chainId: number;
+    pointTokenAddress: Address;
+    pointAmount: bigint;
+    pools: PoolKey[];
+    /** Operator gas-reimbursement quoted in USDT (subtracted from output). */
+    gasFeeUsdt: bigint;
+    /** Override deadline window; default 300 seconds. */
+    deadlineSeconds?: number;
+    now?: () => number;
+}
+interface QuotePointTokenToUsdtResult {
+    /** Raw V4 quote on the full point amount, before gas deduction. */
+    estimatedUsdtOut: bigint;
+    /** `estimatedUsdtOut - gasFeeUsdt`, clamped to 0. */
+    netUsdtOut: bigint;
+    /** USDT per 1.0 PT (1e18 raw units), formatted to 8 decimal places. */
+    exchangeRate: string;
+    /** V4 Quoter's gas estimate for the swap — informational. */
+    gasEstimate: bigint;
+    /** Unix seconds — `now + deadlineSeconds`. */
+    suggestedDeadline: number;
+    /** When set, the FE should hide the CTA / show "increase amount". */
+    quoteError?: "QUOTE_UNAVAILABLE" | "AMOUNT_TOO_SMALL_FOR_GAS";
+}
+declare function quotePointTokenToUsdt(params: QuotePointTokenToUsdtParams): Promise<QuotePointTokenToUsdtResult>;
+
 /**
  * Config for `createSubgraphPoolsProvider`.
  */
@@ -2581,7 +2587,97 @@ interface IssuerService {
  */
 declare function createIssuerService(config: IssuerServiceConfig): IssuerService;
 
+interface IssuerRegistryRecord {
+    issuerAddress: Address;
+    signerAddress: Address;
+    name: string;
+    symbol: string;
+    declaredTotalSupply: bigint;
+    capBasisPoints: number;
+    active: boolean;
+    pointToken: Address;
+    mintingOracle: Address;
+}
+interface PreValidateMintResult {
+    /** Registry record read at pre-validation time. */
+    issuer: IssuerRegistryRecord;
+    /** Current on-chain PointToken.totalSupply(). */
+    totalSupply: bigint;
+    /** declaredTotalSupply × capBasisPoints / 10000. */
+    hardCap: bigint;
+    /** hardCap − totalSupply (clamped to 0). */
+    remaining: bigint;
+}
+/**
+ * Thrown by `IssuerStateValidator.preValidateMint()`.
+ * `code` maps 1:1 to the HTTP error the issuer API surfaces to clients.
+ */
+declare class IssuerStateError extends Error {
+    readonly code: "ISSUER_NOT_REGISTERED" | "ISSUER_INACTIVE" | "MINT_CAP_EXCEEDED";
+    readonly details?: Record<string, unknown> | undefined;
+    constructor(code: "ISSUER_NOT_REGISTERED" | "ISSUER_INACTIVE" | "MINT_CAP_EXCEEDED", message: string, details?: Record<string, unknown> | undefined);
+}
+
+/**
+ * Pure (framework-agnostic) validator for issuer state.
+ *
+ * Reads IssuerRegistry + PointToken on-chain state and pre-validates
+ * mint requests before the user submits a UserOp. Catching these
+ * off-chain lets issuers fail fast with a clear error rather than
+ * wasting gas on a revert.
+ *
+ * Caching:
+ *   - `PointToken.issuer()` — memoized for the process lifetime (immutable)
+ *   - Full state (registry + totalSupply) — 30s TTL per PointToken
+ *   - Burst calls while a fetch is in-flight share the same Promise
+ *     (thundering-herd protection)
+ *
+ * Usage in NestJS: wrap this in an `@Injectable()` service; pass
+ * `PublicClient` and `registryAddress` from your DI container.
+ */
+declare class IssuerStateValidator {
+    private readonly provider;
+    private readonly registryAddress;
+    private readonly pointTokenIssuerCache;
+    private readonly stateCache;
+    private readonly inflight;
+    constructor(provider: PublicClient, registryAddress: Address);
+    /**
+     * Convenience factory — reads `registryAddress` from the SDK
+     * `CONTRACT_ADDRESSES` map for the given chain.
+     */
+    static forChain(provider: PublicClient, chainId: number): IssuerStateValidator;
+    /**
+     * Invalidate cached state for one PointToken, or everything if omitted.
+     * Call after admin txs that change registry or cap settings.
+     */
+    invalidate(pointToken?: Address): void;
+    /**
+     * Resolve `PointToken.issuer()` once per token and memoize.
+     * The issuer field is set at `initialize()` and never changes.
+     */
+    getIssuerAddressForPointToken(pointToken: Address): Promise<Address>;
+    /**
+     * Read registry record + totalSupply, with 30s cache and in-flight
+     * deduplication. Does NOT throw on inactive/missing — returns raw state.
+     */
+    getIssuerState(pointToken: Address): Promise<PreValidateMintResult>;
+    /**
+     * Validate that `amount` PT can be minted on `pointToken` right now.
+     *
+     * Throws `IssuerStateError` with:
+     *   - `ISSUER_NOT_REGISTERED` — registry has no record for this issuer
+     *   - `ISSUER_INACTIVE`       — issuer.active is false
+     *   - `MINT_CAP_EXCEEDED`     — totalSupply + amount would exceed hardCap
+     *
+     * Returns the fetched state on success so callers can log without a
+     * second RPC round-trip.
+     */
+    preValidateMint(pointToken: Address, amount: bigint): Promise<PreValidateMintResult>;
+    private fetchIssuerState;
+}
+
 /** 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 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 };
+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 HandleDelegateSubmitParams, type HandleDelegateSubmitResult, 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, type QuotePointTokenToUsdtParams, type QuotePointTokenToUsdtResult, 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, handleDelegateSubmit, handleMobilePrepare, handleMobileSubmit, handleRedeemStatus, mergePaymasterFields, prepareMobileUserOp, quotePointTokenToUsdt, relayUserOp, requestPaymaster, serializeEntryToJsonRpc, serializeUserOpTypedData };

package/dist/index.d.ts

@@ -1,5 +1,5 @@
 import { Address, Hex, PublicClient, WalletClient } from 'viem';
-import { PointTokenDomainConfig, PartialUserOperation, BurnRequest, PoolKey, UserOpTypedData, decodeBatchExecuteCalls, BROKER_HASHES, ENTRY_POINT_V08 } from '@pafi-dev/core';
+import { PointTokenDomainConfig, PartialUserOperation, BurnRequest, PoolKey, UserOpTypedData, decodeBatchExecuteCalls, BROKER_HASHES, Eip7702AuthorizationJsonRpc, ENTRY_POINT_V08 } from '@pafi-dev/core';
 export { PAFI_SUBGRAPH_URL } from '@pafi-dev/core';
 
 /**
@@ -1847,98 +1847,17 @@ declare function handleMobileSubmit(params: HandleMobileSubmitParams): Promise<{
     userOpHash: Hex;
 }>;
 
-interface IssuerRegistryRecord {
-    issuerAddress: Address;
-    signerAddress: Address;
-    name: string;
-    symbol: string;
-    declaredTotalSupply: bigint;
-    capBasisPoints: number;
-    active: boolean;
-    pointToken: Address;
-    mintingOracle: Address;
-}
-interface PreValidateMintResult {
-    /** Registry record read at pre-validation time. */
-    issuer: IssuerRegistryRecord;
-    /** Current on-chain PointToken.totalSupply(). */
-    totalSupply: bigint;
-    /** declaredTotalSupply × capBasisPoints / 10000. */
-    hardCap: bigint;
-    /** hardCap − totalSupply (clamped to 0). */
-    remaining: bigint;
-}
-/**
- * Thrown by `IssuerStateValidator.preValidateMint()`.
- * `code` maps 1:1 to the HTTP error the issuer API surfaces to clients.
- */
-declare class IssuerStateError extends Error {
-    readonly code: "ISSUER_NOT_REGISTERED" | "ISSUER_INACTIVE" | "MINT_CAP_EXCEEDED";
-    readonly details?: Record<string, unknown> | undefined;
-    constructor(code: "ISSUER_NOT_REGISTERED" | "ISSUER_INACTIVE" | "MINT_CAP_EXCEEDED", message: string, details?: Record<string, unknown> | undefined);
-}
+type DecodedCall$2 = ReturnType<typeof decodeBatchExecuteCalls>[number];
 
 /**
- * Pure (framework-agnostic) validator for issuer state.
- *
- * Reads IssuerRegistry + PointToken on-chain state and pre-validates
- * mint requests before the user submits a UserOp. Catching these
- * off-chain lets issuers fail fast with a clear error rather than
- * wasting gas on a revert.
- *
- * Caching:
- *   - `PointToken.issuer()` — memoized for the process lifetime (immutable)
- *   - Full state (registry + totalSupply) — 30s TTL per PointToken
- *   - Burst calls while a fetch is in-flight share the same Promise
- *     (thundering-herd protection)
- *
- * Usage in NestJS: wrap this in an `@Injectable()` service; pass
- * `PublicClient` and `registryAddress` from your DI container.
+ * 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.
  */
-declare class IssuerStateValidator {
-    private readonly provider;
-    private readonly registryAddress;
-    private readonly pointTokenIssuerCache;
-    private readonly stateCache;
-    private readonly inflight;
-    constructor(provider: PublicClient, registryAddress: Address);
-    /**
-     * Convenience factory — reads `registryAddress` from the SDK
-     * `CONTRACT_ADDRESSES` map for the given chain.
-     */
-    static forChain(provider: PublicClient, chainId: number): IssuerStateValidator;
-    /**
-     * Invalidate cached state for one PointToken, or everything if omitted.
-     * Call after admin txs that change registry or cap settings.
-     */
-    invalidate(pointToken?: Address): void;
-    /**
-     * Resolve `PointToken.issuer()` once per token and memoize.
-     * The issuer field is set at `initialize()` and never changes.
-     */
-    getIssuerAddressForPointToken(pointToken: Address): Promise<Address>;
-    /**
-     * Read registry record + totalSupply, with 30s cache and in-flight
-     * deduplication. Does NOT throw on inactive/missing — returns raw state.
-     */
-    getIssuerState(pointToken: Address): Promise<PreValidateMintResult>;
-    /**
-     * Validate that `amount` PT can be minted on `pointToken` right now.
-     *
-     * Throws `IssuerStateError` with:
-     *   - `ISSUER_NOT_REGISTERED` — registry has no record for this issuer
-     *   - `ISSUER_INACTIVE`       — issuer.active is false
-     *   - `MINT_CAP_EXCEEDED`     — totalSupply + amount would exceed hardCap
-     *
-     * Returns the fetched state on success so callers can log without a
-     * second RPC round-trip.
-     */
-    preValidateMint(pointToken: Address, amount: bigint): Promise<PreValidateMintResult>;
-    private fetchIssuerState;
+interface IssuerStateValidatorLike {
+    preValidateMint(pointToken: Address, amount: bigint): Promise<unknown>;
 }
-
-type DecodedCall$2 = ReturnType<typeof decodeBatchExecuteCalls>[number];
-
 /**
  * v1.4 sig-gated mint handler — mirrors `PTRedeemHandler` on the mint side.
  *
@@ -1971,7 +1890,7 @@ interface PTClaimHandlerConfig {
     /** Optional — when wired, used to estimate the PT gas-reimbursement fee. */
     feeService?: FeeManager;
     /** Optional — pre-validates issuer status + cap before locking balance. */
-    issuerStateValidator?: IssuerStateValidator;
+    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. */
@@ -2150,6 +2069,93 @@ declare class PerpDepositHandler {
     handle(request: PerpDepositRequest): Promise<PerpDepositResponse>;
 }
 
+/**
+ * Pure mechanics for the EIP-7702 delegation submit flow. Builds the
+ * empty-batch UserOp, attaches paymaster sponsorship, splits the user's
+ * authorization signature into the JSON-RPC tuple, and relays via the
+ * PAFI sponsor-relayer.
+ *
+ * The UserOp itself is a no-op — `BatchExecutor.execute([])` does
+ * nothing. The work is in the `eip7702Auth` object: the bundler picks
+ * it up, runs the EIP-7702 path, and installs the delegation on the
+ * user's EOA atomically with the (empty) UserOp.
+ *
+ * Throws the same `BundlerNotConfiguredError` / `BundlerRejectedError`
+ * as other relay paths so issuer controllers can use one error mapper.
+ */
+interface HandleDelegateSubmitParams {
+    userAddress: Address;
+    chainId: number;
+    /** Account nonce read at `delegate/prepare` time and signed by the user. */
+    delegationNonce: bigint;
+    /** ERC-4337 account nonce. Caller fetches via EntryPoint.getNonce. */
+    aaNonce: bigint;
+    /** 65-byte secp256k1 signature over the EIP-7702 authorization hash. */
+    authSig: Hex | string;
+    /** EIP-1559 fees from `provider.estimateFeesPerGas()` (or RPC equivalent). */
+    fees: {
+        maxFeePerGas?: bigint;
+        maxPriorityFeePerGas?: bigint;
+    };
+    pafiBackendClient?: PafiBackendClient | null;
+    onWarning?: (msg: string) => void;
+    /** Override gas limits for the empty-batch UserOp. */
+    gasLimits?: {
+        callGasLimit?: bigint;
+        verificationGasLimit?: bigint;
+        preVerificationGas?: bigint;
+    };
+}
+interface HandleDelegateSubmitResult {
+    userOpHash: Hex;
+    /** True when paymaster sponsorship was applied (gas is free). */
+    isSponsored: boolean;
+    /** The authorization tuple actually sent to the bundler. */
+    authorization: Eip7702AuthorizationJsonRpc;
+}
+declare function handleDelegateSubmit(params: HandleDelegateSubmitParams): Promise<HandleDelegateSubmitResult>;
+
+/**
+ * Quote PT → USDT for the cashout preview screen.
+ *
+ * Three branches the FE needs distinct handling for:
+ *   - `pointAmount = 0`           → all zeros, no RPC call.
+ *   - no pool / no path           → `quoteError: 'QUOTE_UNAVAILABLE'`.
+ *   - amountOut < gas reimbursement → `quoteError: 'AMOUNT_TOO_SMALL_FOR_GAS'`.
+ *
+ * Returns derived `netUsdtOut`, `exchangeRate`, and a `suggestedDeadline`
+ * so callers don't need to compute those locally.
+ *
+ * Replaces ~50 LoC of inline quote-handling in issuer controllers.
+ */
+interface QuotePointTokenToUsdtParams {
+    provider: PublicClient;
+    chainId: number;
+    pointTokenAddress: Address;
+    pointAmount: bigint;
+    pools: PoolKey[];
+    /** Operator gas-reimbursement quoted in USDT (subtracted from output). */
+    gasFeeUsdt: bigint;
+    /** Override deadline window; default 300 seconds. */
+    deadlineSeconds?: number;
+    now?: () => number;
+}
+interface QuotePointTokenToUsdtResult {
+    /** Raw V4 quote on the full point amount, before gas deduction. */
+    estimatedUsdtOut: bigint;
+    /** `estimatedUsdtOut - gasFeeUsdt`, clamped to 0. */
+    netUsdtOut: bigint;
+    /** USDT per 1.0 PT (1e18 raw units), formatted to 8 decimal places. */
+    exchangeRate: string;
+    /** V4 Quoter's gas estimate for the swap — informational. */
+    gasEstimate: bigint;
+    /** Unix seconds — `now + deadlineSeconds`. */
+    suggestedDeadline: number;
+    /** When set, the FE should hide the CTA / show "increase amount". */
+    quoteError?: "QUOTE_UNAVAILABLE" | "AMOUNT_TOO_SMALL_FOR_GAS";
+}
+declare function quotePointTokenToUsdt(params: QuotePointTokenToUsdtParams): Promise<QuotePointTokenToUsdtResult>;
+
 /**
  * Config for `createSubgraphPoolsProvider`.
  */
@@ -2581,7 +2587,97 @@ interface IssuerService {
  */
 declare function createIssuerService(config: IssuerServiceConfig): IssuerService;
 
+interface IssuerRegistryRecord {
+    issuerAddress: Address;
+    signerAddress: Address;
+    name: string;
+    symbol: string;
+    declaredTotalSupply: bigint;
+    capBasisPoints: number;
+    active: boolean;
+    pointToken: Address;
+    mintingOracle: Address;
+}
+interface PreValidateMintResult {
+    /** Registry record read at pre-validation time. */
+    issuer: IssuerRegistryRecord;
+    /** Current on-chain PointToken.totalSupply(). */
+    totalSupply: bigint;
+    /** declaredTotalSupply × capBasisPoints / 10000. */
+    hardCap: bigint;
+    /** hardCap − totalSupply (clamped to 0). */
+    remaining: bigint;
+}
+/**
+ * Thrown by `IssuerStateValidator.preValidateMint()`.
+ * `code` maps 1:1 to the HTTP error the issuer API surfaces to clients.
+ */
+declare class IssuerStateError extends Error {
+    readonly code: "ISSUER_NOT_REGISTERED" | "ISSUER_INACTIVE" | "MINT_CAP_EXCEEDED";
+    readonly details?: Record<string, unknown> | undefined;
+    constructor(code: "ISSUER_NOT_REGISTERED" | "ISSUER_INACTIVE" | "MINT_CAP_EXCEEDED", message: string, details?: Record<string, unknown> | undefined);
+}
+
+/**
+ * Pure (framework-agnostic) validator for issuer state.
+ *
+ * Reads IssuerRegistry + PointToken on-chain state and pre-validates
+ * mint requests before the user submits a UserOp. Catching these
+ * off-chain lets issuers fail fast with a clear error rather than
+ * wasting gas on a revert.
+ *
+ * Caching:
+ *   - `PointToken.issuer()` — memoized for the process lifetime (immutable)
+ *   - Full state (registry + totalSupply) — 30s TTL per PointToken
+ *   - Burst calls while a fetch is in-flight share the same Promise
+ *     (thundering-herd protection)
+ *
+ * Usage in NestJS: wrap this in an `@Injectable()` service; pass
+ * `PublicClient` and `registryAddress` from your DI container.
+ */
+declare class IssuerStateValidator {
+    private readonly provider;
+    private readonly registryAddress;
+    private readonly pointTokenIssuerCache;
+    private readonly stateCache;
+    private readonly inflight;
+    constructor(provider: PublicClient, registryAddress: Address);
+    /**
+     * Convenience factory — reads `registryAddress` from the SDK
+     * `CONTRACT_ADDRESSES` map for the given chain.
+     */
+    static forChain(provider: PublicClient, chainId: number): IssuerStateValidator;
+    /**
+     * Invalidate cached state for one PointToken, or everything if omitted.
+     * Call after admin txs that change registry or cap settings.
+     */
+    invalidate(pointToken?: Address): void;
+    /**
+     * Resolve `PointToken.issuer()` once per token and memoize.
+     * The issuer field is set at `initialize()` and never changes.
+     */
+    getIssuerAddressForPointToken(pointToken: Address): Promise<Address>;
+    /**
+     * Read registry record + totalSupply, with 30s cache and in-flight
+     * deduplication. Does NOT throw on inactive/missing — returns raw state.
+     */
+    getIssuerState(pointToken: Address): Promise<PreValidateMintResult>;
+    /**
+     * Validate that `amount` PT can be minted on `pointToken` right now.
+     *
+     * Throws `IssuerStateError` with:
+     *   - `ISSUER_NOT_REGISTERED` — registry has no record for this issuer
+     *   - `ISSUER_INACTIVE`       — issuer.active is false
+     *   - `MINT_CAP_EXCEEDED`     — totalSupply + amount would exceed hardCap
+     *
+     * Returns the fetched state on success so callers can log without a
+     * second RPC round-trip.
+     */
+    preValidateMint(pointToken: Address, amount: bigint): Promise<PreValidateMintResult>;
+    private fetchIssuerState;
+}
+
 /** 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 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 };
+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 HandleDelegateSubmitParams, type HandleDelegateSubmitResult, 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, type QuotePointTokenToUsdtParams, type QuotePointTokenToUsdtResult, 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, handleDelegateSubmit, handleMobilePrepare, handleMobileSubmit, handleRedeemStatus, mergePaymasterFields, prepareMobileUserOp, quotePointTokenToUsdt, relayUserOp, requestPaymaster, serializeEntryToJsonRpc, serializeUserOpTypedData };