@aztec/archiver 0.0.1-commit.96bb3f7 → 0.0.1-commit.993d240

package/src/{archiver/l1 → l1}/data_retrieval.ts

@@ -6,51 +6,61 @@ import {
   decodeCheckpointBlobDataFromBlobs,
   encodeBlockBlobData,
 } from '@aztec/blob-lib';
-import type { EpochProofPublicInputArgs } from '@aztec/ethereum/contracts';
-import type { ViemClient, ViemPublicClient, ViemPublicDebugClient } from '@aztec/ethereum/types';
+import type {
+  CheckpointProposedLog,
+  EpochProofPublicInputArgs,
+  InboxContract,
+  MessageSentLog,
+  RollupContract,
+} from '@aztec/ethereum/contracts';
+import type { ViemPublicClient, ViemPublicDebugClient } from '@aztec/ethereum/types';
 import { asyncPool } from '@aztec/foundation/async-pool';
-import { CheckpointNumber } from '@aztec/foundation/branded-types';
-import { Buffer16, Buffer32 } from '@aztec/foundation/buffer';
+import { CheckpointNumber, IndexWithinCheckpoint } from '@aztec/foundation/branded-types';
 import { Fr } from '@aztec/foundation/curves/bn254';
 import { EthAddress } from '@aztec/foundation/eth-address';
 import { type Logger, createLogger } from '@aztec/foundation/log';
-import { type InboxAbi, RollupAbi } from '@aztec/l1-artifacts';
-import { Body, CommitteeAttestation, L2BlockNew } from '@aztec/stdlib/block';
+import { RollupAbi } from '@aztec/l1-artifacts';
+import { Body, CommitteeAttestation, L2Block } from '@aztec/stdlib/block';
 import { Checkpoint, L1PublishedData, PublishedCheckpoint } from '@aztec/stdlib/checkpoint';
 import { Proof } from '@aztec/stdlib/proofs';
 import { CheckpointHeader } from '@aztec/stdlib/rollup';
 import { AppendOnlyTreeSnapshot } from '@aztec/stdlib/trees';
 import { BlockHeader, GlobalVariables, PartialStateReference, StateReference } from '@aztec/stdlib/tx';
 
-import {
-  type GetContractEventsReturnType,
-  type GetContractReturnType,
-  type Hex,
-  decodeFunctionData,
-  getAbiItem,
-  hexToBytes,
-} from 'viem';
+import { type Hex, decodeFunctionData, getAbiItem, hexToBytes } from 'viem';
 
 import { NoBlobBodiesFoundError } from '../errors.js';
-import type { ArchiverInstrumentation } from '../instrumentation.js';
+import type { ArchiverInstrumentation } from '../modules/instrumentation.js';
 import type { DataRetrieval } from '../structs/data_retrieval.js';
 import type { InboxMessage } from '../structs/inbox_message.js';
 import { CalldataRetriever } from './calldata_retriever.js';
 
