@pafi-dev/core 0.7.0 → 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);
 }
@@ -100,6 +130,41 @@ declare class ApiError extends PafiSDKError {
     status?: number | undefined;
     constructor(message: string, status?: number | undefined);
 }
+/**
+ * Thrown by `quoteOperatorFee*` when an upstream price source
+ * (Chainlink ETH/USD, PAFI subgraph) is unavailable or stale and the
+ * 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`. 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 {
+    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
@@ -859,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. */
@@ -1169,13 +1233,18 @@ interface SmartAccountSender {
  * Returns true when `err` originates from the **paymaster layer** rather
  * than the contract or bundler layer. Covers:
  *
- * - ERC-4337 AA3x validation errors (AA31–AA34)
- * - Pimlico sponsorship rejections (`pm_*` methods, "sponsorship" messages)
- * - PAFI proxy HTTP errors (401, 403, 429, 503)
+ * - ERC-4337 AA3x validation errors (AA31–AA34, word-boundary match)
+ * - Pimlico sponsorship rejections (`pm_*` methods, "sponsorship" / "paymaster")
+ * - PAFI proxy HTTP errors — checked via typed `status` / `statusCode`
+ *   field when present, NOT substring match
  * - Generic "rate limit" / "unauthorized" strings
  *
  * Use this to decide whether retrying without a paymaster makes sense.
  * Contract reverts (AA23, AA24, AA25) and bundler errors are NOT matched.
+ *
+ * v0.7.1 — replaced naive substring matching that false-positived on
+ * arbitrary text containing "503"/"403"/"429" (e.g. address/transit ID).
+ * See SDK_CORE_TRADING_AUDIT.md C3.
  */
 declare function isPaymasterError(err: unknown): boolean;
 interface SendWithPaymasterFallbackParams {
@@ -1228,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;
     /**
@@ -1251,9 +1340,20 @@ interface QuoteOperatorFeePtConfig {
     subgraphUrl?: string;
     /** USDT token decimals. Default 6 (USDC/USDT on Base/Ethereum). */
     usdtDecimals?: number;
-    /** Fallback ETH price (USD) when Chainlink is unreachable. Default 3000. */
+    /**
+     * Opt-in fallback prices used when Chainlink / subgraph is
+     * unavailable. Default `false` — throw `OracleStaleError`. Set
+     * `true` AND configure `fallbackEthPriceUsd` / `fallbackPtPriceUsdt`
+     * to absorb oracle outages instead of surfacing them.
+     *
+     * v0.7.1 — previously fallback was always-on with hardcoded
+     * defaults (ETH=$3000, PT=$0.10), causing under-priced fees during
+     * incidents. See SDK_CORE_TRADING_AUDIT.md C2.
+     */
+    allowStaleFallback?: boolean;
+    /** Fallback ETH price (USD) when Chainlink is unreachable. Only used when `allowStaleFallback: true`. Default 3000. */
     fallbackEthPriceUsd?: number;
-    /** Fallback PT price (USDT per 1 PT) when subgraph is unreachable. Default 0.1. */
+    /** Fallback PT price (USDT per 1 PT) when subgraph is unreachable. Only used when `allowStaleFallback: true`. Default 0.1. */
     fallbackPtPriceUsdt?: number;
     fetchImpl?: typeof fetch;
 }
@@ -1266,10 +1366,17 @@ interface QuoteOperatorFeePtConfig {
 interface QuoteOperatorFeeUsdtConfig {
     provider: PublicClient;
     chainId: number;
+    /** See `QuoteOperatorFeePtConfig.scenario`. v0.7.4. */
+    scenario?: FeeScenario;
     gasUnits?: bigint;
     premiumBps?: number;
     chainlinkFeedAddress?: Address;
     usdtDecimals?: number;
+    /**
+     * Opt-in fallback price when Chainlink is unavailable. Default
+     * `false` — throw `OracleStaleError`. v0.7.1 — see C2.
+     */
+    allowStaleFallback?: boolean;
     fallbackEthPriceUsd?: number;
 }
 /**
@@ -1649,7 +1756,7 @@ declare class PafiSDK {
     buildMintRequestTypedData(message: MintRequest): Promise<{
         domain: {
             name: string;
-            version: "1";
+            version: string;
             chainId: number;
             verifyingContract: `0x${string}`;
         };
@@ -1674,7 +1781,7 @@ declare class PafiSDK {
     buildReceiverConsentTypedData(message: ReceiverConsent): Promise<{
         domain: {
             name: string;
-            version: "1";
+            version: string;
             chainId: number;
             verifyingContract: `0x${string}`;
         };
@@ -1713,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, 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);
 }
@@ -100,6 +130,41 @@ declare class ApiError extends PafiSDKError {
     status?: number | undefined;
     constructor(message: string, status?: number | undefined);
 }
+/**
+ * Thrown by `quoteOperatorFee*` when an upstream price source
+ * (Chainlink ETH/USD, PAFI subgraph) is unavailable or stale and the
+ * 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`. 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 {
+    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
@@ -859,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. */
@@ -1169,13 +1233,18 @@ interface SmartAccountSender {
  * Returns true when `err` originates from the **paymaster layer** rather
  * than the contract or bundler layer. Covers:
  *
- * - ERC-4337 AA3x validation errors (AA31–AA34)
- * - Pimlico sponsorship rejections (`pm_*` methods, "sponsorship" messages)
- * - PAFI proxy HTTP errors (401, 403, 429, 503)
+ * - ERC-4337 AA3x validation errors (AA31–AA34, word-boundary match)
+ * - Pimlico sponsorship rejections (`pm_*` methods, "sponsorship" / "paymaster")
+ * - PAFI proxy HTTP errors — checked via typed `status` / `statusCode`
+ *   field when present, NOT substring match
  * - Generic "rate limit" / "unauthorized" strings
  *
  * Use this to decide whether retrying without a paymaster makes sense.
  * Contract reverts (AA23, AA24, AA25) and bundler errors are NOT matched.
+ *
+ * v0.7.1 — replaced naive substring matching that false-positived on
+ * arbitrary text containing "503"/"403"/"429" (e.g. address/transit ID).
+ * See SDK_CORE_TRADING_AUDIT.md C3.
  */
 declare function isPaymasterError(err: unknown): boolean;
 interface SendWithPaymasterFallbackParams {
@@ -1228,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;
     /**
@@ -1251,9 +1340,20 @@ interface QuoteOperatorFeePtConfig {
     subgraphUrl?: string;
     /** USDT token decimals. Default 6 (USDC/USDT on Base/Ethereum). */
     usdtDecimals?: number;
-    /** Fallback ETH price (USD) when Chainlink is unreachable. Default 3000. */
+    /**
+     * Opt-in fallback prices used when Chainlink / subgraph is
+     * unavailable. Default `false` — throw `OracleStaleError`. Set
+     * `true` AND configure `fallbackEthPriceUsd` / `fallbackPtPriceUsdt`
+     * to absorb oracle outages instead of surfacing them.
+     *
+     * v0.7.1 — previously fallback was always-on with hardcoded
+     * defaults (ETH=$3000, PT=$0.10), causing under-priced fees during
+     * incidents. See SDK_CORE_TRADING_AUDIT.md C2.
+     */
+    allowStaleFallback?: boolean;
+    /** Fallback ETH price (USD) when Chainlink is unreachable. Only used when `allowStaleFallback: true`. Default 3000. */
     fallbackEthPriceUsd?: number;
-    /** Fallback PT price (USDT per 1 PT) when subgraph is unreachable. Default 0.1. */
+    /** Fallback PT price (USDT per 1 PT) when subgraph is unreachable. Only used when `allowStaleFallback: true`. Default 0.1. */
     fallbackPtPriceUsdt?: number;
     fetchImpl?: typeof fetch;
 }
@@ -1266,10 +1366,17 @@ interface QuoteOperatorFeePtConfig {
 interface QuoteOperatorFeeUsdtConfig {
     provider: PublicClient;
     chainId: number;
+    /** See `QuoteOperatorFeePtConfig.scenario`. v0.7.4. */
+    scenario?: FeeScenario;
     gasUnits?: bigint;
     premiumBps?: number;
     chainlinkFeedAddress?: Address;
     usdtDecimals?: number;
+    /**
+     * Opt-in fallback price when Chainlink is unavailable. Default
+     * `false` — throw `OracleStaleError`. v0.7.1 — see C2.
+     */
+    allowStaleFallback?: boolean;
     fallbackEthPriceUsd?: number;
 }
 /**
@@ -1649,7 +1756,7 @@ declare class PafiSDK {
     buildMintRequestTypedData(message: MintRequest): Promise<{
         domain: {
             name: string;
-            version: "1";
+            version: string;
             chainId: number;
             verifyingContract: `0x${string}`;
         };
@@ -1674,7 +1781,7 @@ declare class PafiSDK {
     buildReceiverConsentTypedData(message: ReceiverConsent): Promise<{
         domain: {
             name: string;
-            version: "1";
+            version: string;
             chainId: number;
             verifyingContract: `0x${string}`;
         };
@@ -1713,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, 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 };