@aztec/node-lib 4.0.0-nightly.20250907 → 4.0.0-nightly.20260108

package/src/actions/snapshot-sync.ts

@@ -1,6 +1,6 @@
 import { ARCHIVER_DB_VERSION, ARCHIVER_STORE_NAME, type ArchiverConfig, createArchiverStore } from '@aztec/archiver';
 import { INITIAL_L2_BLOCK_NUM } from '@aztec/constants';
-import { type EthereumClientConfig, getPublicClient } from '@aztec/ethereum';
+import { type EthereumClientConfig, getPublicClient } from '@aztec/ethereum/client';
 import type { EthAddress } from '@aztec/foundation/eth-address';
 import { tryRmDir } from '@aztec/foundation/fs';
 import type { Logger } from '@aztec/foundation/log';
@@ -26,11 +26,12 @@ import type { SharedNodeConfig } from '../config/index.js';
 // Half day worth of L1 blocks
 const MIN_L1_BLOCKS_TO_TRIGGER_REPLACE = 86400 / 2 / 12;
 
-type SnapshotSyncConfig = Pick<SharedNodeConfig, 'syncMode' | 'snapshotsUrl'> &
+type SnapshotSyncConfig = Pick<SharedNodeConfig, 'syncMode'> &
   Pick<ChainConfig, 'l1ChainId' | 'rollupVersion'> &
   Pick<ArchiverConfig, 'archiverStoreMapSizeKb' | 'maxLogs'> &
   Required<DataStoreConfig> &
   EthereumClientConfig & {
+    snapshotsUrls?: string[];
     minL1BlocksToTriggerReplace?: number;
   };
 
