@pafi-dev/issuer 0.19.0 → 0.20.0

package/dist/index.d.cts

@@ -621,6 +621,35 @@ 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 placeholder.
+     */
+    previewMintUserOp(params: PreviewMintParams): PartialUserOperation;
+    /** Burn-side mirror of `previewMintUserOp`. */
+    previewBurnUserOp(params: PreviewBurnParams): PartialUserOperation;
+}
+/**
+ * Inputs for `previewMintUserOp` — strict subset of `PrepareMintParams`
+ * that excludes the signing wallet, EIP-712 domain, and on-chain
+ * `mintRequestNonces` lookup since those don't affect calldata shape
+ * (the bundler estimate is shape-invariant under their values).
+ */
+interface PreviewMintParams {
+    userAddress: Address;
+    aaNonce: bigint;
+    pointTokenAddress: Address;
+    amount: bigint;
+    deadline: bigint;
+    mintFeeWrapperAddress?: Address;
+}
+interface PreviewBurnParams {
+    userAddress: Address;
+    aaNonce: bigint;
+    pointTokenAddress: Address;
+    amount: bigint;
+    deadline: bigint;
 }
 /**
  * Sig-gated `PointToken.mint(to, amount, deadline, minterSig)`.
@@ -708,66 +737,206 @@ interface PrepareBurnParams {
     preVerificationGas?: bigint;
 }
 
+/**
+ * Caller-supplied fetch implementation, matching the WHATWG Fetch API
+ * shape. Defaults to `globalThis.fetch` when omitted; tests and
+ * non-browser/node environments can plug in their own.
+ */
+type FetchImpl = (input: string, init?: RequestInit) => Promise<Response>;
+/**
+ * Duck-typed estimator interface. `FeeManager` accepts any object
+ * satisfying this surface so the SDK stays decoupled from where the
+ * bundler estimate physically lives (PAFI sponsor-relayer in production,
+ * a mock in tests, a local Pimlico proxy in dev).
+ *
+ * The estimator's job: given the preview UserOp shape, return the gas
+ * units to multiply by `gasPrice` and feed into the caller's fee
+ * quoter. Premium and PM overhead are the estimator's responsibility,
+ * NOT the SDK's — preventing double-padding.
+ */
+interface BundlerEstimatorClient {
+    /**
+     * Resolve gas units for a sponsored UserOp.
+     *
+     * @throws — implementations should throw on transport / auth /
+     *   protocol errors so `FeeManager` can degrade to its hardcoded
+     *   fallback. Network failures must NOT silently return a default,
+     *   since that would mask a misconfiguration as a successful estimate.
+     */
+    getGasUnits(input: {
+        scenario: string;
+        contractAddress: Address;
+        paymasterAddress?: Address;
+        partialUserOp: {
+            sender: Address;
+            nonce: bigint;
+            callData: Hex;
+            signature?: Hex;
+        };
+    }): Promise<{
+        gasUnits: bigint;
+        source: "cache" | "bundler" | "fallback";
+        expiresAt: number;
+    }>;
+}
+interface PafiEstimatorClientConfig {
+    /**
+     * Base URL of the PAFI sponsor-relayer (no trailing slash). The
+     * adapter appends `/v1/estimate-gas-fee` — issuer infrastructure
+     * never talks to Pimlico directly.
+     */
+    baseUrl: string;
+    /** Issuer's PAFI API key — the same one used for `/paymaster/sponsor`. */
+    apiKey: string;
+    /** Issuer ID used in `X-Issuer-Id` header. */
+    issuerId: string;
+    /** Custom fetch (e.g. `undici` in tests). Defaults to `globalThis.fetch`. */
+    fetchImpl?: FetchImpl;
+}
+declare class PafiEstimatorHttpError extends Error {
+    readonly status: number;
+    readonly body: unknown;
+    constructor(status: number, body: unknown, message?: string);
+}
+/**
+ * HTTP adapter that hits PAFI sponsor-relayer's `/v1/estimate-gas-fee`
+ * endpoint. The SDK never imports Pimlico-specific code or holds the
+ * Pimlico API key — the bundler call happens server-side at PAFI.
+ *
+ * Authentication mirrors `/paymaster/sponsor`:
+ *   - `Authorization: Bearer <apiKey>`
+ *   - `X-Issuer-Id: <issuerId>`
+ *
+ * Issuers wire this once at boot via `createPafiEstimatorClient({
+ * baseUrl, apiKey, issuerId })` and pass it to `FeeManager` as
+ * `bundlerClient`. The same `baseUrl`/`apiKey`/`issuerId` already
+ * authenticate other PAFI calls — no new secrets required.
+ */
+declare function createPafiEstimatorClient(config: PafiEstimatorClientConfig): BundlerEstimatorClient;
+
+type GasFeeSource = "estimator" | "fallback" | "cached-fee";
+/**
+ * Hooks for observability. Sync, best-effort — errors thrown by hooks
+ * are swallowed so they cannot break the user-facing fee flow.
+ */
+interface FeeManagerMetrics {
+    onEstimate?: (info: {
+        source: GasFeeSource;
+        scenario?: string;
+        gasUnits: bigint;
+        latencyMs: number;
+    }) => void;
+    onEstimatorError?: (info: {
+        scenario?: string;
+        reason: string;
+    }) => void;
+}
 interface FeeManagerConfig {
-    /** Provider used for gas price reads. */
+    /** Provider used for gas-price reads. */
     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) no `bundlerClient` is
