@aztec/archiver 0.0.1-commit.21ecf947b → 0.0.1-commit.2448fdb

package/src/archiver.ts

@@ -1,5 +1,4 @@
 import type { BlobClientInterface } from '@aztec/blob-client/client';
-import { GENESIS_BLOCK_HEADER_HASH, INITIAL_L2_BLOCK_NUM } from '@aztec/constants';
 import { EpochCache } from '@aztec/epoch-cache';
 import { BlockTagTooOldError, RollupContract } from '@aztec/ethereum/contracts';
 import type { L1ContractAddresses } from '@aztec/ethereum/l1-contract-addresses';
@@ -15,8 +14,6 @@ import { RunningPromise, makeLoggingErrorHandler } from '@aztec/foundation/runni
 import { DateProvider } from '@aztec/foundation/timer';
 import {
   type ArchiverEmitter,
-  type CheckpointId,
-  GENESIS_CHECKPOINT_HEADER_HASH,
   L2Block,
   type L2BlockSink,
   type L2Tips,
@@ -25,22 +22,22 @@ import {
 import { PublishedCheckpoint } from '@aztec/stdlib/checkpoint';
 import {
   type L1RollupConstants,
-  getEpochNumberAtTimestamp,
+  getEpochAtSlot,
   getSlotAtNextL1Block,
-  getSlotAtTimestamp,
   getSlotRangeForEpoch,
   getTimestampRangeForEpoch,
 } from '@aztec/stdlib/epoch-helpers';
 import { type TelemetryClient, type Traceable, type Tracer, trackSpan } from '@aztec/telemetry-client';
 
 import { type ArchiverConfig, mapArchiverConfig } from './config.js';
-import { NoBlobBodiesFoundError } from './errors.js';
+import { BlockAlreadyCheckpointedError, NoBlobBodiesFoundError } from './errors.js';
 import { validateAndLogTraceAvailability } from './l1/validate_trace.js';
 import { ArchiverDataSourceBase } from './modules/data_source_base.js';
 import { ArchiverDataStoreUpdater } from './modules/data_store_updater.js';
 import type { ArchiverInstrumentation } from './modules/instrumentation.js';
 import type { ArchiverL1Synchronizer } from './modules/l1_synchronizer.js';
 import type { KVArchiverDataStore } from './store/kv_archiver_store.js';
+import { L2TipsCache } from './store/l2_tips_cache.js';
 
 /** Export ArchiverEmitter for use in factory and tests. */
 export type { ArchiverEmitter };
@@ -83,6 +80,9 @@ export class Archiver extends ArchiverDataSourceBase implements L2BlockSink, Tra
   /** Helper to handle updates to the store */
   private readonly updater: ArchiverDataStoreUpdater;
 
+  /** In-memory cache for L2 chain tips. */
+  private readonly l2TipsCache: L2TipsCache;
+
   public readonly tracer: Tracer;
 
   /**
@@ -119,9 +119,13 @@ export class Archiver extends ArchiverDataSourceBase implements L2BlockSink, Tra
     },
     private readonly blobClient: BlobClientInterface,
     instrumentation: ArchiverInstrumentation,
-    protected override readonly l1Constants: L1RollupConstants & { l1StartBlockHash: Buffer32; genesisArchiveRoot: Fr },
+    protected override readonly l1Constants: L1RollupConstants & {
+      l1StartBlockHash: Buffer32;
+      genesisArchiveRoot: Fr;
+    },
     synchronizer: ArchiverL1Synchronizer,
     events: ArchiverEmitter,
+    l2TipsCache?: L2TipsCache,
     private readonly log: Logger = createLogger('archiver'),
   ) {
     super(dataStore, l1Constants);
@@ -130,7 +134,10 @@ export class Archiver extends ArchiverDataSourceBase implements L2BlockSink, Tra
     this.initialSyncPromise = promiseWithResolvers();
     this.synchronizer = synchronizer;
     this.events = events;
-    this.updater = new ArchiverDataStoreUpdater(this.dataStore);
+    this.l2TipsCache = l2TipsCache ?? new L2TipsCache(this.dataStore.blockStore);
+    this.updater = new ArchiverDataStoreUpdater(this.dataStore, this.l2TipsCache, {
+      rollupManaLimit: l1Constants.rollupManaLimit,
+    });
 
     // Running promise starts with a small interval inbetween runs, so all iterations needed for the initial sync
     // are done as fast as possible. This then gets updated once the initial sync completes.
@@ -235,10 +242,15 @@ export class Archiver extends ArchiverDataSourceBase implements L2BlockSink, Tra
       }
 
       try {
-        await this.updater.addProposedBlocks([block]);
+        await this.updater.addProposedBlock(block);
         this.log.debug(`Added block ${block.number} to store`);
         resolve();
       } catch (err: any) {
+        if (err instanceof BlockAlreadyCheckpointedError) {
+          this.log.debug(`Proposed block ${block.number} matches already checkpointed block, ignoring late proposal`);
+          resolve();
+          continue;
+        }
         this.log.error(`Failed to add block ${block.number} to store: ${err.message}`);
         reject(err);
       }
@@ -330,16 +342,49 @@ export class Archiver extends ArchiverDataSourceBase implements L2BlockSink, Tra
     return Promise.resolve(this.synchronizer.getL1Timestamp());
   }
 
-  public getL2SlotNumber(): Promise<SlotNumber | undefined> {
+  public async getSyncedL2SlotNumber(): Promise<SlotNumber | undefined> {
+    // The synced L2 slot is the latest slot for which we have all L1 data,
+    // either because we have seen all L1 blocks for that slot, or because
+    // we have seen the corresponding checkpoint.
+
+    let slotFromL1Sync: SlotNumber | undefined;
     const l1Timestamp = this.synchronizer.getL1Timestamp();
-    return Promise.resolve(l1Timestamp === undefined ? undefined : getSlotAtTimestamp(l1Timestamp, this.l1Constants));
+    if (l1Timestamp !== undefined) {
+      const nextL1BlockSlot = getSlotAtNextL1Block(l1Timestamp, this.l1Constants);
+      if (Number(nextL1BlockSlot) > 0) {
+        slotFromL1Sync = SlotNumber.add(nextL1BlockSlot, -1);
+      }
+    }
+
+    let slotFromCheckpoint: SlotNumber | undefined;
+    const latestCheckpointNumber = await this.store.getSynchedCheckpointNumber();
+    if (latestCheckpointNumber > 0) {
+      const checkpointData = await this.store.getCheckpointData(latestCheckpointNumber);
+      if (checkpointData) {
+        slotFromCheckpoint = checkpointData.header.slotNumber;
+      }
+    }
+
+    if (slotFromL1Sync === undefined && slotFromCheckpoint === undefined) {
+      return undefined;
+    }
+    return SlotNumber(Math.max(slotFromL1Sync ?? 0, slotFromCheckpoint ?? 0));
   }
 
-  public getL2EpochNumber(): Promise<EpochNumber | undefined> {
-    const l1Timestamp = this.synchronizer.getL1Timestamp();
-    return Promise.resolve(
-      l1Timestamp === undefined ? undefined : getEpochNumberAtTimestamp(l1Timestamp, this.l1Constants),
-    );
+  public async getSyncedL2EpochNumber(): Promise<EpochNumber | undefined> {
+    const syncedSlot = await this.getSyncedL2SlotNumber();
+    if (syncedSlot === undefined) {
+      return undefined;
+    }
+    // An epoch is fully synced when all its slots are synced.
+    // We check if syncedSlot is the last slot of its epoch; if so, that epoch is fully synced.
+    // Otherwise, only the previous epoch is fully synced.
+    const epoch = getEpochAtSlot(syncedSlot, this.l1Constants);
+    const [, endSlot] = getSlotRangeForEpoch(epoch, this.l1Constants);
+    if (syncedSlot >= endSlot) {
+      return epoch;
+    }
+    return Number(epoch) > 0 ? EpochNumber(Number(epoch) - 1) : undefined;
   }
 
   public async isEpochComplete(epochNumber: EpochNumber): Promise<boolean> {
@@ -391,115 +436,11 @@ export class Archiver extends ArchiverDataSourceBase implements L2BlockSink, Tra
     return true;
   }
 
-  public async getL2Tips(): Promise<L2Tips> {
-    const [latestBlockNumber, provenBlockNumber, checkpointedBlockNumber, finalizedBlockNumber] = await Promise.all([
-      this.getBlockNumber(),
-      this.getProvenBlockNumber(),
-      this.getCheckpointedL2BlockNumber(),
-      this.getFinalizedL2BlockNumber(),
-    ] as const);
-
-    const beforeInitialblockNumber = BlockNumber(INITIAL_L2_BLOCK_NUM - 1);
-
-    // Get the latest block header and checkpointed blocks for proven, finalised and checkpointed blocks
-    const [latestBlockHeader, provenCheckpointedBlock, finalizedCheckpointedBlock, checkpointedBlock] =
-      await Promise.all([
-        latestBlockNumber > beforeInitialblockNumber ? this.getBlockHeader(latestBlockNumber) : undefined,
-        provenBlockNumber > beforeInitialblockNumber ? this.getCheckpointedBlock(provenBlockNumber) : undefined,
-        finalizedBlockNumber > beforeInitialblockNumber ? this.getCheckpointedBlock(finalizedBlockNumber) : undefined,
-        checkpointedBlockNumber > beforeInitialblockNumber
-          ? this.getCheckpointedBlock(checkpointedBlockNumber)
-          : undefined,
-      ] as const);
-
-    if (latestBlockNumber > beforeInitialblockNumber && !latestBlockHeader) {
-      throw new Error(`Failed to retrieve latest block header for block ${latestBlockNumber}`);
-    }
-
-    // Checkpointed blocks must exist for proven, finalized and checkpointed tips if they are beyond the initial block number.
-    if (checkpointedBlockNumber > beforeInitialblockNumber && !checkpointedBlock?.block.header) {
-      throw new Error(
-        `Failed to retrieve checkpointed block header for block ${checkpointedBlockNumber} (latest block is ${latestBlockNumber})`,
-      );
-    }
-
-    if (provenBlockNumber > beforeInitialblockNumber && !provenCheckpointedBlock?.block.header) {
-      throw new Error(
-        `Failed to retrieve proven checkpointed for block ${provenBlockNumber} (latest block is ${latestBlockNumber})`,
-      );
-    }
-
-    if (finalizedBlockNumber > beforeInitialblockNumber && !finalizedCheckpointedBlock?.block.header) {
-      throw new Error(
-        `Failed to retrieve finalized block header for block ${finalizedBlockNumber} (latest block is ${latestBlockNumber})`,
-      );
-    }
-
-    const latestBlockHeaderHash = (await latestBlockHeader?.hash()) ?? GENESIS_BLOCK_HEADER_HASH;
-    const provenBlockHeaderHash = (await provenCheckpointedBlock?.block.header?.hash()) ?? GENESIS_BLOCK_HEADER_HASH;
-    const finalizedBlockHeaderHash =
-      (await finalizedCheckpointedBlock?.block.header?.hash()) ?? GENESIS_BLOCK_HEADER_HASH;
-    const checkpointedBlockHeaderHash = (await checkpointedBlock?.block.header?.hash()) ?? GENESIS_BLOCK_HEADER_HASH;
-
-    // Now attempt to retrieve checkpoints for proven, finalised and checkpointed blocks
-    const [[provenBlockCheckpoint], [finalizedBlockCheckpoint], [checkpointedBlockCheckpoint]] = await Promise.all([
-      provenCheckpointedBlock !== undefined
-        ? await this.getCheckpoints(provenCheckpointedBlock?.checkpointNumber, 1)
-        : [undefined],
-      finalizedCheckpointedBlock !== undefined
-        ? await this.getCheckpoints(finalizedCheckpointedBlock?.checkpointNumber, 1)
-        : [undefined],
-      checkpointedBlock !== undefined ? await this.getCheckpoints(checkpointedBlock?.checkpointNumber, 1) : [undefined],
-    ]);
-
-    const initialcheckpointId: CheckpointId = {
-      number: CheckpointNumber.ZERO,
-      hash: GENESIS_CHECKPOINT_HEADER_HASH.toString(),
-    };
-
-    const makeCheckpointId = (checkpoint: PublishedCheckpoint | undefined) => {
-      if (checkpoint === undefined) {
-        return initialcheckpointId;
-      }
-      return {
-        number: checkpoint.checkpoint.number,
-        hash: checkpoint.checkpoint.hash().toString(),
-      };
-    };
-
-    const l2Tips: L2Tips = {
-      proposed: {
-        number: latestBlockNumber,
-        hash: latestBlockHeaderHash.toString(),
-      },
-      proven: {
-        block: {
-          number: provenBlockNumber,
-          hash: provenBlockHeaderHash.toString(),
-        },
-        checkpoint: makeCheckpointId(provenBlockCheckpoint),
-      },
-      finalized: {
-        block: {
-          number: finalizedBlockNumber,
-          hash: finalizedBlockHeaderHash.toString(),
-        },
-        checkpoint: makeCheckpointId(finalizedBlockCheckpoint),
-      },
-      checkpointed: {
-        block: {
-          number: checkpointedBlockNumber,
-          hash: checkpointedBlockHeaderHash.toString(),
-        },
-        checkpoint: makeCheckpointId(checkpointedBlockCheckpoint),
-      },
-    };
-
-    return l2Tips;
+  public getL2Tips(): Promise<L2Tips> {
+    return this.l2TipsCache.getL2Tips();
   }
 
   public async rollbackTo(targetL2BlockNumber: BlockNumber): Promise<void> {
-    // TODO(pw/mbps): This still assumes 1 block per checkpoint
     const currentBlocks = await this.getL2Tips();
     const currentL2Block = currentBlocks.proposed.number;
     const currentProvenBlock = currentBlocks.proven.block.number;
@@ -511,8 +452,25 @@ export class Archiver extends ArchiverDataSourceBase implements L2BlockSink, Tra
     if (!targetL2Block) {
       throw new Error(`Target L2 block ${targetL2BlockNumber} not found`);
     }
-    const targetL1BlockNumber = targetL2Block.l1.blockNumber;
     const targetCheckpointNumber = targetL2Block.checkpointNumber;
+
+    // Rollback operates at checkpoint granularity: the target block must be the last block of its checkpoint.
+    const checkpointData = await this.store.getCheckpointData(targetCheckpointNumber);
+    if (checkpointData) {
+      const lastBlockInCheckpoint = BlockNumber(checkpointData.startBlock + checkpointData.blockCount - 1);
+      if (targetL2BlockNumber !== lastBlockInCheckpoint) {
+        const previousCheckpointBoundary =
+          checkpointData.startBlock > 1 ? BlockNumber(checkpointData.startBlock - 1) : BlockNumber(0);
+        throw new Error(
+          `Target L2 block ${targetL2BlockNumber} is not at a checkpoint boundary. ` +
+            `Checkpoint ${targetCheckpointNumber} spans blocks ${checkpointData.startBlock} to ${lastBlockInCheckpoint}. ` +
+            `Use block ${lastBlockInCheckpoint} to roll back to this checkpoint, ` +
+            `or block ${previousCheckpointBoundary} to roll back to the previous one.`,
+        );
+      }
+    }
+
+    const targetL1BlockNumber = targetL2Block.l1.blockNumber;
     const targetL1Block = await this.publicClient.getBlock({
       blockNumber: targetL1BlockNumber,
       includeTransactions: false,
@@ -531,13 +489,13 @@ export class Archiver extends ArchiverDataSourceBase implements L2BlockSink, Tra
     await this.store.setCheckpointSynchedL1BlockNumber(targetL1BlockNumber);
     await this.store.setMessageSynchedL1Block({ l1BlockNumber: targetL1BlockNumber, l1BlockHash: targetL1BlockHash });
     if (targetL2BlockNumber < currentProvenBlock) {
-      this.log.info(`Clearing proven L2 block number`);
-      await this.store.setProvenCheckpointNumber(CheckpointNumber.ZERO);
+      this.log.info(`Rolling back proven L2 checkpoint to ${targetCheckpointNumber}`);
+      await this.updater.setProvenCheckpointNumber(targetCheckpointNumber);
+    }
+    const currentFinalizedBlock = currentBlocks.finalized.block.number;
+    if (targetL2BlockNumber < currentFinalizedBlock) {
+      this.log.info(`Rolling back finalized L2 checkpoint to ${targetCheckpointNumber}`);
+      await this.updater.setFinalizedCheckpointNumber(targetCheckpointNumber);
     }
-    // TODO(palla/reorg): Set the finalized block when we add support for it.
-    // if (targetL2BlockNumber < currentFinalizedBlock) {
-    //   this.log.info(`Clearing finalized L2 block number`);
-    //   await this.store.setFinalizedL2BlockNumber(0);
-    // }
   }
 }

package/src/errors.ts

@@ -6,24 +6,9 @@ export class NoBlobBodiesFoundError extends Error {
   }
 }
 
-export class InitialBlockNumberNotSequentialError extends Error {
-  constructor(
-    public readonly newBlockNumber: number,
-    public readonly previousBlockNumber: number | undefined,
-  ) {
-    super(
-      `Cannot insert new block ${newBlockNumber} given previous block number in store is ${
-        previousBlockNumber ?? 'undefined'
-      }`,
-    );
-  }
-}
-
 export class BlockNumberNotSequentialError extends Error {
   constructor(newBlockNumber: number, previous: number | undefined) {
-    super(
-      `Cannot insert new block ${newBlockNumber} given previous block number in batch is ${previous ?? 'undefined'}`,
-    );
+    super(`Cannot insert new block ${newBlockNumber} given previous block number is ${previous ?? 'undefined'}`);
   }
 }
 
@@ -48,14 +33,6 @@ export class CheckpointNumberNotSequentialError extends Error {
   }
 }
 
-export class CheckpointNumberNotConsistentError extends Error {
-  constructor(newCheckpointNumber: number, previous: number | undefined) {
-    super(
-      `Cannot insert block for new checkpoint ${newCheckpointNumber} given previous block was checkpoint ${previous ?? 'undefined'}`,
-    );
-  }
-}
-
 export class BlockIndexNotSequentialError extends Error {
   constructor(newBlockIndex: number, previousBlockIndex: number | undefined) {
     super(
@@ -89,6 +66,15 @@ export class BlockNotFoundError extends Error {
   }
 }
 
+/** Thrown when a proposed block matches a block that was already checkpointed. This is expected for late proposals. */
+export class BlockAlreadyCheckpointedError extends Error {
+  constructor(public readonly blockNumber: number) {
+    super(`Block ${blockNumber} has already been checkpointed with the same content`);
+    this.name = 'BlockAlreadyCheckpointedError';
+  }
+}
+
+/** Thrown when a proposed block conflicts with an already checkpointed block (different content). */
 export class CannotOverwriteCheckpointedBlockError extends Error {
   constructor(
     public readonly blockNumber: number,

package/src/factory.ts

@@ -1,5 +1,6 @@
 import { EpochCache } from '@aztec/epoch-cache';
 import { createEthereumChain } from '@aztec/ethereum/chain';
+import { makeL1HttpTransport } from '@aztec/ethereum/client';
 import { InboxContract, RollupContract } from '@aztec/ethereum/contracts';
 import type { ViemPublicDebugClient } from '@aztec/ethereum/types';
 import { BlockNumber } from '@aztec/foundation/branded-types';
@@ -13,32 +14,31 @@ import { protocolContractNames } from '@aztec/protocol-contracts';
 import { BundledProtocolContractsProvider } from '@aztec/protocol-contracts/providers/bundle';
 import { FunctionType, decodeFunctionSignature } from '@aztec/stdlib/abi';
 import type { ArchiverEmitter } from '@aztec/stdlib/block';
-import { type ContractClassPublic, computePublicBytecodeCommitment } from '@aztec/stdlib/contract';
-import type { L1RollupConstants } from '@aztec/stdlib/epoch-helpers';
+import { type ContractClassPublicWithCommitment, computePublicBytecodeCommitment } from '@aztec/stdlib/contract';
 import { getTelemetryClient } from '@aztec/telemetry-client';
 
 import { EventEmitter } from 'events';
-import { createPublicClient, fallback, http } from 'viem';
+import { createPublicClient } from 'viem';
 
 import { Archiver, type ArchiverDeps } from './archiver.js';
 import { type ArchiverConfig, mapArchiverConfig } from './config.js';
 import { ArchiverInstrumentation } from './modules/instrumentation.js';
 import { ArchiverL1Synchronizer } from './modules/l1_synchronizer.js';
 import { ARCHIVER_DB_VERSION, KVArchiverDataStore } from './store/kv_archiver_store.js';
+import { L2TipsCache } from './store/l2_tips_cache.js';
 
 export const ARCHIVER_STORE_NAME = 'archiver';
 
 /** Creates an archiver store. */
 export async function createArchiverStore(
   userConfig: Pick<ArchiverConfig, 'archiverStoreMapSizeKb' | 'maxLogs'> & DataStoreConfig,
-  l1Constants: Pick<L1RollupConstants, 'epochDuration'>,
 ) {
   const config = {
     ...userConfig,
     dataStoreMapSizeKb: userConfig.archiverStoreMapSizeKb ?? userConfig.dataStoreMapSizeKb,
   };
   const store = await createStore(ARCHIVER_STORE_NAME, ARCHIVER_DB_VERSION, config);
-  return new KVArchiverDataStore(store, config.maxLogs, l1Constants);
+  return new KVArchiverDataStore(store, config.maxLogs);
 }
 
 /**
@@ -53,14 +53,15 @@ export async function createArchiver(
   deps: ArchiverDeps,
   opts: { blockUntilSync: boolean } = { blockUntilSync: true },
 ): Promise<Archiver> {
-  const archiverStore = await createArchiverStore(config, { epochDuration: config.aztecEpochDuration });
+  const archiverStore = await createArchiverStore(config);
   await registerProtocolContracts(archiverStore);
 
   // Create Ethereum clients
   const chain = createEthereumChain(config.l1RpcUrls, config.l1ChainId);
+  const httpTimeout = config.l1HttpTimeoutMS;
   const publicClient = createPublicClient({
     chain: chain.chainInfo,
-    transport: fallback(config.l1RpcUrls.map(url => http(url, { batch: false }))),
+    transport: makeL1HttpTransport(config.l1RpcUrls, { timeout: httpTimeout }),
     pollingInterval: config.viemPollingIntervalMS,
   });
 
@@ -68,7 +69,7 @@ export async function createArchiver(
   const debugRpcUrls = config.l1DebugRpcUrls.length > 0 ? config.l1DebugRpcUrls : config.l1RpcUrls;
   const debugClient = createPublicClient({
     chain: chain.chainInfo,
-    transport: fallback(debugRpcUrls.map(url => http(url, { batch: false }))),
+    transport: makeL1HttpTransport(debugRpcUrls, { timeout: httpTimeout }),
     pollingInterval: config.viemPollingIntervalMS,
   }) as ViemPublicDebugClient;
 
@@ -84,6 +85,7 @@ export async function createArchiver(
     genesisArchiveRoot,
     slashingProposerAddress,
     targetCommitteeSize,
+    rollupManaLimit,
   ] = await Promise.all([
     rollup.getL1StartBlock(),
     rollup.getL1GenesisTime(),
@@ -91,6 +93,7 @@ export async function createArchiver(
     rollup.getGenesisArchiveTreeRoot(),
     rollup.getSlashingProposerAddress(),
     rollup.getTargetCommitteeSize(),
+    rollup.getManaLimit(),
   ] as const);
 
   const l1StartBlockHash = await publicClient
@@ -109,6 +112,7 @@ export async function createArchiver(
     proofSubmissionEpochs: Number(proofSubmissionEpochs),
     targetCommitteeSize,
     genesisArchiveRoot: Fr.fromString(genesisArchiveRoot.toString()),
+    rollupManaLimit: Number(rollupManaLimit),
   };
 
   const archiverConfig = merge(
@@ -128,13 +132,15 @@ export async function createArchiver(
   // Create the event emitter that will be shared by archiver and synchronizer
   const events = new EventEmitter() as ArchiverEmitter;
 
+  // Create L2 tips cache shared by archiver and synchronizer
+  const l2TipsCache = new L2TipsCache(archiverStore.blockStore);
+
   // Create the L1 synchronizer
   const synchronizer = new ArchiverL1Synchronizer(
     publicClient,
     debugClient,
     rollup,
     inbox,
-    { ...config.l1Contracts, slashingProposerAddress },
     archiverStore,
     archiverConfig,
     deps.blobClient,
@@ -144,6 +150,8 @@ export async function createArchiver(
     l1Constants,
     events,
     instrumentation.tracer,
+    l2TipsCache,
+    undefined, // log (use default)
   );
 
   const archiver = new Archiver(
@@ -158,20 +166,29 @@ export async function createArchiver(
     l1Constants,
     synchronizer,
     events,
+    l2TipsCache,
   );
 
   await archiver.start(opts.blockUntilSync);
   return archiver;
 }
 
-/** Registers protocol contracts in the archiver store. */
+/** Registers protocol contracts in the archiver store. Idempotent — skips contracts that already exist (e.g. on node restart). */
 export async function registerProtocolContracts(store: KVArchiverDataStore) {
   const blockNumber = 0;
   for (const name of protocolContractNames) {
     const provider = new BundledProtocolContractsProvider();
     const contract = await provider.getProtocolContractArtifact(name);
-    const contractClassPublic: ContractClassPublic = {
+
+    // Skip if already registered (happens on node restart with a persisted store).
+    if (await store.getContractClass(contract.contractClass.id)) {
+      continue;
+    }
+
+    const publicBytecodeCommitment = await computePublicBytecodeCommitment(contract.contractClass.packedBytecode);
+    const contractClassPublic: ContractClassPublicWithCommitment = {
       ...contract.contractClass,
+      publicBytecodeCommitment,
       privateFunctions: [],
       utilityFunctions: [],
     };
@@ -181,8 +198,7 @@ export async function registerProtocolContracts(store: KVArchiverDataStore) {
       .map(fn => decodeFunctionSignature(fn.name, fn.parameters));
 
     await store.registerContractFunctionSignatures(publicFunctionSignatures);
-    const bytecodeCommitment = await computePublicBytecodeCommitment(contractClassPublic.packedBytecode);
-    await store.addContractClasses([contractClassPublic], [bytecodeCommitment], BlockNumber(blockNumber));
+    await store.addContractClasses([contractClassPublic], BlockNumber(blockNumber));
     await store.addContractInstances([contract.instance], BlockNumber(blockNumber));
   }
 }

package/src/index.ts

@@ -8,5 +8,6 @@ export * from './config.js';
 export { type L1PublishedData } from './structs/published.js';
 export { KVArchiverDataStore, ARCHIVER_DB_VERSION } from './store/kv_archiver_store.js';
 export { ContractInstanceStore } from './store/contract_instance_store.js';
+export { L2TipsCache } from './store/l2_tips_cache.js';
 
 export { retrieveCheckpointsFromRollup, retrieveL2ProofVerifiedEvents } from './l1/data_retrieval.js';

package/src/l1/README.md

@@ -5,29 +5,27 @@ Modules and classes to handle data retrieval from L1 for the archiver.
 ## Calldata Retriever
 
 The sequencer publisher bundles multiple operations into a single multicall3 transaction for gas
-efficiency. A typical transaction includes:
+efficiency. The archiver needs to extract the `propose` calldata from these bundled transactions
+to reconstruct L2 blocks.
 
-1. Attestation invalidations (if needed): `invalidateBadAttestation`, `invalidateInsufficientAttestations`
-2. Block proposal: `propose` (exactly one per transaction to the rollup contract)
-3. Governance and slashing (if needed): votes, payload creation/execution
+The retriever uses hash matching against `attestationsHash` and `payloadDigest` from the
+`CheckpointProposed` L1 event to verify it has found the correct propose calldata. These hashes
+are always required.
 
-The archiver needs to extract the `propose` calldata from these bundled transactions to reconstruct
-L2 blocks. This class needs to handle scenarios where the transaction was submitted via multicall3,
-as well as alternative ways for submitting the `propose` call that other clients might use.
+### Multicall3 Decoding with Hash Matching
 
-### Multicall3 Validation and Decoding
-
-First attempt to decode the transaction as a multicall3 `aggregate3` call with validation:
+First attempt to decode the transaction as a multicall3 `aggregate3` call:
 
 - Check if transaction is to multicall3 address (`0xcA11bde05977b3631167028862bE2a173976CA11`)
 - Decode as `aggregate3(Call3[] calldata calls)`
-- Allow calls to known addresses and methods (rollup, governance, slashing contracts, etc.)
-- Find the single `propose` call to the rollup contract
-- Verify exactly one `propose` call exists
-- Extract and return the propose calldata
+- Find all calls matching the rollup contract address and the `propose` function selector
+- Verify each candidate by computing `attestationsHash` (keccak256 of ABI-encoded attestations)
+  and `payloadDigest` (keccak256 of the consensus payload signing hash) and comparing against
+  expected values from the `CheckpointProposed` event
+- Return the verified candidate (if multiple verify, return the first with a warning)
 
-This step handles the common case efficiently without requiring expensive trace or debug RPC calls.
-Any validation failure triggers fallback to the next step.
+This approach works regardless of what other calls are in the multicall3 bundle, because hash
+matching identifies the correct propose call without needing an allowlist.
 
 ### Direct Propose Call
 
@@ -35,64 +33,23 @@ Second attempt to decode the transaction as a direct `propose` call to the rollu
 
 - Check if transaction is to the rollup address
 - Decode as `propose` function call
-- Verify the function is indeed `propose`
+- Verify against expected hashes
 - Return the transaction input as the propose calldata
 
-This handles scenarios where clients submit transactions directly to the rollup contract without
-using multicall3 for bundling. Any validation failure triggers fallback to the next step.
-
 ### Spire Proposer Call
 
-Given existing attempts to route the call via the Spire proposer, we also check if the tx is `to` the 
-proposer known address, and if so, we try decoding it as either a multicall3 or a direct call to the
-rollup contract.
-
-Similar as with the multicall3 check, we check that there are no other calls in the Spire proposer, so
-we are absolutely sure that the only call is the successful one to the rollup. Any extraneous call would
-imply an unexpected path to calling `propose` in the rollup contract, and since we cannot verify if the
-calldata arguments we extracted are the correct ones (see the section below), we cannot know for sure which
-one is the call that succeeded, so we don't know which calldata to process.
-
-Furthermore, since the Spire proposer is upgradeable, we check if the implementation has not changed in
-order to decode. As usual, any validation failure triggers fallback to the next step.
-
-### Verifying Multicall3 Arguments
-
-**This is NOT implemented for simplicity's sake**
-
-If the checks above don't hold, such as when there are multiple calls to `propose`, then we cannot
-reliably extract the `propose` calldata from the multicall3 arguments alone. We can try a best-effort
-where we try all `propose` calls we see and validate them against on-chain data. Note that we can use these
-same strategies if we were to obtain the calldata from another source.
-
-#### TempBlockLog Verification
-
-Read the stored `TempBlockLog` for the L2 block number from L1 and verify it matches our decoded header hash,
-since the `TempBlockLog` stores the hash of the proposed block header, the payload commitment, and the attestations.
-
-However, `TempBlockLog` is only stored temporarily and deleted after proven, so this method only works for recent
-blocks, not for historical data syncing.
-
-#### Archive Verification
-
-Verify that the archive root in the decoded propose is correct with regard to the block header. This requires
-hashing the block header we have retrieved, inserting it into the archive tree, and checking the resulting root
-against the one we got from L1.
-
-However, this requires that the archive keeps a reference to world-state, which is not the case in the current
-system.
-
-#### Emit Commitments in Rollup Contract
-
-Modify rollup contract to emit commitments to the block header in the `L2BlockProposed` event, allowing us to easily
-verify the calldata we obtained vs the emitted event.
+Given existing attempts to route the call via the Spire proposer, we also check if the tx is
+`to` the proposer known address. If so, we extract all wrapped calls and try each as either
+a multicall3 or direct propose call, using hash matching to find and verify the correct one.
 
-However, modifying the rollup contract is out of scope for this change. But we can implement this approach in `v2`.
+Since the Spire proposer is upgradeable, we check that the implementation has not changed in
+order to decode. Any validation failure triggers fallback to the next step.
 
 ### Debug and Trace Transaction Fallback
 
-Last, we use L1 node's trace/debug RPC methods to definitively identify the one successful `propose` call within the tx.
-We can then extract the exact calldata that hit the `propose` function in the rollup contract.
+Last, we use L1 node's trace/debug RPC methods to definitively identify the one successful
+`propose` call within the tx. We can then extract the exact calldata that hit the `propose`
+function in the rollup contract.
 
-This approach requires access to a debug-enabled L1 node, which may be more resource-intensive, so we only
-use it as a fallback when the first step fails, which should be rare in practice.
+This approach requires access to a debug-enabled L1 node, which may be more resource-intensive,
+so we only use it as a fallback when earlier steps fail, which should be rare in practice.