@aztec/ethereum 0.0.1-commit.4d79d1f2d → 0.0.1-commit.4d9804df

package/src/config.ts

@@ -2,15 +2,15 @@ import {
   type ConfigMappingsType,
   bigintConfigHelper,
   booleanConfigHelper,
-  enumConfigHelper,
   getConfigFromMappings,
   getDefaultConfig,
   numberConfigHelper,
+  omitConfigMappings,
   optionalNumberConfigHelper,
 } from '@aztec/foundation/config';
 import { EthAddress } from '@aztec/foundation/eth-address';
+import l1ContractsDefaultEnv from '@aztec/l1-artifacts/network-defaults.json' with { type: 'json' };
 
-import { l1ContractsDefaultEnv } from './generated/l1-contracts-defaults.js';
 import { type L1TxUtilsConfig, l1TxUtilsConfigMappings } from './l1_tx_utils/config.js';
 
 export type GenesisStateConfig = {
@@ -18,6 +18,8 @@ export type GenesisStateConfig = {
   testAccounts: boolean;
   /** Whether to populate the genesis state with initial fee juice for the sponsored FPC */
   sponsoredFPC: boolean;
+  /** Additional addresses to prefund with fee juice at genesis */
+  prefundAddresses: string[];
 };
 
 export type L1ContractsConfig = {
@@ -57,13 +59,13 @@ export type L1ContractsConfig = {
   slashingOffsetInRounds: number;
   /** How long slashing can be disabled for in seconds when vetoer disables it */
   slashingDisableDuration: number;
-  /** Type of slasher proposer */
-  slasherFlavor: 'empire' | 'tally' | 'none';
-  /** Minimum amount that can be slashed in tally slashing */
+  /** Whether to deploy a slasher proposer */
+  slasherEnabled: boolean;
+  /** Minimum amount that can be slashed */
   slashAmountSmall: bigint;
-  /** Medium amount to slash in tally slashing */
+  /** Medium amount to slash */
   slashAmountMedium: bigint;
-  /** Largest amount that can be slashed per round in tally slashing */
+  /** Largest amount that can be slashed per round */
   slashAmountLarge: bigint;
   /** Governance proposing quorum (defaults to roundSize/2 + 1) */
   governanceProposerQuorum?: number;
@@ -79,11 +81,21 @@ export type L1ContractsConfig = {
   initialEthPerFeeAsset: bigint;
   /** The number of seconds to wait for an exit */
   exitDelaySeconds: number;
+  /** Validator set size at or below which the entry queue uses the bootstrap flush size. */
+  entryQueueBootstrapValidatorSetSize: number;
+  /** Number of validators admitted from the entry queue per flush during the bootstrap phase. */
+  entryQueueBootstrapFlushSize: number;
+  /** Minimum number of validators admitted from the entry queue per flush. */
+  entryQueueFlushSizeMin: number;
+  /** Divisor applied to the queue size to derive the normal per-flush admission count. */
+  entryQueueFlushSizeQuotient: number;
+  /** Maximum number of validators admitted from the entry queue per flush. */
+  entryQueueMaxFlushSize: number;
 } & L1TxUtilsConfig;
 
 /**
  * Config mappings for L1ContractsConfig.
- * Default values come from generated l1-contracts-defaults.json (source: defaults.yml).
+ * Default values come from l1-contracts/scripts/network-defaults.json (published via @aztec/l1-artifacts).
  * Real deployments use forge scripts which require explicit env vars (vm.envUint).
  */
 export const l1ContractsConfigMappings: ConfigMappingsType<L1ContractsConfig> = {
@@ -149,13 +161,10 @@ export const l1ContractsConfigMappings: ConfigMappingsType<L1ContractsConfig> =
       'How many slashing rounds back we slash (ie when slashing in round N, we slash for offenses committed during epochs of round N-offset)',
     ...numberConfigHelper(l1ContractsDefaultEnv.AZTEC_SLASHING_OFFSET_IN_ROUNDS),
   },
-  slasherFlavor: {
-    env: 'AZTEC_SLASHER_FLAVOR',
-    description: 'Type of slasher proposer (empire, tally, or none)',
-    ...enumConfigHelper(
-      ['empire', 'tally', 'none'] as const,
-      l1ContractsDefaultEnv.AZTEC_SLASHER_FLAVOR as 'empire' | 'tally' | 'none',
-    ),
+  slasherEnabled: {
+    env: 'AZTEC_SLASHER_ENABLED',
+    description: 'Whether to deploy a slasher proposer',
+    ...booleanConfigHelper(true),
   },
   slashAmountSmall: {
     env: 'AZTEC_SLASH_AMOUNT_SMALL',
@@ -238,15 +247,75 @@ export const l1ContractsConfigMappings: ConfigMappingsType<L1ContractsConfig> =
     description: 'The delay before a validator can exit the set',
     ...numberConfigHelper(l1ContractsDefaultEnv.AZTEC_EXIT_DELAY_SECONDS),
   },
-  ...l1TxUtilsConfigMappings,
+  entryQueueBootstrapValidatorSetSize: {
+    env: 'AZTEC_ENTRY_QUEUE_BOOTSTRAP_VALIDATOR_SET_SIZE',
+    description: 'Validator set size at or below which the entry queue uses the bootstrap flush size.',
+    ...numberConfigHelper(l1ContractsDefaultEnv.AZTEC_ENTRY_QUEUE_BOOTSTRAP_VALIDATOR_SET_SIZE),
+  },
+  entryQueueBootstrapFlushSize: {
+    env: 'AZTEC_ENTRY_QUEUE_BOOTSTRAP_FLUSH_SIZE',
+    description: 'Number of validators admitted from the entry queue per flush during the bootstrap phase.',
+    ...numberConfigHelper(l1ContractsDefaultEnv.AZTEC_ENTRY_QUEUE_BOOTSTRAP_FLUSH_SIZE),
+  },
+  entryQueueFlushSizeMin: {
+    env: 'AZTEC_ENTRY_QUEUE_FLUSH_SIZE_MIN',
+    description: 'Minimum number of validators admitted from the entry queue per flush.',
+    ...numberConfigHelper(l1ContractsDefaultEnv.AZTEC_ENTRY_QUEUE_FLUSH_SIZE_MIN),
+  },
+  entryQueueFlushSizeQuotient: {
+    env: 'AZTEC_ENTRY_QUEUE_FLUSH_SIZE_QUOTIENT',
+    description: 'Divisor applied to the queue size to derive the normal per-flush admission count.',
+    ...numberConfigHelper(l1ContractsDefaultEnv.AZTEC_ENTRY_QUEUE_FLUSH_SIZE_QUOTIENT),
+  },
+  entryQueueMaxFlushSize: {
+    env: 'AZTEC_ENTRY_QUEUE_MAX_FLUSH_SIZE',
+    description: 'Maximum number of validators admitted from the entry queue per flush.',
+    ...numberConfigHelper(l1ContractsDefaultEnv.AZTEC_ENTRY_QUEUE_MAX_FLUSH_SIZE),
+  },
+  ...omitConfigMappings(l1TxUtilsConfigMappings, ['ethereumSlotDuration']),
 };
 
 /**
  * Default L1 contracts configuration derived from l1ContractsConfigMappings.
- * Source of truth: spartan/environments/defaults.yml -> defaults.l1-contracts
+ * Source of truth: l1-contracts/scripts/network-defaults.json (published via @aztec/l1-artifacts).
  */
 export const DefaultL1ContractsConfig = getDefaultConfig(l1ContractsConfigMappings);
 
+/**
+ * Validates that `ethereumSlotDuration` and `aztecSlotDuration` are positive and that the L2 slot is an exact
+ * multiple of the L1 slot. Every L2 slot boundary must land on an L1 slot boundary; a non-multiple pairing
+ * desyncs the epoch/checkpoint timing math throughout the sequencer, validator client, and timetables. Returns
+ * a list of error messages (empty when valid).
+ */
+export function validateSlotDurations(
+  config: Pick<L1ContractsConfig, 'ethereumSlotDuration' | 'aztecSlotDuration'>,
+): string[] {
+  const errors: string[] = [];
+  if (config.ethereumSlotDuration <= 0) {
+    errors.push(`ethereumSlotDuration must be positive (got ${config.ethereumSlotDuration})`);
+  }
+  if (config.aztecSlotDuration <= 0) {
+    errors.push(`aztecSlotDuration must be positive (got ${config.aztecSlotDuration})`);
+  }
+  if (config.ethereumSlotDuration > 0 && config.aztecSlotDuration % config.ethereumSlotDuration !== 0) {
+    errors.push(
+      `aztecSlotDuration (${config.aztecSlotDuration}s) must be a multiple of ethereumSlotDuration ` +
+        `(${config.ethereumSlotDuration}s)`,
+    );
+  }
+  return errors;
+}
+
+/** Throws if {@link validateSlotDurations} reports any errors. */
+export function assertValidSlotDurations(
+  config: Pick<L1ContractsConfig, 'ethereumSlotDuration' | 'aztecSlotDuration'>,
+): void {
+  const errors = validateSlotDurations(config);
+  if (errors.length > 0) {
+    throw new Error(`Invalid slot duration configuration:\n${errors.map(e => `  - ${e}`).join('\n')}`);
+  }
+}
+
 export const genesisStateConfigMappings: ConfigMappingsType<GenesisStateConfig> = {
   testAccounts: {
     env: 'TEST_ACCOUNTS',
@@ -258,6 +327,16 @@ export const genesisStateConfigMappings: ConfigMappingsType<GenesisStateConfig>
     description: 'Whether to populate the genesis state with initial fee juice for the sponsored FPC.',
     ...booleanConfigHelper(false),
   },
+  prefundAddresses: {
+    env: 'PREFUND_ADDRESSES',
+    description: 'Comma-separated list of Aztec addresses to prefund with fee juice at genesis (local network only).',
+    parseEnv: (val: string) =>
+      val
+        .split(',')
+        .map(a => a.trim())
+        .filter(a => a.length > 0),
+    defaultValue: [],
+  },
 };
 
 export function getL1ContractsConfigEnvVars(): L1ContractsConfig {

package/src/contracts/chain_state_override.ts

@@ -0,0 +1,200 @@
+import { toHex as toPaddedHex } from '@aztec/foundation/bigint-buffer';
+import type { CheckpointNumber, SlotNumber } from '@aztec/foundation/branded-types';
+import type { Buffer32 } from '@aztec/foundation/buffer';
+import { merge } from '@aztec/foundation/collection';
+import type { Fr } from '@aztec/foundation/curves/bn254';
+
+import type { StateOverride } from 'viem';
+
+import { type FeeHeader, RollupContract } from './rollup.js';
+
+/**
+ * Override values for the pending checkpoint that the simulation should treat as already applied.
+ * Every field is optional at plan-building time so callers can populate them incrementally; whatever
+ * is present at translation time is forwarded to the partial `tempCheckpointLogs` helper so the
+ * load-bearing `slotNumber` can land even if other fields could not be derived locally.
+ */
+export type PendingCheckpointOverrideState = {
+  archive?: Fr;
+  feeHeader?: FeeHeader;
+  headerHash?: Fr;
+  outHash?: Fr;
+  payloadDigest?: Buffer32;
+  slotNumber?: SlotNumber;
+};
+
+export type ChainTipsOverride = {
+  pending?: CheckpointNumber;
+  proven?: CheckpointNumber;
+};
+
+/** Describes the simulated L1 rollup state that downstream calls should observe. */
+export type SimulationOverridesPlan = {
+  chainTipsOverride?: ChainTipsOverride;
+  pendingCheckpointState?: PendingCheckpointOverrideState;
+  disableBlobCheck?: boolean;
+};
+
+/** Builds a single-checkpoint simulation plan before it is translated into a viem state override. */
+export class SimulationOverridesBuilder {
+  private chainTipsOverride?: ChainTipsOverride;
+  private pendingCheckpointState?: PendingCheckpointOverrideState;
+  private disableBlobCheck = false;
+
+  /** Starts from an existing plan so callers can extend or specialize it. */
+  public static from(plan: SimulationOverridesPlan | undefined): SimulationOverridesBuilder {
+    return new SimulationOverridesBuilder().merge(plan);
+  }
+
+  /**
+   * Merges another plan into this builder. Later values win on a per-half basis for chain tips,
+   * but explicit `undefined` fields in the incoming plan are ignored so they cannot erase a
+   * previously-set value.
+   */
+  public merge(plan: SimulationOverridesPlan | undefined): this {
+    if (!plan) {
+      return this;
+    }
+
+    if (plan.chainTipsOverride) {
+      this.chainTipsOverride = merge(this.chainTipsOverride ?? {}, plan.chainTipsOverride);
+    }
+    if (plan.pendingCheckpointState) {
+      this.pendingCheckpointState = merge(this.pendingCheckpointState ?? {}, plan.pendingCheckpointState);
+    }
+    this.disableBlobCheck = this.disableBlobCheck || (plan.disableBlobCheck ?? false);
+
+    return this;
+  }
+
+  /**
+   * Sets the pending and/or proven checkpoint number overrides. Subsequent calls merge into the existing
+   * override on a per-half basis, so callers can set pending in one call and proven in another without
+   * clobbering each other.
+   */
+  public withChainTips(override: ChainTipsOverride): this {
+    this.chainTipsOverride = { ...(this.chainTipsOverride ?? {}), ...override };
+    return this;
+  }
+
+  /** Overrides the archive root for the configured pending checkpoint. */
+  public withPendingArchive(archive: Fr): this {
+    this.assertPendingCheckpointNumber();
+    this.pendingCheckpointState = { ...(this.pendingCheckpointState ?? {}), archive };
+    return this;
+  }
+
+  /** Overrides the fee header for the configured pending checkpoint. */
+  public withPendingFeeHeader(feeHeader: FeeHeader): this {
+    this.assertPendingCheckpointNumber();
+    this.pendingCheckpointState = { ...(this.pendingCheckpointState ?? {}), feeHeader };
+    return this;
+  }
+
+  /**
+   * Overrides one or more `tempCheckpointLogs` cell fields for the configured pending checkpoint.
+   * Fields are independent: any subset can be provided. The translator (`makeTempCheckpointLogOverride`)
+   * emits a stateDiff entry per field actually set, so unspecified fields stay at their on-chain
+   * values.
+   *
+   * `slotNumber` is load-bearing for `STFLib.canPruneAtTime`: when the simulation overrides `pending`
+   * to a checkpoint that has no on-chain `tempCheckpointLogs` entry yet, the missing slotNumber falls
+   * back to 0 and the contract treats the pending tip as belonging to epoch 0, triggering a phantom
+   * prune that silently undoes the `pending` override.
+   */
+  public withPendingTempCheckpointLogFields(fields: {
+    headerHash?: Fr;
+    outHash?: Fr;
+    payloadDigest?: Buffer32;
+    slotNumber?: SlotNumber;
+  }): this {
+    this.assertPendingCheckpointNumber();
+    this.pendingCheckpointState = { ...(this.pendingCheckpointState ?? {}), ...fields };
+    return this;
+  }
+
+  /** Disables blob checking for simulations that cannot provide DA inputs. */
+  public withoutBlobCheck(): this {
+    this.disableBlobCheck = true;
+    return this;
+  }
+
+  /** Builds the final plan, or `undefined` when no overrides were configured. */
+  public build(): SimulationOverridesPlan | undefined {
+    if (!this.pendingCheckpointState && !this.chainTipsOverride && !this.disableBlobCheck) {
+      return undefined;
+    }
+
+    return {
+      chainTipsOverride: this.chainTipsOverride,
+      pendingCheckpointState: this.pendingCheckpointState,
+      disableBlobCheck: this.disableBlobCheck || undefined,
+    };
+  }
+
+  private assertPendingCheckpointNumber(): void {
+    if (this.chainTipsOverride?.pending === undefined) {
+      throw new Error('withChainTips({ pending }) must be called before attaching archive or fee header overrides');
+    }
+  }
+}
+
+/** Translates a simulation plan into the viem state override shape expected by rollup calls. */
+export async function buildSimulationOverridesStateOverride(
+  rollup: RollupContract,
+  plan: SimulationOverridesPlan | undefined,
+): Promise<StateOverride> {
+  if (!plan) {
+    return [];
+  }
+
+  const rollupStateDiff: NonNullable<StateOverride[number]['stateDiff']> = [];
+
+  if (plan.chainTipsOverride) {
+    rollupStateDiff.push(...extractRollupStateDiff(await rollup.makeChainTipsOverride(plan.chainTipsOverride)));
+  }
+
+  if (plan.pendingCheckpointState && plan.chainTipsOverride?.pending === undefined) {
+    throw new Error('pendingCheckpointState requires chainTipsOverride.pending to be set');
+  }
+
+  if (plan.pendingCheckpointState?.archive) {
+    rollupStateDiff.push(
+      ...extractRollupStateDiff(
+        rollup.makeArchiveOverride(plan.chainTipsOverride!.pending!, plan.pendingCheckpointState.archive),
+      ),
+    );
+  }
+
+  if (plan.pendingCheckpointState) {
+    rollupStateDiff.push(
+      ...extractRollupStateDiff(
+        await rollup.makeTempCheckpointLogOverride(plan.chainTipsOverride!.pending!, {
+          headerHash: plan.pendingCheckpointState.headerHash,
+          outHash: plan.pendingCheckpointState.outHash,
+          payloadDigest: plan.pendingCheckpointState.payloadDigest,
+          slotNumber: plan.pendingCheckpointState.slotNumber,
+          feeHeader: plan.pendingCheckpointState.feeHeader,
+        }),
+      ),
+    );
+  }
+
+  if (plan.disableBlobCheck) {
+    rollupStateDiff.push({
+      slot: toPaddedHex(RollupContract.checkBlobStorageSlot, true),
+      value: toPaddedHex(0n, true),
+    });
+  }
+
+  if (rollupStateDiff.length === 0) {
+    return [];
+  }
+
+  return [{ address: rollup.address, stateDiff: rollupStateDiff }];
+}
+
+function extractRollupStateDiff(override: StateOverride | StateOverride[number] | undefined) {
+  const entries = Array.isArray(override) ? override : override ? [override] : [];
+  return entries.flatMap(entry => entry.stateDiff ?? []);
+}

package/src/contracts/fee_asset_price_oracle.ts

@@ -0,0 +1,285 @@
+import { memoize } from '@aztec/foundation/decorators';
+import { EthAddress } from '@aztec/foundation/eth-address';
+import { type Logger, createLogger } from '@aztec/foundation/log';
+
+import { type Hex, encodeAbiParameters, getContract, keccak256, parseAbiParameters } from 'viem';
+
+import type { ViemClient } from '../types.js';
+import { RollupContract } from './rollup.js';
+
+/** Maximum price modifier per checkpoint in basis points. ±100 bps = ±1% */
+export const MAX_FEE_ASSET_PRICE_MODIFIER_BPS = 100n;
+
+/**
+ * Validates that a fee asset price modifier is within the allowed range.
+ * Validators should call this before attesting to a checkpoint proposal.
+ *
+ * @param modifier - The fee asset price modifier in basis points
+ * @returns true if the modifier is valid (between -100 and +100 bps)
+ */
+export function validateFeeAssetPriceModifier(modifier: bigint): boolean {
+  return modifier >= -MAX_FEE_ASSET_PRICE_MODIFIER_BPS && modifier <= MAX_FEE_ASSET_PRICE_MODIFIER_BPS;
+}
+
+/**
+ * Oracle for computing fee asset price modifiers based on Uniswap V4 pool prices.
+ * Only active on Ethereum mainnet - returns 0 on other chains.
+ */
+export class FeeAssetPriceOracle {
+  constructor(
+    private client: ViemClient,
+    private readonly rollupContract: RollupContract,
+    private log: Logger = createLogger('fee-asset-price-oracle'),
+  ) {}
+
+  @memoize
+  async getUniswapOracle(): Promise<UniswapPriceOracle | undefined> {
+    const code = await this.client.getCode({ address: STATE_VIEW_ADDRESS.toString() });
+    if (code === undefined || code === '0x') {
+      this.log.warn('Uniswap V4 StateView contract not found, skipping fee asset price oracle');
+      return undefined;
+    }
+    this.log.info('Uniswap V4 StateView contract found, initializing fee asset price oracle');
+    const oracle = new UniswapPriceOracle(this.client, this.log);
+
+    try {
+      if (!(await oracle.isPoolInitialized())) {
+        this.log.warn('Uniswap V4 pool not initialized, skipping fee asset price oracle');
+        return undefined;
+      }
+    } catch (err) {
+      this.log.warn(`Failed to check if Uniswap V4 pool is initialized: ${err}`);
+      return undefined;
+    }
+
+    return oracle;
+  }
+
+  /**
+   * Computes the fee asset price modifier to be used in the next checkpoint proposal.
+   *
+   * The modifier adjusts the on-chain fee asset price toward the oracle price,
+   * clamped to ±1% (±100 basis points) per checkpoint.
+   *
+   * Returns 0 if not on mainnet or if the oracle query fails.
+   *
+   * @param currentPriceE12 - Optional override for the parent checkpoint's eth-per-fee-asset
+   *   (E12 scale). When omitted, the latest published value is read from L1. Pipelined
+   *   proposers should supply the predicted parent value so the modifier they emit aligns
+   *   with the parent fee header L1 will see when the previous pipelined checkpoint lands.
+   * @returns The price modifier in basis points (positive to increase price, negative to decrease)
+   */
+  async computePriceModifier(currentPriceE12?: bigint): Promise<bigint> {
+    const uniswapOracle = await this.getUniswapOracle();
+    if (!uniswapOracle) {
+      return 0n;
+    }
+
+    try {
+      // Get current on-chain price (ETH per fee asset, E12), preferring the caller-supplied value.
+      const resolvedCurrentPriceE12 = currentPriceE12 ?? (await this.rollupContract.getEthPerFeeAsset());
+
+      // Get oracle price (median of last N blocks, ETH per fee asset, E12)
+      const oraclePriceE12 = await uniswapOracle.getMeanEthPerFeeAssetE12();
+
+      // Compute modifier in basis points
+      const modifier = this.computePriceModifierBps(resolvedCurrentPriceE12, oraclePriceE12);
+
+      this.log.debug('Computed price modifier', {
+        currentPriceE12: resolvedCurrentPriceE12.toString(),
+        oraclePriceE12: oraclePriceE12.toString(),
+        modifierBps: modifier.toString(),
+        currentPriceFromCaller: currentPriceE12 !== undefined,
+      });
+
+      return modifier;
+    } catch (err) {
+      this.log.warn(`Failed to compute price modifier, using 0: ${err}`);
+      return 0n;
+    }
+  }
+
+  /**
+   * Gets the current oracle price (ETH per fee asset, scaled by 1e12).
+   * Returns undefined if not on mainnet or if the oracle query fails.
+   */
+  async getOraclePrice(): Promise<bigint | undefined> {
+    const uniswapOracle = await this.getUniswapOracle();
+    if (!uniswapOracle) {
+      return undefined;
+    }
+
+    try {
+      return await uniswapOracle.getMeanEthPerFeeAssetE12();
+    } catch (err) {
+      this.log.warn(`Failed to get oracle price: ${err}`);
+      return undefined;
+    }
+  }
+
+  /**
+   * Computes the basis points modifier needed to move from current price toward target price.
+   *
+   * @param currentPrice - Current ETH per fee asset (E12 scale)
+   * @param targetPrice - Target ETH per fee asset (E12 scale)
+   * @returns Basis points modifier clamped to ±100 (±1%)
+   */
+  computePriceModifierBps(currentPrice: bigint, targetPrice: bigint): bigint {
+    if (currentPrice === 0n) {
+      return MAX_FEE_ASSET_PRICE_MODIFIER_BPS;
+    }
+
+    // Calculate percentage difference in basis points
+    // modifierBps = ((targetPrice - currentPrice) / currentPrice) * 10000
+    const diff = targetPrice - currentPrice;
+    const rawModifierBps = (diff * 10_000n) / currentPrice;
+
+    // Clamp to ±MAX_FEE_ASSET_PRICE_MODIFIER_BPS
+    if (rawModifierBps > MAX_FEE_ASSET_PRICE_MODIFIER_BPS) {
+      return MAX_FEE_ASSET_PRICE_MODIFIER_BPS;
+    }
+    if (rawModifierBps < -MAX_FEE_ASSET_PRICE_MODIFIER_BPS) {
+      return -MAX_FEE_ASSET_PRICE_MODIFIER_BPS;
+    }
+    return rawModifierBps;
+  }
+}
+
+/** Mainnet Uniswap V4 StateView contract address */
+export const STATE_VIEW_ADDRESS = EthAddress.fromString('0x7ffe42c4a5deea5b0fec41c94c136cf115597227');
+
+const PRECISION_Q192 = 10n ** 12n * 2n ** 192n;
+
+/**
+ * Converts Uniswap's sqrtPriceX96 directly to ETH per FeeAsset (E12).
+ *
+ * For an ETH/FeeAsset pool where ETH is currency0 and FeeAsset is currency1:
+ * - Uniswap's sqrtPriceX96 = sqrt(FeeAsset/ETH) * 2^96
+ * - We need: ETH/FeeAsset with 1e12 precision
+ *
+ * Math:
+ *   price = (sqrtPriceX96 / 2^96)^2 = sqrtPriceX96^2 / 2^192  (FeeAsset per ETH)
+ *   ethPerFeeAsset = 1 / price = 2^192 / sqrtPriceX96^2
+ *   ethPerFeeAssetE12 = ethPerFeeAsset * 1e12 = 1e12 * 2^192 / sqrtPriceX96^2
+ */
+export function sqrtPriceX96ToEthPerFeeAssetE12(sqrtPriceX96: bigint): bigint {
+  if (sqrtPriceX96 === 0n) {
+    throw new Error('Cannot convert zero sqrtPriceX96');
+  }
+  return PRECISION_Q192 / (sqrtPriceX96 * sqrtPriceX96);
+}
+/**
+ * Uniswap V4 StateView ABI - only the functions we need
+ */
+const StateViewAbi = [
+  {
+    type: 'function',
+    name: 'getSlot0',
+    inputs: [{ name: 'poolId', type: 'bytes32', internalType: 'PoolId' }],
+    outputs: [
+      { name: 'sqrtPriceX96', type: 'uint160', internalType: 'uint160' },
+      { name: 'tick', type: 'int24', internalType: 'int24' },
+      { name: 'protocolFee', type: 'uint24', internalType: 'uint24' },
+      { name: 'lpFee', type: 'uint24', internalType: 'uint24' },
+    ],
+    stateMutability: 'view',
+  },
+] as const;
+
+/**
+ * Client for querying the ETH/FeeAsset price from Uniswap V4.
+ * Returns prices in ETH per FeeAsset format (E12) to match the rollup contract.
+ */
+class UniswapPriceOracle {
+  private readonly stateView;
+  private readonly poolId: Hex;
+  private readonly log: Logger;
+
+  constructor(
+    private readonly client: ViemClient,
+    log?: Logger,
+  ) {
+    this.log = log ?? createLogger('uniswap-price-oracle');
+    this.stateView = getContract({
+      address: STATE_VIEW_ADDRESS.toString(),
+      abi: StateViewAbi,
+      client,
+    });
+    this.poolId = this.computePoolId();
+    this.log.debug(`Initialized UniswapPriceOracle with poolId: ${this.poolId}`);
+  }
+
+  /**
+   * Computes the PoolId from the pool configuration by hashing its components.
+   * PoolId = keccak256(abi.encode(currency0, currency1, fee, tickSpacing, hooks))
+   * For mainnet, the value is expected to be: 0xce2899b16743cfd5a954d8122d5e07f410305b1aebee39fd73d9f3b9ebf10c2f
+   * Derived anyway to make it simpler to change if needed.
+   */
+  @memoize
+  computePoolId(): Hex {
+    /** ETH/FeeAsset pool configuration (hardcoded for mainnet) */
+    const encoded = encodeAbiParameters(parseAbiParameters('address, address, uint24, int24, address'), [
+      EthAddress.ZERO.toString(),
+      EthAddress.fromString('0xA27EC0006e59f245217Ff08CD52A7E8b169E62D2').toString(),
+      500, // 0.05%
+      10,
+      EthAddress.fromString('0xd53006d1e3110fD319a79AEEc4c527a0d265E080').toString(),
+    ]);
+    return keccak256(encoded);
+  }
+
+  async isPoolInitialized(): Promise<boolean> {
+    const [sqrtPriceX96] = await this.stateView.read.getSlot0([this.poolId], undefined);
+    return sqrtPriceX96 !== 0n;
+  }
+
+  /**
+   * Gets the price as ETH per FeeAsset, scaled by 1e12.
+   * This is the format expected by the rollup contract.
+   *
+   * @param blockNumber - Optional block number to query at (defaults to latest)
+   */
+  async getEthPerFeeAssetE12(blockNumber?: bigint): Promise<bigint> {
+    const [sqrtPriceX96] = await this.stateView.read.getSlot0(
+      [this.poolId],
+      blockNumber !== undefined ? { blockNumber } : undefined,
+    );
+    return sqrtPriceX96ToEthPerFeeAssetE12(sqrtPriceX96);
+  }
+
+  /**
+   * Gets the median price over the last N blocks as ETH per FeeAsset (E12).
+   * Using median helps protect against single-block manipulation.
+   *
+   * @param numBlocks - Number of recent blocks to sample (default: 5)
+   * @returns Median price as ETH per FeeAsset, scaled by 1e12
+   */
+  async getMeanEthPerFeeAssetE12(numBlocks: number = 5): Promise<bigint> {
+    const currentBlock = await this.client.getBlockNumber();
+    const prices: bigint[] = [];
+
+    for (let i = 0; i < numBlocks; i++) {
+      const blockNumber = currentBlock - BigInt(i);
+      if (blockNumber < 0n) {
+        break;
+      }
+
+      try {
+        const price = await this.getEthPerFeeAssetE12(blockNumber);
+        prices.push(price);
+      } catch (err) {
+        this.log.warn(`Failed to get price at block ${blockNumber}: ${err}`);
+        // Continue with fewer samples
+      }
+    }
+
+    const filteredPrices = prices.filter(price => price !== 0n);
+
+    if (filteredPrices.length === 0) {
+      throw new Error('Failed to get any price samples from Uniswap oracle');
+    }
+
+    const mean = filteredPrices.reduce((a, b) => a + b, 0n) / BigInt(filteredPrices.length);
+    return mean;
+  }
+}