@aztec-labs/sequencer-client 6.0.0-nightly.20260829

package/src/publisher/sequencer-bundle-simulator.ts

@@ -0,0 +1,253 @@
+import type { EpochCache } from '@aztec-labs/epoch-cache';
+import { Multicall3, type RollupContract, buildSimulationOverridesStateOverride } from '@aztec-labs/ethereum/contracts';
+import { type L1TxUtils, MAX_L1_TX_LIMIT } from '@aztec-labs/ethereum/l1-tx-utils';
+import { formatViemError } from '@aztec-labs/ethereum/utils';
+import type { SlotNumber } from '@aztec-labs/foundation/branded-types';
+import { type Logger, createLogger } from '@aztec-labs/foundation/log';
+import { getLastL1SlotTimestampForL2Slot } from '@aztec-labs/stdlib/epoch-helpers';
+import type { Hex, StateOverride } from 'viem';
+
+import type { RequestWithExpiry } from './sequencer-publisher.js';
+
+/** A request that was dropped by bundle simulation, with the decoded revert reason. */
+export type DroppedRequest = {
+  request: RequestWithExpiry;
+  revertReason: string | undefined;
+  returnData: Hex | undefined;
+};
+
+/**
+ * Result of {@link SequencerBundleSimulator.simulate}.
+ *
+ * - `success`: simulation succeeded. `requests` is the filtered survivor list, `gasLimit` is
+ *   the bumped gas limit derived from `gasUsed` (plus blob evaluation gas). `droppedRequests`
+ *   lists the entries that were observed to revert in simulation.
+ * - `fallback`: the node does not support eth_simulateV1 (or the simulate call threw). The
+ *   caller should send `requests` as-is with a safe gas limit (e.g. {@link MAX_L1_TX_LIMIT}).
+ *   `droppedRequests` carries any entries that the first pass already proved reverted, so the
+ *   caller does not re-include them when the second pass falls back.
+ * - `aborted`: the bundle cannot be sent. `droppedRequests` contains only entries that were
+ *   actually observed to revert (so they can be reported as simulation failures); it is empty
+ *   when the abort was caused by an empty input bundle.
+ */
+export type BundleSimulateResult =
+  | { kind: 'success'; requests: RequestWithExpiry[]; gasLimit: bigint; droppedRequests: DroppedRequest[] }
+  | { kind: 'fallback'; requests: RequestWithExpiry[]; droppedRequests: DroppedRequest[] }
+  | { kind: 'aborted'; reason: AbortReason; droppedRequests: DroppedRequest[] };
+
+export type AbortReason = 'empty-bundle' | 'all-reverted' | 'second-pass-reverts';
+
+type SimulatePassResult =
+  | { kind: 'decoded'; survivors: RequestWithExpiry[]; droppedRequests: DroppedRequest[]; gasUsed: bigint }
+  | { kind: 'fallback' };
+
+/**
+ * Bundle-level simulator for the aggregate3 payload that `SequencerPublisher` is about to send.
+ *
+ * Runs `eth_simulateV1` against `Multicall3.aggregate3`, drops entries that revert, and returns
+ * a gasLimit for the survivors. When `eth_simulateV1` is unavailable, signals fallback to the
+ * caller so it can send the bundle as-is with a conservative gas limit.
+ */
+export class SequencerBundleSimulator {
+  private readonly log: Logger;
+
+  constructor(
+    private readonly deps: {
+      getL1TxUtils: () => L1TxUtils;
+      rollupContract: RollupContract;
+      epochCache: EpochCache;
+      log?: Logger;
+    },
+  ) {
+    this.log = deps.log ?? createLogger('sequencer:publisher:bundle-simulator');
+  }
+
+  /**
+   * Simulates the given bundle near the end of the target slot and filters out entries
+   * that revert.
+   *
+   * - If all entries pass on the first pass, returns `success` with the gasLimit.
+   * - If some entries revert, re-simulates the survivors. If the second pass is clean, returns
+   *   `success` with the survivors and dropped entries. If the second pass surfaces any revert,
+   *   returns `aborted` — we refuse to send a bundle whose composition still has internal
+   *   reverts after one round of filtering.
+   * - If eth_simulateV1 is unavailable, returns `fallback`. The caller is expected to send the
+   *   bundle as-is with a safe gas limit.
+   *
+   * The simulation `block.timestamp` is the last L1 slot timestamp inside the target L2 slot.
+   * This still maps to the target L2 slot for propose's `validateHeader` and EIP-712 signature
+   * checks, while avoiding eth_simulateV1 rejecting a child block whose timestamp is not strictly
+   * greater than the current L1 head.
+   *
+   * Known limitation: on networks where L1 is mining behind cadence (missed L1 slots, anvil with
+   * overridden timestamps), the actual `block.timestamp` at send time can land in the prior L2
+   * slot. In that case `propose` would revert silently inside the multicall. The simulator does
+   * not detect this case because it simulates inside the target slot — the prior implementation
+   * used `min(predictedNextL1Ts, targetTimestamp)` to surface this failure mode at simulate time.
+   */
+  public async simulate(validRequests: RequestWithExpiry[], targetSlot: SlotNumber): Promise<BundleSimulateResult> {
+    if (validRequests.length === 0) {
+      return { kind: 'aborted', reason: 'empty-bundle', droppedRequests: [] };
+    }
+    // Pin the publisher we'll use across the whole simulate call so that the publisher's rotation
+    // can't change l1TxUtils mid-flight.
+    const l1TxUtils = this.deps.getL1TxUtils();
+
+    const proposeRequest = validRequests.find(r => r.action === 'propose');
+    const simulateTimestamp = getLastL1SlotTimestampForL2Slot(targetSlot, this.deps.epochCache.getL1Constants());
+    const firstPassOverrides = await this.buildStateOverrides(!!proposeRequest);
+
+    const firstPass = await this.simulateAndDecode(l1TxUtils, validRequests, simulateTimestamp, firstPassOverrides);
+
+    if (firstPass.kind === 'fallback') {
+      this.log.warn('Bundle simulate fallback (eth_simulateV1 unavailable); caller will send bundle as-is', {
+        actions: validRequests.map(r => r.action),
+      });
+      return { kind: 'fallback', requests: validRequests, droppedRequests: [] };
+    }
+
+    if (firstPass.survivors.length === 0) {
+      this.log.warn('All bundle entries dropped in simulation; aborting send', {
+        actions: validRequests.map(r => r.action),
+      });
+      return { kind: 'aborted', reason: 'all-reverted', droppedRequests: firstPass.droppedRequests };
+    }
+
+    if (firstPass.droppedRequests.length === 0) {
+      return this.buildSuccessResult(l1TxUtils, firstPass.survivors, [], firstPass.gasUsed, proposeRequest);
+    }
+
+    this.log.warn('Some bundle entries reverted; re-simulating reduced bundle', {
+      droppedActions: firstPass.droppedRequests.map(d => d.request.action),
+      remainingActions: firstPass.survivors.map(r => r.action),
+    });
+
+    // Rebuild overrides for the reduced bundle: if propose was dropped, we no longer need the blob-check override
+    const proposeSurvived = proposeRequest !== undefined && firstPass.survivors.includes(proposeRequest);
+    const secondPassOverrides = proposeSurvived ? firstPassOverrides : await this.buildStateOverrides(false);
+    const secondPass = await this.simulateAndDecode(
+      l1TxUtils,
+      firstPass.survivors,
+      simulateTimestamp,
+      secondPassOverrides,
+    );
+
+    if (secondPass.kind === 'fallback') {
+      this.log.warn(
+        'Bundle simulate errored on second pass (eth_simulateV1 unavailable); sending first-pass survivors as-is',
+        {
+          actions: firstPass.survivors.map(r => r.action),
+          droppedActions: firstPass.droppedRequests.map(d => d.request.action),
+        },
+      );
+      return { kind: 'fallback', requests: firstPass.survivors, droppedRequests: firstPass.droppedRequests };
+    }
+
+    // We refuse to chase reverts through repeated trimming: anything other than a clean second pass aborts the whole send
+    if (secondPass.droppedRequests.length > 0) {
+      this.log.error('Re-simulate surfaced reverts; aborting send', {
+        secondPassDroppedActions: secondPass.droppedRequests.map(d => d.request.action),
+      });
+      return {
+        kind: 'aborted',
+        reason: 'second-pass-reverts',
+        droppedRequests: [...firstPass.droppedRequests, ...secondPass.droppedRequests],
+      };
+    }
+
+    return this.buildSuccessResult(
+      l1TxUtils,
+      secondPass.survivors,
+      firstPass.droppedRequests,
+      secondPass.gasUsed,
+      proposeRequest,
+    );
+  }
+
+  private buildSuccessResult(
+    l1TxUtils: L1TxUtils,
+    survivors: RequestWithExpiry[],
+    droppedRequests: DroppedRequest[],
+    bundleGasUsed: bigint,
+    proposeRequest: RequestWithExpiry | undefined,
+  ): BundleSimulateResult {
+    const proposeSurvived = proposeRequest !== undefined && survivors.includes(proposeRequest);
+    const blobEvaluationGas = proposeSurvived ? (proposeRequest?.blobEvaluationGas ?? 0n) : 0n;
+    const gasLimit = this.computeGasLimit(l1TxUtils, bundleGasUsed, blobEvaluationGas);
+    this.log.debug('Bundle simulate complete', {
+      survivingRequests: survivors.length,
+      bundleGasUsed,
+      gasLimit,
+      actions: survivors.map(r => r.action),
+    });
+    return { kind: 'success', requests: survivors, gasLimit, droppedRequests };
+  }
+
+  /**
+   * `gasLimit = bumpGasLimit(ceil(gasUsed * 64 / 63))`, plus blob evaluation gas if a propose
+   * survived, capped at the L1 block gas limit.
+   */
+  private computeGasLimit(l1TxUtils: L1TxUtils, bundleGasUsed: bigint, blobEvaluationGas: bigint): bigint {
+    const gasUsedWithEip150 = (bundleGasUsed * 64n + 62n) / 63n;
+    const gasLimit = l1TxUtils.bumpGasLimit(gasUsedWithEip150) + blobEvaluationGas;
+    return gasLimit > MAX_L1_TX_LIMIT ? MAX_L1_TX_LIMIT : gasLimit;
+  }
+
+  /**
+   * eth_simulateV1 cannot carry blob sidecar data, so disable the rollup's on-chain blob check
+   * when a propose is in the bundle.
+   */
+  private buildStateOverrides(hasProposeAction: boolean): Promise<StateOverride> {
+    return buildSimulationOverridesStateOverride(
+      this.deps.rollupContract,
+      hasProposeAction ? { disableBlobCheck: true } : undefined,
+    );
+  }
+
+  private async simulateAndDecode(
+    l1TxUtils: L1TxUtils,
+    requests: RequestWithExpiry[],
+    simulateTimestamp: bigint,
+    stateOverrides: StateOverride,
+  ): Promise<SimulatePassResult> {
+    let simResult: Awaited<ReturnType<typeof Multicall3.simulateAggregate3>>;
+    try {
+      simResult = await Multicall3.simulateAggregate3(
+        requests.map(r => ({ to: r.request.to! as Hex, data: r.request.data! as Hex, abi: r.request.abi })),
+        l1TxUtils,
+        {
+          blockOverrides: { time: simulateTimestamp, gasLimit: MAX_L1_TX_LIMIT * 2n },
+          stateOverrides,
+          gas: MAX_L1_TX_LIMIT,
+          fallbackGasEstimate: MAX_L1_TX_LIMIT,
+        },
+      );
+    } catch (err) {
+      this.log.warn('Bundle simulate threw; treating as fallback', {
+        err: formatViemError(err),
+        actions: requests.map(r => r.action),
+      });
+      return { kind: 'fallback' };
+    }
+
+    if (simResult.kind === 'fallback') {
+      return { kind: 'fallback' };
+    }
+
+    const survivors: RequestWithExpiry[] = [];
+    const droppedRequests: DroppedRequest[] = [];
+    for (let i = 0; i < requests.length; i++) {
+      const entry = simResult.entries[i];
+      if (entry.success) {
+        survivors.push(requests[i]);
+        continue;
+      }
+      droppedRequests.push({
+        request: requests[i],
+        revertReason: entry.revertReason,
+        returnData: entry.returnData,
+      });
+    }
+    return { kind: 'decoded', survivors, droppedRequests, gasUsed: simResult.gasUsed };
+  }
+}

