@mixerx/oracles 2.0.0 → 3.1.0

package/dist/infrastructure/mixerx/MixerXFeeOracle.d.ts

@@ -1,7 +1,7 @@
 import type { ILogger } from '../../application/ports/ILogger';
 import { type ITokenPriceRepository } from '../../domain/repositories';
 import { GasPriceOracle, type GasPriceParams } from '../gas/GasPriceOracle';
-import type { ChainId } from '../config/gasOracleConfigs';
+import { type ChainId } from '../config/gasOracleConfigs';
 import { TokenPriceOracle } from '../token-price/TokenPriceOracle';
 export type MixerXTxType = 'relayer_withdrawal' | 'user_withdrawal' | 'relayer_withdrawal_check_v4';
 export type MixerXGasPurpose = 'fee' | 'send' | 'replacement';
@@ -20,6 +20,12 @@ export interface MixerXFeeOracleOptions {
     maxGasPriceGwei?: number;
     maxPriceAgeMs?: number;
     maxRefundWei?: bigint;
+    maxTotalFeeBps?: number;
+    priceBounds?: Readonly<Record<string, TokenPriceBounds>>;
+}
+export interface TokenPriceBounds {
+    minimumWeiPerToken: bigint;
+    maximumWeiPerToken: bigint;
 }
 export interface MixerXWithdrawalFeeInput {
     currency: string;
@@ -28,6 +34,7 @@ export interface MixerXWithdrawalFeeInput {
     /** Gas limit obtained from a simulation or eth_estimateGas for this exact transaction. */
     gasLimit: number;
     refund?: string;
+    refundGasMultiplier?: number;
     txType?: MixerXTxType;
     purpose?: 'fee' | LegacyFeePurpose;
 }
@@ -45,10 +52,12 @@ export interface MixerXFeeCalculationResult {
     gasCost: bigint;
     relayerFee: bigint;
     refundAmount: bigint;
+    refundWei: bigint;
     totalFee: bigint;
     currency: string;
     gasLimit: number;
     gasPriceWei: bigint;
+    gasSource: 'rpc';
     baseFeePerGas?: string;
     maxFeePerGas?: string;
     maxPriorityFeePerGas?: string;
@@ -63,7 +72,6 @@ export interface MixerXFeeCalculationResult {
 export type WithdrawalFeeInput = MixerXWithdrawalFeeInput;
 export type FeeCalculationResult = MixerXFeeCalculationResult;
 export declare class MixerXFeeOracle {
-    private readonly chainId;
     private readonly relayerFeePartsPerMillion;
     private readonly gasPriceOracle;
     private readonly tokenPriceOracle;
@@ -71,18 +79,21 @@ export declare class MixerXFeeOracle {
     private readonly logger;
     private readonly maxPriceAgeMs;
     private readonly maxRefundWei;
-    private readonly supportedCurrencies;
+    private readonly maxTotalFeeBps;
+    private readonly currencyDecimals;
+    private readonly priceBounds;
     constructor(options: MixerXFeeOracleOptions);
     calculateWithdrawalFee(input: MixerXWithdrawalFeeInput): Promise<MixerXFeeCalculationResult>;
     getGasParametersForTx(input?: MixerXGasParametersForTxInput): Promise<MixerXGasParametersForTxResult>;
     assertReady(): Promise<void>;
-    getGasParameters(isLegacy?: boolean): Promise<GasPriceParams>;
-    getChainId(): ChainId;
     private validateFeeInput;
     private parseRefund;
+    private resolveRefundWei;
     private getFreshPrice;
+    private validatePriceBounds;
     private effectiveGasPrice;
     private assertTotalFee;
     private normalizePurpose;
+    private validateTxType;
     private result;
 }

package/dist/infrastructure/mixerx/MixerXFeeOracle.js

@@ -6,12 +6,27 @@ const TokenDefaults_1 = require("../../domain/config/TokenDefaults");
 const exceptions_1 = require("../../domain/exceptions");
 const repositories_1 = require("../../domain/repositories");
 const GasPriceOracle_1 = require("../gas/GasPriceOracle");
+const gasOracleConfigs_1 = require("../config/gasOracleConfigs");
 const TokenPriceOracle_1 = require("../token-price/TokenPriceOracle");
 const DEFAULT_MAX_PRICE_AGE_MS = 120_000;
 const DEFAULT_MAX_REFUND_WEI = 1000000000000000000n;
+const DEFAULT_MAX_TOTAL_FEE_BPS = 1_000;
+const BASIS_POINTS_SCALE = 10000n;
 const FEE_SCALE = 1000000n;
+const MAX_REFUND_DIGITS = 256;
+const TX_TYPES = new Set([
+    'relayer_withdrawal',
+    'user_withdrawal',
+    'relayer_withdrawal_check_v4',
+]);
+const GAS_PURPOSES = new Set([
+    'fee',
+    'send',
+    'replacement',
+    'fee_quote',
+    'fee_validation',
+]);
 class MixerXFeeOracle {
-    chainId;
     relayerFeePartsPerMillion;
     gasPriceOracle;
     tokenPriceOracle;
@@ -19,11 +34,18 @@ class MixerXFeeOracle {
     logger;
     maxPriceAgeMs;
     maxRefundWei;
-    supportedCurrencies;
+    maxTotalFeeBps;
+    currencyDecimals;
+    priceBounds;
     constructor(options) {
+        (0, gasOracleConfigs_1.assertSupportedChainId)(options.chainId);
         if (!Number.isFinite(options.relayerFeePercent) || options.relayerFeePercent < 0 || options.relayerFeePercent > 0.1) {
             throw new exceptions_1.OracleError('INVALID_CONFIG', 'relayerFeePercent must be between 0 and 0.1');
         }
+        const relayerFeePartsPerMillion = options.relayerFeePercent * Number(FEE_SCALE);
+        if (!Number.isInteger(relayerFeePartsPerMillion)) {
+            throw new exceptions_1.OracleError('INVALID_CONFIG', 'relayerFeePercent exceeds supported precision');
+        }
         this.maxPriceAgeMs = options.maxPriceAgeMs ?? DEFAULT_MAX_PRICE_AGE_MS;
         if (!Number.isInteger(this.maxPriceAgeMs) || this.maxPriceAgeMs < 1_000 || this.maxPriceAgeMs > 3_600_000) {
             throw new exceptions_1.OracleError('INVALID_CONFIG', 'maxPriceAgeMs must be between 1000 and 3600000');
@@ -32,8 +54,13 @@ class MixerXFeeOracle {
         if (this.maxRefundWei < 0n) {
             throw new exceptions_1.OracleError('INVALID_CONFIG', 'maxRefundWei cannot be negative');
         }
-        this.chainId = options.chainId;
-        this.relayerFeePartsPerMillion = BigInt(Math.round(options.relayerFeePercent * Number(FEE_SCALE)));
+        this.maxTotalFeeBps = options.maxTotalFeeBps ?? DEFAULT_MAX_TOTAL_FEE_BPS;
+        if (!Number.isInteger(this.maxTotalFeeBps) ||
+            this.maxTotalFeeBps < 1 ||
+            this.maxTotalFeeBps > DEFAULT_MAX_TOTAL_FEE_BPS) {
+            throw new exceptions_1.OracleError('INVALID_CONFIG', 'maxTotalFeeBps must be an integer between 1 and 1000');
+        }
+        this.relayerFeePartsPerMillion = BigInt(relayerFeePartsPerMillion);
         this.logger = options.logger ?? new ILogger_1.NullLogger();
         this.gasPriceOracle = options.gasPriceOracle ?? new GasPriceOracle_1.GasPriceOracle({
             chainId: options.chainId,
@@ -43,15 +70,20 @@ class MixerXFeeOracle {
             maxGasPriceGwei: options.maxGasPriceGwei,
         });
         this.tokenPriceOracle = options.tokenPriceOracle ?? new TokenPriceOracle_1.TokenPriceOracle(options.rpcUrl, options.chainId, options.offchainOracleAddress, options.multicallAddress, undefined, this.logger, options.rpcTimeoutMs);
-        this.supportedCurrencies = new Set([
-            'eth',
-            ...this.tokenPriceOracle.getSupportedTokens().map((token) => token.symbol),
+        const supportedTokens = this.tokenPriceOracle.getSupportedTokens();
+        if (supportedTokens.some((token) => token.symbol.trim().toLowerCase() === 'eth')) {
+            throw new exceptions_1.OracleError('INVALID_CONFIG', 'Token symbol eth is reserved for native ETH');
+        }
+        this.currencyDecimals = new Map([
+            ['eth', 18],
+            ...supportedTokens.map((token) => [token.symbol, token.decimals]),
         ]);
+        this.priceBounds = this.validatePriceBounds(options.priceBounds ?? {});
         this.priceRepository = options.priceRepository;
     }
     async calculateWithdrawalFee(input) {
         const currency = this.validateFeeInput(input);
-        const txType = input.txType ?? 'relayer_withdrawal';
+        const txType = this.validateTxType(input.txType ?? 'relayer_withdrawal');
         const gasParams = await this.getGasParametersForTx({
             txType,
             purpose: this.normalizePurpose(input.purpose ?? 'fee'),
@@ -62,7 +94,8 @@ class MixerXFeeOracle {
         const gasCostWei = gasPriceWei * BigInt(gasLimit);
         const relayerFee = (input.amount * this.relayerFeePartsPerMillion) / FEE_SCALE;
         if (currency === 'eth') {
-            if (input.refund !== undefined && this.parseRefund(input.refund) !== 0n) {
+            if ((input.refund !== undefined && this.parseRefund(input.refund) !== 0n) ||
+                (input.refundGasMultiplier !== undefined && input.refundGasMultiplier !== 0)) {
                 throw new exceptions_1.OracleError('INVALID_INPUT', 'refund must be zero for native ETH withdrawals');
             }
             const totalFee = gasCostWei + relayerFee;
@@ -71,6 +104,7 @@ class MixerXFeeOracle {
                 gasCost: gasCostWei,
                 relayerFee,
                 refundAmount: 0n,
+                refundWei: 0n,
                 totalFee,
                 currency,
                 gasLimit,
@@ -83,7 +117,7 @@ class MixerXFeeOracle {
         const quote = await this.getFreshPrice(currency);
         const decimalsFactor = 10n ** BigInt(input.decimals);
         const gasCost = (gasCostWei * decimalsFactor) / quote.priceInEthWei;
-        const refundWei = this.parseRefund(input.refund ?? '0');
+        const refundWei = this.resolveRefundWei(input, gasCostWei);
         const refundAmount = (refundWei * decimalsFactor) / quote.priceInEthWei;
         const totalFee = gasCost + relayerFee + refundAmount;
         this.assertTotalFee(totalFee, input.amount);
@@ -91,6 +125,7 @@ class MixerXFeeOracle {
             gasCost,
             relayerFee,
             refundAmount,
+            refundWei,
             totalFee,
             currency,
             gasLimit,
@@ -103,31 +138,31 @@ class MixerXFeeOracle {
         });
     }
     async getGasParametersForTx(input = {}) {
-        const txType = input.txType ?? 'relayer_withdrawal';
+        const txType = this.validateTxType(input.txType ?? 'relayer_withdrawal');
         const purpose = this.normalizePurpose(input.purpose ?? 'send');
         const bumpPercent = purpose === 'send' ? 0 : (0, TokenDefaults_1.getBumpPercent)(txType);
         const gasParams = await this.gasPriceOracle.getTxGasParams({
             isLegacy: input.isLegacy ?? false,
             bumpPercent,
-            legacySpeed: 'fast',
         });
         return { ...gasParams, txType, purpose, bumpPercent };
     }
     async assertReady() {
-        await this.tokenPriceOracle.fetchPrices();
-    }
-    async getGasParameters(isLegacy = false) {
-        return this.gasPriceOracle.getTxGasParams({ isLegacy });
-    }
-    getChainId() {
-        return this.chainId;
+        await Promise.all([
+            this.gasPriceOracle.getTxGasParams(),
+            this.tokenPriceOracle.fetchPrices(),
+        ]);
+        await Promise.all(this.tokenPriceOracle
+            .getSupportedTokens()
+            .map((token) => this.getFreshPrice(token.symbol)));
     }
     validateFeeInput(input) {
         const currency = input.currency.trim().toLowerCase();
         if (!/^[a-z0-9]{2,16}$/.test(currency)) {
             throw new exceptions_1.OracleError('INVALID_INPUT', 'currency must be a valid protocol token symbol');
         }
-        if (!this.supportedCurrencies.has(currency)) {
+        const configuredDecimals = this.currencyDecimals.get(currency);
+        if (configuredDecimals === undefined) {
             throw new exceptions_1.OracleError('INVALID_INPUT', `Unsupported MixerX currency: ${currency}`);
         }
         if (input.amount <= 0n) {
@@ -136,13 +171,16 @@ class MixerXFeeOracle {
         if (!Number.isInteger(input.decimals) || input.decimals < 0 || input.decimals > 255) {
             throw new exceptions_1.OracleError('INVALID_INPUT', 'decimals must be an integer between 0 and 255');
         }
+        if (input.decimals !== configuredDecimals) {
+            throw new exceptions_1.OracleError('INVALID_INPUT', `${currency} must use configured decimals ${String(configuredDecimals)}`);
+        }
         if (!Number.isInteger(input.gasLimit) || input.gasLimit < 21_000 || input.gasLimit > 5_000_000) {
             throw new exceptions_1.OracleError('INVALID_INPUT', 'gasLimit must be an integer between 21000 and 5000000');
         }
         return currency;
     }
     parseRefund(raw) {
-        if (!/^\d+$/.test(raw)) {
+        if (typeof raw !== 'string' || raw.length > MAX_REFUND_DIGITS || !/^\d+$/.test(raw)) {
             throw new exceptions_1.OracleError('INVALID_INPUT', 'refund must be an unsigned base-10 integer string');
         }
         const refund = BigInt(raw);
@@ -151,45 +189,78 @@ class MixerXFeeOracle {
         }
         return refund;
     }
+    resolveRefundWei(input, gasCostWei) {
+        if (input.refund !== undefined && input.refundGasMultiplier !== undefined) {
+            throw new exceptions_1.OracleError('INVALID_INPUT', 'Specify either refund or refundGasMultiplier, not both');
+        }
+        if (input.refundGasMultiplier === undefined) {
+            return this.parseRefund(input.refund ?? '0');
+        }
+        if (!Number.isSafeInteger(input.refundGasMultiplier) ||
+            input.refundGasMultiplier < 0 ||
+            input.refundGasMultiplier > 10) {
+            throw new exceptions_1.OracleError('INVALID_INPUT', 'refundGasMultiplier must be an integer between 0 and 10');
+        }
+        return this.parseRefund((gasCostWei * BigInt(input.refundGasMultiplier)).toString());
+    }
     async getFreshPrice(symbol) {
         if (!this.priceRepository) {
             throw new exceptions_1.OracleError('TOKEN_PRICE_UNAVAILABLE', `No fresh price repository configured for ${symbol}`);
         }
-        const [price, observedAtMs] = await Promise.all([
-            this.priceRepository.getPrice(symbol),
-            this.priceRepository.getLastUpdateTimestamp(symbol),
-        ]);
-        const quote = (0, repositories_1.toPriceQuote)(price, observedAtMs);
+        const storedQuote = await this.priceRepository.getQuote(symbol);
+        const quote = (0, repositories_1.toPriceQuote)(storedQuote?.priceInEthWei, storedQuote?.observedAtMs);
         if (!quote) {
             throw new exceptions_1.OracleError('TOKEN_PRICE_UNAVAILABLE', `Price unavailable for ${symbol}`);
         }
         if (Date.now() - quote.observedAtMs > this.maxPriceAgeMs || quote.observedAtMs > Date.now() + 5_000) {
             throw new exceptions_1.OracleError('TOKEN_PRICE_STALE', `Price is stale for ${symbol}`);
         }
+        const bounds = this.priceBounds.get(symbol);
+        if (bounds &&
+            (quote.priceInEthWei < bounds.minimumWeiPerToken ||
+                quote.priceInEthWei > bounds.maximumWeiPerToken)) {
+            throw new exceptions_1.OracleError('TOKEN_PRICE_OUT_OF_RANGE', `Price is outside configured bounds for ${symbol}`);
+        }
         return quote;
     }
-    effectiveGasPrice(params) {
-        if (params.gasPrice) {
-            return BigInt(params.gasPrice);
-        }
-        if (params.baseFeePerGas && params.maxFeePerGas && params.maxPriorityFeePerGas) {
-            const maxFee = BigInt(params.maxFeePerGas);
-            const likelyEffective = BigInt(params.baseFeePerGas) + BigInt(params.maxPriorityFeePerGas);
-            return likelyEffective < maxFee ? likelyEffective : maxFee;
+    validatePriceBounds(configuredBounds) {
+        const validated = new Map();
+        for (const [rawSymbol, bounds] of Object.entries(configuredBounds)) {
+            const symbol = rawSymbol.trim().toLowerCase();
+            if (!this.currencyDecimals.has(symbol) ||
+                bounds.minimumWeiPerToken <= 0n ||
+                bounds.maximumWeiPerToken <= bounds.minimumWeiPerToken) {
+                throw new exceptions_1.OracleError('INVALID_CONFIG', `Invalid token price bounds for ${symbol}`);
+            }
+            validated.set(symbol, Object.freeze({ ...bounds }));
         }
-        throw new exceptions_1.OracleError('RPC_REQUEST_FAILED', 'Gas price response is incomplete');
+        return validated;
+    }
+    effectiveGasPrice(params) {
+        return BigInt(params.effectiveGasPriceWei);
     }
     assertTotalFee(totalFee, amount) {
-        if (totalFee < 0n || totalFee > amount) {
-            throw new exceptions_1.OracleError('ECONOMIC_LIMIT_EXCEEDED', 'Total fee must be between zero and withdrawal amount');
+        const maximumFee = (amount * BigInt(this.maxTotalFeeBps)) / BASIS_POINTS_SCALE;
+        if (totalFee <= 0n || totalFee > maximumFee) {
+            const maximumPercent = (this.maxTotalFeeBps / 100).toFixed(2);
+            throw new exceptions_1.OracleError('ECONOMIC_LIMIT_EXCEEDED', `Total fee must be greater than zero and no more than ${maximumPercent}% of the withdrawal amount`);
         }
     }
     normalizePurpose(purpose) {
+        if (typeof purpose !== 'string' || !GAS_PURPOSES.has(purpose)) {
+            throw new exceptions_1.OracleError('INVALID_INPUT', 'purpose is not supported');
+        }
         if (purpose === 'fee_quote' || purpose === 'fee_validation') {
             return 'fee';
         }
         return purpose;
     }
+    validateTxType(txType) {
+        if (typeof txType !== 'string' || !TX_TYPES.has(txType)) {
+            throw new exceptions_1.OracleError('INVALID_INPUT', 'txType is not supported');
+        }
+        return txType;
+    }
     result(input) {
         this.logger.debug('Withdrawal fee calculated', {
             priceSource: input.priceSource,
@@ -199,10 +270,12 @@ class MixerXFeeOracle {
             gasCost: input.gasCost,
             relayerFee: input.relayerFee,
             refundAmount: input.refundAmount,
+            refundWei: input.refundWei,
             totalFee: input.totalFee,
             currency: input.currency,
             gasLimit: input.gasLimit,
             gasPriceWei: input.gasPriceWei,
+            gasSource: input.gasParams.gasSource,
             baseFeePerGas: input.gasParams.baseFeePerGas,
             maxFeePerGas: input.gasParams.maxFeePerGas,
             maxPriorityFeePerGas: input.gasParams.maxPriorityFeePerGas,
@@ -217,4 +290,3 @@ class MixerXFeeOracle {
     }
 }
 exports.MixerXFeeOracle = MixerXFeeOracle;
-//# sourceMappingURL=MixerXFeeOracle.js.map

package/dist/infrastructure/multicall/MulticallProvider.d.ts

@@ -7,10 +7,14 @@ export interface CallResult {
     success: boolean;
     returnData: string;
 }
+export interface MulticallResult {
+    blockNumber: number;
+    results: CallResult[];
+}
 export declare class MulticallProvider {
     private readonly provider;
     private readonly multicall;
     private readonly chainId;
     constructor(rpcUrl: string, multicallAddress: string | undefined, chainId: ChainId | number, rpcTimeoutMs?: number);
-    aggregate(calls: readonly Call[]): Promise<CallResult[]>;
+    aggregate(calls: readonly Call[]): Promise<MulticallResult>;
 }

package/dist/infrastructure/multicall/MulticallProvider.js

@@ -15,7 +15,7 @@ class MulticallProvider {
     multicall;
     chainId;
     constructor(rpcUrl, multicallAddress = MULTICALL3_ADDRESS, chainId, rpcTimeoutMs) {
-        (0, gasOracleConfigs_1.assertSepoliaChainId)(chainId);
+        (0, gasOracleConfigs_1.assertSupportedChainId)(chainId);
         if (!ethers_1.ethers.isAddress(multicallAddress)) {
             throw new exceptions_1.OracleError('INVALID_CONFIG', 'multicallAddress must be a valid EVM address');
         }
@@ -28,7 +28,7 @@ class MulticallProvider {
             throw new exceptions_1.OracleError('INVALID_INPUT', `Multicall supports at most ${String(MAX_CALLS)} calls`);
         }
         if (calls.length === 0) {
-            return [];
+            return { blockNumber: await this.provider.getBlockNumber(), results: [] };
         }
         for (const call of calls) {
             if (!ethers_1.ethers.isAddress(call.target) || !ethers_1.ethers.isHexString(call.callData)) {
@@ -37,14 +37,18 @@ class MulticallProvider {
         }
         try {
             await (0, staticProvider_1.assertProviderNetwork)(this.provider, this.chainId);
-            const rawResults = (await this.multicall.aggregate3.staticCall(calls.map((call) => ({ ...call, allowFailure: true }))));
+            const blockNumber = await this.provider.getBlockNumber();
+            const rawResults = (await this.multicall.aggregate3.staticCall(calls.map((call) => ({ ...call, allowFailure: true })), { blockTag: blockNumber }));
             if (rawResults.length !== calls.length) {
                 throw new exceptions_1.OracleError('RPC_REQUEST_FAILED', 'Multicall returned an unexpected number of results');
             }
-            return rawResults.map((result) => ({
-                success: result.success,
-                returnData: result.returnData,
-            }));
+            return {
+                blockNumber,
+                results: rawResults.map((result) => ({
+                    success: result.success,
+                    returnData: result.returnData,
+                })),
+            };
         }
         catch (error) {
             if (error instanceof exceptions_1.OracleError) {
@@ -55,4 +59,3 @@ class MulticallProvider {
     }
 }
 exports.MulticallProvider = MulticallProvider;
-//# sourceMappingURL=MulticallProvider.js.map

package/dist/infrastructure/token-price/TokenPriceOracle.d.ts

@@ -1,15 +1,13 @@
 import type { ILogger } from '../../application/ports/ILogger';
-import type { ChainId, Token, TokenPrices } from '../../types';
+import type { ChainId, Token, TokenPriceSnapshot } from '../../types';
 export declare class TokenPriceOracle {
     private readonly multicall;
     private readonly offchainOracleAddress;
     private readonly interface;
     private readonly logger;
-    private defaultTokens;
+    private readonly defaultTokens;
     constructor(rpcUrl: string, chainId: ChainId | number, offchainOracleAddress?: string, multicallAddress?: string, tokens?: Token[], logger?: ILogger, rpcTimeoutMs?: number);
-    fetchPrices(tokens?: readonly Token[]): Promise<TokenPrices>;
-    fetchPrice(token: Token): Promise<string>;
+    fetchPrices(tokens?: readonly Token[]): Promise<TokenPriceSnapshot>;
     getSupportedTokens(): Token[];
-    addTokens(tokens: readonly Token[]): void;
     private normalizeTokens;
 }

package/dist/infrastructure/token-price/TokenPriceOracle.js

@@ -31,7 +31,7 @@ class TokenPriceOracle {
             target: this.offchainOracleAddress,
             callData: this.interface.encodeFunctionData('getRateToEth', [token.address, true]),
         }));
-        const results = await this.multicall.aggregate(calls);
+        const { blockNumber, results } = await this.multicall.aggregate(calls);
         const prices = Object.create(null);
         const failedSymbols = [];
         for (const [index, result] of results.entries()) {
@@ -57,18 +57,15 @@ class TokenPriceOracle {
             this.logger.warn('Token price batch rejected', { failedSymbols: [...failedSymbols] });
             throw new exceptions_1.TokenPriceError('One or more on-chain token prices are unavailable', failedSymbols);
         }
-        return { ...prices };
-    }
-    async fetchPrice(token) {
-        const prices = await this.fetchPrices([token]);
-        return prices[token.symbol.trim().toLowerCase()];
+        return Object.freeze({
+            prices: Object.freeze({ ...prices }),
+            observedAtMs: Date.now(),
+            blockNumber,
+        });
     }
     getSupportedTokens() {
         return this.defaultTokens.map((token) => ({ ...token }));
     }
-    addTokens(tokens) {
-        this.defaultTokens = this.normalizeTokens([...this.defaultTokens, ...tokens]);
-    }
     normalizeTokens(tokens) {
         if (tokens.length === 0) {
             throw new exceptions_1.OracleError('INVALID_CONFIG', `Token list must contain between 1 and ${String(MAX_TOKENS)} items`);
@@ -87,6 +84,11 @@ class TokenPriceOracle {
             if (symbols.has(symbol) && byAddress.get(address)?.symbol !== symbol) {
                 throw new exceptions_1.OracleError('INVALID_CONFIG', `Duplicate token symbol: ${symbol}`);
             }
+            const existingToken = byAddress.get(address);
+            if (existingToken &&
+                (existingToken.symbol !== symbol || existingToken.decimals !== token.decimals)) {
+                throw new exceptions_1.OracleError('INVALID_CONFIG', `Conflicting metadata for token address: ${address}`);
+            }
             symbols.add(symbol);
             byAddress.set(address, { address, symbol, decimals: token.decimals });
         }
@@ -97,4 +99,3 @@ class TokenPriceOracle {
     }
 }
 exports.TokenPriceOracle = TokenPriceOracle;
-//# sourceMappingURL=TokenPriceOracle.js.map

package/dist/types.d.ts

@@ -5,7 +5,12 @@ export interface Token {
     decimals: number;
 }
 export interface TokenPrices {
-    [symbol: string]: string;
+    readonly [symbol: string]: string;
+}
+export interface TokenPriceSnapshot {
+    readonly prices: TokenPrices;
+    readonly observedAtMs: number;
+    readonly blockNumber: number;
 }
 export interface TokenPriceQuote {
     priceInEthWei: bigint;

package/dist/types.js

@@ -1,3 +1,2 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-//# sourceMappingURL=types.js.map

package/package.json

@@ -1,9 +1,15 @@
 {
   "name": "@mixerx/oracles",
-  "version": "2.0.0",
-  "description": "Fail-closed Sepolia gas, token-price and withdrawal-fee policies for MixerX",
+  "version": "3.1.0",
+  "description": "Fail-closed Ethereum gas, token-price and withdrawal-fee policies for MixerX",
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    }
+  },
   "packageManager": "yarn@4.12.0",
   "files": [
     "dist/**/*"
@@ -39,7 +45,7 @@
     "access": "public"
   },
   "dependencies": {
-    "@mixerx/config": "0.5.4",
+    "@mixerx/config": "1.1.0",
     "ethers": "6.17.0"
   },
   "devDependencies": {
@@ -51,6 +57,6 @@
     "typescript-eslint": "8.48.1"
   },
   "engines": {
-    "node": ">=22.12.0"
+    "node": ">=24.12.0"
   }
-}
+}

package/dist/application/ports/ILogger.js.map

@@ -1 +0,0 @@
-{"version":3,"file":"ILogger.js","sourceRoot":"","sources":["../../../src/application/ports/ILogger.ts"],"names":[],"mappings":";;;AAMA,MAAa,UAAU;IACrB,KAAK,CAAC,QAAgB,EAAE,KAAe,IAAS,CAAC;IACjD,IAAI,CAAC,QAAgB,EAAE,KAAe,IAAS,CAAC;IAChD,KAAK,CAAC,QAAgB,EAAE,KAAe,IAAS,CAAC;CAClD;AAJD,gCAIC;AAED,MAAa,aAAa;IACK;IAA7B,YAA6B,QAAQ,gBAAgB;QAAxB,UAAK,GAAL,KAAK,CAAmB;IAAG,CAAC;IAEzD,KAAK,CAAC,OAAe,EAAE,IAAc;QACnC,OAAO,CAAC,KAAK,CAAC,IAAI,IAAI,CAAC,KAAK,KAAK,OAAO,EAAE,EAAE,IAAI,IAAI,EAAE,CAAC,CAAC;IAC1D,CAAC;IAED,IAAI,CAAC,OAAe,EAAE,IAAc;QAClC,OAAO,CAAC,IAAI,CAAC,IAAI,IAAI,CAAC,KAAK,KAAK,OAAO,EAAE,EAAE,IAAI,IAAI,EAAE,CAAC,CAAC;IACzD,CAAC;IAED,KAAK,CAAC,OAAe,EAAE,IAAc;QACnC,OAAO,CAAC,KAAK,CAAC,IAAI,IAAI,CAAC,KAAK,KAAK,OAAO,EAAE,EAAE,IAAI,IAAI,EAAE,CAAC,CAAC;IAC1D,CAAC;CACF;AAdD,sCAcC","sourcesContent":["export interface ILogger {\r\n  debug(message: string, meta?: unknown): void;\r\n  warn(message: string, meta?: unknown): void;\r\n  error(message: string, meta?: unknown): void;\r\n}\r\n\r\nexport class NullLogger implements ILogger {\r\n  debug(_message: string, _meta?: unknown): void {}\r\n  warn(_message: string, _meta?: unknown): void {}\r\n  error(_message: string, _meta?: unknown): void {}\r\n}\r\n\r\nexport class ConsoleLogger implements ILogger {\r\n  constructor(private readonly scope = 'mixerx-oracles') {}\r\n\r\n  debug(message: string, meta?: unknown): void {\r\n    console.debug(`[${this.scope}] ${message}`, meta ?? '');\r\n  }\r\n\r\n  warn(message: string, meta?: unknown): void {\r\n    console.warn(`[${this.scope}] ${message}`, meta ?? '');\r\n  }\r\n\r\n  error(message: string, meta?: unknown): void {\r\n    console.error(`[${this.scope}] ${message}`, meta ?? '');\r\n  }\r\n}\r\n"]}

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

@@ -1,5 +0,0 @@
-import type { Token, TokenPrices } from '../../types';
-export interface ITokenPriceFetcher {
-    fetchPrices(tokens?: Token[]): Promise<TokenPrices>;
-}
-export * from './ILogger';

package/dist/application/ports/index.js

@@ -1,18 +0,0 @@
-"use strict";
-var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
-    if (k2 === undefined) k2 = k;
-    var desc = Object.getOwnPropertyDescriptor(m, k);
-    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
-      desc = { enumerable: true, get: function() { return m[k]; } };
-    }
-    Object.defineProperty(o, k2, desc);
-}) : (function(o, m, k, k2) {
-    if (k2 === undefined) k2 = k;
-    o[k2] = m[k];
-}));
-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 });
-__exportStar(require("./ILogger"), exports);
-//# sourceMappingURL=index.js.map

package/dist/application/ports/index.js.map

@@ -1 +0,0 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/application/ports/index.ts"],"names":[],"mappings":";;;;;;;;;;;;;;;;AAMA,4CAA0B","sourcesContent":["import type { Token, TokenPrices } from '../../types';\r\n\r\nexport interface ITokenPriceFetcher {\r\n  fetchPrices(tokens?: Token[]): Promise<TokenPrices>;\r\n}\r\n\r\nexport * from './ILogger';\r\n"]}

package/dist/domain/config/TokenDefaults.js.map

@@ -1 +0,0 @@
-{"version":3,"file":"TokenDefaults.js","sourceRoot":"","sources":["../../../src/domain/config/TokenDefaults.ts"],"names":[],"mappings":";;AAMA,wCAGC;AATD,MAAM,gBAAgB,GAAgC,IAAI,GAAG,CAAC;IAC5D,CAAC,oBAAoB,EAAE,EAAE,CAAC;IAC1B,CAAC,iBAAiB,EAAE,EAAE,CAAC;IACvB,CAAC,6BAA6B,EAAE,CAAC,CAAC;CACnC,CAAC,CAAC;AAEH,SAAgB,cAAc,CAAC,MAAc;IAC3C,MAAM,GAAG,GAAG,MAAM,CAAC,IAAI,EAAE,CAAC,WAAW,EAAE,CAAC;IACxC,OAAO,gBAAgB,CAAC,GAAG,CAAC,GAAG,CAAC,IAAI,EAAE,CAAC;AACzC,CAAC","sourcesContent":["const BUMP_PERCENTAGES: ReadonlyMap<string, number> = new Map([\r\n  ['relayer_withdrawal', 10],\r\n  ['user_withdrawal', 30],\r\n  ['relayer_withdrawal_check_v4', 0],\r\n]);\r\n\r\nexport function getBumpPercent(txType: string): number {\r\n  const key = txType.trim().toLowerCase();\r\n  return BUMP_PERCENTAGES.get(key) ?? 10;\r\n}\r\n"]}

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

@@ -1 +0,0 @@
-export { getBumpPercent, } from './TokenDefaults';

package/dist/domain/config/index.js

@@ -1,8 +0,0 @@
-"use strict";
-// Domain configuration exports
-// Centralized defaults to eliminate duplication across the codebase
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.getBumpPercent = void 0;
-var TokenDefaults_1 = require("./TokenDefaults");
-Object.defineProperty(exports, "getBumpPercent", { enumerable: true, get: function () { return TokenDefaults_1.getBumpPercent; } });
-//# sourceMappingURL=index.js.map

package/dist/domain/config/index.js.map

@@ -1 +0,0 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/domain/config/index.ts"],"names":[],"mappings":";AAAA,+BAA+B;AAC/B,oEAAoE;;;AAEpE,iDAEyB;AADvB,+GAAA,cAAc,OAAA","sourcesContent":["// Domain configuration exports\r\n// Centralized defaults to eliminate duplication across the codebase\r\n\r\nexport {\r\n  getBumpPercent,\r\n} from './TokenDefaults';\r\n"]}

package/dist/domain/exceptions.js.map

@@ -1 +0,0 @@
-{"version":3,"file":"exceptions.js","sourceRoot":"","sources":["../../src/domain/exceptions.ts"],"names":[],"mappings":";;;AASA,MAAa,WAAY,SAAQ,KAAK;IAElB;IADlB,YACkB,IAAqB,EACrC,OAAe;QAEf,KAAK,CAAC,OAAO,CAAC,CAAC;QAHC,SAAI,GAAJ,IAAI,CAAiB;QAIrC,IAAI,CAAC,IAAI,GAAG,aAAa,CAAC;IAC5B,CAAC;CACF;AARD,kCAQC;AAED,MAAa,eAAgB,SAAQ,WAAW;IACD;IAA7C,YAAY,OAAe,EAAkB,UAA6B,EAAE;QAC1E,KAAK,CAAC,yBAAyB,EAAE,OAAO,CAAC,CAAC;QADC,YAAO,GAAP,OAAO,CAAwB;QAE1E,IAAI,CAAC,IAAI,GAAG,iBAAiB,CAAC;IAChC,CAAC;CACF;AALD,0CAKC","sourcesContent":["export type OracleErrorCode =\r\n  | 'INVALID_CONFIG'\r\n  | 'INVALID_INPUT'\r\n  | 'NETWORK_MISMATCH'\r\n  | 'RPC_REQUEST_FAILED'\r\n  | 'TOKEN_PRICE_UNAVAILABLE'\r\n  | 'TOKEN_PRICE_STALE'\r\n  | 'ECONOMIC_LIMIT_EXCEEDED';\r\n\r\nexport class OracleError extends Error {\r\n  constructor(\r\n    public readonly code: OracleErrorCode,\r\n    message: string,\r\n  ) {\r\n    super(message);\r\n    this.name = 'OracleError';\r\n  }\r\n}\r\n\r\nexport class TokenPriceError extends OracleError {\r\n  constructor(message: string, public readonly symbols: readonly string[] = []) {\r\n    super('TOKEN_PRICE_UNAVAILABLE', message);\r\n    this.name = 'TokenPriceError';\r\n  }\r\n}\r\n"]}

package/dist/domain/repositories.js.map

@@ -1 +0,0 @@
-{"version":3,"file":"repositories.js","sourceRoot":"","sources":["../../src/domain/repositories.ts"],"names":[],"mappings":";;AAOA,oCAaC;AAbD,SAAgB,YAAY,CAC1B,KAAgC,EAChC,YAAuC;IAEvC,IAAI,KAAK,KAAK,IAAI,IAAI,KAAK,KAAK,SAAS,IAAI,KAAK,IAAI,EAAE,EAAE,CAAC;QACzD,OAAO,IAAI,CAAC;IACd,CAAC;IAED,IAAI,CAAC,MAAM,CAAC,aAAa,CAAC,YAAY,CAAC,IAAI,CAAC,YAAY,IAAI,CAAC,CAAC,CAAC,GAAG,CAAC,EAAE,CAAC;QACpE,OAAO,IAAI,CAAC;IACd,CAAC;IAED,OAAO,EAAE,aAAa,EAAE,KAAK,EAAE,YAAY,EAAE,YAAsB,EAAE,MAAM,EAAE,YAAY,EAAE,CAAC;AAC9F,CAAC","sourcesContent":["import type { TokenPriceQuote } from '../types';\r\n\r\nexport interface ITokenPriceRepository {\r\n  getPrice(symbol: string): Promise<bigint | null | undefined>;\r\n  getLastUpdateTimestamp(symbol: string): Promise<number | null | undefined>;\r\n}\r\n\r\nexport function toPriceQuote(\r\n  price: bigint | null | undefined,\r\n  observedAtMs: number | null | undefined,\r\n): TokenPriceQuote | null {\r\n  if (price === null || price === undefined || price <= 0n) {\r\n    return null;\r\n  }\r\n\r\n  if (!Number.isSafeInteger(observedAtMs) || (observedAtMs ?? -1) < 0) {\r\n    return null;\r\n  }\r\n\r\n  return { priceInEthWei: price, observedAtMs: observedAtMs as number, source: 'repository' };\r\n}\r\n"]}

package/dist/factory.js.map

@@ -1 +0,0 @@
-{"version":3,"file":"factory.js","sourceRoot":"","sources":["../src/factory.ts"],"names":[],"mappings":";;AAmCA,8DAyCC;AA3ED,yDAAyD;AAEzD,wEAAqE;AACrE,6EAA0E;AAC1E,oFAAiF;AA8BjF,SAAgB,yBAAyB,CAAC,MAA2B;IACnE,MAAM,MAAM,GAAG,MAAM,CAAC,MAAM,IAAI,IAAI,oBAAU,EAAE,CAAC;IACjD,MAAM,cAAc,GAAG,IAAI,+BAAc,CAAC;QACxC,OAAO,EAAE,MAAM,CAAC,OAAO;QACvB,MAAM,EAAE,MAAM,CAAC,MAAM;QACrB,MAAM;QACN,iBAAiB,EAAE,MAAM,CAAC,iBAAiB;QAC3C,YAAY,EAAE,MAAM,CAAC,YAAY;QACjC,eAAe,EAAE,MAAM,CAAC,eAAe;KACxC,CAAC,CAAC;IACH,MAAM,gBAAgB,GAAG,IAAI,mCAAgB,CAC3C,MAAM,CAAC,MAAM,EACb,MAAM,CAAC,OAAO,EACd,MAAM,CAAC,qBAAqB,EAC5B,MAAM,CAAC,gBAAgB,EACvB,SAAS,EACT,MAAM,EACN,MAAM,CAAC,YAAY,CACpB,CAAC;IACF,MAAM,eAAe,GAAG,IAAI,iCAAe,CAAC;QAC1C,OAAO,EAAE,MAAM,CAAC,OAAO;QACvB,MAAM,EAAE,MAAM,CAAC,MAAM;QACrB,iBAAiB,EAAE,MAAM,CAAC,iBAAiB;QAC3C,cAAc;QACd,gBAAgB;QAChB,eAAe,EAAE,MAAM,CAAC,eAAe;QACvC,MAAM;QACN,YAAY,EAAE,MAAM,CAAC,YAAY;QACjC,eAAe,EAAE,MAAM,CAAC,eAAe;QACvC,aAAa,EAAE,MAAM,CAAC,aAAa;QACnC,YAAY,EAAE,MAAM,CAAC,YAAY;KAClC,CAAC,CAAC;IAEH,OAAO;QACL,cAAc;QACd,gBAAgB;QAChB,eAAe;QACf,OAAO,EAAE,MAAM,CAAC,OAAO;QACvB,WAAW,EAAE,GAAG,EAAE,CAAC,gBAAgB,CAAC,WAAW,EAAE;QACjD,WAAW,EAAE,GAAG,EAAE,CAAC,eAAe,CAAC,WAAW,EAAE;KACjD,CAAC;AACJ,CAAC","sourcesContent":["import type { ILogger } from './application/ports/ILogger';\r\nimport { NullLogger } from './application/ports/ILogger';\r\nimport type { ITokenPriceRepository } from './domain/repositories';\r\nimport { GasPriceOracle } from './infrastructure/gas/GasPriceOracle';\r\nimport { MixerXFeeOracle } from './infrastructure/mixerx/MixerXFeeOracle';\r\nimport { TokenPriceOracle } from './infrastructure/token-price/TokenPriceOracle';\r\nimport type { ChainId, TokenPrices } from './types';\r\n\r\nexport interface MixerxOraclesConfig {\r\n  chainId: ChainId;\r\n  rpcUrl: string;\r\n  relayerFeePercent: number;\r\n  priceRepository?: ITokenPriceRepository;\r\n  multicallAddress?: string;\r\n  offchainOracleAddress?: string;\r\n  logger?: ILogger;\r\n  rpcTimeoutMs?: number;\r\n  maxGasPriceGwei?: number;\r\n  maxPriceAgeMs?: number;\r\n  maxRefundWei?: bigint;\r\n  fallbackGasPrices?: {\r\n    legacy?: { instant: number; fast: number; standard: number; low: number };\r\n    eip1559?: { baseFee: number; maxFeePerGas: number; maxPriorityFeePerGas: number };\r\n  };\r\n}\r\n\r\nexport interface IMixerxOraclesModule {\r\n  gasPriceOracle: GasPriceOracle;\r\n  tokenPriceOracle: TokenPriceOracle;\r\n  mixerXFeeOracle: MixerXFeeOracle;\r\n  fetchPrices(): Promise<TokenPrices>;\r\n  assertReady(): Promise<void>;\r\n  chainId: ChainId;\r\n}\r\n\r\nexport function createMixerxOraclesModule(config: MixerxOraclesConfig): IMixerxOraclesModule {\r\n  const logger = config.logger ?? new NullLogger();\r\n  const gasPriceOracle = new GasPriceOracle({\r\n    chainId: config.chainId,\r\n    rpcUrl: config.rpcUrl,\r\n    logger,\r\n    fallbackGasPrices: config.fallbackGasPrices,\r\n    rpcTimeoutMs: config.rpcTimeoutMs,\r\n    maxGasPriceGwei: config.maxGasPriceGwei,\r\n  });\r\n  const tokenPriceOracle = new TokenPriceOracle(\r\n    config.rpcUrl,\r\n    config.chainId,\r\n    config.offchainOracleAddress,\r\n    config.multicallAddress,\r\n    undefined,\r\n    logger,\r\n    config.rpcTimeoutMs,\r\n  );\r\n  const mixerXFeeOracle = new MixerXFeeOracle({\r\n    chainId: config.chainId,\r\n    rpcUrl: config.rpcUrl,\r\n    relayerFeePercent: config.relayerFeePercent,\r\n    gasPriceOracle,\r\n    tokenPriceOracle,\r\n    priceRepository: config.priceRepository,\r\n    logger,\r\n    rpcTimeoutMs: config.rpcTimeoutMs,\r\n    maxGasPriceGwei: config.maxGasPriceGwei,\r\n    maxPriceAgeMs: config.maxPriceAgeMs,\r\n    maxRefundWei: config.maxRefundWei,\r\n  });\r\n\r\n  return {\r\n    gasPriceOracle,\r\n    tokenPriceOracle,\r\n    mixerXFeeOracle,\r\n    chainId: config.chainId,\r\n    fetchPrices: () => tokenPriceOracle.fetchPrices(),\r\n    assertReady: () => mixerXFeeOracle.assertReady(),\r\n  };\r\n}\r\n"]}

package/dist/index.js.map

@@ -1 +0,0 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":";;;;;;;;;;;;;;;;;AAAA,4CAA0B;AAC1B,kDAAmE;AAA1D,yGAAA,WAAW,OAAA;AAAE,6GAAA,eAAe,OAAA","sourcesContent":["export * from './factory';\r\nexport { OracleError, TokenPriceError } from './domain/exceptions';\r\nexport type { OracleErrorCode } from './domain/exceptions';\r\nexport type { ILogger } from './application/ports/ILogger';\r\nexport type { ITokenPriceRepository } from './domain/repositories';\r\nexport type {\r\n  FeeCalculationResult,\r\n  MixerXGasPurpose,\r\n  MixerXFeeCalculationResult,\r\n  MixerXGasParametersForTxResult,\r\n  MixerXTxType,\r\n  WithdrawalFeeInput,\r\n} from './infrastructure/mixerx/MixerXFeeOracle';\r\n"]}