@pafi-dev/issuer 0.16.0 → 0.18.0

package/dist/index.d.cts

@@ -621,6 +621,14 @@ declare class RelayService {
      * issuer-signed `BurnRequest` path.
      */
     prepareBurn(params: PrepareBurnParams): Promise<PartialUserOperation>;
+    /**
+     * Build a dummy `PartialUserOperation` for the mint scenario, suitable
+     * for `feeManager.estimateGasFee({ partialUserOp, ... })`. NO signing —
+     * uses a 65-byte zero signature in place of the real minter sig.
+     */
+    previewMintUserOp(params: PreviewMintParams): PartialUserOperation;
+    /** Burn-side mirror of `previewMintUserOp`. */
+    previewBurnUserOp(params: PreviewBurnParams): PartialUserOperation;
 }
 /**
  * Sig-gated `PointToken.mint(to, amount, deadline, minterSig)`.
@@ -707,19 +715,131 @@ interface PrepareBurnParams {
     verificationGasLimit?: bigint;
     preVerificationGas?: bigint;
 }
+/**
+ * Inputs for `previewMintUserOp` — strict subset of `PrepareMintParams`
+ * that excludes the signing wallet, EIP-712 domain, and on-chain nonce.
+ * These don't affect calldata shape so the bundler estimate doesn't
+ * need them.
+ */
+interface PreviewMintParams {
+    userAddress: Address;
+    aaNonce: bigint;
+    pointTokenAddress: Address;
+    amount: bigint;
+    deadline: bigint;
+    mintFeeWrapperAddress?: Address;
+}
+interface PreviewBurnParams {
+    userAddress: Address;
+    aaNonce: bigint;
+    pointTokenAddress: Address;
+    amount: bigint;
+    deadline: bigint;
+}
+
+/**
+ * In-memory cache for bundler-estimated gas units, keyed by
+ * `(scenario, contractCodehash, paymaster)`.
+ *
+ * Why these key components:
+ *  - `scenario`           — distinguishes mint vs burn vs swap; their UserOps
+ *                           differ in calldata shape so estimates differ.
+ *  - `contractCodehash`   — fetched from the SC address via `eth_getCode`,
+ *                           cached separately for 1h. When the SC is upgraded
+ *                           the codehash changes → the gas key auto-invalidates
+ *                           (no manual purge needed).
+ *  - `paymaster`          — paymaster contract version affects postOp gas;
+ *                           rotating paymaster naturally invalidates.
+ *
+ * Bound: max `maxEntries` to defend against unbounded growth on
+ * long-running issuer backends; eldest evicted first (LRU-by-insertion).
+ */
+interface GasUnitsCacheConfig {
+    /** Gas-units cache TTL in ms. Default 5 minutes. */
+    ttlMs?: number;
+    /** Codehash cache TTL in ms. Default 1 hour. */
+    codehashTtlMs?: number;
+    /** Max entries before LRU eviction. Default 100. */
+    maxEntries?: number;
+}
+declare class GasUnitsCache {
+    private readonly entries;
+    private readonly codehashEntries;
+    private readonly ttlMs;
+    private readonly codehashTtlMs;
+    private readonly maxEntries;
+    constructor(config?: GasUnitsCacheConfig);
+    buildKey(params: {
+        scenario: string;
+        contractAddress: Address;
+        paymasterAddress?: Address;
+        provider: PublicClient;
+    }): Promise<string>;
+    get(key: string, now?: number): bigint | null;
+    set(key: string, gasUnits: bigint, now?: number): void;
+    invalidate(): void;
+    size(): number;
+    private getCodehash;
+}
 
