@pafi-dev/core 0.7.1 → 0.7.2

package/dist/index.d.cts

@@ -1,11 +1,11 @@
 import { Address, Hex, TypedDataDomain, PublicClient, HttpTransport, WalletClient } from 'viem';
-import { P as PoolKey, C as ChainConfig, a as PafiSDKConfig, b as PointTokenDomainConfig, M as MintRequest, R as ReceiverConsent, E as EIP712Signature, S as SignatureVerification } from './types-JyuXUM8C.cjs';
-export { B as BestQuote, c as BurnRequest, I as Issuer, d as PathKey, Q as QuoteResult } from './types-JyuXUM8C.cjs';
+import { P as PoolKey, C as ChainConfig, a as PafiSDKConfig, b as PointTokenDomainConfig, M as MintRequest, R as ReceiverConsent, E as EIP712Signature, S as SignatureVerification } from './types-BAkmxgVo.cjs';
+export { B as BestQuote, c as BurnRequest, I as Issuer, d as PathKey, Q as QuoteResult } from './types-BAkmxgVo.cjs';
 export { pointTokenAbi as POINT_TOKEN_V2_ABI, erc20Abi, issuerRegistryAbi, mintingOracleAbi, permit2Abi, pointTokenAbi, pointTokenFactoryAbi, universalRouterAbi, v4QuoterAbi } from './abi/index.cjs';
 export { buildBurnRequestTypedData, buildDomain, buildMintRequestTypedData, buildReceiverConsentTypedData, signBurnRequest, signMintRequest, signReceiverConsent, verifyBurnRequest, verifyMintRequest, verifyReceiverConsent } from './eip712/index.cjs';
 export { getBurnRequestNonce, getIssuer, getMintRequestNonce, getPointTokenBalance, getPointTokenIssuer, getPointTokenIssuerAddress, getReceiverConsentNonce, getTokenName, isActiveIssuer, isMinter, issuerRegistryGetIssuerFlatAbi, verifyMintCap } from './contract/index.cjs';
 import { LoginMessageParams } from './auth/index.cjs';