+     * configured, OR (b) the bundler call fails and `partialUserOp` was
+     * not supplied. Default: 500_000n. Sized as a safe over-estimate vs
+     * the historically observed mint/burn cost so a fallback never
+     * under-charges the sponsor.
      */
     gasUnits?: bigint;
     /**
-     * Safety margin applied before charging the user, as basis points.
-     * 12_000 = 120%. Default: 12_000.
+     * SDK-side premium in basis points. Default: 10_000 (100% = no extra
+     * padding). Pimlico's bundler pads ~10-15% internally, and PAFI
+     * sponsor-relayer applies its own premium (110%) before returning
+     * gasUnits, so adding more here would compound the over-charge that
+     * the v0.20 refactor was designed to remove. Override only when the
+     * caller's `bundlerClient` returns raw bundler values without a
+     * premium applied.
      */
     gasPremiumBps?: number;
     /**
      * Quote function — given an amount of native wei, return the
-     * equivalent amount in the fee currency (typically PT raw units;
-     * USDT 6-decimal for swap / perp deposit flows).
-     *
-     * Injected so the manager stays chain- and token-agnostic. Issuers
-     * wire it to `@pafi-dev/core` Quoter helpers, a PAFI subgraph query,
-     * or an oracle feed.
+     * equivalent amount in the fee currency (PT raw units for mint/burn,
+     * USDT/USDC 6-decimal for swap / perp deposit). Chain- and
+     * token-agnostic by design; wire to `createNativePtQuoter` for PT or
+     * `quoteOperatorFeeUsdt` for stables.
      */
     quoteNativeToFee: (amountNative: bigint) => Promise<bigint>;
