@aztec/prover-node 0.0.0-test.1 → 0.0.1-commit.017a351

package/src/prover-node-publisher.ts

@@ -1,48 +1,47 @@
-import { AGGREGATION_OBJECT_LENGTH, AZTEC_MAX_EPOCH_DURATION } from '@aztec/constants';
-import type { L1TxUtils, RollupContract } from '@aztec/ethereum';
+import { BatchedBlob, getEthBlobEvaluationInputs } from '@aztec/blob-lib';
+import { MAX_CHECKPOINTS_PER_EPOCH } from '@aztec/constants';
+import type { RollupContract, ViemCommitteeAttestation } from '@aztec/ethereum/contracts';
+import type { L1TxUtils } from '@aztec/ethereum/l1-tx-utils';
 import { makeTuple } from '@aztec/foundation/array';
-import { areArraysEqual, times } from '@aztec/foundation/collection';
+import { CheckpointNumber, EpochNumber } from '@aztec/foundation/branded-types';
+import { areArraysEqual } from '@aztec/foundation/collection';
+import { Fr } from '@aztec/foundation/curves/bn254';
 import { EthAddress } from '@aztec/foundation/eth-address';
-import { Fr } from '@aztec/foundation/fields';
-import { createLogger } from '@aztec/foundation/log';
-import { type Tuple, serializeToBuffer } from '@aztec/foundation/serialize';
-import { InterruptibleSleep } from '@aztec/foundation/sleep';
+import { type Logger, type LoggerBindings, createLogger } from '@aztec/foundation/log';
+import { retryUntil } from '@aztec/foundation/retry';
+import type { Tuple } from '@aztec/foundation/serialize';
 import { Timer } from '@aztec/foundation/timer';
 import { RollupAbi } from '@aztec/l1-artifacts';
 import type { PublisherConfig, TxSenderConfig } from '@aztec/sequencer-client';
+import { CommitteeAttestation, CommitteeAttestationsAndSigners } from '@aztec/stdlib/block';
+import { getProofSubmissionDeadlineTimestamp } from '@aztec/stdlib/epoch-helpers';
 import type { Proof } from '@aztec/stdlib/proofs';
 import type { FeeRecipient, RootRollupPublicInputs } from '@aztec/stdlib/rollup';
 import type { L1PublishProofStats } from '@aztec/stdlib/stats';
 import { type TelemetryClient, getTelemetryClient } from '@aztec/telemetry-client';
 
-import { type Hex, type TransactionReceipt, encodeFunctionData } from 'viem';
+import { inspect } from 'util';
+import { type Hex, type TransactionReceipt, encodeFunctionData, formatEther, formatGwei } from 'viem';
 
-import { ProverNodeMetrics } from './metrics.js';
+import { type EstimatedSubmitProofStats, ProverNodePublisherMetrics } from './metrics.js';
 
-/**
- * Stats for a sent transaction.
- */
 /** Arguments to the submitEpochProof method of the rollup contract */
 export type L1SubmitEpochProofArgs = {
   epochSize: number;
   previousArchive: Fr;
   endArchive: Fr;
-  previousBlockHash: Fr;
-  endBlockHash: Fr;
   endTimestamp: Fr;
   outHash: Fr;
   proverId: Fr;
-  fees: Tuple<FeeRecipient, typeof AZTEC_MAX_EPOCH_DURATION>;
+  fees: Tuple<FeeRecipient, typeof MAX_CHECKPOINTS_PER_EPOCH>;
   proof: Proof;
 };
 
 export class ProverNodePublisher {
-  private interruptibleSleep = new InterruptibleSleep();
-  private sleepTimeMs: number;
   private interrupted = false;
-  private metrics: ProverNodeMetrics;
+  private metrics: ProverNodePublisherMetrics;
 
-  protected log = createLogger('prover-node:l1-tx-publisher');
+  protected log: Logger;
 
   protected rollupContract: RollupContract;
 
@@ -55,17 +54,21 @@ export class ProverNodePublisher {
       l1TxUtils: L1TxUtils;
       telemetry?: TelemetryClient;
     },
+    bindings?: LoggerBindings,
   ) {
-    this.sleepTimeMs = config?.l1PublishRetryIntervalMS ?? 60_000;
-
     const telemetry = deps.telemetry ?? getTelemetryClient();
 
-    this.metrics = new ProverNodeMetrics(telemetry, 'ProverNode');
+    this.metrics = new ProverNodePublisherMetrics(telemetry, 'ProverNode');
+    this.log = createLogger('prover-node:l1-tx-publisher', bindings);
 
     this.rollupContract = deps.rollupContract;
     this.l1TxUtils = deps.l1TxUtils;
   }
 
