@aztec/ethereum 2.1.9-rc.2 → 2.1.9-rc.4

package/dest/l1_tx_utils/l1_fee_analyzer.d.ts

@@ -0,0 +1,235 @@
+import { type Logger } from '@aztec/foundation/log';
+import { DateProvider } from '@aztec/foundation/timer';
+import { type Hex } from 'viem';
+import type { ViemClient } from '../types.js';
+import type { L1TxUtilsConfig } from './config.js';
+import { type PriorityFeeStrategy } from './fee-strategies/index.js';
+import type { L1BlobInputs, L1TxRequest } from './types.js';
+/**
+ * Information about a blob transaction in the pending pool or mined block
+ */
+export interface BlobTxInfo {
+    hash: Hex;
+    maxPriorityFeePerGas: bigint;
+    maxFeePerGas: bigint;
+    maxFeePerBlobGas: bigint;
+    blobCount: number;
+    gas: bigint;
+}
+/**
+ * Snapshot of the pending block state at the time of analysis
+ */
+export interface PendingBlockSnapshot {
+    /** Timestamp when the snapshot was taken */
+    timestamp: number;
+    /** The latest L1 block number at the time of snapshot */
+    latestBlockNumber: bigint;
+    /** Base fee per gas of the latest block */
+    baseFeePerGas: bigint;
+    /** Blob base fee at the time of snapshot */
+    blobBaseFee: bigint;
+    /** Total number of transactions in the pending block */
+    pendingTxCount: number;
+    /** Number of blob transactions in the pending block */
+    pendingBlobTxCount: number;
+    /** Total number of blobs in pending blob transactions */
+    pendingBlobCount: number;
+    /** Details of blob transactions in the pending pool */
+    pendingBlobTxs: BlobTxInfo[];
+    /** 75th percentile priority fee from pending transactions */
+    pendingP75PriorityFee: bigint;
+    /** 75th percentile priority fee from pending blob transactions */
+    pendingBlobP75PriorityFee: bigint;
+}
+/**
+ * Result of a strategy's priority fee calculation for analysis
+ */
+export interface StrategyAnalysisResult {
+    /** Strategy ID */
+    strategyId: string;
+    /** Strategy name */
+    strategyName: string;
+    /** Calculated priority fee from this strategy */
+    calculatedPriorityFee: bigint;
+    /** Debug info from the strategy calculation */
+    debugInfo?: Record<string, string | number>;
+    /** Whether this transaction would have been included with this strategy's fee */
+    wouldBeIncluded?: boolean;
+    /** If not included, reason why */
+    exclusionReason?: 'priority_fee_too_low' | 'block_full';
+    /** Priority fee delta compared to minimum included fee */
+    priorityFeeDelta?: bigint;
+    /** Estimated total cost in ETH for this strategy */
+    estimatedCostEth?: number;
+    /** Estimated overpayment in ETH vs minimum required */
+    estimatedOverpaymentEth?: number;
+}
+/**
+ * Transaction metadata and strategy analysis results
+ */
+export interface ComputedGasPrices {
+    /** Estimated gas limit for the transaction */
+    gasLimit: bigint;
+    /** Number of blobs in our transaction */
+    blobCount: number;
+    /** Results from all strategies analyzed */
+    strategyResults?: StrategyAnalysisResult[];
+}
+/**
+ * Information about what actually got included in the mined block
+ */
+export interface MinedBlockInfo {
+    /** The block number that was mined */
+    blockNumber: bigint;
+    /** The block hash */
+    blockHash: Hex;
+    /** Timestamp of the mined block */
+    blockTimestamp: bigint;
+    /** Base fee per gas in the mined block */
+    baseFeePerGas: bigint;
+    /** Blob gas used in the mined block */
+    blobGasUsed: bigint;
+    /** Total number of transactions in the mined block */
+    txCount: number;
+    /** Number of blob transactions that got included */
+    includedBlobTxCount: number;
+    /** Total number of blobs included in the block */
+    includedBlobCount: number;
+    /** Details of blob transactions that got included */
+    includedBlobTxs: BlobTxInfo[];
+    /** Minimum priority fee among included transactions */
+    minIncludedPriorityFee: bigint;
+    /** Minimum priority fee among included blob transactions */
+    minIncludedBlobPriorityFee: bigint;
+}
+/**
+ * Complete fee analysis result comparing our estimates to what happened
+ */
+export interface L1FeeAnalysisResult {
+    /** Unique identifier for this analysis */
+    id: string;
+    /** L2 slot number this analysis was performed for */
+    l2SlotNumber: bigint;
+    /** Snapshot of pending state when we computed our fees */
+    pendingSnapshot: PendingBlockSnapshot;
+    /** Our computed gas prices */
+    computedPrices: ComputedGasPrices;
+    /** Information about what we were trying to send */
+    txInfo: {
+        requestCount: number;
+        hasBlobData: boolean;
+        totalEstimatedGas: bigint;
+    };
+    /** Information about the block that was eventually mined (populated after block mines) */
+    minedBlock?: MinedBlockInfo;
+    /** Analysis results (populated after block mines) */
+    analysis?: {
+        /** Time in ms between our snapshot and block mining */
+        timeBeforeBlockMs: number;
+        /** How many blob txs from pending actually got included */
+        pendingBlobTxsIncludedCount: number;
+        /** How many blob txs from pending were NOT included */
+        pendingBlobTxsExcludedCount: number;
+        /** Number of blobs in the mined block */
+        blobsInBlock: number;
+        /** Maximum blob capacity for this block */
+        maxBlobCapacity: number;
+        /** Whether the block's blob space was full */
+        blockBlobsFull: boolean;
+        /** Actual cost in ETH if this analysis is linked to a mined tx */
+        actualCostEth?: number;
+        /** Strategy results ranked by estimated cost */
+        costRanking?: Array<{
+            strategyId: string;
+            strategyName: string;
+            estimatedCostEth: number;
+            wouldBeIncluded: boolean;
+        }>;
+    };
+}
+/** Callback type for when an analysis is completed */
+export type L1FeeAnalysisCallback = (analysis: L1FeeAnalysisResult) => void;
+/**
+ * Analyzes L1 transaction fees in fisherman mode.
+ * Captures pending block state, records gas calculations, and compares to what gets included.
+ * Supports multiple priority fee calculation strategies for comparison.
+ */
+export declare class L1FeeAnalyzer {
+    private client;
+    private dateProvider;
+    private logger;
+    private maxCompletedAnalyses;
+    private gasConfig;
+    private pendingAnalyses;
+    private pendingCallbacks;
+    private completedAnalyses;
+    private analysisCounter;
+    private strategies;
+    constructor(client: ViemClient, dateProvider?: DateProvider, logger?: Logger, maxCompletedAnalyses?: number, strategies?: PriorityFeeStrategy[], gasConfig?: L1TxUtilsConfig);
+    /**
+     * Executes all configured strategies and returns their results.
+     * Each strategy handles its own RPC calls internally.
+     * @param isBlobTx - Whether this is a blob transaction
+     * @returns Array of strategy results
+     */
+    executeAllStrategies(isBlobTx: boolean): Promise<StrategyAnalysisResult[]>;
+    /**
+     * Captures a snapshot of the current pending block state
+     */
+    capturePendingSnapshot(): Promise<PendingBlockSnapshot>;
+    /**
+     * Starts a fee analysis for a transaction bundle
+     * @param l2SlotNumber - The L2 slot this analysis is for
+     * @param gasLimit - The estimated gas limit
+     * @param requests - The transaction requests being analyzed
+     * @param blobInputs - Blob inputs if this is a blob transaction
+     * @param onComplete - Optional callback to invoke when analysis completes
+     * @returns The analysis ID for tracking
+     */
+    startAnalysis(l2SlotNumber: bigint, gasLimit: bigint, requests: L1TxRequest[], blobInputs?: L1BlobInputs, onComplete?: L1FeeAnalysisCallback): Promise<string>;
+    /**
+     * Watches for the next block to be mined and completes the analysis
+     */
+    private watchForNextBlock;
+    /**
+     * Completes the analysis once the next block is mined
+     */
+    private completeAnalysis;
+    /**
+     * Gets a specific analysis result by ID
+     */
+    getAnalysis(id: string): L1FeeAnalysisResult | undefined;
+    /**
+     * Gets all completed analyses
+     */
+    getCompletedAnalyses(): L1FeeAnalysisResult[];
+    /**
+     * Gets statistics about all completed analyses
+     */
+    getAnalysisStats(): {
+        totalAnalyses: number;
+        avgTimeBeforeBlockMs: number;
+        avgBlobsInBlock: number;
+        blocksBlobsFull: number;
+    };
+    /**
+     * Gets comparative statistics for all strategies across completed analyses
+     */
+    getStrategyComparison(): Array<{
+        strategyId: string;
+        strategyName: string;
+        totalAnalyses: number;
+        inclusionCount: number;
+        inclusionRate: number;
+        avgEstimatedCostEth: number;
+        totalEstimatedCostEth: number;
+        avgOverpaymentEth: number;
+        totalOverpaymentEth: number;
+        avgPriorityFeeDeltaGwei: number;
+    }>;
+    /**
+     * Gets the minimum value from an array of bigints
+     */
+    private minBigInt;
+}
+//# sourceMappingURL=l1_fee_analyzer.d.ts.map

