@aztec/ethereum 3.0.0-canary.a9708bd → 3.0.0-devnet.20251212

package/src/l1_tx_utils/factory.ts

@@ -0,0 +1,64 @@
+import { EthAddress } from '@aztec/foundation/eth-address';
+import type { Logger } from '@aztec/foundation/log';
+import { DateProvider } from '@aztec/foundation/timer';
+
+import type { TransactionSerializable } from 'viem';
+
+import type { EthSigner } from '../eth-signer/eth-signer.js';
+import type { ExtendedViemWalletClient, ViemClient } from '../types.js';
+import type { L1TxUtilsConfig } from './config.js';
+import type { IL1TxMetrics, IL1TxStore } from './interfaces.js';
+import { L1TxUtils } from './l1_tx_utils.js';
+import { createViemSigner } from './signer.js';
+import type { SigningCallback } from './types.js';
+
+export function createL1TxUtilsFromViemWallet(
+  client: ExtendedViemWalletClient,
+  deps?: {
+    logger?: Logger;
+    dateProvider?: DateProvider;
+    store?: IL1TxStore;
+    metrics?: IL1TxMetrics;
+  },
+  config?: Partial<L1TxUtilsConfig> & { debugMaxGasLimit?: boolean },
+): L1TxUtils {
+  return new L1TxUtils(
+    client,
+    EthAddress.fromString(client.account.address),
+    createViemSigner(client),
+    deps?.logger,
+    deps?.dateProvider,
+    config,
+    config?.debugMaxGasLimit ?? false,
+    deps?.store,
+    deps?.metrics,
+  );
+}
+
+export function createL1TxUtilsFromEthSigner(
+  client: ViemClient,
+  signer: EthSigner,
+  deps?: {
+    logger?: Logger;
+    dateProvider?: DateProvider;
+    store?: IL1TxStore;
+    metrics?: IL1TxMetrics;
+  },
+  config?: Partial<L1TxUtilsConfig> & { debugMaxGasLimit?: boolean },
+): L1TxUtils {
+  const callback: SigningCallback = async (transaction: TransactionSerializable, _signingAddress) => {
+    return (await signer.signTransaction(transaction)).toViemTransactionSignature();
+  };
+
+  return new L1TxUtils(
+    client,
+    signer.address,
+    callback,
+    deps?.logger,
+    deps?.dateProvider,
+    config,
+    config?.debugMaxGasLimit ?? false,
+    deps?.store,
+    deps?.metrics,
+  );
+}

package/src/l1_tx_utils/forwarder_l1_tx_utils.ts

@@ -0,0 +1,119 @@
+import { EthAddress } from '@aztec/foundation/eth-address';
+import type { Logger } from '@aztec/foundation/log';
+import type { DateProvider } from '@aztec/foundation/timer';
+
+import { type Hex, encodeFunctionData } from 'viem';
+
+import type { EthSigner } from '../eth-signer/eth-signer.js';
+import { FORWARDER_ABI } from '../forwarder_proxy.js';
+import type { ExtendedViemWalletClient, ViemClient } from '../types.js';
+import type { L1TxUtilsConfig } from './config.js';
+import type { IL1TxMetrics, IL1TxStore } from './interfaces.js';
+import { L1TxUtilsWithBlobs } from './l1_tx_utils_with_blobs.js';
+import { createViemSigner } from './signer.js';
+import type { L1BlobInputs, L1TxConfig, L1TxRequest, SigningCallback } from './types.js';
+
+/**
+ * Extends L1TxUtilsWithBlobs to wrap all transactions through a forwarder contract.
+ * This is mainly used for testing the archiver's ability to decode transactions that go through proxies.
+ */
+export class ForwarderL1TxUtils extends L1TxUtilsWithBlobs {
+  constructor(
+    client: ViemClient | ExtendedViemWalletClient,
+    senderAddress: EthAddress,
+    signingCallback: SigningCallback,
+    logger: Logger | undefined,
+    dateProvider: DateProvider | undefined,
+    config: Partial<L1TxUtilsConfig>,
+    debugMaxGasLimit: boolean,
+    store: IL1TxStore | undefined,
+    metrics: IL1TxMetrics | undefined,
+    private readonly forwarderAddress: EthAddress,
+  ) {
+    super(client, senderAddress, signingCallback, logger, dateProvider, config, debugMaxGasLimit, store, metrics);
+  }
+
+  /**
+   * Wraps the transaction request in a call to the forwarder contract.
+   */
+  private wrapInForwarder(request: L1TxRequest): L1TxRequest {
+    const forwarderCalldata = encodeFunctionData({
+      abi: FORWARDER_ABI,
+      functionName: 'forward',
+      args: [request.to as Hex, request.data as Hex],
+    });
+
+    return {
+      to: this.forwarderAddress.toString() as Hex,
+      data: forwarderCalldata,
+      value: request.value,
+      abi: request.abi, // Preserve the original ABI for error decoding
+    };
+  }
+
+  /**
+   * Override sendAndMonitorTransaction to wrap the request in a forwarder call.
+   */
+  public override sendAndMonitorTransaction(request: L1TxRequest, gasConfig?: L1TxConfig, blobInputs?: L1BlobInputs) {
+    this.logger.debug(`Wrapping transaction to ${request.to} in forwarder at ${this.forwarderAddress.toString()}`);
+    const wrappedRequest = this.wrapInForwarder(request);
+    return super.sendAndMonitorTransaction(wrappedRequest, gasConfig, blobInputs);
+  }
+}
+
+export function createForwarderL1TxUtilsFromViemWallet(
+  client: ExtendedViemWalletClient,
+  forwarderAddress: EthAddress,
+  deps: {
+    logger?: Logger;
+    dateProvider?: DateProvider;
+    store?: IL1TxStore;
+    metrics?: IL1TxMetrics;
+  } = {},
+  config: Partial<L1TxUtilsConfig> = {},
+  debugMaxGasLimit: boolean = false,
+) {
+  return new ForwarderL1TxUtils(
+    client,
+    EthAddress.fromString(client.account.address),
+    createViemSigner(client),
+    deps.logger,
+    deps.dateProvider,
+    config,
+    debugMaxGasLimit,
+    deps.store,
+    deps.metrics,
+    forwarderAddress,
+  );
+}
+
+export function createForwarderL1TxUtilsFromEthSigner(
+  client: ViemClient,
+  signer: EthSigner,
+  forwarderAddress: EthAddress,
+  deps: {
+    logger?: Logger;
+    dateProvider?: DateProvider;
+    store?: IL1TxStore;
+    metrics?: IL1TxMetrics;
+  } = {},
+  config: Partial<L1TxUtilsConfig> = {},
+  debugMaxGasLimit: boolean = false,
+) {
+  const callback: SigningCallback = async (transaction, _signingAddress) => {
+    return (await signer.signTransaction(transaction)).toViemTransactionSignature();
+  };
+
+  return new ForwarderL1TxUtils(
+    client,
+    signer.address,
+    callback,
+    deps.logger,
+    deps.dateProvider,
+    config,
+    debugMaxGasLimit,
+    deps.store,
+    deps.metrics,
+    forwarderAddress,
+  );
+}