+/**
+ * Minimal duck-typed shape of an ERC-4337 bundler client supporting
+ * `eth_estimateUserOperationGas`. Compatible with `permissionless`'s
+ * `createBundlerClient` and any spec-compliant bundler (Pimlico, Alchemy,
+ * StackUp, Biconomy). The SDK does NOT add `permissionless` as a hard
+ * dependency — callers pass whatever client they already use.
+ */
+interface BundlerEstimatorClient {
+    estimateUserOperationGas(args: {
+        sender: Address;
+        nonce: bigint;
+        callData: Hex;
+        signature?: Hex;
+        paymaster?: Address;
+        paymasterData?: Hex;
+    }): Promise<{
+        callGasLimit: bigint;
+        verificationGasLimit: bigint;
+        preVerificationGas: bigint;
+        paymasterVerificationGasLimit?: bigint;
+        paymasterPostOpGasLimit?: bigint;
+    }>;
+}
+type GasFeeSource = "cache" | "bundler" | "fallback";
+/**
+ * Hooks called by `FeeManager` so callers can wire their own
+ * observability (Pino logger, Prometheus counters, ...). All hooks are
+ * synchronous and best-effort — they MUST NOT throw.
+ */
+interface FeeManagerMetrics {
+    onEstimate?: (info: {
+        source: GasFeeSource;
+        scenario?: string;
+        gasUnits: bigint;
+        latencyMs: number;
+    }) => void;
+    onBundlerError?: (info: {
+        scenario?: string;
+        reason: string;
+    }) => void;
+}
 interface FeeManagerConfig {
-    /** Provider used for gas price reads. */
+    /** Provider used for gas price reads + codehash lookup. */
     provider: PublicClient;
     /**
-     * Typical gas used by a single sponsored UserOp. Default: 500_000.
-     * The manager multiplies this by current gas price to get native
-     * cost, then converts via the injected `quoteNativeToFee`.
+     * Hardcoded fallback gas units, used when (a) `bundlerClient` is not
+     * configured OR (b) the bundler call fails. Default: 500_000.
      */
     gasUnits?: bigint;
     /**
-     * Safety margin applied before charging the user, as basis points.
-     * 12_000 = 120%. Default: 12_000.
+     * Safety margin applied on top of the bundler/fallback estimate, in
+     * basis points. 10_000 = 100% (no extra). Default: 10_000.
+     *
+     * Pimlico's `eth_estimateUserOperationGas` already adds ~10-15% safety
+     * margin internally, so a second SDK-side premium just pads padding
+     * and over-charges users. We dropped the historical 12_000 (120%)
+     * default after measuring `actualGasUsed / estimate ≈ 0.92` across
+     * 100 dev mints.
      */
     gasPremiumBps?: number;
     /**
@@ -732,6 +852,60 @@ interface FeeManagerConfig {
      * or an oracle feed.
      */
     quoteNativeToFee: (amountNative: bigint) => Promise<bigint>;
+    /**
+     * Optional ERC-4337 bundler client. When set, `estimateGasFee({
+     * partialUserOp, ... })` will call `eth_estimateUserOperationGas`
+     * (cached) for per-UserOp accuracy. Omit to keep the legacy hardcoded
+     * path.
+     */
+    bundlerClient?: BundlerEstimatorClient;
+    /** Gas-units cache config — see `GasUnitsCache`. */
+    cache?: GasUnitsCacheConfig;
+    /**
+     * Fixed overhead added to bundler estimates to account for paymaster
+     * verification + postOp gas, since we estimate WITHOUT paymaster
+     * context (chicken-and-egg: paymaster data depends on gas limits).
+     * Default: 80_000 — covers Pimlico singleton paymaster v0.7 postOp.
+     */
+    paymasterOverheadGas?: bigint;
+    /** Optional observability hooks. */
+    metrics?: FeeManagerMetrics;
+}
+/**
+ * Parameters for a single bundler-driven `estimateGasFee` call.
+ *
+ * All fields optional for backwards compat: when `partialUserOp` is
+ * omitted, FeeManager falls back to the legacy `gasUnits × gasPrice`
+ * path.
+ */
+interface EstimateGasFeeOptions {
+    /**
+     * Partial UserOperation to simulate. The bundler runs the calldata in
+     * a virtual EVM and returns gas limits. Pass `signature` as a 65-byte
+     * dummy when the user hasn't signed yet.
+     *
+     * Estimate WITHOUT paymaster fields (paymaster/paymasterData omitted)
+     * to avoid the chicken-and-egg with paymasterData generation —
+     * `paymasterOverheadGas` is added afterwards.
+     */
+    partialUserOp?: {
+        sender: Address;
+        nonce: bigint;
+        callData: Hex;
+        signature?: Hex;
+    };
+    /**
+     * Contract address being called — used for cache key (codehash
+     * lookup). Typically the PointToken address for mint/burn.
+     */
+    contractAddress?: Address;
+    /** Scenario label used in the cache key (e.g. 'mint', 'burn'). */
+    scenario?: string;
+    /**
+     * Paymaster address used in the cache key. When omitted, '0x0' is
+     * used — fine if a single paymaster is used across the deployment.
+     */
+    paymasterAddress?: Address;
 }
 /**
  * Computes how much fee to collect from the user to cover the gas cost
@@ -740,34 +914,55 @@ interface FeeManagerConfig {
  * The fee is expressed in the **fee currency** chosen by the caller
  * (PT for mint/burn, USDT for swap/perp_deposit) — not hardcoded.
  *
+ * Two paths:
+ *  1. Legacy (no `bundlerClient`):  gasUnits × gasPrice × premium
+ *  2. Bundler (recommended):         bundler.estimateUserOperationGas →
+ *                                    sum gas limits → × gasPrice × premium
+ *
+ * The bundler path caches by `(scenario, contractCodehash, paymaster)`
+ * for ~99% hit rate after warm-up; cache invalidates automatically on
+ * SC upgrade via codehash change.
+ *
  * **No operator rebalancing.** The operator does not hold ETH directly;
- * gas is paid by PAFI sponsor-relayer via the paymaster-proxy (see
- * [SPONSORED_PATH_FLOW.md]). The fee collected here is an
- * application-level ERC-20 transfer inside the same UserOp batch, not a
- * reimbursement to a wallet that needs topping up.
+ * gas is paid by PAFI sponsor-relayer via the paymaster-proxy. The fee
+ * collected here is an application-level ERC-20 transfer inside the same
+ * UserOp batch, not a reimbursement to a wallet that needs topping up.
  */
 declare class FeeManager {
     private readonly provider;
     private readonly gasUnits;
     private readonly gasPremiumBps;
     private readonly quoteNativeToFee;
+    private readonly bundlerClient;
+    private readonly cache;
+    private readonly paymasterOverheadGas;
+    private readonly metrics;
     private cachedFee;
     private cacheExpiresAt;
-    private static readonly CACHE_TTL_MS;
+    private static readonly FEE_CACHE_TTL_MS;
     constructor(config: FeeManagerConfig);
     /**
      * Estimate the fee (in the caller's fee currency) to charge for the
-     * next sponsored UserOp:
+     * next sponsored UserOp.
      *
+     *   gasUnits      = bundler-estimated (cached) or hardcoded fallback
      *   nativeCost    = gasUnits × gasPrice
      *   withPremium   = nativeCost × premiumBps / 10_000
      *   fee           = quoteNativeToFee(withPremium)
      *
-     * For backward compatibility with v0.2.x code that reads `gasFeeUsdt`
-     * from the response, the name `estimateGasFee` is kept — but the
-     * currency depends on how the caller wired `quoteNativeToFee`.
+     * When `opts.partialUserOp` is omitted, behaves exactly like v0.16.x:
+     * uses the hardcoded `gasUnits` default.
+     */
+    estimateGasFee(opts?: EstimateGasFeeOptions): Promise<bigint>;
+    /**
+     * Manually purge the per-scenario gas-units cache. Useful after an SC
+     * upgrade when ops wants the next estimate to refresh immediately
+     * (the codehash check would catch it on the NEXT call anyway, but
+     * this forces it now).
      */
-    estimateGasFee(): Promise<bigint>;
+    invalidateCache(): void;
+    private resolveGasUnits;
+    private safeEmit;
 }
 
 /** Decoded Transfer(from=0x0 → to) event used to finalize a mint. */
