@mixerx/oracles 3.0.0 → 3.1.0

package/README.md

@@ -1,59 +1,65 @@
-# MixerX Oracles
-
-Fail-closed Sepolia pricing and gas policy for MixerX. Version 3.0.0 rejects a
+# MixerX Oracles
+
+Fail-closed Ethereum pricing and gas policy for MixerX. Version 3.1.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.
+
+## Security contract
+
+- Ethereum mainnet (`1`) and Sepolia (`11155111`) are accepted, as defined by
+  `@mixerx/config`. A fork must report a supported chain ID.
+- 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@3.0.0
-```
-
+- 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 selected network's 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.
+
+Mainnet addresses in Config 1.1.0 are provisional copies of Sepolia. Accepting
+chain ID `1` only enables backend configuration; it does not establish that
+contracts or oracle rates exist. Readiness and pricing still fail when required
+on-chain data is absent or the RPC reports another chain.
+
+## Installation
+
+```bash
+yarn add @mixerx/oracles@3.1.0
+```
+
 Node.js 24.12.0 or newer is required.
-
-## Usage
-
-```ts
-import {
-  createMixerxOraclesModule,
-  type ITokenPriceRepository,
-} from '@mixerx/oracles';
-
+
+## Usage
+
+```ts
+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,
+
+const oracles = createMixerxOraclesModule({
+  chainId: 11155111,
+  rpcUrl: process.env.SEPOLIA_RPC_URL!,
+  relayerFeePercent: 0.004,
+  priceRepository,
   maxGasPriceGwei: 100,
   maxPriceAgeMs: 120_000,
   maxTotalFeeBps: 1_000,
@@ -63,56 +69,56 @@ const oracles = createMixerxOraclesModule({
       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,
+});
+
+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
+```
+
+`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 tokens configured for the selected network 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
-
-```bash
-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`.
+
+The default Multicall3 address is
+`0xcA11bde05977b3631167028862bE2a173976CA11`; an explicit verified address can
+be supplied with `multicallAddress`.
+
+## Development
+
+```bash
+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`.

package/dist/infrastructure/blockchain/staticProvider.js

@@ -7,7 +7,7 @@ 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);
+    (0, gasOracleConfigs_1.assertSupportedChainId)(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');

package/dist/infrastructure/config/ProtocolTokenConfig.js

@@ -7,7 +7,7 @@ const exceptions_1 = require("../../domain/exceptions");
 const gasOracleConfigs_1 = require("./gasOracleConfigs");
 function toSupportedChainId(chainId) {
     const numericChainId = Number(chainId);
-    (0, gasOracleConfigs_1.assertSepoliaChainId)(numericChainId);
+    (0, gasOracleConfigs_1.assertSupportedChainId)(numericChainId);
     if (!(0, config_1.isSupportedNetId)(numericChainId)) {
         throw new exceptions_1.OracleError('INVALID_CONFIG', `Unsupported chainId ${chainId} for @mixerx/config`);
     }

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

@@ -1,3 +1,2 @@
 export type ChainId = number;
-export declare const SEPOLIA_CHAIN_ID = 11155111;
-export declare function assertSepoliaChainId(chainId: number): void;
+export declare function assertSupportedChainId(chainId: number): void;

package/dist/infrastructure/config/gasOracleConfigs.js

@@ -1,11 +1,10 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.SEPOLIA_CHAIN_ID = void 0;
-exports.assertSepoliaChainId = assertSepoliaChainId;
+exports.assertSupportedChainId = assertSupportedChainId;
+const config_1 = require("@mixerx/config");
 const exceptions_1 = require("../../domain/exceptions");
-exports.SEPOLIA_CHAIN_ID = 11_155_111;
-function assertSepoliaChainId(chainId) {
-    if (chainId !== exports.SEPOLIA_CHAIN_ID) {
-        throw new exceptions_1.OracleError('INVALID_CONFIG', `Unsupported chainId ${String(chainId)}; @mixerx/oracles is Sepolia-only`);
+function assertSupportedChainId(chainId) {
+    if (!(0, config_1.isSupportedNetId)(chainId)) {
+        throw new exceptions_1.OracleError('INVALID_CONFIG', `Unsupported chainId ${String(chainId)}; supported networks: ${config_1.SUPPORTED_NET_IDS.join(', ')}`);
     }
 }

package/dist/infrastructure/mixerx/MixerXFeeOracle.js

@@ -38,7 +38,7 @@ class MixerXFeeOracle {
     currencyDecimals;
     priceBounds;
     constructor(options) {
-        (0, gasOracleConfigs_1.assertSepoliaChainId)(options.chainId);
+        (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');
         }

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');
         }

package/package.json

@@ -1,62 +1,62 @@
-{
-  "name": "@mixerx/oracles",
-  "version": "3.0.0",
-  "description": "Fail-closed Sepolia 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/**/*"
-  ],
-  "scripts": {
-    "build": "yarn clean && tsc",
-    "clean": "node -e \"require('node:fs').rmSync('dist', { recursive: true, force: true })\"",
-    "typecheck": "tsc --noEmit",
-    "lint": "eslint src tests",
-    "test": "yarn build && node --test \"tests/**/*.test.cjs\"",
-    "validate": "yarn typecheck && yarn lint && yarn test",
-    "prepack": "yarn build",
-    "prepublish": "yarn validate"
-  },
-  "keywords": [
-    "mixerx",
-    "ethereum",
-    "gas",
-    "oracle",
-    "fees"
-  ],
-  "author": "MixerX Contributors",
-  "license": "GPL-3.0-only",
-  "repository": {
-    "type": "git",
-    "url": "git+https://github.com/zkusd-mixerx/mixerx-oracles.git"
-  },
-  "bugs": {
-    "url": "https://github.com/zkusd-mixerx/mixerx-oracles/issues"
-  },
-  "homepage": "https://github.com/zkusd-mixerx/mixerx-oracles#readme",
-  "publishConfig": {
-    "access": "public"
-  },
-  "dependencies": {
-    "@mixerx/config": "1.0.0",
-    "ethers": "6.17.0"
-  },
-  "devDependencies": {
-    "@eslint/js": "9.39.1",
-    "@types/node": "24.10.1",
-    "eslint": "9.39.1",
-    "globals": "16.5.0",
-    "typescript": "5.9.3",
-    "typescript-eslint": "8.48.1"
-  },
-  "engines": {
-    "node": ">=24.12.0"
-  }
-}
+{
+  "name": "@mixerx/oracles",
+  "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/**/*"
+  ],
+  "scripts": {
+    "build": "yarn clean && tsc",
+    "clean": "node -e \"require('node:fs').rmSync('dist', { recursive: true, force: true })\"",
+    "typecheck": "tsc --noEmit",
+    "lint": "eslint src tests",
+    "test": "yarn build && node --test \"tests/**/*.test.cjs\"",
+    "validate": "yarn typecheck && yarn lint && yarn test",
+    "prepack": "yarn build",
+    "prepublish": "yarn validate"
+  },
+  "keywords": [
+    "mixerx",
+    "ethereum",
+    "gas",
+    "oracle",
+    "fees"
+  ],
+  "author": "MixerX Contributors",
+  "license": "GPL-3.0-only",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/zkusd-mixerx/mixerx-oracles.git"
+  },
+  "bugs": {
+    "url": "https://github.com/zkusd-mixerx/mixerx-oracles/issues"
+  },
+  "homepage": "https://github.com/zkusd-mixerx/mixerx-oracles#readme",
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "@mixerx/config": "1.1.0",
+    "ethers": "6.17.0"
+  },
+  "devDependencies": {
+    "@eslint/js": "9.39.1",
+    "@types/node": "24.10.1",
+    "eslint": "9.39.1",
+    "globals": "16.5.0",
+    "typescript": "5.9.3",
+    "typescript-eslint": "8.48.1"
+  },
+  "engines": {
+    "node": ">=24.12.0"
+  }
+}