@aztec/pxe 0.0.1-commit.29c6b1a3 → 0.0.1-commit.2c85e299c

package/src/contract_function_simulator/oracle/utility_execution_oracle.ts

@@ -3,29 +3,30 @@ import type { BlockNumber } from '@aztec/foundation/branded-types';
 import { Aes128 } from '@aztec/foundation/crypto/aes128';
 import { Fr } from '@aztec/foundation/curves/bn254';
 import { Point } from '@aztec/foundation/curves/grumpkin';
-import { LogLevels, applyStringFormatting, createLogger } from '@aztec/foundation/log';
+import { LogLevels, type Logger, createLogger } from '@aztec/foundation/log';
 import type { MembershipWitness } from '@aztec/foundation/trees';
 import type { KeyStore } from '@aztec/key-store';
 import type { AuthWitness } from '@aztec/stdlib/auth-witness';
 import { AztecAddress } from '@aztec/stdlib/aztec-address';
 import { BlockHash } from '@aztec/stdlib/block';
-import type { CompleteAddress, ContractInstance } from '@aztec/stdlib/contract';
+import type { CompleteAddress, ContractInstance, PartialAddress } from '@aztec/stdlib/contract';
 import { siloNullifier } from '@aztec/stdlib/hash';
 import type { AztecNode } from '@aztec/stdlib/interfaces/server';
 import type { KeyValidationRequest } from '@aztec/stdlib/kernel';
-import { computeAddressSecret } from '@aztec/stdlib/keys';
+import { type PublicKeys, computeAddressSecret } from '@aztec/stdlib/keys';
 import { deriveEcdhSharedSecret } from '@aztec/stdlib/logs';
 import { getNonNullifiedL1ToL2MessageWitness } from '@aztec/stdlib/messaging';
 import type { NoteStatus } from '@aztec/stdlib/note';
 import { MerkleTreeId, type NullifierMembershipWitness, PublicDataWitness } from '@aztec/stdlib/trees';
 import type { BlockHeader, Capsule } from '@aztec/stdlib/tx';
 
+import type { AccessScopes } from '../../access_scopes.js';
+import { createContractLogger, logContractMessage } from '../../contract_logging.js';
 import { EventService } from '../../events/event_service.js';
 import { LogService } from '../../logs/log_service.js';
 import { NoteService } from '../../notes/note_service.js';
 import { ORACLE_VERSION } from '../../oracle_version.js';
 import type { AddressStore } from '../../storage/address_store/address_store.js';
-import type { AnchorBlockStore } from '../../storage/anchor_block_store/anchor_block_store.js';
 import type { CapsuleStore } from '../../storage/capsule_store/capsule_store.js';
 import type { ContractStore } from '../../storage/contract_store/contract_store.js';
 import type { NoteStore } from '../../storage/note_store/note_store.js';
@@ -41,6 +42,27 @@ import { pickNotes } from '../pick_notes.js';
 import type { IMiscOracle, IUtilityExecutionOracle, NoteData } from './interfaces.js';
 import { MessageLoadOracleInputs } from './message_load_oracle_inputs.js';
 
+/** Args for UtilityExecutionOracle constructor. */
+export type UtilityExecutionOracleArgs = {
+  contractAddress: AztecAddress;
+  /** List of transient auth witnesses to be used during this simulation */
+  authWitnesses: AuthWitness[];
+  capsules: Capsule[]; // TODO(#12425): Rename to transientCapsules
+  anchorBlockHeader: BlockHeader;
+  contractStore: ContractStore;
+  noteStore: NoteStore;
+  keyStore: KeyStore;
+  addressStore: AddressStore;
+  aztecNode: AztecNode;
+  recipientTaggingStore: RecipientTaggingStore;
+  senderAddressBookStore: SenderAddressBookStore;
+  capsuleStore: CapsuleStore;
+  privateEventStore: PrivateEventStore;
+  jobId: string;
+  log?: ReturnType<typeof createLogger>;
+  scopes: AccessScopes;
+};
+
 /**
  * The oracle for an execution of utility contract functions.
  */