+    /**
+     * Optional bundler-driven gas-units estimator. When set,
+     * `estimateGasFee({ partialUserOp, scenario, contractAddress })` calls
+     * the estimator for per-UserOp accuracy. When unset, the legacy
+     * hardcoded path runs — backward-compatible with v0.16/0.19 callers.
+     */
+    bundlerClient?: BundlerEstimatorClient;
+    /** Optional observability hooks. Throws inside hooks are swallowed. */
+    metrics?: FeeManagerMetrics;
+}
+/**
+ * Parameters for a single bundler-driven `estimateGasFee` call. All
+ * fields optional for backwards compatibility — when `partialUserOp` is
+ * absent the SDK falls back to the hardcoded path.
+ */
+interface EstimateGasFeeOptions {
+    partialUserOp?: {
+        sender: Address;
+        nonce: bigint;
+        callData: Hex;
+        signature?: Hex;
+    };
+    scenario?: string;
+    contractAddress?: Address;
+    paymasterAddress?: Address;
 }
 /**
- * Computes how much fee to collect from the user to cover the gas cost
- * of a sponsored UserOp.
+ * Computes the operator fee the issuer charges users for sponsored gas.
+ *
+ * Fee currency is whatever the injected `quoteNativeToFee` returns —
+ * PT for mint/burn, USDT/USDC for swap & perp deposit.
+ *
+ * Two execution paths:
+ *
+ *   1. **Estimator path** (recommended) — caller wires `bundlerClient`
+ *      (typically `createPafiEstimatorClient`). Each call hits the PAFI
+ *      sponsor-relayer's `/v1/estimate-gas-fee` which caches by
+ *      `(scenario, contract codehash, paymaster)` and applies its own
+ *      premium. Result is the most accurate fee available and matches
+ *      what sponsor-relayer's verify path expects, eliminating
+ *      `INSUFFICIENT_FEE` rejects from formula drift.
  *
- * The fee is expressed in the **fee currency** chosen by the caller
- * (PT for mint/burn, USDT for swap/perp_deposit) — not hardcoded.
+ *   2. **Fallback path** — no bundler client OR estimator threw. Use
+ *      hardcoded `gasUnits × premium`. Same shape as v0.16/0.19 so
+ *      legacy integrations get identical behaviour.
  *
- * **No operator rebalancing.** The operator does not hold ETH 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.
+ * **No operator rebalancing**: the operator does NOT hold ETH; gas is
+ * paid by PAFI's Pimlico paymaster. The fee here is an
+ * application-level ERC-20 transfer in the same UserOp batch.
  */
 declare class FeeManager {
     private readonly provider;
-    private readonly gasUnits;
+    private readonly fallbackGasUnits;
     private readonly gasPremiumBps;
     private readonly quoteNativeToFee;
+    private readonly bundlerClient;
+    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:
+     * Estimate the operator fee for the next sponsored UserOp.
      *
-     *   nativeCost    = gasUnits × gasPrice
-     *   withPremium   = nativeCost × premiumBps / 10_000
-     *   fee           = quoteNativeToFee(withPremium)
+     * Without `opts` → legacy path: `gasUnits × gasPrice × premium →
+     * quoteNativeToFee`. Cached for 10 s to absorb bursts.
      *
-     * 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`.
+     * With `opts` AND `bundlerClient` → estimator path. Each call may
+     * hit a different bundler-cached result; the SDK does NOT add its
+     * own value cache because the estimator's cache TTL is the source
+     * of truth for "how long is this estimate good for".
      */
-    estimateGasFee(): Promise<bigint>;
+    estimateGasFee(opts?: EstimateGasFeeOptions): Promise<bigint>;
+    /** Manually purge the legacy 10s fee cache. */
+    invalidateCache(): void;
+    private resolveGasUnits;
+    private safeEmit;
 }
 
 /** Decoded Transfer(from=0x0 → to) event used to finalize a mint. */
@@ -3487,4 +3656,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 FetchImpl, type FetchResult, type GasFeeDto, type GasFeeSource, type HandleDelegateSubmitParams, type HandleDelegateSubmitResult, type HandleMobilePrepareParams, type HandleMobilePrepareResult, type HandleMobileSubmitParams, type IIndexerCursorStore, type IPendingUserOpStore, type IPointLedger, type IPolicyEngine, type IRateLimiter, type IRedemptionHistoryStore, type ISessionStore, InMemoryCursorStore, IssuerApiAdapter, type IssuerApiAdapterConfig, IssuerApiHandlers, type IssuerApiHandlersConfig, type IssuerRegistryRecord, type IssuerService, type IssuerServiceConfig, IssuerStateError, IssuerStateValidator, LockNotFoundError, type LockedMintRequest, type LoginResult, MemoryPendingUserOpStore, MemoryRateLimiter, MemoryRedemptionHistoryStore, MemorySessionStore, type MemorySessionStoreOptions, type MintEvent, type MintStatusParams, type MintStatusResponse, type MintingStatus, type MobilePrepareDto, type MobileSubmitDto, type NativePtQuoterConfig, NonceManager, NoopRateLimiter, PAFI_ISSUER_SDK_VERSION, PTClaimError, PTClaimHandler, type PTClaimHandlerConfig, type PTClaimRequest, type PTClaimResponse, PTRedeemError, PTRedeemHandler, type PTRedeemHandlerConfig, type PTRedeemRequest, type PTRedeemResponse, PafiBackendClient, type PafiBackendConfig, PafiBackendError, type PafiBackendErrorCode, type PafiEstimatorClientConfig, PafiEstimatorHttpError, type PaymasterGasEstimates, type PendingCredit, type PendingUserOpEntry, PendingUserOpForbiddenError, PendingUserOpNotFoundError, type PerpDepositDto, PerpDepositError, PerpDepositHandler, type PerpDepositHandlerConfig, type PerpDepositRequest, type PerpDepositResponse, PointIndexer, type PointIndexerConfig, 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, createPafiEstimatorClient, createSdkErrorMapper, createSubgraphNativeUsdtQuoter, createSubgraphPoolsProvider, defaultPolicyFor, evaluateRedemption, handleClaimStatus, handleDelegateSubmit, handleMobilePrepare, handleMobileSubmit, handleRedeemStatus, mergePaymasterFields, prepareMobileUserOp, relayUserOp, requestPaymaster, serializeEntryToJsonRpc, serializeUserOpTypedData };

package/dist/index.d.ts

@@ -621,6 +621,35 @@ 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 placeholder.
+     */
+    previewMintUserOp(params: PreviewMintParams): PartialUserOperation;
+    /** Burn-side mirror of `previewMintUserOp`. */
+    previewBurnUserOp(params: PreviewBurnParams): PartialUserOperation;
+}
+/**
+ * Inputs for `previewMintUserOp` — strict subset of `PrepareMintParams`
+ * that excludes the signing wallet, EIP-712 domain, and on-chain
+ * `mintRequestNonces` lookup since those don't affect calldata shape
+ * (the bundler estimate is shape-invariant under their values).
+ */
+interface PreviewMintParams {
+    userAddress: Address;
+    aaNonce: bigint;
+    pointTokenAddress: Address;
+    amount: bigint;
+    deadline: bigint;
+    mintFeeWrapperAddress?: Address;
+}
+interface PreviewBurnParams {
+    userAddress: Address;
+    aaNonce: bigint;
+    pointTokenAddress: Address;
+    amount: bigint;
+    deadline: bigint;
 }
 /**
  * Sig-gated `PointToken.mint(to, amount, deadline, minterSig)`.
@@ -708,66 +737,206 @@ interface PrepareBurnParams {
     preVerificationGas?: bigint;
 }
 
+/**
+ * Caller-supplied fetch implementation, matching the WHATWG Fetch API
+ * shape. Defaults to `globalThis.fetch` when omitted; tests and
+ * non-browser/node environments can plug in their own.
+ */
+type FetchImpl = (input: string, init?: RequestInit) => Promise<Response>;
+/**
+ * Duck-typed estimator interface. `FeeManager` accepts any object
+ * satisfying this surface so the SDK stays decoupled from where the
+ * bundler estimate physically lives (PAFI sponsor-relayer in production,
+ * a mock in tests, a local Pimlico proxy in dev).
+ *
+ * The estimator's job: given the preview UserOp shape, return the gas
+ * units to multiply by `gasPrice` and feed into the caller's fee
+ * quoter. Premium and PM overhead are the estimator's responsibility,
+ * NOT the SDK's — preventing double-padding.
+ */
+interface BundlerEstimatorClient {
+    /**
+     * Resolve gas units for a sponsored UserOp.
+     *
+     * @throws — implementations should throw on transport / auth /
+     *   protocol errors so `FeeManager` can degrade to its hardcoded
+     *   fallback. Network failures must NOT silently return a default,
+     *   since that would mask a misconfiguration as a successful estimate.
+     */
+    getGasUnits(input: {
+        scenario: string;
+        contractAddress: Address;
+        paymasterAddress?: Address;
+        partialUserOp: {
+            sender: Address;
+            nonce: bigint;
+            callData: Hex;
+            signature?: Hex;
+        };
+    }): Promise<{
+        gasUnits: bigint;
+        source: "cache" | "bundler" | "fallback";
+        expiresAt: number;
+    }>;
+}
+interface PafiEstimatorClientConfig {
+    /**
+     * Base URL of the PAFI sponsor-relayer (no trailing slash). The
+     * adapter appends `/v1/estimate-gas-fee` — issuer infrastructure
+     * never talks to Pimlico directly.
+     */
+    baseUrl: string;
+    /** Issuer's PAFI API key — the same one used for `/paymaster/sponsor`. */
+    apiKey: string;
+    /** Issuer ID used in `X-Issuer-Id` header. */
+    issuerId: string;
+    /** Custom fetch (e.g. `undici` in tests). Defaults to `globalThis.fetch`. */
+    fetchImpl?: FetchImpl;
+}
+declare class PafiEstimatorHttpError extends Error {
+    readonly status: number;
+    readonly body: unknown;
+    constructor(status: number, body: unknown, message?: string);
+}
+/**
+ * HTTP adapter that hits PAFI sponsor-relayer's `/v1/estimate-gas-fee`
+ * endpoint. The SDK never imports Pimlico-specific code or holds the
+ * Pimlico API key — the bundler call happens server-side at PAFI.
+ *
+ * Authentication mirrors `/paymaster/sponsor`:
+ *   - `Authorization: Bearer <apiKey>`
+ *   - `X-Issuer-Id: <issuerId>`
+ *
+ * Issuers wire this once at boot via `createPafiEstimatorClient({
+ * baseUrl, apiKey, issuerId })` and pass it to `FeeManager` as
+ * `bundlerClient`. The same `baseUrl`/`apiKey`/`issuerId` already
+ * authenticate other PAFI calls — no new secrets required.
+ */
+declare function createPafiEstimatorClient(config: PafiEstimatorClientConfig): BundlerEstimatorClient;
+
+type GasFeeSource = "estimator" | "fallback" | "cached-fee";
+/**
+ * Hooks for observability. Sync, best-effort — errors thrown by hooks
+ * are swallowed so they cannot break the user-facing fee flow.
+ */
+interface FeeManagerMetrics {
+    onEstimate?: (info: {
+        source: GasFeeSource;
+        scenario?: string;
+        gasUnits: bigint;
+        latencyMs: number;
+    }) => void;
+    onEstimatorError?: (info: {
+        scenario?: string;
+        reason: string;
+    }) => void;
+}
 interface FeeManagerConfig {
-    /** Provider used for gas price reads. */
+    /** Provider used for gas-price reads. */
     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) no `bundlerClient` is
+     * configured, OR (b) the bundler call fails and `partialUserOp` was
+     * not supplied. Default: 500_000n. Sized as a safe over-estimate vs
+     * the historically observed mint/burn cost so a fallback never
+     * under-charges the sponsor.
      */
     gasUnits?: bigint;
     /**
-     * Safety margin applied before charging the user, as basis points.
-     * 12_000 = 120%. Default: 12_000.
+     * SDK-side premium in basis points. Default: 10_000 (100% = no extra
+     * padding). Pimlico's bundler pads ~10-15% internally, and PAFI
+     * sponsor-relayer applies its own premium (110%) before returning
+     * gasUnits, so adding more here would compound the over-charge that
+     * the v0.20 refactor was designed to remove. Override only when the
+     * caller's `bundlerClient` returns raw bundler values without a
+     * premium applied.
      */
     gasPremiumBps?: number;
     /**
      * Quote function — given an amount of native wei, return the
-     * equivalent amount in the fee currency (typically PT raw units;
-     * USDT 6-decimal for swap / perp deposit flows).
-     *
-     * Injected so the manager stays chain- and token-agnostic. Issuers
-     * wire it to `@pafi-dev/core` Quoter helpers, a PAFI subgraph query,
-     * or an oracle feed.
+     * equivalent amount in the fee currency (PT raw units for mint/burn,
+     * USDT/USDC 6-decimal for swap / perp deposit). Chain- and
+     * token-agnostic by design; wire to `createNativePtQuoter` for PT or
+     * `quoteOperatorFeeUsdt` for stables.
      */
     quoteNativeToFee: (amountNative: bigint) => Promise<bigint>;
+    /**
+     * Optional bundler-driven gas-units estimator. When set,
+     * `estimateGasFee({ partialUserOp, scenario, contractAddress })` calls
+     * the estimator for per-UserOp accuracy. When unset, the legacy
+     * hardcoded path runs — backward-compatible with v0.16/0.19 callers.
+     */
+    bundlerClient?: BundlerEstimatorClient;
+    /** Optional observability hooks. Throws inside hooks are swallowed. */
+    metrics?: FeeManagerMetrics;
+}
+/**
+ * Parameters for a single bundler-driven `estimateGasFee` call. All
+ * fields optional for backwards compatibility — when `partialUserOp` is
+ * absent the SDK falls back to the hardcoded path.
+ */
+interface EstimateGasFeeOptions {
+    partialUserOp?: {
+        sender: Address;
+        nonce: bigint;
+        callData: Hex;
+        signature?: Hex;
+    };
+    scenario?: string;
+    contractAddress?: Address;
+    paymasterAddress?: Address;
 }
 /**
- * Computes how much fee to collect from the user to cover the gas cost
- * of a sponsored UserOp.
+ * Computes the operator fee the issuer charges users for sponsored gas.
+ *
+ * Fee currency is whatever the injected `quoteNativeToFee` returns —
+ * PT for mint/burn, USDT/USDC for swap & perp deposit.
+ *
+ * Two execution paths:
+ *
+ *   1. **Estimator path** (recommended) — caller wires `bundlerClient`
+ *      (typically `createPafiEstimatorClient`). Each call hits the PAFI
+ *      sponsor-relayer's `/v1/estimate-gas-fee` which caches by
+ *      `(scenario, contract codehash, paymaster)` and applies its own
+ *      premium. Result is the most accurate fee available and matches
+ *      what sponsor-relayer's verify path expects, eliminating
+ *      `INSUFFICIENT_FEE` rejects from formula drift.
  *
- * The fee is expressed in the **fee currency** chosen by the caller
- * (PT for mint/burn, USDT for swap/perp_deposit) — not hardcoded.
+ *   2. **Fallback path** — no bundler client OR estimator threw. Use
+ *      hardcoded `gasUnits × premium`. Same shape as v0.16/0.19 so
+ *      legacy integrations get identical behaviour.
  *
- * **No operator rebalancing.** The operator does not hold ETH 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.
+ * **No operator rebalancing**: the operator does NOT hold ETH; gas is
+ * paid by PAFI's Pimlico paymaster. The fee here is an
+ * application-level ERC-20 transfer in the same UserOp batch.
  */
 declare class FeeManager {
     private readonly provider;
-    private readonly gasUnits;
+    private readonly fallbackGasUnits;
     private readonly gasPremiumBps;
     private readonly quoteNativeToFee;
+    private readonly bundlerClient;
+    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:
+     * Estimate the operator fee for the next sponsored UserOp.
      *
-     *   nativeCost    = gasUnits × gasPrice
-     *   withPremium   = nativeCost × premiumBps / 10_000
-     *   fee           = quoteNativeToFee(withPremium)
+     * Without `opts` → legacy path: `gasUnits × gasPrice × premium →
+     * quoteNativeToFee`. Cached for 10 s to absorb bursts.
      *
-     * 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`.
+     * With `opts` AND `bundlerClient` → estimator path. Each call may
+     * hit a different bundler-cached result; the SDK does NOT add its
+     * own value cache because the estimator's cache TTL is the source
+     * of truth for "how long is this estimate good for".
      */
-    estimateGasFee(): Promise<bigint>;
+    estimateGasFee(opts?: EstimateGasFeeOptions): Promise<bigint>;
+    /** Manually purge the legacy 10s fee cache. */
+    invalidateCache(): void;
+    private resolveGasUnits;
+    private safeEmit;
 }
 
 /** Decoded Transfer(from=0x0 → to) event used to finalize a mint. */