-export { BuildSponsorAuthParams, BuiltSponsorAuth, SPONSOR_AUTH_DOMAIN_NAME, SPONSOR_AUTH_TYPES, SponsorAuthPayload, SponsorAuthVerifyResult, VerifyLoginResult, buildAndSignSponsorAuth, buildSponsorAuthDomain, buildSponsorAuthTypedData, computeCallDataHash, createLoginMessage, parseLoginMessage, signSponsorAuth, verifyLoginMessage, verifySponsorAuth } from './auth/index.cjs';
+export { BuildSponsorAuthParams, BuiltSponsorAuth, SPONSOR_AUTH_DOMAIN_NAME, SPONSOR_AUTH_TYPES, SponsorAuthPayload, SponsorAuthVerifyResult, VerifyLoginResult, buildAndSignSponsorAuth, buildSponsorAuthDomain, buildSponsorAuthTypedData, computeCallDataHash, createLoginMessage, generateSponsorAuthNonce, parseLoginMessage, signSponsorAuth, verifyLoginMessage, verifySponsorAuth } from './auth/index.cjs';
 
 declare const mintRequestTypes: {
     readonly MintRequest: readonly [{
@@ -82,6 +82,36 @@ declare const ENTRY_POINT_V08: Address;
 /** Permit2 — Uniswap's universal approval contract, same address on all EVM chains. */
 declare const PERMIT2_ADDRESS: Address;
 
+/**
+ * v0.7.1 — unified error base for the entire SDK (core + issuer +
+ * trading). Subclasses declare `code` (machine-readable) and
+ * `httpStatus` (recommended HTTP status for issuer's controller).
+ *
+ * Issuer's `createSdkErrorMapper` routes any `PafiSdkError` instance
+ * through framework-specific exception factories; non-PafiSdkError
+ * still becomes 500.
+ *
+ * See SDK_CORE_TRADING_AUDIT.md H3.
+ */
+type SdkErrorHttpStatus = "not_found" | "forbidden" | "unprocessable" | "service_unavailable";
+declare abstract class PafiSdkError extends Error {
+    abstract readonly code: string;
+    /**
+     * `true` when the FE should consider a retry safe — typically because
+     * the failure is transient.
+     */
+    readonly safeToRetry: boolean;
+    readonly details?: unknown;
+    abstract readonly httpStatus: SdkErrorHttpStatus;
+    constructor(message: string);
+}
+/**
+ * @deprecated v0.7.1 — use `PafiSdkError` (capital S, lowercase dk).
+ * The two classes existed in parallel ("PafiSDKError" in core,
+ * "PafiSdkError" in issuer) due to historical drift; consolidating
+ * here. Kept as alias for back-compat through v0.7.x; will be removed
+ * in v0.8. See SDK_CORE_TRADING_AUDIT.md H3.
+ */
 declare class PafiSDKError extends Error {
     constructor(message: string);
 }
@@ -106,16 +136,35 @@ declare class ApiError extends PafiSDKError {
  * caller did not opt in to the hardcoded fallback prices.
  *
  * v0.7.1 — previously `quoteOperatorFeePt` silently fell back to
- * ETH=$3000 / PT=$0.10 with `console.warn`. That caused mass
- * `INSUFFICIENT_FEE` rejects during Chainlink incidents, or worse,
- * accepted under-priced fees. Now opt-in via
+ * ETH=$3000 / PT=$0.10 with `console.warn`. Now opt-in via
  * `allowStaleFallback: true`. See SDK_CORE_TRADING_AUDIT.md C2.
+ *
+ * Extends the unified `PafiSdkError` so issuer's `createSdkErrorMapper`
+ * routes it to 503 instead of leaking as a 500.
  */
-declare class OracleStaleError extends PafiSDKError {
+declare class OracleStaleError extends PafiSdkError {
+    readonly httpStatus: "service_unavailable";
+    readonly code: "ORACLE_STALE";
     readonly source: "chainlink" | "subgraph";
     readonly reason: string;
     constructor(source: "chainlink" | "subgraph", reason: string);
 }
+/**
+ * Generic 4xx-class validation failure for input checks at any SDK
+ * boundary (core helpers, trading handlers, etc.). Issuer's
+ * `createSdkErrorMapper` routes to 422.
+ *
+ * Uses an instance `details` field so subclasses can override the
+ * declaration; matches the issuer-side shape that pre-existed here.
+ *
+ * v0.7.4 — added per SDK_CORE_TRADING_AUDIT.md H2/H13.
+ */
+declare class ValidationError extends PafiSdkError {
+    readonly httpStatus: "unprocessable";
+    readonly code: string;
+    readonly details?: Record<string, unknown>;
+    constructor(code: string, message: string, details?: Record<string, unknown>);
+}
 
 /**
  * Orderly Network Vault — entrypoint for **perp deposit** flow on
@@ -875,16 +924,15 @@ interface PaymasterConfig {
 type SponsorshipScenario = "mint" | "burn" | "swap" | "perp-deposit";
 
 /**
+ * @deprecated v0.7.1 — see file comment.
+ *
  * Set the application-wide paymaster config. Safe to call multiple
  * times (later calls override earlier). Throws if required fields
  * are missing.
  */
 declare function setPaymasterConfig(config: PaymasterConfig): void;
 /**
- * Get the current paymaster config. Throws if `setPaymasterConfig()`
- * has not been called yet — this surfaces boot-order bugs early
- * instead of failing with "paymaster.feeRecipient is undefined" at
- * the point of use.
+ * @deprecated v0.7.1 — see file comment.
  */
 declare function getPaymasterConfig(): PaymasterConfig;
 /** Test helper — clear the singleton. */
@@ -1249,15 +1297,35 @@ interface SendWithPaymasterFallbackParams {
  */
 declare function sendWithPaymasterFallback(params: SendWithPaymasterFallbackParams): Promise<Hex>;
 
+/**
+ * Per-scenario gas budgets (callGasLimit + verificationGas + preVerify)
+ * used by `quoteOperatorFee*`. Defaults are calibrated against the
+ * actual UserOps the issuer + trading SDKs build:
+ *
+ *   mint         — `RelayService.prepareMint` callGasLimit 300k → 500k margin
+ *   burn         — `RelayService.prepareBurn` 300k → 500k margin
+ *   swap         — `buildSwapUserOp` callGasLimit 700k (UR.execute heavy)
+ *   perp-deposit — `buildPerpDepositViaRelay` 800k (LayerZero msg)
+ *   delegate     — minimal no-op self-call, 200k margin
+ *
+ * Pass an explicit `gasUnits` to override. v0.7.4 — added per
+ * SDK_CORE_TRADING_AUDIT.md H12.
+ */
+type FeeScenario = "mint" | "burn" | "swap" | "perp-deposit" | "delegate";
 interface QuoteOperatorFeePtConfig {
     provider: PublicClient;
     chainId: number;
     pointTokenAddress: Address;
     /**
-     * ERC-4337 gas units the UserOp will consume on chain. Default
-     * 500_000n covers the common scenarios (mint, swap, perp deposit
-     * via Relay) with margin. Pass a tighter number when you have a
-     * Pimlico estimate to feed in.
+     * Scenario tag — picks default `gasUnits` from `SCENARIO_GAS_UNITS`.
+     * Ignored when `gasUnits` is explicit. Default `"mint"` for back-
+     * compat (matches the legacy 500_000 constant).
+     */
+    scenario?: FeeScenario;
+    /**
+     * ERC-4337 gas units the UserOp will consume on chain. Defaults to
+     * `SCENARIO_GAS_UNITS[scenario]`, falling back to 500_000n. Pass a
+     * tighter number when you have a Pimlico estimate to feed in.
      */
     gasUnits?: bigint;
     /**
@@ -1298,6 +1366,8 @@ interface QuoteOperatorFeePtConfig {
 interface QuoteOperatorFeeUsdtConfig {
     provider: PublicClient;
     chainId: number;
+    /** See `QuoteOperatorFeePtConfig.scenario`. v0.7.4. */
+    scenario?: FeeScenario;
     gasUnits?: bigint;
     premiumBps?: number;
     chainlinkFeedAddress?: Address;
@@ -1686,7 +1756,7 @@ declare class PafiSDK {
     buildMintRequestTypedData(message: MintRequest): Promise<{
         domain: {
             name: string;
-            version: "1";
+            version: string;
             chainId: number;
             verifyingContract: `0x${string}`;
         };
@@ -1711,7 +1781,7 @@ declare class PafiSDK {
     buildReceiverConsentTypedData(message: ReceiverConsent): Promise<{
         domain: {
             name: string;
-            version: "1";
+            version: string;
             chainId: number;
             verifyingContract: `0x${string}`;
         };
@@ -1750,4 +1820,4 @@ declare class PafiSDK {
     signLoginMessage(message: string): Promise<Hex>;
 }
 
-export { ApiError, BATCH_EXECUTOR_7702_IMPL, BATCH_EXECUTOR_ABI, BATCH_EXECUTOR_ADDRESS_BASE_MAINNET, BATCH_EXECUTOR_ADDRESS_BASE_SEPOLIA, BROKER_HASHES, type BuildDelegationUserOpParams, type BuildPartialUserOpParams, type BuildPerpDepositViaRelayParams, type BuildPerpDepositWithGasDeductionParams, COMMON_POOLS, COMMON_TOKENS, CONTRACT_ADDRESSES, ChainConfig, type CheckEthAndBranchParams, ConfigurationError, type ContractAddresses, DUMMY_SIGNATURE_V07, type DelegateImpl, EIP712Signature, ENTRY_POINT_V07, ENTRY_POINT_V08, type Eip7702AuthorizationJsonRpc, LoginMessageParams, MintRequest, type ModalOpenOptions, ORDERLY_RELAY_ABI, ORDERLY_VAULT_ABI, ORDERLY_VAULT_ADDRESSES, ORDERLY_VAULT_BASE_MAINNET, type Operation, OracleStaleError, type OrderlyRelayDepositRequest, PAFI_SUBGRAPH_URL, PERMIT2_ADDRESS, POINT_TOKEN_FACTORY_ADDRESSES, POINT_TOKEN_IMPL_ADDRESSES, POINT_TOKEN_POOLS, type PackedUserOperationMessage, type PafiProxyTransportParams, PafiSDK, PafiSDKConfig, PafiSDKError, type PafiWebModalAdapter, type PafiWebModalHandle, type PartialUserOperation, type PaymasterConfig, type PaymasterFields, PointTokenDomainConfig, PoolKey, type QuoteOperatorFeePtConfig, type QuoteOperatorFeeUsdtConfig, ReceiverConsent, SIMPLE_7702_IMPL_BASE_MAINNET, SUPPORTED_CHAINS, type SendWithPaymasterFallbackParams, type SignatureStruct, SignatureVerification, SigningError, SimulationError, type SmartAccountSender, type SponsorshipScenario, type SubmissionPath, TOKEN_HASHES, UNIVERSAL_ROUTER_ADDRESSES, type UserOpReceipt, type UserOpTypedData, type UserOperation, V4_QUOTER_ADDRESSES, type VaultDepositFE, ZERO_VALUE, _resetPaymasterConfigForTests, assembleUserOperation, buildDelegationUserOp, buildEip7702Authorization, buildPartialUserOperation, buildPerpDepositViaRelay, buildPerpDepositWithGasDeduction, buildUserOpTypedData, burnRequestTypes, checkDelegation, checkEthAndBranch, computeAccountId, computeAuthorizationHash, computeUserOpHash, createPafiProxyTransport, decodeBatchExecuteCalls, detectDelegateImpl, encodeBatchExecute, erc20ApproveOp, erc20BurnOp, erc20TransferOp, fetchPafiPools, getAaNonce, getContractAddresses, getDummySignatureFor7702, getPafiWebModalAdapter, getPaymasterConfig, isDelegatedTo, isDelegatedToTarget, isPaymasterConfigured, isPaymasterError, mintRequestTypes, openPafiWebModal, openWebPopup, parseEip7702DelegatedAddress, quoteOperatorFeePt, quoteOperatorFeeUsdt, rawCallOp, receiverConsentTypes, sendWithPaymasterFallback, serializeUserOpToJsonRpc, setPafiWebModalAdapter, setPaymasterConfig, splitAuthorizationSig, webPopupAdapter };
+export { ApiError, BATCH_EXECUTOR_7702_IMPL, BATCH_EXECUTOR_ABI, BATCH_EXECUTOR_ADDRESS_BASE_MAINNET, BATCH_EXECUTOR_ADDRESS_BASE_SEPOLIA, BROKER_HASHES, type BuildDelegationUserOpParams, type BuildPartialUserOpParams, type BuildPerpDepositViaRelayParams, type BuildPerpDepositWithGasDeductionParams, COMMON_POOLS, COMMON_TOKENS, CONTRACT_ADDRESSES, ChainConfig, type CheckEthAndBranchParams, ConfigurationError, type ContractAddresses, DUMMY_SIGNATURE_V07, type DelegateImpl, EIP712Signature, ENTRY_POINT_V07, ENTRY_POINT_V08, type Eip7702AuthorizationJsonRpc, LoginMessageParams, MintRequest, type ModalOpenOptions, ORDERLY_RELAY_ABI, ORDERLY_VAULT_ABI, ORDERLY_VAULT_ADDRESSES, ORDERLY_VAULT_BASE_MAINNET, type Operation, OracleStaleError, type OrderlyRelayDepositRequest, PAFI_SUBGRAPH_URL, PERMIT2_ADDRESS, POINT_TOKEN_FACTORY_ADDRESSES, POINT_TOKEN_IMPL_ADDRESSES, POINT_TOKEN_POOLS, type PackedUserOperationMessage, type PafiProxyTransportParams, PafiSDK, PafiSDKConfig, PafiSDKError, PafiSdkError, type PafiWebModalAdapter, type PafiWebModalHandle, type PartialUserOperation, type PaymasterConfig, type PaymasterFields, PointTokenDomainConfig, PoolKey, type QuoteOperatorFeePtConfig, type QuoteOperatorFeeUsdtConfig, ReceiverConsent, SIMPLE_7702_IMPL_BASE_MAINNET, SUPPORTED_CHAINS, type SdkErrorHttpStatus, type SendWithPaymasterFallbackParams, type SignatureStruct, SignatureVerification, SigningError, SimulationError, type SmartAccountSender, type SponsorshipScenario, type SubmissionPath, TOKEN_HASHES, UNIVERSAL_ROUTER_ADDRESSES, type UserOpReceipt, type UserOpTypedData, type UserOperation, V4_QUOTER_ADDRESSES, ValidationError, type VaultDepositFE, ZERO_VALUE, _resetPaymasterConfigForTests, assembleUserOperation, buildDelegationUserOp, buildEip7702Authorization, buildPartialUserOperation, buildPerpDepositViaRelay, buildPerpDepositWithGasDeduction, buildUserOpTypedData, burnRequestTypes, checkDelegation, checkEthAndBranch, computeAccountId, computeAuthorizationHash, computeUserOpHash, createPafiProxyTransport, decodeBatchExecuteCalls, detectDelegateImpl, encodeBatchExecute, erc20ApproveOp, erc20BurnOp, erc20TransferOp, fetchPafiPools, getAaNonce, getContractAddresses, getDummySignatureFor7702, getPafiWebModalAdapter, getPaymasterConfig, isDelegatedTo, isDelegatedToTarget, isPaymasterConfigured, isPaymasterError, mintRequestTypes, openPafiWebModal, openWebPopup, parseEip7702DelegatedAddress, quoteOperatorFeePt, quoteOperatorFeeUsdt, rawCallOp, receiverConsentTypes, sendWithPaymasterFallback, serializeUserOpToJsonRpc, setPafiWebModalAdapter, setPaymasterConfig, splitAuthorizationSig, webPopupAdapter };

package/dist/index.d.ts

@@ -1,11 +1,11 @@
 import { Address, Hex, TypedDataDomain, PublicClient, HttpTransport, WalletClient } from 'viem';
-import { P as PoolKey, C as ChainConfig, a as PafiSDKConfig, b as PointTokenDomainConfig, M as MintRequest, R as ReceiverConsent, E as EIP712Signature, S as SignatureVerification } from './types-JyuXUM8C.js';
-export { B as BestQuote, c as BurnRequest, I as Issuer, d as PathKey, Q as QuoteResult } from './types-JyuXUM8C.js';
+import { P as PoolKey, C as ChainConfig, a as PafiSDKConfig, b as PointTokenDomainConfig, M as MintRequest, R as ReceiverConsent, E as EIP712Signature, S as SignatureVerification } from './types-BAkmxgVo.js';
+export { B as BestQuote, c as BurnRequest, I as Issuer, d as PathKey, Q as QuoteResult } from './types-BAkmxgVo.js';
 export { pointTokenAbi as POINT_TOKEN_V2_ABI, erc20Abi, issuerRegistryAbi, mintingOracleAbi, permit2Abi, pointTokenAbi, pointTokenFactoryAbi, universalRouterAbi, v4QuoterAbi } from './abi/index.js';
 export { buildBurnRequestTypedData, buildDomain, buildMintRequestTypedData, buildReceiverConsentTypedData, signBurnRequest, signMintRequest, signReceiverConsent, verifyBurnRequest, verifyMintRequest, verifyReceiverConsent } from './eip712/index.js';
 export { getBurnRequestNonce, getIssuer, getMintRequestNonce, getPointTokenBalance, getPointTokenIssuer, getPointTokenIssuerAddress, getReceiverConsentNonce, getTokenName, isActiveIssuer, isMinter, issuerRegistryGetIssuerFlatAbi, verifyMintCap } from './contract/index.js';
 import { LoginMessageParams } from './auth/index.js';
-export { BuildSponsorAuthParams, BuiltSponsorAuth, SPONSOR_AUTH_DOMAIN_NAME, SPONSOR_AUTH_TYPES, SponsorAuthPayload, SponsorAuthVerifyResult, VerifyLoginResult, buildAndSignSponsorAuth, buildSponsorAuthDomain, buildSponsorAuthTypedData, computeCallDataHash, createLoginMessage, parseLoginMessage, signSponsorAuth, verifyLoginMessage, verifySponsorAuth } from './auth/index.js';
+export { BuildSponsorAuthParams, BuiltSponsorAuth, SPONSOR_AUTH_DOMAIN_NAME, SPONSOR_AUTH_TYPES, SponsorAuthPayload, SponsorAuthVerifyResult, VerifyLoginResult, buildAndSignSponsorAuth, buildSponsorAuthDomain, buildSponsorAuthTypedData, computeCallDataHash, createLoginMessage, generateSponsorAuthNonce, parseLoginMessage, signSponsorAuth, verifyLoginMessage, verifySponsorAuth } from './auth/index.js';
 
 declare const mintRequestTypes: {
     readonly MintRequest: readonly [{
@@ -82,6 +82,36 @@ declare const ENTRY_POINT_V08: Address;
 /** Permit2 — Uniswap's universal approval contract, same address on all EVM chains. */
 declare const PERMIT2_ADDRESS: Address;
 
+/**
+ * v0.7.1 — unified error base for the entire SDK (core + issuer +
+ * trading). Subclasses declare `code` (machine-readable) and
+ * `httpStatus` (recommended HTTP status for issuer's controller).
+ *
+ * Issuer's `createSdkErrorMapper` routes any `PafiSdkError` instance
+ * through framework-specific exception factories; non-PafiSdkError
+ * still becomes 500.
+ *
+ * See SDK_CORE_TRADING_AUDIT.md H3.
+ */
+type SdkErrorHttpStatus = "not_found" | "forbidden" | "unprocessable" | "service_unavailable";
+declare abstract class PafiSdkError extends Error {
+    abstract readonly code: string;
+    /**
+     * `true` when the FE should consider a retry safe — typically because
+     * the failure is transient.
+     */
+    readonly safeToRetry: boolean;
+    readonly details?: unknown;
+    abstract readonly httpStatus: SdkErrorHttpStatus;
+    constructor(message: string);
+}
+/**
+ * @deprecated v0.7.1 — use `PafiSdkError` (capital S, lowercase dk).
+ * The two classes existed in parallel ("PafiSDKError" in core,
+ * "PafiSdkError" in issuer) due to historical drift; consolidating
+ * here. Kept as alias for back-compat through v0.7.x; will be removed
+ * in v0.8. See SDK_CORE_TRADING_AUDIT.md H3.
+ */
 declare class PafiSDKError extends Error {
     constructor(message: string);
 }
@@ -106,16 +136,35 @@ declare class ApiError extends PafiSDKError {
  * caller did not opt in to the hardcoded fallback prices.
  *
  * v0.7.1 — previously `quoteOperatorFeePt` silently fell back to
- * ETH=$3000 / PT=$0.10 with `console.warn`. That caused mass
- * `INSUFFICIENT_FEE` rejects during Chainlink incidents, or worse,
- * accepted under-priced fees. Now opt-in via
+ * ETH=$3000 / PT=$0.10 with `console.warn`. Now opt-in via
  * `allowStaleFallback: true`. See SDK_CORE_TRADING_AUDIT.md C2.
+ *
+ * Extends the unified `PafiSdkError` so issuer's `createSdkErrorMapper`
+ * routes it to 503 instead of leaking as a 500.
  */
-declare class OracleStaleError extends PafiSDKError {
+declare class OracleStaleError extends PafiSdkError {
+    readonly httpStatus: "service_unavailable";
+    readonly code: "ORACLE_STALE";
     readonly source: "chainlink" | "subgraph";
     readonly reason: string;
     constructor(source: "chainlink" | "subgraph", reason: string);
 }
+/**
+ * Generic 4xx-class validation failure for input checks at any SDK
+ * boundary (core helpers, trading handlers, etc.). Issuer's
+ * `createSdkErrorMapper` routes to 422.
+ *
+ * Uses an instance `details` field so subclasses can override the
+ * declaration; matches the issuer-side shape that pre-existed here.
+ *
+ * v0.7.4 — added per SDK_CORE_TRADING_AUDIT.md H2/H13.
+ */
+declare class ValidationError extends PafiSdkError {
+    readonly httpStatus: "unprocessable";
+    readonly code: string;
+    readonly details?: Record<string, unknown>;
+    constructor(code: string, message: string, details?: Record<string, unknown>);
+}
 
 /**
  * Orderly Network Vault — entrypoint for **perp deposit** flow on
@@ -875,16 +924,15 @@ interface PaymasterConfig {
 type SponsorshipScenario = "mint" | "burn" | "swap" | "perp-deposit";
 
 /**
+ * @deprecated v0.7.1 — see file comment.
+ *
  * Set the application-wide paymaster config. Safe to call multiple
  * times (later calls override earlier). Throws if required fields
  * are missing.
  */
 declare function setPaymasterConfig(config: PaymasterConfig): void;
 /**
- * Get the current paymaster config. Throws if `setPaymasterConfig()`
- * has not been called yet — this surfaces boot-order bugs early
- * instead of failing with "paymaster.feeRecipient is undefined" at
- * the point of use.
+ * @deprecated v0.7.1 — see file comment.
  */
 declare function getPaymasterConfig(): PaymasterConfig;
 /** Test helper — clear the singleton. */
@@ -1249,15 +1297,35 @@ interface SendWithPaymasterFallbackParams {
  */
 declare function sendWithPaymasterFallback(params: SendWithPaymasterFallbackParams): Promise<Hex>;
 
+/**
+ * Per-scenario gas budgets (callGasLimit + verificationGas + preVerify)
+ * used by `quoteOperatorFee*`. Defaults are calibrated against the
+ * actual UserOps the issuer + trading SDKs build:
+ *
+ *   mint         — `RelayService.prepareMint` callGasLimit 300k → 500k margin
+ *   burn         — `RelayService.prepareBurn` 300k → 500k margin
+ *   swap         — `buildSwapUserOp` callGasLimit 700k (UR.execute heavy)
+ *   perp-deposit — `buildPerpDepositViaRelay` 800k (LayerZero msg)
+ *   delegate     — minimal no-op self-call, 200k margin
+ *
+ * Pass an explicit `gasUnits` to override. v0.7.4 — added per
+ * SDK_CORE_TRADING_AUDIT.md H12.
+ */
+type FeeScenario = "mint" | "burn" | "swap" | "perp-deposit" | "delegate";
 interface QuoteOperatorFeePtConfig {
     provider: PublicClient;
     chainId: number;
     pointTokenAddress: Address;
     /**
-     * ERC-4337 gas units the UserOp will consume on chain. Default
-     * 500_000n covers the common scenarios (mint, swap, perp deposit
-     * via Relay) with margin. Pass a tighter number when you have a
-     * Pimlico estimate to feed in.
+     * Scenario tag — picks default `gasUnits` from `SCENARIO_GAS_UNITS`.
+     * Ignored when `gasUnits` is explicit. Default `"mint"` for back-
+     * compat (matches the legacy 500_000 constant).
+     */
+    scenario?: FeeScenario;
+    /**
+     * ERC-4337 gas units the UserOp will consume on chain. Defaults to
+     * `SCENARIO_GAS_UNITS[scenario]`, falling back to 500_000n. Pass a
+     * tighter number when you have a Pimlico estimate to feed in.
      */
     gasUnits?: bigint;
     /**
@@ -1298,6 +1366,8 @@ interface QuoteOperatorFeePtConfig {
 interface QuoteOperatorFeeUsdtConfig {
     provider: PublicClient;
     chainId: number;
+    /** See `QuoteOperatorFeePtConfig.scenario`. v0.7.4. */
+    scenario?: FeeScenario;
     gasUnits?: bigint;
     premiumBps?: number;
     chainlinkFeedAddress?: Address;
@@ -1686,7 +1756,7 @@ declare class PafiSDK {
     buildMintRequestTypedData(message: MintRequest): Promise<{
         domain: {
             name: string;
-            version: "1";
+            version: string;
             chainId: number;
             verifyingContract: `0x${string}`;
         };
@@ -1711,7 +1781,7 @@ declare class PafiSDK {
     buildReceiverConsentTypedData(message: ReceiverConsent): Promise<{
         domain: {
             name: string;
-            version: "1";
+            version: string;
             chainId: number;
             verifyingContract: `0x${string}`;
         };
@@ -1750,4 +1820,4 @@ declare class PafiSDK {
     signLoginMessage(message: string): Promise<Hex>;
 }
 
-export { ApiError, BATCH_EXECUTOR_7702_IMPL, BATCH_EXECUTOR_ABI, BATCH_EXECUTOR_ADDRESS_BASE_MAINNET, BATCH_EXECUTOR_ADDRESS_BASE_SEPOLIA, BROKER_HASHES, type BuildDelegationUserOpParams, type BuildPartialUserOpParams, type BuildPerpDepositViaRelayParams, type BuildPerpDepositWithGasDeductionParams, COMMON_POOLS, COMMON_TOKENS, CONTRACT_ADDRESSES, ChainConfig, type CheckEthAndBranchParams, ConfigurationError, type ContractAddresses, DUMMY_SIGNATURE_V07, type DelegateImpl, EIP712Signature, ENTRY_POINT_V07, ENTRY_POINT_V08, type Eip7702AuthorizationJsonRpc, LoginMessageParams, MintRequest, type ModalOpenOptions, ORDERLY_RELAY_ABI, ORDERLY_VAULT_ABI, ORDERLY_VAULT_ADDRESSES, ORDERLY_VAULT_BASE_MAINNET, type Operation, OracleStaleError, type OrderlyRelayDepositRequest, PAFI_SUBGRAPH_URL, PERMIT2_ADDRESS, POINT_TOKEN_FACTORY_ADDRESSES, POINT_TOKEN_IMPL_ADDRESSES, POINT_TOKEN_POOLS, type PackedUserOperationMessage, type PafiProxyTransportParams, PafiSDK, PafiSDKConfig, PafiSDKError, type PafiWebModalAdapter, type PafiWebModalHandle, type PartialUserOperation, type PaymasterConfig, type PaymasterFields, PointTokenDomainConfig, PoolKey, type QuoteOperatorFeePtConfig, type QuoteOperatorFeeUsdtConfig, ReceiverConsent, SIMPLE_7702_IMPL_BASE_MAINNET, SUPPORTED_CHAINS, type SendWithPaymasterFallbackParams, type SignatureStruct, SignatureVerification, SigningError, SimulationError, type SmartAccountSender, type SponsorshipScenario, type SubmissionPath, TOKEN_HASHES, UNIVERSAL_ROUTER_ADDRESSES, type UserOpReceipt, type UserOpTypedData, type UserOperation, V4_QUOTER_ADDRESSES, type VaultDepositFE, ZERO_VALUE, _resetPaymasterConfigForTests, assembleUserOperation, buildDelegationUserOp, buildEip7702Authorization, buildPartialUserOperation, buildPerpDepositViaRelay, buildPerpDepositWithGasDeduction, buildUserOpTypedData, burnRequestTypes, checkDelegation, checkEthAndBranch, computeAccountId, computeAuthorizationHash, computeUserOpHash, createPafiProxyTransport, decodeBatchExecuteCalls, detectDelegateImpl, encodeBatchExecute, erc20ApproveOp, erc20BurnOp, erc20TransferOp, fetchPafiPools, getAaNonce, getContractAddresses, getDummySignatureFor7702, getPafiWebModalAdapter, getPaymasterConfig, isDelegatedTo, isDelegatedToTarget, isPaymasterConfigured, isPaymasterError, mintRequestTypes, openPafiWebModal, openWebPopup, parseEip7702DelegatedAddress, quoteOperatorFeePt, quoteOperatorFeeUsdt, rawCallOp, receiverConsentTypes, sendWithPaymasterFallback, serializeUserOpToJsonRpc, setPafiWebModalAdapter, setPaymasterConfig, splitAuthorizationSig, webPopupAdapter };
+export { ApiError, BATCH_EXECUTOR_7702_IMPL, BATCH_EXECUTOR_ABI, BATCH_EXECUTOR_ADDRESS_BASE_MAINNET, BATCH_EXECUTOR_ADDRESS_BASE_SEPOLIA, BROKER_HASHES, type BuildDelegationUserOpParams, type BuildPartialUserOpParams, type BuildPerpDepositViaRelayParams, type BuildPerpDepositWithGasDeductionParams, COMMON_POOLS, COMMON_TOKENS, CONTRACT_ADDRESSES, ChainConfig, type CheckEthAndBranchParams, ConfigurationError, type ContractAddresses, DUMMY_SIGNATURE_V07, type DelegateImpl, EIP712Signature, ENTRY_POINT_V07, ENTRY_POINT_V08, type Eip7702AuthorizationJsonRpc, LoginMessageParams, MintRequest, type ModalOpenOptions, ORDERLY_RELAY_ABI, ORDERLY_VAULT_ABI, ORDERLY_VAULT_ADDRESSES, ORDERLY_VAULT_BASE_MAINNET, type Operation, OracleStaleError, type OrderlyRelayDepositRequest, PAFI_SUBGRAPH_URL, PERMIT2_ADDRESS, POINT_TOKEN_FACTORY_ADDRESSES, POINT_TOKEN_IMPL_ADDRESSES, POINT_TOKEN_POOLS, type PackedUserOperationMessage, type PafiProxyTransportParams, PafiSDK, PafiSDKConfig, PafiSDKError, PafiSdkError, type PafiWebModalAdapter, type PafiWebModalHandle, type PartialUserOperation, type PaymasterConfig, type PaymasterFields, PointTokenDomainConfig, PoolKey, type QuoteOperatorFeePtConfig, type QuoteOperatorFeeUsdtConfig, ReceiverConsent, SIMPLE_7702_IMPL_BASE_MAINNET, SUPPORTED_CHAINS, type SdkErrorHttpStatus, type SendWithPaymasterFallbackParams, type SignatureStruct, SignatureVerification, SigningError, SimulationError, type SmartAccountSender, type SponsorshipScenario, type SubmissionPath, TOKEN_HASHES, UNIVERSAL_ROUTER_ADDRESSES, type UserOpReceipt, type UserOpTypedData, type UserOperation, V4_QUOTER_ADDRESSES, ValidationError, type VaultDepositFE, ZERO_VALUE, _resetPaymasterConfigForTests, assembleUserOperation, buildDelegationUserOp, buildEip7702Authorization, buildPartialUserOperation, buildPerpDepositViaRelay, buildPerpDepositWithGasDeduction, buildUserOpTypedData, burnRequestTypes, checkDelegation, checkEthAndBranch, computeAccountId, computeAuthorizationHash, computeUserOpHash, createPafiProxyTransport, decodeBatchExecuteCalls, detectDelegateImpl, encodeBatchExecute, erc20ApproveOp, erc20BurnOp, erc20TransferOp, fetchPafiPools, getAaNonce, getContractAddresses, getDummySignatureFor7702, getPafiWebModalAdapter, getPaymasterConfig, isDelegatedTo, isDelegatedToTarget, isPaymasterConfigured, isPaymasterError, mintRequestTypes, openPafiWebModal, openWebPopup, parseEip7702DelegatedAddress, quoteOperatorFeePt, quoteOperatorFeeUsdt, rawCallOp, receiverConsentTypes, sendWithPaymasterFallback, serializeUserOpToJsonRpc, setPafiWebModalAdapter, setPaymasterConfig, splitAuthorizationSig, webPopupAdapter };

package/dist/index.js

@@ -13,11 +13,12 @@ import {
   buildSponsorAuthTypedData,
   computeCallDataHash,
   createLoginMessage,
+  generateSponsorAuthNonce,
   parseLoginMessage,
   signSponsorAuth,
   verifyLoginMessage,
   verifySponsorAuth
-} from "./chunk-QGXJLLKF.js";
+} from "./chunk-6UX2IFA2.js";
 import {
   getBurnRequestNonce,
   getIssuer,
@@ -60,12 +61,25 @@ import {
   verifyBurnRequest,
   verifyMintRequest,
   verifyReceiverConsent
-} from "./chunk-UOKI5GG6.js";
+} from "./chunk-WJSIB5GF.js";
+import "./chunk-DGUM43GV.js";
 
 // src/index.ts
 import { createPublicClient, http as http2 } from "viem";
 
 // src/errors.ts
+var PafiSdkError = class extends Error {
+  /**
+   * `true` when the FE should consider a retry safe — typically because
+   * the failure is transient.
+   */
+  safeToRetry = false;
+  details;
+  constructor(message) {
+    super(message);
+    this.name = new.target.name;
+  }
+};
 var PafiSDKError = class extends Error {
   constructor(message) {
     super(message);
@@ -102,16 +116,27 @@ var ApiError = class extends PafiSDKError {
   }
   status;
 };
-var OracleStaleError = class extends PafiSDKError {
+var OracleStaleError = class extends PafiSdkError {
+  httpStatus = "service_unavailable";
+  code = "ORACLE_STALE";
   source;
   reason;
   constructor(source, reason) {
     super(`Oracle ${source} unavailable: ${reason}`);
-    this.name = "OracleStaleError";
     this.source = source;
     this.reason = reason;
   }
 };
+var ValidationError = class extends PafiSdkError {
+  httpStatus = "unprocessable";
+  code;
+  details;
+  constructor(code, message, details) {
+    super(message);
+    this.code = code;
+    this.details = details;
+  }
+};
 
 // src/perp/buildPerpDepositWithGasDeduction.ts
 import { encodeFunctionData as encodeFunctionData3 } from "viem";
@@ -912,6 +937,13 @@ var POOL_PRICE_QUERY = `
     }
   }
 `;
+var SCENARIO_GAS_UNITS = {
+  mint: 500000n,
+  burn: 500000n,
+  swap: 700000n,
+  "perp-deposit": 800000n,
+  delegate: 200000n
+};
 var DEFAULT_GAS_UNITS = 500000n;
 var DEFAULT_PREMIUM_BPS = 12e3;
 var DEFAULT_USDT_DECIMALS = 6;
@@ -919,7 +951,8 @@ async function quoteOperatorFeeUsdt(config) {
   const {
     provider,
     chainId,
-    gasUnits = DEFAULT_GAS_UNITS,
+    scenario = "mint",
+    gasUnits = SCENARIO_GAS_UNITS[scenario] ?? DEFAULT_GAS_UNITS,
     premiumBps = DEFAULT_PREMIUM_BPS,
     usdtDecimals = DEFAULT_USDT_DECIMALS,
     allowStaleFallback = false,
@@ -942,7 +975,8 @@ async function quoteOperatorFeePt(config) {
     provider,
     chainId,
     pointTokenAddress,
-    gasUnits = DEFAULT_GAS_UNITS,
+    scenario = "mint",
+    gasUnits = SCENARIO_GAS_UNITS[scenario] ?? DEFAULT_GAS_UNITS,
     premiumBps = DEFAULT_PREMIUM_BPS,
     subgraphUrl = PAFI_SUBGRAPH_URL,
     usdtDecimals = DEFAULT_USDT_DECIMALS,
@@ -1353,6 +1387,7 @@ export {
   pointTokenAbi as POINT_TOKEN_V2_ABI,
   PafiSDK,
   PafiSDKError,
+  PafiSdkError,
   SIMPLE_7702_IMPL_BASE_MAINNET,
   SPONSOR_AUTH_DOMAIN_NAME,
   SPONSOR_AUTH_TYPES,
@@ -1362,6 +1397,7 @@ export {
   TOKEN_HASHES,
   UNIVERSAL_ROUTER_ADDRESSES,
   V4_QUOTER_ADDRESSES,
+  ValidationError,
   ZERO_VALUE,
   _resetPaymasterConfigForTests,
   assembleUserOperation,
@@ -1395,6 +1431,7 @@ export {
   erc20BurnOp,
   erc20TransferOp,
   fetchPafiPools,
+  generateSponsorAuthNonce,
   getAaNonce,
   getBurnRequestNonce,
   getContractAddresses,