@@ -3487,4 +3682,4 @@ declare class MemoryRedemptionHistoryStore implements IRedemptionHistoryStore {
 
 declare const PAFI_ISSUER_SDK_VERSION: string;
 
-export { AdapterMisconfiguredError, type ApiConfigResponse, type ApiGasFeeResponse, type ApiLoginRequest, type ApiLoginResponse, type ApiNonceResponse, type ApiPoolsRequest, type ApiPoolsResponse, type ApiRedemptionEvaluateRequest, type ApiRedemptionEvaluateResponse, type ApiRedemptionPreviewRequest, type ApiRedemptionPreviewResponse, type ApiUserRequest, type ApiUserResponse, type AuthContext, AuthError, type AuthErrorCode, AuthService, type AuthServiceConfig, BundlerNotConfiguredError, BundlerRejectedError, type BurnEvent, BurnIndexer, type BurnIndexerConfig, type BurnStatusParams, type BurnStatusResponse, type ClaimDto, type ConfigDto, ConfigurationError, DEFAULT_REDEMPTION_POLICY, type DecodedCallDto, DefaultPolicyEngine, type DefaultPolicyEngineOptions, type DelegatePrepareDto, type DelegateStatusDto, type EvaluateInput, FeeManager, type FeeManagerConfig, type FetchFailureReason, type FetchResult, type GasFeeDto, type HandleDelegateSubmitParams, type HandleDelegateSubmitResult, type HandleMobilePrepareParams, type HandleMobilePrepareResult, type HandleMobileSubmitParams, type IIndexerCursorStore, type IPendingUserOpStore, type IPointLedger, type IPolicyEngine, type IRateLimiter, type IRedemptionHistoryStore, type ISessionStore, InMemoryCursorStore, IssuerApiAdapter, type IssuerApiAdapterConfig, IssuerApiHandlers, type IssuerApiHandlersConfig, type IssuerRegistryRecord, type IssuerService, type IssuerServiceConfig, IssuerStateError, IssuerStateValidator, LockNotFoundError, type LockedMintRequest, type LoginResult, MemoryPendingUserOpStore, MemoryRateLimiter, MemoryRedemptionHistoryStore, MemorySessionStore, type MemorySessionStoreOptions, type MintEvent, type MintStatusParams, type MintStatusResponse, type MintingStatus, type MobilePrepareDto, type MobileSubmitDto, type NativePtQuoterConfig, NonceManager, NoopRateLimiter, PAFI_ISSUER_SDK_VERSION, PTClaimError, PTClaimHandler, type PTClaimHandlerConfig, type PTClaimRequest, type PTClaimResponse, PTRedeemError, PTRedeemHandler, type PTRedeemHandlerConfig, type PTRedeemRequest, type PTRedeemResponse, PafiBackendClient, type PafiBackendConfig, PafiBackendError, type PafiBackendErrorCode, type PaymasterGasEstimates, type PendingCredit, type PendingUserOpEntry, PendingUserOpForbiddenError, PendingUserOpNotFoundError, type PerpDepositDto, PerpDepositError, PerpDepositHandler, type PerpDepositHandlerConfig, type PerpDepositRequest, type PerpDepositResponse, PointIndexer, type PointIndexerConfig, type PolicyDecision, type PolicyEvalRequest, PolicyProvider, type PolicyProviderConfig, type PoolsDto, type PoolsProvider, type PreValidateMintResult, type PrepareBurnParams, type PrepareMintParams, type PrepareMobileUserOpParams, type PrepareMobileUserOpResult, type PreparedUserOp, REDEMPTION_HISTORY_WINDOW_SEC, type RateLimitAction, type RateLimiterConfig, type RedeemDto, type RedeemPrepareDto, RedemptionService, type RedemptionServiceConfig, RelayError, type RelayErrorCode, RelayService, type RelayUserOpParams, type RelayUserOpRequest, type RelayUserOpResponse, type RequestPaymasterParams, type ResolvedPolicy, type RetryConfig, type SdkErrorBody, type SdkErrorMapperFactories, type SdkErrorStatus, type SerializedUserOpTypedData, type Session, SettlementClient, type SettlementClientConfig, type SponsorshipRequest, type SponsorshipResponse, type SponsorshipTarget, type SponsorshipUserOp, type SubgraphNativeUsdtQuoterConfig, type SubgraphPoolsProviderConfig, type UserDto, type UserHistory, applyPaymasterGasEstimates, authenticateRequest, buildSdkErrorBody, createIssuerService, createNativePtQuoter, createSdkErrorMapper, createSubgraphNativeUsdtQuoter, createSubgraphPoolsProvider, defaultPolicyFor, evaluateRedemption, handleClaimStatus, handleDelegateSubmit, handleMobilePrepare, handleMobileSubmit, handleRedeemStatus, mergePaymasterFields, prepareMobileUserOp, relayUserOp, requestPaymaster, serializeEntryToJsonRpc, serializeUserOpTypedData };
+export { AdapterMisconfiguredError, type ApiConfigResponse, type ApiGasFeeResponse, type ApiLoginRequest, type ApiLoginResponse, type ApiNonceResponse, type ApiPoolsRequest, type ApiPoolsResponse, type ApiRedemptionEvaluateRequest, type ApiRedemptionEvaluateResponse, type ApiRedemptionPreviewRequest, type ApiRedemptionPreviewResponse, type ApiUserRequest, type ApiUserResponse, type AuthContext, AuthError, type AuthErrorCode, AuthService, type AuthServiceConfig, type BundlerEstimatorClient, BundlerNotConfiguredError, BundlerRejectedError, type BurnEvent, BurnIndexer, type BurnIndexerConfig, type BurnStatusParams, type BurnStatusResponse, type ClaimDto, type ConfigDto, ConfigurationError, DEFAULT_REDEMPTION_POLICY, type DecodedCallDto, DefaultPolicyEngine, type DefaultPolicyEngineOptions, type DelegatePrepareDto, type DelegateStatusDto, type EstimateGasFeeOptions, type EvaluateInput, FeeManager, type FeeManagerConfig, type FeeManagerMetrics, type FetchFailureReason, type FetchResult, type GasFeeDto, type GasFeeSource, GasUnitsCache, type GasUnitsCacheConfig, type HandleDelegateSubmitParams, type HandleDelegateSubmitResult, type HandleMobilePrepareParams, type HandleMobilePrepareResult, type HandleMobileSubmitParams, type IIndexerCursorStore, type IPendingUserOpStore, type IPointLedger, type IPolicyEngine, type IRateLimiter, type IRedemptionHistoryStore, type ISessionStore, InMemoryCursorStore, IssuerApiAdapter, type IssuerApiAdapterConfig, IssuerApiHandlers, type IssuerApiHandlersConfig, type IssuerRegistryRecord, type IssuerService, type IssuerServiceConfig, IssuerStateError, IssuerStateValidator, LockNotFoundError, type LockedMintRequest, type LoginResult, MemoryPendingUserOpStore, MemoryRateLimiter, MemoryRedemptionHistoryStore, MemorySessionStore, type MemorySessionStoreOptions, type MintEvent, type MintStatusParams, type MintStatusResponse, type MintingStatus, type MobilePrepareDto, type MobileSubmitDto, type NativePtQuoterConfig, NonceManager, NoopRateLimiter, PAFI_ISSUER_SDK_VERSION, PTClaimError, PTClaimHandler, type PTClaimHandlerConfig, type PTClaimRequest, type PTClaimResponse, PTRedeemError, PTRedeemHandler, type PTRedeemHandlerConfig, type PTRedeemRequest, type PTRedeemResponse, PafiBackendClient, type PafiBackendConfig, PafiBackendError, type PafiBackendErrorCode, type PaymasterGasEstimates, type PendingCredit, type PendingUserOpEntry, PendingUserOpForbiddenError, PendingUserOpNotFoundError, type PerpDepositDto, PerpDepositError, PerpDepositHandler, type PerpDepositHandlerConfig, type PerpDepositRequest, type PerpDepositResponse, PointIndexer, type PointIndexerConfig, type PolicyDecision, type PolicyEvalRequest, PolicyProvider, type PolicyProviderConfig, type PoolsDto, type PoolsProvider, type PreValidateMintResult, type PrepareBurnParams, type PrepareMintParams, type PrepareMobileUserOpParams, type PrepareMobileUserOpResult, type PreparedUserOp, type PreviewBurnParams, type PreviewMintParams, REDEMPTION_HISTORY_WINDOW_SEC, type RateLimitAction, type RateLimiterConfig, type RedeemDto, type RedeemPrepareDto, RedemptionService, type RedemptionServiceConfig, RelayError, type RelayErrorCode, RelayService, type RelayUserOpParams, type RelayUserOpRequest, type RelayUserOpResponse, type RequestPaymasterParams, type ResolvedPolicy, type RetryConfig, type SdkErrorBody, type SdkErrorMapperFactories, type SdkErrorStatus, type SerializedUserOpTypedData, type Session, SettlementClient, type SettlementClientConfig, type SponsorshipRequest, type SponsorshipResponse, type SponsorshipTarget, type SponsorshipUserOp, type SubgraphNativeUsdtQuoterConfig, type SubgraphPoolsProviderConfig, type UserDto, type UserHistory, applyPaymasterGasEstimates, authenticateRequest, buildSdkErrorBody, createIssuerService, createNativePtQuoter, createSdkErrorMapper, createSubgraphNativeUsdtQuoter, createSubgraphPoolsProvider, defaultPolicyFor, evaluateRedemption, handleClaimStatus, handleDelegateSubmit, handleMobilePrepare, handleMobileSubmit, handleRedeemStatus, mergePaymasterFields, prepareMobileUserOp, relayUserOp, requestPaymaster, serializeEntryToJsonRpc, serializeUserOpTypedData };

package/dist/index.d.ts

@@ -621,6 +621,14 @@ declare class RelayService {
      * issuer-signed `BurnRequest` path.
      */
     prepareBurn(params: PrepareBurnParams): Promise<PartialUserOperation>;
+    /**
+     * Build a dummy `PartialUserOperation` for the mint scenario, suitable
+     * for `feeManager.estimateGasFee({ partialUserOp, ... })`. NO signing —
+     * uses a 65-byte zero signature in place of the real minter sig.
+     */
+    previewMintUserOp(params: PreviewMintParams): PartialUserOperation;
+    /** Burn-side mirror of `previewMintUserOp`. */
+    previewBurnUserOp(params: PreviewBurnParams): PartialUserOperation;
 }
 /**
  * Sig-gated `PointToken.mint(to, amount, deadline, minterSig)`.
@@ -707,19 +715,131 @@ interface PrepareBurnParams {
     verificationGasLimit?: bigint;
     preVerificationGas?: bigint;
 }
+/**
+ * Inputs for `previewMintUserOp` — strict subset of `PrepareMintParams`
+ * that excludes the signing wallet, EIP-712 domain, and on-chain nonce.
+ * These don't affect calldata shape so the bundler estimate doesn't
+ * need them.
+ */
+interface PreviewMintParams {
+    userAddress: Address;
+    aaNonce: bigint;
+    pointTokenAddress: Address;
+    amount: bigint;
+    deadline: bigint;
+    mintFeeWrapperAddress?: Address;
+}
+interface PreviewBurnParams {
+    userAddress: Address;
+    aaNonce: bigint;
+    pointTokenAddress: Address;
+    amount: bigint;
+    deadline: bigint;
+}
+
+/**
+ * In-memory cache for bundler-estimated gas units, keyed by
+ * `(scenario, contractCodehash, paymaster)`.
+ *
+ * Why these key components:
+ *  - `scenario`           — distinguishes mint vs burn vs swap; their UserOps
+ *                           differ in calldata shape so estimates differ.
+ *  - `contractCodehash`   — fetched from the SC address via `eth_getCode`,
+ *                           cached separately for 1h. When the SC is upgraded
+ *                           the codehash changes → the gas key auto-invalidates
+ *                           (no manual purge needed).
+ *  - `paymaster`          — paymaster contract version affects postOp gas;
+ *                           rotating paymaster naturally invalidates.
+ *
+ * Bound: max `maxEntries` to defend against unbounded growth on
+ * long-running issuer backends; eldest evicted first (LRU-by-insertion).
+ */
+interface GasUnitsCacheConfig {
+    /** Gas-units cache TTL in ms. Default 5 minutes. */
+    ttlMs?: number;
+    /** Codehash cache TTL in ms. Default 1 hour. */
+    codehashTtlMs?: number;
+    /** Max entries before LRU eviction. Default 100. */
+    maxEntries?: number;
+}
+declare class GasUnitsCache {
+    private readonly entries;
+    private readonly codehashEntries;
+    private readonly ttlMs;
+    private readonly codehashTtlMs;
+    private readonly maxEntries;
+    constructor(config?: GasUnitsCacheConfig);
+    buildKey(params: {
+        scenario: string;
+        contractAddress: Address;
+        paymasterAddress?: Address;
+        provider: PublicClient;
+    }): Promise<string>;
+    get(key: string, now?: number): bigint | null;
+    set(key: string, gasUnits: bigint, now?: number): void;
+    invalidate(): void;
+    size(): number;
+    private getCodehash;
+}
 
+/**
+ * Minimal duck-typed shape of an ERC-4337 bundler client supporting
+ * `eth_estimateUserOperationGas`. Compatible with `permissionless`'s
+ * `createBundlerClient` and any spec-compliant bundler (Pimlico, Alchemy,
+ * StackUp, Biconomy). The SDK does NOT add `permissionless` as a hard
+ * dependency — callers pass whatever client they already use.
+ */
+interface BundlerEstimatorClient {
+    estimateUserOperationGas(args: {
+        sender: Address;
+        nonce: bigint;
+        callData: Hex;
+        signature?: Hex;
+        paymaster?: Address;
+        paymasterData?: Hex;
+    }): Promise<{
+        callGasLimit: bigint;
+        verificationGasLimit: bigint;
+        preVerificationGas: bigint;
+        paymasterVerificationGasLimit?: bigint;
+        paymasterPostOpGasLimit?: bigint;
+    }>;
+}
+type GasFeeSource = "cache" | "bundler" | "fallback";
+/**
+ * Hooks called by `FeeManager` so callers can wire their own
+ * observability (Pino logger, Prometheus counters, ...). All hooks are
+ * synchronous and best-effort — they MUST NOT throw.
+ */
+interface FeeManagerMetrics {
+    onEstimate?: (info: {
+        source: GasFeeSource;
+        scenario?: string;
+        gasUnits: bigint;
+        latencyMs: number;
+    }) => void;
+    onBundlerError?: (info: {
+        scenario?: string;
+        reason: string;
+    }) => void;
+}
 interface FeeManagerConfig {
-    /** Provider used for gas price reads. */
+    /** Provider used for gas price reads + codehash lookup. */
     provider: PublicClient;
     /**
-     * Typical gas used by a single sponsored UserOp. Default: 500_000.
-     * The manager multiplies this by current gas price to get native
-     * cost, then converts via the injected `quoteNativeToFee`.
+     * Hardcoded fallback gas units, used when (a) `bundlerClient` is not
+     * configured OR (b) the bundler call fails. Default: 500_000.
      */
     gasUnits?: bigint;
     /**
-     * Safety margin applied before charging the user, as basis points.
-     * 12_000 = 120%. Default: 12_000.
+     * Safety margin applied on top of the bundler/fallback estimate, in
+     * basis points. 10_000 = 100% (no extra). Default: 10_000.
+     *
+     * Pimlico's `eth_estimateUserOperationGas` already adds ~10-15% safety
+     * margin internally, so a second SDK-side premium just pads padding
+     * and over-charges users. We dropped the historical 12_000 (120%)
+     * default after measuring `actualGasUsed / estimate ≈ 0.92` across
+     * 100 dev mints.
      */
     gasPremiumBps?: number;
     /**
@@ -732,6 +852,60 @@ interface FeeManagerConfig {
      * or an oracle feed.
      */
     quoteNativeToFee: (amountNative: bigint) => Promise<bigint>;
+    /**
+     * Optional ERC-4337 bundler client. When set, `estimateGasFee({
+     * partialUserOp, ... })` will call `eth_estimateUserOperationGas`
+     * (cached) for per-UserOp accuracy. Omit to keep the legacy hardcoded
+     * path.
+     */
+    bundlerClient?: BundlerEstimatorClient;
+    /** Gas-units cache config — see `GasUnitsCache`. */
+    cache?: GasUnitsCacheConfig;
+    /**
+     * Fixed overhead added to bundler estimates to account for paymaster
+     * verification + postOp gas, since we estimate WITHOUT paymaster
+     * context (chicken-and-egg: paymaster data depends on gas limits).
+     * Default: 80_000 — covers Pimlico singleton paymaster v0.7 postOp.
+     */
+    paymasterOverheadGas?: bigint;
+    /** Optional observability hooks. */
+    metrics?: FeeManagerMetrics;
+}
+/**
+ * Parameters for a single bundler-driven `estimateGasFee` call.
+ *
+ * All fields optional for backwards compat: when `partialUserOp` is
+ * omitted, FeeManager falls back to the legacy `gasUnits × gasPrice`
+ * path.
+ */
+interface EstimateGasFeeOptions {
+    /**
+     * Partial UserOperation to simulate. The bundler runs the calldata in
+     * a virtual EVM and returns gas limits. Pass `signature` as a 65-byte
+     * dummy when the user hasn't signed yet.
+     *
+     * Estimate WITHOUT paymaster fields (paymaster/paymasterData omitted)
+     * to avoid the chicken-and-egg with paymasterData generation —
+     * `paymasterOverheadGas` is added afterwards.
+     */
+    partialUserOp?: {
+        sender: Address;
+        nonce: bigint;
+        callData: Hex;
+        signature?: Hex;
+    };
+    /**
+     * Contract address being called — used for cache key (codehash
+     * lookup). Typically the PointToken address for mint/burn.
+     */
+    contractAddress?: Address;
+    /** Scenario label used in the cache key (e.g. 'mint', 'burn'). */
+    scenario?: string;
+    /**
+     * Paymaster address used in the cache key. When omitted, '0x0' is
+     * used — fine if a single paymaster is used across the deployment.
+     */
+    paymasterAddress?: Address;
 }
 /**
  * Computes how much fee to collect from the user to cover the gas cost
@@ -740,34 +914,55 @@ interface FeeManagerConfig {
  * The fee is expressed in the **fee currency** chosen by the caller
  * (PT for mint/burn, USDT for swap/perp_deposit) — not hardcoded.
  *
+ * Two paths:
+ *  1. Legacy (no `bundlerClient`):  gasUnits × gasPrice × premium
+ *  2. Bundler (recommended):         bundler.estimateUserOperationGas →
+ *                                    sum gas limits → × gasPrice × premium
+ *
+ * The bundler path caches by `(scenario, contractCodehash, paymaster)`
+ * for ~99% hit rate after warm-up; cache invalidates automatically on
+ * SC upgrade via codehash change.
+ *
  * **No operator rebalancing.** The operator does not hold ETH directly;
- * gas is paid by PAFI sponsor-relayer via the paymaster-proxy (see
- * [SPONSORED_PATH_FLOW.md]). The fee collected here is an
- * application-level ERC-20 transfer inside the same UserOp batch, not a
- * reimbursement to a wallet that needs topping up.
+ * gas is paid by PAFI sponsor-relayer via the paymaster-proxy. The fee
+ * collected here is an application-level ERC-20 transfer inside the same
+ * UserOp batch, not a reimbursement to a wallet that needs topping up.
  */
 declare class FeeManager {
     private readonly provider;
     private readonly gasUnits;
     private readonly gasPremiumBps;
     private readonly quoteNativeToFee;
+    private readonly bundlerClient;
+    private readonly cache;
+    private readonly paymasterOverheadGas;
+    private readonly metrics;
     private cachedFee;
     private cacheExpiresAt;
-    private static readonly CACHE_TTL_MS;
+    private static readonly FEE_CACHE_TTL_MS;
     constructor(config: FeeManagerConfig);
     /**
      * Estimate the fee (in the caller's fee currency) to charge for the
-     * next sponsored UserOp:
+     * next sponsored UserOp.
      *
+     *   gasUnits      = bundler-estimated (cached) or hardcoded fallback
      *   nativeCost    = gasUnits × gasPrice
      *   withPremium   = nativeCost × premiumBps / 10_000
      *   fee           = quoteNativeToFee(withPremium)
      *
-     * For backward compatibility with v0.2.x code that reads `gasFeeUsdt`
-     * from the response, the name `estimateGasFee` is kept — but the
-     * currency depends on how the caller wired `quoteNativeToFee`.
+     * When `opts.partialUserOp` is omitted, behaves exactly like v0.16.x:
+     * uses the hardcoded `gasUnits` default.
+     */
+    estimateGasFee(opts?: EstimateGasFeeOptions): Promise<bigint>;
+    /**
+     * Manually purge the per-scenario gas-units cache. Useful after an SC
+     * upgrade when ops wants the next estimate to refresh immediately
+     * (the codehash check would catch it on the NEXT call anyway, but
+     * this forces it now).
      */
-    estimateGasFee(): Promise<bigint>;
+    invalidateCache(): void;
+    private resolveGasUnits;
+    private safeEmit;
 }
 
 /** Decoded Transfer(from=0x0 → to) event used to finalize a mint. */
@@ -3487,4 +3682,4 @@ declare class MemoryRedemptionHistoryStore implements IRedemptionHistoryStore {
 
 declare const PAFI_ISSUER_SDK_VERSION: string;
 
-export { AdapterMisconfiguredError, type ApiConfigResponse, type ApiGasFeeResponse, type ApiLoginRequest, type ApiLoginResponse, type ApiNonceResponse, type ApiPoolsRequest, type ApiPoolsResponse, type ApiRedemptionEvaluateRequest, type ApiRedemptionEvaluateResponse, type ApiRedemptionPreviewRequest, type ApiRedemptionPreviewResponse, type ApiUserRequest, type ApiUserResponse, type AuthContext, AuthError, type AuthErrorCode, AuthService, type AuthServiceConfig, BundlerNotConfiguredError, BundlerRejectedError, type BurnEvent, BurnIndexer, type BurnIndexerConfig, type BurnStatusParams, type BurnStatusResponse, type ClaimDto, type ConfigDto, ConfigurationError, DEFAULT_REDEMPTION_POLICY, type DecodedCallDto, DefaultPolicyEngine, type DefaultPolicyEngineOptions, type DelegatePrepareDto, type DelegateStatusDto, type EvaluateInput, FeeManager, type FeeManagerConfig, type FetchFailureReason, type FetchResult, type GasFeeDto, type HandleDelegateSubmitParams, type HandleDelegateSubmitResult, type HandleMobilePrepareParams, type HandleMobilePrepareResult, type HandleMobileSubmitParams, type IIndexerCursorStore, type IPendingUserOpStore, type IPointLedger, type IPolicyEngine, type IRateLimiter, type IRedemptionHistoryStore, type ISessionStore, InMemoryCursorStore, IssuerApiAdapter, type IssuerApiAdapterConfig, IssuerApiHandlers, type IssuerApiHandlersConfig, type IssuerRegistryRecord, type IssuerService, type IssuerServiceConfig, IssuerStateError, IssuerStateValidator, LockNotFoundError, type LockedMintRequest, type LoginResult, MemoryPendingUserOpStore, MemoryRateLimiter, MemoryRedemptionHistoryStore, MemorySessionStore, type MemorySessionStoreOptions, type MintEvent, type MintStatusParams, type MintStatusResponse, type MintingStatus, type MobilePrepareDto, type MobileSubmitDto, type NativePtQuoterConfig, NonceManager, NoopRateLimiter, PAFI_ISSUER_SDK_VERSION, PTClaimError, PTClaimHandler, type PTClaimHandlerConfig, type PTClaimRequest, type PTClaimResponse, PTRedeemError, PTRedeemHandler, type PTRedeemHandlerConfig, type PTRedeemRequest, type PTRedeemResponse, PafiBackendClient, type PafiBackendConfig, PafiBackendError, type PafiBackendErrorCode, type PaymasterGasEstimates, type PendingCredit, type PendingUserOpEntry, PendingUserOpForbiddenError, PendingUserOpNotFoundError, type PerpDepositDto, PerpDepositError, PerpDepositHandler, type PerpDepositHandlerConfig, type PerpDepositRequest, type PerpDepositResponse, PointIndexer, type PointIndexerConfig, type PolicyDecision, type PolicyEvalRequest, PolicyProvider, type PolicyProviderConfig, type PoolsDto, type PoolsProvider, type PreValidateMintResult, type PrepareBurnParams, type PrepareMintParams, type PrepareMobileUserOpParams, type PrepareMobileUserOpResult, type PreparedUserOp, REDEMPTION_HISTORY_WINDOW_SEC, type RateLimitAction, type RateLimiterConfig, type RedeemDto, type RedeemPrepareDto, RedemptionService, type RedemptionServiceConfig, RelayError, type RelayErrorCode, RelayService, type RelayUserOpParams, type RelayUserOpRequest, type RelayUserOpResponse, type RequestPaymasterParams, type ResolvedPolicy, type RetryConfig, type SdkErrorBody, type SdkErrorMapperFactories, type SdkErrorStatus, type SerializedUserOpTypedData, type Session, SettlementClient, type SettlementClientConfig, type SponsorshipRequest, type SponsorshipResponse, type SponsorshipTarget, type SponsorshipUserOp, type SubgraphNativeUsdtQuoterConfig, type SubgraphPoolsProviderConfig, type UserDto, type UserHistory, applyPaymasterGasEstimates, authenticateRequest, buildSdkErrorBody, createIssuerService, createNativePtQuoter, createSdkErrorMapper, createSubgraphNativeUsdtQuoter, createSubgraphPoolsProvider, defaultPolicyFor, evaluateRedemption, handleClaimStatus, handleDelegateSubmit, handleMobilePrepare, handleMobileSubmit, handleRedeemStatus, mergePaymasterFields, prepareMobileUserOp, relayUserOp, requestPaymaster, serializeEntryToJsonRpc, serializeUserOpTypedData };
+export { AdapterMisconfiguredError, type ApiConfigResponse, type ApiGasFeeResponse, type ApiLoginRequest, type ApiLoginResponse, type ApiNonceResponse, type ApiPoolsRequest, type ApiPoolsResponse, type ApiRedemptionEvaluateRequest, type ApiRedemptionEvaluateResponse, type ApiRedemptionPreviewRequest, type ApiRedemptionPreviewResponse, type ApiUserRequest, type ApiUserResponse, type AuthContext, AuthError, type AuthErrorCode, AuthService, type AuthServiceConfig, type BundlerEstimatorClient, BundlerNotConfiguredError, BundlerRejectedError, type BurnEvent, BurnIndexer, type BurnIndexerConfig, type BurnStatusParams, type BurnStatusResponse, type ClaimDto, type ConfigDto, ConfigurationError, DEFAULT_REDEMPTION_POLICY, type DecodedCallDto, DefaultPolicyEngine, type DefaultPolicyEngineOptions, type DelegatePrepareDto, type DelegateStatusDto, type EstimateGasFeeOptions, type EvaluateInput, FeeManager, type FeeManagerConfig, type FeeManagerMetrics, type FetchFailureReason, type FetchResult, type GasFeeDto, type GasFeeSource, GasUnitsCache, type GasUnitsCacheConfig, type HandleDelegateSubmitParams, type HandleDelegateSubmitResult, type HandleMobilePrepareParams, type HandleMobilePrepareResult, type HandleMobileSubmitParams, type IIndexerCursorStore, type IPendingUserOpStore, type IPointLedger, type IPolicyEngine, type IRateLimiter, type IRedemptionHistoryStore, type ISessionStore, InMemoryCursorStore, IssuerApiAdapter, type IssuerApiAdapterConfig, IssuerApiHandlers, type IssuerApiHandlersConfig, type IssuerRegistryRecord, type IssuerService, type IssuerServiceConfig, IssuerStateError, IssuerStateValidator, LockNotFoundError, type LockedMintRequest, type LoginResult, MemoryPendingUserOpStore, MemoryRateLimiter, MemoryRedemptionHistoryStore, MemorySessionStore, type MemorySessionStoreOptions, type MintEvent, type MintStatusParams, type MintStatusResponse, type MintingStatus, type MobilePrepareDto, type MobileSubmitDto, type NativePtQuoterConfig, NonceManager, NoopRateLimiter, PAFI_ISSUER_SDK_VERSION, PTClaimError, PTClaimHandler, type PTClaimHandlerConfig, type PTClaimRequest, type PTClaimResponse, PTRedeemError, PTRedeemHandler, type PTRedeemHandlerConfig, type PTRedeemRequest, type PTRedeemResponse, PafiBackendClient, type PafiBackendConfig, PafiBackendError, type PafiBackendErrorCode, type PaymasterGasEstimates, type PendingCredit, type PendingUserOpEntry, PendingUserOpForbiddenError, PendingUserOpNotFoundError, type PerpDepositDto, PerpDepositError, PerpDepositHandler, type PerpDepositHandlerConfig, type PerpDepositRequest, type PerpDepositResponse, PointIndexer, type PointIndexerConfig, type PolicyDecision, type PolicyEvalRequest, PolicyProvider, type PolicyProviderConfig, type PoolsDto, type PoolsProvider, type PreValidateMintResult, type PrepareBurnParams, type PrepareMintParams, type PrepareMobileUserOpParams, type PrepareMobileUserOpResult, type PreparedUserOp, type PreviewBurnParams, type PreviewMintParams, REDEMPTION_HISTORY_WINDOW_SEC, type RateLimitAction, type RateLimiterConfig, type RedeemDto, type RedeemPrepareDto, RedemptionService, type RedemptionServiceConfig, RelayError, type RelayErrorCode, RelayService, type RelayUserOpParams, type RelayUserOpRequest, type RelayUserOpResponse, type RequestPaymasterParams, type ResolvedPolicy, type RetryConfig, type SdkErrorBody, type SdkErrorMapperFactories, type SdkErrorStatus, type SerializedUserOpTypedData, type Session, SettlementClient, type SettlementClientConfig, type SponsorshipRequest, type SponsorshipResponse, type SponsorshipTarget, type SponsorshipUserOp, type SubgraphNativeUsdtQuoterConfig, type SubgraphPoolsProviderConfig, type UserDto, type UserHistory, applyPaymasterGasEstimates, authenticateRequest, buildSdkErrorBody, createIssuerService, createNativePtQuoter, createSdkErrorMapper, createSubgraphNativeUsdtQuoter, createSubgraphPoolsProvider, defaultPolicyFor, evaluateRedemption, handleClaimStatus, handleDelegateSubmit, handleMobilePrepare, handleMobileSubmit, handleRedeemStatus, mergePaymasterFields, prepareMobileUserOp, relayUserOp, requestPaymaster, serializeEntryToJsonRpc, serializeUserOpTypedData };