@aztec/archiver 0.56.0 → 0.58.0

package/src/archiver/archiver.ts

@@ -1,11 +1,14 @@
 import {
   type FromLogType,
   type GetUnencryptedLogsResponse,
+  type InboxLeaf,
   type L1ToL2MessageSource,
   type L2Block,
+  type L2BlockId,
   type L2BlockL2Logs,
   type L2BlockSource,
   type L2LogsSource,
+  type L2Tips,
   type LogFilter,
   type LogType,
   type TxEffect,
@@ -13,14 +16,22 @@ import {
   type TxReceipt,
   type UnencryptedL2Log,
 } from '@aztec/circuit-types';
-import { ContractClassRegisteredEvent, type FunctionSelector } from '@aztec/circuits.js';
 import {
+  type ContractClassPublic,
+  ContractClassRegisteredEvent,
+  type ContractDataSource,
   ContractInstanceDeployedEvent,
+  type ContractInstanceWithAddress,
+  type ExecutablePrivateFunctionWithMembershipProof,
+  type FunctionSelector,
+  type Header,
   PrivateFunctionBroadcastedEvent,
+  type PublicFunction,
   UnconstrainedFunctionBroadcastedEvent,
+  type UnconstrainedFunctionWithMembershipProof,
   isValidPrivateFunctionMembershipProof,
   isValidUnconstrainedFunctionMembershipProof,
-} from '@aztec/circuits.js/contract';
+} from '@aztec/circuits.js';
 import { createEthereumChain } from '@aztec/ethereum';
 import { type ContractArtifact } from '@aztec/foundation/abi';
 import { type AztecAddress } from '@aztec/foundation/aztec-address';
@@ -30,16 +41,8 @@ import { type DebugLogger, createDebugLogger } from '@aztec/foundation/log';
 import { RunningPromise } from '@aztec/foundation/running-promise';
 import { Timer } from '@aztec/foundation/timer';
 import { InboxAbi, RollupAbi } from '@aztec/l1-artifacts';
-import { ClassRegistererAddress } from '@aztec/protocol-contracts/class-registerer';
+import { ProtocolContractAddress } from '@aztec/protocol-contracts';
 import { type TelemetryClient } from '@aztec/telemetry-client';
