@aztec/pxe 0.22.0 → 0.24.0

package/src/database/kv_pxe_database.ts

@@ -0,0 +1,409 @@
+import { ContractDao, MerkleTreeId, NoteFilter, NoteStatus, PublicKey } from '@aztec/circuit-types';
+import { AztecAddress, CompleteAddress, Header } from '@aztec/circuits.js';
+import { ContractArtifact } from '@aztec/foundation/abi';
+import { toBufferBE } from '@aztec/foundation/bigint-buffer';
+import { Fr, Point } from '@aztec/foundation/fields';
+import { AztecArray, AztecKVStore, AztecMap, AztecMultiMap, AztecSingleton } from '@aztec/kv-store';
+import { contractArtifactFromBuffer, contractArtifactToBuffer } from '@aztec/types/abi';
+import { ContractInstanceWithAddress, SerializableContractInstance } from '@aztec/types/contracts';
+
+import { DeferredNoteDao } from './deferred_note_dao.js';
+import { NoteDao } from './note_dao.js';
+import { PxeDatabase } from './pxe_database.js';
+
+/**
+ * A PXE database backed by LMDB.
+ */
+export class KVPxeDatabase implements PxeDatabase {
+  #synchronizedBlock: AztecSingleton<Buffer>;
+  #addresses: AztecArray<Buffer>;
+  #addressIndex: AztecMap<string, number>;
+  #authWitnesses: AztecMap<string, Buffer[]>;
+  #capsules: AztecArray<Buffer[]>;
+  #contracts: AztecMap<string, Buffer>;
+  #notes: AztecMap<string, Buffer>;
+  #nullifiedNotes: AztecMap<string, Buffer>;
+  #nullifierToNoteId: AztecMap<string, string>;
+  #notesByContract: AztecMultiMap<string, string>;
+  #notesByStorageSlot: AztecMultiMap<string, string>;
+  #notesByTxHash: AztecMultiMap<string, string>;
+  #notesByOwner: AztecMultiMap<string, string>;
+  #nullifiedNotesByContract: AztecMultiMap<string, string>;
+  #nullifiedNotesByStorageSlot: AztecMultiMap<string, string>;
+  #nullifiedNotesByTxHash: AztecMultiMap<string, string>;
+  #nullifiedNotesByOwner: AztecMultiMap<string, string>;
+  #deferredNotes: AztecArray<Buffer | null>;
+  #deferredNotesByContract: AztecMultiMap<string, number>;
+  #syncedBlockPerPublicKey: AztecMap<string, number>;
+  #contractArtifacts: AztecMap<string, Buffer>;
+  #contractInstances: AztecMap<string, Buffer>;
+  #db: AztecKVStore;
+
+  constructor(private db: AztecKVStore) {
+    this.#db = db;
+
+    this.#addresses = db.openArray('addresses');
+    this.#addressIndex = db.openMap('address_index');
+
+    this.#authWitnesses = db.openMap('auth_witnesses');
+    this.#capsules = db.openArray('capsules');
+    this.#contracts = db.openMap('contracts');
+
+    this.#contractArtifacts = db.openMap('contract_artifacts');
+    this.#contractInstances = db.openMap('contracts_instances');
+
+    this.#synchronizedBlock = db.openSingleton('header');
+    this.#syncedBlockPerPublicKey = db.openMap('synced_block_per_public_key');
+
+    this.#notes = db.openMap('notes');
+    this.#nullifiedNotes = db.openMap('nullified_notes');
+    this.#nullifierToNoteId = db.openMap('nullifier_to_note');
+
+    this.#notesByContract = db.openMultiMap('notes_by_contract');
+    this.#notesByStorageSlot = db.openMultiMap('notes_by_storage_slot');
+    this.#notesByTxHash = db.openMultiMap('notes_by_tx_hash');
+    this.#notesByOwner = db.openMultiMap('notes_by_owner');
+
+    this.#nullifiedNotesByContract = db.openMultiMap('nullified_notes_by_contract');
+    this.#nullifiedNotesByStorageSlot = db.openMultiMap('nullified_notes_by_storage_slot');
+    this.#nullifiedNotesByTxHash = db.openMultiMap('nullified_notes_by_tx_hash');
+    this.#nullifiedNotesByOwner = db.openMultiMap('nullified_notes_by_owner');
+
+    this.#deferredNotes = db.openArray('deferred_notes');
+    this.#deferredNotesByContract = db.openMultiMap('deferred_notes_by_contract');
+  }
+
+  public async addContractArtifact(id: Fr, contract: ContractArtifact): Promise<void> {
+    await this.#contractArtifacts.set(id.toString(), contractArtifactToBuffer(contract));
+  }
+
+  getContractArtifact(id: Fr): Promise<ContractArtifact | undefined> {
+    const contract = this.#contractArtifacts.get(id.toString());
+    // TODO(@spalladino): AztecMap lies and returns Uint8Arrays instead of Buffers, hence the extra Buffer.from.
+    return Promise.resolve(contract && contractArtifactFromBuffer(Buffer.from(contract)));
+  }
+
+  async addContractInstance(contract: ContractInstanceWithAddress): Promise<void> {
+    await this.#contractInstances.set(
+      contract.address.toString(),
+      new SerializableContractInstance(contract).toBuffer(),
+    );
+  }
+
+  getContractInstance(address: AztecAddress): Promise<ContractInstanceWithAddress | undefined> {
+    const contract = this.#contractInstances.get(address.toString());
+    return Promise.resolve(contract && SerializableContractInstance.fromBuffer(contract).withAddress(address));
+  }
+
+  async addAuthWitness(messageHash: Fr, witness: Fr[]): Promise<void> {
+    await this.#authWitnesses.set(
+      messageHash.toString(),
+      witness.map(w => w.toBuffer()),
+    );
+  }
+
+  getAuthWitness(messageHash: Fr): Promise<Fr[] | undefined> {
+    const witness = this.#authWitnesses.get(messageHash.toString());
+    return Promise.resolve(witness?.map(w => Fr.fromBuffer(w)));
+  }
+
+  async addCapsule(capsule: Fr[]): Promise<void> {
+    await this.#capsules.push(capsule.map(c => c.toBuffer()));
+  }
+
+  async popCapsule(): Promise<Fr[] | undefined> {
+    const val = await this.#capsules.pop();
+    return val?.map(b => Fr.fromBuffer(b));
+  }
+
+  async addNote(note: NoteDao): Promise<void> {
+    await this.addNotes([note]);
+  }
+
+  addNotes(notes: NoteDao[]): Promise<void> {
+    return this.db.transaction(() => {
+      for (const dao of notes) {
+        // store notes by their index in the notes hash tree
+        // this provides the uniqueness we need to store individual notes
+        // and should also return notes in the order that they were created.
+        // Had we stored them by their nullifier, they would be returned in random order
+        const noteIndex = toBufferBE(dao.index, 32).toString('hex');
+        void this.#notes.set(noteIndex, dao.toBuffer());
+        void this.#nullifierToNoteId.set(dao.siloedNullifier.toString(), noteIndex);
+        void this.#notesByContract.set(dao.contractAddress.toString(), noteIndex);
+        void this.#notesByStorageSlot.set(dao.storageSlot.toString(), noteIndex);
+        void this.#notesByTxHash.set(dao.txHash.toString(), noteIndex);
+        void this.#notesByOwner.set(dao.publicKey.toString(), noteIndex);
+      }
+    });
+  }
+
+  async addDeferredNotes(deferredNotes: DeferredNoteDao[]): Promise<void> {
+    const newLength = await this.#deferredNotes.push(...deferredNotes.map(note => note.toBuffer()));
+    for (const [index, note] of deferredNotes.entries()) {
+      const noteId = newLength - deferredNotes.length + index;
+      await this.#deferredNotesByContract.set(note.contractAddress.toString(), noteId);
+    }
+  }
+
+  getDeferredNotesByContract(contractAddress: AztecAddress): Promise<DeferredNoteDao[]> {
+    const noteIds = this.#deferredNotesByContract.getValues(contractAddress.toString());
+    const notes: DeferredNoteDao[] = [];
+    for (const noteId of noteIds) {
+      const serializedNote = this.#deferredNotes.at(noteId);
+      if (!serializedNote) {
+        continue;
+      }
+
+      const note = DeferredNoteDao.fromBuffer(serializedNote);
+      notes.push(note);
+    }
+
+    return Promise.resolve(notes);
+  }
+
+  /**
+   * Removes all deferred notes for a given contract address.
+   * @param contractAddress - the contract address to remove deferred notes for
+   * @returns an array of the removed deferred notes
+   */
+  removeDeferredNotesByContract(contractAddress: AztecAddress): Promise<DeferredNoteDao[]> {
+    return this.#db.transaction(() => {
+      const deferredNotes: DeferredNoteDao[] = [];
+      const indices = this.#deferredNotesByContract.getValues(contractAddress.toString());
+
+      for (const index of indices) {
+        const deferredNoteBuffer = this.#deferredNotes.at(index);
+        if (!deferredNoteBuffer) {
+          continue;
+        } else {
+          deferredNotes.push(DeferredNoteDao.fromBuffer(deferredNoteBuffer));
+        }
+
+        void this.#deferredNotesByContract.deleteValue(contractAddress.toString(), index);
+        void this.#deferredNotes.setAt(index, null);
+      }
+
+      return deferredNotes;
+    });
+  }
+
+  #getNotes(filter: NoteFilter): NoteDao[] {
+    const publicKey: PublicKey | undefined = filter.owner
+      ? this.#getCompleteAddress(filter.owner)?.publicKey
+      : undefined;
+
+    filter.status = filter.status ?? NoteStatus.ACTIVE;
+
+    const candidateNoteSources = [];
+
+    candidateNoteSources.push({
+      ids: publicKey
+        ? this.#notesByOwner.getValues(publicKey.toString())
+        : filter.txHash
+        ? this.#notesByTxHash.getValues(filter.txHash.toString())
+        : filter.contractAddress
+        ? this.#notesByContract.getValues(filter.contractAddress.toString())
+        : filter.storageSlot
+        ? this.#notesByStorageSlot.getValues(filter.storageSlot.toString())
+        : this.#notes.keys(),
+      notes: this.#notes,
+    });
+
+    if (filter.status == NoteStatus.ACTIVE_OR_NULLIFIED) {
+      candidateNoteSources.push({
+        ids: publicKey
+          ? this.#nullifiedNotesByOwner.getValues(publicKey.toString())
+          : filter.txHash
+          ? this.#nullifiedNotesByTxHash.getValues(filter.txHash.toString())
+          : filter.contractAddress
+          ? this.#nullifiedNotesByContract.getValues(filter.contractAddress.toString())
+          : filter.storageSlot
+          ? this.#nullifiedNotesByStorageSlot.getValues(filter.storageSlot.toString())
+          : this.#nullifiedNotes.keys(),
+        notes: this.#nullifiedNotes,
+      });
+    }
+
+    const result: NoteDao[] = [];
+    for (const { ids, notes } of candidateNoteSources) {
+      for (const id of ids) {
+        const serializedNote = notes.get(id);
+        if (!serializedNote) {
+          continue;
+        }
+
+        const note = NoteDao.fromBuffer(serializedNote);
+        if (filter.contractAddress && !note.contractAddress.equals(filter.contractAddress)) {
+          continue;
+        }
+
+        if (filter.txHash && !note.txHash.equals(filter.txHash)) {
+          continue;
+        }
+
+        if (filter.storageSlot && !note.storageSlot.equals(filter.storageSlot!)) {
+          continue;
+        }
+
+        if (publicKey && !note.publicKey.equals(publicKey)) {
+          continue;
+        }
+
+        result.push(note);
+      }
+    }
+
+    return result;
+  }
+
+  getNotes(filter: NoteFilter): Promise<NoteDao[]> {
+    return Promise.resolve(this.#getNotes(filter));
+  }
+
+  removeNullifiedNotes(nullifiers: Fr[], account: PublicKey): Promise<NoteDao[]> {
+    if (nullifiers.length === 0) {
+      return Promise.resolve([]);
+    }
+
+    return this.#db.transaction(() => {
+      const nullifiedNotes: NoteDao[] = [];
+
+      for (const nullifier of nullifiers) {
+        const noteIndex = this.#nullifierToNoteId.get(nullifier.toString());
+        if (!noteIndex) {
+          continue;
+        }
+
+        const noteBuffer = noteIndex ? this.#notes.get(noteIndex) : undefined;
+
+        if (!noteBuffer) {
+          // note doesn't exist. Maybe it got nullified already
+          continue;
+        }
+
+        const note = NoteDao.fromBuffer(noteBuffer);
+        if (!note.publicKey.equals(account)) {
+          // tried to nullify someone else's note
+          continue;
+        }
+
+        nullifiedNotes.push(note);
+
+        void this.#notes.delete(noteIndex);
+        void this.#notesByOwner.deleteValue(account.toString(), noteIndex);
+        void this.#notesByTxHash.deleteValue(note.txHash.toString(), noteIndex);
+        void this.#notesByContract.deleteValue(note.contractAddress.toString(), noteIndex);
+        void this.#notesByStorageSlot.deleteValue(note.storageSlot.toString(), noteIndex);
+
+        void this.#nullifiedNotes.set(noteIndex, note.toBuffer());
+        void this.#nullifiedNotesByContract.set(note.contractAddress.toString(), noteIndex);
+        void this.#nullifiedNotesByStorageSlot.set(note.storageSlot.toString(), noteIndex);
+        void this.#nullifiedNotesByTxHash.set(note.txHash.toString(), noteIndex);
+        void this.#nullifiedNotesByOwner.set(note.publicKey.toString(), noteIndex);
+
+        void this.#nullifierToNoteId.delete(nullifier.toString());
+      }
+
+      return nullifiedNotes;
+    });
+  }
+
+  async setHeader(header: Header): Promise<void> {
+    await this.#synchronizedBlock.set(header.toBuffer());
+  }
+
+  getBlockNumber(): number | undefined {
+    const headerBuffer = this.#synchronizedBlock.get();
+    if (!headerBuffer) {
+      return undefined;
+    }
+
+    return Number(Header.fromBuffer(headerBuffer).globalVariables.blockNumber.toBigInt());
+  }
+
+  getHeader(): Header {
+    const headerBuffer = this.#synchronizedBlock.get();
+    if (!headerBuffer) {
+      throw new Error(`Header not set`);
+    }
+
+    return Header.fromBuffer(headerBuffer);
+  }
+
+  addCompleteAddress(completeAddress: CompleteAddress): Promise<boolean> {
+    return this.#db.transaction(() => {
+      const addressString = completeAddress.address.toString();
+      const buffer = completeAddress.toBuffer();
+      const existing = this.#addressIndex.get(addressString);
+      if (typeof existing === 'undefined') {
+        const index = this.#addresses.length;
+        void this.#addresses.push(buffer);
+        void this.#addressIndex.set(addressString, index);
+
+        return true;
+      } else {
+        const existingBuffer = this.#addresses.at(existing);
+
+        if (existingBuffer?.equals(buffer)) {
+          return false;
+        }
+
+        throw new Error(
+          `Complete address with aztec address ${addressString} but different public key or partial key already exists in memory database`,
+        );
+      }
+    });
+  }
+
+  #getCompleteAddress(address: AztecAddress): CompleteAddress | undefined {
+    const index = this.#addressIndex.get(address.toString());
+    if (typeof index === 'undefined') {
+      return undefined;
+    }
+
+    const value = this.#addresses.at(index);
+    return value ? CompleteAddress.fromBuffer(value) : undefined;
+  }
+
+  getCompleteAddress(address: AztecAddress): Promise<CompleteAddress | undefined> {
+    return Promise.resolve(this.#getCompleteAddress(address));
+  }
+
+  getCompleteAddresses(): Promise<CompleteAddress[]> {
+    return Promise.resolve(Array.from(this.#addresses).map(v => CompleteAddress.fromBuffer(v)));
+  }
+
+  getSynchedBlockNumberForPublicKey(publicKey: Point): number | undefined {
+    return this.#syncedBlockPerPublicKey.get(publicKey.toString());
+  }
+
+  setSynchedBlockNumberForPublicKey(publicKey: Point, blockNumber: number): Promise<boolean> {
+    return this.#syncedBlockPerPublicKey.set(publicKey.toString(), blockNumber);
+  }
+
+  estimateSize(): number {
+    const notesSize = Array.from(this.#getNotes({})).reduce((sum, note) => sum + note.getSize(), 0);
+    const authWitsSize = Array.from(this.#authWitnesses.values()).reduce(
+      (sum, value) => sum + value.length * Fr.SIZE_IN_BYTES,
+      0,
+    );
+    const addressesSize = this.#addresses.length * CompleteAddress.SIZE_IN_BYTES;
+    const treeRootsSize = Object.keys(MerkleTreeId).length * Fr.SIZE_IN_BYTES;
+
+    return notesSize + treeRootsSize + authWitsSize + addressesSize;
+  }
+
+  async addContract(contract: ContractDao): Promise<void> {
+    await this.#contracts.set(contract.instance.address.toString(), contract.toBuffer());
+  }
+
+  getContract(address: AztecAddress): Promise<ContractDao | undefined> {
+    const contract = this.#contracts.get(address.toString());
+    return Promise.resolve(contract ? ContractDao.fromBuffer(contract) : undefined);
+  }
+
+  getContracts(): Promise<ContractDao[]> {
+    return Promise.resolve(Array.from(this.#contracts.values()).map(c => ContractDao.fromBuffer(c)));
+  }
+}

package/src/database/note_dao.ts

@@ -0,0 +1,97 @@
+import { Note, TxHash } from '@aztec/circuit-types';
+import { AztecAddress, Fr, Point, PublicKey } from '@aztec/circuits.js';
+import { toBigIntBE, toBufferBE } from '@aztec/foundation/bigint-buffer';
+import { BufferReader } from '@aztec/foundation/serialize';
+import { NoteData } from '@aztec/simulator';
+
+/**
+ * A note with contextual data.
+ */
+export class NoteDao implements NoteData {
+  constructor(
+    /** The note as emitted from the Noir contract. */
+    public note: Note,
+    /** The contract address this note is created in. */
+    public contractAddress: AztecAddress,
+    /** The specific storage location of the note on the contract. */
+    public storageSlot: Fr,
+    /** The note type identifier for the contract. */
+    public noteTypeId: Fr,
+    /** The hash of the tx the note was created in. */
+    public txHash: TxHash,
+    /** The nonce of the note. */
+    public nonce: Fr,
+    /**
+     * Inner note hash of the note. This is customizable by the app circuit.
+     * We can use this value to compute siloedNoteHash and uniqueSiloedNoteHash.
+     */
+    public innerNoteHash: Fr,
+    /** The nullifier of the note (siloed by contract address). */
+    public siloedNullifier: Fr,
+    /** The location of the relevant note in the note hash tree. */
+    public index: bigint,
+    /** The public key with which the note was encrypted. */
+    public publicKey: PublicKey,
+  ) {}
+
+  toBuffer(): Buffer {
+    return Buffer.concat([
+      this.note.toBuffer(),
+      this.contractAddress.toBuffer(),
+      this.storageSlot.toBuffer(),
+      this.noteTypeId.toBuffer(),
+      this.txHash.buffer,
+      this.nonce.toBuffer(),
+      this.innerNoteHash.toBuffer(),
+      this.siloedNullifier.toBuffer(),
+      toBufferBE(this.index, 32),
+      this.publicKey.toBuffer(),
+    ]);
+  }
+  static fromBuffer(buffer: Buffer | BufferReader) {
+    const reader = BufferReader.asReader(buffer);
+
+    const note = Note.fromBuffer(reader);
+    const contractAddress = AztecAddress.fromBuffer(reader);
+    const storageSlot = Fr.fromBuffer(reader);
+    const noteTypeId = Fr.fromBuffer(reader);
+    const txHash = new TxHash(reader.readBytes(TxHash.SIZE));
+    const nonce = Fr.fromBuffer(reader);
+    const innerNoteHash = Fr.fromBuffer(reader);
+    const siloedNullifier = Fr.fromBuffer(reader);
+    const index = toBigIntBE(reader.readBytes(32));
+    const publicKey = Point.fromBuffer(reader);
+
+    return new NoteDao(
+      note,
+      contractAddress,
+      storageSlot,
+      noteTypeId,
+      txHash,
+      nonce,
+      innerNoteHash,
+      siloedNullifier,
+      index,
+      publicKey,
+    );
+  }
+
+  toString() {
+    return '0x' + this.toBuffer().toString('hex');
+  }
+
+  static fromString(str: string) {
+    const hex = str.replace(/^0x/, '');
+    return NoteDao.fromBuffer(Buffer.from(hex, 'hex'));
+  }
+
+  /**
+   * Returns the size in bytes of the Note Dao.
+   * @returns - Its size in bytes.
+   */
+  public getSize() {
+    const indexSize = Math.ceil(Math.log2(Number(this.index)));
+    const noteSize = 4 + this.note.items.length * Fr.SIZE_IN_BYTES;
+    return noteSize + AztecAddress.SIZE_IN_BYTES + Fr.SIZE_IN_BYTES * 4 + TxHash.SIZE + Point.SIZE_IN_BYTES + indexSize;
+  }
+}

package/src/database/pxe_database.ts

@@ -0,0 +1,162 @@
+import { ContractDatabase, NoteFilter } from '@aztec/circuit-types';
+import { CompleteAddress, Header, PublicKey } from '@aztec/circuits.js';
+import { AztecAddress } from '@aztec/foundation/aztec-address';
+import { Fr } from '@aztec/foundation/fields';
+
+import { ContractArtifactDatabase } from './contracts/contract_artifact_db.js';
+import { ContractInstanceDatabase } from './contracts/contract_instance_db.js';
+import { DeferredNoteDao } from './deferred_note_dao.js';
+import { NoteDao } from './note_dao.js';
+
+/**
+ * A database interface that provides methods for retrieving, adding, and removing transactional data related to Aztec
+ * addresses, storage slots, and nullifiers.
+ */
+export interface PxeDatabase extends ContractDatabase, ContractArtifactDatabase, ContractInstanceDatabase {
+  /**
+   * Add a auth witness to the database.
+   * @param messageHash - The message hash.
+   * @param witness - An array of field elements representing the auth witness.
+   */
+  addAuthWitness(messageHash: Fr, witness: Fr[]): Promise<void>;
+
+  /**
+   * Fetching the auth witness for a given message hash.
+   * @param messageHash - The message hash.
+   * @returns A Promise that resolves to an array of field elements representing the auth witness.
+   */
+  getAuthWitness(messageHash: Fr): Promise<Fr[] | undefined>;
+
+  /**
+   * Adding a capsule to the capsule dispenser.
+   * @remarks A capsule is a "blob" of data that is passed to the contract through an oracle.
+   * @param capsule - An array of field elements representing the capsule.
+   */
+  addCapsule(capsule: Fr[]): Promise<void>;
+
+  /**
+   * Get the next capsule from the capsule dispenser.
+   * @remarks A capsule is a "blob" of data that is passed to the contract through an oracle.
+   * @returns A promise that resolves to an array of field elements representing the capsule.
+   */
+  popCapsule(): Promise<Fr[] | undefined>;
+
+  /**
+   * Gets notes based on the provided filter.
+   * @param filter - The filter to apply to the notes.
+   * @returns The requested notes.
+   */
+  getNotes(filter: NoteFilter): Promise<NoteDao[]>;
+
+  /**
+   * Adds a note to DB.
+   * @param note - The note to add.
+   */
+  addNote(note: NoteDao): Promise<void>;
+
+  /**
+   * Adds an array of notes to DB.
+   * This function is used to insert multiple notes to the database at once,
+   * which can improve performance when dealing with large numbers of transactions.
+   *
+   * @param notes - An array of notes.
+   */
+  addNotes(notes: NoteDao[]): Promise<void>;
+
+  /**
+   * Add notes to the database that are intended for us, but we don't yet have the contract.
+   * @param deferredNotes - An array of deferred notes.
+   */
+  addDeferredNotes(deferredNotes: DeferredNoteDao[]): Promise<void>;
+
+  /**
+   * Get deferred notes for a given contract address.
+   * @param contractAddress - The contract address to get the deferred notes for.
+   */
+  getDeferredNotesByContract(contractAddress: AztecAddress): Promise<DeferredNoteDao[]>;
+
+  /**
+   * Remove deferred notes for a given contract address.
+   * @param contractAddress - The contract address to remove the deferred notes for.
+   * @returns an array of the removed deferred notes
+   */
+  removeDeferredNotesByContract(contractAddress: AztecAddress): Promise<DeferredNoteDao[]>;
+
+  /**
+   * Remove nullified notes associated with the given account and nullifiers.
+   *
+   * @param nullifiers - An array of Fr instances representing nullifiers to be matched.
+   * @param account - A PublicKey instance representing the account for which the records are being removed.
+   * @returns Removed notes.
+   */
+  removeNullifiedNotes(nullifiers: Fr[], account: PublicKey): Promise<NoteDao[]>;
+
+  /**
+   * Gets the most recently processed block number.
+   * @returns The most recently processed block number or undefined if never synched.
+   */
+  getBlockNumber(): number | undefined;
+
+  /**
+   * Retrieve the stored Block Header from the database.
+   * The function returns a Promise that resolves to the Block Header.
+   * This data is required to reproduce block attestations.
+   * Throws an error if the block header is not available within the database.
+   *
+   * note: this data is a combination of the tree roots and the global variables hash.
+   *
+   * @returns The Block Header.
+   * @throws If no block have been processed yet.
+   */
+  getHeader(): Header;
+
+  /**
+   * Set the latest Block Header.
+   * Note that this will overwrite any existing hash or roots in the database.
+   *
+   * @param header - An object containing the most recent block header.
+   * @returns A Promise that resolves when the hash has been successfully updated in the database.
+   */
+  setHeader(header: Header): Promise<void>;
+
+  /**
+   * Adds complete address to the database.
+   * @param address - The complete address to add.
+   * @returns A promise resolving to true if the address was added, false if it already exists.
+   * @throws If we try to add a CompleteAddress with the same AztecAddress but different public key or partial
+   * address.
+   */
+  addCompleteAddress(address: CompleteAddress): Promise<boolean>;
+
+  /**
+   * Retrieves the complete address corresponding to the provided aztec address.
+   * @param address - The aztec address of the complete address contract.
+   * @returns A promise that resolves to a CompleteAddress instance if the address is found, or undefined if not found.
+   */
+  getCompleteAddress(address: AztecAddress): Promise<CompleteAddress | undefined>;
+
+  /**
+   * Retrieves the list of complete address added to this database
+   * @returns A promise that resolves to an array of AztecAddress instances.
+   */
+  getCompleteAddresses(): Promise<CompleteAddress[]>;
+
+  /**
+   * Updates up to which block number we have processed notes for a given public key.
+   * @param publicKey - The public key to set the synched block number for.
+   * @param blockNumber - The block number to set.
+   */
+  setSynchedBlockNumberForPublicKey(publicKey: PublicKey, blockNumber: number): Promise<boolean>;
+
+  /**
+   * Get the synched block number for a given public key.
+   * @param publicKey - The public key to get the synched block number for.
+   */
+  getSynchedBlockNumberForPublicKey(publicKey: PublicKey): number | undefined;
+
+  /**
+   * Returns the estimated size in bytes of this db.
+   * @returns The estimated size in bytes of this db.
+   */
+  estimateSize(): number;
+}