@@ -39,14 +40,14 @@ type SnapshotSyncConfig = Pick<SharedNodeConfig, 'syncMode' | 'snapshotsUrl'> &
  * Behaviour depends on syncing mode.
  */
 export async function trySnapshotSync(config: SnapshotSyncConfig, log: Logger) {
-  const { syncMode, snapshotsUrl, dataDirectory, l1ChainId, rollupVersion, l1Contracts } = config;
+  const { syncMode, snapshotsUrls, dataDirectory, l1ChainId, rollupVersion, l1Contracts } = config;
   if (syncMode === 'full') {
     log.debug('Snapshot sync is disabled. Running full sync.', { syncMode: syncMode });
     return false;
   }
 
-  if (!snapshotsUrl) {
-    log.verbose('Snapshot sync is disabled. No snapshots URL provided.');
+  if (!snapshotsUrls || snapshotsUrls.length === 0) {
+    log.verbose('Snapshot sync is disabled. No snapshots URLs provided.');
     return false;
   }
 
@@ -55,15 +56,7 @@ export async function trySnapshotSync(config: SnapshotSyncConfig, log: Logger) {
     return false;
   }
 
-  let fileStore: ReadOnlyFileStore;
-  try {
-    fileStore = await createReadOnlyFileStore(snapshotsUrl, log);
-  } catch (err) {
-    log.error(`Invalid config for downloading snapshots`, err);
-    return false;
-  }
-
-  // Create an archiver store to check the current state
+  // Create an archiver store to check the current state (do this only once)
   log.verbose(`Creating temporary archiver data store`);
   const archiverStore = await createArchiverStore(config);
   let archiverL1BlockNumber: bigint | undefined;
@@ -71,7 +64,7 @@ export async function trySnapshotSync(config: SnapshotSyncConfig, log: Logger) {
   try {
     [archiverL1BlockNumber, archiverL2BlockNumber] = await Promise.all([
       archiverStore.getSynchPoint().then(s => s.blocksSynchedTo),
-      archiverStore.getSynchedL2BlockNumber(),
+      archiverStore.getLatestBlockNumber(),
     ] as const);
   } finally {
     log.verbose(`Closing temporary archiver data store`, { archiverL1BlockNumber, archiverL2BlockNumber });
@@ -102,65 +95,111 @@ export async function trySnapshotSync(config: SnapshotSyncConfig, log: Logger) {
     rollupVersion,
     rollupAddress: l1Contracts.rollupAddress,
   };
-  let snapshot: SnapshotMetadata | undefined;
-  try {
-    snapshot = await getLatestSnapshotMetadata(indexMetadata, fileStore);
-  } catch (err) {
-    log.error(`Failed to get latest snapshot metadata. Skipping snapshot sync.`, err, {
-      ...indexMetadata,
-      snapshotsUrl,
-    });
-    return false;
-  }
 
-  if (!snapshot) {
-    log.verbose(`No snapshot found. Skipping snapshot sync.`, { ...indexMetadata, snapshotsUrl });
-    return false;
-  }
+  // Fetch latest snapshot from each URL
+  type SnapshotCandidate = { snapshot: SnapshotMetadata; url: string; fileStore: ReadOnlyFileStore };
+  const snapshotCandidates: SnapshotCandidate[] = [];
 
-  if (snapshot.schemaVersions.archiver !== ARCHIVER_DB_VERSION) {
-    log.warn(
-      `Skipping snapshot sync as last snapshot has schema version ${snapshot.schemaVersions.archiver} but expected ${ARCHIVER_DB_VERSION}.`,
-      snapshot,
-    );
-    return false;
-  }
+  for (const snapshotsUrl of snapshotsUrls) {
+    let fileStore: ReadOnlyFileStore;
+    try {
+      fileStore = await createReadOnlyFileStore(snapshotsUrl, log);
+    } catch (err) {
+      log.error(`Invalid config for downloading snapshots from ${snapshotsUrl}`, err);
+      continue;
+    }
 
-  if (snapshot.schemaVersions.worldState !== WORLD_STATE_DB_VERSION) {
-    log.warn(
-      `Skipping snapshot sync as last snapshot has world state schema version ${snapshot.schemaVersions.worldState} but we expected ${WORLD_STATE_DB_VERSION}.`,
-      snapshot,
-    );
-    return false;
+    let snapshot: SnapshotMetadata | undefined;
+    try {
+      snapshot = await getLatestSnapshotMetadata(indexMetadata, fileStore);
+    } catch (err) {
+      log.error(`Failed to get latest snapshot metadata from ${snapshotsUrl}. Skipping this URL.`, err, {
+        ...indexMetadata,
+        snapshotsUrl,
+      });
+      continue;
+    }
+
+    if (!snapshot) {
+      log.verbose(`No snapshot found at ${snapshotsUrl}. Skipping this URL.`, { ...indexMetadata, snapshotsUrl });
+      continue;
+    }
+
+    if (snapshot.schemaVersions.archiver !== ARCHIVER_DB_VERSION) {
+      log.warn(
+        `Skipping snapshot from ${snapshotsUrl} as it has schema version ${snapshot.schemaVersions.archiver} but expected ${ARCHIVER_DB_VERSION}.`,
+        snapshot,
+      );
+      continue;
+    }
+
+    if (snapshot.schemaVersions.worldState !== WORLD_STATE_DB_VERSION) {
+      log.warn(
+        `Skipping snapshot from ${snapshotsUrl} as it has world state schema version ${snapshot.schemaVersions.worldState} but we expected ${WORLD_STATE_DB_VERSION}.`,
+        snapshot,
+      );
+      continue;
+    }
+
+    if (archiverL1BlockNumber && snapshot.l1BlockNumber < archiverL1BlockNumber) {
+      log.verbose(
+        `Skipping snapshot from ${snapshotsUrl} since local archiver is at L1 block ${archiverL1BlockNumber} which is further than snapshot at ${snapshot.l1BlockNumber}`,
+        { snapshot, archiverL1BlockNumber, snapshotsUrl },
+      );
+      continue;
+    }
+
+    if (archiverL1BlockNumber && snapshot.l1BlockNumber - Number(archiverL1BlockNumber) < minL1BlocksToTriggerReplace) {
+      log.verbose(
+        `Skipping snapshot from ${snapshotsUrl} as archiver is less than ${
+          snapshot.l1BlockNumber - Number(archiverL1BlockNumber)
+        } L1 blocks behind this snapshot.`,
+        { snapshot, archiverL1BlockNumber, snapshotsUrl },
+      );
+      continue;
+    }
+
+    snapshotCandidates.push({ snapshot, url: snapshotsUrl, fileStore });
   }
 
-  if (archiverL1BlockNumber && snapshot.l1BlockNumber < archiverL1BlockNumber) {
-    log.verbose(
-      `Skipping snapshot sync since local archiver is at L1 block ${archiverL1BlockNumber} which is further than last snapshot at ${snapshot.l1BlockNumber}`,
-      { snapshot, archiverL1BlockNumber },
-    );
+  if (snapshotCandidates.length === 0) {
+    log.verbose(`No valid snapshots found from any URL, skipping snapshot sync`, { ...indexMetadata, snapshotsUrls });
     return false;
   }
 
-  if (archiverL1BlockNumber && snapshot.l1BlockNumber - Number(archiverL1BlockNumber) < minL1BlocksToTriggerReplace) {
-    log.verbose(
-      `Skipping snapshot sync as archiver is less than ${
-        snapshot.l1BlockNumber - Number(archiverL1BlockNumber)
-      } L1 blocks behind latest snapshot.`,
-      { snapshot, archiverL1BlockNumber },
-    );
-    return false;
+  // Sort candidates by L1 block number (highest first)
+  snapshotCandidates.sort((a, b) => b.snapshot.l1BlockNumber - a.snapshot.l1BlockNumber);
+
+  // Try each candidate in order until one succeeds
+  for (const { snapshot, url } of snapshotCandidates) {
+    const { l1BlockNumber, l2BlockNumber } = snapshot;
+    log.info(`Attempting to sync from snapshot at L1 block ${l1BlockNumber} L2 block ${l2BlockNumber}`, {
+      snapshot,
+      snapshotsUrl: url,
+    });
+
+    try {
+      await snapshotSync(snapshot, log, {
+        dataDirectory: config.dataDirectory!,
+        rollupAddress: config.l1Contracts.rollupAddress,
+        snapshotsUrl: url,
+      });
+      log.info(`Snapshot synced to L1 block ${l1BlockNumber} L2 block ${l2BlockNumber}`, {
+        snapshot,
+        snapshotsUrl: url,
+      });
+      return true;
+    } catch (err) {
+      log.error(`Failed to download snapshot from ${url}, trying next candidate`, err, {
+        snapshot,
+        snapshotsUrl: url,
+      });
+      continue;
+    }
   }
 
-  const { l1BlockNumber, l2BlockNumber } = snapshot;
-  log.info(`Syncing from snapshot at L1 block ${l1BlockNumber} L2 block ${l2BlockNumber}`, { snapshot, snapshotsUrl });
-  await snapshotSync(snapshot, log, {
-    dataDirectory: config.dataDirectory!,
-    rollupAddress: config.l1Contracts.rollupAddress,
-    snapshotsUrl,
-  });
-  log.info(`Snapshot synced to L1 block ${l1BlockNumber} L2 block ${l2BlockNumber}`, { snapshot });
-  return true;
+  log.error(`Failed to download snapshot from all URLs`, { snapshotsUrls });
+  return false;
 }
 
 /**

package/src/config/index.ts

@@ -7,8 +7,8 @@ export type SharedNodeConfig = {
   sponsoredFPC: boolean;
   /** Sync mode: full to always sync via L1, snapshot to download a snapshot if there is no local data, force-snapshot to download even if there is local data. */
   syncMode: 'full' | 'snapshot' | 'force-snapshot';
-  /** Base URL for snapshots index. Index file will be searched at `SNAPSHOTS_BASE_URL/aztec-L1_CHAIN_ID-VERSION-ROLLUP_ADDRESS/index.json` */
-  snapshotsUrl?: string;
+  /** Base URLs for snapshots index. Index file will be searched at `SNAPSHOTS_BASE_URL/aztec-L1_CHAIN_ID-VERSION-ROLLUP_ADDRESS/index.json` */
+  snapshotsUrls?: string[];
 
   /** Auto update mode: disabled - to completely ignore remote signals to update the node. enabled - to respect the signals (potentially shutting this node down). log - check for updates but log a warning instead of applying them*/
   autoUpdate?: 'disabled' | 'notify' | 'config' | 'config-and-version';
@@ -17,6 +17,11 @@ export type SharedNodeConfig = {
 
   /** URL of the Web3Signer instance */
   web3SignerUrl?: string;
+  /** Whether to run in fisherman mode */
+  fishermanMode?: boolean;
+
+  /** Force verification of tx Chonk proofs. Only used for testnet */
+  debugForceTxProofVerification: boolean;
 };
 
 export const sharedNodeConfigMappings: ConfigMappingsType<SharedNodeConfig> = {
@@ -36,9 +41,16 @@ export const sharedNodeConfigMappings: ConfigMappingsType<SharedNodeConfig> = {
       'Set sync mode to `full` to always sync via L1, `snapshot` to download a snapshot if there is no local data, `force-snapshot` to download even if there is local data.',
     defaultValue: 'snapshot',
   },
-  snapshotsUrl: {
-    env: 'SYNC_SNAPSHOTS_URL',
-    description: 'Base URL for snapshots index.',
+  snapshotsUrls: {
+    env: 'SYNC_SNAPSHOTS_URLS',
+    description: 'Base URLs for snapshots index, comma-separated.',
+    parseEnv: (val: string) =>
+      val
+        .split(',')
+        .map(url => url.trim())
+        .filter(url => url.length > 0),
+    fallback: ['SYNC_SNAPSHOTS_URL'],
+    defaultValue: [],
   },
   autoUpdate: {
     env: 'AUTO_UPDATE',
@@ -54,4 +66,14 @@ export const sharedNodeConfigMappings: ConfigMappingsType<SharedNodeConfig> = {
     description: 'URL of the Web3Signer instance',
     parseEnv: (val: string) => val.trim(),
   },
+  fishermanMode: {
+    env: 'FISHERMAN_MODE',
+    description: 'Whether to run in fisherman mode.',
+    ...booleanConfigHelper(false),
+  },
+  debugForceTxProofVerification: {
+    env: 'DEBUG_FORCE_TX_PROOF_VERIFICATION',
+    description: 'Whether to force tx proof verification. Only has an effect if real proving is turned off',
+    ...booleanConfigHelper(false),
+  },
 };

package/src/factories/index.ts

@@ -0,0 +1 @@
+export * from './l1_tx_utils.js';

package/src/factories/l1_tx_utils.ts

@@ -0,0 +1,212 @@
+import type { EthSigner } from '@aztec/ethereum/eth-signer';
+import {
+  createL1TxUtilsFromEthSigner as createL1TxUtilsFromEthSignerBase,
+  createL1TxUtilsFromViemWallet as createL1TxUtilsFromViemWalletBase,
+} from '@aztec/ethereum/l1-tx-utils';
+import type { L1TxUtilsConfig } from '@aztec/ethereum/l1-tx-utils';
+import {
+  createForwarderL1TxUtilsFromEthSigner as createForwarderL1TxUtilsFromEthSignerBase,
+  createForwarderL1TxUtilsFromViemWallet as createForwarderL1TxUtilsFromViemWalletBase,
+  createL1TxUtilsWithBlobsFromEthSigner as createL1TxUtilsWithBlobsFromEthSignerBase,
+  createL1TxUtilsWithBlobsFromViemWallet as createL1TxUtilsWithBlobsFromViemWalletBase,
+} from '@aztec/ethereum/l1-tx-utils-with-blobs';
+import type { ExtendedViemWalletClient, ViemClient } from '@aztec/ethereum/types';
+import { omit } from '@aztec/foundation/collection';
+import { createLogger } from '@aztec/foundation/log';
+import type { DateProvider } from '@aztec/foundation/timer';
+import type { DataStoreConfig } from '@aztec/kv-store/config';
+import { createStore } from '@aztec/kv-store/lmdb-v2';
+import type { TelemetryClient } from '@aztec/telemetry-client';
+
+import type { L1TxScope } from '../metrics/l1_tx_metrics.js';
+import { L1TxMetrics } from '../metrics/l1_tx_metrics.js';
+import { L1TxStore } from '../stores/l1_tx_store.js';
+
+const L1_TX_STORE_NAME = 'l1-tx-utils';
+
+/**
+ * Creates shared dependencies (logger, store, metrics) for L1TxUtils instances.
+ */
+async function createSharedDeps(
+  config: DataStoreConfig & { scope?: L1TxScope },
+  deps: {
+    telemetry: TelemetryClient;
+    logger?: ReturnType<typeof createLogger>;
+    dateProvider?: DateProvider;
+  },
+) {
+  const logger = deps.logger ?? createLogger('l1-tx-utils');
+
+  // Note that we do NOT bind them to the rollup address, since we still need to
+  // monitor and cancel txs for previous rollups to free up our nonces.
+  const noRollupConfig = omit(config, 'l1Contracts');
+  const kvStore = await createStore(L1_TX_STORE_NAME, L1TxStore.SCHEMA_VERSION, noRollupConfig, logger);
+  const store = new L1TxStore(kvStore, logger);
+
+  const meter = deps.telemetry.getMeter('L1TxUtils');
+  const metrics = new L1TxMetrics(meter, config.scope ?? 'other', logger);
+
+  return { logger, store, metrics, dateProvider: deps.dateProvider };
+}
+
+/**
+ * Creates L1TxUtils with blobs from multiple Viem wallets, sharing store and metrics.
+ */
+export async function createL1TxUtilsWithBlobsFromViemWallet(
+  clients: ExtendedViemWalletClient[],
+  config: DataStoreConfig & Partial<L1TxUtilsConfig> & { debugMaxGasLimit?: boolean; scope?: L1TxScope },
+  deps: {
+    telemetry: TelemetryClient;
+    logger?: ReturnType<typeof createLogger>;
+    dateProvider?: DateProvider;
+  },
+) {
+  const sharedDeps = await createSharedDeps(config, deps);
+
+  return clients.map(client =>
+    createL1TxUtilsWithBlobsFromViemWalletBase(client, sharedDeps, config, config.debugMaxGasLimit),
+  );
+}
+
+/**
+ * Creates L1TxUtils with blobs from multiple EthSigners, sharing store and metrics. Removes duplicates
+ */
+export async function createL1TxUtilsWithBlobsFromEthSigner(
+  client: ViemClient,
+  signers: EthSigner[],
+  config: DataStoreConfig & Partial<L1TxUtilsConfig> & { debugMaxGasLimit?: boolean; scope?: L1TxScope },
+  deps: {
+    telemetry: TelemetryClient;
+    logger?: ReturnType<typeof createLogger>;
+    dateProvider?: DateProvider;
+  },
+) {
+  const sharedDeps = await createSharedDeps(config, deps);
+
+  // Deduplicate signers by address to avoid creating multiple L1TxUtils instances
+  // for the same publisher address (e.g., when multiple attesters share the same publisher key)
+  const signersByAddress = new Map<string, EthSigner>();
+  for (const signer of signers) {
+    const addressKey = signer.address.toString().toLowerCase();
+    if (!signersByAddress.has(addressKey)) {
+      signersByAddress.set(addressKey, signer);
+    }
+  }
+
+  const uniqueSigners = Array.from(signersByAddress.values());
+
+  if (uniqueSigners.length < signers.length) {
+    sharedDeps.logger.info(
+      `Deduplicated ${signers.length} signers to ${uniqueSigners.length} unique publisher addresses`,
+    );
+  }
+
+  return uniqueSigners.map(signer =>
+    createL1TxUtilsWithBlobsFromEthSignerBase(client, signer, sharedDeps, config, config.debugMaxGasLimit),
+  );
+}
+
+/**
+ * Creates L1TxUtils (without blobs) from multiple Viem wallets, sharing store and metrics.
+ */
+export async function createL1TxUtilsFromViemWalletWithStore(
+  clients: ExtendedViemWalletClient[],
+  config: DataStoreConfig & Partial<L1TxUtilsConfig> & { debugMaxGasLimit?: boolean; scope?: L1TxScope },
+  deps: {
+    telemetry: TelemetryClient;
+    logger?: ReturnType<typeof createLogger>;
+    dateProvider?: DateProvider;
+    scope?: L1TxScope;
+  },
+) {
+  const sharedDeps = await createSharedDeps(config, deps);
+
+  return clients.map(client => createL1TxUtilsFromViemWalletBase(client, sharedDeps, config));
+}
+
+/**
+ * Creates L1TxUtils (without blobs) from multiple EthSigners, sharing store and metrics. Removes duplicates.
+ */
+export async function createL1TxUtilsFromEthSignerWithStore(
+  client: ViemClient,
+  signers: EthSigner[],
+  config: DataStoreConfig & Partial<L1TxUtilsConfig> & { debugMaxGasLimit?: boolean; scope?: L1TxScope },
+  deps: {
+    telemetry: TelemetryClient;
+    logger?: ReturnType<typeof createLogger>;
+    dateProvider?: DateProvider;
+    scope?: L1TxScope;
+  },
+) {
+  const sharedDeps = await createSharedDeps(config, deps);
+
+  // Deduplicate signers by address to avoid creating multiple L1TxUtils instances
+  // for the same publisher address (e.g., when multiple attesters share the same publisher key)
+  const signersByAddress = new Map<string, EthSigner>();
+  for (const signer of signers) {
+    const addressKey = signer.address.toString().toLowerCase();
+    if (!signersByAddress.has(addressKey)) {
+      signersByAddress.set(addressKey, signer);
+    }
+  }
+
+  const uniqueSigners = Array.from(signersByAddress.values());
+
+  if (uniqueSigners.length < signers.length) {
+    sharedDeps.logger.info(
+      `Deduplicated ${signers.length} signers to ${uniqueSigners.length} unique publisher addresses`,
+    );
+  }
+
+  return uniqueSigners.map(signer => createL1TxUtilsFromEthSignerBase(client, signer, sharedDeps, config));
+}
+
+/**
+ * Creates ForwarderL1TxUtils from multiple Viem wallets, sharing store and metrics.
+ * This wraps all transactions through a forwarder contract for testing purposes.
+ */
+export async function createForwarderL1TxUtilsFromViemWallet(
+  clients: ExtendedViemWalletClient[],
+  forwarderAddress: import('@aztec/foundation/eth-address').EthAddress,
+  config: DataStoreConfig & Partial<L1TxUtilsConfig> & { debugMaxGasLimit?: boolean; scope?: L1TxScope },
+  deps: {
+    telemetry: TelemetryClient;
+    logger?: ReturnType<typeof createLogger>;
+    dateProvider?: DateProvider;
+  },
+) {
+  const sharedDeps = await createSharedDeps(config, deps);
+
+  return clients.map(client =>
+    createForwarderL1TxUtilsFromViemWalletBase(client, forwarderAddress, sharedDeps, config, config.debugMaxGasLimit),
+  );
+}
+
+/**
+ * Creates ForwarderL1TxUtils from multiple EthSigners, sharing store and metrics.
+ * This wraps all transactions through a forwarder contract for testing purposes.
+ */
+export async function createForwarderL1TxUtilsFromEthSigner(
+  client: ViemClient,
+  signers: EthSigner[],
+  forwarderAddress: import('@aztec/foundation/eth-address').EthAddress,
+  config: DataStoreConfig & Partial<L1TxUtilsConfig> & { debugMaxGasLimit?: boolean; scope?: L1TxScope },
+  deps: {
+    telemetry: TelemetryClient;
+    logger?: ReturnType<typeof createLogger>;
+    dateProvider?: DateProvider;
+  },
+) {
+  const sharedDeps = await createSharedDeps(config, deps);
+
+  return signers.map(signer =>
+    createForwarderL1TxUtilsFromEthSignerBase(
+      client,
+      signer,
+      forwarderAddress,
+      sharedDeps,
+      config,
+      config.debugMaxGasLimit,
+    ),
+  );
+}

package/src/metrics/index.ts

@@ -0,0 +1 @@
+export * from './l1_tx_metrics.js';

package/src/metrics/l1_tx_metrics.ts

@@ -0,0 +1,169 @@
+import type { IL1TxMetrics, L1TxState } from '@aztec/ethereum/l1-tx-utils';
+import { TxUtilsState } from '@aztec/ethereum/l1-tx-utils';
+import { createLogger } from '@aztec/foundation/log';
+import {
+  Attributes,
+  type Histogram,
+  type Meter,
+  Metrics,
+  type UpDownCounter,
+  ValueType,
+} from '@aztec/telemetry-client';
+
+export type L1TxScope = 'sequencer' | 'prover' | 'other';
+
+/**
+ * Metrics for L1 transaction utils tracking tx lifecycle and gas costs.
+ */
+export class L1TxMetrics implements IL1TxMetrics {
+  // Time until tx is mined
+  private txMinedDuration: Histogram;
+
+  // Number of attempts until mined
+  private txAttemptsUntilMined: Histogram;
+
+  // Counters for end states
+  private txMinedCount: UpDownCounter;
+  private txRevertedCount: UpDownCounter;
+  private txCancelledCount: UpDownCounter;
+  private txNotMinedCount: UpDownCounter;
+
+  // Gas price histograms (at end state, in wei)
+  private maxPriorityFeeHistogram: Histogram;
+  private maxFeeHistogram: Histogram;
+  private blobFeeHistogram: Histogram;
+
+  constructor(
+    private meter: Meter,
+    private scope: L1TxScope = 'other',
+    private logger = createLogger('l1-tx-utils:metrics'),
+  ) {
+    this.txMinedDuration = this.meter.createHistogram(Metrics.L1_TX_MINED_DURATION, {
+      description: 'Time from initial tx send until mined',
+      unit: 's',
+      valueType: ValueType.INT,
+    });
+
+    this.txAttemptsUntilMined = this.meter.createHistogram(Metrics.L1_TX_ATTEMPTS_UNTIL_MINED, {
+      description: 'Number of tx attempts (including speed-ups) until mined',
+      unit: 'attempts',
+      valueType: ValueType.INT,
+    });
+
+    this.txMinedCount = this.meter.createUpDownCounter(Metrics.L1_TX_MINED_COUNT, {
+      description: 'Count of transactions successfully mined',
+      valueType: ValueType.INT,
+    });
+
+    this.txRevertedCount = this.meter.createUpDownCounter(Metrics.L1_TX_REVERTED_COUNT, {
+      description: 'Count of transactions that reverted',
+      valueType: ValueType.INT,
+    });
+
+    this.txCancelledCount = this.meter.createUpDownCounter(Metrics.L1_TX_CANCELLED_COUNT, {
+      description: 'Count of transactions cancelled',
+      valueType: ValueType.INT,
+    });
+
+    this.txNotMinedCount = this.meter.createUpDownCounter(Metrics.L1_TX_NOT_MINED_COUNT, {
+      description: 'Count of transactions not mined (timed out)',
+      valueType: ValueType.INT,
+    });
+
+    this.maxPriorityFeeHistogram = this.meter.createHistogram(Metrics.L1_TX_MAX_PRIORITY_FEE, {
+      description: 'Max priority fee per gas at tx end state (in wei)',
+      unit: 'wei',
+      valueType: ValueType.INT,
+    });
+
+    this.maxFeeHistogram = this.meter.createHistogram(Metrics.L1_TX_MAX_FEE, {
+      description: 'Max fee per gas at tx end state (in wei)',
+      unit: 'wei',
+      valueType: ValueType.INT,
+    });
+
+    this.blobFeeHistogram = this.meter.createHistogram(Metrics.L1_TX_BLOB_FEE, {
+      description: 'Max fee per blob gas at tx end state (in wei)',
+      unit: 'wei',
+      valueType: ValueType.INT,
+    });
+  }
+
+  /**
+   * Records metrics when a transaction is mined.
+   * @param state - The L1 transaction state
+   * @param l1Timestamp - The current L1 timestamp
+   */
+  public recordMinedTx(state: L1TxState, l1Timestamp: Date): void {
+    if (state.status !== TxUtilsState.MINED) {
+      this.logger.warn(
+        `Attempted to record mined tx metrics for a tx not in MINED state (state: ${TxUtilsState[state.status]})`,
+        { scope: this.scope, nonce: state.nonce },
+      );
+      return;
+    }
+
+    const attributes = { [Attributes.L1_TX_SCOPE]: this.scope };
+    const isCancelTx = state.cancelTxHashes.length > 0;
+    const isReverted = state.receipt?.status === 'reverted';
+
+    if (isCancelTx) {
+      this.txCancelledCount.add(1, attributes);
+    } else if (isReverted) {
+      this.txRevertedCount.add(1, attributes);
+    } else {
+      this.txMinedCount.add(1, attributes);
+    }
+
+    // Record time to mine using provided L1 timestamp
+    const duration = Math.floor((l1Timestamp.getTime() - state.sentAtL1Ts.getTime()) / 1000);
+    this.txMinedDuration.record(duration, attributes);
+
+    // Record number of attempts until mined
+    const attempts = isCancelTx ? state.cancelTxHashes.length : state.txHashes.length;
+    this.txAttemptsUntilMined.record(attempts, attributes);
+
+    // Record gas prices at end state (in wei as integers)
+    const maxPriorityFeeWei = Number(state.gasPrice.maxPriorityFeePerGas);
+    const maxFeeWei = Number(state.gasPrice.maxFeePerGas);
+    const blobFeeWei = state.gasPrice.maxFeePerBlobGas ? Number(state.gasPrice.maxFeePerBlobGas) : undefined;
+
+    this.maxPriorityFeeHistogram.record(maxPriorityFeeWei, attributes);
+    this.maxFeeHistogram.record(maxFeeWei, attributes);
+
+    // Record blob fee if present (in wei as integer)
+    if (blobFeeWei !== undefined) {
+      this.blobFeeHistogram.record(blobFeeWei, attributes);
+    }
+
+    this.logger.debug(`Recorded tx end state metrics`, {
+      status: TxUtilsState[state.status],
+      nonce: state.nonce,
+      isCancelTx,
+      isReverted,
+      scope: this.scope,
+      maxPriorityFeeWei,
+      maxFeeWei,
+      blobFeeWei,
+    });
+  }
+
+  public recordDroppedTx(state: L1TxState): void {
+    if (state.status !== TxUtilsState.NOT_MINED) {
+      this.logger.warn(
+        `Attempted to record dropped tx metrics for a tx not in NOT_MINED state (state: ${TxUtilsState[state.status]})`,
+        { scope: this.scope, nonce: state.nonce },
+      );
+      return;
+    }
+
+    const attributes = { [Attributes.L1_TX_SCOPE]: this.scope };
+    this.txNotMinedCount.add(1, attributes);
+
+    this.logger.debug(`Recorded tx dropped metrics`, {
+      status: TxUtilsState[state.status],
+      nonce: state.nonce,
+      scope: this.scope,
+    });
+  }
+}

package/src/stores/index.ts

@@ -0,0 +1 @@
+export * from './l1_tx_store.js';