@valve-tech/gas-oracle 0.2.0

package/dist/viem-transport.js

@@ -0,0 +1,165 @@
+/**
+ * @valve-tech/gas-oracle/viem-transport — viem Transport wrapper.
+ *
+ * Use when callers want viem's existing API to *just work better*
+ * without changing call-site code:
+ *
+ *   const transport = withGasOracle(http(rpcUrl), {
+ *     chainId: 1,
+ *     priorityFeeDecayCap: parseEther('0.125'),
+ *     priorityModel: 'eip1559',
+ *     intercept: { eth_maxPriorityFeePerGas: 'fast' },
+ *   })
+ *   const client = createPublicClient({ chain: mainnet, transport })
+ *
+ *   // Standard viem APIs now reach the oracle cache instead of upstream:
+ *   await client.estimateMaxPriorityFeePerGas()
+ *   await walletClient.sendTransaction({ ... })  // gas auto-fill is corrected
+ *
+ * Default `intercept` is `{ eth_gasFeeEstimate: true }` only — the
+ * additive method that returns the full tier shape. Standard methods
+ * (`eth_gasPrice`, `eth_maxPriorityFeePerGas`) pass through to upstream
+ * unless the caller opts in AND specifies which tier to map them to.
+ * Forcing the tier choice keeps the package out of the silently-pick-a-
+ * percentile foot-gun the relay's gas-intercept caught earlier (one
+ * customer's eth_gasPrice and another's eth_maxPriorityFeePerGas
+ * returning numbers 5x apart because each defaulted to a different
+ * percentile).
+ *
+ * `eth_feeHistory` is intentionally NOT in the intercept options.
+ * Synthesizing the historical-percentile array from oracle state is
+ * its own design problem; passthrough is the only honest answer in v0.2.
+ */
+import { custom } from 'viem';
+import { createGasOracle } from './oracle.js';
+/**
+ * Sentinel returned by `dispatchIntercept` when no intercept matched
+ * and the request should be passed through to the inner transport.
+ * Using a unique symbol avoids any chance of ambiguity with a real
+ * RPC result that happens to be `null` or `undefined`.
+ */
+const PASSTHROUGH = Symbol('gas-oracle:passthrough');
+const toHex = (n) => '0x' + n.toString(16);
+const TIER_NAMES = ['instant', 'fast', 'standard', 'slow'];
+/**
+ * Format a single tier for the `eth_gasFeeEstimate` response, scoped
+ * to the requested tx type. Mirrors the relay's `gas-intercept.ts`
+ * formatter so consumers of either surface get identical wire shapes.
+ */
+const formatTier = (tier, txType) => {
+    if (txType === 0 || txType === 1) {
+        return { gasPrice: toHex(tier.gasPrice) };
+    }
+    if (txType === 2 || txType === 4) {
+        return {
+            maxFeePerGas: toHex(tier.maxFeePerGas),
+            maxPriorityFeePerGas: toHex(tier.maxPriorityFeePerGas),
+        };
+    }
+    if (txType === 3) {
+        return {
+            maxFeePerGas: toHex(tier.maxFeePerGas),
+            maxPriorityFeePerGas: toHex(tier.maxPriorityFeePerGas),
+            maxFeePerBlobGas: toHex(tier.maxFeePerBlobGas ?? 0n),
+        };
+    }
+    // No type → include everything available
+    const out = {
+        gasPrice: toHex(tier.gasPrice),
+        maxFeePerGas: toHex(tier.maxFeePerGas),
+        maxPriorityFeePerGas: toHex(tier.maxPriorityFeePerGas),
+    };
+    if (tier.maxFeePerBlobGas !== null) {
+        out.maxFeePerBlobGas = toHex(tier.maxFeePerBlobGas);
+    }
+    return out;
+};
+const buildGasFeeEstimate = (state, params) => {
+    const txType = typeof params[0] === 'number' ? params[0] : undefined;
+    const tiers = {};
+    for (const name of TIER_NAMES) {
+        tiers[name] = formatTier(state.tiers[name], txType);
+    }
+    const out = {
+        baseFee: toHex(state.baseFee),
+        baseFeeTrend: state.baseFeeTrend,
+        blockNumber: toHex(state.blockNumber),
+        lastUpdated: toHex(state.timestamp),
+        mempoolPendingCount: state.mempool.pendingCount,
+        tiers,
+    };
+    if (state.blob)
+        out.blobBaseFee = toHex(state.blob.blobBaseFee);
+    return out;
+};
+/**
+ * Decide whether the requested method should be answered from oracle
+ * state or passed through. Returns the response value, or PASSTHROUGH
+ * when the method either isn't in the intercept config or the oracle
+ * has no state yet (cold-start fallback to upstream).
+ */
+const dispatchIntercept = async (args, oracle, intercept) => {
+    const params = args.params ?? [];
+    if (args.method === 'eth_gasFeeEstimate' && intercept.eth_gasFeeEstimate !== false) {
+        const state = oracle.getState() ?? (await oracle.pollOnce());
+        if (!state)
+            return PASSTHROUGH;
+        return buildGasFeeEstimate(state, params);
+    }
+    if (args.method === 'eth_gasPrice') {
+        const tier = intercept.eth_gasPrice;
+        if (tier === undefined || tier === false)
+            return PASSTHROUGH;
+        const state = oracle.getState() ?? (await oracle.pollOnce());
+        if (!state)
+            return PASSTHROUGH;
+        return toHex(state.tiers[tier].gasPrice);
+    }
+    if (args.method === 'eth_maxPriorityFeePerGas') {
+        const tier = intercept.eth_maxPriorityFeePerGas;
+        if (tier === undefined || tier === false)
+            return PASSTHROUGH;
+        const state = oracle.getState() ?? (await oracle.pollOnce());
+        if (!state)
+            return PASSTHROUGH;
+        return toHex(state.tiers[tier].maxPriorityFeePerGas);
+    }
+    return PASSTHROUGH;
+};
+/**
+ * Wrap an existing viem Transport with gas-oracle interception.
+ *
+ * The returned value is a Transport (drops into `createPublicClient({
+ * transport })` directly) plus a `stopGasOracle()` handle for shutdown
+ * hooks (HMR, test teardown). The oracle is constructed once per
+ * `withGasOracle` call — a single Transport instance is shared with
+ * the oracle's poll loop, so wrapping `http(url)` once produces one
+ * oracle and one stream of upstream RPC, regardless of how many
+ * clients consume the transport downstream.
+ */
+export const withGasOracle = (innerTransport, options) => {
+    const intercept = {
+        eth_gasFeeEstimate: true,
+        ...options.intercept,
+    };
+    // Pull a TransportInstance for the oracle's own RPC fan-out. http() and
+    // most built-in transports don't require a chain config for request
+    // dispatch — chainId validation happens elsewhere.
+    const oracleInner = innerTransport({});
+    const oracleClient = { request: oracleInner.request };
+    const oracle = createGasOracle({ ...options, client: oracleClient });
+    if ((options.lifecycle ?? 'eager') === 'eager')
+        oracle.start();
+    const wrapped = custom({
+        request: async (args) => {
+            const result = await dispatchIntercept(args, oracle, intercept);
+            if (result !== PASSTHROUGH)
+                return result;
+            // Reuse the inner transport-instance the oracle already opened
+            // so we don't double-instantiate the http transport per client.
+            return oracleInner.request({ method: args.method, params: args.params });
+        },
+    });
+    return Object.assign(wrapped, { stopGasOracle: () => oracle.stop() });
+};
+//# sourceMappingURL=viem-transport.js.map