+  public getRollupContract() {
+    return this.rollupContract;
+  }
+
   /**
    * Calling `interrupt` will cause any in progress call to `publishRollup` to return `false` asap.
    * Be warned, the call may return false even if the tx subsequently gets successfully mined.
@@ -74,46 +77,58 @@ export class ProverNodePublisher {
    */
   public interrupt() {
     this.interrupted = true;
-    this.interruptibleSleep.interrupt();
+    this.l1TxUtils.interrupt();
   }
 
   /** Restarts the publisher after calling `interrupt`. */
   public restart() {
     this.interrupted = false;
+    this.l1TxUtils.restart();
   }
 
   public getSenderAddress() {
-    return EthAddress.fromString(this.l1TxUtils.getSenderAddress());
+    return this.l1TxUtils.getSenderAddress();
   }
 
   public async submitEpochProof(args: {
-    epochNumber: number;
-    fromBlock: number;
-    toBlock: number;
+    epochNumber: EpochNumber;
+    fromCheckpoint: CheckpointNumber;
+    toCheckpoint: CheckpointNumber;
     publicInputs: RootRollupPublicInputs;
     proof: Proof;
+    batchedBlobInputs: BatchedBlob;
+    attestations: ViemCommitteeAttestation[];
   }): Promise<boolean> {
-    const { epochNumber, fromBlock, toBlock } = args;
-    const ctx = { epochNumber, fromBlock, toBlock };
+    const { epochNumber, fromCheckpoint, toCheckpoint } = args;
+    const ctx = { epochNumber, fromCheckpoint, toCheckpoint };
+
     if (!this.interrupted) {
-      const timer = new Timer();
+      if (!(await this.waitUntilStartBuildsOnProven(args))) {
+        this.log.verbose('Checkpoint data syncing interrupted', ctx);
+        return false;
+      }
 
+      const timer = new Timer();
       // Validate epoch proof range and hashes are correct before submitting
       await this.validateEpochProofSubmission(args);
 
       const txReceipt = await this.sendSubmitEpochProofTx(args);
       if (!txReceipt) {
+        this.log.error(`Failed to mine submitEpochProof tx`, undefined, ctx);
         return false;
       }
 
       try {
-        this.metrics.recordSenderBalance(await this.l1TxUtils.getSenderBalance(), this.l1TxUtils.getSenderAddress());
+        this.metrics.recordSenderBalance(
+          await this.l1TxUtils.getSenderBalance(),
+          this.l1TxUtils.getSenderAddress().toString(),
+        );
       } catch (err) {
         this.log.warn(`Failed to record the ETH balance of the prover node: ${err}`);
       }
 
       // Tx was mined successfully
-      if (txReceipt.status) {
+      if (txReceipt.status === 'success') {
         const tx = await this.l1TxUtils.getTransactionStats(txReceipt.transactionHash);
         const stats: L1PublishProofStats = {
           gasPrice: txReceipt.effectiveGasPrice,
@@ -132,155 +147,383 @@ export class ProverNodePublisher {
       }
 
       this.metrics.recordFailedTx();
-      this.log.error(`Rollup.submitEpochProof tx status failed: ${txReceipt.transactionHash}`, ctx);
-      await this.sleepOrInterrupted();
+      this.log.error(`Rollup submitEpochProof tx reverted ${txReceipt.transactionHash}`, undefined, ctx);
     }
 
-    this.log.verbose('L2 block data syncing interrupted while processing blocks.', ctx);
+    this.log.verbose('Checkpoint data syncing interrupted', ctx);
     return false;
   }
 
+  private async waitUntilStartBuildsOnProven(args: { epochNumber: EpochNumber; fromCheckpoint: CheckpointNumber }) {
+    const { epochNumber, fromCheckpoint } = args;
+    const provenCheckpoint = await this.getProvenCheckpoint();
+    if (this.isStartBuildingOnProven(fromCheckpoint, provenCheckpoint)) {
+      return true;
+    }
+
+    const timeout = await this.getSecondsUntilProofSubmissionWindowEnd(epochNumber);
+    this.log.info(`Waiting for proven checkpoint to reach proof start`, {
+      epochNumber,
+      fromCheckpoint,
+      provenCheckpoint,
+      timeout,
+    });
+
+    await retryUntil(
+      async () => {
+        if (this.interrupted) {
+          return true;
+        }
+
+        const proven = await this.getProvenCheckpoint();
+        this.log.verbose(`Proven checkpoint is at ${proven} (waiting for ${fromCheckpoint - 1})`, { epochNumber });
+        return this.isStartBuildingOnProven(fromCheckpoint, proven) ? true : undefined;
+      },
+      `proven checkpoint to reach ${fromCheckpoint - 1}`,
+      timeout,
+      4,
+    );
+
+    return !this.interrupted;
+  }
+
+  private async getProvenCheckpoint() {
+    return (await this.rollupContract.getTips()).proven;
+  }
+
+  private isStartBuildingOnProven(fromCheckpoint: CheckpointNumber, provenCheckpoint: CheckpointNumber) {
+    return fromCheckpoint - 1 <= provenCheckpoint;
+  }
+
+  private async getSecondsUntilProofSubmissionWindowEnd(epochNumber: EpochNumber) {
+    const deadline = getProofSubmissionDeadlineTimestamp(epochNumber, await this.rollupContract.getRollupConstants());
+    const now = BigInt(Math.floor(Date.now() / 1000));
+    return Math.max(Number(deadline - now), 0.001);
+  }
+
   private async validateEpochProofSubmission(args: {
-    fromBlock: number;
-    toBlock: number;
+    fromCheckpoint: CheckpointNumber;
+    toCheckpoint: CheckpointNumber;
     publicInputs: RootRollupPublicInputs;
     proof: Proof;
+    batchedBlobInputs: BatchedBlob;
+    attestations: ViemCommitteeAttestation[];
   }) {
-    const { fromBlock, toBlock, publicInputs, proof } = args;
+    const { fromCheckpoint, toCheckpoint, publicInputs, batchedBlobInputs } = args;
 
-    // Check that the block numbers match the expected epoch to be proven
-    const { pendingBlockNumber: pending, provenBlockNumber: proven } = await this.rollupContract.getTips();
-    if (proven !== BigInt(fromBlock) - 1n) {
-      throw new Error(`Cannot submit epoch proof for ${fromBlock}-${toBlock} as proven block is ${proven}`);
+    // Check that the checkpoint numbers match the expected epoch to be proven
+    const { pending, proven } = await this.rollupContract.getTips();
+    // Don't publish if proven is beyond our toCheckpoint, pointless to do so
+    if (proven > toCheckpoint) {
+      throw new Error(
+        `Cannot submit epoch proof for ${fromCheckpoint}-${toCheckpoint} as proven checkpoint is ${proven}`,
+      );
     }
-    if (toBlock > pending) {
-      throw new Error(`Cannot submit epoch proof for ${fromBlock}-${toBlock} as pending block is ${pending}`);
+    // toCheckpoint can't be greater than pending
+    if (toCheckpoint > pending) {
+      throw new Error(
+        `Cannot submit epoch proof for ${fromCheckpoint}-${toCheckpoint} as proposed checkpoint is ${pending}`,
+      );
     }
 
-    // Check the block hash and archive for the immediate block before the epoch
-    const blockLog = await this.rollupContract.getBlock(proven);
-    if (publicInputs.previousArchive.root.toString() !== blockLog.archive) {
+    // Check the archive for the immediate checkpoint before the epoch
+    const checkpointLog = await this.rollupContract.getCheckpoint(CheckpointNumber(fromCheckpoint - 1));
+    if (!publicInputs.previousArchiveRoot.equals(checkpointLog.archive)) {
       throw new Error(
-        `Previous archive root mismatch: ${publicInputs.previousArchive.root.toString()} !== ${blockLog.archive}`,
+        `Previous archive root mismatch: ${publicInputs.previousArchiveRoot.toString()} !== ${checkpointLog.archive.toString()}`,
       );
     }
-    // TODO: Remove zero check once we inject the proper zero blockhash
-    if (blockLog.blockHash !== Fr.ZERO.toString() && publicInputs.previousBlockHash.toString() !== blockLog.blockHash) {
+
+    // Check the archive for the last checkpoint in the epoch
+    const endCheckpointLog = await this.rollupContract.getCheckpoint(toCheckpoint);
+    if (!publicInputs.endArchiveRoot.equals(endCheckpointLog.archive)) {
       throw new Error(
-        `Previous block hash mismatch: ${publicInputs.previousBlockHash.toString()} !== ${blockLog.blockHash}`,
+        `End archive root mismatch: ${publicInputs.endArchiveRoot.toString()} !== ${endCheckpointLog.archive.toString()}`,
       );
     }
 
-    // Check the block hash and archive for the last block in the epoch
-    const endBlockLog = await this.rollupContract.getBlock(BigInt(toBlock));
-    if (publicInputs.endArchive.root.toString() !== endBlockLog.archive) {
+    // Check the batched blob inputs from the root rollup against the batched blob computed in ts
+    const finalBlobAccumulator = batchedBlobInputs.toFinalBlobAccumulator();
+    if (!publicInputs.blobPublicInputs.equals(finalBlobAccumulator)) {
       throw new Error(
-        `End archive root mismatch: ${publicInputs.endArchive.root.toString()} !== ${endBlockLog.archive}`,
+        `Batched blob mismatch: ${inspect(publicInputs.blobPublicInputs)} !== ${inspect(finalBlobAccumulator)}`,
       );
     }
-    if (publicInputs.endBlockHash.toString() !== endBlockLog.blockHash) {
-      throw new Error(`End block hash mismatch: ${publicInputs.endBlockHash.toString()} !== ${endBlockLog.blockHash}`);
-    }
 
     // Compare the public inputs computed by the contract with the ones injected
-    const rollupPublicInputs = await this.rollupContract.getEpochProofPublicInputs(this.getSubmitEpochProofArgs(args));
-    const aggregationObject = proof.isEmpty()
-      ? times(AGGREGATION_OBJECT_LENGTH, Fr.zero)
-      : proof.extractAggregationObject();
-    const argsPublicInputs = [...publicInputs.toFields(), ...aggregationObject];
-
-    if (!areArraysEqual(rollupPublicInputs.map(Fr.fromHexString), argsPublicInputs, (a, b) => a.equals(b))) {
-      const fmt = (inputs: Fr[] | readonly string[]) => inputs.map(x => x.toString()).join(', ');
-      throw new Error(
-        `Root rollup public inputs mismatch:\nRollup:  ${fmt(rollupPublicInputs)}\nComputed:${fmt(argsPublicInputs)}`,
-      );
+    const rollupPublicInputs = await this.rollupContract.getEpochProofPublicInputs(
+      this.getEpochProofPublicInputsArgs(args),
+    );
+    const argsPublicInputs = [...publicInputs.toFields()];
+
+    if (!areArraysEqual(rollupPublicInputs, argsPublicInputs, (a, b) => a.equals(b))) {
+      throw await reportPublicInputsMismatch({
+        rollupPublicInputs,
+        argsPublicInputs,
+        fromCheckpoint,
+        toCheckpoint,
+        rollupContract: this.rollupContract,
+        log: this.log,
+      });
     }
   }
 
+  /**
+   * Estimates what submitting the epoch proof would have cost on L1 without actually sending it.
+   * Runs the same validation as `submitEpochProof`, encodes the calldata, estimates gas, and records metrics.
+   * Used when proof publishing is disabled (e.g. PROVER_NODE_DISABLE_PROOF_PUBLISH=true on mainnet).
+   */
+  public async analyzeEpochProofSubmission(args: {
+    epochNumber: EpochNumber;
+    fromCheckpoint: CheckpointNumber;
+    toCheckpoint: CheckpointNumber;
+    publicInputs: RootRollupPublicInputs;
+    proof: Proof;
+    batchedBlobInputs: BatchedBlob;
+    attestations: ViemCommitteeAttestation[];
+  }): Promise<void> {
+    const { epochNumber, fromCheckpoint, toCheckpoint } = args;
+
+    await this.validateEpochProofSubmission(args);
+
+    const data = this.encodeSubmitEpochProofCalldata(args);
+    const senderAddress = this.l1TxUtils.getSenderAddress();
+
+    const [gasLimit, gasPrice, latestBlock] = await Promise.all([
+      this.l1TxUtils.estimateGas(senderAddress.toString() as `0x${string}`, { to: this.rollupContract.address, data }),
+      this.l1TxUtils.getGasPrice(),
+      this.l1TxUtils.client.getBlock({ blockTag: 'latest' }),
+    ]);
+
+    const baseFeePerGas = latestBlock.baseFeePerGas ?? 0n;
+    const { maxPriorityFeePerGas } = gasPrice;
+
+    const effectiveFeePerGas = baseFeePerGas + maxPriorityFeePerGas;
+    const estimatedTotalFee = gasLimit * effectiveFeePerGas;
+
+    const stats: EstimatedSubmitProofStats = {
+      gasLimit,
+      baseFeePerGas,
+      maxPriorityFeePerGas,
+      estimatedTotalFee,
+    };
+
+    this.log.info(`Estimated epoch proof submission cost (not submitted)`, {
+      epochNumber,
+      fromCheckpoint,
+      toCheckpoint,
+      gasLimit: gasLimit.toString(),
+      baseFeePerGas: formatGwei(baseFeePerGas),
+      maxPriorityFeePerGas: formatGwei(maxPriorityFeePerGas),
+      estimatedTotalFeeEth: formatEther(estimatedTotalFee),
+    });
+
+    this.metrics.recordEstimatedSubmitProof(stats);
+  }
+
+  private encodeSubmitEpochProofCalldata(args: {
+    fromCheckpoint: CheckpointNumber;
+    toCheckpoint: CheckpointNumber;
+    publicInputs: RootRollupPublicInputs;
+    proof: Proof;
+    batchedBlobInputs: BatchedBlob;
+    attestations: ViemCommitteeAttestation[];
+  }): Hex {
+    return encodeFunctionData({
+      abi: RollupAbi,
+      functionName: 'submitEpochRootProof',
+      args: [this.getSubmitEpochProofArgs(args)],
+    });
+  }
+
   private async sendSubmitEpochProofTx(args: {
-    fromBlock: number;
-    toBlock: number;
+    fromCheckpoint: CheckpointNumber;
+    toCheckpoint: CheckpointNumber;
     publicInputs: RootRollupPublicInputs;
     proof: Proof;
+    batchedBlobInputs: BatchedBlob;
+    attestations: ViemCommitteeAttestation[];
   }): Promise<TransactionReceipt | undefined> {
-    const proofHex: Hex = `0x${args.proof.withoutPublicInputs().toString('hex')}`;
-    const argsArray = this.getSubmitEpochProofArgs(args);
-
-    const txArgs = [
-      {
-        start: argsArray[0],
-        end: argsArray[1],
-        args: argsArray[2],
-        fees: argsArray[3],
-        blobPublicInputs: argsArray[4],
-        aggregationObject: argsArray[5],
-        proof: proofHex,
-      },
-    ] as const;
+    const txArgs = [this.getSubmitEpochProofArgs(args)] as const;
 
-    this.log.info(`SubmitEpochProof proofSize=${args.proof.withoutPublicInputs().length} bytes`);
+    this.log.info(`Submitting epoch proof to L1 rollup contract`, {
+      proofSize: args.proof.withoutPublicInputs().length,
+      fromCheckpoint: args.fromCheckpoint,
+      toCheckpoint: args.toCheckpoint,
+    });
     const data = encodeFunctionData({
       abi: RollupAbi,
       functionName: 'submitEpochRootProof',
       args: txArgs,
     });
     try {
-      const { receipt } = await this.l1TxUtils.sendAndMonitorTransaction({
-        to: this.rollupContract.address,
-        data,
-      });
-
+      const { receipt } = await this.l1TxUtils.sendAndMonitorTransaction({ to: this.rollupContract.address, data });
+      if (receipt.status !== 'success') {
+        const errorMsg = await this.l1TxUtils.tryGetErrorFromRevertedTx(
+          data,
+          {
+            args: [...txArgs],
+            functionName: 'submitEpochRootProof',
+            abi: RollupAbi,
+            address: this.rollupContract.address,
+          },
+          /*blobInputs*/ undefined,
+          /*stateOverride*/ [],
+        );
+        this.log.error(`Rollup submit epoch proof tx reverted with ${errorMsg ?? 'unknown error'}`);
+        return undefined;
+      }
       return receipt;
     } catch (err) {
       this.log.error(`Rollup submit epoch proof failed`, err);
-      const errorMsg = await this.l1TxUtils.tryGetErrorFromRevertedTx(
-        data,
-        {
-          args: [...txArgs],
-          functionName: 'submitEpochRootProof',
-          abi: RollupAbi,
-          address: this.rollupContract.address,
-        },
-        /*blobInputs*/ undefined,
-        /*stateOverride*/ [],
-      );
-      this.log.error(`Rollup submit epoch proof tx reverted. ${errorMsg}`);
       return undefined;
     }
   }
 
-  private getSubmitEpochProofArgs(args: {
-    fromBlock: number;
-    toBlock: number;
+  private getEpochProofPublicInputsArgs(args: {
+    fromCheckpoint: CheckpointNumber;
+    toCheckpoint: CheckpointNumber;
     publicInputs: RootRollupPublicInputs;
-    proof: Proof;
+    batchedBlobInputs: BatchedBlob;
+    attestations: ViemCommitteeAttestation[];
   }) {
+    // Returns arguments for EpochProofLib.sol -> getEpochProofPublicInputs()
     return [
-      BigInt(args.fromBlock),
-      BigInt(args.toBlock),
+      BigInt(args.fromCheckpoint) /*_start*/,
+      BigInt(args.toCheckpoint) /*_end*/,
       {
-        previousArchive: args.publicInputs.previousArchive.root.toString(),
-        endArchive: args.publicInputs.endArchive.root.toString(),
-        previousBlockHash: args.publicInputs.previousBlockHash.toString(),
-        endBlockHash: args.publicInputs.endBlockHash.toString(),
-        endTimestamp: args.publicInputs.endTimestamp.toBigInt(),
+        previousArchive: args.publicInputs.previousArchiveRoot.toString(),
+        endArchive: args.publicInputs.endArchiveRoot.toString(),
         outHash: args.publicInputs.outHash.toString(),
-        proverId: EthAddress.fromField(args.publicInputs.proverId).toString(),
-      },
-      makeTuple(AZTEC_MAX_EPOCH_DURATION * 2, i =>
+        proverId: EthAddress.fromField(args.publicInputs.constants.proverId).toString(),
+      } /*_args*/,
+      makeTuple(MAX_CHECKPOINTS_PER_EPOCH * 2, i =>
         i % 2 === 0
           ? args.publicInputs.fees[i / 2].recipient.toField().toString()
           : args.publicInputs.fees[(i - 1) / 2].value.toString(),
-      ),
-      `0x${args.publicInputs.blobPublicInputs
-        .filter((_, i) => i < args.toBlock - args.fromBlock + 1)
-        .map(b => b.toString())
-        .join(``)}`,
-      `0x${serializeToBuffer(args.proof.extractAggregationObject()).toString('hex')}`,
+      ) /*_fees*/,
+      getEthBlobEvaluationInputs(args.batchedBlobInputs) /*_blobPublicInputs*/,
     ] as const;
   }
 
-  protected async sleepOrInterrupted() {
-    await this.interruptibleSleep.sleep(this.sleepTimeMs);
+  private getSubmitEpochProofArgs(args: {
+    fromCheckpoint: CheckpointNumber;
+    toCheckpoint: CheckpointNumber;
+    publicInputs: RootRollupPublicInputs;
+    proof: Proof;
+    batchedBlobInputs: BatchedBlob;
+    attestations: ViemCommitteeAttestation[];
+  }) {
+    // Returns arguments for EpochProofLib.sol -> submitEpochRootProof()
+    const proofHex: Hex = `0x${args.proof.withoutPublicInputs().toString('hex')}`;
+    const argsArray = this.getEpochProofPublicInputsArgs(args);
+    return {
+      start: argsArray[0],
+      end: argsArray[1],
+      args: argsArray[2],
+      fees: argsArray[3],
+      attestations: CommitteeAttestationsAndSigners.packAttestations(
+        args.attestations.map(a => CommitteeAttestation.fromViem(a)),
+      ),
+      blobInputs: argsArray[4],
+      proof: proofHex,
+    };
   }
 }
+
+/**
+ * Decodes a `Root rollup public inputs mismatch`, fetches the on-chain CheckpointLog for any
+ * mismatching `checkpointHeaderHashes[i]`, emits a structured error log, and returns a thrown-ready
+ * Error with a human-readable summary.
+ *
+ * Layout of `RootRollupPublicInputs.toFields()`:
+ *   [0]                   previousArchiveRoot
+ *   [1]                   endArchiveRoot
+ *   [2]                   outHash
+ *   [3 .. 3+N-1]          checkpointHeaderHashes[i] for i in 0..N-1   (N = MAX_CHECKPOINTS_PER_EPOCH)
+ *   [3+N .. 3+3N-1]       fees[i] = (recipient, value) for i in 0..N-1
+ *   [3+3N .. 3+3N+4]      EpochConstantData (chainId, version, vkTreeRoot, protocolContractsHash, proverId)
+ *   [3+3N+5 ..]           blobPublicInputs (FinalBlobAccumulator)
+ */
+async function reportPublicInputsMismatch(input: {
+  rollupPublicInputs: readonly Fr[];
+  argsPublicInputs: readonly Fr[];
+  fromCheckpoint: CheckpointNumber;
+  toCheckpoint: CheckpointNumber;
+  rollupContract: RollupContract;
+  log: Logger;
+}): Promise<Error> {
+  const { rollupPublicInputs, argsPublicInputs, fromCheckpoint, toCheckpoint, rollupContract, log } = input;
+  const N = MAX_CHECKPOINTS_PER_EPOCH;
+  const constantsStart = 3 + 3 * N;
+  const blobStart = constantsStart + 5;
+  const constantLabels = ['chainId', 'version', 'vkTreeRoot', 'protocolContractsHash', 'proverId'];
+
+  const diffs: { index: number; label: string; rollup: Fr; computed: Fr; checkpointIndex?: number }[] = [];
+  const len = Math.max(rollupPublicInputs.length, argsPublicInputs.length);
+  for (let i = 0; i < len; i++) {
+    const a = rollupPublicInputs[i] ?? Fr.ZERO;
+    const b = argsPublicInputs[i] ?? Fr.ZERO;
+    if (a.equals(b)) {
+      continue;
+    }
+    let label: string;
+    let checkpointIndex: number | undefined;
+    if (i === 0) {
+      label = 'previousArchiveRoot';
+    } else if (i === 1) {
+      label = 'endArchiveRoot';
+    } else if (i === 2) {
+      label = 'outHash';
+    } else if (i < 3 + N) {
+      checkpointIndex = i - 3;
+      label = `checkpointHeaderHashes[${checkpointIndex}]`;
+    } else if (i < 3 + 3 * N) {
+      const feePairIndex = i - (3 + N);
+      const feeIndex = Math.floor(feePairIndex / 2);
+      const sub = feePairIndex % 2 === 0 ? 'recipient' : 'value';
+      label = `fees[${feeIndex}].${sub}`;
+    } else if (i < blobStart) {
+      label = `constants.${constantLabels[i - constantsStart]}`;
+    } else {
+      label = `blobPublicInputs[${i - blobStart}]`;
+    }
+    diffs.push({ index: i, label, rollup: a, computed: b, checkpointIndex });
+  }
+
+  // For each mismatching checkpointHeaderHash, fetch the L1 CheckpointLog so the operator can
+  // see what was published on-chain alongside the prover's recomputed hash.
+  const onChainCheckpoints = await Promise.all(
+    diffs
+      .filter(d => d.checkpointIndex !== undefined)
+      .map(async d => {
+        const checkpointNumber = CheckpointNumber(fromCheckpoint + d.checkpointIndex!);
+        try {
+          const cp = await rollupContract.getCheckpoint(checkpointNumber);
+          return { checkpointIndex: d.checkpointIndex!, checkpointNumber, headerHash: cp.headerHash.toString() };
+        } catch (err) {
+          return { checkpointIndex: d.checkpointIndex!, checkpointNumber, error: (err as Error).message };
+        }
+      }),
+  );
+
+  log.error(`Root rollup public inputs mismatch`, undefined, {
+    fromCheckpoint,
+    toCheckpoint,
+    numDiffs: diffs.length,
+    diffs: diffs.map(d => ({
+      index: d.index,
+      label: d.label,
+      rollup: d.rollup.toString(),
+      computed: d.computed.toString(),
+    })),
+    onChainCheckpoints,
+  });
+
+  const fmt = (inputs: readonly Fr[]) => inputs.map(x => x.toString()).join(', ');
+  const summary = diffs.map(d => `[${d.index} ${d.label}] L1=${d.rollup} prover=${d.computed}`).join('\n');
+  return new Error(
+    `Root rollup public inputs mismatch (${diffs.length} fields differ):\n${summary}\n` +
+      `Rollup:  ${fmt(rollupPublicInputs)}\nComputed:${fmt(argsPublicInputs)}`,
+  );
+}