@aztec/archiver 0.0.0-test.1 → 0.0.1-commit.5476d83

package/src/archiver/archiver_store.ts

@@ -1,21 +1,23 @@
+import type { L1BlockId } from '@aztec/ethereum';
 import type { Fr } from '@aztec/foundation/fields';
+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 { L2Block, ValidateBlockResult } from '@aztec/stdlib/block';
 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 { 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 { InboxMessage } from './structs/inbox_message.js';
+import type { PublishedL2Block } from './structs/published.js';
 
 /**
  * Represents the latest L1 block processed by the archiver for various objects in L2.
@@ -23,10 +25,8 @@ import type { L1Published } from './structs/published.js';
 export type ArchiverL1SynchPoint = {
   /** Number of the last L1 block that added a new L2 block 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,12 +34,17 @@ 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: PublishedL2Block[], opts?: { force?: boolean }): Promise<boolean>;
 
   /**
    * Unwinds blocks from the database
@@ -51,12 +56,30 @@ export interface ArchiverDataStore {
   unwindBlocks(from: number, blocksToUnwind: number): Promise<boolean>;
 
   /**
-   * Gets up to `limit` amount of L2 blocks starting from `from`.
+   * Returns the block for the given number, or undefined if not exists.
+   * @param number - The block number to return.
+   */
+  getPublishedBlock(number: number): Promise<PublishedL2Block | undefined>;
+
+  /**
+   * Returns the block for the given hash, or undefined if not exists.
+   * @param blockHash - The block hash to return.
+   */
+  getPublishedBlockByHash(blockHash: Fr): Promise<PublishedL2Block | undefined>;
+
+  /**
+   * Returns the block for the given archive root, or undefined if not exists.
+   * @param archive - The archive root to return.
+   */
+  getPublishedBlockByArchive(archive: Fr): Promise<PublishedL2Block | undefined>;
+
+  /**
+   * 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>[]>;
+  getPublishedBlocks(from: number, limit: number): Promise<PublishedL2Block[]>;
 
   /**
    * Gets up to `limit` amount of L2 block headers starting from `from`.
@@ -66,12 +89,24 @@ export interface ArchiverDataStore {
    */
   getBlockHeaders(from: number, 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.
@@ -88,36 +123,19 @@ export interface ArchiverDataStore {
   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)[]>;
-
   /**
    * 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.
    * @returns The L1 to L2 messages/leaves of the messages subtree (throws if not found).
    */
-  getL1ToL2Messages(blockNumber: bigint): Promise<Fr[]>;
+  getL1ToL2Messages(blockNumber: number): Promise<Fr[]>;
 
   /**
    * Gets the L1 to L2 message index in the L1 to L2 message tree.
@@ -143,10 +161,11 @@ export interface ArchiverDataStore {
   /**
    * 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.
+   * @param logsPerTag - The number of logs to return per tag. Defaults to everything
    * @returns For each received tag, an array of matching logs is returned. An empty array implies no logs match
    * that tag.
    */
-  getLogsByTags(tags: Fr[]): Promise<TxScopedL2Log[][]>;
+  getLogsByTags(tags: Fr[], logsPerTag?: number): Promise<TxScopedL2Log[][]>;
 
   /**
    * Gets public logs based on the provided filter.
@@ -187,10 +206,9 @@ export interface ArchiverDataStore {
   setBlockSynchedL1BlockNumber(l1BlockNumber: bigint): Promise<void>;
 
   /**
-   * Stores the l1 block number that messages have been synched until
-   * @param l1BlockNumber  - The l1 block number
+   * Stores the l1 block that messages have been synched until
    */
-  setMessageSynchedL1BlockNumber(l1BlockNumber: bigint): Promise<void>;
+  setMessageSynchedL1Block(l1Block: L1BlockId): Promise<void>;
 
   /**
    * Gets the synch point of the archiver
@@ -227,37 +245,61 @@ export interface ArchiverDataStore {
   /**
    * 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 L2 block number. */
+  rollbackL1ToL2MessagesToL2Block(targetBlockNumber: number): 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>;
 }