@aztec/node-lib 0.0.1-commit.0208eb9

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.getBindings());
+  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,138 @@
+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,
+  createUpDownCounterWithDefault,
+} 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);
+
+    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 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';