package/src/l1_tx_utils/index-blobs.ts

@@ -0,0 +1,2 @@
+export * from './forwarder_l1_tx_utils.js';
+export * from './l1_tx_utils_with_blobs.js';

package/src/l1_tx_utils/index.ts

@@ -0,0 +1,12 @@
+export * from './config.js';
+export * from './constants.js';
+export * from './factory.js';
+export * from './interfaces.js';
+export * from './l1_tx_utils.js';
+export * from './readonly_l1_tx_utils.js';
+export * from './signer.js';
+export * from './types.js';
+export * from './utils.js';
+
+// Note: We intentionally do not export l1_tx_utils_with_blobs.js
+// to avoid accidentally importing blob-lib dependency.

package/src/l1_tx_utils/interfaces.ts

@@ -0,0 +1,86 @@
+import type { L1BlobInputs, L1TxState } from './types.js';
+
+/**
+ * Interface for L1 transaction state storage.
+ * Implementations handle persistence of transaction states across restarts.
+ */
+export interface IL1TxStore {
+  /**
+   * Gets the next available state ID for an account.
+   */
+  consumeNextStateId(account: string): Promise<number>;
+
+  /**
+   * Saves a single transaction state for a specific account.
+   * Does not save blob data (see saveBlobs).
+   * @param account - The sender account address
+   * @param state - Transaction state to save
+   */
+  saveState(account: string, state: L1TxState): Promise<L1TxState>;
+
+  /**
+   * Saves blobs for a given state.
+   * @param account - The sender account address
+   * @param stateId - The state ID
+   * @param blobInputs - Blob inputs to save
+   */
+  saveBlobs(account: string, stateId: number, blobInputs: L1BlobInputs | undefined): Promise<void>;
+
+  /**
+   * Loads all transaction states for a specific account.
+   * @param account - The sender account address
+   * @returns Array of transaction states with their IDs
+   */
+  loadStates(account: string): Promise<L1TxState[]>;
+
+  /**
+   * Loads a single state by ID.
+   * @param account - The sender account address
+   * @param stateId - The state ID
+   * @returns The transaction state or undefined if not found
+   */
+  loadState(account: string, stateId: number): Promise<L1TxState | undefined>;
+
+  /**
+   * Deletes a specific state and its associated blobs.
+   * @param account - The sender account address
+   * @param stateId - The state ID to delete
+   */
+  deleteState(account: string, ...stateId: number[]): Promise<void>;
+
+  /**
+   * Clears all transaction states for a specific account.
+   * @param account - The sender account address
+   */
+  clearStates(account: string): Promise<void>;
+
+  /**
+   * Gets all accounts that have stored states.
+   * @returns Array of account addresses
+   */
+  getAllAccounts(): Promise<string[]>;
+
+  /**
+   * Closes the store.
+   */
+  close(): Promise<void>;
+}
+
+/**
+ * Interface for L1 transaction metrics recording.
+ * Implementations handle tracking of transaction lifecycle and gas costs.
+ */
+export interface IL1TxMetrics {
+  /**
+   * Records metrics when a transaction is mined
+   * @param state - The L1 transaction state
+   * @param l1Timestamp - The current L1 timestamp
+   */
+  recordMinedTx(state: L1TxState, l1Timestamp: Date): void;
+
+  /**
+   * Records metrics when a transaction is dropped
+   * @param state - The L1 transaction state
+   */
+  recordDroppedTx(state: L1TxState): void;
+}