@@ -3487,4 +3656,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 FetchImpl, type FetchResult, type GasFeeDto, type GasFeeSource, type HandleDelegateSubmitParams, type HandleDelegateSubmitResult, type HandleMobilePrepareParams, type HandleMobilePrepareResult, type HandleMobileSubmitParams, type IIndexerCursorStore, type IPendingUserOpStore, type IPointLedger, type IPolicyEngine, type IRateLimiter, type IRedemptionHistoryStore, type ISessionStore, InMemoryCursorStore, IssuerApiAdapter, type IssuerApiAdapterConfig, IssuerApiHandlers, type IssuerApiHandlersConfig, type IssuerRegistryRecord, type IssuerService, type IssuerServiceConfig, IssuerStateError, IssuerStateValidator, LockNotFoundError, type LockedMintRequest, type LoginResult, MemoryPendingUserOpStore, MemoryRateLimiter, MemoryRedemptionHistoryStore, MemorySessionStore, type MemorySessionStoreOptions, type MintEvent, type MintStatusParams, type MintStatusResponse, type MintingStatus, type MobilePrepareDto, type MobileSubmitDto, type NativePtQuoterConfig, NonceManager, NoopRateLimiter, PAFI_ISSUER_SDK_VERSION, PTClaimError, PTClaimHandler, type PTClaimHandlerConfig, type PTClaimRequest, type PTClaimResponse, PTRedeemError, PTRedeemHandler, type PTRedeemHandlerConfig, type PTRedeemRequest, type PTRedeemResponse, PafiBackendClient, type PafiBackendConfig, PafiBackendError, type PafiBackendErrorCode, type PafiEstimatorClientConfig, PafiEstimatorHttpError, type PaymasterGasEstimates, type PendingCredit, type PendingUserOpEntry, PendingUserOpForbiddenError, PendingUserOpNotFoundError, type PerpDepositDto, PerpDepositError, PerpDepositHandler, type PerpDepositHandlerConfig, type PerpDepositRequest, type PerpDepositResponse, PointIndexer, type PointIndexerConfig, 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, createPafiEstimatorClient, createSdkErrorMapper, createSubgraphNativeUsdtQuoter, createSubgraphPoolsProvider, defaultPolicyFor, evaluateRedemption, handleClaimStatus, handleDelegateSubmit, handleMobilePrepare, handleMobileSubmit, handleRedeemStatus, mergePaymasterFields, prepareMobileUserOp, relayUserOp, requestPaymaster, serializeEntryToJsonRpc, serializeUserOpTypedData };