-import {
-  type ContractClassPublic,
-  type ContractDataSource,
-  type ContractInstanceWithAddress,
-  type ExecutablePrivateFunctionWithMembershipProof,
-  type PublicFunction,
-  type UnconstrainedFunctionWithMembershipProof,
-} from '@aztec/types/contracts';
 
 import groupBy from 'lodash.groupby';
 import {
@@ -52,11 +55,18 @@ import {
   http,
 } from 'viem';
 
-import { type ArchiverDataStore } from './archiver_store.js';
+import { type ArchiverDataStore, type ArchiverL1SynchPoint } from './archiver_store.js';
 import { type ArchiverConfig } from './config.js';
 import { retrieveBlockFromRollup, retrieveL1ToL2Messages } from './data_retrieval.js';
+import {
+  getEpochNumberAtTimestamp,
+  getSlotAtTimestamp,
+  getSlotRangeForEpoch,
+  getTimestampRangeForEpoch,
+} from './epoch_helpers.js';
 import { ArchiverInstrumentation } from './instrumentation.js';
-import { type SingletonDataRetrieval } from './structs/data_retrieval.js';
+import { type DataRetrieval } from './structs/data_retrieval.js';
+import { type L1Published } from './structs/published.js';
 
 /**
  * Helper interface to combine all sources this archiver implementation provides.
@@ -77,6 +87,11 @@ export class Archiver implements ArchiveSource {
   private rollup: GetContractReturnType<typeof RollupAbi, PublicClient<HttpTransport, Chain>>;
   private inbox: GetContractReturnType<typeof InboxAbi, PublicClient<HttpTransport, Chain>>;
 
+  private store: ArchiverStoreHelper;
+
+  public l1BlockNumber: bigint | undefined;
+  public l1Timestamp: bigint | undefined;
+
   /**
    * Creates a new instance of the Archiver.
    * @param publicClient - A client for interacting with the Ethereum node.
@@ -90,14 +105,16 @@ export class Archiver implements ArchiveSource {
   constructor(
     private readonly publicClient: PublicClient<HttpTransport, Chain>,
     private readonly rollupAddress: EthAddress,
-    private readonly inboxAddress: EthAddress,
+    readonly inboxAddress: EthAddress,
     private readonly registryAddress: EthAddress,
-    private readonly store: ArchiverDataStore,
-    private readonly pollingIntervalMs = 10_000,
+    readonly dataStore: ArchiverDataStore,
+    private readonly pollingIntervalMs: number,
     private readonly instrumentation: ArchiverInstrumentation,
-    private readonly l1StartBlock: bigint = 0n,
+    private readonly l1constants: L1RollupConstants = EmptyL1RollupConstants,
     private readonly log: DebugLogger = createDebugLogger('aztec:archiver'),
   ) {
+    this.store = new ArchiverStoreHelper(dataStore);
+
     this.rollup = getContract({
       address: rollupAddress.toString(),
       abi: RollupAbi,
@@ -137,7 +154,10 @@ export class Archiver implements ArchiveSource {
       client: publicClient,
     });
 
-    const l1StartBlock = await rollup.read.L1_BLOCK_AT_GENESIS();
+    const [l1StartBlock, l1GenesisTime] = await Promise.all([
+      rollup.read.L1_BLOCK_AT_GENESIS(),
+      rollup.read.GENESIS_TIME(),
+    ] as const);
 
     const archiver = new Archiver(
       publicClient,
@@ -145,9 +165,9 @@ export class Archiver implements ArchiveSource {
       config.l1Contracts.inboxAddress,
       config.l1Contracts.registryAddress,
       archiverStore,
-      config.archiverPollingIntervalMS,
+      config.archiverPollingIntervalMS ?? 10_000,
       new ArchiverInstrumentation(telemetry),
-      BigInt(l1StartBlock),
+      { l1StartBlock, l1GenesisTime },
     );
     await archiver.start(blockUntilSynced);
     return archiver;
@@ -199,11 +219,8 @@ export class Archiver implements ArchiveSource {
      *
      * This code does not handle reorgs.
      */
-    const {
-      blocksSynchedTo = this.l1StartBlock,
-      messagesSynchedTo = this.l1StartBlock,
-      provenLogsSynchedTo = this.l1StartBlock,
-    } = await this.store.getSynchPoint();
+    const { l1StartBlock } = this.l1constants;
+    const { blocksSynchedTo = l1StartBlock, messagesSynchedTo = l1StartBlock } = await this.store.getSynchPoint();
     const currentL1BlockNumber = await this.publicClient.getBlockNumber();
 
     // ********** Ensuring Consistency of data pulled from L1 **********
@@ -225,14 +242,47 @@ export class Archiver implements ArchiveSource {
      * in future but for the time being it should give us the guarantees that we need
      */
 
-    await this.updateLastProvenL2Block(provenLogsSynchedTo, currentL1BlockNumber);
-
     // ********** Events that are processed per L1 block **********
-
     await this.handleL1ToL2Messages(blockUntilSynced, messagesSynchedTo, currentL1BlockNumber);
 
     // ********** Events that are processed per L2 block **********
-    await this.handleL2blocks(blockUntilSynced, blocksSynchedTo, currentL1BlockNumber);
+    if (currentL1BlockNumber > blocksSynchedTo) {
+      // First we retrieve new L2 blocks
+      const { provenBlockNumber } = await this.handleL2blocks(blockUntilSynced, blocksSynchedTo, currentL1BlockNumber);
+      // And then we prune the current epoch if it'd reorg on next submission.
+      // Note that we don't do this before retrieving L2 blocks because we may need to retrieve
+      // blocks from more than 2 epochs ago, so we want to make sure we have the latest view of
+      // the chain locally before we start unwinding stuff. This can be optimized by figuring out
+      // up to which point we're pruning, and then requesting L2 blocks up to that point only.
+      await this.handleEpochPrune(provenBlockNumber, currentL1BlockNumber);
+    }
+
+    // Store latest l1 block number and timestamp seen. Used for epoch and slots calculations.
+    if (!this.l1BlockNumber || this.l1BlockNumber < currentL1BlockNumber) {
+      this.l1Timestamp = await this.publicClient.getBlock({ blockNumber: currentL1BlockNumber }).then(b => b.timestamp);
+      this.l1BlockNumber = currentL1BlockNumber;
+    }
+  }
+
+  /** Checks if there'd be a reorg for the next block submission and start pruning now. */
+  private async handleEpochPrune(provenBlockNumber: bigint, currentL1BlockNumber: bigint) {
+    const localPendingBlockNumber = BigInt(await this.getBlockNumber());
+
+    const canPrune =
+      localPendingBlockNumber > provenBlockNumber &&
+      (await this.rollup.read.canPrune({ blockNumber: currentL1BlockNumber }));
+
+    if (canPrune) {
+      this.log.verbose(`L2 prune will occur on next submission. Rolling back to last proven block.`);
+      const blocksToUnwind = localPendingBlockNumber - provenBlockNumber;
+      this.log.verbose(
+        `Unwinding ${blocksToUnwind} block${blocksToUnwind > 1n ? 's' : ''} from block ${localPendingBlockNumber}`,
+      );
+      await this.store.unwindBlocks(Number(localPendingBlockNumber), Number(blocksToUnwind));
+      // TODO(palla/reorg): Do we need to set the block synched L1 block number here?
+      // Seems like the next iteration should handle this.
+      // await this.store.setBlockSynchedL1BlockNumber(currentL1BlockNumber);
+    }
   }
 
   private async handleL1ToL2Messages(
@@ -244,14 +294,10 @@ export class Archiver implements ArchiveSource {
       return;
     }
 
-    const retrievedL1ToL2Messages = await retrieveL1ToL2Messages(
-      this.inbox,
-      blockUntilSynced,
-      messagesSynchedTo + 1n,
-      currentL1BlockNumber,
-    );
+    const localTotalMessageCount = await this.store.getTotalL1ToL2MessageCount();
+    const destinationTotalMessageCount = await this.inbox.read.totalMessagesInserted();
 
-    if (retrievedL1ToL2Messages.retrievedData.length === 0) {
+    if (localTotalMessageCount === destinationTotalMessageCount) {
       await this.store.setMessageSynchedL1BlockNumber(currentL1BlockNumber);
       this.log.verbose(
         `Retrieved no new L1 -> L2 messages between L1 blocks ${messagesSynchedTo + 1n} and ${currentL1BlockNumber}.`,
@@ -259,6 +305,13 @@ export class Archiver implements ArchiveSource {
       return;
     }
 
+    const retrievedL1ToL2Messages = await retrieveL1ToL2Messages(
+      this.inbox,
+      blockUntilSynced,
+      messagesSynchedTo + 1n,
+      currentL1BlockNumber,
+    );
+
     await this.store.addL1ToL2Messages(retrievedL1ToL2Messages);
 
     this.log.verbose(
@@ -268,46 +321,91 @@ export class Archiver implements ArchiveSource {
     );
   }
 
-  private async updateLastProvenL2Block(provenSynchedTo: bigint, currentL1BlockNumber: bigint) {
-    if (currentL1BlockNumber <= provenSynchedTo) {
-      return;
-    }
-
-    const provenBlockNumber = await this.rollup.read.getProvenBlockNumber();
-    if (provenBlockNumber) {
-      await this.store.setProvenL2BlockNumber({
-        retrievedData: Number(provenBlockNumber),
-        lastProcessedL1BlockNumber: currentL1BlockNumber,
-      });
-    }
-  }
+  private async handleL2blocks(
+    blockUntilSynced: boolean,
+    blocksSynchedTo: bigint,
+    currentL1BlockNumber: bigint,
+  ): Promise<{ provenBlockNumber: bigint }> {
+    const localPendingBlockNumber = BigInt(await this.getBlockNumber());
+    const [
+      provenBlockNumber,
+      provenArchive,
+      pendingBlockNumber,
+      pendingArchive,
+      archiveForLocalPendingBlockNumber,
+      provenEpochNumber,
+    ] = await this.rollup.read.status([localPendingBlockNumber], { blockNumber: currentL1BlockNumber });
+
+    const updateProvenBlock = async () => {
+      const localBlockForDestinationProvenBlockNumber = await this.getBlock(Number(provenBlockNumber));
+      if (
+        localBlockForDestinationProvenBlockNumber &&
+        provenArchive === localBlockForDestinationProvenBlockNumber.archive.root.toString()
+      ) {
+        this.log.info(`Updating the proven block number to ${provenBlockNumber} and epoch to ${provenEpochNumber}`);
+        await this.store.setProvenL2BlockNumber(Number(provenBlockNumber));
+        // if we are here then we must have a valid proven epoch number
+        await this.store.setProvenL2EpochNumber(Number(provenEpochNumber));
+      }
+      this.instrumentation.updateLastProvenBlock(Number(provenBlockNumber));
+    };
 
-  private async handleL2blocks(blockUntilSynced: boolean, blocksSynchedTo: bigint, currentL1BlockNumber: bigint) {
-    if (currentL1BlockNumber <= blocksSynchedTo) {
-      return;
+    // This is an edge case that we only hit if there are no proposed blocks.
+    // If we have 0 blocks locally and there are no blocks onchain there is nothing to do.
+    const noBlocks = localPendingBlockNumber === 0n && pendingBlockNumber === 0n;
+    if (noBlocks) {
+      await this.store.setBlockSynchedL1BlockNumber(currentL1BlockNumber);
+      this.log.verbose(`No blocks to retrieve from ${blocksSynchedTo + 1n} to ${currentL1BlockNumber}`);
+      return { provenBlockNumber };
     }
 
-    const lastBlock = await this.getBlock(-1);
+    await updateProvenBlock();
 
-    const [, , pendingBlockNumber, pendingArchive, archiveOfMyBlock] = await this.rollup.read.status([
-      BigInt(lastBlock?.number ?? 0),
-    ]);
+    // Related to the L2 reorgs of the pending chain. We are only interested in actually addressing a reorg if there
+    // are any state that could be impacted by it. If we have no blocks, there is no impact.
+    if (localPendingBlockNumber > 0) {
+      const localPendingBlock = await this.getBlock(Number(localPendingBlockNumber));
+      if (localPendingBlock === undefined) {
+        throw new Error(`Missing block ${localPendingBlockNumber}`);
+      }
 
-    const noBlocksButInitial = lastBlock === undefined && pendingBlockNumber == 0n;
-    const noBlockSinceLast =
-      lastBlock &&
-      pendingBlockNumber === BigInt(lastBlock.number) &&
-      pendingArchive === lastBlock.archive.root.toString();
+      const noBlockSinceLast = localPendingBlock && pendingArchive === localPendingBlock.archive.root.toString();
+      if (noBlockSinceLast) {
+        await this.store.setBlockSynchedL1BlockNumber(currentL1BlockNumber);
+        this.log.verbose(`No blocks to retrieve from ${blocksSynchedTo + 1n} to ${currentL1BlockNumber}`);
+        return { provenBlockNumber };
+      }
 
-    if (noBlocksButInitial || noBlockSinceLast) {
-      await this.store.setBlockSynchedL1BlockNumber(currentL1BlockNumber);
-      this.log.verbose(`No blocks to retrieve from ${blocksSynchedTo + 1n} to ${currentL1BlockNumber}`);
-      return;
-    }
+      const localPendingBlockInChain = archiveForLocalPendingBlockNumber === localPendingBlock.archive.root.toString();
+      if (!localPendingBlockInChain) {
+        // If our local pending block tip is not in the chain on L1 a "prune" must have happened
+        // or the L1 have reorged.
+        // In any case, we have to figure out how far into the past the action will take us.
+        // For simplicity here, we will simply rewind until we end in a block that is also on the chain on L1.
+        this.log.verbose(`L2 prune have occurred, unwind state`);
+
+        let tipAfterUnwind = localPendingBlockNumber;
+        while (true) {
+          const candidateBlock = await this.getBlock(Number(tipAfterUnwind));
+          if (candidateBlock === undefined) {
+            break;
+          }
+
+          const archiveAtContract = await this.rollup.read.archiveAt([BigInt(candidateBlock.number)]);
+
+          if (archiveAtContract === candidateBlock.archive.root.toString()) {
+            break;
+          }
+          tipAfterUnwind--;
+        }
+
+        const blocksToUnwind = localPendingBlockNumber - tipAfterUnwind;
+        this.log.verbose(
+          `Unwinding ${blocksToUnwind} block${blocksToUnwind > 1n ? 's' : ''} from block ${localPendingBlockNumber}`,
+        );
 
-    if (lastBlock && archiveOfMyBlock !== lastBlock.archive.root.toString()) {
-      // @todo  Either `prune` have been called, or L1 have re-orged deep enough to remove a block.
-      //        Issue#8620 and Issue#8621
+        await this.store.unwindBlocks(Number(localPendingBlockNumber), Number(blocksToUnwind));
+      }
     }
 
     this.log.debug(`Retrieving blocks from ${blocksSynchedTo + 1n} to ${currentL1BlockNumber}`);
@@ -315,15 +413,16 @@ export class Archiver implements ArchiveSource {
       this.rollup,
       this.publicClient,
       blockUntilSynced,
-      blocksSynchedTo + 1n,
+      blocksSynchedTo + 1n, // TODO(palla/reorg): If the L2 reorg was due to an L1 reorg, we need to start search earlier
       currentL1BlockNumber,
       this.log,
     );
 
     if (retrievedBlocks.length === 0) {
-      await this.store.setBlockSynchedL1BlockNumber(currentL1BlockNumber);
-      this.log.verbose(`Retrieved no new blocks from ${blocksSynchedTo + 1n} to ${currentL1BlockNumber}`);
-      return;
+      // We are not calling `setBlockSynchedL1BlockNumber` because it may cause sync issues if based off infura.
+      // See further details in earlier comments.
+      this.log.verbose(`Retrieved no new L2 blocks from ${blocksSynchedTo + 1n} to ${currentL1BlockNumber}`);
+      return { provenBlockNumber };
     }
 
     this.log.debug(
@@ -334,110 +433,24 @@ export class Archiver implements ArchiveSource {
 
     const lastProcessedL1BlockNumber = retrievedBlocks[retrievedBlocks.length - 1].l1.blockNumber;
 
-    this.log.debug(
-      `Processing retrieved blocks ${retrievedBlocks
-        .map(b => b.data.number)
-        .join(',')} with last processed L1 block ${lastProcessedL1BlockNumber}`,
-    );
-
-    await Promise.all(
-      retrievedBlocks.map(block => {
-        return this.store.addLogs(
-          block.data.body.noteEncryptedLogs,
-          block.data.body.encryptedLogs,
-          block.data.body.unencryptedLogs,
-          block.data.number,
-        );
-      }),
-    );
-
-    // Unroll all logs emitted during the retrieved blocks and extract any contract classes and instances from them
-    await Promise.all(
-      retrievedBlocks.map(async block => {
-        const blockLogs = block.data.body.txEffects
-          .flatMap(txEffect => (txEffect ? [txEffect.unencryptedLogs] : []))
-          .flatMap(txLog => txLog.unrollLogs());
-        await this.storeRegisteredContractClasses(blockLogs, block.data.number);
-        await this.storeDeployedContractInstances(blockLogs, block.data.number);
-        await this.storeBroadcastedIndividualFunctions(blockLogs, block.data.number);
-      }),
-    );
+    this.log.debug(`last processed L1 block: [${lastProcessedL1BlockNumber}]`);
+    for (const block of retrievedBlocks) {
+      this.log.debug(`ingesting new L2 block`, block.data.header.globalVariables.toFriendlyJSON());
+    }
 
     const timer = new Timer();
     await this.store.addBlocks(retrievedBlocks);
+
+    // Important that we update AFTER inserting the blocks.
+    await updateProvenBlock();
     this.instrumentation.processNewBlocks(
       timer.ms() / retrievedBlocks.length,
       retrievedBlocks.map(b => b.data),
     );
     const lastL2BlockNumber = retrievedBlocks[retrievedBlocks.length - 1].data.number;
     this.log.verbose(`Processed ${retrievedBlocks.length} new L2 blocks up to ${lastL2BlockNumber}`);
-  }
-
-  /**
-   * Extracts and stores contract classes out of ContractClassRegistered events emitted by the class registerer contract.
-   * @param allLogs - All logs emitted in a bunch of blocks.
-   */
-  private async storeRegisteredContractClasses(allLogs: UnencryptedL2Log[], blockNum: number) {
-    const contractClasses = ContractClassRegisteredEvent.fromLogs(allLogs, ClassRegistererAddress).map(e =>
-      e.toContractClassPublic(),
-    );
-    if (contractClasses.length > 0) {
-      contractClasses.forEach(c => this.log.verbose(`Registering contract class ${c.id.toString()}`));
-      await this.store.addContractClasses(contractClasses, blockNum);
-    }
-  }
-
-  /**
-   * Extracts and stores contract instances out of ContractInstanceDeployed events emitted by the canonical deployer contract.
-   * @param allLogs - All logs emitted in a bunch of blocks.
-   */
-  private async storeDeployedContractInstances(allLogs: UnencryptedL2Log[], blockNum: number) {
-    const contractInstances = ContractInstanceDeployedEvent.fromLogs(allLogs).map(e => e.toContractInstance());
-    if (contractInstances.length > 0) {
-      contractInstances.forEach(c => this.log.verbose(`Storing contract instance at ${c.address.toString()}`));
-      await this.store.addContractInstances(contractInstances, blockNum);
-    }
-  }
-
-  private async storeBroadcastedIndividualFunctions(allLogs: UnencryptedL2Log[], _blockNum: number) {
-    // Filter out private and unconstrained function broadcast events
-    const privateFnEvents = PrivateFunctionBroadcastedEvent.fromLogs(allLogs, ClassRegistererAddress);
-    const unconstrainedFnEvents = UnconstrainedFunctionBroadcastedEvent.fromLogs(allLogs, ClassRegistererAddress);
-
-    // Group all events by contract class id
-    for (const [classIdString, classEvents] of Object.entries(
-      groupBy([...privateFnEvents, ...unconstrainedFnEvents], e => e.contractClassId.toString()),
-    )) {
-      const contractClassId = Fr.fromString(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 unconstrained functions, and filter out invalid ones
-      const allFns = classEvents.map(e => e.toFunctionWithMembershipProof());
-      const privateFns = allFns.filter(
-        (fn): fn is ExecutablePrivateFunctionWithMembershipProof => 'unconstrainedFunctionsArtifactTreeRoot' in fn,
-      );
-      const unconstrainedFns = allFns.filter(
-        (fn): fn is UnconstrainedFunctionWithMembershipProof => 'privateFunctionsArtifactTreeRoot' in fn,
-      );
-      const validPrivateFns = privateFns.filter(fn => isValidPrivateFunctionMembershipProof(fn, contractClass));
-      const validUnconstrainedFns = unconstrainedFns.filter(fn =>
-        isValidUnconstrainedFunctionMembershipProof(fn, contractClass),
-      );
-      const validFnCount = validPrivateFns.length + validUnconstrainedFns.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()}`);
-      }
-      await this.store.addFunctions(contractClassId, validPrivateFns, validUnconstrainedFns);
-    }
+    return { provenBlockNumber };
   }
 
   /**
@@ -460,6 +473,71 @@ export class Archiver implements ArchiveSource {
     return Promise.resolve(this.registryAddress);
   }
 
+  public getL1BlockNumber(): bigint {
+    const l1BlockNumber = this.l1BlockNumber;
+    if (!l1BlockNumber) {
+      throw new Error('L1 block number not yet available. Complete an initial sync first.');
+    }
+    return l1BlockNumber;
+  }
+
+  public getL1Timestamp(): bigint {
+    const l1Timestamp = this.l1Timestamp;
+    if (!l1Timestamp) {
+      throw new Error('L1 timestamp not yet available. Complete an initial sync first.');
+    }
+    return l1Timestamp;
+  }
+
+  public getL2SlotNumber(): Promise<bigint> {
+    return Promise.resolve(getSlotAtTimestamp(this.getL1Timestamp(), this.l1constants));
+  }
+
+  public getL2EpochNumber(): Promise<bigint> {
+    return Promise.resolve(getEpochNumberAtTimestamp(this.getL1Timestamp(), this.l1constants));
+  }
+
+  public async getBlocksForEpoch(epochNumber: bigint): Promise<L2Block[]> {
+    const [start, end] = getSlotRangeForEpoch(epochNumber);
+    const blocks: L2Block[] = [];
+
+    // Walk the list of blocks backwards and filter by slots matching the requested epoch.
+    // We'll typically ask for blocks for a very recent epoch, so we shouldn't need an index here.
+    let block = await this.getBlock(await this.store.getSynchedL2BlockNumber());
+    const slot = (b: L2Block) => b.header.globalVariables.slotNumber.toBigInt();
+    while (block && slot(block) >= start) {
+      if (slot(block) <= end) {
+        blocks.push(block);
+      }
+      block = await this.getBlock(block.number - 1);
+    }
+
+    return blocks.reverse();
+  }
+
+  public async isEpochComplete(epochNumber: bigint): Promise<boolean> {
+    // The epoch is complete if the current L2 block is the last one in the epoch (or later)
+    const header = await this.getBlockHeader('latest');
+    const slot = header?.globalVariables.slotNumber.toBigInt();
+    const [_startSlot, endSlot] = getSlotRangeForEpoch(epochNumber);
+    if (slot && slot >= endSlot) {
+      return true;
+    }
+
+    // If not, the epoch may also be complete if the L2 slot has passed without a block
+    // We compute this based on the timestamp for the given epoch and the timestamp of the last L1 block
+    const l1Timestamp = this.getL1Timestamp();
+    const [_startTimestamp, endTimestamp] = getTimestampRangeForEpoch(epochNumber, this.l1constants);
+
+    // For this computation, we throw in a few extra seconds just for good measure,
+    // since we know the next L1 block won't be mined within this range. Remember that
+    // l1timestamp is the timestamp of the last l1 block we've seen, so this 3s rely on
+    // the fact that L1 won't mine two blocks within 3s of each other.
+    // TODO(palla/reorg): Is the above a safe assumption?
+    const leeway = 3n;
+    return l1Timestamp + leeway >= endTimestamp;
+  }
+
   /**
    * Gets up to `limit` amount of L2 blocks starting from `from`.
    * @param from - Number of the first block to return (inclusive).
@@ -476,7 +554,7 @@ export class Archiver implements ArchiveSource {
 
   /**
    * Gets an l2 block.
-   * @param number - The block number to return (inclusive).
+   * @param number - The block number to return.
    * @returns The requested L2 block.
    */
   public async getBlock(number: number): Promise<L2Block | undefined> {
@@ -484,10 +562,27 @@ export class Archiver implements ArchiveSource {
     if (number < 0) {
       number = await this.store.getSynchedL2BlockNumber();
     }
+    if (number == 0) {
+      return undefined;
+    }
     const blocks = await this.store.getBlocks(number, 1);
     return blocks.length === 0 ? undefined : blocks[0].data;
   }
 
+  public async getBlockHeader(number: number | 'latest'): Promise<Header | undefined> {
+    if (number === 'latest') {
+      number = await this.store.getSynchedL2BlockNumber();
+    }
+    try {
+      const headers = await this.store.getBlockHeaders(number, 1);
+      return headers.length === 0 ? undefined : headers[0];
+    } catch (e) {
+      // If the latest is 0, then getBlockHeaders will throw an error
+      this.log.error(`getBlockHeader: error fetching block number: ${number}`);
+      return undefined;
+    }
+  }
+
   public getTxEffect(txHash: TxHash): Promise<TxEffect | undefined> {
     return this.store.getTxEffect(txHash);
   }
@@ -553,9 +648,13 @@ export class Archiver implements ArchiveSource {
     return this.store.getProvenL2BlockNumber();
   }
 
+  public getProvenL2EpochNumber(): Promise<number | undefined> {
+    return this.store.getProvenL2EpochNumber();
+  }
+
   /** Forcefully updates the last proven block number. Use for testing. */
-  public setProvenBlockNumber(block: SingletonDataRetrieval<number>): Promise<void> {
-    return this.store.setProvenL2BlockNumber(block);
+  public setProvenBlockNumber(blockNumber: number): Promise<void> {
+    return this.store.setProvenL2BlockNumber(blockNumber);
   }
 
   public getContractClass(id: Fr): Promise<ContractClassPublic | undefined> {
@@ -596,4 +695,288 @@ export class Archiver implements ArchiveSource {
   getContractArtifact(address: AztecAddress): Promise<ContractArtifact | undefined> {
     return this.store.getContractArtifact(address);
   }
+
+  async getL2Tips(): Promise<L2Tips> {
+    const [latestBlockNumber, provenBlockNumber] = await Promise.all([
+      this.getBlockNumber(),
+      this.getProvenBlockNumber(),
+    ] as const);
+
+    const [latestBlockHeader, provenBlockHeader] = await Promise.all([
+      latestBlockNumber > 0 ? this.getBlockHeader(latestBlockNumber) : undefined,
+      provenBlockNumber > 0 ? this.getBlockHeader(provenBlockNumber) : undefined,
+    ] as const);
+
+    if (latestBlockNumber > 0 && !latestBlockHeader) {
+      throw new Error('Failed to retrieve latest block header');
+    }
+
+    if (provenBlockNumber > 0 && !provenBlockHeader) {
+      throw new Error('Failed to retrieve proven block header');
+    }
+
+    return {
+      latest: { number: latestBlockNumber, hash: latestBlockHeader?.hash().toString() } as L2BlockId,
+      proven: { number: provenBlockNumber, hash: provenBlockHeader?.hash().toString() } as L2BlockId,
+      finalized: { number: provenBlockNumber, hash: provenBlockHeader?.hash().toString() } as L2BlockId,
+    };
+  }
+}
+
+enum Operation {
+  Store,
+  Delete,
 }
+
+/**
+ * A helper class that we use to deal with some of the logic needed when adding blocks.
+ *
+ * I would have preferred to not have this type. But it is useful for handling the logic that any
+ * store would need to include otherwise while exposing fewer functions and logic directly to the archiver.
+ */
+class ArchiverStoreHelper
+  implements
+    Omit<
+      ArchiverDataStore,
+      | 'addLogs'
+      | 'deleteLogs'
+      | 'addContractClasses'
+      | 'deleteContractClasses'
+      | 'addContractInstances'
+      | 'deleteContractInstances'
+      | 'addFunctions'
+    >
+{
+  #log = createDebugLogger('aztec:archiver:block-helper');
+
+  constructor(private readonly store: ArchiverDataStore) {}
+
+  /**
+   * Extracts and stores contract classes out of ContractClassRegistered events emitted by the class registerer contract.
+   * @param allLogs - All logs emitted in a bunch of blocks.
+   */
+  async #updateRegisteredContractClasses(allLogs: UnencryptedL2Log[], blockNum: number, operation: Operation) {
+    const contractClasses = ContractClassRegisteredEvent.fromLogs(
+      allLogs,
+      ProtocolContractAddress.ContractClassRegisterer,
+    ).map(e => e.toContractClassPublic());
+    if (contractClasses.length > 0) {
+      contractClasses.forEach(c => this.#log.verbose(`Registering contract class ${c.id.toString()}`));
+      if (operation == Operation.Store) {
+        return await this.store.addContractClasses(contractClasses, blockNum);
+      } else if (operation == Operation.Delete) {
+        return await this.store.deleteContractClasses(contractClasses, blockNum);
+      }
+    }
+    return true;
+  }
+
+  /**
+   * Extracts and stores contract instances out of ContractInstanceDeployed events emitted by the canonical deployer contract.
+   * @param allLogs - All logs emitted in a bunch of blocks.
+   */
+  async #updateDeployedContractInstances(allLogs: UnencryptedL2Log[], blockNum: number, operation: Operation) {
+    const contractInstances = ContractInstanceDeployedEvent.fromLogs(allLogs).map(e => e.toContractInstance());
+    if (contractInstances.length > 0) {
+      contractInstances.forEach(c =>
+        this.#log.verbose(`${Operation[operation]} contract instance at ${c.address.toString()}`),
+      );
+      if (operation == Operation.Store) {
+        return await this.store.addContractInstances(contractInstances, blockNum);
+      } else if (operation == Operation.Delete) {
+        return await this.store.deleteContractInstances(contractInstances, blockNum);
+      }
+    }
+    return true;
+  }
+
+  /**
+   * Stores the functions that was 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.
+   *
+   * @param allLogs - The logs from the block
+   * @param _blockNum - The block number
+   * @returns
+   */
+  async #storeBroadcastedIndividualFunctions(allLogs: UnencryptedL2Log[], _blockNum: number) {
+    // Filter out private and unconstrained function broadcast events
+    const privateFnEvents = PrivateFunctionBroadcastedEvent.fromLogs(
+      allLogs,
+      ProtocolContractAddress.ContractClassRegisterer,
+    );
+    const unconstrainedFnEvents = UnconstrainedFunctionBroadcastedEvent.fromLogs(
+      allLogs,
+      ProtocolContractAddress.ContractClassRegisterer,
+    );
+
+    // Group all events by contract class id
+    for (const [classIdString, classEvents] of Object.entries(
+      groupBy([...privateFnEvents, ...unconstrainedFnEvents], e => e.contractClassId.toString()),
+    )) {
+      const contractClassId = Fr.fromString(classIdString);
+      const contractClass = await this.getContractClass(contractClassId);
+      if (!contractClass) {
+        this.#log.warn(`Skipping broadcasted functions as contract class ${contractClassId.toString()} was not found`);
+        continue;
+      }
+
+      // Split private and unconstrained functions, and filter out invalid ones
+      const allFns = classEvents.map(e => e.toFunctionWithMembershipProof());
+      const privateFns = allFns.filter(
+        (fn): fn is ExecutablePrivateFunctionWithMembershipProof => 'unconstrainedFunctionsArtifactTreeRoot' in fn,
+      );
+      const unconstrainedFns = allFns.filter(
+        (fn): fn is UnconstrainedFunctionWithMembershipProof => 'privateFunctionsArtifactTreeRoot' in fn,
+      );
+      const validPrivateFns = privateFns.filter(fn => isValidPrivateFunctionMembershipProof(fn, contractClass));
+      const validUnconstrainedFns = unconstrainedFns.filter(fn =>
+        isValidUnconstrainedFunctionMembershipProof(fn, contractClass),
+      );
+      const validFnCount = validPrivateFns.length + validUnconstrainedFns.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, validUnconstrainedFns);
+    }
+    return true;
+  }
+
+  async addBlocks(blocks: L1Published<L2Block>[]): Promise<boolean> {
+    return [
+      this.store.addLogs(blocks.map(block => block.data)),
+      // Unroll all logs emitted during the retrieved blocks and extract any contract classes and instances from them
+      ...(await Promise.all(
+        blocks.map(async block => {
+          const blockLogs = block.data.body.txEffects
+            .flatMap(txEffect => (txEffect ? [txEffect.unencryptedLogs] : []))
+            .flatMap(txLog => txLog.unrollLogs());
+
+          return (
+            await Promise.all([
+              this.#updateRegisteredContractClasses(blockLogs, block.data.number, Operation.Store),
+              this.#updateDeployedContractInstances(blockLogs, block.data.number, Operation.Store),
+              this.#storeBroadcastedIndividualFunctions(blockLogs, block.data.number),
+            ])
+          ).every(Boolean);
+        }),
+      )),
+      this.store.addBlocks(blocks),
+    ].every(Boolean);
+  }
+
+  async unwindBlocks(from: number, blocksToUnwind: number): Promise<boolean> {
+    const last = await this.getSynchedL2BlockNumber();
+    if (from != last) {
+      throw new Error(`Can only remove from the tip`);
+    }
+
+    // from - blocksToUnwind = the new head, so + 1 for what we need to remove
+    const blocks = await this.getBlocks(from - blocksToUnwind + 1, blocksToUnwind);
+
+    return [
+      // Unroll all logs emitted during the retrieved blocks and extract any contract classes and instances from them
+      ...(await Promise.all(
+        blocks.map(async block => {
+          const blockLogs = block.data.body.txEffects
+            .flatMap(txEffect => (txEffect ? [txEffect.unencryptedLogs] : []))
+            .flatMap(txLog => txLog.unrollLogs());
+          await this.#updateRegisteredContractClasses(blockLogs, block.data.number, Operation.Delete);
+          await this.#updateDeployedContractInstances(blockLogs, block.data.number, Operation.Delete);
+        }),
+      )),
+      this.store.deleteLogs(blocks.map(b => b.data)),
+      this.store.unwindBlocks(from, blocksToUnwind),
+    ].every(Boolean);
+  }
+
+  getBlocks(from: number, limit: number): Promise<L1Published<L2Block>[]> {
+    return this.store.getBlocks(from, limit);
+  }
+  getBlockHeaders(from: number, limit: number): Promise<Header[]> {
+    return this.store.getBlockHeaders(from, limit);
+  }
+  getTxEffect(txHash: TxHash): Promise<TxEffect | undefined> {
+    return this.store.getTxEffect(txHash);
+  }
+  getSettledTxReceipt(txHash: TxHash): Promise<TxReceipt | undefined> {
+    return this.store.getSettledTxReceipt(txHash);
+  }
+  addL1ToL2Messages(messages: DataRetrieval<InboxLeaf>): Promise<boolean> {
+    return this.store.addL1ToL2Messages(messages);
+  }
+  getL1ToL2Messages(blockNumber: bigint): Promise<Fr[]> {
+    return this.store.getL1ToL2Messages(blockNumber);
+  }
+  getL1ToL2MessageIndex(l1ToL2Message: Fr, startIndex: bigint): Promise<bigint | undefined> {
+    return this.store.getL1ToL2MessageIndex(l1ToL2Message, startIndex);
+  }
+  getLogs<TLogType extends LogType>(
+    from: number,
+    limit: number,
+    logType: TLogType,
+  ): Promise<L2BlockL2Logs<FromLogType<TLogType>>[]> {
+    return this.store.getLogs(from, limit, logType);
+  }
+  getUnencryptedLogs(filter: LogFilter): Promise<GetUnencryptedLogsResponse> {
+    return this.store.getUnencryptedLogs(filter);
+  }
+  getSynchedL2BlockNumber(): Promise<number> {
+    return this.store.getSynchedL2BlockNumber();
+  }
+  getProvenL2BlockNumber(): Promise<number> {
+    return this.store.getProvenL2BlockNumber();
+  }
+  getProvenL2EpochNumber(): Promise<number | undefined> {
+    return this.store.getProvenL2EpochNumber();
+  }
+  setProvenL2BlockNumber(l2BlockNumber: number): Promise<void> {
+    return this.store.setProvenL2BlockNumber(l2BlockNumber);
+  }
+  setProvenL2EpochNumber(l2EpochNumber: number): Promise<void> {
+    return this.store.setProvenL2EpochNumber(l2EpochNumber);
+  }
+  setBlockSynchedL1BlockNumber(l1BlockNumber: bigint): Promise<void> {
+    return this.store.setBlockSynchedL1BlockNumber(l1BlockNumber);
+  }
+  setMessageSynchedL1BlockNumber(l1BlockNumber: bigint): Promise<void> {
+    return this.store.setMessageSynchedL1BlockNumber(l1BlockNumber);
+  }
+  getSynchPoint(): Promise<ArchiverL1SynchPoint> {
+    return this.store.getSynchPoint();
+  }
+  getContractClass(id: Fr): Promise<ContractClassPublic | undefined> {
+    return this.store.getContractClass(id);
+  }
+  getContractInstance(address: AztecAddress): Promise<ContractInstanceWithAddress | undefined> {
+    return this.store.getContractInstance(address);
+  }
+  getContractClassIds(): Promise<Fr[]> {
+    return this.store.getContractClassIds();
+  }
+  addContractArtifact(address: AztecAddress, contract: ContractArtifact): Promise<void> {
+    return this.store.addContractArtifact(address, contract);
+  }
+  getContractArtifact(address: AztecAddress): Promise<ContractArtifact | undefined> {
+    return this.store.getContractArtifact(address);
+  }
+  getTotalL1ToL2MessageCount(): Promise<bigint> {
+    return this.store.getTotalL1ToL2MessageCount();
+  }
+}
+
+type L1RollupConstants = {
+  l1StartBlock: bigint;
+  l1GenesisTime: bigint;
+};
+
+const EmptyL1RollupConstants: L1RollupConstants = {
+  l1StartBlock: 0n,
+  l1GenesisTime: 0n,
+};