@aztec/archiver 0.0.0-test.1 → 0.0.1-commit.03f7ef2

package/src/archiver/archiver_store.ts

@@ -1,32 +1,34 @@
-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 type { CustomRange } from '@aztec/kv-store';
 import type { FunctionSelector } from '@aztec/stdlib/abi';
 import type { AztecAddress } from '@aztec/stdlib/aztec-address';
-import type { InBlock, L2Block } from '@aztec/stdlib/block';
+import type { CheckpointedL2Block, L2BlockNew, ValidateBlockResult } from '@aztec/stdlib/block';
+import type { PublishedCheckpoint } from '@aztec/stdlib/checkpoint';
 import type {
   ContractClassPublic,
   ContractInstanceUpdateWithAddress,
   ContractInstanceWithAddress,
   ExecutablePrivateFunctionWithMembershipProof,
-  UnconstrainedFunctionWithMembershipProof,
+  UtilityFunctionWithMembershipProof,
 } from '@aztec/stdlib/contract';
 import type { GetContractClassLogsResponse, GetPublicLogsResponse } from '@aztec/stdlib/interfaces/client';
-import type { LogFilter, PrivateLog, TxScopedL2Log } from '@aztec/stdlib/logs';
-import type { InboxLeaf } from '@aztec/stdlib/messaging';
-import { BlockHeader, type TxEffect, type TxHash, type TxReceipt } from '@aztec/stdlib/tx';
+import type { LogFilter, SiloedTag, Tag, TxScopedL2Log } from '@aztec/stdlib/logs';
+import { BlockHeader, type IndexedTxEffect, type TxHash, type TxReceipt } from '@aztec/stdlib/tx';
+import type { UInt64 } from '@aztec/stdlib/types';
 