package/dist/viem-transport.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"viem-transport.js","sourceRoot":"","sources":["../src/viem-transport.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -0,0 +1,81 @@
+{
+  "name": "@valve-tech/gas-oracle",
+  "version": "0.2.0",
+  "description": "Multi-tier gas-fee oracle for EVM chains. Computes slow/standard/fast/instant tier recommendations from block-included tips, mempool pending tips, and base-fee trend, with a configurable downside-decay cap and a chain-aware EIP-1559 priority cutoff. viem-native — pass it a PublicClient and it does the rest. Ships viem-actions and viem-transport subpaths for drop-in client extension and transport-wrapping.",
+  "license": "MIT",
+  "homepage": "https://github.com/valve-tech/gas-oracle#readme",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/valve-tech/gas-oracle.git"
+  },
+  "bugs": {
+    "url": "https://github.com/valve-tech/gas-oracle/issues"
+  },
+  "keywords": [
+    "ethereum",
+    "evm",
+    "gas",
+    "gas-oracle",
+    "gas-price",
+    "eip-1559",
+    "fee-market",
+    "viem",
+    "mempool"
+  ],
+  "type": "module",
+  "packageManager": "yarn@4.14.1",
+  "main": "src/index.ts",
+  "types": "src/index.ts",
+  "exports": {
+    ".": {
+      "types": "./src/index.ts",
+      "import": "./src/index.ts"
+    },
+    "./viem-actions": {
+      "types": "./src/viem-actions.ts",
+      "import": "./src/viem-actions.ts"
+    },
+    "./viem-transport": {
+      "types": "./src/viem-transport.ts",
+      "import": "./src/viem-transport.ts"
+    }
+  },
+  "publishConfig": {
+    "main": "dist/index.js",
+    "types": "dist/index.d.ts",
+    "exports": {
+      ".": {
+        "types": "./dist/index.d.ts",
+        "import": "./dist/index.js"
+      },
+      "./viem-actions": {
+        "types": "./dist/viem-actions.d.ts",
+        "import": "./dist/viem-actions.js"
+      },
+      "./viem-transport": {
+        "types": "./dist/viem-transport.d.ts",
+        "import": "./dist/viem-transport.js"
+      }
+    }
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "build": "tsc -p .",
+    "typecheck": "tsc -p . --noEmit",
+    "test": "vitest run",
+    "test:watch": "vitest"
+  },
+  "peerDependencies": {
+    "viem": "^2.0.0"
+  },
+  "devDependencies": {
+    "@types/node": "^22.0.0",
+    "typescript": "^6.0.2",
+    "viem": "^2.21.0",
+    "vitest": "^4.1.4"
+  }
+}

