@mixerx/oracles 1.0.0 → 3.0.0

package/README.md

@@ -1,139 +1,118 @@
 # MixerX Oracles
 
-Oracle library for MixerX Relayer - fee calculation and token pricing for Tornado Cash operations.
-
-## Requirements
-
-- Node.js >= 24.12.0
-- Yarn 4.12.0 (nodeLinker: node-modules)
-
-Create `./.yarnrc.yml` (repository-root relative path, works on Linux/macOS/Windows):
-
-```yaml
-nodeLinker: node-modules
-```
+Fail-closed Sepolia pricing and gas policy for MixerX. Version 3.0.0 rejects a
+withdrawal quote when its gas or token price is missing, stale or economically
+unsafe.
+
+## Security contract
+
+- Sepolia (`11155111`) is the only accepted chain.
+- RPC endpoints must use HTTPS, are time-bounded and are checked against the
+  real `eth_chainId` response.
+- Token calls use Multicall3 atomically at one block. Any failed token rejects
+  the batch; no historical constant is substituted.
+- Non-native withdrawal fees require a repository price plus its observation
+  timestamp. The default maximum age is two minutes.
+- Gas data, service fee, refund, token decimals and total fee are bounded before
+  a result is returned. The default total-fee ceiling matches the contracts at
+  10% of the withdrawal amount.
+- Configurable token-price sanity bands can reject corrupted but fresh cache
+  values.
+- The exact withdrawal gas limit is mandatory input and must come from
+  simulation or `eth_estimateGas`; the package contains no token-specific
+  limits inherited from another protocol.
+- Logging is disabled by default. Inject an `ILogger` that follows the host
+  service's privacy policy if operational events are required.
+
+The Sepolia OffchainOracle deployment must contain valid rates and must be
+protected by the protocol's TWAP/deviation policy. The library cannot create or
+initialize that on-chain state. Call `assertReady()` during application startup;
+do not accept traffic if it fails.
 
 ## Installation
 
 ```bash
-yarn add @mixerx/oracles
+yarn add @mixerx/oracles@3.0.0
 ```
 
-## Quick Start
+Node.js 24.12.0 or newer is required.
+
+## Usage
+
+```ts
+import {
+  createMixerxOraclesModule,
+  type ITokenPriceRepository,
+} from '@mixerx/oracles';
 
-```typescript
-import { createMixerxOraclesModule } from '@mixerx/oracles';
+const priceRepository: ITokenPriceRepository = {
+  getQuote: async (symbol) => readCachedQuote(symbol),
+};
 
-// Create module
 const oracles = createMixerxOraclesModule({
-  chainId: 1, // Mainnet
-  rpcUrl: 'https://mainnet.infura.io/v3/YOUR_KEY',
-  relayerFeePercent: 0.004, // 0.4%
-  priceRepository: yourRedisRepository, // Implementation of ITokenPriceRepository
-  multicallAddress: '0xeefBa1e63905eF1D7ACbA5a8513c70307C1cE441', // optional
-  // offchainOracleAddress is optional:
-  // if omitted, it is resolved from @mixerx/config by chainId
-  fallbackGasPrices: {
-    legacy: { instant: 25, fast: 20, standard: 18, low: 15 },
-    eip1559: { baseFee: 10, maxFeePerGas: 20, maxPriorityFeePerGas: 2 },
-  },
+  chainId: 11155111,
+  rpcUrl: process.env.SEPOLIA_RPC_URL!,
+  relayerFeePercent: 0.004,
+  priceRepository,
+  maxGasPriceGwei: 100,
+  maxPriceAgeMs: 120_000,
+  maxTotalFeeBps: 1_000,
+  priceBounds: {
+    fds: {
+      minimumWeiPerToken: minimumAcceptedFdsPrice,
+      maximumWeiPerToken: maximumAcceptedFdsPrice,
+    },
+  },
 });
 
-// Fetch token prices
-const prices = await oracles.fetchPrices();
-console.log(prices); // { dai: '603108348359886', usdc: '601311723569085', ... }
+await oracles.assertReady();
 