-export type RetrievedCheckpoint = {
+type RetrievedCheckpointBase = {
   checkpointNumber: CheckpointNumber;
   archiveRoot: Fr;
+  feeAssetPriceModifier: bigint;
   header: CheckpointHeader;
-  checkpointBlobData: CheckpointBlobData;
   l1: L1PublishedData;
   chainId: Fr;
   version: Fr;
   attestations: CommitteeAttestation[];
 };
 
+/** Checkpoint data as retrieved from L1 calldata and blob data. */
+export type RetrievedCheckpoint = RetrievedCheckpointBase & { checkpointBlobData: CheckpointBlobData };
+
+/** Checkpoint data retrieved from L1 calldata only, without blob data. */
+export type RetrievedCheckpointFromCalldata = RetrievedCheckpointBase & {
+  /** Versioned blob hashes from the checkpoint proposed event. */
+  blobHashes: Buffer[];
+  /** Parent beacon block root from the L1 block, used for blob fetching. */
+  parentBeaconBlockRoot: string | undefined;
+};
+
 export async function retrievedToPublishedCheckpoint({
   checkpointNumber,
   archiveRoot,
+  feeAssetPriceModifier,
   header: checkpointHeader,
   checkpointBlobData,
   l1,
@@ -71,7 +81,7 @@ export async function retrievedToPublishedCheckpoint({
   const l1toL2MessageTreeRoot = blocksBlobData[0].l1ToL2MessageRoot!;
 
   const spongeBlob = SpongeBlob.init();
-  const l2Blocks: L2BlockNew[] = [];
+  const l2Blocks: L2Block[] = [];
   for (let i = 0; i < blocksBlobData.length; i++) {
     const blockBlobData = blocksBlobData[i];
     const { blockEndMarker, blockEndStateField, lastArchiveRoot, noteHashRoot, nullifierRoot, publicDataRoot } =
@@ -102,7 +112,7 @@ export async function retrievedToPublishedCheckpoint({
       }),
     });
 
-    const body = Body.fromTxBlobData(checkpointBlobData.blocks[0].txs);
+    const body = Body.fromTxBlobData(blockBlobData.txs);
 
     const blobFields = encodeBlockBlobData(blockBlobData);
     await spongeBlob.absorb(blobFields);
@@ -121,7 +131,7 @@ export async function retrievedToPublishedCheckpoint({
 
     const newArchive = new AppendOnlyTreeSnapshot(newArchiveRoots[i], l2BlockNumber + 1);
 
-    l2Blocks.push(new L2BlockNew(newArchive, header, body, checkpointNumber, i));
+    l2Blocks.push(new L2Block(newArchive, header, body, checkpointNumber, IndexWithinCheckpoint(i)));
   }
 
   const lastBlock = l2Blocks.at(-1)!;
@@ -130,42 +140,34 @@ export async function retrievedToPublishedCheckpoint({
     header: checkpointHeader,
     blocks: l2Blocks,
     number: checkpointNumber,
+    feeAssetPriceModifier: feeAssetPriceModifier,
   });
 
   return PublishedCheckpoint.from({ checkpoint, l1, attestations });
 }
 
 /**
- * Fetches new checkpoints.
- * @param rollup - The rollup contract instance.
+ * Fetches checkpoint calldata from the rollup contract without fetching blob data.
+ * Returns RetrievedCheckpointFromCalldata objects that preserve the information needed for deferred blob fetching.
+ * @param rollup - The rollup contract wrapper.
  * @param publicClient - The viem public client to use for transaction retrieval.
  * @param debugClient - The viem debug client to use for trace/debug RPC methods (optional).
- * @param blobClient - The blob client client for fetching blob data.
  * @param searchStartBlock - The block number to use for starting the search.
  * @param searchEndBlock - The highest block number that we should search up to.
- * @param contractAddresses - The contract addresses (governanceProposerAddress, slashFactoryAddress, slashingProposerAddress).
  * @param instrumentation - The archiver instrumentation instance.
  * @param logger - The logger instance.
- * @param isHistoricalSync - Whether this is a historical sync.
- * @returns An array of retrieved checkpoints.
+ * @returns An array of calldata-only checkpoints.
  */
-export async function retrieveCheckpointsFromRollup(
-  rollup: GetContractReturnType<typeof RollupAbi, ViemPublicClient>,
+export async function retrieveCheckpointCalldataFromRollup(
+  rollup: RollupContract,
   publicClient: ViemPublicClient,
   debugClient: ViemPublicDebugClient,
-  blobClient: BlobClientInterface,
   searchStartBlock: bigint,
   searchEndBlock: bigint,
-  contractAddresses: {
-    governanceProposerAddress: EthAddress;
-    slashFactoryAddress?: EthAddress;
-    slashingProposerAddress: EthAddress;
-  },
   instrumentation: ArchiverInstrumentation,
   logger: Logger = createLogger('archiver'),
-  isHistoricalSync: boolean = false,
-): Promise<RetrievedCheckpoint[]> {
-  const retrievedCheckpoints: RetrievedCheckpoint[] = [];
+): Promise<RetrievedCheckpointFromCalldata[]> {
+  const retrievedCheckpoints: RetrievedCheckpointFromCalldata[] = [];
 
   let rollupConstants: { chainId: Fr; version: Fr; targetCommitteeSize: number } | undefined;
 
@@ -173,15 +175,7 @@ export async function retrieveCheckpointsFromRollup(
     if (searchStartBlock > searchEndBlock) {
       break;
     }
-    const checkpointProposedLogs = (
-      await rollup.getEvents.CheckpointProposed(
-        {},
-        {
-          fromBlock: searchStartBlock,
-          toBlock: searchEndBlock,
-        },
-      )
-    ).filter(log => log.blockNumber! >= searchStartBlock && log.blockNumber! <= searchEndBlock);
+    const checkpointProposedLogs = await rollup.getCheckpointProposedEvents(searchStartBlock, searchEndBlock);
 
     if (checkpointProposedLogs.length === 0) {
       break;
@@ -189,19 +183,19 @@ export async function retrieveCheckpointsFromRollup(
 
     const lastLog = checkpointProposedLogs.at(-1)!;
     logger.debug(
-      `Got ${checkpointProposedLogs.length} processed logs for checkpoints  ${checkpointProposedLogs[0].args.checkpointNumber}-${lastLog.args.checkpointNumber} between L1 blocks ${searchStartBlock}-${searchEndBlock}`,
+      `Got ${checkpointProposedLogs.length} processed logs for checkpoints ${checkpointProposedLogs[0].args.checkpointNumber}-${lastLog.args.checkpointNumber} between L1 blocks ${searchStartBlock}-${searchEndBlock}`,
     );
 
     if (rollupConstants === undefined) {
       const [chainId, version, targetCommitteeSize] = await Promise.all([
         publicClient.getChainId(),
-        rollup.read.getVersion(),
-        rollup.read.getTargetCommitteeSize(),
+        rollup.getVersion(),
+        rollup.getTargetCommitteeSize(),
       ]);
       rollupConstants = {
         chainId: new Fr(chainId),
         version: new Fr(version),
-        targetCommitteeSize: Number(targetCommitteeSize),
+        targetCommitteeSize,
       };
     }
 
@@ -209,108 +203,88 @@ export async function retrieveCheckpointsFromRollup(
       rollup,
       publicClient,
       debugClient,
-      blobClient,
       checkpointProposedLogs,
       rollupConstants,
-      contractAddresses,
       instrumentation,
       logger,
-      isHistoricalSync,
     );
     retrievedCheckpoints.push(...newCheckpoints);
-    searchStartBlock = lastLog.blockNumber! + 1n;
+    searchStartBlock = lastLog.l1BlockNumber + 1n;
   } while (searchStartBlock <= searchEndBlock);
 
-  // The asyncPool from processCheckpointProposedLogs will not necessarily return the checkpoints in order, so we sort them before returning.
   return retrievedCheckpoints.sort((a, b) => Number(a.l1.blockNumber - b.l1.blockNumber));
 }
 
 /**
- * Processes newly received CheckpointProposed logs.
- * @param rollup - The rollup contract instance.
+ * Processes CheckpointProposed logs, fetching only calldata (no blobs).
+ * @param rollup - The rollup contract wrapper.
  * @param publicClient - The viem public client to use for transaction retrieval.
  * @param debugClient - The viem debug client to use for trace/debug RPC methods (optional).
- * @param blobClient - The blob client client for fetching blob data.
  * @param logs - CheckpointProposed logs.
  * @param rollupConstants - The rollup constants (chainId, version, targetCommitteeSize).
- * @param contractAddresses - The contract addresses (governanceProposerAddress, slashFactoryAddress, slashingProposerAddress).
  * @param instrumentation - The archiver instrumentation instance.
  * @param logger - The logger instance.
- * @param isHistoricalSync - Whether this is a historical sync.
- * @returns An array of retrieved checkpoints.
+ * @returns An array of calldata-only checkpoints.
  */
 async function processCheckpointProposedLogs(
-  rollup: GetContractReturnType<typeof RollupAbi, ViemPublicClient>,
+  rollup: RollupContract,
   publicClient: ViemPublicClient,
   debugClient: ViemPublicDebugClient,
-  blobClient: BlobClientInterface,
-  logs: GetContractEventsReturnType<typeof RollupAbi, 'CheckpointProposed'>,
+  logs: CheckpointProposedLog[],
   { chainId, version, targetCommitteeSize }: { chainId: Fr; version: Fr; targetCommitteeSize: number },
-  contractAddresses: {
-    governanceProposerAddress: EthAddress;
-    slashFactoryAddress?: EthAddress;
-    slashingProposerAddress: EthAddress;
-  },
   instrumentation: ArchiverInstrumentation,
   logger: Logger,
-  isHistoricalSync: boolean,
-): Promise<RetrievedCheckpoint[]> {
-  const retrievedCheckpoints: RetrievedCheckpoint[] = [];
+): Promise<RetrievedCheckpointFromCalldata[]> {
+  const retrievedCheckpoints: RetrievedCheckpointFromCalldata[] = [];
   const calldataRetriever = new CalldataRetriever(
     publicClient,
     debugClient,
     targetCommitteeSize,
     instrumentation,
     logger,
-    { ...contractAddresses, rollupAddress: EthAddress.fromString(rollup.address) },
+    EthAddress.fromString(rollup.address),
   );
 
   await asyncPool(10, logs, async log => {
-    const checkpointNumber = CheckpointNumber.fromBigInt(log.args.checkpointNumber!);
-    const archive = log.args.archive!;
-    const archiveFromChain = await rollup.read.archiveAt([BigInt(checkpointNumber)]);
-    const blobHashes = log.args.versionedBlobHashes!.map(blobHash => Buffer.from(blobHash.slice(2), 'hex'));
-
-    // The value from the event and contract will match only if the checkpoint is in the chain.
-    if (archive === archiveFromChain) {
-      // Build expected hashes object (fields may be undefined for backwards compatibility with older events)
+    const checkpointNumber = log.args.checkpointNumber;
+    const archive = log.args.archive;
+    const archiveFromChain = await rollup.archiveAt(checkpointNumber);
+    const blobHashes = log.args.versionedBlobHashes;
+
+    if (archive.equals(archiveFromChain)) {
       const expectedHashes = {
-        attestationsHash: log.args.attestationsHash,
-        payloadDigest: log.args.payloadDigest,
+        attestationsHash: log.args.attestationsHash.toString() as Hex,
+        payloadDigest: log.args.payloadDigest.toString() as Hex,
       };
 
       const checkpoint = await calldataRetriever.getCheckpointFromRollupTx(
-        log.transactionHash!,
+        log.l1TransactionHash,
         blobHashes,
         checkpointNumber,
         expectedHashes,
       );
-      const checkpointBlobData = await getCheckpointBlobDataFromBlobs(
-        blobClient,
-        checkpoint.blockHash,
+      const { timestamp, parentBeaconBlockRoot } = await getL1Block(publicClient, log.l1BlockNumber);
+      const l1 = new L1PublishedData(log.l1BlockNumber, timestamp, log.l1BlockHash.toString());
+
+      retrievedCheckpoints.push({
+        ...checkpoint,
+        l1,
+        chainId,
+        version,
         blobHashes,
-        checkpointNumber,
-        logger,
-        isHistoricalSync,
-      );
-
-      const l1 = new L1PublishedData(
-        log.blockNumber,
-        await getL1BlockTime(publicClient, log.blockNumber),
-        log.blockHash,
-      );
+        parentBeaconBlockRoot,
+      });
 
-      retrievedCheckpoints.push({ ...checkpoint, checkpointBlobData, l1, chainId, version });
-      logger.trace(`Retrieved checkpoint ${checkpointNumber} from L1 tx ${log.transactionHash}`, {
-        l1BlockNumber: log.blockNumber,
+      logger.trace(`Retrieved checkpoint calldata ${checkpointNumber} from L1 tx ${log.l1TransactionHash}`, {
+        l1BlockNumber: log.l1BlockNumber,
         checkpointNumber,
         archive: archive.toString(),
         attestations: checkpoint.attestations,
       });
     } else {
       logger.warn(`Ignoring checkpoint ${checkpointNumber} due to archive root mismatch`, {
-        actual: archive,
-        expected: archiveFromChain,
+        actual: archive.toString(),
+        expected: archiveFromChain.toString(),
       });
     }
   });
@@ -318,9 +292,12 @@ async function processCheckpointProposedLogs(
   return retrievedCheckpoints;
 }
 
-export async function getL1BlockTime(publicClient: ViemPublicClient, blockNumber: bigint): Promise<bigint> {
+export async function getL1Block(
+  publicClient: ViemPublicClient,
+  blockNumber: bigint,
+): Promise<{ timestamp: bigint; parentBeaconBlockRoot: string | undefined }> {
   const block = await publicClient.getBlock({ blockNumber, includeTransactions: false });
-  return block.timestamp;
+  return { timestamp: block.timestamp, parentBeaconBlockRoot: block.parentBeaconBlockRoot };
 }
 
 export async function getCheckpointBlobDataFromBlobs(
@@ -330,8 +307,14 @@ export async function getCheckpointBlobDataFromBlobs(
   checkpointNumber: CheckpointNumber,
   logger: Logger,
   isHistoricalSync: boolean,
+  parentBeaconBlockRoot?: string,
+  l1BlockTimestamp?: bigint,
 ): Promise<CheckpointBlobData> {
-  const blobBodies = await blobClient.getBlobSidecar(blockHash, blobHashes, { isHistoricalSync });
+  const blobBodies = await blobClient.getBlobSidecar(blockHash, blobHashes, {
+    isHistoricalSync,
+    parentBeaconBlockRoot,
+    l1BlockTimestamp,
+  });
   if (blobBodies.length === 0) {
     throw new NoBlobBodiesFoundError(checkpointNumber);
   }
@@ -355,60 +338,49 @@ export async function getCheckpointBlobDataFromBlobs(
 
 /** Given an L1 to L2 message, retrieves its corresponding event from the Inbox within a specific block range. */
 export async function retrieveL1ToL2Message(
-  inbox: GetContractReturnType<typeof InboxAbi, ViemClient>,
-  leaf: Fr,
-  fromBlock: bigint,
-  toBlock: bigint,
+  inbox: InboxContract,
+  message: InboxMessage,
 ): Promise<InboxMessage | undefined> {
-  const logs = await inbox.getEvents.MessageSent({ hash: leaf.toString() }, { fromBlock, toBlock });
-
-  const messages = mapLogsInboxMessage(logs);
-  return messages.length > 0 ? messages[0] : undefined;
+  const log = await inbox.getMessageSentEventByHash(message.leaf.toString(), message.l1BlockNumber);
+  return log && mapLogInboxMessage(log);
 }
 
 /**
  * Fetch L1 to L2 messages.
- * @param publicClient - The viem public client to use for transaction retrieval.
- * @param inboxAddress - The address of the inbox contract to fetch messages from.
- * @param blockUntilSynced - If true, blocks until the archiver has fully synced.
+ * @param inbox - The inbox contract wrapper.
  * @param searchStartBlock - The block number to use for starting the search.
  * @param searchEndBlock - The highest block number that we should search up to.
  * @returns An array of InboxLeaf and next eth block to search from.
  */
 export async function retrieveL1ToL2Messages(
-  inbox: GetContractReturnType<typeof InboxAbi, ViemClient>,
+  inbox: InboxContract,
   searchStartBlock: bigint,
   searchEndBlock: bigint,
 ): Promise<InboxMessage[]> {
   const retrievedL1ToL2Messages: InboxMessage[] = [];
   while (searchStartBlock <= searchEndBlock) {
-    const messageSentLogs = (
-      await inbox.getEvents.MessageSent({}, { fromBlock: searchStartBlock, toBlock: searchEndBlock })
-    ).filter(log => log.blockNumber! >= searchStartBlock && log.blockNumber! <= searchEndBlock);
+    const messageSentLogs = await inbox.getMessageSentEvents(searchStartBlock, searchEndBlock);
 
     if (messageSentLogs.length === 0) {
       break;
     }
 
-    retrievedL1ToL2Messages.push(...mapLogsInboxMessage(messageSentLogs));
-    searchStartBlock = messageSentLogs.at(-1)!.blockNumber + 1n;
+    retrievedL1ToL2Messages.push(...messageSentLogs.map(mapLogInboxMessage));
+    searchStartBlock = messageSentLogs.at(-1)!.l1BlockNumber + 1n;
   }
 
   return retrievedL1ToL2Messages;
 }
 
-function mapLogsInboxMessage(logs: GetContractEventsReturnType<typeof InboxAbi, 'MessageSent'>): InboxMessage[] {
-  return logs.map(log => {
-    const { index, hash, checkpointNumber, rollingHash } = log.args;
-    return {
-      index: index!,
-      leaf: Fr.fromHexString(hash!),
-      l1BlockNumber: log.blockNumber,
-      l1BlockHash: Buffer32.fromString(log.blockHash),
-      checkpointNumber: CheckpointNumber.fromBigInt(checkpointNumber!),
-      rollingHash: Buffer16.fromString(rollingHash!),
-    };
-  });
+function mapLogInboxMessage(log: MessageSentLog): InboxMessage {
+  return {
+    index: log.args.index,
+    leaf: log.args.leaf,
+    l1BlockNumber: log.l1BlockNumber,
+    l1BlockHash: log.l1BlockHash,
+    checkpointNumber: log.args.checkpointNumber,
+    rollingHash: log.args.rollingHash,
+  };
 }
 
 /** Retrieves L2ProofVerified events from the rollup contract. */

package/src/{archiver/l1 → l1}/spire_proposer.ts

@@ -87,17 +87,17 @@ export async function verifyProxyImplementation(
 /**
  * Attempts to decode transaction as a Spire Proposer Multicall.
  * Spire Proposer is a proxy contract that wraps multiple calls.
- * Returns the target address and calldata of the wrapped call if validation succeeds and there is a single call.
+ * Returns all wrapped calls if validation succeeds (caller handles hash matching to find the propose call).
  * @param tx - The transaction to decode
  * @param publicClient - The viem public client for proxy verification
  * @param logger - Logger instance
- * @returns Object with 'to' and 'data' of the wrapped call, or undefined if validation fails
+ * @returns Array of wrapped calls with 'to' and 'data', or undefined if not a valid Spire Proposer tx
  */
-export async function getCallFromSpireProposer(
+export async function getCallsFromSpireProposer(
   tx: Transaction,
   publicClient: { getStorageAt: (params: { address: Hex; slot: Hex }) => Promise<Hex | undefined> },
   logger: Logger,
-): Promise<{ to: Hex; data: Hex } | undefined> {
+): Promise<{ to: Hex; data: Hex }[] | undefined> {
   const txHash = tx.hash;
 
   try {
@@ -141,17 +141,9 @@ export async function getCallFromSpireProposer(
 
     const [calls] = spireArgs;
 
-    // Validate exactly ONE call (see ./README.md for rationale)
-    if (calls.length !== 1) {
-      logger.warn(`Spire Proposer multicall must contain exactly one call (got ${calls.length})`, { txHash });
-      return undefined;
-    }
-
-    const call = calls[0];
-
-    // Successfully extracted the single wrapped call
-    logger.trace(`Decoded Spire Proposer with single call to ${call.target}`, { txHash });
-    return { to: call.target, data: call.data };
+    // Return all wrapped calls (hash matching in the caller determines which is the propose call)
+    logger.trace(`Decoded Spire Proposer with ${calls.length} call(s)`, { txHash });
+    return calls.map(call => ({ to: call.target, data: call.data }));
   } catch (err) {
     // Any decoding error triggers fallback to trace
     logger.warn(`Failed to decode Spire Proposer: ${err}`, { txHash });

package/src/l1/validate_historical_logs.ts

@@ -0,0 +1,140 @@
+import { getPublicClient, getRpcUrlsFromClient } from '@aztec/ethereum/client';
+import { RollupContract } from '@aztec/ethereum/contracts';
+import type { L1ContractAddresses } from '@aztec/ethereum/l1-contract-addresses';
+import type { ViemPublicClient } from '@aztec/ethereum/types';
+import { type Logger, type LoggerBindings, createLogger } from '@aztec/foundation/log';
+
+/** Subset of L1 contract addresses whose historical logs the Aztec node relies on. */
+export type HistoricalLogsContractAddresses = Pick<
+  L1ContractAddresses,
+  'rollupAddress' | 'inboxAddress' | 'registryAddress' | 'governanceProposerAddress'
+>;
+
+/** Result of probing a single RPC URL. */
+type ProbeResult = { ok: true } | { ok: false; reason: string; clientVersion: string | undefined };
+
+/**
+ * Validates that every configured L1 RPC URL returns historical logs for the Rollup contract.
+ *
+ * Some RPC providers prune old logs, which would cause L1 syncing to silently fail. To detect this,
+ * we query for the `OwnershipTransferred` event which every Rollup emits in its constructor (via
+ * Ownable) on the block it was deployed (`l1StartBlock`). The `client` is typically a viem fallback
+ * transport over several user-configured RPC URLs — checking only the first URL would miss a bad
+ * secondary, so we probe each URL independently. The first URL that fails aborts startup, unless
+ * the operator has explicitly opted out.
+ *
+ * @param client - The L1 public client built from the user-configured RPC URLs.
+ * @param addresses - The subset of L1 contract addresses we rely on for historical log retrieval.
+ * @param skipCheck - If true, log warnings instead of throwing.
+ * @param bindings - Optional logger bindings for context.
+ * @throws Error if any URL fails the probe and skipCheck is false.
+ */
+export async function validateAndLogHistoricalLogsAvailability(
+  client: ViemPublicClient,
+  addresses: HistoricalLogsContractAddresses,
+  skipCheck: boolean,
+  bindings?: LoggerBindings,
+): Promise<void> {
+  const logger = createLogger('archiver:validate_historical_logs', bindings);
+  logger.debug('Validating historical log availability on L1 RPCs');
+
+  const urls = getRpcUrlsFromClient(client);
+  if (urls.length === 0) {
+    logger.warn('Could not determine L1 RPC URLs from the public client; skipping historical logs check.');
+    return;
+  }
+
+  const chainId = client.chain?.id;
+  if (chainId === undefined) {
+    logger.warn('Could not determine L1 chain ID from the public client; skipping historical logs check.');
+    return;
+  }
+
+  for (const url of urls) {
+    const probeClient = getPublicClient({ l1RpcUrls: [url], l1ChainId: chainId });
+    const rollup = new RollupContract(probeClient, addresses.rollupAddress.toString());
+    const result = await probeRpcUrl(rollup, probeClient, logger);
+
+    if (result.ok) {
+      logger.debug(`L1 RPC ${url} returned historical OwnershipTransferred log for the Rollup contract.`);
+      continue;
+    }
+
+    const errorMessage = buildErrorMessage(url, result, addresses);
+    if (skipCheck) {
+      logger.warn(`${errorMessage}\nContinuing because ARCHIVER_SKIP_HISTORICAL_LOGS_CHECK is true.`);
+      continue;
+    }
+
+    logger.error(errorMessage);
+    throw new Error(errorMessage);
+  }
+}
+
+/** Runs the OwnershipTransferred probe against a single RPC and queries its client version. */
+async function probeRpcUrl(rollup: RollupContract, client: ViemPublicClient, logger: Logger): Promise<ProbeResult> {
+  let queryError: unknown;
+  try {
+    const logs = await rollup.getOwnershipTransferredEventsAtDeploy();
+    if (logs.length > 0) {
+      return { ok: true };
+    }
+  } catch (err) {
+    queryError = err;
+  }
+
+  const clientVersion = await getClientVersion(client, logger);
+
+  let reason: string;
+  if (queryError instanceof Error) {
+    reason = `Query for historical logs failed: ${queryError.message}`;
+  } else if (queryError !== undefined) {
+    reason = 'Query for historical logs failed with a non-Error value.';
+  } else {
+    reason = 'No OwnershipTransferred event was returned by the L1 RPC for the Rollup deploy block.';
+  }
+  return { ok: false, reason, clientVersion };
+}
+
+/** Builds the operator-facing error message for a failing RPC URL. */
+function buildErrorMessage(
+  url: string,
+  result: Extract<ProbeResult, { ok: false }>,
+  addresses: HistoricalLogsContractAddresses,
+): string {
+  return [
+    `L1 RPC at ${url} does not return historical logs for the Rollup contract. ${result.reason}`,
+    `This likely means this Ethereum RPC node prunes old logs, which would cause the archiver ` +
+      `to silently miss data during L1 sync.`,
+    result.clientVersion
+      ? `Detected L1 client version for ${url}: ${result.clientVersion}.`
+      : `Could not determine L1 client version for ${url}.`,
+    `The following L1 contract addresses must have their historical logs retained by the RPC node:`,
+    `  - Rollup:             ${addresses.rollupAddress.toString()}`,
+    `  - Inbox:              ${addresses.inboxAddress.toString()}`,
+    `  - Registry:           ${addresses.registryAddress.toString()}`,
+    `  - GovernanceProposer: ${addresses.governanceProposerAddress.toString()}`,
+    isReth(result.clientVersion)
+      ? `To retain logs for these contracts, configure reth with a ` +
+        `prune.segments.receipts_log_filter entry for each address above ` +
+        `so reth does not prune their receipts/logs. See https://reth.rs/run/pruning.html for details.`
+      : `Point this RPC endpoint at a node that retains full log history for the addresses above.`,
+    `Set ARCHIVER_SKIP_HISTORICAL_LOGS_CHECK=true to bypass this check at your own risk.`,
+  ].join('\n');
+}
+
+/** Queries `web3_clientVersion` on the L1 RPC. Returns undefined if the call fails or returns a non-string. */
+async function getClientVersion(client: ViemPublicClient, logger: Logger): Promise<string | undefined> {
+  try {
+    const result = await client.request({ method: 'web3_clientVersion' });
+    return typeof result === 'string' ? result : undefined;
+  } catch (err) {
+    logger.debug(`Failed to query web3_clientVersion: ${err instanceof Error ? err.message : err}`);
+    return undefined;
+  }
+}
+
+/** Heuristic check for reth based on the web3_clientVersion string (reth returns e.g. "reth/v1.0.0-..."). */
+function isReth(clientVersion: string | undefined): boolean {
+  return !!clientVersion && /reth/i.test(clientVersion);
+}