@aztec/archiver 4.0.0-nightly.20250907 → 4.0.0-nightly.20260108

package/src/archiver/kv_archiver_store/log_store.ts

@@ -1,9 +1,11 @@
-import { INITIAL_L2_BLOCK_NUM, MAX_NOTE_HASHES_PER_TX } from '@aztec/constants';
-import type { Fr } from '@aztec/foundation/fields';
+import { INITIAL_L2_BLOCK_NUM } from '@aztec/constants';
+import { BlockNumber } from '@aztec/foundation/branded-types';
+import { 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';
-import type { L2Block } from '@aztec/stdlib/block';
+import type { AztecAddress } from '@aztec/stdlib/aztec-address';
+import { L2BlockHash, L2BlockNew } from '@aztec/stdlib/block';
 import type { GetContractClassLogsResponse, GetPublicLogsResponse } from '@aztec/stdlib/interfaces/client';
 import {
   ContractClassLog,
@@ -11,8 +13,9 @@ import {
   ExtendedPublicLog,
   type LogFilter,
   LogId,
-  PrivateLog,
   PublicLog,
+  type SiloedTag,
+  Tag,
   TxScopedL2Log,
 } from '@aztec/stdlib/logs';
 
@@ -22,9 +25,12 @@ import type { BlockStore } from './block_store.js';
  * A store for logs
  */
 export class LogStore {
-  #logsByTag: AztecAsyncMap<string, Buffer[]>;
-  #logTagsByBlock: AztecAsyncMap<number, string[]>;
-  #privateLogsByBlock: AztecAsyncMap<number, Buffer>;
+  // `tag` --> private logs
+  #privateLogsByTag: AztecAsyncMap<string, Buffer[]>;
+  // `{contractAddress}_${tag}` --> public logs
+  #publicLogsByContractAndTag: AztecAsyncMap<string, Buffer[]>;
+  #privateLogKeysByBlock: AztecAsyncMap<number, string[]>;
+  #publicLogKeysByBlock: AztecAsyncMap<number, string[]>;
   #publicLogsByBlock: AztecAsyncMap<number, Buffer>;
   #contractClassLogsByBlock: AztecAsyncMap<number, Buffer>;
   #logsMaxPageSize: number;
@@ -35,43 +41,107 @@ export class LogStore {
     private blockStore: BlockStore,
     logsMaxPageSize: number = 1000,
   ) {
-    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.#privateLogsByTag = db.openMap('archiver_private_tagged_logs_by_tag');
+    this.#publicLogsByContractAndTag = db.openMap('archiver_public_tagged_logs_by_tag');
+    this.#privateLogKeysByBlock = db.openMap('archiver_private_log_keys_by_block');
+    this.#publicLogKeysByBlock = db.openMap('archiver_public_log_keys_by_block');
     this.#publicLogsByBlock = db.openMap('archiver_public_logs_by_block');
     this.#contractClassLogsByBlock = db.openMap('archiver_contract_class_logs_by_block');
 
     this.#logsMaxPageSize = logsMaxPageSize;
   }
 
-  #extractTaggedLogs(block: L2Block) {
-    const taggedLogs = new Map<string, Buffer[]>();
-    const dataStartIndexForBlock =
-      block.header.state.partial.noteHashTree.nextAvailableLeafIndex -
-      block.body.txEffects.length * MAX_NOTE_HASHES_PER_TX;
-    block.body.txEffects.forEach((txEffect, txIndex) => {
+  /**
+   * Extracts tagged logs from a single block, grouping them into private and public maps.
+   *
+   * @param block - The L2 block to extract logs from.
+   * @returns An object containing the private and public tagged logs for the block.
+   */
+  #extractTaggedLogsFromBlock(block: L2BlockNew) {
+    // SiloedTag (as string) -> array of log buffers.
+    const privateTaggedLogs = new Map<string, Buffer[]>();
+    // "{contractAddress}_{tag}" (as string) -> array of log buffers.
+    const publicTaggedLogs = new Map<string, Buffer[]>();
+
+    block.body.txEffects.forEach(txEffect => {
       const txHash = txEffect.txHash;
-      const dataStartIndexForTx = dataStartIndexForBlock + txIndex * MAX_NOTE_HASHES_PER_TX;
 
-      txEffect.privateLogs.forEach((log, logIndex) => {
+      txEffect.privateLogs.forEach(log => {
+        // Private logs use SiloedTag (already siloed by kernel)
         const tag = log.fields[0];
         this.#log.debug(`Found private log with tag ${tag.toString()} in block ${block.number}`);
 
-        const currentLogs = taggedLogs.get(tag.toString()) ?? [];
-        currentLogs.push(new TxScopedL2Log(txHash, dataStartIndexForTx, logIndex, block.number, log).toBuffer());
-        taggedLogs.set(tag.toString(), currentLogs);
+        const currentLogs = privateTaggedLogs.get(tag.toString()) ?? [];
+        currentLogs.push(
+          new TxScopedL2Log(
+            txHash,
+            block.number,
+            block.timestamp,
+            log.getEmittedFields(),
+            txEffect.noteHashes,
+            txEffect.nullifiers[0],
+          ).toBuffer(),
+        );
+        privateTaggedLogs.set(tag.toString(), currentLogs);
       });
 
-      txEffect.publicLogs.forEach((log, logIndex) => {
+      txEffect.publicLogs.forEach(log => {
+        // Public logs use Tag directly (not siloed) and are stored with contract address
         const tag = log.fields[0];
-        this.#log.debug(`Found public log with tag ${tag.toString()} in block ${block.number}`);
-
-        const currentLogs = taggedLogs.get(tag.toString()) ?? [];
-        currentLogs.push(new TxScopedL2Log(txHash, dataStartIndexForTx, logIndex, block.number, log).toBuffer());
-        taggedLogs.set(tag.toString(), currentLogs);
+        const contractAddress = log.contractAddress;
+        const key = `${contractAddress.toString()}_${tag.toString()}`;
+        this.#log.debug(
+          `Found public log with tag ${tag.toString()} from contract ${contractAddress.toString()} in block ${block.number}`,
+        );
+
+        const currentLogs = publicTaggedLogs.get(key) ?? [];
+        currentLogs.push(
+          new TxScopedL2Log(
+            txHash,
+            block.number,
+            block.timestamp,
+            log.getEmittedFields(),
+            txEffect.noteHashes,
+            txEffect.nullifiers[0],
+          ).toBuffer(),
+        );
+        publicTaggedLogs.set(key, currentLogs);
       });
     });
-    return taggedLogs;
+
+    return { privateTaggedLogs, publicTaggedLogs };
+  }
+
+  /**
+   * Extracts and aggregates tagged logs from a list of blocks.
+   * @param blocks - The blocks to extract logs from.
+   * @returns A map from tag (as string) to an array of serialized private logs belonging to that tag, and a map from
+   * "{contractAddress}_{tag}" (as string) to an array of serialized public logs belonging to that key.
+   */
+  #extractTaggedLogs(blocks: L2BlockNew[]): {
+    privateTaggedLogs: Map<string, Buffer[]>;
+    publicTaggedLogs: Map<string, Buffer[]>;
+  } {
+    const taggedLogsInBlocks = blocks.map(block => this.#extractTaggedLogsFromBlock(block));
+
+    // Now we merge the maps from each block into a single map.
+    const privateTaggedLogs = taggedLogsInBlocks.reduce((acc, { privateTaggedLogs }) => {
+      for (const [tag, logs] of privateTaggedLogs.entries()) {
+        const currentLogs = acc.get(tag) ?? [];
+        acc.set(tag, currentLogs.concat(logs));
+      }
+      return acc;
+    }, new Map<string, Buffer[]>());
+
+    const publicTaggedLogs = taggedLogsInBlocks.reduce((acc, { publicTaggedLogs }) => {
+      for (const [key, logs] of publicTaggedLogs.entries()) {
+        const currentLogs = acc.get(key) ?? [];
+        acc.set(key, currentLogs.concat(logs));
+      }
+      return acc;
+    }, new Map<string, Buffer[]>());
+
+    return { privateTaggedLogs, publicTaggedLogs };
   }
 
   /**
@@ -79,43 +149,59 @@ export class LogStore {
    * @param blocks - The blocks for which to add the logs.
    * @returns True if the operation is successful.
    */
-  addLogs(blocks: L2Block[]): Promise<boolean> {
-    const taggedLogsToAdd = blocks
-      .map(block => this.#extractTaggedLogs(block))
-      .reduce((acc, val) => {
-        for (const [tag, logs] of val.entries()) {
-          const currentLogs = acc.get(tag) ?? [];
-          acc.set(tag, currentLogs.concat(logs));
-        }
-        return acc;
-      }, new Map());
-    const tagsToUpdate = Array.from(taggedLogsToAdd.keys());
+  addLogs(blocks: L2BlockNew[]): Promise<boolean> {
+    const { privateTaggedLogs, publicTaggedLogs } = this.#extractTaggedLogs(blocks);
+
+    const keysOfPrivateLogsToUpdate = Array.from(privateTaggedLogs.keys());
+    const keysOfPublicLogsToUpdate = Array.from(publicTaggedLogs.keys());
 
     return this.db.transactionAsync(async () => {
-      const currentTaggedLogs = await Promise.all(
-        tagsToUpdate.map(async tag => ({ tag, logBuffers: await this.#logsByTag.getAsync(tag) })),
+      const currentPrivateTaggedLogs = await Promise.all(
+        keysOfPrivateLogsToUpdate.map(async key => ({
+          tag: key,
+          logBuffers: await this.#privateLogsByTag.getAsync(key),
+        })),
       );
-      currentTaggedLogs.forEach(taggedLogBuffer => {
+      currentPrivateTaggedLogs.forEach(taggedLogBuffer => {
         if (taggedLogBuffer.logBuffers && taggedLogBuffer.logBuffers.length > 0) {
-          taggedLogsToAdd.set(
+          privateTaggedLogs.set(
             taggedLogBuffer.tag,
-            taggedLogBuffer.logBuffers!.concat(taggedLogsToAdd.get(taggedLogBuffer.tag)!),
+            taggedLogBuffer.logBuffers!.concat(privateTaggedLogs.get(taggedLogBuffer.tag)!),
           );
         }
       });
+
+      const currentPublicTaggedLogs = await Promise.all(
+        keysOfPublicLogsToUpdate.map(async key => ({
+          key,
+          logBuffers: await this.#publicLogsByContractAndTag.getAsync(key),
+        })),
+      );
+      currentPublicTaggedLogs.forEach(taggedLogBuffer => {
+        if (taggedLogBuffer.logBuffers && taggedLogBuffer.logBuffers.length > 0) {
+          publicTaggedLogs.set(
+            taggedLogBuffer.key,
+            taggedLogBuffer.logBuffers!.concat(publicTaggedLogs.get(taggedLogBuffer.key)!),
+          );
+        }
+      });
+
       for (const block of blocks) {
-        const tagsInBlock = [];
-        for (const [tag, logs] of taggedLogsToAdd.entries()) {
-          await this.#logsByTag.set(tag, logs);
-          tagsInBlock.push(tag);
+        const blockHash = await block.hash();
+
+        const privateTagsInBlock: string[] = [];
+        for (const [tag, logs] of privateTaggedLogs.entries()) {
+          await this.#privateLogsByTag.set(tag, logs);
+          privateTagsInBlock.push(tag);
         }
-        await this.#logTagsByBlock.set(block.number, tagsInBlock);
+        await this.#privateLogKeysByBlock.set(block.number, privateTagsInBlock);
 
-        const privateLogsInBlock = block.body.txEffects
-          .map(txEffect => txEffect.privateLogs)
-          .flat()
-          .map(log => log.toBuffer());
-        await this.#privateLogsByBlock.set(block.number, Buffer.concat(privateLogsInBlock));
+        const publicKeysInBlock: string[] = [];
+        for (const [key, logs] of publicTaggedLogs.entries()) {
+          await this.#publicLogsByContractAndTag.set(key, logs);
+          publicKeysInBlock.push(key);
+        }
+        await this.#publicLogKeysByBlock.set(block.number, publicKeysInBlock);
 
         const publicLogsInBlock = block.body.txEffects
           .map((txEffect, txIndex) =>
@@ -137,72 +223,82 @@ export class LogStore {
           )
           .flat();
 
-        await this.#publicLogsByBlock.set(block.number, Buffer.concat(publicLogsInBlock));
-        await this.#contractClassLogsByBlock.set(block.number, Buffer.concat(contractClassLogsInBlock));
+        await this.#publicLogsByBlock.set(block.number, this.#packWithBlockHash(blockHash, publicLogsInBlock));
+        await this.#contractClassLogsByBlock.set(
+          block.number,
+          this.#packWithBlockHash(blockHash, contractClassLogsInBlock),
+        );
       }
 
       return true;
     });
   }
 
-  deleteLogs(blocks: L2Block[]): Promise<boolean> {
+  #packWithBlockHash(blockHash: Fr, data: Buffer<ArrayBufferLike>[]): Buffer<ArrayBufferLike> {
+    return Buffer.concat([blockHash.toBuffer(), ...data]);
+  }
+
+  #unpackBlockHash(reader: BufferReader): L2BlockHash {
+    const blockHash = reader.remainingBytes() > 0 ? reader.readObject(Fr) : undefined;
+
+    if (!blockHash) {
+      throw new Error('Failed to read block hash from log entry buffer');
+    }
+
+    return L2BlockHash.fromField(blockHash);
+  }
+
+  deleteLogs(blocks: L2BlockNew[]): Promise<boolean> {
     return this.db.transactionAsync(async () => {
-      const tagsToDelete = (
-        await Promise.all(
-          blocks.map(async block => {
-            const tags = await this.#logTagsByBlock.getAsync(block.number);
-            return tags ?? [];
-          }),
-        )
-      ).flat();
+      await Promise.all(
+        blocks.map(async block => {
+          // Delete private logs
+          const privateKeys = (await this.#privateLogKeysByBlock.getAsync(block.number)) ?? [];
+          await Promise.all(privateKeys.map(tag => this.#privateLogsByTag.delete(tag)));
+
+          // Delete public logs
+          const publicKeys = (await this.#publicLogKeysByBlock.getAsync(block.number)) ?? [];
+          await Promise.all(publicKeys.map(key => this.#publicLogsByContractAndTag.delete(key)));
+        }),
+      );
 
       await Promise.all(
         blocks.map(block =>
           Promise.all([
-            this.#privateLogsByBlock.delete(block.number),
             this.#publicLogsByBlock.delete(block.number),
-            this.#logTagsByBlock.delete(block.number),
+            this.#privateLogKeysByBlock.delete(block.number),
+            this.#publicLogKeysByBlock.delete(block.number),
             this.#contractClassLogsByBlock.delete(block.number),
           ]),
         ),
       );
 
-      await Promise.all(tagsToDelete.map(tag => this.#logsByTag.delete(tag.toString())));
       return true;
     });
   }
 
   /**
-   * 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.
+   * Gets all private logs that match any of the `tags`. For each tag, an array of matching logs is returned. An empty
+   * array implies no logs match that tag.
    */
-  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;
+  async getPrivateLogsByTags(tags: SiloedTag[]): Promise<TxScopedL2Log[][]> {
+    const logs = await Promise.all(tags.map(tag => this.#privateLogsByTag.getAsync(tag.toString())));
+
+    return logs.map(logBuffers => logBuffers?.map(logBuffer => TxScopedL2Log.fromBuffer(logBuffer)) ?? []);
   }
 
   /**
-   * 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.
-   * @returns For each received tag, an array of matching logs is returned. An empty array implies no logs match
-   * that tag.
+   * Gets all public logs that match any of the `tags` from the specified contract. For each tag, an array of matching
+   * logs is returned. An empty array implies no logs match that tag.
    */
-  async getLogsByTags(tags: Fr[], limitPerTag?: number): Promise<TxScopedL2Log[][]> {
-    if (limitPerTag !== undefined && limitPerTag <= 0) {
-      throw new TypeError('limitPerTag needs to be greater than 0');
-    }
-    const logs = await Promise.all(tags.map(tag => this.#logsByTag.getAsync(tag.toString())));
-    return logs.map(
-      logBuffers => logBuffers?.slice(0, limitPerTag).map(logBuffer => TxScopedL2Log.fromBuffer(logBuffer)) ?? [],
+  async getPublicLogsByTagsFromContract(contractAddress: AztecAddress, tags: Tag[]): Promise<TxScopedL2Log[][]> {
+    const logs = await Promise.all(
+      tags.map(tag => {
+        const key = `${contractAddress.toString()}_${tag.value.toString()}`;
+        return this.#publicLogsByContractAndTag.getAsync(key);
+      }),
     );
+    return logs.map(logBuffers => logBuffers?.map(logBuffer => TxScopedL2Log.fromBuffer(logBuffer)) ?? []);
   }
 
   /**
@@ -233,6 +329,9 @@ export class LogStore {
     const buffer = (await this.#publicLogsByBlock.getAsync(blockNumber)) ?? Buffer.alloc(0);
     const publicLogsInBlock: [PublicLog[]] = [[]];
     const reader = new BufferReader(buffer);
+
+    const blockHash = this.#unpackBlockHash(reader);
+
     while (reader.remainingBytes() > 0) {
       const indexOfTx = reader.readNumber();
       const numLogsInTx = reader.readNumber();
@@ -245,7 +344,7 @@ export class LogStore {
     const txLogs = publicLogsInBlock[txIndex];
 
     const logs: ExtendedPublicLog[] = [];
-    const maxLogsHit = this.#accumulateLogs(logs, blockNumber, txIndex, txLogs, filter);
+    const maxLogsHit = this.#accumulateLogs(logs, blockNumber, blockHash, txIndex, txLogs, filter);
 
     return { logs, maxLogsHit };
   }
@@ -268,6 +367,9 @@ export class LogStore {
     loopOverBlocks: for await (const [blockNumber, logBuffer] of this.#publicLogsByBlock.entriesAsync({ start, end })) {
       const publicLogsInBlock: [PublicLog[]] = [[]];
       const reader = new BufferReader(logBuffer);
+
+      const blockHash = this.#unpackBlockHash(reader);
+
       while (reader.remainingBytes() > 0) {
         const indexOfTx = reader.readNumber();
         const numLogsInTx = reader.readNumber();
@@ -278,7 +380,7 @@ export class LogStore {
       }
       for (let txIndex = filter.afterLog?.txIndex ?? 0; txIndex < publicLogsInBlock.length; txIndex++) {
         const txLogs = publicLogsInBlock[txIndex];
-        maxLogsHit = this.#accumulateLogs(logs, blockNumber, txIndex, txLogs, filter);
+        maxLogsHit = this.#accumulateLogs(logs, blockNumber, blockHash, txIndex, txLogs, filter);
         if (maxLogsHit) {
           this.#log.debug(`Max logs hit at block ${blockNumber}`);
           break loopOverBlocks;
@@ -317,6 +419,8 @@ export class LogStore {
     const contractClassLogsInBlock: [ContractClassLog[]] = [[]];
 
     const reader = new BufferReader(contractClassLogsBuffer);
+    const blockHash = this.#unpackBlockHash(reader);
+
     while (reader.remainingBytes() > 0) {
       const indexOfTx = reader.readNumber();
       const numLogsInTx = reader.readNumber();
@@ -329,7 +433,7 @@ export class LogStore {
     const txLogs = contractClassLogsInBlock[txIndex];
 
     const logs: ExtendedContractClassLog[] = [];
-    const maxLogsHit = this.#accumulateLogs(logs, blockNumber, txIndex, txLogs, filter);
+    const maxLogsHit = this.#accumulateLogs(logs, blockNumber, blockHash, txIndex, txLogs, filter);
 
     return { logs, maxLogsHit };
   }
@@ -355,6 +459,7 @@ export class LogStore {
     })) {
       const contractClassLogsInBlock: [ContractClassLog[]] = [[]];
       const reader = new BufferReader(logBuffer);
+      const blockHash = this.#unpackBlockHash(reader);
       while (reader.remainingBytes() > 0) {
         const indexOfTx = reader.readNumber();
         const numLogsInTx = reader.readNumber();
@@ -365,7 +470,7 @@ export class LogStore {
       }
       for (let txIndex = filter.afterLog?.txIndex ?? 0; txIndex < contractClassLogsInBlock.length; txIndex++) {
         const txLogs = contractClassLogsInBlock[txIndex];
-        maxLogsHit = this.#accumulateLogs(logs, blockNumber, txIndex, txLogs, filter);
+        maxLogsHit = this.#accumulateLogs(logs, blockNumber, blockHash, txIndex, txLogs, filter);
         if (maxLogsHit) {
           this.#log.debug(`Max logs hit at block ${blockNumber}`);
           break loopOverBlocks;
@@ -379,9 +484,10 @@ export class LogStore {
   #accumulateLogs(
     results: (ExtendedContractClassLog | ExtendedPublicLog)[],
     blockNumber: number,
+    blockHash: L2BlockHash,
     txIndex: number,
     txLogs: (ContractClassLog | PublicLog)[],
-    filter: LogFilter,
+    filter: LogFilter = {},
   ): boolean {
     let maxLogsHit = false;
     let logIndex = typeof filter.afterLog?.logIndex === 'number' ? filter.afterLog.logIndex + 1 : 0;
@@ -389,9 +495,13 @@ 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), blockHash, txIndex, logIndex), log),
+          );
+        } else if (log instanceof PublicLog) {
+          results.push(new ExtendedPublicLog(new LogId(BlockNumber(blockNumber), blockHash, txIndex, logIndex), log));
         } else {
-          results.push(new ExtendedPublicLog(new LogId(blockNumber, txIndex, logIndex), log));
+          throw new Error('Unknown log type');
         }
 
         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.