MixerX Oracles

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

yarn add @mixerx/[email protected]

Node.js 24.12.0 or newer is required.

Usage

import {
  createMixerxOraclesModule,
  type ITokenPriceRepository,
} from '@mixerx/oracles';

const priceRepository: ITokenPriceRepository = {
  getQuote: async (symbol) => readCachedQuote(symbol),
};

const oracles = createMixerxOraclesModule({
  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,
    },
  },
});

await oracles.assertReady();

const fee = await oracles.mixerXFeeOracle.calculateWithdrawalFee({
  currency: 'fds',
  amount: 1_000_000_000_000_000_000n,
  decimals: 18,
  gasLimit: estimatedWithdrawalGas,
  refund: '0',
  purpose: 'fee',
});

console.log({
  totalFee: fee.totalFee,
  tokenPriceInEth: fee.tokenPriceInEth,
  priceSource: fee.priceSource,
  priceObservedAtMs: fee.priceObservedAtMs,
  baseFeePerGas: fee.baseFeePerGas,
  effectiveGasPriceWei: fee.gasPriceWei,
  gasSource: fee.gasSource,
});

fee_quote and fee_validation remain accepted as input aliases for migration, but both normalize to the single fee policy in returned data.

Price-feed operation

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.

The default Multicall3 address is 0xcA11bde05977b3631167028862bE2a173976CA11; an explicit verified address can be supplied with multicallAddress.

Development

yarn install --immutable
yarn validate
yarn npm audit --all --recursive --severity high

CI executes those gates for every pull request. Published packages pin the protocol configuration dependency exactly.

License

GPL-3.0-only. See LICENSE.