@aztec-labs/node-lib 6.0.0-nightly.20260829

package/src/factories/l1_tx_utils.ts

@@ -0,0 +1,156 @@
+import type { BlobKzgInstance } from '@aztec-labs/blob-lib/types';
+import type { EthSigner } from '@aztec-labs/ethereum/eth-signer';
+import { createDelayer, createL1TxUtils as createL1TxUtilsBase } from '@aztec-labs/ethereum/l1-tx-utils';
+import type { L1TxUtilsConfig } from '@aztec-labs/ethereum/l1-tx-utils';
+import { createForwarderL1TxUtils as createForwarderL1TxUtilsBase } from '@aztec-labs/ethereum/l1-tx-utils-with-blobs';
+import type { ExtendedViemWalletClient, ViemClient } from '@aztec-labs/ethereum/types';
+import { omit } from '@aztec-labs/foundation/collection';
+import type { EthAddress } from '@aztec-labs/foundation/eth-address';
+import { createLogger } from '@aztec-labs/foundation/log';
+import type { DateProvider } from '@aztec-labs/foundation/timer';
+import { createStore } from '@aztec-labs/kv-store/lmdb-v2';
+import type { DataStoreConfig } from '@aztec-labs/stdlib/kv-store';
+import type { TelemetryClient } from '@aztec-labs/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, delayer) for L1TxUtils instances.
+ * When enableDelayer is set in config, a single shared delayer is created and passed to all instances.
+ */
+async function createSharedDeps(
+  config: DataStoreConfig & Partial<L1TxUtilsConfig> & { 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, 'rollupAddress');
+  const kvStore = await createStore(L1_TX_STORE_NAME, L1TxStore.SCHEMA_VERSION, noRollupConfig, logger.getBindings());
+  const store = new L1TxStore(kvStore, logger);
+
+  const meter = deps.telemetry.getMeter('L1TxUtils');
+  const metrics = new L1TxMetrics(meter, config.scope ?? 'other', logger);
+
+  // Create a single shared delayer for all L1TxUtils instances in this group
+  const delayer =
+    config.enableDelayer && config.ethereumSlotDuration !== undefined
+      ? createDelayer(deps.dateProvider, { ethereumSlotDuration: config.ethereumSlotDuration }, logger.getBindings())
+      : undefined;
+
+  return { logger, store, metrics, dateProvider: deps.dateProvider, delayer };
+}
+
+/**
+ * Creates L1TxUtils from multiple Viem wallet clients, sharing store, metrics, and delayer.
+ * When kzg is provided in deps, blob support is enabled.
+ */
+export async function createL1TxUtilsFromWallets(
+  clients: ExtendedViemWalletClient[],
+  config: DataStoreConfig & Partial<L1TxUtilsConfig> & { debugMaxGasLimit?: boolean; scope?: L1TxScope },
+  deps: {
+    telemetry: TelemetryClient;
+    logger?: ReturnType<typeof createLogger>;
+    dateProvider: DateProvider;
+    kzg?: BlobKzgInstance;
+  },
+) {
+  const sharedDeps = await createSharedDeps(config, deps);
+
+  return clients.map(client => createL1TxUtilsBase(client, { ...sharedDeps, kzg: deps.kzg }, config));
+}
+
+/**
+ * Creates L1TxUtils from multiple EthSigners, sharing store, metrics, and delayer.
+ * When kzg is provided in deps, blob support is enabled.
+ * Deduplicates signers by address to avoid creating multiple instances for the same publisher.
+ */
+export async function createL1TxUtilsFromSigners(
+  client: ViemClient,
+  signers: EthSigner[],
+  config: DataStoreConfig & Partial<L1TxUtilsConfig> & { debugMaxGasLimit?: boolean; scope?: L1TxScope },
+  deps: {
+    telemetry: TelemetryClient;
+    logger?: ReturnType<typeof createLogger>;
+    dateProvider: DateProvider;
+    kzg?: BlobKzgInstance;
+  },
+) {
+  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 => createL1TxUtilsBase({ client, signer }, { ...sharedDeps, kzg: deps.kzg }, config));
+}
+
+/**
+ * Creates ForwarderL1TxUtils from multiple Viem wallet clients, sharing store, metrics, and delayer.
+ * Wraps all transactions through a forwarder contract for testing purposes.
+ * When kzg is provided in deps, blob support is enabled.
+ */
+export async function createForwarderL1TxUtilsFromWallets(
+  clients: ExtendedViemWalletClient[],
+  forwarderAddress: EthAddress,
+  config: DataStoreConfig & Partial<L1TxUtilsConfig> & { debugMaxGasLimit?: boolean; scope?: L1TxScope },
+  deps: {
+    telemetry: TelemetryClient;
+    logger?: ReturnType<typeof createLogger>;
+    dateProvider: DateProvider;
+    kzg?: BlobKzgInstance;
+  },
+) {
+  const sharedDeps = await createSharedDeps(config, deps);
+
+  return clients.map(client =>
+    createForwarderL1TxUtilsBase(client, forwarderAddress, { ...sharedDeps, kzg: deps.kzg }, config),
+  );
+}
+
+/**
+ * Creates ForwarderL1TxUtils from multiple EthSigners, sharing store, metrics, and delayer.
+ * Wraps all transactions through a forwarder contract for testing purposes.
+ * When kzg is provided in deps, blob support is enabled.
+ */
+export async function createForwarderL1TxUtilsFromSigners(
+  client: ViemClient,
+  signers: EthSigner[],
+  forwarderAddress: EthAddress,
+  config: DataStoreConfig & Partial<L1TxUtilsConfig> & { debugMaxGasLimit?: boolean; scope?: L1TxScope },
+  deps: {
+    telemetry: TelemetryClient;
+    logger?: ReturnType<typeof createLogger>;
+    dateProvider: DateProvider;
+    kzg?: BlobKzgInstance;
+  },
+) {
+  const sharedDeps = await createSharedDeps(config, deps);
+
+  return signers.map(signer =>
+    createForwarderL1TxUtilsBase({ client, signer }, forwarderAddress, { ...sharedDeps, kzg: deps.kzg }, config),
+  );
+}

