@aztec/archiver 3.0.0-devnet.2 → 3.0.0-devnet.2-patch.1

package/src/archiver/config.ts

@@ -1,11 +1,7 @@
 import { type BlobSinkConfig, blobSinkConfigMapping } from '@aztec/blob-sink/client';
-import {
-  type L1ContractsConfig,
-  type L1ReaderConfig,
-  l1ContractAddressesMapping,
-  l1ContractsConfigMappings,
-  l1ReaderConfigMappings,
-} from '@aztec/ethereum';
+import { type L1ContractsConfig, l1ContractsConfigMappings } from '@aztec/ethereum/config';
+import { l1ContractAddressesMapping } from '@aztec/ethereum/l1-contract-addresses';
+import { type L1ReaderConfig, l1ReaderConfigMappings } from '@aztec/ethereum/l1-reader';
 import {
   type ConfigMappingsType,
   booleanConfigHelper,
@@ -50,6 +46,16 @@ export const archiverConfigMappings: ConfigMappingsType<ArchiverConfig> = {
     description: 'Whether to skip validating block attestations (use only for testing).',
     ...booleanConfigHelper(false),
   },
+  maxAllowedEthClientDriftSeconds: {
+    env: 'MAX_ALLOWED_ETH_CLIENT_DRIFT_SECONDS',
+    description: 'Maximum allowed drift in seconds between the Ethereum client and current time.',
+    ...numberConfigHelper(300),
+  },
+  ethereumAllowNoDebugHosts: {
+    env: 'ETHEREUM_ALLOW_NO_DEBUG_HOSTS',
+    description: 'Whether to allow starting the archiver without debug/trace method support on Ethereum hosts',
+    ...booleanConfigHelper(true),
+  },
   ...chainConfigMappings,
   ...l1ReaderConfigMappings,
   viemPollingIntervalMS: {

package/src/archiver/instrumentation.ts

@@ -1,5 +1,5 @@
 import { createLogger } from '@aztec/foundation/log';
-import type { L2Block } from '@aztec/stdlib/block';
+import type { L2BlockNew } from '@aztec/stdlib/block';
 import {
   Attributes,
   type Gauge,
@@ -34,6 +34,8 @@ export class ArchiverInstrumentation {
   private syncDurationPerMessage: Histogram;
   private syncMessageCount: UpDownCounter;
 
+  private blockProposalTxTargetCount: UpDownCounter;
+
   private log = createLogger('archiver:instrumentation');
 
   private constructor(
@@ -114,6 +116,11 @@ export class ArchiverInstrumentation {
       valueType: ValueType.INT,
     });
 
+    this.blockProposalTxTargetCount = meter.createUpDownCounter(Metrics.ARCHIVER_BLOCK_PROPOSAL_TX_TARGET_COUNT, {
+      description: 'Number of block proposals by tx target',
+      valueType: ValueType.INT,
+    });
+
     this.dbMetrics = new LmdbMetrics(
       meter,
       {
@@ -139,7 +146,7 @@ export class ArchiverInstrumentation {
     return this.telemetry.isEnabled();
   }
 
-  public processNewBlocks(syncTimePerBlock: number, blocks: L2Block[]) {
+  public processNewBlocks(syncTimePerBlock: number, blocks: L2BlockNew[]) {
     this.syncDurationPerBlock.record(Math.ceil(syncTimePerBlock));
     this.blockHeight.record(Math.max(...blocks.map(b => b.number)));
     this.syncBlockCount.add(blocks.length);
@@ -184,4 +191,11 @@ export class ArchiverInstrumentation {
   public updateL1BlockHeight(blockNumber: bigint) {
     this.l1BlockHeight.record(Number(blockNumber));
   }
+
+  public recordBlockProposalTxTarget(target: string, usedTrace: boolean) {
+    this.blockProposalTxTargetCount.add(1, {
+      [Attributes.L1_BLOCK_PROPOSAL_TX_TARGET]: target.toLowerCase(),
+      [Attributes.L1_BLOCK_PROPOSAL_USED_TRACE]: usedTrace,
+    });
+  }
 }

package/src/archiver/kv_archiver_store/block_store.ts

@@ -1,5 +1,6 @@
 import { INITIAL_L2_BLOCK_NUM } from '@aztec/constants';
-import { Fr } from '@aztec/foundation/fields';
+import { BlockNumber } from '@aztec/foundation/branded-types';
+import { Fr } from '@aztec/foundation/curves/bn254';
 import { toArray } from '@aztec/foundation/iterable';
 import { createLogger } from '@aztec/foundation/log';
 import { BufferReader } from '@aztec/foundation/serialize';
@@ -158,7 +159,7 @@ export class BlockStore {
    * @param blocksToUnwind - The number of blocks we are to unwind
    * @returns True if the operation is successful
    */
-  async unwindBlocks(from: number, blocksToUnwind: number) {
+  async unwindBlocks(from: BlockNumber, blocksToUnwind: number) {
     return await this.db.transactionAsync(async () => {
       const last = await this.getSynchedL2BlockNumber();
       if (from !== last) {
@@ -167,12 +168,12 @@ export class BlockStore {
 
       const proven = await this.getProvenL2BlockNumber();
       if (from - blocksToUnwind < proven) {
-        await this.setProvenL2BlockNumber(from - blocksToUnwind);
+        await this.setProvenL2BlockNumber(BlockNumber(from - blocksToUnwind));
       }
 
       for (let i = 0; i < blocksToUnwind; i++) {
         const blockNumber = from - i;
-        const block = await this.getBlock(blockNumber);
+        const block = await this.getBlock(BlockNumber(blockNumber));
 
         if (block === undefined) {
           this.#log.warn(`Cannot remove block ${blockNumber} from the store since we don't have it`);
@@ -200,7 +201,7 @@ export class BlockStore {
    * @param limit - The number of blocks to return.
    * @returns The requested L2 blocks
    */
-  async *getBlocks(start: number, limit: number): AsyncIterableIterator<PublishedL2Block> {
+  async *getBlocks(start: BlockNumber, limit: number): AsyncIterableIterator<PublishedL2Block> {
     for await (const [blockNumber, blockStorage] of this.getBlockStorages(start, limit)) {
       const block = await this.getBlockFromBlockStorage(blockNumber, blockStorage);
       if (block) {
@@ -214,7 +215,7 @@ export class BlockStore {
    * @param blockNumber - The number of the block to return.
    * @returns The requested L2 block.
    */
-  async getBlock(blockNumber: number): Promise<PublishedL2Block | undefined> {
+  async getBlock(blockNumber: BlockNumber): Promise<PublishedL2Block | undefined> {
     const blockStorage = await this.#blocks.getAsync(blockNumber);
     if (!blockStorage || !blockStorage.header) {
       return Promise.resolve(undefined);
@@ -232,7 +233,7 @@ export class BlockStore {
     if (blockNumber === undefined) {
       return undefined;
     }
-    return this.getBlock(blockNumber);
+    return this.getBlock(BlockNumber(blockNumber));
   }
 
   /**
@@ -245,7 +246,7 @@ export class BlockStore {
     if (blockNumber === undefined) {
       return undefined;
     }
-    return this.getBlock(blockNumber);
+    return this.getBlock(BlockNumber(blockNumber));
   }
 
   /**
@@ -288,7 +289,7 @@ export class BlockStore {
    * @param limit - The number of blocks to return.
    * @returns The requested L2 block headers
    */
-  async *getBlockHeaders(start: number, limit: number): AsyncIterableIterator<BlockHeader> {
+  async *getBlockHeaders(start: BlockNumber, limit: number): AsyncIterableIterator<BlockHeader> {
     for await (const [blockNumber, blockStorage] of this.getBlockStorages(start, limit)) {
       const header = L2BlockHeader.fromBuffer(blockStorage.header).toBlockHeader();
       if (header.getBlockNumber() !== blockNumber) {
@@ -300,7 +301,7 @@ export class BlockStore {
     }
   }
 
-  private async *getBlockStorages(start: number, limit: number) {
+  private async *getBlockStorages(start: BlockNumber, limit: number) {
     let expectedBlockNumber = start;
     for await (const [blockNumber, blockStorage] of this.#blocks.entriesAsync(this.#computeBlockRange(start, limit))) {
       if (blockNumber !== expectedBlockNumber) {
@@ -382,7 +383,7 @@ export class BlockStore {
       '',
       txEffect.data.transactionFee.toBigInt(),
       txEffect.l2BlockHash,
-      txEffect.l2BlockNumber,
+      BlockNumber(txEffect.l2BlockNumber),
     );
   }
 
@@ -413,9 +414,9 @@ export class BlockStore {
    * Gets the number of the latest L2 block processed.
    * @returns The number of the latest L2 block processed.
    */
-  async getSynchedL2BlockNumber(): Promise<number> {
+  async getSynchedL2BlockNumber(): Promise<BlockNumber> {
     const [lastBlockNumber] = await toArray(this.#blocks.keysAsync({ reverse: true, limit: 1 }));
-    return typeof lastBlockNumber === 'number' ? lastBlockNumber : INITIAL_L2_BLOCK_NUM - 1;
+    return typeof lastBlockNumber === 'number' ? BlockNumber(lastBlockNumber) : BlockNumber(INITIAL_L2_BLOCK_NUM - 1);
   }
 
   /**
@@ -430,19 +431,19 @@ export class BlockStore {
     return this.#lastSynchedL1Block.set(l1BlockNumber);
   }
 
-  async getProvenL2BlockNumber(): Promise<number> {
+  async getProvenL2BlockNumber(): Promise<BlockNumber> {
     const [latestBlockNumber, provenBlockNumber] = await Promise.all([
       this.getSynchedL2BlockNumber(),
       this.#lastProvenL2Block.getAsync(),
     ]);
-    return (provenBlockNumber ?? 0) > latestBlockNumber ? latestBlockNumber : (provenBlockNumber ?? 0);
+    return (provenBlockNumber ?? 0) > latestBlockNumber ? latestBlockNumber : BlockNumber(provenBlockNumber ?? 0);
   }
 
-  setProvenL2BlockNumber(blockNumber: number) {
+  setProvenL2BlockNumber(blockNumber: BlockNumber) {
     return this.#lastProvenL2Block.set(blockNumber);
   }
 
-  #computeBlockRange(start: number, limit: number): Required<Pick<Range<number>, 'start' | 'limit'>> {
+  #computeBlockRange(start: BlockNumber, limit: number): Required<Pick<Range<number>, 'start' | 'limit'>> {
     if (limit < 1) {
       throw new Error(`Invalid limit: ${limit}`);
     }

package/src/archiver/kv_archiver_store/contract_class_store.ts

@@ -1,4 +1,4 @@
-import { Fr } from '@aztec/foundation/fields';
+import { Fr } from '@aztec/foundation/curves/bn254';
 import { toArray } from '@aztec/foundation/iterable';
 import { BufferReader, numToUInt8, serializeToBuffer } from '@aztec/foundation/serialize';
 import type { AztecAsyncKVStore, AztecAsyncMap } from '@aztec/kv-store';

package/src/archiver/kv_archiver_store/contract_instance_store.ts

@@ -1,4 +1,4 @@
-import type { Fr } from '@aztec/foundation/fields';
+import type { Fr } from '@aztec/foundation/curves/bn254';
 import type { AztecAsyncKVStore, AztecAsyncMap } from '@aztec/kv-store';
 import type { AztecAddress } from '@aztec/stdlib/aztec-address';
 import {

package/src/archiver/kv_archiver_store/kv_archiver_store.ts

@@ -1,5 +1,6 @@
-import type { L1BlockId } from '@aztec/ethereum';
-import type { Fr } from '@aztec/foundation/fields';
+import type { L1BlockId } from '@aztec/ethereum/l1-types';
+import type { BlockNumber, CheckpointNumber } from '@aztec/foundation/branded-types';
+import type { Fr } from '@aztec/foundation/curves/bn254';
 import { toArray } from '@aztec/foundation/iterable';
 import { createLogger } from '@aztec/foundation/log';
 import type { AztecAsyncKVStore, CustomRange, StoreSize } from '@aztec/kv-store';
@@ -15,7 +16,7 @@ import type {
   UtilityFunctionWithMembershipProof,
 } from '@aztec/stdlib/contract';
 import type { GetContractClassLogsResponse, GetPublicLogsResponse } from '@aztec/stdlib/interfaces/client';
-import { type LogFilter, PrivateLog, type TxScopedL2Log } from '@aztec/stdlib/logs';
+import type { LogFilter, TxScopedL2Log } from '@aztec/stdlib/logs';
 import type { BlockHeader, TxHash, TxReceipt } from '@aztec/stdlib/tx';
 import type { UInt64 } from '@aztec/stdlib/types';
 
@@ -30,7 +31,7 @@ import { ContractInstanceStore } from './contract_instance_store.js';
 import { LogStore } from './log_store.js';
 import { MessageStore } from './message_store.js';
 
-export const ARCHIVER_DB_VERSION = 3;
+export const ARCHIVER_DB_VERSION = 4;
 export const MAX_FUNCTION_SIGNATURES = 1000;
 export const MAX_FUNCTION_NAME_LEN = 256;
 
@@ -65,7 +66,7 @@ export class KVArchiverDataStore implements ArchiverDataStore, ContractDataSourc
     return this.db.transactionAsync(callback);
   }
 
-  public getBlockNumber(): Promise<number> {
+  public getBlockNumber(): Promise<BlockNumber> {
     return this.getSynchedL2BlockNumber();
   }
 
@@ -124,7 +125,7 @@ export class KVArchiverDataStore implements ArchiverDataStore, ContractDataSourc
   async addContractClasses(
     data: ContractClassPublic[],
     bytecodeCommitments: Fr[],
-    blockNumber: number,
+    blockNumber: BlockNumber,
   ): Promise<boolean> {
     return (
       await Promise.all(
@@ -133,7 +134,7 @@ export class KVArchiverDataStore implements ArchiverDataStore, ContractDataSourc
     ).every(Boolean);
   }
 
-  async deleteContractClasses(data: ContractClassPublic[], blockNumber: number): Promise<boolean> {
+  async deleteContractClasses(data: ContractClassPublic[], blockNumber: BlockNumber): Promise<boolean> {
     return (await Promise.all(data.map(c => this.#contractClassStore.deleteContractClasses(c, blockNumber)))).every(
       Boolean,
     );
@@ -151,13 +152,13 @@ export class KVArchiverDataStore implements ArchiverDataStore, ContractDataSourc
     return this.#contractClassStore.addFunctions(contractClassId, privateFunctions, utilityFunctions);
   }
 
-  async addContractInstances(data: ContractInstanceWithAddress[], blockNumber: number): Promise<boolean> {
+  async addContractInstances(data: ContractInstanceWithAddress[], blockNumber: BlockNumber): Promise<boolean> {
     return (await Promise.all(data.map(c => this.#contractInstanceStore.addContractInstance(c, blockNumber)))).every(
       Boolean,
     );
   }
 
-  async deleteContractInstances(data: ContractInstanceWithAddress[], _blockNumber: number): Promise<boolean> {
+  async deleteContractInstances(data: ContractInstanceWithAddress[], _blockNumber: BlockNumber): Promise<boolean> {
     return (await Promise.all(data.map(c => this.#contractInstanceStore.deleteContractInstance(c)))).every(Boolean);
   }
 
@@ -196,11 +197,11 @@ export class KVArchiverDataStore implements ArchiverDataStore, ContractDataSourc
    * @param blocksToUnwind - The number of blocks we are to unwind
    * @returns True if the operation is successful
    */
-  unwindBlocks(from: number, blocksToUnwind: number): Promise<boolean> {
+  unwindBlocks(from: BlockNumber, blocksToUnwind: number): Promise<boolean> {
     return this.#blockStore.unwindBlocks(from, blocksToUnwind);
   }
 
-  getPublishedBlock(number: number): Promise<PublishedL2Block | undefined> {
+  getPublishedBlock(number: BlockNumber): Promise<PublishedL2Block | undefined> {
     return this.#blockStore.getBlock(number);
   }
 
@@ -219,7 +220,7 @@ export class KVArchiverDataStore implements ArchiverDataStore, ContractDataSourc
    * @param limit - The number of blocks to return.
    * @returns The requested L2 blocks
    */
-  getPublishedBlocks(start: number, limit: number): Promise<PublishedL2Block[]> {
+  getPublishedBlocks(start: BlockNumber, limit: number): Promise<PublishedL2Block[]> {
     return toArray(this.#blockStore.getBlocks(start, limit));
   }
 
@@ -230,7 +231,7 @@ export class KVArchiverDataStore implements ArchiverDataStore, ContractDataSourc
    * @param limit - The number of blocks to return.
    * @returns The requested L2 blocks
    */
-  getBlockHeaders(start: number, limit: number): Promise<BlockHeader[]> {
+  getBlockHeaders(start: BlockNumber, limit: number): Promise<BlockHeader[]> {
     return toArray(this.#blockStore.getBlockHeaders(start, limit));
   }
 
@@ -299,22 +300,12 @@ export class KVArchiverDataStore implements ArchiverDataStore, ContractDataSourc
   }
 
   /**
-   * Gets L1 to L2 message (to be) included in a given block.
-   * @param blockNumber - L2 block number to get messages for.
+   * Gets L1 to L2 message (to be) included in a given checkpoint.
+   * @param checkpointNumber - Checkpoint number to get messages for.
    * @returns The L1 to L2 messages/leaves of the messages subtree (throws if not found).
    */
-  getL1ToL2Messages(blockNumber: number): Promise<Fr[]> {
-    return this.#messageStore.getL1ToL2Messages(blockNumber);
-  }
-
-  /**
-   * Retrieves all private logs from up to `limit` blocks, starting from the block number `from`.
-   * @param from - The block number from which to begin retrieving logs.
-   * @param limit - The maximum number of blocks to retrieve logs from.
-   * @returns An array of private logs from the specified range of blocks.
-   */
-  getPrivateLogs(from: number, limit: number): Promise<PrivateLog[]> {
-    return this.#logStore.getPrivateLogs(from, limit);
+  getL1ToL2Messages(checkpointNumber: CheckpointNumber): Promise<Fr[]> {
+    return this.#messageStore.getL1ToL2Messages(checkpointNumber);
   }
 
   /**
@@ -362,15 +353,15 @@ export class KVArchiverDataStore implements ArchiverDataStore, ContractDataSourc
    * Gets the number of the latest L2 block processed.
    * @returns The number of the latest L2 block processed.
    */
-  getSynchedL2BlockNumber(): Promise<number> {
+  getSynchedL2BlockNumber(): Promise<BlockNumber> {
     return this.#blockStore.getSynchedL2BlockNumber();
   }
 
-  getProvenL2BlockNumber(): Promise<number> {
+  getProvenL2BlockNumber(): Promise<BlockNumber> {
     return this.#blockStore.getProvenL2BlockNumber();
   }
 
-  async setProvenL2BlockNumber(blockNumber: number) {
+  async setProvenL2BlockNumber(blockNumber: BlockNumber) {
     await this.#blockStore.setProvenL2BlockNumber(blockNumber);
   }
 
@@ -400,8 +391,8 @@ export class KVArchiverDataStore implements ArchiverDataStore, ContractDataSourc
     return this.db.estimateSize();
   }
 
-  public rollbackL1ToL2MessagesToL2Block(targetBlockNumber: number): Promise<void> {
-    return this.#messageStore.rollbackL1ToL2MessagesToL2Block(targetBlockNumber);
+  public rollbackL1ToL2MessagesToCheckpoint(targetCheckpointNumber: CheckpointNumber): Promise<void> {
+    return this.#messageStore.rollbackL1ToL2MessagesToCheckpoint(targetCheckpointNumber);
   }
 
   public iterateL1ToL2Messages(range: CustomRange<bigint> = {}): AsyncIterableIterator<InboxMessage> {

package/src/archiver/kv_archiver_store/log_store.ts

@@ -1,5 +1,6 @@
 import { INITIAL_L2_BLOCK_NUM, MAX_NOTE_HASHES_PER_TX } from '@aztec/constants';
-import type { Fr } from '@aztec/foundation/fields';
+import { BlockNumber } from '@aztec/foundation/branded-types';
+import type { Fr } from '@aztec/foundation/curves/bn254';
 import { createLogger } from '@aztec/foundation/log';
 import { BufferReader, numToUInt32BE } from '@aztec/foundation/serialize';
 import type { AztecAsyncKVStore, AztecAsyncMap } from '@aztec/kv-store';
@@ -11,7 +12,6 @@ import {
   ExtendedPublicLog,
   type LogFilter,
   LogId,
-  PrivateLog,
   PublicLog,
   TxScopedL2Log,
 } from '@aztec/stdlib/logs';
@@ -24,7 +24,6 @@ import type { BlockStore } from './block_store.js';
 export class LogStore {
   #logsByTag: AztecAsyncMap<string, Buffer[]>;
   #logTagsByBlock: AztecAsyncMap<number, string[]>;
-  #privateLogsByBlock: AztecAsyncMap<number, Buffer>;
   #publicLogsByBlock: AztecAsyncMap<number, Buffer>;
   #contractClassLogsByBlock: AztecAsyncMap<number, Buffer>;
   #logsMaxPageSize: number;
@@ -37,7 +36,6 @@ export class LogStore {
   ) {
     this.#logsByTag = db.openMap('archiver_tagged_logs_by_tag');
     this.#logTagsByBlock = db.openMap('archiver_log_tags_by_block');
-    this.#privateLogsByBlock = db.openMap('archiver_private_logs_by_block');
     this.#publicLogsByBlock = db.openMap('archiver_public_logs_by_block');
     this.#contractClassLogsByBlock = db.openMap('archiver_contract_class_logs_by_block');
 
@@ -111,12 +109,6 @@ export class LogStore {
         }
         await this.#logTagsByBlock.set(block.number, tagsInBlock);
 
-        const privateLogsInBlock = block.body.txEffects
-          .map(txEffect => txEffect.privateLogs)
-          .flat()
-          .map(log => log.toBuffer());
-        await this.#privateLogsByBlock.set(block.number, Buffer.concat(privateLogsInBlock));
-
         const publicLogsInBlock = block.body.txEffects
           .map((txEffect, txIndex) =>
             [
@@ -159,7 +151,6 @@ export class LogStore {
       await Promise.all(
         blocks.map(block =>
           Promise.all([
-            this.#privateLogsByBlock.delete(block.number),
             this.#publicLogsByBlock.delete(block.number),
             this.#logTagsByBlock.delete(block.number),
             this.#contractClassLogsByBlock.delete(block.number),
@@ -172,23 +163,6 @@ export class LogStore {
     });
   }
 
-  /**
-   * Retrieves all private logs from up to `limit` blocks, starting from the block number `start`.
-   * @param start - The block number from which to begin retrieving logs.
-   * @param limit - The maximum number of blocks to retrieve logs from.
-   * @returns An array of private logs from the specified range of blocks.
-   */
-  async getPrivateLogs(start: number, limit: number): Promise<PrivateLog[]> {
-    const logs = [];
-    for await (const buffer of this.#privateLogsByBlock.valuesAsync({ start, limit })) {
-      const reader = new BufferReader(buffer);
-      while (reader.remainingBytes() > 0) {
-        logs.push(reader.readObject(PrivateLog));
-      }
-    }
-    return logs;
-  }
-
   /**
    * Gets all logs that match any of the received tags (i.e. logs with their first field equal to a tag).
    * @param tags - The tags to filter the logs by.
@@ -389,9 +363,9 @@ export class LogStore {
       const log = txLogs[logIndex];
       if (!filter.contractAddress || log.contractAddress.equals(filter.contractAddress)) {
         if (log instanceof ContractClassLog) {
-          results.push(new ExtendedContractClassLog(new LogId(blockNumber, txIndex, logIndex), log));
+          results.push(new ExtendedContractClassLog(new LogId(BlockNumber(blockNumber), txIndex, logIndex), log));
         } else {
-          results.push(new ExtendedPublicLog(new LogId(blockNumber, txIndex, logIndex), log));
+          results.push(new ExtendedPublicLog(new LogId(BlockNumber(blockNumber), txIndex, logIndex), log));
         }
 
         if (results.length >= this.#logsMaxPageSize) {

package/src/archiver/kv_archiver_store/message_store.ts

@@ -1,6 +1,7 @@
-import type { L1BlockId } from '@aztec/ethereum';
+import type { L1BlockId } from '@aztec/ethereum/l1-types';
+import { CheckpointNumber } from '@aztec/foundation/branded-types';
 import { Buffer16, Buffer32 } from '@aztec/foundation/buffer';
-import { Fr } from '@aztec/foundation/fields';
+import { Fr } from '@aztec/foundation/curves/bn254';
 import { toArray } from '@aztec/foundation/iterable';
 import { createLogger } from '@aztec/foundation/log';
 import { BufferReader, serializeToBuffer } from '@aztec/foundation/serialize';
@@ -113,20 +114,20 @@ export class MessageStore {
           );
         }
 
-        // Check index corresponds to the L2 block number.
-        const [expectedStart, expectedEnd] = InboxLeaf.indexRangeFromL2Block(message.l2BlockNumber);
+        // Check index corresponds to the checkpoint number.
+        const [expectedStart, expectedEnd] = InboxLeaf.indexRangeForCheckpoint(message.checkpointNumber);
         if (message.index < expectedStart || message.index >= expectedEnd) {
           throw new MessageStoreError(
             `Invalid index ${message.index} for incoming L1 to L2 message ${message.leaf.toString()} ` +
-              `at block ${message.l2BlockNumber} (expected value in range [${expectedStart}, ${expectedEnd}))`,
+              `at checkpoint ${message.checkpointNumber} (expected value in range [${expectedStart}, ${expectedEnd}))`,
             message,
           );
         }
 
-        // Check there are no gaps in the indices within the same block.
+        // Check there are no gaps in the indices within the same checkpoint.
         if (
           lastMessage &&
-          message.l2BlockNumber === lastMessage.l2BlockNumber &&
+          message.checkpointNumber === lastMessage.checkpointNumber &&
           message.index !== lastMessage.index + 1n
         ) {
           throw new MessageStoreError(
@@ -138,12 +139,12 @@ export class MessageStore {
 
         // Check the first message in a block has the correct index.
         if (
-          (!lastMessage || message.l2BlockNumber > lastMessage.l2BlockNumber) &&
-          message.index !== InboxLeaf.smallestIndexFromL2Block(message.l2BlockNumber)
+          (!lastMessage || message.checkpointNumber > lastMessage.checkpointNumber) &&
+          message.index !== expectedStart
         ) {
           throw new MessageStoreError(
-            `Message ${message.leaf.toString()} for L2 block ${message.l2BlockNumber} has wrong index ` +
-              `${message.index} (expected ${InboxLeaf.smallestIndexFromL2Block(message.l2BlockNumber)})`,
+            `Message ${message.leaf.toString()} for checkpoint ${message.checkpointNumber} has wrong index ` +
+              `${message.index} (expected ${expectedStart})`,
             message,
           );
         }
@@ -184,10 +185,10 @@ export class MessageStore {
     return msg ? deserializeInboxMessage(msg) : undefined;
   }
 
-  public async getL1ToL2Messages(blockNumber: number): Promise<Fr[]> {
+  public async getL1ToL2Messages(checkpointNumber: CheckpointNumber): Promise<Fr[]> {
     const messages: Fr[] = [];
 
-    const [startIndex, endIndex] = InboxLeaf.indexRangeFromL2Block(blockNumber);
+    const [startIndex, endIndex] = InboxLeaf.indexRangeForCheckpoint(checkpointNumber);
     let lastIndex = startIndex - 1n;
 
     for await (const msgBuffer of this.#l1ToL2Messages.valuesAsync({
@@ -195,8 +196,10 @@ export class MessageStore {
       end: this.indexToKey(endIndex),
     })) {
       const msg = deserializeInboxMessage(msgBuffer);
-      if (msg.l2BlockNumber !== blockNumber) {
-        throw new Error(`L1 to L2 message with index ${msg.index} has invalid block number ${msg.l2BlockNumber}`);
+      if (msg.checkpointNumber !== checkpointNumber) {
+        throw new Error(
+          `L1 to L2 message with index ${msg.index} has invalid checkpoint number ${msg.checkpointNumber}`,
+        );
       } else if (msg.index !== lastIndex + 1n) {
         throw new Error(`Expected L1 to L2 message with index ${lastIndex + 1n} but got ${msg.index}`);
       }
@@ -232,9 +235,9 @@ export class MessageStore {
     });
   }
 
-  public rollbackL1ToL2MessagesToL2Block(targetBlockNumber: number): Promise<void> {
-    this.#log.debug(`Deleting L1 to L2 messages up to target L2 block ${targetBlockNumber}`);
-    const startIndex = InboxLeaf.smallestIndexFromL2Block(targetBlockNumber + 1);
+  public rollbackL1ToL2MessagesToCheckpoint(targetCheckpointNumber: CheckpointNumber): Promise<void> {
+    this.#log.debug(`Deleting L1 to L2 messages up to target checkpoint ${targetCheckpointNumber}`);
+    const startIndex = InboxLeaf.smallestIndexForCheckpoint(CheckpointNumber(targetCheckpointNumber + 1));
     return this.removeL1ToL2Messages(startIndex);
   }
 

package/src/archiver/l1/README.md

@@ -0,0 +1,98 @@
+# Archiver L1 Data Retrieval
+
+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:
+
+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 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 Validation and Decoding
+
+First attempt to decode the transaction as a multicall3 `aggregate3` call with validation:
+
+- 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
+
+This step handles the common case efficiently without requiring expensive trace or debug RPC calls.
+Any validation failure triggers fallback to the next step.
+
+### Direct Propose Call
+
+Second attempt to decode the transaction as a direct `propose` call to the rollup contract:
+
+- Check if transaction is to the rollup address
+- Decode as `propose` function call
+- Verify the function is indeed `propose`
+- 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.
+
+However, modifying the rollup contract is out of scope for this change. But we can implement this approach in `v2`.
+
+### 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.
+
+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.