@aztec/ethereum 0.0.0-test.1 → 0.0.1-commit.21caa21

package/src/l1_tx_utils/config.ts

@@ -0,0 +1,143 @@
+import {
+  type ConfigMappingsType,
+  booleanConfigHelper,
+  floatConfigHelper,
+  getConfigFromMappings,
+  getDefaultConfig,
+  numberConfigHelper,
+} from '@aztec/foundation/config';
+
+export interface L1TxUtilsConfig {
+  /**
+   * How much to increase calculated gas limit.
+   */
+  gasLimitBufferPercentage?: number;
+  /**
+   * Maximum gas price in gwei
+   */
+  maxGwei?: number;
+  /**
+   * Maximum blob fee per gas in gwei
+   */
+  maxBlobGwei?: number;
+  /**
+   * Priority fee bump percentage
+   */
+  priorityFeeBumpPercentage?: number;
+  /**
+   * How much to increase priority fee by each attempt (percentage)
+   */
+  priorityFeeRetryBumpPercentage?: number;
+  /**
+   * Fixed priority fee per gas in Gwei. Overrides any priority fee bump percentage config
+   */
+  fixedPriorityFeePerGas?: number;
+  /**
+   * Maximum number of speed-up attempts
+   */
+  maxSpeedUpAttempts?: number;
+  /**
+   * How often to check tx status
+   */
+  checkIntervalMs?: number;
+  /**
+   * How long before considering tx stalled
+   */
+  stallTimeMs?: number;
+  /**
+   * How long to wait for a tx to be mined before giving up
+   */
+  txTimeoutMs?: number;
+  /**
+   * Whether to attempt to cancel a tx if it's not mined after txTimeoutMs
+   */
+  cancelTxOnTimeout?: boolean;
+  /**
+   * How long to wait for a cancellation tx to be mined after its last attempt before giving up
+   */
+  txCancellationFinalTimeoutMs?: number;
+  /**
+   * How long a tx nonce can be unseen in the mempool before considering it dropped
+   */
+  txUnseenConsideredDroppedMs?: number;
+}
+
+export const l1TxUtilsConfigMappings: ConfigMappingsType<L1TxUtilsConfig> = {
+  gasLimitBufferPercentage: {
+    description: 'How much to increase calculated gas limit by (percentage)',
+    env: 'L1_GAS_LIMIT_BUFFER_PERCENTAGE',
+    ...numberConfigHelper(20),
+  },
+  maxGwei: {
+    description: 'Maximum gas price in gwei to be used for transactions.',
+    env: 'L1_GAS_PRICE_MAX',
+    fallback: ['L1_FEE_PER_GAS_GWEI_MAX'],
+    ...floatConfigHelper(2000),
+  },
+  maxBlobGwei: {
+    description: 'Maximum blob fee per gas in gwei',
+    env: 'L1_BLOB_FEE_PER_GAS_MAX',
+    fallback: ['L1_BLOB_FEE_PER_GAS_GWEI_MAX'],
+    ...floatConfigHelper(3000),
+  },
+  priorityFeeBumpPercentage: {
+    description: 'How much to increase priority fee by each attempt (percentage)',
+    env: 'L1_PRIORITY_FEE_BUMP_PERCENTAGE',
+    ...numberConfigHelper(20),
+  },
+  priorityFeeRetryBumpPercentage: {
+    description: 'How much to increase priority fee by each retry attempt (percentage)',
+    env: 'L1_PRIORITY_FEE_RETRY_BUMP_PERCENTAGE',
+    ...numberConfigHelper(50),
+  },
+  fixedPriorityFeePerGas: {
+    description: 'Fixed priority fee per gas in Gwei. Overrides any priority fee bump percentage',
+    env: 'L1_FIXED_PRIORITY_FEE_PER_GAS',
+    fallback: ['L1_FIXED_PRIORITY_FEE_PER_GAS_GWEI'],
+    ...floatConfigHelper(0),
+  },
+  maxSpeedUpAttempts: {
+    description: 'Maximum number of speed-up attempts',
+    env: 'L1_TX_MONITOR_MAX_ATTEMPTS',
+    ...numberConfigHelper(3),
+  },
+  checkIntervalMs: {
+    description: 'How often to check tx status',
+    env: 'L1_TX_MONITOR_CHECK_INTERVAL_MS',
+    ...numberConfigHelper(1_000),
+  },
+  stallTimeMs: {
+    description: 'How long before considering tx stalled',
+    env: 'L1_TX_MONITOR_STALL_TIME_MS',
+    ...numberConfigHelper(12_000), // 12s, 1 ethereum slot
+  },
+  txTimeoutMs: {
+    description: 'How long to wait for a tx to be mined before giving up. Set to 0 to disable.',
+    env: 'L1_TX_MONITOR_TX_TIMEOUT_MS',
+    ...numberConfigHelper(120_000), // 2 mins
+  },
+  cancelTxOnTimeout: {
+    description: "Whether to attempt to cancel a tx if it's not mined after txTimeoutMs",
+    env: 'L1_TX_MONITOR_CANCEL_TX_ON_TIMEOUT',
+    ...booleanConfigHelper(true),
+  },
+  txCancellationFinalTimeoutMs: {
+    description: 'How long to wait for a cancellation tx after its last attempt before giving up',
+    env: 'L1_TX_MONITOR_TX_CANCELLATION_TIMEOUT_MS',
+    ...numberConfigHelper(24 * 12 * 1000), // 24 L1 blocks
+  },
+  txUnseenConsideredDroppedMs: {
+    description: 'How long a tx nonce can be unseen in the mempool before considering it dropped',
+    env: 'L1_TX_MONITOR_TX_UNSEEN_CONSIDERED_DROPPED_MS',
+    ...numberConfigHelper(6 * 12 * 1000), // 6 L1 blocks
+  },
+};
+
+// We abuse the fact that all mappings above have a non null default value and force-type this to Required
+export const defaultL1TxUtilsConfig = getDefaultConfig<L1TxUtilsConfig>(
+  l1TxUtilsConfigMappings,
+) as Required<L1TxUtilsConfig>;
+
+export function getL1TxUtilsConfigEnvVars(): L1TxUtilsConfig {
+  return getConfigFromMappings(l1TxUtilsConfigMappings);
+}

package/src/l1_tx_utils/constants.ts

@@ -0,0 +1,18 @@
+// 1_000_000_000 Gwei = 1 ETH
+// 1_000_000_000 Wei = 1 Gwei
+// 1_000_000_000_000_000_000 Wei = 1 ETH
+export const WEI_CONST = 1_000_000_000n;
+
+// @note using this large gas limit to avoid the issue of `gas limit too low` when estimating gas in reth
+export const LARGE_GAS_LIMIT = 12_000_000n;
+
+// setting a minimum bump percentage to 10% due to geth's implementation
+// https://github.com/ethereum/go-ethereum/blob/e3d61e6db028c412f74bc4d4c7e117a9e29d0de0/core/txpool/legacypool/list.go#L298
+export const MIN_REPLACEMENT_BUMP_PERCENTAGE = 10;
+
+// setting a minimum bump percentage to 100% due to geth's implementation
+// https://github.com/ethereum/go-ethereum/blob/e3d61e6db028c412f74bc4d4c7e117a9e29d0de0/core/txpool/blobpool/config.go#L34
+export const MIN_BLOB_REPLACEMENT_BUMP_PERCENTAGE = 100;
+
+// Avg ethereum block time is ~12s
+export const BLOCK_TIME_MS = 12_000;

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/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;
+}