package/src/metrics/index.ts

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

package/src/metrics/l1_tx_metrics.ts

@@ -0,0 +1,140 @@
+import type { IL1TxMetrics, L1TxState } from '@aztec-labs/ethereum/l1-tx-utils';
+import { TxUtilsState } from '@aztec-labs/ethereum/l1-tx-utils';
+import { createLogger } from '@aztec-labs/foundation/log';
+import {
+  Attributes,
+  type Histogram,
+  type Meter,
+  Metrics,
+  type UpDownCounter,
+  createUpDownCounterWithDefault,
+} from '@aztec-labs/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);
+
+    this.txAttemptsUntilMined = this.meter.createHistogram(Metrics.L1_TX_ATTEMPTS_UNTIL_MINED);
+
+    const scopeAttributes = [{ [Attributes.L1_TX_SCOPE]: this.scope }];
+    this.txMinedCount = createUpDownCounterWithDefault(this.meter, Metrics.L1_TX_MINED_COUNT, scopeAttributes);
+
+    this.txRevertedCount = createUpDownCounterWithDefault(this.meter, Metrics.L1_TX_REVERTED_COUNT, scopeAttributes);
+
+    this.txCancelledCount = createUpDownCounterWithDefault(this.meter, Metrics.L1_TX_CANCELLED_COUNT, scopeAttributes);
+
+    this.txNotMinedCount = createUpDownCounterWithDefault(this.meter, Metrics.L1_TX_NOT_MINED_COUNT, scopeAttributes);
+
+    this.maxPriorityFeeHistogram = this.meter.createHistogram(Metrics.L1_TX_MAX_PRIORITY_FEE);
+
+    this.maxFeeHistogram = this.meter.createHistogram(Metrics.L1_TX_MAX_FEE);
+
+    this.blobFeeHistogram = this.meter.createHistogram(Metrics.L1_TX_BLOB_FEE);
+  }
+
+  /**
+   * 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 fees per gas at end state, converted from wei to gwei to match metric unit definitions
+    const weiToGwei = 1e9;
+    const maxPriorityFeeGwei = Number(state.feesPerGas.maxPriorityFeePerGas) / weiToGwei;
+    const maxFeeGwei = Number(state.feesPerGas.maxFeePerGas) / weiToGwei;
+    const blobFeeGwei = state.feesPerGas.maxFeePerBlobGas
+      ? Number(state.feesPerGas.maxFeePerBlobGas) / weiToGwei
+      : undefined;
+
+    this.maxPriorityFeeHistogram.record(maxPriorityFeeGwei, attributes);
+    this.maxFeeHistogram.record(maxFeeGwei, attributes);
+
+    if (blobFeeGwei !== undefined) {
+      this.blobFeeHistogram.record(blobFeeGwei, attributes);
+    }
+
+    this.logger.debug(`Recorded tx end state metrics`, {
+      status: TxUtilsState[state.status],
+      nonce: state.nonce,
+      isCancelTx,
+      isReverted,
+      scope: this.scope,
+      maxPriorityFeeGwei,
+      maxFeeGwei,
+      blobFeeGwei,
+    });
+  }
+
+  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';