-// Calculate withdrawal fee
-const fee = await oracles.tornadoFeeOracle.calculateWithdrawalFee({
-  currency: 'dai',
-  amount: BigInt('100000000000000000000'), // 100 DAI
+const fee = await oracles.mixerXFeeOracle.calculateWithdrawalFee({
+  currency: 'fds',
+  amount: 1_000_000_000_000_000_000n,
   decimals: 18,
-  refund: '0x0',
-  txType: 'relayer_withdrawal',
+  gasLimit: estimatedWithdrawalGas,
+  refund: '0',
+  purpose: 'fee',
 });
 
-console.log(`Total fee: ${fee.totalFee.toString()}`);
+console.log({
+  totalFee: fee.totalFee,
+  tokenPriceInEth: fee.tokenPriceInEth,
+  priceSource: fee.priceSource,
+  priceObservedAtMs: fee.priceObservedAtMs,
+  baseFeePerGas: fee.baseFeePerGas,
+  effectiveGasPriceWei: fee.gasPriceWei,
+  gasSource: fee.gasSource,
+});
 ```
 
-## Architecture
-
-This library follows Domain-Driven Design (DDD) principles:
-
-- **Domain**: Value objects and entities for fees, gas, and tokens
-- **Application**: Services and use cases for fee calculation and price fetching
-- **Infrastructure**: Adapters for blockchain interaction (ethers)
-
-## Features
-
-### Fee Calculation (V5)
-
-- Smart gas limit bumping (10% for relayer, 30% for user)
-- On-chain gas estimation with fallback to defaults
-- Support for ETH and ERC-20 tokens
-- Automatic conversion between ETH and token units
-- EIP-1559 and Legacy gas price support
-
-### Token Price Fetching
+`fee_quote` and `fee_validation` remain accepted as input aliases for migration,
+but both normalize to the single `fee` policy in returned data.
 
-- Fetches prices from on-chain OffchainOracle
-- Uses Multicall for efficient batch requests
-- Fallback to default prices if fetching fails
-- Token list is resolved from `@mixerx/config` by `chainId`
+## Price-feed operation
 
-### Mining Fee Support
+`fetchPrices()` reads all configured Sepolia tokens through Multicall3 at one
+explicit block. It returns the complete price map together with `blockNumber`
+and `observedAtMs`, and only succeeds when every token succeeds. The host price
+feed must persist each price and its observation metadata atomically. Fee
+calculation never falls back from that repository to a spot value.
 
-- Anonymity Mining reward calculations
-- Anonymity Mining withdrawal calculations
-- Automatic conversion between points and TORN
+The default Multicall3 address is
+`0xcA11bde05977b3631167028862bE2a173976CA11`; an explicit verified address can
+be supplied with `multicallAddress`.
 
-## API Reference
+## Development
 
-### `createMixerxOraclesModule(config)`
-
-Factory function to create the oracles module.
-
-**Config:**
-- `chainId`: Chain ID (1 for Mainnet)
-- `rpcUrl`: RPC endpoint URL
-- `relayerFeePercent`: Fee percentage (e.g., 0.004 for 0.4%)
-- `priceRepository`: Implementation of `ITokenPriceRepository`
-- `multicallAddress?`: Multicall contract address
-- `offchainOracleAddress?`: OffchainOracle contract address (fallback to `@mixerx/config` by `chainId`)
-- `fallbackGasPrices?`: Optional fallback gas prices
-
-### Use Cases
-
-#### `tornadoFeeOracle.calculateWithdrawalFee(input)`
-
-Calculate and validate fees for Tornado Cash withdrawals.
-
-**Input:**
-- `currency`: Token symbol (eth, dai, usdc, etc.)
-- `amount`: Withdrawal amount in base units (`bigint`)
-- `decimals`: Token decimals
-- `refund?`: Optional refund amount (hex string)
-- `txType?`: `'relayer_withdrawal' | 'user_withdrawal' | 'relayer_withdrawal_check_v4'`
-
-**Output:**
-- `gasCost`: bigint
-- `relayerFee`: bigint
-- `refundAmount`: bigint
-- `totalFee`: bigint
-- `currency`: string
-
-#### `fetchTokenPrices.execute(input?)`
-
-Fetch current token prices from on-chain oracle.
-
-**Input (optional):**
-- `tokens?`: Specific tokens to fetch
-- `useDefaults?`: Use default prices as fallback
+```bash
+yarn install --immutable
+yarn validate
+yarn npm audit --all --recursive --severity high
+```
 
-**Output:**
-- `prices`: TokenPrices map
-- `failedTokens`: Tokens that failed to fetch
-- `usedDefaults`: Whether defaults were used
+CI executes those gates for every pull request. Published packages pin the
+protocol configuration dependency exactly.
 
 ## License
 
-MIT
+GPL-3.0-only. See `LICENSE`.

package/dist/application/ports/ILogger.d.ts

@@ -15,4 +15,3 @@ export declare class ConsoleLogger implements ILogger {
     warn(message: string, meta?: unknown): void;
     error(message: string, meta?: unknown): void;
 }
-//# sourceMappingURL=ILogger.d.ts.map

package/dist/application/ports/ILogger.js

@@ -23,4 +23,3 @@ class ConsoleLogger {
     }
 }
 exports.ConsoleLogger = ConsoleLogger;
-//# sourceMappingURL=ILogger.js.map

package/dist/domain/config/TokenDefaults.d.ts

@@ -1,33 +1 @@
-/**
- * Token Defaults
- * Centralized configuration for Tornado Cash tokens
- *
- * This eliminates duplication between:
- * - TokenPriceOracle
- * - TokenPriceService
- * - FeeCalculator
- *
- * All token addresses, decimals, and default prices in one place
- */
-export declare const DEFAULT_TOKEN_PRICES: Record<string, string>;
-export declare const TORNADO_GAS_LIMITS: Record<string, number>;
-export declare const MINING_GAS_LIMITS: Record<string, number>;
-export declare const DEFAULT_RELAYER_FEE_PERCENT = 0.004;
-export declare const BUMP_PERCENTAGES: Record<string, number>;
-/**
- * Get default price for token
- */
-export declare function getDefaultTokenPrice(symbol: string): string | undefined;
-/**
- * Get gas limit for Tornado operation
- */
-export declare function getTornadoGasLimit(currency: string): number;
-/**
- * Get mining gas limit
- */
-export declare function getMiningGasLimit(operation: 'reward' | 'withdraw'): number;
-/**
- * Get bump percent for transaction type
- */
 export declare function getBumpPercent(txType: string): number;
-//# sourceMappingURL=TokenDefaults.d.ts.map

package/dist/domain/config/TokenDefaults.js

@@ -1,78 +1,12 @@
 "use strict";
-/**
- * Token Defaults
- * Centralized configuration for Tornado Cash tokens
- *
- * This eliminates duplication between:
- * - TokenPriceOracle
- * - TokenPriceService
- * - FeeCalculator
- *
- * All token addresses, decimals, and default prices in one place
- */
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.BUMP_PERCENTAGES = exports.DEFAULT_RELAYER_FEE_PERCENT = exports.MINING_GAS_LIMITS = exports.TORNADO_GAS_LIMITS = exports.DEFAULT_TOKEN_PRICES = void 0;
-exports.getDefaultTokenPrice = getDefaultTokenPrice;
-exports.getTornadoGasLimit = getTornadoGasLimit;
-exports.getMiningGasLimit = getMiningGasLimit;
 exports.getBumpPercent = getBumpPercent;
-// Token contract addresses and metadata are sourced from @mixerx/config
-// via infrastructure/config/ProtocolTokenConfig.ts.
-// Default prices as fallback (in wei per token unit, relative to ETH)
-// These represent the rate: 1 token = X wei of ETH
-exports.DEFAULT_TOKEN_PRICES = {
-    torn: '1689423546359032',
-    dai: '598416104472725',
-    cdai: '13384388487019',
-    usdc: '599013776676721',
-    usdt: '599323410893614',
-    wbtc: '15659889148334216720',
-};
-// Gas limits for Tornado operations by token (in gas units)
-exports.TORNADO_GAS_LIMITS = {
-    eth: 390000,
-    dai: 550000,
-    cdai: 425000,
-    usdc: 80000,
-    usdt: 100000,
-    wbtc: 85000,
-};
-// Mining operation gas limits
-exports.MINING_GAS_LIMITS = {
-    reward: 455000,
-    withdraw: 400000,
-};
-// Relayer fee percentage (0.4% default)
-exports.DEFAULT_RELAYER_FEE_PERCENT = 0.004;
-// Bump percentages by transaction type
-exports.BUMP_PERCENTAGES = {
-    relayer_withdrawal: 10,
-    user_withdrawal: 30,
-    relayer_withdrawal_check_v4: 0,
-    default: 10,
-};
-/**
- * Get default price for token
- */
-function getDefaultTokenPrice(symbol) {
-    return exports.DEFAULT_TOKEN_PRICES[symbol.toLowerCase()];
-}
-/**
- * Get gas limit for Tornado operation
- */
-function getTornadoGasLimit(currency) {
-    return exports.TORNADO_GAS_LIMITS[currency.toLowerCase()] ?? exports.TORNADO_GAS_LIMITS.eth;
-}
-/**
- * Get mining gas limit
- */
-function getMiningGasLimit(operation) {
-    return exports.MINING_GAS_LIMITS[operation] ?? 400000;
-}
-/**
- * Get bump percent for transaction type
- */
+const BUMP_PERCENTAGES = new Map([
+    ['relayer_withdrawal', 10],
+    ['user_withdrawal', 30],
+    ['relayer_withdrawal_check_v4', 0],
+]);
 function getBumpPercent(txType) {
-    return exports.BUMP_PERCENTAGES[txType] ?? exports.BUMP_PERCENTAGES.default;
+    const key = txType.trim().toLowerCase();
+    return BUMP_PERCENTAGES.get(key) ?? 10;
 }
-//# sourceMappingURL=TokenDefaults.js.map

package/dist/domain/exceptions.d.ts

@@ -1,5 +1,9 @@
-export declare class TokenPriceError extends Error {
-    readonly symbols: string[];
-    constructor(message: string, symbols?: string[]);
+export type OracleErrorCode = 'INVALID_CONFIG' | 'INVALID_INPUT' | 'NETWORK_MISMATCH' | 'RPC_REQUEST_FAILED' | 'TOKEN_PRICE_UNAVAILABLE' | 'TOKEN_PRICE_STALE' | 'TOKEN_PRICE_OUT_OF_RANGE' | 'ECONOMIC_LIMIT_EXCEEDED';
+export declare class OracleError extends Error {
+    readonly code: OracleErrorCode;
+    constructor(code: OracleErrorCode, message: string);
+}
+export declare class TokenPriceError extends OracleError {
+    readonly symbols: readonly string[];
+    constructor(message: string, symbols?: readonly string[]);
 }
-//# sourceMappingURL=exceptions.d.ts.map

package/dist/domain/exceptions.js

@@ -1,13 +1,21 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.TokenPriceError = void 0;
-class TokenPriceError extends Error {
+exports.TokenPriceError = exports.OracleError = void 0;
+class OracleError extends Error {
+    code;
+    constructor(code, message) {
+        super(message);
+        this.code = code;
+        this.name = 'OracleError';
+    }
+}
+exports.OracleError = OracleError;
+class TokenPriceError extends OracleError {
     symbols;
     constructor(message, symbols = []) {
-        super(message);
+        super('TOKEN_PRICE_UNAVAILABLE', message);
         this.symbols = symbols;
         this.name = 'TokenPriceError';
     }
 }
 exports.TokenPriceError = TokenPriceError;
-//# sourceMappingURL=exceptions.js.map

package/dist/domain/repositories.d.ts

@@ -1,4 +1,5 @@
+import type { TokenPriceQuote } from '../types';
 export interface ITokenPriceRepository {
-    getPrice(symbol: string): Promise<bigint | null | undefined>;
+    getQuote(symbol: string): Promise<TokenPriceQuote | null | undefined>;
 }
-//# sourceMappingURL=repositories.d.ts.map
+export declare function toPriceQuote(price: bigint | null | undefined, observedAtMs: number | null | undefined): TokenPriceQuote | null;

package/dist/domain/repositories.js

@@ -1,3 +1,12 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-//# sourceMappingURL=repositories.js.map
+exports.toPriceQuote = toPriceQuote;
+function toPriceQuote(price, observedAtMs) {
+    if (price === null || price === undefined || price <= 0n) {
+        return null;
+    }
+    if (!Number.isSafeInteger(observedAtMs) || (observedAtMs ?? -1) < 0) {
+        return null;
+    }
+    return { priceInEthWei: price, observedAtMs: observedAtMs, source: 'repository' };
+}

package/dist/factory.d.ts

@@ -1,62 +1,31 @@
+import type { ILogger } from './application/ports/ILogger';
+import type { ITokenPriceRepository } from './domain/repositories';
 import { GasPriceOracle } from './infrastructure/gas/GasPriceOracle';
+import { MixerXFeeOracle } from './infrastructure/mixerx/MixerXFeeOracle';
+import type { TokenPriceBounds } from './infrastructure/mixerx/MixerXFeeOracle';
 import { TokenPriceOracle } from './infrastructure/token-price/TokenPriceOracle';
-import { TornadoFeeOracle } from './infrastructure/tornado/TornadoFeeOracle';
-import { ITokenPriceRepository } from './domain/repositories';
-import { ChainId } from './infrastructure/config/gasOracleConfigs';
-import { TokenPrices } from './types';
-/**
- * Simplified Configuration for mixerx-oracles module
- */
+import type { ChainId, TokenPriceSnapshot } from './types';
 export interface MixerxOraclesConfig {
-    /** Chain ID */
     chainId: ChainId;
-    /** RPC URL for blockchain connection */
     rpcUrl: string;
-    /** Relayer fee percentage (e.g., 0.004 for 0.4%) */
     relayerFeePercent: number;
-    /** Token price repository (for reading prices from Redis/cache) - optional */
     priceRepository?: ITokenPriceRepository;
-    /** Multicall contract address (optional, uses default) */
     multicallAddress?: string;
-    /** Offchain oracle contract address (optional, falls back to @mixerx/config by chain) */
     offchainOracleAddress?: string;
-    /** Fallback gas prices (optional) */
-    fallbackGasPrices?: {
-        legacy?: {
-            instant: number;
-            fast: number;
-            standard: number;
-            low: number;
-        };
-        eip1559?: {
-            baseFee: number;
-            maxFeePerGas: number;
-            maxPriorityFeePerGas: number;
-        };
-    };
+    logger?: ILogger;
+    rpcTimeoutMs?: number;
+    maxGasPriceGwei?: number;
+    maxPriceAgeMs?: number;
+    maxRefundWei?: bigint;
+    maxTotalFeeBps?: number;
+    priceBounds?: Readonly<Record<string, TokenPriceBounds>>;
 }
-/**
- * Mixerx Oracles Module Interface
- */
 export interface IMixerxOraclesModule {
-    /** Gas price oracle (EIP-1559 + Legacy) */
     gasPriceOracle: GasPriceOracle;
-    /** Token price oracle (Multicall + OffchainOracle) */
     tokenPriceOracle: TokenPriceOracle;
-    /** Tornado fee oracle (V5 - calculates withdrawal fees) */
-    tornadoFeeOracle: TornadoFeeOracle;
-    /** Convenience method to fetch token prices */
-    fetchPrices(): Promise<TokenPrices>;
-    /** Chain ID */
+    mixerXFeeOracle: MixerXFeeOracle;
+    fetchPrices(): Promise<TokenPriceSnapshot>;
+    assertReady(): Promise<void>;
     chainId: ChainId;
 }
-/**
- * Factory function to create mixerx-oracles module
- *
- * This creates a complete oracle module with:
- * - GasPriceOracle: Fetches EIP-1559 and Legacy gas prices from multiple sources
- * - TokenPriceOracle: Fetches token prices using Multicall to OffchainOracle
- * - TornadoFeeOracle: Calculates Tornado Cash withdrawal fees
- */
 export declare function createMixerxOraclesModule(config: MixerxOraclesConfig): IMixerxOraclesModule;
-//# sourceMappingURL=factory.d.ts.map

package/dist/factory.js

@@ -1,51 +1,41 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.createMixerxOraclesModule = createMixerxOraclesModule;
+const ILogger_1 = require("./application/ports/ILogger");
 const GasPriceOracle_1 = require("./infrastructure/gas/GasPriceOracle");
+const MixerXFeeOracle_1 = require("./infrastructure/mixerx/MixerXFeeOracle");
 const TokenPriceOracle_1 = require("./infrastructure/token-price/TokenPriceOracle");
-const TornadoFeeOracle_1 = require("./infrastructure/tornado/TornadoFeeOracle");
-const ProtocolTokenConfig_1 = require("./infrastructure/config/ProtocolTokenConfig");
-/**
- * Factory function to create mixerx-oracles module
- *
- * This creates a complete oracle module with:
- * - GasPriceOracle: Fetches EIP-1559 and Legacy gas prices from multiple sources
- * - TokenPriceOracle: Fetches token prices using Multicall to OffchainOracle
- * - TornadoFeeOracle: Calculates Tornado Cash withdrawal fees
- */
 function createMixerxOraclesModule(config) {
-    // Multicall remains explicit/hardcoded-compatible by design
-    const multicallAddress = config.multicallAddress || '0xeefBa1e63905eF1D7ACbA5a8513c70307C1cE441';
-    const offchainOracleAddress = config.offchainOracleAddress || (0, ProtocolTokenConfig_1.resolveOffchainOracleAddress)(config.chainId);
-    const defaultTokens = (0, ProtocolTokenConfig_1.resolveDefaultTokens)(config.chainId);
-    // Create gas price oracle
+    const logger = config.logger ?? new ILogger_1.NullLogger();
     const gasPriceOracle = new GasPriceOracle_1.GasPriceOracle({
         chainId: config.chainId,
         rpcUrl: config.rpcUrl,
-        fallbackGasPrices: config.fallbackGasPrices,
+        logger,
+        rpcTimeoutMs: config.rpcTimeoutMs,
+        maxGasPriceGwei: config.maxGasPriceGwei,
     });
-    // Create token price oracle
-    const tokenPriceOracle = new TokenPriceOracle_1.TokenPriceOracle(config.rpcUrl, config.chainId, offchainOracleAddress, multicallAddress, defaultTokens);
-    // Create tornado fee oracle
-    const tornadoFeeOracle = new TornadoFeeOracle_1.TornadoFeeOracle({
+    const tokenPriceOracle = new TokenPriceOracle_1.TokenPriceOracle(config.rpcUrl, config.chainId, config.offchainOracleAddress, config.multicallAddress, undefined, logger, config.rpcTimeoutMs);
+    const mixerXFeeOracle = new MixerXFeeOracle_1.MixerXFeeOracle({
         chainId: config.chainId,
         rpcUrl: config.rpcUrl,
         relayerFeePercent: config.relayerFeePercent,
         gasPriceOracle,
         tokenPriceOracle,
         priceRepository: config.priceRepository,
-        multicallAddress,
-        offchainOracleAddress,
+        logger,
+        rpcTimeoutMs: config.rpcTimeoutMs,
+        maxGasPriceGwei: config.maxGasPriceGwei,
+        maxPriceAgeMs: config.maxPriceAgeMs,
+        maxRefundWei: config.maxRefundWei,
+        maxTotalFeeBps: config.maxTotalFeeBps,
+        priceBounds: config.priceBounds,
     });
     return {
         gasPriceOracle,
         tokenPriceOracle,
-        tornadoFeeOracle,
+        mixerXFeeOracle,
         chainId: config.chainId,
-        // Convenience method
-        async fetchPrices() {
-            return tokenPriceOracle.fetchPrices();
-        },
+        fetchPrices: () => tokenPriceOracle.fetchPrices(),
+        assertReady: () => mixerXFeeOracle.assertReady(),
     };
 }
-//# sourceMappingURL=factory.js.map

package/dist/index.d.ts

@@ -1,2 +1,7 @@
 export * from './factory';
-//# sourceMappingURL=index.d.ts.map
+export { OracleError, TokenPriceError } from './domain/exceptions';
+export type { OracleErrorCode } from './domain/exceptions';
+export type { ILogger } from './application/ports/ILogger';
+export type { ITokenPriceRepository } from './domain/repositories';
+export type { TokenPriceQuote, TokenPriceSnapshot } from './types';
+export type { FeeCalculationResult, MixerXGasPurpose, MixerXFeeCalculationResult, MixerXGasParametersForTxResult, MixerXTxType, WithdrawalFeeInput, } from './infrastructure/mixerx/MixerXFeeOracle';

package/dist/index.js

@@ -14,5 +14,8 @@ var __exportStar = (this && this.__exportStar) || function(m, exports) {
     for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
 };
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.TokenPriceError = exports.OracleError = void 0;
 __exportStar(require("./factory"), exports);
-//# sourceMappingURL=index.js.map
+var exceptions_1 = require("./domain/exceptions");
+Object.defineProperty(exports, "OracleError", { enumerable: true, get: function () { return exceptions_1.OracleError; } });
+Object.defineProperty(exports, "TokenPriceError", { enumerable: true, get: function () { return exceptions_1.TokenPriceError; } });

package/dist/infrastructure/blockchain/staticProvider.d.ts

@@ -0,0 +1,3 @@
+import { ethers, type JsonRpcApiProviderOptions } from 'ethers';
+export declare function createVerifiedJsonRpcProvider(rpcUrl: string, chainId: number, options?: JsonRpcApiProviderOptions, timeoutMs?: number): ethers.JsonRpcProvider;
+export declare function assertProviderNetwork(provider: ethers.JsonRpcProvider, expectedChainId: number): Promise<void>;

package/dist/infrastructure/blockchain/staticProvider.js

@@ -0,0 +1,36 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createVerifiedJsonRpcProvider = createVerifiedJsonRpcProvider;
+exports.assertProviderNetwork = assertProviderNetwork;
+const ethers_1 = require("ethers");
+const exceptions_1 = require("../../domain/exceptions");
+const gasOracleConfigs_1 = require("../config/gasOracleConfigs");
+const DEFAULT_RPC_TIMEOUT_MS = 10_000;
+function createVerifiedJsonRpcProvider(rpcUrl, chainId, options, timeoutMs = DEFAULT_RPC_TIMEOUT_MS) {
+    (0, gasOracleConfigs_1.assertSepoliaChainId)(chainId);
+    validateRpcUrl(rpcUrl);
+    if (!Number.isInteger(timeoutMs) || timeoutMs < 1_000 || timeoutMs > 60_000) {
+        throw new exceptions_1.OracleError('INVALID_CONFIG', 'rpcTimeoutMs must be an integer between 1000 and 60000');
+    }
+    const request = new ethers_1.FetchRequest(rpcUrl);
+    request.timeout = timeoutMs;
+    return new ethers_1.ethers.JsonRpcProvider(request, undefined, options);
+}
+async function assertProviderNetwork(provider, expectedChainId) {
+    const network = await provider.getNetwork();
+    if (network.chainId !== BigInt(expectedChainId)) {
+        throw new exceptions_1.OracleError('NETWORK_MISMATCH', `RPC network mismatch: expected ${String(expectedChainId)}, received ${network.chainId.toString()}`);
+    }
+}
+function validateRpcUrl(rawUrl) {
+    let url;
+    try {
+        url = new URL(rawUrl);
+    }
+    catch {
+        throw new exceptions_1.OracleError('INVALID_CONFIG', 'rpcUrl must be a valid HTTPS URL');
+    }
+    if (url.protocol !== 'https:' || url.username || url.password) {
+        throw new exceptions_1.OracleError('INVALID_CONFIG', 'rpcUrl must use HTTPS and must not contain user-info credentials');
+    }
+}

package/dist/infrastructure/config/ProtocolTokenConfig.d.ts

@@ -1,4 +1,3 @@
 import type { ChainId, Token } from '../../types';
 export declare function resolveOffchainOracleAddress(chainId: ChainId | number): string;
 export declare function resolveDefaultTokens(chainId: ChainId | number): Token[];
-//# sourceMappingURL=ProtocolTokenConfig.d.ts.map