package/src/publisher/sequencer-publisher-factory.ts

@@ -0,0 +1,121 @@
+import type { BlobClientInterface } from '@aztec-labs/blob-client/client';
+import type { EpochCache } from '@aztec-labs/epoch-cache';
+import type { GovernanceProposerContract, RollupContract } from '@aztec-labs/ethereum/contracts';
+import type { L1TxUtils } from '@aztec-labs/ethereum/l1-tx-utils';
+import type { PublisherFilter, PublisherManager } from '@aztec-labs/ethereum/publisher-manager';
+import { SlotNumber } from '@aztec-labs/foundation/branded-types';
+import { EthAddress } from '@aztec-labs/foundation/eth-address';
+import { type Logger, createLogger } from '@aztec-labs/foundation/log';
+import type { DateProvider } from '@aztec-labs/foundation/timer';
+import type { TelemetryClient } from '@aztec-labs/telemetry-client';
+import { NodeKeystoreAdapter } from '@aztec-labs/validator-client';
+
+import type { SequencerClientConfig } from '../config.js';
+import { SequencerPublisherMetrics } from './sequencer-publisher-metrics.js';
+import { type Action, SequencerPublisher } from './sequencer-publisher.js';
+
+export type AttestorPublisherPair = {
+  attestorAddress: EthAddress;
+  publisher: SequencerPublisher;
+};
+
+export class SequencerPublisherFactory {
+  private publisherMetrics: SequencerPublisherMetrics;
+
+  /** Stores the last slot in which every action was carried out by a publisher */
+  private lastActions: Partial<Record<Action, SlotNumber>> = {};
+
+  private nodeKeyStore: NodeKeystoreAdapter;
+
+  private logger: Logger;
+
+  constructor(
+    private sequencerConfig: SequencerClientConfig,
+    private deps: {
+      telemetry: TelemetryClient;
+      publisherManager: PublisherManager<L1TxUtils>;
+      blobClient: BlobClientInterface;
+      dateProvider: DateProvider;
+      epochCache: EpochCache;
+      rollupContract: RollupContract;
+      governanceProposerContract: GovernanceProposerContract;
+      nodeKeyStore: NodeKeystoreAdapter;
+      logger?: Logger;
+    },
+  ) {
+    this.publisherMetrics = new SequencerPublisherMetrics(deps.telemetry, 'SequencerPublisher');
+    this.logger = deps.logger ?? createLogger('sequencer');
+    this.nodeKeyStore = this.deps.nodeKeyStore;
+  }
+
+  /**
+   * Updates the node keystore adapter used for publisher lookups.
+   * Called when the keystore is reloaded at runtime to reflect new validator-publisher mappings.
+   */
+  public updateNodeKeyStore(adapter: NodeKeystoreAdapter): void {
+    this.nodeKeyStore = adapter;
+  }
+
+  /**
+   * Creates a new SequencerPublisher instance.
+   * @param _validatorAddress - The address of the validator that will be using the publisher.
+   * @returns A new SequencerPublisher instance.
+   */
+  public async create(validatorAddress?: EthAddress): Promise<AttestorPublisherPair> {
+    // If we have been given an attestor address we must only allow publishers permitted for that attestor
+
+    const allowedPublishers = !validatorAddress ? [] : this.nodeKeyStore.getPublisherAddresses(validatorAddress);
+    const filter: PublisherFilter<L1TxUtils> = !validatorAddress
+      ? () => true
+      : (utils: L1TxUtils) => {
+          const publisherAddress = utils.getSenderAddress();
+          return allowedPublishers.some(allowedPublisher => allowedPublisher.equals(publisherAddress));
+        };
+
+    const l1Publisher = await this.deps.publisherManager.getAvailablePublisher(filter);
+    const attestorAddress =
+      validatorAddress ?? this.nodeKeyStore.getAttestorForPublisher(l1Publisher.getSenderAddress());
+
+    const rollup = this.deps.rollupContract;
+    const slashingProposerContract = await rollup.getSlashingProposer();
+
+    const getNextPublisher = async (excludeAddresses: EthAddress[]): Promise<L1TxUtils | undefined> => {
+      const exclusionFilter: PublisherFilter<L1TxUtils> = (utils: L1TxUtils) => {
+        if (excludeAddresses.some(addr => addr.equals(utils.getSenderAddress()))) {
+          return false;
+        }
+        return filter(utils);
+      };
+      try {
+        return await this.deps.publisherManager.getAvailablePublisher(exclusionFilter);
+      } catch {
+        return undefined;
+      }
+    };
+
+    const publisher = new SequencerPublisher(this.sequencerConfig, {
+      l1TxUtils: l1Publisher,
+      getNextPublisher,
+      telemetry: this.deps.telemetry,
+      blobClient: this.deps.blobClient,
+      rollupContract: this.deps.rollupContract,
+      epochCache: this.deps.epochCache,
+      governanceProposerContract: this.deps.governanceProposerContract,
+      slashingProposerContract,
+      dateProvider: this.deps.dateProvider,
+      metrics: this.publisherMetrics,
+      lastActions: this.lastActions,
+      log: this.logger.createChild('publisher'),
+    });
+
+    return {
+      attestorAddress,
+      publisher,
+    };
+  }
+
+  /** Stops all publishers managed by this factory. Used during sequencer shutdown. */
+  public async stopAll(): Promise<void> {
+    await this.deps.publisherManager.stop();
+  }
+}

