@aztec/archiver 0.0.1-commit.cd76b27 → 0.0.1-commit.ce4f8c4f2

package/src/l1/data_retrieval.ts

@@ -157,11 +157,6 @@ export async function retrieveCheckpointsFromRollup(
   blobClient: BlobClientInterface,
   searchStartBlock: bigint,
   searchEndBlock: bigint,
-  contractAddresses: {
-    governanceProposerAddress: EthAddress;
-    slashFactoryAddress?: EthAddress;
-    slashingProposerAddress: EthAddress;
-  },
   instrumentation: ArchiverInstrumentation,
   logger: Logger = createLogger('archiver'),
   isHistoricalSync: boolean = false,
@@ -205,7 +200,6 @@ export async function retrieveCheckpointsFromRollup(
       blobClient,
       checkpointProposedLogs,
       rollupConstants,
-      contractAddresses,
       instrumentation,
       logger,
       isHistoricalSync,
@@ -226,7 +220,6 @@ export async function retrieveCheckpointsFromRollup(
  * @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.
@@ -239,11 +232,6 @@ async function processCheckpointProposedLogs(
   blobClient: BlobClientInterface,
   logs: CheckpointProposedLog[],
   { chainId, version, targetCommitteeSize }: { chainId: Fr; version: Fr; targetCommitteeSize: number },
-  contractAddresses: {
-    governanceProposerAddress: EthAddress;
-    slashFactoryAddress?: EthAddress;
-    slashingProposerAddress: EthAddress;
-  },
   instrumentation: ArchiverInstrumentation,
   logger: Logger,
   isHistoricalSync: boolean,
@@ -255,7 +243,7 @@ async function processCheckpointProposedLogs(
     targetCommitteeSize,
     instrumentation,
     logger,
-    { ...contractAddresses, rollupAddress: EthAddress.fromString(rollup.address) },
+    EthAddress.fromString(rollup.address),
   );
 
   await asyncPool(10, logs, async log => {
@@ -266,10 +254,9 @@ async function processCheckpointProposedLogs(
 
     // The value from the event and contract will match only if the checkpoint is in the chain.
     if (archive.equals(archiveFromChain)) {
-      // Build expected hashes object (fields may be undefined for backwards compatibility with older events)
       const expectedHashes = {
-        attestationsHash: log.args.attestationsHash?.toString(),
-        payloadDigest: log.args.payloadDigest?.toString(),
+        attestationsHash: log.args.attestationsHash.toString() as Hex,
+        payloadDigest: log.args.payloadDigest.toString() as Hex,
       };
 
       const checkpoint = await calldataRetriever.getCheckpointFromRollupTx(
@@ -278,6 +265,9 @@ async function processCheckpointProposedLogs(
         checkpointNumber,
         expectedHashes,
       );
+      const { timestamp, parentBeaconBlockRoot } = await getL1Block(publicClient, log.l1BlockNumber);
+      const l1 = new L1PublishedData(log.l1BlockNumber, timestamp, log.l1BlockHash.toString());
+
       const checkpointBlobData = await getCheckpointBlobDataFromBlobs(
         blobClient,
         checkpoint.blockHash,
@@ -285,12 +275,8 @@ async function processCheckpointProposedLogs(
         checkpointNumber,
         logger,
         isHistoricalSync,
-      );
-
-      const l1 = new L1PublishedData(
-        log.l1BlockNumber,
-        await getL1BlockTime(publicClient, log.l1BlockNumber),
-        log.l1BlockHash.toString(),
+        parentBeaconBlockRoot,
+        timestamp,
       );
 
       retrievedCheckpoints.push({ ...checkpoint, checkpointBlobData, l1, chainId, version });
@@ -311,9 +297,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(
@@ -323,8 +312,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);
   }

package/src/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/modules/data_source_base.ts

@@ -46,9 +46,9 @@ export abstract class ArchiverDataSourceBase
 
   abstract getL2Tips(): Promise<L2Tips>;
 
-  abstract getL2SlotNumber(): Promise<SlotNumber | undefined>;
+  abstract getSyncedL2SlotNumber(): Promise<SlotNumber | undefined>;
 
-  abstract getL2EpochNumber(): Promise<EpochNumber | undefined>;
+  abstract getSyncedL2EpochNumber(): Promise<EpochNumber | undefined>;
 
   abstract isEpochComplete(epochNumber: EpochNumber): Promise<boolean>;
 
@@ -154,7 +154,7 @@ export abstract class ArchiverDataSourceBase
   }
 
   public getSettledTxReceipt(txHash: TxHash): Promise<TxReceipt | undefined> {
-    return this.store.getSettledTxReceipt(txHash);
+    return this.store.getSettledTxReceipt(txHash, this.l1Constants);
   }
 
   public isPendingChainInvalid(): Promise<boolean> {
@@ -165,16 +165,21 @@ export abstract class ArchiverDataSourceBase
     return (await this.store.getPendingChainValidationStatus()) ?? { valid: true };
   }
 
-  public getPrivateLogsByTags(tags: SiloedTag[], page?: number): Promise<TxScopedL2Log[][]> {
-    return this.store.getPrivateLogsByTags(tags, page);
+  public getPrivateLogsByTags(
+    tags: SiloedTag[],
+    page?: number,
+    upToBlockNumber?: BlockNumber,
+  ): Promise<TxScopedL2Log[][]> {
+    return this.store.getPrivateLogsByTags(tags, page, upToBlockNumber);
   }
 
   public getPublicLogsByTagsFromContract(
     contractAddress: AztecAddress,
     tags: Tag[],
     page?: number,
+    upToBlockNumber?: BlockNumber,
   ): Promise<TxScopedL2Log[][]> {
-    return this.store.getPublicLogsByTagsFromContract(contractAddress, tags, page);
+    return this.store.getPublicLogsByTagsFromContract(contractAddress, tags, page, upToBlockNumber);
   }
 
   public getPublicLogs(filter: LogFilter): Promise<GetPublicLogsResponse> {

package/src/modules/data_store_updater.ts

@@ -1,29 +1,21 @@
 import { BlockNumber, CheckpointNumber } from '@aztec/foundation/branded-types';
-import { Fr } from '@aztec/foundation/curves/bn254';
+import { filterAsync } from '@aztec/foundation/collection';
 import { createLogger } from '@aztec/foundation/log';
-import {
-  ContractClassPublishedEvent,
-  PrivateFunctionBroadcastedEvent,
-  UtilityFunctionBroadcastedEvent,
-} from '@aztec/protocol-contracts/class-registry';
+import { ContractClassPublishedEvent } from '@aztec/protocol-contracts/class-registry';
 import {
   ContractInstancePublishedEvent,
   ContractInstanceUpdatedEvent,
 } from '@aztec/protocol-contracts/instance-registry';
 import type { L2Block, ValidateCheckpointResult } from '@aztec/stdlib/block';
-import type { PublishedCheckpoint } from '@aztec/stdlib/checkpoint';
+import { type PublishedCheckpoint, validateCheckpoint } from '@aztec/stdlib/checkpoint';
 import {
-  type ExecutablePrivateFunctionWithMembershipProof,
-  type UtilityFunctionWithMembershipProof,
-  computePublicBytecodeCommitment,
-  isValidPrivateFunctionMembershipProof,
-  isValidUtilityFunctionMembershipProof,
+  type ContractClassPublicWithCommitment,
+  computeContractAddressFromInstance,
+  computeContractClassId,
 } from '@aztec/stdlib/contract';
 import type { ContractClassLog, PrivateLog, PublicLog } from '@aztec/stdlib/logs';
 import type { UInt64 } from '@aztec/stdlib/types';
 
-import groupBy from 'lodash.groupby';
-
 import type { KVArchiverDataStore } from '../store/kv_archiver_store.js';
 import type { L2TipsCache } from '../store/l2_tips_cache.js';
 
@@ -48,32 +40,32 @@ export class ArchiverDataStoreUpdater {
   constructor(
     private store: KVArchiverDataStore,
     private l2TipsCache?: L2TipsCache,
+    private opts: { rollupManaLimit?: number } = {},
   ) {}
 
   /**
-   * Adds proposed blocks to the store with contract class/instance extraction from logs.
-   * These are uncheckpointed blocks that have been proposed by the sequencer but not yet included in a checkpoint on L1.
-   * Extracts ContractClassPublished, ContractInstancePublished, ContractInstanceUpdated events,
-   * and individually broadcasted functions from the block logs.
+   * Adds a proposed block to the store with contract class/instance extraction from logs.
+   * This is an uncheckpointed block that has been proposed by the sequencer but not yet included in a checkpoint on L1.
+   * Extracts ContractClassPublished, ContractInstancePublished, ContractInstanceUpdated events from the block logs.
    *
-   * @param blocks - The proposed L2 blocks to add.
+   * @param block - The proposed L2 block to add.
    * @param pendingChainValidationStatus - Optional validation status to set.
    * @returns True if the operation is successful.
    */
-  public async addProposedBlocks(
-    blocks: L2Block[],
+  public async addProposedBlock(
+    block: L2Block,
     pendingChainValidationStatus?: ValidateCheckpointResult,
   ): Promise<boolean> {
     const result = await this.store.transactionAsync(async () => {
-      await this.store.addProposedBlocks(blocks);
+      await this.store.addProposedBlock(block);
 
       const opResults = await Promise.all([
         // Update the pending chain validation status if provided
         pendingChainValidationStatus && this.store.setPendingChainValidationStatus(pendingChainValidationStatus),
-        // Add any logs emitted during the retrieved blocks
-        this.store.addLogs(blocks),
-        // Unroll all logs emitted during the retrieved blocks and extract any contract classes and instances from them
-        ...blocks.map(block => this.addContractDataToDb(block)),
+        // Add any logs emitted during the retrieved block
+        this.store.addLogs([block]),
+        // Unroll all logs emitted during the retrieved block and extract any contract classes and instances from it
+        this.addContractDataToDb(block),
       ]);
 
       await this.l2TipsCache?.refresh();
@@ -86,8 +78,7 @@ export class ArchiverDataStoreUpdater {
    * Reconciles local blocks with incoming checkpoints from L1.
    * Adds new checkpoints to the store with contract class/instance extraction from logs.
    * Prunes any local blocks that conflict with checkpoint data (by comparing archive roots).
-   * Extracts ContractClassPublished, ContractInstancePublished, ContractInstanceUpdated events,
-   * and individually broadcasted functions from the checkpoint block logs.
+   * Extracts ContractClassPublished, ContractInstancePublished, ContractInstanceUpdated events from the checkpoint block logs.
    *
    * @param checkpoints - The published checkpoints to add.
    * @param pendingChainValidationStatus - Optional validation status to set.
@@ -97,13 +88,17 @@ export class ArchiverDataStoreUpdater {
     checkpoints: PublishedCheckpoint[],
     pendingChainValidationStatus?: ValidateCheckpointResult,
   ): Promise<ReconcileCheckpointsResult> {
+    for (const checkpoint of checkpoints) {
+      validateCheckpoint(checkpoint.checkpoint, { rollupManaLimit: this.opts?.rollupManaLimit });
+    }
+
     const result = await this.store.transactionAsync(async () => {
       // Before adding checkpoints, check for conflicts with local blocks if any
       const { prunedBlocks, lastAlreadyInsertedBlockNumber } = await this.pruneMismatchingLocalBlocks(checkpoints);
 
       await this.store.addCheckpoints(checkpoints);
 
-      // Filter out blocks that were already inserted via addProposedBlocks() to avoid duplicating logs/contract data
+      // Filter out blocks that were already inserted via addProposedBlock() to avoid duplicating logs/contract data
       const newBlocks = checkpoints
         .flatMap((ch: PublishedCheckpoint) => ch.checkpoint.blocks)
         .filter(b => lastAlreadyInsertedBlockNumber === undefined || b.number > lastAlreadyInsertedBlockNumber);
@@ -173,7 +168,7 @@ export class ArchiverDataStoreUpdater {
           this.log.verbose(`Block number ${blockNumber} already inserted and matches checkpoint`, blockInfos);
           lastAlreadyInsertedBlockNumber = blockNumber;
         } else {
-          this.log.warn(`Conflict detected at block ${blockNumber} between checkpointed and local block`, blockInfos);
+          this.log.info(`Conflict detected at block ${blockNumber} between checkpointed and local block`, blockInfos);
           const prunedBlocks = await this.removeBlocksAfter(BlockNumber(blockNumber - 1));
           return { prunedBlocks, lastAlreadyInsertedBlockNumber };
         }
@@ -276,6 +271,17 @@ export class ArchiverDataStoreUpdater {
     });
   }
 
+  /**
+   * Updates the finalized checkpoint number and refreshes the L2 tips cache.
+   * @param checkpointNumber - The checkpoint number to set as finalized.
+   */
+  public async setFinalizedCheckpointNumber(checkpointNumber: CheckpointNumber): Promise<void> {
+    await this.store.transactionAsync(async () => {
+      await this.store.setFinalizedCheckpointNumber(checkpointNumber);
+      await this.l2TipsCache?.refresh();
+    });
+  }
+
   /** Extracts and stores contract data from a single block. */
   private addContractDataToDb(block: L2Block): Promise<boolean> {
     return this.updateContractDataOnDb(block, Operation.Store);
@@ -297,9 +303,6 @@ export class ArchiverDataStoreUpdater {
         this.updatePublishedContractClasses(contractClassLogs, block.number, operation),
         this.updateDeployedContractInstances(privateLogs, block.number, operation),
         this.updateUpdatedContractInstances(publicLogs, block.header.globalVariables.timestamp, operation),
-        operation === Operation.Store
-          ? this.storeBroadcastedIndividualFunctions(contractClassLogs, block.number)
-          : Promise.resolve(true),
       ])
     ).every(Boolean);
   }
@@ -316,18 +319,37 @@ export class ArchiverDataStoreUpdater {
       .filter(log => ContractClassPublishedEvent.isContractClassPublishedEvent(log))
       .map(log => ContractClassPublishedEvent.fromLog(log));
 
-    const contractClasses = await Promise.all(contractClassPublishedEvents.map(e => e.toContractClassPublic()));
-    if (contractClasses.length > 0) {
-      contractClasses.forEach(c => this.log.verbose(`${Operation[operation]} contract class ${c.id.toString()}`));
-      if (operation == Operation.Store) {
-        // TODO: Will probably want to create some worker threads to compute these bytecode commitments as they are expensive
-        const commitments = await Promise.all(
-          contractClasses.map(c => computePublicBytecodeCommitment(c.packedBytecode)),
-        );
-        return await this.store.addContractClasses(contractClasses, commitments, blockNum);
-      } else if (operation == Operation.Delete) {
+    if (operation == Operation.Delete) {
+      const contractClasses = contractClassPublishedEvents.map(e => e.toContractClassPublic());
+      if (contractClasses.length > 0) {
+        contractClasses.forEach(c => this.log.verbose(`${Operation[operation]} contract class ${c.id.toString()}`));
         return await this.store.deleteContractClasses(contractClasses, blockNum);
       }
+      return true;
+    }
+
+    // Compute bytecode commitments and validate class IDs in a single pass.
+    const contractClasses: ContractClassPublicWithCommitment[] = [];
+    for (const event of contractClassPublishedEvents) {
+      const contractClass = await event.toContractClassPublicWithBytecodeCommitment();
+      const computedClassId = await computeContractClassId({
+        artifactHash: contractClass.artifactHash,
+        privateFunctionsRoot: contractClass.privateFunctionsRoot,
+        publicBytecodeCommitment: contractClass.publicBytecodeCommitment,
+      });
+      if (!computedClassId.equals(contractClass.id)) {
+        this.log.warn(
+          `Skipping contract class with mismatched id at block ${blockNum}. Claimed ${contractClass.id}, computed ${computedClassId}`,
+          { blockNum, contractClassId: event.contractClassId.toString() },
+        );
+        continue;
+      }
+      contractClasses.push(contractClass);
+    }
+
+    if (contractClasses.length > 0) {
+      contractClasses.forEach(c => this.log.verbose(`${Operation[operation]} contract class ${c.id.toString()}`));
+      return await this.store.addContractClasses(contractClasses, blockNum);
     }
     return true;
   }
@@ -340,10 +362,27 @@ export class ArchiverDataStoreUpdater {
     blockNum: BlockNumber,
     operation: Operation,
   ): Promise<boolean> {
-    const contractInstances = allLogs
+    const allInstances = allLogs
       .filter(log => ContractInstancePublishedEvent.isContractInstancePublishedEvent(log))
       .map(log => ContractInstancePublishedEvent.fromLog(log))
       .map(e => e.toContractInstance());
+
+    // Verify that each instance's address matches the one derived from its fields if we're adding
+    const contractInstances =
+      operation === Operation.Delete
+        ? allInstances
+        : await filterAsync(allInstances, async instance => {
+            const computedAddress = await computeContractAddressFromInstance(instance);
+            if (!computedAddress.equals(instance.address)) {
+              this.log.warn(
+                `Found contract instance with mismatched address at block ${blockNum}. Claimed ${instance.address} but computed ${computedAddress}.`,
+                { instanceAddress: instance.address.toString(), computedAddress: computedAddress.toString(), blockNum },
+              );
+              return false;
+            }
+            return true;
+          });
+
     if (contractInstances.length > 0) {
       contractInstances.forEach(c =>
         this.log.verbose(`${Operation[operation]} contract instance at ${c.address.toString()}`),
@@ -382,67 +421,4 @@ export class ArchiverDataStoreUpdater {
     }
     return true;
   }
-
-  /**
-   * Stores the functions that were broadcasted individually.
-   *
-   * @dev Beware that there is not a delete variant of this, since they are added to contract classes
-   *      and will be deleted as part of the class if needed.
-   */
-  private async storeBroadcastedIndividualFunctions(
-    allLogs: ContractClassLog[],
-    _blockNum: BlockNumber,
-  ): Promise<boolean> {
-    // Filter out private and utility function broadcast events
-    const privateFnEvents = allLogs
-      .filter(log => PrivateFunctionBroadcastedEvent.isPrivateFunctionBroadcastedEvent(log))
-      .map(log => PrivateFunctionBroadcastedEvent.fromLog(log));
-    const utilityFnEvents = allLogs
-      .filter(log => UtilityFunctionBroadcastedEvent.isUtilityFunctionBroadcastedEvent(log))
-      .map(log => UtilityFunctionBroadcastedEvent.fromLog(log));
-
-    // Group all events by contract class id
-    for (const [classIdString, classEvents] of Object.entries(
-      groupBy([...privateFnEvents, ...utilityFnEvents], e => e.contractClassId.toString()),
-    )) {
-      const contractClassId = Fr.fromHexString(classIdString);
-      const contractClass = await this.store.getContractClass(contractClassId);
-      if (!contractClass) {
-        this.log.warn(`Skipping broadcasted functions as contract class ${contractClassId.toString()} was not found`);
-        continue;
-      }
-
-      // Split private and utility functions, and filter out invalid ones
-      const allFns = classEvents.map(e => e.toFunctionWithMembershipProof());
-      const privateFns = allFns.filter(
-        (fn): fn is ExecutablePrivateFunctionWithMembershipProof => 'utilityFunctionsTreeRoot' in fn,
-      );
-      const utilityFns = allFns.filter(
-        (fn): fn is UtilityFunctionWithMembershipProof => 'privateFunctionsArtifactTreeRoot' in fn,
-      );
-
-      const privateFunctionsWithValidity = await Promise.all(
-        privateFns.map(async fn => ({ fn, valid: await isValidPrivateFunctionMembershipProof(fn, contractClass) })),
-      );
-      const validPrivateFns = privateFunctionsWithValidity.filter(({ valid }) => valid).map(({ fn }) => fn);
-      const utilityFunctionsWithValidity = await Promise.all(
-        utilityFns.map(async fn => ({
-          fn,
-          valid: await isValidUtilityFunctionMembershipProof(fn, contractClass),
-        })),
-      );
-      const validUtilityFns = utilityFunctionsWithValidity.filter(({ valid }) => valid).map(({ fn }) => fn);
-      const validFnCount = validPrivateFns.length + validUtilityFns.length;
-      if (validFnCount !== allFns.length) {
-        this.log.warn(`Skipping ${allFns.length - validFnCount} invalid functions`);
-      }
-
-      // Store the functions in the contract class in a single operation
-      if (validFnCount > 0) {
-        this.log.verbose(`Storing ${validFnCount} functions for contract class ${contractClassId.toString()}`);
-      }
-      return await this.store.addFunctions(contractClassId, validPrivateFns, validUtilityFns);
-    }
-    return true;
-  }
 }

package/src/modules/instrumentation.ts

@@ -1,6 +1,9 @@
+import type { SlotNumber } from '@aztec/foundation/branded-types';
 import { createLogger } from '@aztec/foundation/log';
 import type { L2Block } from '@aztec/stdlib/block';
 import type { CheckpointData } from '@aztec/stdlib/checkpoint';
+import type { L1RollupConstants } from '@aztec/stdlib/epoch-helpers';
+import { getTimestampForSlot } from '@aztec/stdlib/epoch-helpers';
 import {
   Attributes,
   type Gauge,
@@ -38,6 +41,8 @@ export class ArchiverInstrumentation {
 
   private blockProposalTxTargetCount: UpDownCounter;
 
+  private checkpointL1InclusionDelay: Histogram;
+
   private log = createLogger('archiver:instrumentation');
 
   private constructor(
@@ -85,6 +90,8 @@ export class ArchiverInstrumentation {
       },
     );
 
+    this.checkpointL1InclusionDelay = meter.createHistogram(Metrics.ARCHIVER_CHECKPOINT_L1_INCLUSION_DELAY);
+
     this.dbMetrics = new LmdbMetrics(
       meter,
       {
@@ -161,4 +168,17 @@ export class ArchiverInstrumentation {
       [Attributes.L1_BLOCK_PROPOSAL_USED_TRACE]: usedTrace,
     });
   }
+
+  /**
+   * Records L1 inclusion timing for a checkpoint observed on L1 (seconds into the L2 slot).
+   */
+  public processCheckpointL1Timing(data: {
+    slotNumber: SlotNumber;
+    l1Timestamp: bigint;
+    l1Constants: Pick<L1RollupConstants, 'l1GenesisTime' | 'slotDuration'>;
+  }): void {
+    const slotStartTs = getTimestampForSlot(data.slotNumber, data.l1Constants);
+    const inclusionDelaySeconds = Number(data.l1Timestamp - slotStartTs);
+    this.checkpointL1InclusionDelay.record(inclusionDelaySeconds);
+  }
 }