package/src/index.ts

@@ -0,0 +1,84 @@
+/**
+ * @valve-tech/gas-oracle — public API.
+ *
+ * Multi-tier gas-fee oracle for EVM chains. Pass it a viem PublicClient
+ * and it polls block + mempool data, computes slow/standard/fast/instant
+ * tier recommendations, and exposes them via a sub-millisecond in-memory
+ * read. Includes EIP-1559-style 12.5%/block downside cap so quiet blocks
+ * don't drop the published number off a cliff, and EIP-4844 blob fee
+ * for chains that support it.
+ *
+ * Zero runtime dependencies. viem is the only peer dependency, used to
+ * issue the underlying RPC calls (`eth_feeHistory`,
+ * `eth_getBlockByNumber`, `txpool_content`).
+ */
+
+export {
+  createGasOracle,
+  reducePollInputs,
+  type CreateGasOracleOptions,
+  type GasOracle,
+} from './oracle.js'
+
+export {
+  effectiveTip,
+  computePercentiles,
+  detectTrend,
+  cappedTip,
+  computeTiers,
+  computeBlobBaseFee,
+  flattenTxPool,
+  gasWeightedPercentiles,
+  sortedTips,
+  DEFAULT_PRIORITY_FEE_DECAY_CAP,
+  DEFAULT_BASE_FEE_LIVENESS_BLOCKS,
+} from './math.js'
+
+export {
+  blockToSample,
+  mempoolToSamples,
+} from './samples.js'
+
+export {
+  fetchOracleInputs,
+  type FeeHistoryResult,
+  type BlockResult,
+  type TxPoolContent,
+  type OraclePollInputs,
+} from './transport.js'
+
+export type {
+  RawTx,
+  TipPercentiles,
+  TierRecommendation,
+  TierName,
+  Trend,
+  MempoolStats,
+  BlobStats,
+  BlockSample,
+  GasOracleState,
+  TipSample,
+  PriorityModel,
+  PollOptions,
+} from './types.js'
+
+// Mempool inspection
+export {
+  normalizeMempool,
+  findByHash,
+  findByAddressNonce,
+  findInMempool,
+} from './mempool.js'
+export type {
+  NormalizedMempool,
+  TxIdentifier,
+  MempoolBucket,
+  MempoolHit,
+} from './mempool.js'
+
+// Block-position calculations
+export { tipForBlockPosition } from './block-position.js'
+export type {
+  BlockPositionQuery,
+  BlockPositionResult,
+} from './block-position.js'