package/dest/l1_tx_utils/l1_fee_analyzer.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"l1_fee_analyzer.d.ts","sourceRoot":"","sources":["../../src/l1_tx_utils/l1_fee_analyzer.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,MAAM,EAAgB,MAAM,uBAAuB,CAAC;AAElE,OAAO,EAAE,YAAY,EAAE,MAAM,yBAAyB,CAAC;AAEvD,OAAO,EAAyC,KAAK,GAAG,EAAc,MAAM,MAAM,CAAC;AAEnF,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AAE9C,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,aAAa,CAAC;AAEnD,OAAO,EAEL,KAAK,mBAAmB,EAEzB,MAAM,2BAA2B,CAAC;AACnC,OAAO,KAAK,EAAE,YAAY,EAAE,WAAW,EAAE,MAAM,YAAY,CAAC;AAE5D;;GAEG;AACH,MAAM,WAAW,UAAU;IACzB,IAAI,EAAE,GAAG,CAAC;IACV,oBAAoB,EAAE,MAAM,CAAC;IAC7B,YAAY,EAAE,MAAM,CAAC;IACrB,gBAAgB,EAAE,MAAM,CAAC;IACzB,SAAS,EAAE,MAAM,CAAC;IAClB,GAAG,EAAE,MAAM,CAAC;CACb;AAED;;GAEG;AACH,MAAM,WAAW,oBAAoB;IACnC,4CAA4C;IAC5C,SAAS,EAAE,MAAM,CAAC;IAClB,yDAAyD;IACzD,iBAAiB,EAAE,MAAM,CAAC;IAC1B,2CAA2C;IAC3C,aAAa,EAAE,MAAM,CAAC;IACtB,4CAA4C;IAC5C,WAAW,EAAE,MAAM,CAAC;IACpB,wDAAwD;IACxD,cAAc,EAAE,MAAM,CAAC;IACvB,uDAAuD;IACvD,kBAAkB,EAAE,MAAM,CAAC;IAC3B,yDAAyD;IACzD,gBAAgB,EAAE,MAAM,CAAC;IACzB,uDAAuD;IACvD,cAAc,EAAE,UAAU,EAAE,CAAC;IAC7B,6DAA6D;IAC7D,qBAAqB,EAAE,MAAM,CAAC;IAC9B,kEAAkE;IAClE,yBAAyB,EAAE,MAAM,CAAC;CACnC;AAED;;GAEG;AACH,MAAM,WAAW,sBAAsB;IACrC,kBAAkB;IAClB,UAAU,EAAE,MAAM,CAAC;IACnB,oBAAoB;IACpB,YAAY,EAAE,MAAM,CAAC;IACrB,iDAAiD;IACjD,qBAAqB,EAAE,MAAM,CAAC;IAC9B,+CAA+C;IAC/C,SAAS,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,CAAC,CAAC;IAC5C,iFAAiF;IACjF,eAAe,CAAC,EAAE,OAAO,CAAC;IAC1B,kCAAkC;IAClC,eAAe,CAAC,EAAE,sBAAsB,GAAG,YAAY,CAAC;IACxD,0DAA0D;IAC1D,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B,oDAAoD;IACpD,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B,uDAAuD;IACvD,uBAAuB,CAAC,EAAE,MAAM,CAAC;CAClC;AAED;;GAEG;AACH,MAAM,WAAW,iBAAiB;IAChC,8CAA8C;IAC9C,QAAQ,EAAE,MAAM,CAAC;IACjB,yCAAyC;IACzC,SAAS,EAAE,MAAM,CAAC;IAClB,2CAA2C;IAC3C,eAAe,CAAC,EAAE,sBAAsB,EAAE,CAAC;CAC5C;AAED;;GAEG;AACH,MAAM,WAAW,cAAc;IAC7B,sCAAsC;IACtC,WAAW,EAAE,MAAM,CAAC;IACpB,qBAAqB;IACrB,SAAS,EAAE,GAAG,CAAC;IACf,mCAAmC;IACnC,cAAc,EAAE,MAAM,CAAC;IACvB,0CAA0C;IAC1C,aAAa,EAAE,MAAM,CAAC;IACtB,uCAAuC;IACvC,WAAW,EAAE,MAAM,CAAC;IACpB,sDAAsD;IACtD,OAAO,EAAE,MAAM,CAAC;IAChB,oDAAoD;IACpD,mBAAmB,EAAE,MAAM,CAAC;IAC5B,kDAAkD;IAClD,iBAAiB,EAAE,MAAM,CAAC;IAC1B,qDAAqD;IACrD,eAAe,EAAE,UAAU,EAAE,CAAC;IAC9B,uDAAuD;IACvD,sBAAsB,EAAE,MAAM,CAAC;IAC/B,4DAA4D;IAC5D,0BAA0B,EAAE,MAAM,CAAC;CACpC;AAED;;GAEG;AACH,MAAM,WAAW,mBAAmB;IAClC,0CAA0C;IAC1C,EAAE,EAAE,MAAM,CAAC;IACX,qDAAqD;IACrD,YAAY,EAAE,MAAM,CAAC;IACrB,0DAA0D;IAC1D,eAAe,EAAE,oBAAoB,CAAC;IACtC,8BAA8B;IAC9B,cAAc,EAAE,iBAAiB,CAAC;IAClC,oDAAoD;IACpD,MAAM,EAAE;QACN,YAAY,EAAE,MAAM,CAAC;QACrB,WAAW,EAAE,OAAO,CAAC;QACrB,iBAAiB,EAAE,MAAM,CAAC;KAC3B,CAAC;IACF,0FAA0F;IAC1F,UAAU,CAAC,EAAE,cAAc,CAAC;IAC5B,qDAAqD;IACrD,QAAQ,CAAC,EAAE;QACT,uDAAuD;QACvD,iBAAiB,EAAE,MAAM,CAAC;QAC1B,2DAA2D;QAC3D,2BAA2B,EAAE,MAAM,CAAC;QACpC,uDAAuD;QACvD,2BAA2B,EAAE,MAAM,CAAC;QACpC,yCAAyC;QACzC,YAAY,EAAE,MAAM,CAAC;QACrB,2CAA2C;QAC3C,eAAe,EAAE,MAAM,CAAC;QACxB,8CAA8C;QAC9C,cAAc,EAAE,OAAO,CAAC;QACxB,kEAAkE;QAClE,aAAa,CAAC,EAAE,MAAM,CAAC;QACvB,gDAAgD;QAChD,WAAW,CAAC,EAAE,KAAK,CAAC;YAClB,UAAU,EAAE,MAAM,CAAC;YACnB,YAAY,EAAE,MAAM,CAAC;YACrB,gBAAgB,EAAE,MAAM,CAAC;YACzB,eAAe,EAAE,OAAO,CAAC;SAC1B,CAAC,CAAC;KACJ,CAAC;CACH;AAED,sDAAsD;AACtD,MAAM,MAAM,qBAAqB,GAAG,CAAC,QAAQ,EAAE,mBAAmB,KAAK,IAAI,CAAC;AAuE5E;;;;GAIG;AACH,qBAAa,aAAa;IAQtB,OAAO,CAAC,MAAM;IACd,OAAO,CAAC,YAAY;IACpB,OAAO,CAAC,MAAM;IACd,OAAO,CAAC,oBAAoB;IAE5B,OAAO,CAAC,SAAS;IAZnB,OAAO,CAAC,eAAe,CAA+C;IACtE,OAAO,CAAC,gBAAgB,CAAiD;IACzE,OAAO,CAAC,iBAAiB,CAA6B;IACtD,OAAO,CAAC,eAAe,CAAK;IAC5B,OAAO,CAAC,UAAU,CAAwB;gBAGhC,MAAM,EAAE,UAAU,EAClB,YAAY,GAAE,YAAiC,EAC/C,MAAM,GAAE,MAAiD,EACzD,oBAAoB,GAAE,MAAY,EAC1C,UAAU,GAAE,mBAAmB,EAAoC,EAC3D,SAAS,GAAE,eAAoB;IAKzC;;;;;OAKG;IACG,oBAAoB,CAAC,QAAQ,EAAE,OAAO,GAAG,OAAO,CAAC,sBAAsB,EAAE,CAAC;IAkChF;;OAEG;IACG,sBAAsB,IAAI,OAAO,CAAC,oBAAoB,CAAC;IAyC7D;;;;;;;;OAQG;IACG,aAAa,CACjB,YAAY,EAAE,MAAM,EACpB,QAAQ,EAAE,MAAM,EAChB,QAAQ,EAAE,WAAW,EAAE,EACvB,UAAU,CAAC,EAAE,YAAY,EACzB,UAAU,CAAC,EAAE,qBAAqB,GACjC,OAAO,CAAC,MAAM,CAAC;IA0DlB;;OAEG;YACW,iBAAiB;IAgC/B;;OAEG;IACH,OAAO,CAAC,gBAAgB;IAiMxB;;OAEG;IACH,WAAW,CAAC,EAAE,EAAE,MAAM,GAAG,mBAAmB,GAAG,SAAS;IAIxD;;OAEG;IACH,oBAAoB,IAAI,mBAAmB,EAAE;IAI7C;;OAEG;IACH,gBAAgB,IAAI;QAClB,aAAa,EAAE,MAAM,CAAC;QACtB,oBAAoB,EAAE,MAAM,CAAC;QAC7B,eAAe,EAAE,MAAM,CAAC;QACxB,eAAe,EAAE,MAAM,CAAC;KACzB;IA2BD;;OAEG;IACH,qBAAqB,IAAI,KAAK,CAAC;QAC7B,UAAU,EAAE,MAAM,CAAC;QACnB,YAAY,EAAE,MAAM,CAAC;QACrB,aAAa,EAAE,MAAM,CAAC;QACtB,cAAc,EAAE,MAAM,CAAC;QACvB,aAAa,EAAE,MAAM,CAAC;QACtB,mBAAmB,EAAE,MAAM,CAAC;QAC5B,qBAAqB,EAAE,MAAM,CAAC;QAC9B,iBAAiB,EAAE,MAAM,CAAC;QAC1B,mBAAmB,EAAE,MAAM,CAAC;QAC5B,uBAAuB,EAAE,MAAM,CAAC;KACjC,CAAC;IAiFF;;OAEG;IACH,OAAO,CAAC,SAAS;CAMlB"}