@aztec/archiver 0.23.0 → 0.26.1

package/src/archiver/kv_archiver_store/kv_archiver_store.ts

@@ -0,0 +1,300 @@
+import {
+  Body,
+  ContractData,
+  ExtendedContractData,
+  GetUnencryptedLogsResponse,
+  L1ToL2Message,
+  L2Block,
+  L2BlockL2Logs,
+  LogFilter,
+  LogType,
+  TxEffect,
+  TxHash,
+  TxReceipt,
+} from '@aztec/circuit-types';
+import { Fr } from '@aztec/circuits.js';
+import { AztecAddress } from '@aztec/foundation/aztec-address';
+import { createDebugLogger } from '@aztec/foundation/log';
+import { AztecKVStore } from '@aztec/kv-store';
+import { ContractClassPublic, ContractInstanceWithAddress } from '@aztec/types/contracts';
+
+import { ArchiverDataStore, ArchiverL1SynchPoint } from '../archiver_store.js';
+import { BlockBodyStore } from './block_body_store.js';
+import { BlockStore } from './block_store.js';
+import { ContractClassStore } from './contract_class_store.js';
+import { ContractInstanceStore } from './contract_instance_store.js';
+import { ContractStore } from './contract_store.js';
+import { LogStore } from './log_store.js';
+import { MessageStore } from './message_store.js';
+
+/**
+ * LMDB implementation of the ArchiverDataStore interface.
+ */
+export class KVArchiverDataStore implements ArchiverDataStore {
+  #blockStore: BlockStore;
+  #blockBodyStore: BlockBodyStore;
+  #logStore: LogStore;
+  #contractStore: ContractStore;
+  #messageStore: MessageStore;
+  #contractClassStore: ContractClassStore;
+  #contractInstanceStore: ContractInstanceStore;
+
+  #log = createDebugLogger('aztec:archiver:data-store');
+
+  constructor(db: AztecKVStore, logsMaxPageSize: number = 1000) {
+    this.#blockBodyStore = new BlockBodyStore(db);
+    this.#blockStore = new BlockStore(db, this.#blockBodyStore);
+    this.#logStore = new LogStore(db, this.#blockStore, logsMaxPageSize);
+    this.#contractStore = new ContractStore(db, this.#blockStore);
+    this.#messageStore = new MessageStore(db);
+    this.#contractClassStore = new ContractClassStore(db);
+    this.#contractInstanceStore = new ContractInstanceStore(db);
+  }
+
+  getContractClass(id: Fr): Promise<ContractClassPublic | undefined> {
+    return Promise.resolve(this.#contractClassStore.getContractClass(id));
+  }
+
+  getContractClassIds(): Promise<Fr[]> {
+    return Promise.resolve(this.#contractClassStore.getContractClassIds());
+  }
+
+  getContractInstance(address: AztecAddress): Promise<ContractInstanceWithAddress | undefined> {
+    return Promise.resolve(this.#contractInstanceStore.getContractInstance(address));
+  }
+
+  async addContractClasses(data: ContractClassPublic[], _blockNumber: number): Promise<boolean> {
+    return (await Promise.all(data.map(c => this.#contractClassStore.addContractClass(c)))).every(Boolean);
+  }
+
+  async addContractInstances(data: ContractInstanceWithAddress[], _blockNumber: number): Promise<boolean> {
+    return (await Promise.all(data.map(c => this.#contractInstanceStore.addContractInstance(c)))).every(Boolean);
+  }
+
+  /**
+   * Append new block bodies to the store's list.
+   * @param blockBodies - The L2 block bodies to be added to the store.
+   * @returns True if the operation is successful.
+   */
+  addBlockBodies(blockBodies: Body[]): Promise<boolean> {
+    return this.#blockBodyStore.addBlockBodies(blockBodies);
+  }
+
+  /**
+   * Gets block bodies that have the same txHashes as we supply.
+   *
+   * @param txsHashes - A list of txsHashes (body hashes).
+   * @returns The requested L2 block bodies
+   */
+  getBlockBodies(txsHashes: Buffer[]): Promise<Body[]> {
+    return this.#blockBodyStore.getBlockBodies(txsHashes);
+  }
+
+  /**
+   * Append new blocks to the store's list.
+   * @param blocks - The L2 blocks to be added to the store.
+   * @returns True if the operation is successful.
+   */
+  addBlocks(blocks: L2Block[]): Promise<boolean> {
+    return this.#blockStore.addBlocks(blocks);
+  }
+
+  /**
+   * Gets up to `limit` amount of L2 blocks starting from `from`.
+   *
+   * @param start - Number of the first block to return (inclusive).
+   * @param limit - The number of blocks to return.
+   * @returns The requested L2 blocks
+   */
+  getBlocks(start: number, limit: number): Promise<L2Block[]> {
+    try {
+      return Promise.resolve(Array.from(this.#blockStore.getBlocks(start, limit)));
+    } catch (err) {
+      // this function is sync so if any errors are thrown we need to make sure they're passed on as rejected Promises
+      return Promise.reject(err);
+    }
+  }
+
+  /**
+   * Gets a tx effect.
+   * @param txHash - The txHash of the tx corresponding to the tx effect.
+   * @returns The requested tx effect (or undefined if not found).
+   */
+  getTxEffect(txHash: TxHash): Promise<TxEffect | undefined> {
+    return Promise.resolve(this.#blockStore.getTxEffect(txHash));
+  }
+
+  /**
+   * Gets a receipt of a settled tx.
+   * @param txHash - The hash of a tx we try to get the receipt for.
+   * @returns The requested tx receipt (or undefined if not found).
+   */
+  getSettledTxReceipt(txHash: TxHash): Promise<TxReceipt | undefined> {
+    return Promise.resolve(this.#blockStore.getSettledTxReceipt(txHash));
+  }
+
+  /**
+   * Append new logs to the store's list.
+   * @param encryptedLogs - The logs to be added to the store.
+   * @param unencryptedLogs - The type of the logs to be added to the store.
+   * @param blockNumber - The block for which to add the logs.
+   * @returns True if the operation is successful.
+   */
+  addLogs(
+    encryptedLogs: L2BlockL2Logs | undefined,
+    unencryptedLogs: L2BlockL2Logs | undefined,
+    blockNumber: number,
+  ): Promise<boolean> {
+    return this.#logStore.addLogs(encryptedLogs, unencryptedLogs, blockNumber);
+  }
+
+  /**
+   * Append new pending L1 to L2 messages to the store.
+   * @param messages - The L1 to L2 messages to be added to the store.
+   * @param l1BlockNumber - The L1 block number for which to add the messages.
+   * @returns True if the operation is successful.
+   */
+  addPendingL1ToL2Messages(messages: L1ToL2Message[], l1BlockNumber: bigint): Promise<boolean> {
+    return Promise.resolve(this.#messageStore.addPendingMessages(messages, l1BlockNumber));
+  }
+
+  /**
+   * Remove pending L1 to L2 messages from the store (if they were cancelled).
+   * @param messages - The entry keys to be removed from the store.
+   * @param l1BlockNumber - The L1 block number for which to remove the messages.
+   * @returns True if the operation is successful.
+   */
+  cancelPendingL1ToL2EntryKeys(messages: Fr[], l1BlockNumber: bigint): Promise<boolean> {
+    return Promise.resolve(this.#messageStore.cancelPendingMessages(messages, l1BlockNumber));
+  }
+
+  /**
+   * Messages that have been published in an L2 block are confirmed.
+   * Add them to the confirmed store, also remove them from the pending store.
+   * @param entryKeys - The entry keys to be removed from the store.
+   * @param blockNumber - The block for which to add the messages.
+   * @returns True if the operation is successful.
+   */
+  confirmL1ToL2EntryKeys(entryKeys: Fr[]): Promise<boolean> {
+    return this.#messageStore.confirmPendingMessages(entryKeys);
+  }
+
+  /**
+   * Gets up to `limit` amount of pending L1 to L2 messages, sorted by fee
+   * @param limit - The number of messages to return (by default NUMBER_OF_L1_L2_MESSAGES_PER_ROLLUP).
+   * @returns The requested L1 to L2 entry keys.
+   */
+  getPendingL1ToL2EntryKeys(limit: number): Promise<Fr[]> {
+    return Promise.resolve(this.#messageStore.getPendingEntryKeysByFee(limit));
+  }
+
+  /**
+   * Gets the confirmed L1 to L2 message corresponding to the given entry key.
+   * @param entryKey - The entry key to look up.
+   * @returns The requested L1 to L2 message or throws if not found.
+   */
+  getConfirmedL1ToL2Message(entryKey: Fr): Promise<L1ToL2Message> {
+    try {
+      return Promise.resolve(this.#messageStore.getConfirmedMessage(entryKey));
+    } catch (err) {
+      return Promise.reject(err);
+    }
+  }
+
+  /**
+   * Gets up to `limit` amount of logs starting from `from`.
+   * @param start - Number of the L2 block to which corresponds the first logs to be returned.
+   * @param limit - The number of logs to return.
+   * @param logType - Specifies whether to return encrypted or unencrypted logs.
+   * @returns The requested logs.
+   */
+  getLogs(start: number, limit: number, logType: LogType): Promise<L2BlockL2Logs[]> {
+    try {
+      return Promise.resolve(Array.from(this.#logStore.getLogs(start, limit, logType)));
+    } catch (err) {
+      return Promise.reject(err);
+    }
+  }
+
+  /**
+   * Gets unencrypted logs based on the provided filter.
+   * @param filter - The filter to apply to the logs.
+   * @returns The requested logs.
+   */
+  getUnencryptedLogs(filter: LogFilter): Promise<GetUnencryptedLogsResponse> {
+    try {
+      return Promise.resolve(this.#logStore.getUnencryptedLogs(filter));
+    } catch (err) {
+      return Promise.reject(err);
+    }
+  }
+
+  /**
+   * Add new extended contract data from an L2 block to the store's list.
+   * @param data - List of contracts' data to be added.
+   * @param blockNum - Number of the L2 block the contract data was deployed in.
+   * @returns True if the operation is successful.
+   */
+  addExtendedContractData(data: ExtendedContractData[], blockNum: number): Promise<boolean> {
+    return this.#contractStore.addExtendedContractData(data, blockNum);
+  }
+
+  /**
+   * Get the extended contract data for this contract.
+   * @param contractAddress - The contract data address.
+   * @returns The extended contract data or undefined if not found.
+   */
+  getExtendedContractData(contractAddress: AztecAddress): Promise<ExtendedContractData | undefined> {
+    return Promise.resolve(this.#contractStore.getExtendedContractData(contractAddress));
+  }
+
+  /**
+   * Lookup all extended contract data in an L2 block.
+   * @param blockNumber - The block number to get all contract data from.
+   * @returns All extended contract data in the block (if found).
+   */
+  getExtendedContractDataInBlock(blockNumber: number): Promise<ExtendedContractData[]> {
+    return Promise.resolve(Array.from(this.#contractStore.getExtendedContractDataInBlock(blockNumber)));
+  }
+
+  /**
+   * Get basic info for an L2 contract.
+   * Contains contract address & the ethereum portal address.
+   * @param contractAddress - The contract data address.
+   * @returns ContractData with the portal address (if we didn't throw an error).
+   */
+  getContractData(contractAddress: AztecAddress): Promise<ContractData | undefined> {
+    return Promise.resolve(this.#contractStore.getContractData(contractAddress));
+  }
+
+  /**
+   * Get basic info for an all L2 contracts deployed in a block.
+   * Contains contract address & the ethereum portal address.
+   * @param blockNumber - Number of the L2 block where contracts were deployed.
+   * @returns ContractData with the portal address (if we didn't throw an error).
+   */
+  getContractDataInBlock(blockNumber: number): Promise<ContractData[]> {
+    return Promise.resolve(Array.from(this.#contractStore.getContractDataInBlock(blockNumber)));
+  }
+
+  /**
+   * Gets the number of the latest L2 block processed.
+   * @returns The number of the latest L2 block processed.
+   */
+  getBlockNumber(): Promise<number> {
+    return Promise.resolve(this.#blockStore.getBlockNumber());
+  }
+
+  /**
+   * Gets the last L1 block number processed by the archiver
+   */
+  getL1BlockNumber(): Promise<ArchiverL1SynchPoint> {
+    const addedBlock = this.#blockStore.getL1BlockNumber();
+    const { addedMessages, cancelledMessages } = this.#messageStore.getL1BlockNumber();
+    return Promise.resolve({
+      addedBlock,
+      addedMessages,
+      cancelledMessages,
+    });
+  }
+}

package/src/archiver/kv_archiver_store/log_store.ts

@@ -0,0 +1,174 @@
+import {
+  ExtendedUnencryptedL2Log,
+  GetUnencryptedLogsResponse,
+  L2BlockL2Logs,
+  LogFilter,
+  LogId,
+  LogType,
+  UnencryptedL2Log,
+} from '@aztec/circuit-types';
+import { INITIAL_L2_BLOCK_NUM } from '@aztec/circuits.js/constants';
+import { createDebugLogger } from '@aztec/foundation/log';
+import { AztecKVStore, AztecMap } from '@aztec/kv-store';
+
+import { BlockStore } from './block_store.js';
+
+/**
+ * A store for logs
+ */
+export class LogStore {
+  #encryptedLogs: AztecMap<number, Buffer>;
+  #unencryptedLogs: AztecMap<number, Buffer>;
+  #logsMaxPageSize: number;
+  #log = createDebugLogger('aztec:archiver:log_store');
+
+  constructor(private db: AztecKVStore, private blockStore: BlockStore, logsMaxPageSize: number = 1000) {
+    this.#encryptedLogs = db.openMap('archiver_encrypted_logs');
+    this.#unencryptedLogs = db.openMap('archiver_unencrypted_logs');
+
+    this.#logsMaxPageSize = logsMaxPageSize;
+  }
+
+  /**
+   * Append new logs to the store's list.
+   * @param encryptedLogs - The logs to be added to the store.
+   * @param unencryptedLogs - The type of the logs to be added to the store.
+   * @param blockNumber - The block for which to add the logs.
+   * @returns True if the operation is successful.
+   */
+  addLogs(
+    encryptedLogs: L2BlockL2Logs | undefined,
+    unencryptedLogs: L2BlockL2Logs | undefined,
+    blockNumber: number,
+  ): Promise<boolean> {
+    return this.db.transaction(() => {
+      if (encryptedLogs) {
+        void this.#encryptedLogs.set(blockNumber, encryptedLogs.toBuffer());
+      }
+
+      if (unencryptedLogs) {
+        void this.#unencryptedLogs.set(blockNumber, unencryptedLogs.toBuffer());
+      }
+
+      return true;
+    });
+  }
+
+  /**
+   * Gets up to `limit` amount of logs starting from `from`.
+   * @param start - Number of the L2 block to which corresponds the first logs to be returned.
+   * @param limit - The number of logs to return.
+   * @param logType - Specifies whether to return encrypted or unencrypted logs.
+   * @returns The requested logs.
+   */
+  *getLogs(start: number, limit: number, logType: LogType): IterableIterator<L2BlockL2Logs> {
+    const logMap = logType === LogType.ENCRYPTED ? this.#encryptedLogs : this.#unencryptedLogs;
+    for (const buffer of logMap.values({ start, limit })) {
+      yield L2BlockL2Logs.fromBuffer(buffer);
+    }
+  }
+
+  /**
+   * Gets unencrypted logs based on the provided filter.
+   * @param filter - The filter to apply to the logs.
+   * @returns The requested logs.
+   */
+  getUnencryptedLogs(filter: LogFilter): GetUnencryptedLogsResponse {
+    if (filter.afterLog) {
+      return this.#filterUnencryptedLogsBetweenBlocks(filter);
+    } else if (filter.txHash) {
+      return this.#filterUnencryptedLogsOfTx(filter);
+    } else {
+      return this.#filterUnencryptedLogsBetweenBlocks(filter);
+    }
+  }
+
+  #filterUnencryptedLogsOfTx(filter: LogFilter): GetUnencryptedLogsResponse {
+    if (!filter.txHash) {
+      throw new Error('Missing txHash');
+    }
+
+    const [blockNumber, txIndex] = this.blockStore.getTxLocation(filter.txHash) ?? [];
+    if (typeof blockNumber !== 'number' || typeof txIndex !== 'number') {
+      return { logs: [], maxLogsHit: false };
+    }
+
+    const unencryptedLogsInBlock = this.#getBlockLogs(blockNumber, LogType.UNENCRYPTED);
+    const txLogs = unencryptedLogsInBlock.txLogs[txIndex].unrollLogs().map(log => UnencryptedL2Log.fromBuffer(log));
+
+    const logs: ExtendedUnencryptedL2Log[] = [];
+    const maxLogsHit = this.#accumulateLogs(logs, blockNumber, txIndex, txLogs, filter);
+
+    return { logs, maxLogsHit };
+  }
+
+  #filterUnencryptedLogsBetweenBlocks(filter: LogFilter): GetUnencryptedLogsResponse {
+    const start =
+      filter.afterLog?.blockNumber ?? Math.max(filter.fromBlock ?? INITIAL_L2_BLOCK_NUM, INITIAL_L2_BLOCK_NUM);
+    const end = filter.toBlock;
+
+    if (typeof end === 'number' && end < start) {
+      return {
+        logs: [],
+        maxLogsHit: true,
+      };
+    }
+
+    const logs: ExtendedUnencryptedL2Log[] = [];
+
+    let maxLogsHit = false;
+    loopOverBlocks: for (const [blockNumber, logBuffer] of this.#unencryptedLogs.entries({ start, end })) {
+      const unencryptedLogsInBlock = L2BlockL2Logs.fromBuffer(logBuffer);
+      for (let txIndex = filter.afterLog?.txIndex ?? 0; txIndex < unencryptedLogsInBlock.txLogs.length; txIndex++) {
+        const txLogs = unencryptedLogsInBlock.txLogs[txIndex].unrollLogs().map(log => UnencryptedL2Log.fromBuffer(log));
+        maxLogsHit = this.#accumulateLogs(logs, blockNumber, txIndex, txLogs, filter);
+        if (maxLogsHit) {
+          this.#log(`Max logs hit at block ${blockNumber}`);
+          break loopOverBlocks;
+        }
+      }
+    }
+
+    return { logs, maxLogsHit };
+  }
+
+  #accumulateLogs(
+    results: ExtendedUnencryptedL2Log[],
+    blockNumber: number,
+    txIndex: number,
+    txLogs: UnencryptedL2Log[],
+    filter: LogFilter,
+  ): boolean {
+    let maxLogsHit = false;
+    let logIndex = typeof filter.afterLog?.logIndex === 'number' ? filter.afterLog.logIndex + 1 : 0;
+    for (; logIndex < txLogs.length; logIndex++) {
+      const log = txLogs[logIndex];
+      if (filter.contractAddress && !log.contractAddress.equals(filter.contractAddress)) {
+        continue;
+      }
+
+      if (filter.selector && !log.selector.equals(filter.selector)) {
+        continue;
+      }
+
+      results.push(new ExtendedUnencryptedL2Log(new LogId(blockNumber, txIndex, logIndex), log));
+      if (results.length >= this.#logsMaxPageSize) {
+        maxLogsHit = true;
+        break;
+      }
+    }
+
+    return maxLogsHit;
+  }
+
+  #getBlockLogs(blockNumber: number, logType: LogType): L2BlockL2Logs {
+    const logMap = logType === LogType.ENCRYPTED ? this.#encryptedLogs : this.#unencryptedLogs;
+    const buffer = logMap.get(blockNumber);
+
+    if (!buffer) {
+      return new L2BlockL2Logs([]);
+    }
+
+    return L2BlockL2Logs.fromBuffer(buffer);
+  }
+}

package/src/archiver/kv_archiver_store/message_store.ts

@@ -0,0 +1,174 @@
+import { L1ToL2Message } from '@aztec/circuit-types';
+import { Fr } from '@aztec/circuits.js';
+import { createDebugLogger } from '@aztec/foundation/log';
+import { AztecCounter, AztecKVStore, AztecMap, AztecSingleton } from '@aztec/kv-store';
+
+/**
+ * A message stored in the database
+ */
+type Message = {
+  /** The L1ToL2Message */
+  message: Buffer;
+  /** The message's fee */
+  fee: number;
+  /** Has it _ever_ been confirmed? */
+  confirmed: boolean;
+};
+
+/**
+ * LMDB implementation of the ArchiverDataStore interface.
+ */
+export class MessageStore {
+  #messages: AztecMap<string, Message>;
+  #pendingMessagesByFee: AztecCounter<[number, string]>;
+  #lastL1BlockAddingMessages: AztecSingleton<bigint>;
+  #lastL1BlockCancellingMessages: AztecSingleton<bigint>;
+
+  #log = createDebugLogger('aztec:archiver:message_store');
+
+  constructor(private db: AztecKVStore) {
+    this.#messages = db.openMap('archiver_l1_to_l2_messages');
+    this.#pendingMessagesByFee = db.openCounter('archiver_messages_by_fee');
+    this.#lastL1BlockAddingMessages = db.openSingleton('archiver_last_l1_block_adding_messages');
+    this.#lastL1BlockCancellingMessages = db.openSingleton('archiver_last_l1_block_cancelling_messages');
+  }
+
+  /**
+   * Gets the last L1 block number that emitted new messages and the block that cancelled messages.
+   * @returns The last L1 block number processed
+   */
+  getL1BlockNumber() {
+    return {
+      addedMessages: this.#lastL1BlockAddingMessages.get() ?? 0n,
+      cancelledMessages: this.#lastL1BlockCancellingMessages.get() ?? 0n,
+    };
+  }
+
+  /**
+   * Append new pending L1 to L2 messages to the store.
+   * @param messages - The L1 to L2 messages to be added to the store.
+   * @param l1BlockNumber - The L1 block number for which to add the messages.
+   * @returns True if the operation is successful.
+   */
+  addPendingMessages(messages: L1ToL2Message[], l1BlockNumber: bigint): Promise<boolean> {
+    return this.db.transaction(() => {
+      const lastL1BlockNumber = this.#lastL1BlockAddingMessages.get() ?? 0n;
+      if (lastL1BlockNumber >= l1BlockNumber) {
+        return false;
+      }
+
+      void this.#lastL1BlockAddingMessages.set(l1BlockNumber);
+
+      for (const message of messages) {
+        const entryKey = message.entryKey?.toString();
+        if (!entryKey) {
+          throw new Error('Message does not have an entry key');
+        }
+
+        void this.#messages.setIfNotExists(entryKey, {
+          message: message.toBuffer(),
+          fee: message.fee,
+          confirmed: false,
+        });
+
+        void this.#pendingMessagesByFee.update([message.fee, entryKey], 1);
+      }
+
+      return true;
+    });
+  }
+
+  /**
+   * Remove pending L1 to L2 messages from the store (if they were cancelled).
+   * @param entryKeys - The entry keys to be removed from the store.
+   * @param l1BlockNumber - The L1 block number for which to remove the messages.
+   * @returns True if the operation is successful.
+   */
+  cancelPendingMessages(entryKeys: Fr[], l1BlockNumber: bigint): Promise<boolean> {
+    return this.db.transaction(() => {
+      const lastL1BlockNumber = this.#lastL1BlockCancellingMessages.get() ?? 0n;
+      if (lastL1BlockNumber >= l1BlockNumber) {
+        return false;
+      }
+
+      void this.#lastL1BlockCancellingMessages.set(l1BlockNumber);
+
+      for (const entryKey of entryKeys) {
+        const messageCtx = this.#messages.get(entryKey.toString());
+        if (!messageCtx) {
+          throw new Error(`Message ${entryKey.toString()} not found`);
+        }
+
+        void this.#pendingMessagesByFee.update([messageCtx.fee, entryKey.toString()], -1);
+      }
+
+      return true;
+    });
+  }
+
+  /**
+   * Messages that have been published in an L2 block are confirmed.
+   * Add them to the confirmed store, also remove them from the pending store.
+   * @param entryKeys - The entry keys to be removed from the store.
+   * @returns True if the operation is successful.
+   */
+  confirmPendingMessages(entryKeys: Fr[]): Promise<boolean> {
+    return this.db.transaction(() => {
+      for (const entryKey of entryKeys) {
+        if (entryKey.equals(Fr.ZERO)) {
+          continue;
+        }
+
+        const messageCtx = this.#messages.get(entryKey.toString());
+        if (!messageCtx) {
+          throw new Error(`Message ${entryKey.toString()} not found`);
+        }
+        messageCtx.confirmed = true;
+
+        void this.#messages.set(entryKey.toString(), messageCtx);
+        void this.#pendingMessagesByFee.update([messageCtx.fee, entryKey.toString()], -1);
+      }
+
+      return true;
+    });
+  }
+
+  /**
+   * Gets the confirmed L1 to L2 message corresponding to the given entry key.
+   * @param entryKey - The entry key to look up.
+   * @returns The requested L1 to L2 message or throws if not found.
+   */
+  getConfirmedMessage(entryKey: Fr): L1ToL2Message {
+    const messageCtx = this.#messages.get(entryKey.toString());
+    if (!messageCtx) {
+      throw new Error(`Message ${entryKey.toString()} not found`);
+    }
+
+    if (!messageCtx.confirmed) {
+      throw new Error(`Message ${entryKey.toString()} not confirmed`);
+    }
+
+    return L1ToL2Message.fromBuffer(messageCtx.message);
+  }
+
+  /**
+   * Gets up to `limit` amount of pending L1 to L2 messages, sorted by fee
+   * @param limit - The number of messages to return (by default NUMBER_OF_L1_L2_MESSAGES_PER_ROLLUP).
+   * @returns The requested L1 to L2 entry keys.
+   */
+  getPendingEntryKeysByFee(limit: number): Fr[] {
+    const entryKeys: Fr[] = [];
+
+    for (const [[_, entryKey], count] of this.#pendingMessagesByFee.entries({
+      reverse: true,
+    })) {
+      // put `count` copies of this message in the result list
+      entryKeys.push(...Array(count).fill(Fr.fromString(entryKey)));
+      if (entryKeys.length >= limit) {
+        break;
+      }
+    }
+
+    return entryKeys;
+  }
+}