package/src/publisher/sequencer-publisher-metrics.ts

@@ -0,0 +1,145 @@
+import { createLogger } from '@aztec-labs/foundation/log';
+import type { L1PublishCheckpointStats, L1PublishStats } from '@aztec-labs/stdlib/stats';
+import {
+  Attributes,
+  type Gauge,
+  type Histogram,
+  Metrics,
+  type TelemetryClient,
+  type UpDownCounter,
+  createUpDownCounterWithDefault,
+} from '@aztec-labs/telemetry-client';
+import { formatEther } from 'viem/utils';
+
+export type L1TxType = 'process';
+
+export class SequencerPublisherMetrics {
+  private gasPrice: Histogram;
+
+  private txCount: UpDownCounter;
+  private txDuration: Histogram;
+  private txGas: Histogram;
+  private txCalldataSize: Histogram;
+  private txCalldataGas: Histogram;
+  private txBlobDataGasUsed: Histogram;
+  private txBlobDataGasCost: Histogram;
+  private txTotalFee: Histogram;
+
+  private readonly blobCountHistogram: Histogram;
+  private readonly blobInclusionBlocksHistogram: Histogram;
+  private readonly blobTxSuccessCounter: UpDownCounter;
+  private readonly blobTxFailureCounter: UpDownCounter;
+
+  private senderBalance: Gauge;
+
+  constructor(
+    client: TelemetryClient,
+    name = 'SequencerPublisher',
+    private logger = createLogger('sequencer:publisher:metrics'),
+  ) {
+    const meter = client.getMeter(name);
+
+    this.gasPrice = meter.createHistogram(Metrics.L1_PUBLISHER_GAS_PRICE);
+
+    this.txCount = createUpDownCounterWithDefault(meter, Metrics.L1_PUBLISHER_TX_COUNT, {
+      [Attributes.L1_TX_TYPE]: ['process'],
+      [Attributes.OK]: [true, false],
+    });
+
+    this.txDuration = meter.createHistogram(Metrics.L1_PUBLISHER_TX_DURATION);
+
+    this.txGas = meter.createHistogram(Metrics.L1_PUBLISHER_TX_GAS);
+
+    this.txCalldataSize = meter.createHistogram(Metrics.L1_PUBLISHER_TX_CALLDATA_SIZE);
+
+    this.txCalldataGas = meter.createHistogram(Metrics.L1_PUBLISHER_TX_CALLDATA_GAS);
+
+    this.txBlobDataGasUsed = meter.createHistogram(Metrics.L1_PUBLISHER_TX_BLOBDATA_GAS_USED);
+
+    this.txBlobDataGasCost = meter.createHistogram(Metrics.L1_PUBLISHER_TX_BLOBDATA_GAS_COST);
+
+    this.blobCountHistogram = meter.createHistogram(Metrics.L1_PUBLISHER_BLOB_COUNT);
+
+    this.blobInclusionBlocksHistogram = meter.createHistogram(Metrics.L1_PUBLISHER_BLOB_INCLUSION_BLOCKS);
+
+    this.blobTxSuccessCounter = createUpDownCounterWithDefault(meter, Metrics.L1_PUBLISHER_BLOB_TX_SUCCESS);
+
+    this.blobTxFailureCounter = createUpDownCounterWithDefault(meter, Metrics.L1_PUBLISHER_BLOB_TX_FAILURE);
+
+    this.txTotalFee = meter.createHistogram(Metrics.L1_PUBLISHER_TX_TOTAL_FEE);
+
+    this.senderBalance = meter.createGauge(Metrics.L1_PUBLISHER_BALANCE);
+  }
+
+  recordFailedTx(txType: L1TxType) {
+    this.txCount.add(1, {
+      [Attributes.L1_TX_TYPE]: txType,
+      [Attributes.OK]: false,
+    });
+
+    if (txType === 'process') {
+      this.blobTxFailureCounter.add(1);
+    }
+  }
+
+  recordProcessBlockTx(durationMs: number, stats: L1PublishCheckpointStats) {
+    this.recordTx('process', durationMs, stats);
+
+    if (stats.blobCount && stats.blobCount > 0) {
+      this.blobCountHistogram.record(stats.blobCount);
+
+      if (stats.inclusionBlocks !== undefined) {
+        this.blobInclusionBlocksHistogram.record(stats.inclusionBlocks);
+      }
+
+      this.blobTxSuccessCounter.add(1);
+    }
+  }
+
+  recordSenderBalance(wei: bigint, senderAddress: string) {
+    const eth = parseFloat(formatEther(wei, 'wei'));
+    this.senderBalance.record(eth, {
+      [Attributes.SENDER_ADDRESS]: senderAddress,
+    });
+  }
+
+  private recordTx(txType: L1TxType, durationMs: number, stats: L1PublishStats) {
+    const attributes = {
+      [Attributes.L1_TX_TYPE]: txType,
+      [Attributes.L1_SENDER]: stats.sender,
+    } as const;
+
+    this.txCount.add(1, {
+      ...attributes,
+      [Attributes.OK]: true,
+    });
+
+    this.txDuration.record(Math.ceil(durationMs), attributes);
+    this.txGas.record(
+      // safe to downcast - total block limit is 30M gas which fits in a JS number
+      Number(stats.gasUsed),
+      attributes,
+    );
+    this.txCalldataGas.record(stats.calldataGas, attributes);
+    this.txCalldataSize.record(stats.calldataSize, attributes);
+
+    this.txBlobDataGasCost.record(Number(stats.blobDataGas), attributes);
+    this.txBlobDataGasUsed.record(Number(stats.blobGasUsed), attributes);
+
+    try {
+      this.gasPrice.record(parseInt(formatEther(stats.gasPrice, 'gwei'), 10));
+    } catch {
+      // ignore
+    }
+
+    const executionFee = stats.gasUsed * stats.gasPrice;
+    const blobFee = stats.blobGasUsed * stats.blobDataGas;
+    const totalFee = executionFee + blobFee;
+
+    try {
+      this.txTotalFee.record(parseFloat(formatEther(totalFee)));
+    } catch {
+      // ignore
+    }
+  }
+}