@@ -48,40 +70,55 @@ export class UtilityExecutionOracle implements IMiscOracle, IUtilityExecutionOra
   isMisc = true as const;
   isUtility = true as const;
 
-  private aztecNrDebugLog = createLogger('aztec-nr:debug_log');
-
-  constructor(
-    protected readonly contractAddress: AztecAddress,
-    /** List of transient auth witnesses to be used during this simulation */
-    protected readonly authWitnesses: AuthWitness[],
-    protected readonly capsules: Capsule[], // TODO(#12425): Rename to transientCapsules
-    protected readonly anchorBlockHeader: BlockHeader,
-    protected readonly contractStore: ContractStore,
-    protected readonly noteStore: NoteStore,
-    protected readonly keyStore: KeyStore,
-    protected readonly addressStore: AddressStore,
-    protected readonly aztecNode: AztecNode,
-    protected readonly anchorBlockStore: AnchorBlockStore,
-    protected readonly recipientTaggingStore: RecipientTaggingStore,
-    protected readonly senderAddressBookStore: SenderAddressBookStore,
-    protected readonly capsuleStore: CapsuleStore,
-    protected readonly privateEventStore: PrivateEventStore,
-    protected readonly jobId: string,
-    protected log = createLogger('simulator:client_view_context'),
-    protected readonly scopes?: AztecAddress[],
-  ) {}
-
-  public utilityAssertCompatibleOracleVersion(version: number): void {
+  private contractLogger: Logger | undefined;
+
+  protected readonly contractAddress: AztecAddress;
+  protected readonly authWitnesses: AuthWitness[];
+  protected readonly capsules: Capsule[];
+  protected readonly anchorBlockHeader: BlockHeader;
+  protected readonly contractStore: ContractStore;
+  protected readonly noteStore: NoteStore;
+  protected readonly keyStore: KeyStore;
+  protected readonly addressStore: AddressStore;
+  protected readonly aztecNode: AztecNode;
+  protected readonly recipientTaggingStore: RecipientTaggingStore;
+  protected readonly senderAddressBookStore: SenderAddressBookStore;
+  protected readonly capsuleStore: CapsuleStore;
+  protected readonly privateEventStore: PrivateEventStore;
+  protected readonly jobId: string;
+  protected logger: ReturnType<typeof createLogger>;
+  protected readonly scopes: AccessScopes;
+
+  constructor(args: UtilityExecutionOracleArgs) {
+    this.contractAddress = args.contractAddress;
+    this.authWitnesses = args.authWitnesses;
+    this.capsules = args.capsules;
+    this.anchorBlockHeader = args.anchorBlockHeader;
+    this.contractStore = args.contractStore;
+    this.noteStore = args.noteStore;
+    this.keyStore = args.keyStore;
+    this.addressStore = args.addressStore;
+    this.aztecNode = args.aztecNode;
+    this.recipientTaggingStore = args.recipientTaggingStore;
+    this.senderAddressBookStore = args.senderAddressBookStore;
+    this.capsuleStore = args.capsuleStore;
+    this.privateEventStore = args.privateEventStore;
+    this.jobId = args.jobId;
+    this.logger = args.log ?? createLogger('simulator:client_view_context');
+    this.scopes = args.scopes;
+  }
+
+  public assertCompatibleOracleVersion(version: number): void {
     if (version !== ORACLE_VERSION) {
       throw new Error(`Incompatible oracle version. Expected version ${ORACLE_VERSION}, got ${version}.`);
     }
   }
 
-  public utilityGetRandomField(): Fr {
+  public getRandomField(): Fr {
     return Fr.random();
   }
 
-  public utilityGetUtilityContext(): UtilityContext {
+  public getUtilityContext(): UtilityContext {
     return new UtilityContext(this.anchorBlockHeader, this.contractAddress);
   }
 
@@ -90,35 +127,54 @@ export class UtilityExecutionOracle implements IMiscOracle, IUtilityExecutionOra
    * @param pkMHash - The master public key hash.
    * @returns A Promise that resolves to nullifier keys.
    * @throws If the keys are not registered in the key store.
+   * @throws If scopes are defined and the account is not in the scopes.
    */
-  public utilityGetKeyValidationRequest(pkMHash: Fr): Promise<KeyValidationRequest> {
+  public async getKeyValidationRequest(pkMHash: Fr): Promise<KeyValidationRequest> {
+    // If scopes are defined, check that the key belongs to an account in the scopes.
+    if (this.scopes !== 'ALL_SCOPES' && this.scopes.length > 0) {
+      let hasAccess = false;
+      for (let i = 0; i < this.scopes.length && !hasAccess; i++) {
+        if (await this.keyStore.accountHasKey(this.scopes[i], pkMHash)) {
+          hasAccess = true;
+        }
+      }
+      if (!hasAccess) {
+        throw new Error(`Key validation request denied: no scoped account has a key with hash ${pkMHash.toString()}.`);
+      }
+    }
     return this.keyStore.getKeyValidationRequest(pkMHash, this.contractAddress);
   }
 
   /**
    * Fetches the index and sibling path of a leaf at a given block from the note hash tree.
-   * @param blockHash - The block hash at which to get the membership witness.
-   * @param leafValue - The leaf value
+   * @param anchorBlockHash - The hash of a block that contains the note hash tree root in which to find the membership
+   * witness.
+   * @param noteHash - The note hash to find in the note hash tree.
    * @returns The membership witness containing the leaf index and sibling path
    */
-  public utilityGetNoteHashMembershipWitness(
-    blockHash: BlockHash,
-    leafValue: Fr,
+  public getNoteHashMembershipWitness(
+    anchorBlockHash: BlockHash,
+    noteHash: Fr,
   ): Promise<MembershipWitness<typeof NOTE_HASH_TREE_HEIGHT> | undefined> {
-    return this.aztecNode.getNoteHashMembershipWitness(blockHash, leafValue);
+    return this.aztecNode.getNoteHashMembershipWitness(anchorBlockHash, noteHash);
   }
 
   /**
-   * Fetches the index and sibling path of a leaf at a given block from the archive tree.
-   * @param blockHash - The block hash at which to get the membership witness.
-   * @param leafValue - The leaf value
+   * Fetches the index and sibling path of a block hash in the archive tree.
+   *
+   * Block hashes are the leaves of the archive tree. Each time a new block is added to the chain,
+   * its block hash is appended as a new leaf to the archive tree.
+   *
+   * @param anchorBlockHash - The hash of a block that contains the archive tree root in which to find the membership
+   * witness.
+   * @param blockHash - The block hash to find in the archive tree.
    * @returns The membership witness containing the leaf index and sibling path
    */
-  public utilityGetArchiveMembershipWitness(
+  public getBlockHashMembershipWitness(
+    anchorBlockHash: BlockHash,
     blockHash: BlockHash,
-    leafValue: Fr,
   ): Promise<MembershipWitness<typeof ARCHIVE_HEIGHT> | undefined> {
-    return this.aztecNode.getArchiveMembershipWitness(blockHash, leafValue);
+    return this.aztecNode.getBlockHashMembershipWitness(anchorBlockHash, blockHash);
   }
 
   /**
@@ -127,7 +183,7 @@ export class UtilityExecutionOracle implements IMiscOracle, IUtilityExecutionOra
    * @param nullifier - Nullifier we try to find witness for.
    * @returns The nullifier membership witness (if found).
    */
-  public utilityGetNullifierMembershipWitness(
+  public getNullifierMembershipWitness(
     blockHash: BlockHash,
     nullifier: Fr,
   ): Promise<NullifierMembershipWitness | undefined> {
@@ -143,7 +199,7 @@ export class UtilityExecutionOracle implements IMiscOracle, IUtilityExecutionOra
    * list structure" of leaves and proving that a lower nullifier is pointing to a bigger next value than the nullifier
    * we are trying to prove non-inclusion for.
    */
-  public utilityGetLowNullifierMembershipWitness(
+  public getLowNullifierMembershipWitness(
     blockHash: BlockHash,
     nullifier: Fr,
   ): Promise<NullifierMembershipWitness | undefined> {
@@ -156,7 +212,7 @@ export class UtilityExecutionOracle implements IMiscOracle, IUtilityExecutionOra
    * @param leafSlot - The slot of the public data tree to get the witness for.
    * @returns - The witness
    */
-  public utilityGetPublicDataWitness(blockHash: BlockHash, leafSlot: Fr): Promise<PublicDataWitness | undefined> {
+  public getPublicDataWitness(blockHash: BlockHash, leafSlot: Fr): Promise<PublicDataWitness | undefined> {
     return this.aztecNode.getPublicDataWitness(blockHash, leafSlot);
   }
 
@@ -165,8 +221,8 @@ export class UtilityExecutionOracle implements IMiscOracle, IUtilityExecutionOra
    * @param blockNumber - The number of a block of which to get the block header.
    * @returns Block extracted from a block with block number `blockNumber`.
    */
-  public async utilityGetBlockHeader(blockNumber: BlockNumber): Promise<BlockHeader | undefined> {
-    const anchorBlockNumber = (await this.anchorBlockStore.getBlockHeader()).getBlockNumber();
+  public async getBlockHeader(blockNumber: BlockNumber): Promise<BlockHeader | undefined> {
+    const anchorBlockNumber = this.anchorBlockHeader.getBlockNumber();
     if (blockNumber > anchorBlockNumber) {
       throw new Error(`Block number ${blockNumber} is higher than current block ${anchorBlockNumber}`);
     }
@@ -176,16 +232,21 @@ export class UtilityExecutionOracle implements IMiscOracle, IUtilityExecutionOra
   }
 
   /**
-   * Retrieve the complete address associated to a given address.
+   * Retrieve the public keys and partial address associated to a given address.
    * @param account - The account address.
-   * @returns A complete address associated with the input address.
-   * @throws An error if the account is not registered in the database.
+   * @returns The public keys and partial address, or `undefined` if the account is not registered.
    */
-  public utilityGetPublicKeysAndPartialAddress(account: AztecAddress): Promise<CompleteAddress> {
-    return this.getCompleteAddress(account);
+  public async tryGetPublicKeysAndPartialAddress(
+    account: AztecAddress,
+  ): Promise<{ publicKeys: PublicKeys; partialAddress: PartialAddress } | undefined> {
+    const completeAddress = await this.addressStore.getCompleteAddress(account);
+    if (!completeAddress) {
+      return undefined;
+    }
+    return { publicKeys: completeAddress.publicKeys, partialAddress: completeAddress.partialAddress };
   }
 
-  protected async getCompleteAddress(account: AztecAddress): Promise<CompleteAddress> {
+  protected async getCompleteAddressOrFail(account: AztecAddress): Promise<CompleteAddress> {
     const completeAddress = await this.addressStore.getCompleteAddress(account);
     if (!completeAddress) {
       throw new Error(
@@ -201,11 +262,7 @@ export class UtilityExecutionOracle implements IMiscOracle, IUtilityExecutionOra
    * @param address - Address.
    * @returns A contract instance.
    */
-  public utilityGetContractInstance(address: AztecAddress): Promise<ContractInstance> {
-    return this.getContractInstance(address);
-  }
-
-  protected async getContractInstance(address: AztecAddress): Promise<ContractInstance> {
+  public async getContractInstance(address: AztecAddress): Promise<ContractInstance> {
     const instance = await this.contractStore.getContractInstance(address);
     if (!instance) {
       throw new Error(`No contract instance found for address ${address.toString()}`);
@@ -219,7 +276,7 @@ export class UtilityExecutionOracle implements IMiscOracle, IUtilityExecutionOra
    * @param messageHash - Hash of the message to authenticate.
    * @returns Authentication witness for the requested message hash.
    */
-  public utilityGetAuthWitness(messageHash: Fr): Promise<Fr[] | undefined> {
+  public getAuthWitness(messageHash: Fr): Promise<Fr[] | undefined> {
     return Promise.resolve(this.authWitnesses.find(w => w.requestHash.equals(messageHash))?.witness);
   }
 
@@ -245,7 +302,7 @@ export class UtilityExecutionOracle implements IMiscOracle, IUtilityExecutionOra
    * @param status - The status of notes to fetch.
    * @returns Array of note data.
    */
-  public async utilityGetNotes(
+  public async getNotes(
     owner: AztecAddress | undefined,
     storageSlot: Fr,
     numSelects: number,
@@ -262,7 +319,7 @@ export class UtilityExecutionOracle implements IMiscOracle, IUtilityExecutionOra
     offset: number,
     status: NoteStatus,
   ): Promise<NoteData[]> {
-    const noteService = new NoteService(this.noteStore, this.aztecNode, this.anchorBlockStore, this.jobId);
+    const noteService = new NoteService(this.noteStore, this.aztecNode, this.anchorBlockHeader, this.jobId);
 
     const dbNotes = await noteService.getNotes(this.contractAddress, owner, storageSlot, status, this.scopes);
     return pickNotes<NoteData>(dbNotes, {
@@ -285,9 +342,14 @@ export class UtilityExecutionOracle implements IMiscOracle, IUtilityExecutionOra
    * @param innerNullifier - The inner nullifier.
    * @returns A boolean indicating whether the nullifier exists in the tree or not.
    */
-  public async utilityCheckNullifierExists(innerNullifier: Fr) {
-    const nullifier = await siloNullifier(this.contractAddress, innerNullifier!);
-    const [leafIndex] = await this.aztecNode.findLeavesIndexes('latest', MerkleTreeId.NULLIFIER_TREE, [nullifier]);
+  public async checkNullifierExists(innerNullifier: Fr) {
+    const [nullifier, anchorBlockHash] = await Promise.all([
+      siloNullifier(this.contractAddress, innerNullifier!),
+      this.anchorBlockHeader.hash(),
+    ]);
+    const [leafIndex] = await this.aztecNode.findLeavesIndexes(anchorBlockHash, MerkleTreeId.NULLIFIER_TREE, [
+      nullifier,
+    ]);
     return leafIndex?.data !== undefined;
   }
 
@@ -299,7 +361,7 @@ export class UtilityExecutionOracle implements IMiscOracle, IUtilityExecutionOra
    * @dev Contract address and secret are only used to compute the nullifier to get non-nullified messages
    * @returns The l1 to l2 membership witness (index of message in the tree and sibling path).
    */
-  public async utilityGetL1ToL2MembershipWitness(contractAddress: AztecAddress, messageHash: Fr, secret: Fr) {
+  public async getL1ToL2MembershipWitness(contractAddress: AztecAddress, messageHash: Fr, secret: Fr) {
     const [messageIndex, siblingPath] = await getNonNullifiedL1ToL2MessageWitness(
       this.aztecNode,
       contractAddress,
@@ -317,7 +379,7 @@ export class UtilityExecutionOracle implements IMiscOracle, IUtilityExecutionOra
    * @param startStorageSlot - The starting storage slot.
    * @param numberOfElements - Number of elements to read from the starting storage slot.
    */
-  public async utilityStorageRead(
+  public async storageRead(
     blockHash: BlockHash,
     contractAddress: AztecAddress,
     startStorageSlot: Fr,
@@ -331,43 +393,51 @@ export class UtilityExecutionOracle implements IMiscOracle, IUtilityExecutionOra
       slots.map(storageSlot => this.aztecNode.getPublicStorageAt(blockHash, contractAddress, storageSlot)),
     );
 
-    this.log.debug(
+    this.logger.debug(
       `Oracle storage read: slots=[${slots.map(slot => slot.toString()).join(', ')}] address=${contractAddress.toString()} values=[${values.join(', ')}]`,
     );
 
     return values;
   }
 
-  public utilityDebugLog(level: number, message: string, fields: Fr[]): void {
+  /**
+   * Returns a per-contract logger whose output is prefixed with `contract_log::<name>(<addrAbbrev>)`.
+   */
+  async #getContractLogger(): Promise<Logger> {
+    if (!this.contractLogger) {
+      // Purpose of instanceId is to distinguish logs from different instances of the same component. It makes sense
+      // to re-use jobId as instanceId here as executions of different PXE jobs are isolated.
+      this.contractLogger = await createContractLogger(
+        this.contractAddress,
+        addr => this.contractStore.getDebugContractName(addr),
+        { instanceId: this.jobId },
+      );
+    }
+    return this.contractLogger;
+  }
+
+  public async log(level: number, message: string, fields: Fr[]): Promise<void> {
     if (!LogLevels[level]) {
-      throw new Error(`Invalid debug log level: ${level}`);
+      throw new Error(`Invalid log level: ${level}`);
     }
-    const levelName = LogLevels[level];
-    this.aztecNrDebugLog[levelName](`${applyStringFormatting(message, fields)}`);
+    const logger = await this.#getContractLogger();
+    logContractMessage(logger, LogLevels[level], message, fields);
   }
 
-  public async utilityFetchTaggedLogs(pendingTaggedLogArrayBaseSlot: Fr) {
+  public async fetchTaggedLogs(pendingTaggedLogArrayBaseSlot: Fr) {
     const logService = new LogService(
       this.aztecNode,
-      this.anchorBlockStore,
+      this.anchorBlockHeader,
       this.keyStore,
       this.capsuleStore,
       this.recipientTaggingStore,
       this.senderAddressBookStore,
       this.addressStore,
       this.jobId,
+      this.logger.getBindings(),
     );
 
-    const noteService = new NoteService(this.noteStore, this.aztecNode, this.anchorBlockStore, this.jobId);
-
-    // It is acceptable to run the following operations in parallel for several reasons:
-    // 1. syncTaggedLogs does not write to the note store — it only stores the pending tagged logs in a capsule array,
-    //    which is then processed in Noir after this handler returns.
-    // 2. Even if syncTaggedLogs did write to the note store, it would not cause inconsistent state.
-    await Promise.all([
-      logService.syncTaggedLogs(this.contractAddress, pendingTaggedLogArrayBaseSlot, this.scopes),
-      noteService.syncNoteNullifiers(this.contractAddress),
-    ]);
+    await logService.fetchTaggedLogs(this.contractAddress, pendingTaggedLogArrayBaseSlot, this.scopes);
   }
 
   /**
@@ -380,7 +450,7 @@ export class UtilityExecutionOracle implements IMiscOracle, IUtilityExecutionOra
    * @param noteValidationRequestsArrayBaseSlot - The base slot of capsule array containing note validation requests.
    * @param eventValidationRequestsArrayBaseSlot - The base slot of capsule array containing event validation requests.
    */
-  public async utilityValidateAndStoreEnqueuedNotesAndEvents(
+  public async validateAndStoreEnqueuedNotesAndEvents(
     contractAddress: AztecAddress,
     noteValidationRequestsArrayBaseSlot: Fr,
     eventValidationRequestsArrayBaseSlot: Fr,
@@ -400,7 +470,7 @@ export class UtilityExecutionOracle implements IMiscOracle, IUtilityExecutionOra
       await this.capsuleStore.readCapsuleArray(contractAddress, eventValidationRequestsArrayBaseSlot, this.jobId)
     ).map(EventValidationRequest.fromFields);
 
-    const noteService = new NoteService(this.noteStore, this.aztecNode, this.anchorBlockStore, this.jobId);
+    const noteService = new NoteService(this.noteStore, this.aztecNode, this.anchorBlockHeader, this.jobId);
     const noteStorePromises = noteValidationRequests.map(request =>
       noteService.validateAndStoreNote(
         request.contractAddress,
@@ -416,7 +486,7 @@ export class UtilityExecutionOracle implements IMiscOracle, IUtilityExecutionOra
       ),
     );
 
-    const eventService = new EventService(this.anchorBlockStore, this.aztecNode, this.privateEventStore, this.jobId);
+    const eventService = new EventService(this.anchorBlockHeader, this.aztecNode, this.privateEventStore, this.jobId);
     const eventStorePromises = eventValidationRequests.map(request =>
       eventService.validateAndStoreEvent(
         request.contractAddress,
@@ -436,7 +506,7 @@ export class UtilityExecutionOracle implements IMiscOracle, IUtilityExecutionOra
     await this.capsuleStore.setCapsuleArray(contractAddress, eventValidationRequestsArrayBaseSlot, [], this.jobId);
   }
 
-  public async utilityBulkRetrieveLogs(
+  public async bulkRetrieveLogs(
     contractAddress: AztecAddress,
     logRetrievalRequestsArrayBaseSlot: Fr,
     logRetrievalResponsesArrayBaseSlot: Fr,
@@ -454,13 +524,14 @@ export class UtilityExecutionOracle implements IMiscOracle, IUtilityExecutionOra
 
     const logService = new LogService(
       this.aztecNode,
-      this.anchorBlockStore,
+      this.anchorBlockHeader,
       this.keyStore,
       this.capsuleStore,
       this.recipientTaggingStore,
       this.senderAddressBookStore,
       this.addressStore,
       this.jobId,
+      this.logger.getBindings(),
     );
 
     const maybeLogRetrievalResponses = await logService.bulkRetrieveLogs(logRetrievalRequests);
@@ -477,7 +548,7 @@ export class UtilityExecutionOracle implements IMiscOracle, IUtilityExecutionOra
     );
   }
 
-  public utilityStoreCapsule(contractAddress: AztecAddress, slot: Fr, capsule: Fr[]): Promise<void> {
+  public storeCapsule(contractAddress: AztecAddress, slot: Fr, capsule: Fr[]): Promise<void> {
     if (!contractAddress.equals(this.contractAddress)) {
       // TODO(#10727): instead of this check that this.contractAddress is allowed to access the external DB
       throw new Error(`Contract ${contractAddress} is not allowed to access ${this.contractAddress}'s PXE DB`);
@@ -486,7 +557,7 @@ export class UtilityExecutionOracle implements IMiscOracle, IUtilityExecutionOra
     return Promise.resolve();
   }
 
-  public async utilityLoadCapsule(contractAddress: AztecAddress, slot: Fr): Promise<Fr[] | null> {
+  public async loadCapsule(contractAddress: AztecAddress, slot: Fr): Promise<Fr[] | null> {
     if (!contractAddress.equals(this.contractAddress)) {
       // TODO(#10727): instead of this check that this.contractAddress is allowed to access the external DB
       throw new Error(`Contract ${contractAddress} is not allowed to access ${this.contractAddress}'s PXE DB`);
@@ -498,7 +569,7 @@ export class UtilityExecutionOracle implements IMiscOracle, IUtilityExecutionOra
     );
   }
 
-  public utilityDeleteCapsule(contractAddress: AztecAddress, slot: Fr): Promise<void> {
+  public deleteCapsule(contractAddress: AztecAddress, slot: Fr): Promise<void> {
     if (!contractAddress.equals(this.contractAddress)) {
       // TODO(#10727): instead of this check that this.contractAddress is allowed to access the external DB
       throw new Error(`Contract ${contractAddress} is not allowed to access ${this.contractAddress}'s PXE DB`);
@@ -507,12 +578,7 @@ export class UtilityExecutionOracle implements IMiscOracle, IUtilityExecutionOra
     return Promise.resolve();
   }
 
-  public utilityCopyCapsule(
-    contractAddress: AztecAddress,
-    srcSlot: Fr,
-    dstSlot: Fr,
-    numEntries: number,
-  ): Promise<void> {
+  public copyCapsule(contractAddress: AztecAddress, srcSlot: Fr, dstSlot: Fr, numEntries: number): Promise<void> {
     if (!contractAddress.equals(this.contractAddress)) {
       // TODO(#10727): instead of this check that this.contractAddress is allowed to access the external DB
       throw new Error(`Contract ${contractAddress} is not allowed to access ${this.contractAddress}'s PXE DB`);
@@ -521,7 +587,7 @@ export class UtilityExecutionOracle implements IMiscOracle, IUtilityExecutionOra
   }
 
   // TODO(#11849): consider replacing this oracle with a pure Noir implementation of aes decryption.
-  public utilityAes128Decrypt(ciphertext: Buffer, iv: Buffer, symKey: Buffer): Promise<Buffer> {
+  public aes128Decrypt(ciphertext: Buffer, iv: Buffer, symKey: Buffer): Promise<Buffer> {
     const aes128 = new Aes128();
     return aes128.decryptBufferCBC(ciphertext, iv, symKey);
   }
@@ -532,13 +598,9 @@ export class UtilityExecutionOracle implements IMiscOracle, IUtilityExecutionOra
    * @param ephPk - The ephemeral public key to get the secret for.
    * @returns The secret for the given address.
    */
-  public utilityGetSharedSecret(address: AztecAddress, ephPk: Point): Promise<Point> {
-    return this.getSharedSecret(address, ephPk);
-  }
-
-  protected async getSharedSecret(address: AztecAddress, ephPk: Point): Promise<Point> {
+  public async getSharedSecret(address: AztecAddress, ephPk: Point): Promise<Point> {
     // TODO(#12656): return an app-siloed secret
-    const recipientCompleteAddress = await this.getCompleteAddress(address);
+    const recipientCompleteAddress = await this.getCompleteAddressOrFail(address);
     const ivskM = await this.keyStore.getMasterSecretKey(
       recipientCompleteAddress.publicKeys.masterIncomingViewingPublicKey,
     );

package/src/contract_logging.ts

@@ -0,0 +1,39 @@
+import type { Fr } from '@aztec/foundation/curves/bn254';
+import { type LogLevel, type Logger, applyStringFormatting, createLogger } from '@aztec/foundation/log';
+import type { AztecAddress } from '@aztec/stdlib/aztec-address';
+import type { DebugLog } from '@aztec/stdlib/logs';
+
+/** Resolves a contract address to a human-readable name, if available. */
+export type ContractNameResolver = (address: AztecAddress) => Promise<string | undefined>;
+
+/**
+ * Creates a logger whose output is prefixed with `contract_log::<name>(<addrAbbrev>)`.
+ */
+export async function createContractLogger(
+  contractAddress: AztecAddress,
+  getContractName: ContractNameResolver,
+  options?: { instanceId?: string },
+): Promise<Logger> {
+  const addrAbbrev = contractAddress.toString().slice(0, 10);
+  const name = await getContractName(contractAddress);
+  const module = name ? `contract_log::${name}(${addrAbbrev})` : `contract_log::Unknown(${addrAbbrev})`;
+  return createLogger(module, options);
+}
+
+/**
+ * Formats and emits a single contract log message through the given logger.
+ */
+export function logContractMessage(logger: Logger, level: LogLevel, message: string, fields: Fr[]): void {
+  logger[level](applyStringFormatting(message, fields));
+}
+
+/**
+ * Displays debug logs collected during public function simulation,
+ * using the `contract_log::` prefixed logger format.
+ */
+export async function displayDebugLogs(debugLogs: DebugLog[], getContractName: ContractNameResolver): Promise<void> {
+  for (const log of debugLogs) {
+    const logger = await createContractLogger(log.contractAddress, getContractName);
+    logContractMessage(logger, log.level, log.message, log.fields);
+  }
+}