@aztec/simulator 0.69.1 → 0.71.0

package/src/acvm/oracle/typed_oracle.ts

@@ -5,7 +5,6 @@ import {
   type NoteStatus,
   type NullifierMembershipWitness,
   type PublicDataWitness,
-  type SiblingPath,
   type UnencryptedL2Log,
 } from '@aztec/circuit-types';
 import {
@@ -19,6 +18,8 @@ import { type FunctionSelector, type NoteSelector } from '@aztec/foundation/abi'
 import { type AztecAddress } from '@aztec/foundation/aztec-address';
 import { Fr } from '@aztec/foundation/fields';
 
+import { type MessageLoadOracleInputs } from '../../common/message_load_oracle_inputs.js';
+
 /**
  * Information about a note needed during execution.
  */
@@ -39,19 +40,6 @@ export interface NoteData {
   index?: bigint;
 }
 
-export class MessageLoadOracleInputs<N extends number> {
-  constructor(
-    /** The index of the message commitment in the merkle tree. */
-    public index: bigint,
-    /** The path in the merkle tree to the message. */
-    public siblingPath: SiblingPath<N>,
-  ) {}
-
-  toFields(): Fr[] {
-    return [new Fr(this.index), ...this.siblingPath.toFields()];
-  }
-}
-
 class OracleMethodNotAvailableError extends Error {
   constructor(methodName: string) {
     super(`Oracle method ${methodName} is not available.`);
@@ -68,16 +56,16 @@ export abstract class TypedOracle {
     return Fr.random();
   }
 
-  packArgumentsArray(_args: Fr[]): Promise<Fr> {
-    throw new OracleMethodNotAvailableError('packArgumentsArray');
+  storeArrayInExecutionCache(_args: Fr[]): Promise<Fr> {
+    throw new OracleMethodNotAvailableError('storeArrayInExecutionCache');
   }
 
-  packReturns(_returns: Fr[]): Promise<Fr> {
-    throw new OracleMethodNotAvailableError('packReturns');
+  storeInExecutionCache(_values: Fr[]): Promise<Fr> {
+    throw new OracleMethodNotAvailableError('storeInExecutionCache');
   }
 
-  unpackReturns(_returnsHash: Fr): Promise<Fr[]> {
-    throw new OracleMethodNotAvailableError('unpackReturns');
+  loadFromExecutionCache(_hash: Fr): Promise<Fr[]> {
+    throw new OracleMethodNotAvailableError('loadFromExecutionCache');
   }
 
   getBlockNumber(): Promise<number> {
@@ -108,10 +96,6 @@ export abstract class TypedOracle {
     throw new OracleMethodNotAvailableError('getMembershipWitness');
   }
 
-  getSiblingPath(_blockNumber: number, _treeId: MerkleTreeId, _leafIndex: Fr): Promise<Fr[]> {
-    throw new OracleMethodNotAvailableError('getSiblingPath');
-  }
-
   getNullifierMembershipWitness(_blockNumber: number, _nullifier: Fr): Promise<NullifierMembershipWitness | undefined> {
     throw new OracleMethodNotAvailableError('getNullifierMembershipWitness');
   }
@@ -170,6 +154,10 @@ export abstract class TypedOracle {
     throw new OracleMethodNotAvailableError('notifyNullifiedNote');
   }
 
+  notifyCreatedNullifier(_innerNullifier: Fr): Promise<void> {
+    throw new OracleMethodNotAvailableError('notifyCreatedNullifier');
+  }
+
   checkNullifierExists(_innerNullifier: Fr): Promise<boolean> {
     throw new OracleMethodNotAvailableError('checkNullifierExists');
   }
@@ -248,4 +236,33 @@ export abstract class TypedOracle {
   syncNotes(): Promise<void> {
     throw new OracleMethodNotAvailableError('syncNotes');
   }
+
+  deliverNote(
+    _contractAddress: AztecAddress,
+    _storageSlot: Fr,
+    _nonce: Fr,
+    _content: Fr[],
+    _noteHash: Fr,
+    _nullifier: Fr,
+    _txHash: Fr,
+    _recipient: AztecAddress,
+  ): Promise<void> {
+    throw new OracleMethodNotAvailableError('deliverNote');
+  }
+
+  dbStore(_contractAddress: AztecAddress, _key: Fr, _values: Fr[]): Promise<void> {
+    throw new OracleMethodNotAvailableError('dbStore');
+  }
+
+  dbLoad(_contractAddress: AztecAddress, _key: Fr): Promise<Fr[] | null> {
+    throw new OracleMethodNotAvailableError('dbLoad');
+  }
+
+  dbDelete(_contractAddress: AztecAddress, _key: Fr): Promise<void> {
+    throw new OracleMethodNotAvailableError('dbDelete');
+  }
+
+  dbCopy(_contractAddress: AztecAddress, _srcKey: Fr, _dstKey: Fr, _numEntries: number): Promise<void> {
+    throw new OracleMethodNotAvailableError('dbCopy');
+  }
 }

package/src/avm/avm_simulator.ts

@@ -137,6 +137,7 @@ export class AvmSimulator {
     this.bytecode = bytecode;
 
     const { machineState } = this.context;
+    const callStartGas = machineState.gasLeft; // Save gas before executing instruction (for profiling)
     try {
       // Execute instruction pointed to by the current program counter
       // continuing until the machine state signifies a halt
@@ -180,6 +181,11 @@ export class AvmSimulator {
       const revertReason = reverted ? await revertReasonFromExplicitRevert(output, this.context) : undefined;
       const results = new AvmContractCallResult(reverted, output, machineState.gasLeft, revertReason);
       this.log.debug(`Context execution results: ${results.toString()}`);
+      const totalGasUsed: Gas = {
+        l2Gas: callStartGas.l2Gas - machineState.l2GasLeft,
+        daGas: callStartGas.daGas - machineState.daGasLeft,
+      };
+      this.log.debug(`Executed ${instrCounter} instructions and consumed ${totalGasUsed.l2Gas} L2 Gas`);
 
       this.tallyPrintFunction();
       // Return results for processing by calling context

package/src/avm/fixtures/index.ts

@@ -1,4 +1,4 @@
-import { TxHash, isNoirCallStackUnresolved } from '@aztec/circuit-types';
+import { isNoirCallStackUnresolved } from '@aztec/circuit-types';
 import { GasFees, GlobalVariables, MAX_L2_GAS_PER_TX_PUBLIC_PORTION } from '@aztec/circuits.js';
 import { type FunctionArtifact, FunctionSelector } from '@aztec/foundation/abi';
 import { AztecAddress } from '@aztec/foundation/aztec-address';
@@ -10,8 +10,9 @@ import { strict as assert } from 'assert';
 import { mock } from 'jest-mock-extended';
 import merge from 'lodash.merge';
 
-import { type WorldStateDB, resolveAssertionMessageFromRevertData, traverseCauseChain } from '../../index.js';
+import { resolveAssertionMessageFromRevertData, traverseCauseChain } from '../../common.js';
 import { type PublicSideEffectTraceInterface } from '../../public/side_effect_trace_interface.js';
+import { type WorldStateDB } from '../../server.js';
 import { AvmContext } from '../avm_context.js';
 import { AvmExecutionEnvironment } from '../avm_execution_environment.js';
 import { AvmMachineState } from '../avm_machine_state.js';
@@ -45,7 +46,7 @@ export function initPersistableStateManager(overrides?: {
   nullifiers?: NullifierManager;
   doMerkleOperations?: boolean;
   merkleTrees?: AvmEphemeralForest;
-  txHash?: TxHash;
+  firstNullifier?: Fr;
 }): AvmPersistableStateManager {
   const worldStateDB = overrides?.worldStateDB || mock<WorldStateDB>();
   return new AvmPersistableStateManager(
@@ -55,7 +56,7 @@ export function initPersistableStateManager(overrides?: {
     overrides?.nullifiers || new NullifierManager(worldStateDB),
     overrides?.doMerkleOperations || false,
     overrides?.merkleTrees || mock<AvmEphemeralForest>(),
-    overrides?.txHash || new TxHash(new Fr(27)),
+    overrides?.firstNullifier || new Fr(27),
   );
 }
 

package/src/avm/journal/journal.ts

@@ -1,4 +1,4 @@
-import { MerkleTreeId, type TxHash } from '@aztec/circuit-types';
+import { MerkleTreeId } from '@aztec/circuit-types';
 import {
   AztecAddress,
   CANONICAL_AUTH_REGISTRY_ADDRESS,
@@ -61,7 +61,7 @@ export class AvmPersistableStateManager {
     private readonly doMerkleOperations: boolean = false,
     /** Ephmeral forest for merkle tree operations */
     public merkleTrees: AvmEphemeralForest,
-    public readonly txHash: TxHash,
+    public readonly firstNullifier: Fr,
   ) {}
 
   /**
@@ -71,7 +71,7 @@ export class AvmPersistableStateManager {
     worldStateDB: WorldStateDB,
     trace: PublicSideEffectTraceInterface,
     doMerkleOperations: boolean = false,
-    txHash: TxHash,
+    firstNullifier: Fr,
   ) {
     const ephemeralForest = await AvmEphemeralForest.create(worldStateDB.getMerkleInterface());
     return new AvmPersistableStateManager(
@@ -81,7 +81,7 @@ export class AvmPersistableStateManager {
       /*nullifiers=*/ new NullifierManager(worldStateDB),
       /*doMerkleOperations=*/ doMerkleOperations,
       ephemeralForest,
-      txHash,
+      firstNullifier,
     );
   }
 
@@ -96,7 +96,7 @@ export class AvmPersistableStateManager {
       this.nullifiers.fork(),
       this.doMerkleOperations,
       this.merkleTrees.fork(),
-      this.txHash,
+      this.firstNullifier,
     );
   }
 
@@ -124,13 +124,14 @@ export class AvmPersistableStateManager {
     this.publicStorage.acceptAndMerge(forkedState.publicStorage);
     this.nullifiers.acceptAndMerge(forkedState.nullifiers);
     this.trace.merge(forkedState.trace, reverted);
-    if (!reverted) {
-      this.merkleTrees = forkedState.merkleTrees;
+    if (reverted) {
       if (this.doMerkleOperations) {
         this.log.debug(
           `Rolled back nullifier tree to root ${this.merkleTrees.treeMap.get(MerkleTreeId.NULLIFIER_TREE)!.getRoot()}`,
         );
       }
+    } else {
+      this.merkleTrees = forkedState.merkleTrees;
     }
   }
 
@@ -293,8 +294,7 @@ export class AvmPersistableStateManager {
    * @param noteHash - the non unique note hash to write
    */
   public writeSiloedNoteHash(noteHash: Fr): void {
-    const txHash = Fr.fromBuffer(this.txHash.toBuffer());
-    const nonce = computeNoteHashNonce(txHash, this.trace.getNoteHashCount());
+    const nonce = computeNoteHashNonce(this.firstNullifier, this.trace.getNoteHashCount());
     const uniqueNoteHash = computeUniqueNoteHash(nonce, noteHash);
 
     this.writeUniqueNoteHash(uniqueNoteHash);

package/src/avm/journal/nullifiers.ts

@@ -1,6 +1,6 @@
 import { Fr } from '@aztec/foundation/fields';
 
-import type { CommitmentsDB } from '../../index.js';
+import type { CommitmentsDB } from '../../server.js';
 
 /**
  * A class to manage new nullifier staging and existence checks during a contract call's AVM simulation.

package/src/avm/journal/public_storage.ts

@@ -1,7 +1,7 @@
 import { type AztecAddress } from '@aztec/circuits.js';
 import { Fr } from '@aztec/foundation/fields';
 
-import type { PublicStateDB } from '../../index.js';
+import type { PublicStateDB } from '../../server.js';
 
 type PublicStorageReadResult = {
   value: Fr;

package/src/avm/opcodes/memory.ts

@@ -190,7 +190,10 @@ export class CalldataCopy extends Instruction {
     const copySize = memory.get(copySizeOffset).toNumber();
     context.machineState.consumeGas(this.gasCost(copySize));
 
-    const transformedData = context.environment.calldata.slice(cdStart, cdStart + copySize).map(f => new Field(f));
+    // Values which are out-of-range of the calldata array will be set with Field(0);
+    const slice = context.environment.calldata.slice(cdStart, cdStart + copySize).map(f => new Field(f));
+    // slice has size = MIN(copySize, calldata.length - cdStart) as TS truncates out-of-range portion
+    const transformedData = [...slice, ...Array(copySize - slice.length).fill(new Field(0))];
 
     memory.setSlice(dstOffset, transformedData);
 
@@ -253,9 +256,10 @@ export class ReturndataCopy extends Instruction {
     const copySize = memory.get(copySizeOffset).toNumber();
     context.machineState.consumeGas(this.gasCost(copySize));
 
-    const transformedData = context.machineState.nestedReturndata
-      .slice(rdStart, rdStart + copySize)
-      .map(f => new Field(f));
+    // Values which are out-of-range of the returndata array will be set with Field(0);
+    const slice = context.machineState.nestedReturndata.slice(rdStart, rdStart + copySize).map(f => new Field(f));
+    // slice has size = MIN(copySize, returndata.length - rdStart) as TS truncates out-of-range portion
+    const transformedData = [...slice, ...Array(copySize - slice.length).fill(new Field(0))];
 
     memory.setSlice(dstOffset, transformedData);
 

package/src/client/client_execution_context.ts

@@ -6,7 +6,7 @@ import {
   Note,
   NoteAndSlot,
   type NoteStatus,
-  type PrivateExecutionResult,
+  type PrivateCallExecutionResult,
   PublicExecutionRequest,
   type UnencryptedL2Log,
 } from '@aztec/circuit-types';
@@ -26,7 +26,8 @@ import { Fr } from '@aztec/foundation/fields';
 import { createLogger } from '@aztec/foundation/log';
 
 import { type NoteData, toACVMWitness } from '../acvm/index.js';
-import { type PackedValuesCache } from '../common/packed_values_cache.js';
+import { type HashedValuesCache } from '../common/hashed_values_cache.js';
+import { type SimulationProvider } from '../server.js';
 import { type DBOracle } from './db_oracle.js';
 import { type ExecutionNoteCache } from './execution_note_cache.js';
 import { pickNotes } from './pick_notes.js';
@@ -57,7 +58,7 @@ export class ClientExecutionContext extends ViewDataOracle {
   private noteHashLeafIndexMap: Map<bigint, bigint> = new Map();
   private noteHashNullifierCounterMap: Map<number, number> = new Map();
   private contractClassLogs: CountedContractClassLog[] = [];
-  private nestedExecutions: PrivateExecutionResult[] = [];
+  private nestedExecutions: PrivateCallExecutionResult[] = [];
   private enqueuedPublicFunctionCalls: CountedPublicExecutionRequest[] = [];
   private publicTeardownFunctionCall: PublicExecutionRequest = PublicExecutionRequest.empty();
 
@@ -69,10 +70,11 @@ export class ClientExecutionContext extends ViewDataOracle {
     protected readonly historicalHeader: BlockHeader,
     /** List of transient auth witnesses to be used during this simulation */
     authWitnesses: AuthWitness[],
-    private readonly packedValuesCache: PackedValuesCache,
+    private readonly executionCache: HashedValuesCache,
     private readonly noteCache: ExecutionNoteCache,
     db: DBOracle,
     private node: AztecNode,
+    private provider: SimulationProvider,
     protected sideEffectCounter: number = 0,
     log = createLogger('simulator:client_execution_context'),
     scopes?: AztecAddress[],
@@ -90,7 +92,7 @@ export class ClientExecutionContext extends ViewDataOracle {
   public getInitialWitness(abi: FunctionAbi) {
     const argumentsSize = countArgumentsSize(abi);
 
-    const args = this.packedValuesCache.unpack(this.argsHash);
+    const args = this.executionCache.getPreimage(this.argsHash);
 
     if (args.length !== argumentsSize) {
       throw new Error('Invalid arguments size');
@@ -159,27 +161,29 @@ export class ClientExecutionContext extends ViewDataOracle {
   }
 
   /**
-   * Pack the given array of arguments.
-   * @param args - Arguments to pack
+   * Store values in the execution cache.
+   * @param values - Values to store.
    */
-  public override packArgumentsArray(args: Fr[]): Promise<Fr> {
-    return Promise.resolve(this.packedValuesCache.pack(args));
+  public override storeArrayInExecutionCache(args: Fr[]): Promise<Fr> {
+    return Promise.resolve(this.executionCache.store(args));
   }
 
   /**
-   * Pack the given returns.
-   * @param returns - Returns to pack
+   * Store values in the execution cache.
+   * @param values - Values to store.
+   * @returns The hash of the values.
    */
-  public override packReturns(returns: Fr[]): Promise<Fr> {
-    return Promise.resolve(this.packedValuesCache.pack(returns));
+  public override storeInExecutionCache(values: Fr[]): Promise<Fr> {
+    return Promise.resolve(this.executionCache.store(values));
   }
 
   /**
-   * Unpack the given returns.
-   * @param returnsHash - Returns hash to unpack
+   * Gets values from the execution cache.
+   * @param hash - Hash of the values.
+   * @returns The values.
    */
-  public override unpackReturns(returnsHash: Fr): Promise<Fr[]> {
-    return Promise.resolve(this.packedValuesCache.unpack(returnsHash));
+  public override loadFromExecutionCache(hash: Fr): Promise<Fr[]> {
+    return Promise.resolve(this.executionCache.getPreimage(hash));
   }
 
   /**
@@ -307,6 +311,17 @@ export class ClientExecutionContext extends ViewDataOracle {
     return Promise.resolve();
   }
 
+  /**
+   * Adding a siloed nullifier into the current set of all pending nullifiers created
+   * within the current transaction/execution.
+   * @param innerNullifier - The pending nullifier to add in the list (not yet siloed by contract address).
+   * @param noteHash - A hash of the new note.
+   */
+  public override notifyCreatedNullifier(innerNullifier: Fr) {
+    this.noteCache.nullifierCreated(this.callContext.contractAddress, innerNullifier);
+    return Promise.resolve();
+  }
+
   /**
    * Emit a contract class unencrypted log.
    * This fn exists because sha hashing the preimage
@@ -323,7 +338,7 @@ export class ClientExecutionContext extends ViewDataOracle {
     return Fr.fromBuffer(log.hash());
   }
 
-  #checkValidStaticCall(childExecutionResult: PrivateExecutionResult) {
+  #checkValidStaticCall(childExecutionResult: PrivateCallExecutionResult) {
     if (
       childExecutionResult.publicInputs.noteHashes.some(item => !item.isEmpty()) ||
       childExecutionResult.publicInputs.nullifiers.some(item => !item.isEmpty()) ||
@@ -339,7 +354,7 @@ export class ClientExecutionContext extends ViewDataOracle {
    * Calls a private function as a nested execution.
    * @param targetContractAddress - The address of the contract to call.
    * @param functionSelector - The function selector of the function to call.
-   * @param argsHash - The packed arguments to pass to the function.
+   * @param argsHash - The arguments hash to pass to the function.
    * @param sideEffectCounter - The side effect counter at the start of the call.
    * @param isStaticCall - Whether the call is a static call.
    * @returns The execution result.
@@ -369,16 +384,18 @@ export class ClientExecutionContext extends ViewDataOracle {
       derivedCallContext,
       this.historicalHeader,
       this.authWitnesses,
-      this.packedValuesCache,
+      this.executionCache,
       this.noteCache,
       this.db,
       this.node,
+      this.provider,
       sideEffectCounter,
       this.log,
       this.scopes,
     );
 
     const childExecutionResult = await executePrivateFunction(
+      this.provider,
       context,
       targetArtifact,
       targetContractAddress,
@@ -402,7 +419,7 @@ export class ClientExecutionContext extends ViewDataOracle {
    * Creates a PublicExecutionRequest object representing the request to call a public function.
    * @param targetContractAddress - The address of the contract to call.
    * @param functionSelector - The function selector of the function to call.
-   * @param argsHash - The packed arguments to pass to the function.
+   * @param argsHash - The arguments hash to pass to the function.
    * @param sideEffectCounter - The side effect counter at the start of the call.
    * @param isStaticCall - Whether the call is a static call.
    * @returns The public call stack item with the request information.
@@ -417,7 +434,7 @@ export class ClientExecutionContext extends ViewDataOracle {
   ) {
     const targetArtifact = await this.db.getFunctionArtifact(targetContractAddress, functionSelector);
     const derivedCallContext = this.deriveCallContext(targetContractAddress, targetArtifact, isStaticCall);
-    const args = this.packedValuesCache.unpack(argsHash);
+    const args = this.executionCache.getPreimage(argsHash);
 
     this.log.verbose(
       `Created ${callType} public execution request to ${targetArtifact.name}@${targetContractAddress}`,
@@ -448,7 +465,7 @@ export class ClientExecutionContext extends ViewDataOracle {
    * of the execution are empty.
    * @param targetContractAddress - The address of the contract to call.
    * @param functionSelector - The function selector of the function to call.
-   * @param argsHash - The packed arguments to pass to the function.
+   * @param argsHash - The arguments hash to pass to the function.
    * @param sideEffectCounter - The side effect counter at the start of the call.
    * @param isStaticCall - Whether the call is a static call.
    * @returns The public call stack item with the request information.
@@ -462,13 +479,13 @@ export class ClientExecutionContext extends ViewDataOracle {
   ): Promise<Fr> {
     // TODO(https://github.com/AztecProtocol/aztec-packages/issues/8985): Fix this.
     // WARNING: This is insecure and should be temporary!
-    // The oracle repacks the arguments and returns a new args_hash.
+    // The oracle re-hashes the arguments and returns a new args_hash.
     // new_args = [selector, ...old_args], so as to make it suitable to call the public dispatch function.
     // We don't validate or compute it in the circuit because a) it's harder to do with slices, and
     // b) this is only temporary.
-    const newArgsHash = this.packedValuesCache.pack([
+    const newArgsHash = this.executionCache.store([
       functionSelector.toField(),
-      ...this.packedValuesCache.unpack(argsHash),
+      ...this.executionCache.getPreimage(argsHash),
     ]);
     await this.createPublicExecutionRequest(
       'enqueued',
@@ -487,7 +504,7 @@ export class ClientExecutionContext extends ViewDataOracle {
    * of the execution are empty.
    * @param targetContractAddress - The address of the contract to call.
    * @param functionSelector - The function selector of the function to call.
-   * @param argsHash - The packed arguments to pass to the function.
+   * @param argsHash - The arguments hash to pass to the function.
    * @param sideEffectCounter - The side effect counter at the start of the call.
    * @param isStaticCall - Whether the call is a static call.
    * @returns The public call stack item with the request information.
@@ -501,13 +518,13 @@ export class ClientExecutionContext extends ViewDataOracle {
   ): Promise<Fr> {
     // TODO(https://github.com/AztecProtocol/aztec-packages/issues/8985): Fix this.
     // WARNING: This is insecure and should be temporary!
-    // The oracle repacks the arguments and returns a new args_hash.
+    // The oracle rehashes the arguments and returns a new args_hash.
     // new_args = [selector, ...old_args], so as to make it suitable to call the public dispatch function.
     // We don't validate or compute it in the circuit because a) it's harder to do with slices, and
     // b) this is only temporary.
-    const newArgsHash = this.packedValuesCache.pack([
+    const newArgsHash = this.executionCache.store([
       functionSelector.toField(),
-      ...this.packedValuesCache.unpack(argsHash),
+      ...this.executionCache.getPreimage(argsHash),
     ]);
     await this.createPublicExecutionRequest(
       'teardown',

package/src/client/db_oracle.ts

@@ -1,6 +1,5 @@
 import {
   type L2Block,
-  type L2BlockNumber,
   type MerkleTreeId,
   type NoteStatus,
   type NullifierMembershipWitness,
@@ -141,22 +140,13 @@ export interface DBOracle extends CommitmentsDB {
   getBlockHeader(): Promise<BlockHeader>;
 
   /**
-   * Fetch the index of the leaf in the respective tree
-   * @param blockNumber - The block number at which to get the leaf index.
-   * @param treeId - The id of the tree to search.
-   * @param leafValue - The leaf value buffer.
-   * @returns - The index of the leaf. Undefined if it does not exist in the tree.
+   * Fetches the index and sibling path of a leaf at a given block from a given tree.
+   * @param blockNumber - The block number at which to get the membership witness.
+   * @param treeId - Id of the tree to get the sibling path from.
+   * @param leafValue - The leaf value
+   * @returns The index and sibling path concatenated [index, sibling_path]
    */
-  findLeafIndex(blockNumber: L2BlockNumber, treeId: MerkleTreeId, leafValue: Fr): Promise<bigint | undefined>;
-
-  /**
-   * Fetch the sibling path of the leaf in the respective tree
-   * @param blockNumber - The block number at which to get the sibling path.
-   * @param treeId - The id of the tree to search.
-   * @param leafIndex - The index of the leaf.
-   * @returns - The sibling path of the leaf.
-   */
-  getSiblingPath(blockNumber: number, treeId: MerkleTreeId, leafIndex: bigint): Promise<Fr[]>;
+  getMembershipWitness(blockNumber: number, treeId: MerkleTreeId, leafValue: Fr): Promise<Fr[]>;
 
   /**
    * Returns a nullifier membership witness for a given nullifier at a given block.
@@ -224,7 +214,7 @@ export interface DBOracle extends CommitmentsDB {
   ): Promise<void>;
 
   /**
-   * Synchronizes the logs tagged with the recipient's address and all the senders in the addressbook.
+   * Synchronizes the logs tagged with the recipient's address and all the senders in the address book.
    * Returns the unsynched logs and updates the indexes of the secrets used to tag them until there are no more logs to sync.
    * @param contractAddress - The address of the contract that the logs are tagged for
    * @param recipient - The address of the recipient
@@ -243,8 +233,69 @@ export interface DBOracle extends CommitmentsDB {
    */
   processTaggedLogs(logs: TxScopedL2Log[], recipient: AztecAddress): Promise<void>;
 
+  /**
+   * Delivers the preimage and metadata of a committed note so that it can be later requested via the `getNotes`
+   * oracle.
+   *
+   * @param contractAddress - The address of the contract that created the note (i.e. the siloing contract)
+   * @param storageSlot - The storage slot of the note - used for indexing in `getNotes`
+   * @param nonce - The nonce of the note used by the kernel to compute the unique note hash
+   * @param content - The note's content: this is the primary item to return in `getNotes`
+   * @param noteHash - The non-unique non-siloed note hash
+   * @param nullifier - The inner (non-siloed) note nullifier
+   * @param txHash - The transaction in which the note was added to the note hash tree
+   * @param recipient - The account that discovered the note
+   */
+  deliverNote(
+    contractAddress: AztecAddress,
+    storageSlot: Fr,
+    nonce: Fr,
+    content: Fr[],
+    noteHash: Fr,
+    nullifier: Fr,
+    txHash: Fr,
+    recipient: AztecAddress,
+  ): Promise<void>;
+
   /**
    * Removes all of a contract's notes that have been nullified from the note database.
    */
   removeNullifiedNotes(contractAddress: AztecAddress): Promise<void>;
+
+  /**
+   * Stores arbitrary information in a per-contract non-volatile database, which can later be retrieved with `dbLoad`.
+   * * If data was already stored at this slot, it is overwrriten.
+   * @param contractAddress - The contract address to scope the data under.
+   * @param slot - The slot in the database in which to store the value. Slots need not be contiguous.
+   * @param values - The data to store.
+   */
+  dbStore(contractAddress: AztecAddress, slot: Fr, values: Fr[]): Promise<void>;
+
+  /**
+   * Returns data previously stored via `dbStore` in the per-contract non-volatile database.
+   * @param contractAddress - The contract address under which the data is scoped.
+   * @param slot - The slot in the database to read.
+   * @returns The stored data or `null` if no data is stored under the slot.
+   */
+  dbLoad(contractAddress: AztecAddress, slot: Fr): Promise<Fr[] | null>;
+
+  /**
+   * Deletes data in the per-contract non-volatile database. Does nothing if no data was present.
+   * @param contractAddress - The contract address under which the data is scoped.
+   * @param slot - The slot in the database to delete.
+   */
+  dbDelete(contractAddress: AztecAddress, slot: Fr): Promise<void>;
+
+  /**
+   * Copies a number of contiguous entries in the per-contract non-volatile database. This allows for efficient data
+   * structures by avoiding repeated calls to `dbLoad` and `dbStore`.
+   * Supports overlapping source and destination regions (which will result in the overlapped source values being
+   * overwritten). All copied slots must exist in the database (i.e. have been stored and not deleted)
+   *
+   * @param contractAddress - The contract address under which the data is scoped.
+   * @param srcSlot - The first slot to copy from.
+   * @param dstSlot - The first slot to copy to.
+   * @param numEntries - The number of entries to copy.
+   */
+  dbCopy(contractAddress: AztecAddress, srcSlot: Fr, dstSlot: Fr, numEntries: number): Promise<void>;
 }