feat: merge-train/fairies (#22048)

BEGIN_COMMIT_OVERRIDE
chore: rename pxe-side oracle implementations (#22044)
END_COMMIT_OVERRIDE

Author: AztecBot

yarn-project/pxe/src/contract_function_simulator/contract_function_simulator.ts

@@ -284,7 +284,7 @@ export class ContractFunctionSimulator {
       );
       const publicFunctionsCalldata = await Promise.all(
         publicCallRequests.map(async r => {
-          const calldata = await privateExecutionOracle.loadFromExecutionCache(r.calldataHash);
+          const calldata = await privateExecutionOracle.getHashPreimage(r.calldataHash);
           return new HashedValues(calldata, r.calldataHash);
         }),
       );

yarn-project/pxe/src/contract_function_simulator/oracle/interfaces.ts

@@ -86,7 +86,7 @@ export interface IUtilityExecutionOracle {
     nullifier: Fr,
   ): Promise<NullifierMembershipWitness | undefined>;
   getBlockHeader(blockNumber: BlockNumber): Promise<BlockHeader | undefined>;
-  tryGetPublicKeysAndPartialAddress(
+  getPublicKeysAndPartialAddress(
     account: AztecAddress,
   ): Promise<{ publicKeys: PublicKeys; partialAddress: PartialAddress } | undefined>;
   getAuthWitness(messageHash: Fr): Promise<Fr[] | undefined>;
@@ -107,19 +107,19 @@ export interface IUtilityExecutionOracle {
     offset: number,
     status: NoteStatus,
   ): Promise<NoteData[]>;
-  checkNullifierExists(innerNullifier: Fr): Promise<boolean>;
+  doesNullifierExist(innerNullifier: Fr): Promise<boolean>;
   getL1ToL2MembershipWitness(
     contractAddress: AztecAddress,
     messageHash: Fr,
     secret: Fr,
   ): Promise<MessageLoadOracleInputs<typeof L1_TO_L2_MSG_TREE_HEIGHT>>;
-  storageRead(
+  getFromPublicStorage(
     anchorBlockHash: BlockHash,
     contractAddress: AztecAddress,
     startStorageSlot: Fr,
     numberOfElements: number,
   ): Promise<Fr[]>;
-  fetchTaggedLogs(pendingTaggedLogArrayBaseSlot: Fr, scope: AztecAddress): Promise<void>;
+  getPendingTaggedLogs(pendingTaggedLogArrayBaseSlot: Fr, scope: AztecAddress): Promise<void>;
   validateAndStoreEnqueuedNotesAndEvents(
     contractAddress: AztecAddress,
     noteValidationRequestsArrayBaseSlot: Fr,
@@ -128,20 +128,20 @@ export interface IUtilityExecutionOracle {
     maxEventSerializedLen: number,
     scope: AztecAddress,
   ): Promise<void>;
-  bulkRetrieveLogs(
+  getLogsByTag(
     contractAddress: AztecAddress,
     logRetrievalRequestsArrayBaseSlot: Fr,
     logRetrievalResponsesArrayBaseSlot: Fr,
     scope: AztecAddress,
   ): Promise<void>;
-  utilityResolveMessageContexts(
+  getMessageContextsByTxHash(
     contractAddress: AztecAddress,
     messageContextRequestsArrayBaseSlot: Fr,
     messageContextResponsesArrayBaseSlot: Fr,
     scope: AztecAddress,
   ): Promise<void>;
-  storeCapsule(contractAddress: AztecAddress, key: Fr, capsule: Fr[], scope: AztecAddress): void;
-  loadCapsule(contractAddress: AztecAddress, key: Fr, scope: AztecAddress): Promise<Fr[] | null>;
+  setCapsule(contractAddress: AztecAddress, key: Fr, capsule: Fr[], scope: AztecAddress): void;
+  getCapsule(contractAddress: AztecAddress, key: Fr, scope: AztecAddress): Promise<Fr[] | null>;
   deleteCapsule(contractAddress: AztecAddress, key: Fr, scope: AztecAddress): void;
   copyCapsule(
     contractAddress: AztecAddress,
@@ -150,9 +150,9 @@ export interface IUtilityExecutionOracle {
     numEntries: number,
     scope: AztecAddress,
   ): Promise<void>;
-  aes128Decrypt(ciphertext: Buffer, iv: Buffer, symKey: Buffer): Promise<Buffer>;
+  decryptAes128(ciphertext: Buffer, iv: Buffer, symKey: Buffer): Promise<Buffer>;
   getSharedSecret(address: AztecAddress, ephPk: Point, contractAddress: AztecAddress): Promise<Fr>;
-  invalidateContractSyncCache(contractAddress: AztecAddress, scopes: AztecAddress[]): void;
+  setContractSyncCacheInvalid(contractAddress: AztecAddress, scopes: AztecAddress[]): void;
   emitOffchainEffect(data: Fr[]): Promise<void>;
 }
 
@@ -163,8 +163,8 @@ export interface IUtilityExecutionOracle {
 export interface IPrivateExecutionOracle {
   isPrivate: true;
 
-  storeInExecutionCache(values: Fr[], hash: Fr): void;
-  loadFromExecutionCache(hash: Fr): Promise<Fr[]>;
+  setHashPreimage(values: Fr[], hash: Fr): void;
+  getHashPreimage(hash: Fr): Promise<Fr[]>;
   notifyCreatedNote(
     owner: AztecAddress,
     storageSlot: Fr,
@@ -185,9 +185,9 @@ export interface IPrivateExecutionOracle {
     sideEffectCounter: number,
     isStaticCall: boolean,
   ): Promise<{ endSideEffectCounter: Fr; returnsHash: Fr }>;
-  validatePublicCalldata(calldataHash: Fr): Promise<void>;
+  assertValidPublicCalldata(calldataHash: Fr): Promise<void>;
   notifyRevertiblePhaseStart(minRevertibleSideEffectCounter: number): Promise<void>;
-  inRevertiblePhase(sideEffectCounter: number): Promise<boolean>;
+  isExecutionInRevertiblePhase(sideEffectCounter: number): Promise<boolean>;
   getSenderForTags(): Promise<AztecAddress | undefined>;
   setSenderForTags(senderForTags: AztecAddress): Promise<void>;
   getNextAppTagAsSender(sender: AztecAddress, recipient: AztecAddress): Promise<Tag>;

yarn-project/pxe/src/contract_function_simulator/oracle/oracle.ts

@@ -27,6 +27,25 @@ export class UnavailableOracleError extends Error {
 
 /**
  * A data source that has all the apis required by Aztec.nr.
+ *
+ * ## Oracle naming conventions
+ *
+ * We try to keep oracle naming consistent, please see below the conventions we adhere to.
+ *
+ * Each oracle method name has the form `aztec_{scope}_{verb}{Object}`, where:
+ *
+ * - **Scope prefix** indicates the execution context required:
+ *   - `aztec_prv_` — available only during private function execution.
+ *   - `aztec_utl_` — available during both utility and private execution.
+ *
+ * - **Verb** signals the operation's semantics (verb-first, then object):
+ *   - `get`              — read / lookup / get data from oracle into contract.
+ *   - `does`/`is`/`has`  — predicate (returns boolean).
+ *   - `emit`/`notify`    — propagate data from contract to oracle.
+ *   - `set`              — contract driven oracle state mutation (capsules, execution cache, tagging, etc).
+ *   - `call`             — trigger nested execution (control flow).
+ *   - `assert`           — validate a condition, throw on failure.
+ *   - Standalone verbs (`delete`, `copy`, `decrypt`, `log`, etc) are used when no generic verb fits.
  */
 export class Oracle {
   constructor(private handler: IMiscOracle | IUtilityExecutionOracle | IPrivateExecutionOracle) {}
@@ -109,13 +128,13 @@ export class Oracle {
 
   // eslint-disable-next-line camelcase
   aztec_prv_setHashPreimage(values: ACVMField[], [hash]: ACVMField[]): Promise<ACVMField[]> {
-    this.handlerAsPrivate().storeInExecutionCache(values.map(Fr.fromString), Fr.fromString(hash));
+    this.handlerAsPrivate().setHashPreimage(values.map(Fr.fromString), Fr.fromString(hash));
     return Promise.resolve([]);
   }
 
   // eslint-disable-next-line camelcase
   async aztec_prv_getHashPreimage([returnsHash]: ACVMField[]): Promise<ACVMField[][]> {
-    const values = await this.handlerAsPrivate().loadFromExecutionCache(Fr.fromString(returnsHash));
+    const values = await this.handlerAsPrivate().getHashPreimage(Fr.fromString(returnsHash));
     return [values.map(toACVMField)];
   }
 
@@ -254,7 +273,7 @@ export class Oracle {
   // eslint-disable-next-line camelcase
   async aztec_utl_getPublicKeysAndPartialAddress([address]: ACVMField[]): Promise<(ACVMField | ACVMField[])[]> {
     const parsedAddress = AztecAddress.fromField(Fr.fromString(address));
-    const result = await this.handlerAsUtility().tryGetPublicKeysAndPartialAddress(parsedAddress);
+    const result = await this.handlerAsUtility().getPublicKeysAndPartialAddress(parsedAddress);
 
     // We are going to return a Noir Option struct to represent the possibility of null values. Options are a struct
     // with two fields: `some` (a boolean) and `value` (a field array in this case).
@@ -381,7 +400,7 @@ export class Oracle {
 
   // eslint-disable-next-line camelcase
   async aztec_utl_doesNullifierExist([innerNullifier]: ACVMField[]): Promise<ACVMField[]> {
-    const exists = await this.handlerAsUtility().checkNullifierExists(Fr.fromString(innerNullifier));
+    const exists = await this.handlerAsUtility().doesNullifierExist(Fr.fromString(innerNullifier));
     return [toACVMField(exists)];
   }
 
@@ -406,7 +425,7 @@ export class Oracle {
     [startStorageSlot]: ACVMField[],
     [numberOfElements]: ACVMField[],
   ): Promise<ACVMField[][]> {
-    const values = await this.handlerAsUtility().storageRead(
+    const values = await this.handlerAsUtility().getFromPublicStorage(
       BlockHash.fromString(blockHash),
       new AztecAddress(Fr.fromString(contractAddress)),
       Fr.fromString(startStorageSlot),
@@ -465,7 +484,7 @@ export class Oracle {
 
   // eslint-disable-next-line camelcase
   async aztec_prv_assertValidPublicCalldata([calldataHash]: ACVMField[]): Promise<ACVMField[]> {
-    await this.handlerAsPrivate().validatePublicCalldata(Fr.fromString(calldataHash));
+    await this.handlerAsPrivate().assertValidPublicCalldata(Fr.fromString(calldataHash));
     return [];
   }
 
@@ -477,7 +496,9 @@ export class Oracle {
 
   // eslint-disable-next-line camelcase
   async aztec_prv_isExecutionInRevertiblePhase([sideEffectCounter]: ACVMField[]): Promise<ACVMField[]> {
-    const isRevertible = await this.handlerAsPrivate().inRevertiblePhase(Fr.fromString(sideEffectCounter).toNumber());
+    const isRevertible = await this.handlerAsPrivate().isExecutionInRevertiblePhase(
+      Fr.fromString(sideEffectCounter).toNumber(),
+    );
     return Promise.resolve([toACVMField(isRevertible)]);
   }
 
@@ -495,7 +516,7 @@ export class Oracle {
     [pendingTaggedLogArrayBaseSlot]: ACVMField[],
     [scope]: ACVMField[],
   ): Promise<ACVMField[]> {
-    await this.handlerAsUtility().fetchTaggedLogs(
+    await this.handlerAsUtility().getPendingTaggedLogs(
       Fr.fromString(pendingTaggedLogArrayBaseSlot),
       AztecAddress.fromString(scope),
     );
@@ -530,7 +551,7 @@ export class Oracle {
     [logRetrievalResponsesArrayBaseSlot]: ACVMField[],
     [scope]: ACVMField[],
   ): Promise<ACVMField[]> {
-    await this.handlerAsUtility().bulkRetrieveLogs(
+    await this.handlerAsUtility().getLogsByTag(
       AztecAddress.fromString(contractAddress),
       Fr.fromString(logRetrievalRequestsArrayBaseSlot),
       Fr.fromString(logRetrievalResponsesArrayBaseSlot),
@@ -546,7 +567,7 @@ export class Oracle {
     [messageContextResponsesArrayBaseSlot]: ACVMField[],
     [scope]: ACVMField[],
   ): Promise<ACVMField[]> {
-    await this.handlerAsUtility().utilityResolveMessageContexts(
+    await this.handlerAsUtility().getMessageContextsByTxHash(
       AztecAddress.fromString(contractAddress),
       Fr.fromString(messageContextRequestsArrayBaseSlot),
       Fr.fromString(messageContextResponsesArrayBaseSlot),
@@ -562,7 +583,7 @@ export class Oracle {
     capsule: ACVMField[],
     [scope]: ACVMField[],
   ): Promise<ACVMField[]> {
-    this.handlerAsUtility().storeCapsule(
+    this.handlerAsUtility().setCapsule(
       AztecAddress.fromField(Fr.fromString(contractAddress)),
       Fr.fromString(slot),
       capsule.map(Fr.fromString),
@@ -578,7 +599,7 @@ export class Oracle {
     [tSize]: ACVMField[],
     [scope]: ACVMField[],
   ): Promise<(ACVMField | ACVMField[])[]> {
-    const values = await this.handlerAsUtility().loadCapsule(
+    const values = await this.handlerAsUtility().getCapsule(
       AztecAddress.fromField(Fr.fromString(contractAddress)),
       Fr.fromString(slot),
       AztecAddress.fromField(Fr.fromString(scope)),
@@ -640,7 +661,7 @@ export class Oracle {
 
     // Noir Option<BoundedVec> is encoded as [is_some: Field, storage: Field[], length: Field].
     try {
-      const plaintext = await this.handlerAsUtility().aes128Decrypt(ciphertext, ivBuffer, symKeyBuffer);
+      const plaintext = await this.handlerAsUtility().decryptAes128(ciphertext, ivBuffer, symKeyBuffer);
       const [storage, length] = bufferToBoundedVec(plaintext, ciphertextBVecStorage.length);
       return [toACVMField(1), storage, length];
     } catch {
@@ -672,7 +693,7 @@ export class Oracle {
     [scopeCount]: ACVMField[],
   ): Promise<ACVMField[]> {
     const scopeAddresses = scopes.slice(0, +scopeCount).map(s => AztecAddress.fromField(Fr.fromString(s)));
-    this.handlerAsUtility().invalidateContractSyncCache(
+    this.handlerAsUtility().setContractSyncCacheInvalid(
       AztecAddress.fromField(Fr.fromString(contractAddress)),
       scopeAddresses,
     );

yarn-project/pxe/src/contract_function_simulator/oracle/oracle_version_is_checked.test.ts

@@ -66,7 +66,7 @@ describe('Oracle Version Check test suite', () => {
 
     aztecNode.getPublicStorageAt.mockResolvedValue(Fr.ZERO);
     anchorBlockHeader = BlockHeader.random();
-    capsuleStore.loadCapsule.mockImplementation((_, __) => Promise.resolve(null));
+    capsuleStore.getCapsule.mockImplementation((_, __) => Promise.resolve(null));
     capsuleStore.readCapsuleArray.mockResolvedValue([]);
     senderTaggingStore.getLastFinalizedIndex.mockResolvedValue(undefined);
     senderTaggingStore.getLastUsedIndex.mockResolvedValue(undefined);

yarn-project/pxe/src/contract_function_simulator/oracle/private_execution.test.ts

@@ -286,7 +286,7 @@ describe('Private Execution test suite', () => {
     senderAddressBookStore = mock<SenderAddressBookStore>();
     contractSyncService = mock<ContractSyncService>();
     messageContextService = mock<MessageContextService>();
-    messageContextService.resolveMessageContexts.mockResolvedValue([]);
+    messageContextService.getMessageContextsByTxHash.mockResolvedValue([]);
     // Configure mock to actually perform sync_state calls (needed for nested call tests)
     contractSyncService.ensureContractSynced.mockImplementation(
       async (contractAddress, functionToInvokeAfterSync, utilityExecutor, anchorBlockHeader, jobId, scopes) => {
@@ -436,7 +436,7 @@ describe('Private Execution test suite', () => {
       });
     });
 
-    capsuleStore.loadCapsule.mockImplementation((_, __) => Promise.resolve(null));
+    capsuleStore.getCapsule.mockImplementation((_, __) => Promise.resolve(null));
 
     aztecNode.getPublicStorageAt.mockImplementation(
       (_block: BlockParameter, _address: AztecAddress, _storageSlot: Fr) => {

yarn-project/pxe/src/contract_function_simulator/oracle/private_execution.ts

@@ -76,7 +76,7 @@ export async function executePrivateFunction(
 
   const contractClassLogs = privateExecutionOracle.getContractClassLogs();
 
-  const rawReturnValues = await privateExecutionOracle.loadFromExecutionCache(publicInputs.returnsHash);
+  const rawReturnValues = await privateExecutionOracle.getHashPreimage(publicInputs.returnsHash);
 
   const newNotes = privateExecutionOracle.getNewNotes();
   const noteHashNullifierCounterMap = privateExecutionOracle.getNoteHashNullifierCounterMap();

yarn-project/pxe/src/contract_function_simulator/oracle/private_execution_oracle.ts

@@ -265,7 +265,7 @@ export class PrivateExecutionOracle extends UtilityExecutionOracle implements IP
    * @param values - Values to store.
    * @returns The hash of the values.
    */
-  public storeInExecutionCache(values: Fr[], hash: Fr) {
+  public setHashPreimage(values: Fr[], hash: Fr) {
     return this.executionCache.store(values, hash);
   }
 
@@ -274,15 +274,15 @@ export class PrivateExecutionOracle extends UtilityExecutionOracle implements IP
    * @param hash - Hash of the values.
    * @returns The values.
    */
-  public loadFromExecutionCache(hash: Fr): Promise<Fr[]> {
+  public getHashPreimage(hash: Fr): Promise<Fr[]> {
     const preimage = this.executionCache.getPreimage(hash);
     if (!preimage) {
       throw new Error(`Preimage for hash ${hash.toString()} not found in cache`);
     }
     return Promise.resolve(preimage);
   }
 
-  override async checkNullifierExists(innerNullifier: Fr): Promise<boolean> {
+  override async doesNullifierExist(innerNullifier: Fr): Promise<boolean> {
     // This oracle must be overridden because while utility execution can only meaningfully check if a nullifier exists
     // in the synched block, during private execution there's also the possibility of it being pending, i.e. created
     // in the current transaction.
@@ -295,7 +295,7 @@ export class PrivateExecutionOracle extends UtilityExecutionOracle implements IP
 
     return (
       this.noteCache.getNullifiers(this.contractAddress).has(nullifier) ||
-      (await super.checkNullifierExists(innerNullifier))
+      (await super.doesNullifierExist(innerNullifier))
     );
   }
 
@@ -598,7 +598,7 @@ export class PrivateExecutionOracle extends UtilityExecutionOracle implements IP
   }
 
   /** Validates the calldata preimage exists in the cache and checks cumulative calldata size is within limits. */
-  public validatePublicCalldata(calldataHash: Fr) {
+  public assertValidPublicCalldata(calldataHash: Fr) {
     const calldata = this.executionCache.getPreimage(calldataHash);
     if (!calldata) {
       throw new Error('Calldata for public call not found in cache');
@@ -615,7 +615,7 @@ export class PrivateExecutionOracle extends UtilityExecutionOracle implements IP
     return this.noteCache.setMinRevertibleSideEffectCounter(minRevertibleSideEffectCounter);
   }
 
-  public inRevertiblePhase(sideEffectCounter: number): Promise<boolean> {
+  public isExecutionInRevertiblePhase(sideEffectCounter: number): Promise<boolean> {
     return Promise.resolve(this.noteCache.isSideEffectCounterRevertible(sideEffectCounter));
   }