-import type { DataRetrieval } from './structs/data_retrieval.js';
-import type { L1Published } from './structs/published.js';
+import type { CheckpointData } from './kv_archiver_store/block_store.js';
+import type { InboxMessage } from './structs/inbox_message.js';
 
 /**
  * Represents the latest L1 block processed by the archiver for various objects in L2.
  */
 export type ArchiverL1SynchPoint = {
-  /** Number of the last L1 block that added a new L2 block metadata.  */
+  /** Number of the last L1 block that added a new L2 checkpoint metadata.  */
   blocksSynchedTo?: bigint;
-  /** Number of the last L1 block that added L1 -> L2 messages from the Inbox. */
-  messagesSynchedTo?: bigint;
-  /** Number of the last L1 block that added a new proven block. */
-  provenLogsSynchedTo?: bigint;
+  /** Last L1 block checked for L1 to L2 messages. */
+  messagesSynchedTo?: L1BlockId;
 };
 
 /**
@@ -34,29 +36,105 @@ export type ArchiverL1SynchPoint = {
  * (blocks, encrypted logs, aztec contract data extended contract data).
  */
 export interface ArchiverDataStore {
+  /** Opens a new transaction to the underlying store and runs all operations within it. */
+  transactionAsync<T>(callback: () => Promise<T>): Promise<T>;
+
   /**
    * Append new blocks to the store's list.
    * @param blocks - The L2 blocks to be added to the store and the last processed L1 block.
+   * @param opts - Options for the operation.
+   * @param opts.force - If true, the blocks will be added even if they have gaps.
    * @returns True if the operation is successful.
    */
-  addBlocks(blocks: L1Published<L2Block>[]): Promise<boolean>;
+  addBlocks(blocks: L2BlockNew[], opts?: { force?: boolean }): Promise<boolean>;
+
+  /**
+   * Appends new checkpoints, and their blocks to the store's collection
+   * @param checkpoints The collectionn of checkpoints to be added
+   * @returns True if the operation is successful
+   */
+  addCheckpoints(checkpoints: PublishedCheckpoint[]): Promise<boolean>;
 
   /**
-   * Unwinds blocks from the database
+   * Retrieves all blocks for the requested chackpoint
+   * @param checkpointNumber Retreieves all blocks for the given checkpoint
+   * @returns The collection of blocks for the requested checkpoint if available (undefined otherwise)
+   */
+  getBlocksForCheckpoint(checkpointNumber: CheckpointNumber): Promise<L2BlockNew[] | undefined>;
+
+  /**
+   * Returns an array of checkpoint objects
+   * @param from The first checkpoint number to be retrieved
+   * @param limit The maximum number of chackpoints to retrieve
+   * @returns The array of requested checkpoint data objects
+   */
+  getRangeOfCheckpoints(from: CheckpointNumber, limit: number): Promise<CheckpointData[]>;
+
+  /**
+   * Unwinds checkpoints from the database
    * @param from -  The tip of the chain, passed for verification purposes,
    *                ensuring that we don't end up deleting something we did not intend
-   * @param blocksToUnwind - The number of blocks we are to unwind
+   * @param checkpointsToUnwind - The number of checkpoints we are to unwind
    * @returns True if the operation is successful
    */
-  unwindBlocks(from: number, blocksToUnwind: number): Promise<boolean>;
+  unwindCheckpoints(from: CheckpointNumber, checkpointsToUnwind: number): Promise<boolean>;
+
+  /**
+   * Returns the block for the given number, or undefined if not exists.
+   * @param number - The block number to return.
+   */
+  getCheckpointedBlock(number: number): Promise<CheckpointedL2Block | undefined>;
+
+  /**
+   * Returns the block for the given hash, or undefined if not exists.
+   * @param blockHash - The block hash to return.
+   */
+  getCheckpointedBlockByHash(blockHash: Fr): Promise<CheckpointedL2Block | undefined>;
+
+  /**
+   * Returns the block for the given archive root, or undefined if not exists.
+   * @param archive - The archive root to return.
+   */
+  getCheckpointedBlockByArchive(archive: Fr): Promise<CheckpointedL2Block | undefined>;
+
+  /**
+   * Returns checkpoint data for the requested checkpoint number
+   * @param checkpointNumber - The checkpoint requested
+   * @returns The checkpoint data or undefined if not found
+   */
+  getCheckpointData(checkpointNumber: CheckpointNumber): Promise<CheckpointData | undefined>;
+
+  /**
+   * Returns the number of the latest block
+   * @returns The number of the latest block
+   */
+  getLatestBlockNumber(): Promise<BlockNumber>;
+
+  /**
+   * Returns the block for the given number, or undefined if not exists.
+   * @param number - The block number to return.
+   */
+  getBlock(number: number): Promise<L2BlockNew | undefined>;
+
+  /**
+   * Returns the block for the given hash, or undefined if not exists.
+   * @param blockHash - The block hash to return.
+   */
+  getBlockByHash(blockHash: Fr): Promise<L2BlockNew | undefined>;
+
+  /**
+   * Returns the block for the given archive root, or undefined if not exists.
+   * @param archive - The archive root to return.
+   */
+  getBlockByArchive(archive: Fr): Promise<L2BlockNew | undefined>;
 
   /**
-   * Gets up to `limit` amount of L2 blocks starting from `from`.
+   * Gets up to `limit` amount of published L2 blocks starting from `from`.
    * @param from - Number of the first block to return (inclusive).
    * @param limit - The number of blocks to return.
    * @returns The requested L2 blocks.
    */
-  getBlocks(from: number, limit: number): Promise<L1Published<L2Block>[]>;
+  getBlocks(from: number, limit: number): Promise<L2BlockNew[]>;
 
   /**
    * Gets up to `limit` amount of L2 block headers starting from `from`.
@@ -64,14 +142,26 @@ export interface ArchiverDataStore {
    * @param limit - The number of blocks to return.
    * @returns The requested L2 block headers.
    */
-  getBlockHeaders(from: number, limit: number): Promise<BlockHeader[]>;
+  getBlockHeaders(from: BlockNumber, limit: number): Promise<BlockHeader[]>;
+
+  /**
+   * Returns the block header for the given hash, or undefined if not exists.
+   * @param blockHash - The block hash to return.
+   */
+  getBlockHeaderByHash(blockHash: Fr): Promise<BlockHeader | undefined>;
+
+  /**
+   * Returns the block header for the given archive root, or undefined if not exists.
+   * @param archive - The archive root to return.
+   */
+  getBlockHeaderByArchive(archive: Fr): Promise<BlockHeader | undefined>;
 
   /**
    * 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).
+   * @param txHash - The hash of the tx corresponding to the tx effect.
+   * @returns The requested tx effect with block info (or undefined if not found).
    */
-  getTxEffect(txHash: TxHash): Promise<InBlock<TxEffect> | undefined>;
+  getTxEffect(txHash: TxHash): Promise<IndexedTxEffect | undefined>;
 
   /**
    * Gets a receipt of a settled tx.
@@ -85,39 +175,22 @@ export interface ArchiverDataStore {
    * @param blocks - The blocks for which to add the logs.
    * @returns True if the operation is successful.
    */
-  addLogs(blocks: L2Block[]): Promise<boolean>;
-  deleteLogs(blocks: L2Block[]): Promise<boolean>;
-
-  /**
-   * Append new nullifiers to the store's list.
-   * @param blocks - The blocks for which to add the nullifiers.
-   * @returns True if the operation is successful.
-   */
-  addNullifiers(blocks: L2Block[]): Promise<boolean>;
-  deleteNullifiers(blocks: L2Block[]): Promise<boolean>;
-
-  /**
-   * Returns the provided nullifier indexes scoped to the block
-   * they were first included in, or undefined if they're not present in the tree
-   * @param blockNumber Max block number to search for the nullifiers
-   * @param nullifiers Nullifiers to get
-   * @returns The block scoped indexes of the provided nullifiers, or undefined if the nullifier doesn't exist in the tree
-   */
-  findNullifiersIndexesWithBlock(blockNumber: number, nullifiers: Fr[]): Promise<(InBlock<bigint> | undefined)[]>;
+  addLogs(blocks: L2BlockNew[]): Promise<boolean>;
+  deleteLogs(blocks: L2BlockNew[]): Promise<boolean>;
 
   /**
    * Append L1 to L2 messages to the store.
-   * @param messages - The L1 to L2 messages to be added to the store and the last processed L1 block.
+   * @param messages - The L1 to L2 messages to be added to the store.
    * @returns True if the operation is successful.
    */
-  addL1ToL2Messages(messages: DataRetrieval<InboxLeaf>): Promise<boolean>;
+  addL1ToL2Messages(messages: InboxMessage[]): Promise<void>;
 
   /**
-   * 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: bigint): Promise<Fr[]>;
+  getL1ToL2Messages(checkpointNumber: CheckpointNumber): Promise<Fr[]>;
 
   /**
    * Gets the L1 to L2 message index in the L1 to L2 message tree.
@@ -133,20 +206,17 @@ export interface ArchiverDataStore {
   getTotalL1ToL2MessageCount(): Promise<bigint>;
 
   /**
-   * 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.
+  /**
+   * 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.
    */
-  getPrivateLogs(from: number, limit: number): Promise<PrivateLog[]>;
+  getPrivateLogsByTags(tags: SiloedTag[]): Promise<TxScopedL2Log[][]>;
 
   /**
-   * 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.
    */
-  getLogsByTags(tags: Fr[]): Promise<TxScopedL2Log[][]>;
+  getPublicLogsByTagsFromContract(contractAddress: AztecAddress, tags: Tag[]): Promise<TxScopedL2Log[][]>;
 
   /**
    * Gets public logs based on the provided filter.
@@ -166,31 +236,42 @@ export interface ArchiverDataStore {
    * Gets the number of the latest L2 block processed.
    * @returns The number of the latest L2 block processed.
    */
-  getSynchedL2BlockNumber(): Promise<number>;
+  getCheckpointedL2BlockNumber(): Promise<BlockNumber>;
 
   /**
-   * Gets the number of the latest proven L2 block processed.
-   * @returns The number of the latest proven L2 block processed.
+   * Gets the number of the latest published checkpoint processed.
+   * @returns The number of the latest published checkpoint processed
    */
-  getProvenL2BlockNumber(): Promise<number>;
+  getSynchedCheckpointNumber(): Promise<CheckpointNumber>;
 
   /**
-   * Stores the number of the latest proven L2 block processed.
-   * @param l2BlockNumber - The number of the latest proven L2 block processed.
+   * Gets the number of the latest proven checkpoint processed.
+   * @returns The number of the latest proven checkpoint processed.
    */
-  setProvenL2BlockNumber(l2BlockNumber: number): Promise<void>;
+  getProvenCheckpointNumber(): Promise<CheckpointNumber>;
 
   /**
-   * Stores the l1 block number that blocks have been synched until
-   * @param l1BlockNumber  - The l1 block number
+   * Returns the number of the most recent proven block
+   * @returns The number of the most recent proven block
+   */
+  getProvenBlockNumber(): Promise<BlockNumber>;
+
+  /**
+   * Stores the number of the latest proven checkpoint processed.
+   * @param checkpointNumber - The number of the latest proven checkpoint processed.
    */
-  setBlockSynchedL1BlockNumber(l1BlockNumber: bigint): Promise<void>;
+  setProvenCheckpointNumber(checkpointNumber: CheckpointNumber): Promise<void>;
 
   /**
-   * Stores the l1 block number that messages have been synched until
+   * Stores the l1 block number that checkpoints have been synched until
    * @param l1BlockNumber  - The l1 block number
    */
-  setMessageSynchedL1BlockNumber(l1BlockNumber: bigint): Promise<void>;
+  setCheckpointSynchedL1BlockNumber(l1BlockNumber: bigint): Promise<void>;
+
+  /**
+   * Stores the l1 block that messages have been synched until
+   */
+  setMessageSynchedL1Block(l1Block: L1BlockId): Promise<void>;
 
   /**
    * Gets the synch point of the archiver
@@ -203,9 +284,13 @@ export interface ArchiverDataStore {
    * @param blockNumber - Number of the L2 block the contracts were registered in.
    * @returns True if the operation is successful.
    */
-  addContractClasses(data: ContractClassPublic[], bytecodeCommitments: Fr[], blockNumber: number): Promise<boolean>;
+  addContractClasses(
+    data: ContractClassPublic[],
+    bytecodeCommitments: Fr[],
+    blockNumber: BlockNumber,
+  ): Promise<boolean>;
 
-  deleteContractClasses(data: ContractClassPublic[], blockNumber: number): Promise<boolean>;
+  deleteContractClasses(data: ContractClassPublic[], blockNumber: BlockNumber): Promise<boolean>;
 
   getBytecodeCommitment(contractClassId: Fr): Promise<Fr | undefined>;
 
@@ -221,43 +306,67 @@ export interface ArchiverDataStore {
    * @param blockNumber - Number of the L2 block the instances were deployed in.
    * @returns True if the operation is successful.
    */
-  addContractInstances(data: ContractInstanceWithAddress[], blockNumber: number): Promise<boolean>;
-  deleteContractInstances(data: ContractInstanceWithAddress[], blockNumber: number): Promise<boolean>;
+  addContractInstances(data: ContractInstanceWithAddress[], blockNumber: BlockNumber): Promise<boolean>;
+  deleteContractInstances(data: ContractInstanceWithAddress[], blockNumber: BlockNumber): Promise<boolean>;
 
   /**
    * Add new contract instance updates
    * @param data - List of contract updates to be added.
-   * @param blockNumber - Number of the L2 block the updates were scheduled in.
+   * @param timestamp - Timestamp at which the updates were scheduled.
    * @returns True if the operation is successful.
    */
-  addContractInstanceUpdates(data: ContractInstanceUpdateWithAddress[], blockNumber: number): Promise<boolean>;
-  deleteContractInstanceUpdates(data: ContractInstanceUpdateWithAddress[], blockNumber: number): Promise<boolean>;
+  addContractInstanceUpdates(data: ContractInstanceUpdateWithAddress[], timestamp: UInt64): Promise<boolean>;
+  deleteContractInstanceUpdates(data: ContractInstanceUpdateWithAddress[], timestamp: UInt64): Promise<boolean>;
   /**
    * Adds private functions to a contract class.
    */
   addFunctions(
     contractClassId: Fr,
     privateFunctions: ExecutablePrivateFunctionWithMembershipProof[],
-    unconstrainedFunctions: UnconstrainedFunctionWithMembershipProof[],
+    utilityFunctions: UtilityFunctionWithMembershipProof[],
   ): Promise<boolean>;
 
   /**
-   * Returns a contract instance given its address and the given block number, or undefined if not exists.
+   * Returns a contract instance given its address and the given timestamp, or undefined if not exists.
    * @param address - Address of the contract.
+   * @param timestamp - Timestamp to get the contract instance at. Contract updates might change the instance.
+   * @returns The contract instance or undefined if not found.
    */
-  getContractInstance(address: AztecAddress): Promise<ContractInstanceWithAddress | undefined>;
+  getContractInstance(address: AztecAddress, timestamp: UInt64): Promise<ContractInstanceWithAddress | undefined>;
 
   /** Returns the list of all class ids known by the archiver. */
   getContractClassIds(): Promise<Fr[]>;
 
-  // TODO:  These function names are in memory only as they are for development/debugging. They require the full contract
-  //        artifact supplied to the node out of band. This should be reviewed and potentially removed as part of
-  //        the node api cleanup process.
-  registerContractFunctionSignatures(address: AztecAddress, signatures: string[]): Promise<void>;
-  getContractFunctionName(address: AztecAddress, selector: FunctionSelector): Promise<string | undefined>;
+  /** Register a public function signature, so it can be looked up by selector. */
+  registerContractFunctionSignatures(signatures: string[]): Promise<void>;
 
-  /**
-   * Estimates the size of the store in bytes.
-   */
-  estimateSize(): Promise<{ mappingSize: number; actualSize: number; numItems: number }>;
+  /** Looks up a public function name given a selector. */
+  getDebugFunctionName(address: AztecAddress, selector: FunctionSelector): Promise<string | undefined>;
+
+  /** Estimates the size of the store in bytes. */
+  estimateSize(): Promise<{ mappingSize: number; physicalFileSize: number; actualSize: number; numItems: number }>;
+
+  /** Backups the archiver db to the target folder. Returns the path to the db file. */
+  backupTo(path: string): Promise<string>;
+
+  /** Closes the underlying data store. */
+  close(): Promise<void>;
+
+  /** Deletes all L1 to L2 messages up until (excluding) the target checkpoint number. */
+  rollbackL1ToL2MessagesToCheckpoint(targetCheckpointNumber: CheckpointNumber): Promise<void>;
+
+  /** Returns an async iterator to all L1 to L2 messages on the range. */
+  iterateL1ToL2Messages(range?: CustomRange<bigint>): AsyncIterableIterator<InboxMessage>;
+
+  /** Removes all L1 to L2 messages starting from the given index (inclusive). */
+  removeL1ToL2Messages(startIndex: bigint): Promise<void>;
+
+  /** Returns the last L1 to L2 message stored. */
+  getLastL1ToL2Message(): Promise<InboxMessage | undefined>;
+
+  /** Returns the last synced validation status of the pending chain. */
+  getPendingChainValidationStatus(): Promise<ValidateBlockResult | undefined>;
+
+  /** Sets the last synced validation status of the pending chain. */
+  setPendingChainValidationStatus(status: ValidateBlockResult | undefined): Promise<void>;
 }