feat!: scoped capsules

noir-projects/aztec-nr/aztec/src/oracle/capsules.nr

@@ -7,7 +7,8 @@ where
     T: Serialize,
 {
     let serialized = value.serialize();
-    store_oracle(contract_address, slot, serialized);
+    // TODO(@mverzilli): bubble scope param up, for now none=global scope
+    store_oracle(contract_address, slot, serialized, Option::none());
 }
 
 /// Returns data previously stored via `storeCapsule` in the per-contract non-volatile database. Returns Option::none()
@@ -16,25 +17,44 @@ pub unconstrained fn load<T>(contract_address: AztecAddress, slot: Field) -> Opt
 where
     T: Deserialize,
 {
-    let serialized_option = load_oracle(contract_address, slot, <T as Deserialize>::N);
+    // TODO(@mverzilli): bubble scope param up, for now none=global scope
+    let serialized_option = load_oracle(
+        contract_address,
+        slot,
+        <T as Deserialize>::N,
+        Option::none(),
+    );
     serialized_option.map(|arr| Deserialize::deserialize(arr))
 }
 
 /// Deletes data in the per-contract non-volatile database. Does nothing if no data was present.
 pub unconstrained fn delete(contract_address: AztecAddress, slot: Field) {
-    delete_oracle(contract_address, slot);
+    // TODO(@mverzilli): bubble scope param up, for now none=global scope
+    delete_oracle(contract_address, slot, Option::none());
 }
 
 /// Copies a number of contiguous entries in the per-contract non-volatile database. This allows for efficient data
 /// structures by avoiding repeated calls to `loadCapsule` and `storeCapsule`. 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)
 pub unconstrained fn copy(contract_address: AztecAddress, src_slot: Field, dst_slot: Field, num_entries: u32) {
-    copy_oracle(contract_address, src_slot, dst_slot, num_entries);
+    // TODO(@mverzilli): bubble scope param up, for now none=global scope
+    copy_oracle(
+        contract_address,
+        src_slot,
+        dst_slot,
+        num_entries,
+        Option::none(),
+    );
 }
 
 #[oracle(aztec_utl_storeCapsule)]
-unconstrained fn store_oracle<let N: u32>(contract_address: AztecAddress, slot: Field, values: [Field; N]) {}
+unconstrained fn store_oracle<let N: u32>(
+    contract_address: AztecAddress,
+    slot: Field,
+    values: [Field; N],
+    scope: Option<AztecAddress>,
+) {}
 
 /// We need to pass in `array_len` (the value of N) as a parameter to tell the oracle how many fields the response must
 /// have.
@@ -48,13 +68,20 @@ unconstrained fn load_oracle<let N: u32>(
     contract_address: AztecAddress,
     slot: Field,
     array_len: u32,
+    scope: Option<AztecAddress>,
 ) -> Option<[Field; N]> {}
 
 #[oracle(aztec_utl_deleteCapsule)]
-unconstrained fn delete_oracle(contract_address: AztecAddress, slot: Field) {}
+unconstrained fn delete_oracle(contract_address: AztecAddress, slot: Field, scope: Option<AztecAddress>) {}
 
 #[oracle(aztec_utl_copyCapsule)]
-unconstrained fn copy_oracle(contract_address: AztecAddress, src_slot: Field, dst_slot: Field, num_entries: u32) {}
+unconstrained fn copy_oracle(
+    contract_address: AztecAddress,
+    src_slot: Field,
+    dst_slot: Field,
+    num_entries: u32,
+    scope: Option<AztecAddress>,
+) {}
 
 mod test {
     // These tests are sort of redundant since we already test the oracle implementation directly in TypeScript, but

noir-projects/aztec-nr/aztec/src/oracle/version.nr

@@ -4,7 +4,7 @@
 ///
 /// @dev Whenever a contract function or Noir test is run, the `aztec_utl_assertCompatibleOracleVersion` oracle is
 /// called and if the oracle version is incompatible an error is thrown.
-pub global ORACLE_VERSION: Field = 16;
+pub global ORACLE_VERSION: Field = 17;
 
 /// Asserts that the version of the oracle is compatible with the version expected by the contract.
 pub fn assert_compatible_oracle_version() {

noir-projects/noir-contracts/contracts/protocol/aztec_sublib/src/oracle/capsules.nr

@@ -7,7 +7,7 @@ where
     T: Serialize,
 {
     let serialized = value.serialize();
-    store_oracle(contract_address, slot, serialized);
+    store_oracle(contract_address, slot, serialized, Option::none());
 }
 
 /// Returns data previously stored via `storeCapsule` in the per-contract non-volatile database. Returns Option::none()
@@ -16,13 +16,13 @@ pub unconstrained fn load<T>(contract_address: AztecAddress, slot: Field) -> Opt
 where
     T: Deserialize,
 {
-    let serialized_option = load_oracle(contract_address, slot, <T as Deserialize>::N);
+    let serialized_option = load_oracle(contract_address, slot, <T as Deserialize>::N, Option::none());
     serialized_option.map(|arr| Deserialize::deserialize(arr))
 }
 
 /// Deletes data in the per-contract non-volatile database. Does nothing if no data was present.
 pub unconstrained fn delete(contract_address: AztecAddress, slot: Field) {
-    delete_oracle(contract_address, slot);
+    delete_oracle(contract_address, slot, Option::none());
 }
 
 /// Copies a number of contiguous entries in the per-contract non-volatile database. This allows for efficient data
@@ -35,14 +35,15 @@ pub unconstrained fn copy(
     dst_slot: Field,
     num_entries: u32,
 ) {
-    copy_oracle(contract_address, src_slot, dst_slot, num_entries);
+    copy_oracle(contract_address, src_slot, dst_slot, num_entries, Option::none());
 }
 
 #[oracle(aztec_utl_storeCapsule)]
 unconstrained fn store_oracle<let N: u32>(
     contract_address: AztecAddress,
     slot: Field,
     values: [Field; N],
+    scope: Option<AztecAddress>,
 ) {}
 
 /// We need to pass in `array_len` (the value of N) as a parameter to tell the oracle how many fields the response must
@@ -57,15 +58,17 @@ unconstrained fn load_oracle<let N: u32>(
     contract_address: AztecAddress,
     slot: Field,
     array_len: u32,
+    scope: Option<AztecAddress>,
 ) -> Option<[Field; N]> {}
 
 #[oracle(aztec_utl_deleteCapsule)]
-unconstrained fn delete_oracle(contract_address: AztecAddress, slot: Field) {}
+unconstrained fn delete_oracle(contract_address: AztecAddress, slot: Field, scope: Option<AztecAddress>) {}
 
 #[oracle(aztec_utl_copyCapsule)]
 unconstrained fn copy_oracle(
     contract_address: AztecAddress,
     src_slot: Field,
     dst_slot: Field,
     num_entries: u32,
+    scope: Option<AztecAddress>,
 ) {}

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

@@ -137,10 +137,16 @@ export interface IUtilityExecutionOracle {
     messageContextRequestsArrayBaseSlot: Fr,
     messageContextResponsesArrayBaseSlot: Fr,
   ): Promise<void>;
-  storeCapsule(contractAddress: AztecAddress, key: Fr, capsule: Fr[]): Promise<void>;
-  loadCapsule(contractAddress: AztecAddress, key: Fr): Promise<Fr[] | null>;
-  deleteCapsule(contractAddress: AztecAddress, key: Fr): Promise<void>;
-  copyCapsule(contractAddress: AztecAddress, srcKey: Fr, dstKey: Fr, numEntries: number): Promise<void>;
+  storeCapsule(contractAddress: AztecAddress, key: Fr, capsule: Fr[], scope?: AztecAddress): void;
+  loadCapsule(contractAddress: AztecAddress, key: Fr, scope?: AztecAddress): Promise<Fr[] | null>;
+  deleteCapsule(contractAddress: AztecAddress, key: Fr, scope?: AztecAddress): void;
+  copyCapsule(
+    contractAddress: AztecAddress,
+    srcKey: Fr,
+    dstKey: Fr,
+    numEntries: number,
+    scope?: AztecAddress,
+  ): Promise<void>;
   aes128Decrypt(ciphertext: Buffer, iv: Buffer, symKey: Buffer): Promise<Buffer>;
   getSharedSecret(address: AztecAddress, ephPk: Point): Promise<Point>;
   emitOffchainEffect(data: Fr[]): Promise<void>;

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

@@ -23,7 +23,10 @@ export function buildLegacyOracleCallbacks(oracle: Oracle): ACIRCallback {
       contractAddress: ACVMField[],
       slot: ACVMField[],
       tSize: ACVMField[],
-    ): Promise<(ACVMField | ACVMField[])[]> => oracle.aztec_utl_loadCapsule(contractAddress, slot, tSize),
+    ): Promise<(ACVMField | ACVMField[])[]> =>
+      // Last two params represent an Option<AztecAddress> == None, which means the capsule is contract-global,
+      // matching legacy behavior.
+      oracle.aztec_utl_loadCapsule(contractAddress, slot, tSize, [new Fr(0).toString()], [new Fr(0).toString()]),
     privateStoreInExecutionCache: (values: ACVMField[], hash: ACVMField[]): Promise<ACVMField[]> =>
       oracle.aztec_prv_storeInExecutionCache(values, hash),
     privateLoadFromExecutionCache: (returnsHash: ACVMField[]): Promise<ACVMField[][]> =>
@@ -65,15 +68,30 @@ export function buildLegacyOracleCallbacks(oracle: Oracle): ACIRCallback {
       contractAddress: ACVMField[],
       slot: ACVMField[],
       capsule: ACVMField[],
-    ): Promise<ACVMField[]> => oracle.aztec_utl_storeCapsule(contractAddress, slot, capsule),
+    ): Promise<ACVMField[]> =>
+      // Last two params represent an Option<AztecAddress> == None, which means the capsule is contract-global,
+      // matching legacy behavior.
+      oracle.aztec_utl_storeCapsule(contractAddress, slot, capsule, [new Fr(0).toString()], [new Fr(0).toString()]),
     utilityCopyCapsule: (
       contractAddress: ACVMField[],
       srcSlot: ACVMField[],
       dstSlot: ACVMField[],
       numEntries: ACVMField[],
-    ): Promise<ACVMField[]> => oracle.aztec_utl_copyCapsule(contractAddress, srcSlot, dstSlot, numEntries),
+    ): Promise<ACVMField[]> =>
+      // Last two params represent an Option<AztecAddress> == None, which means the capsule is contract-global,
+      // matching legacy behavior.
+      oracle.aztec_utl_copyCapsule(
+        contractAddress,
+        srcSlot,
+        dstSlot,
+        numEntries,
+        [new Fr(0).toString()],
+        [new Fr(0).toString()],
+      ),
     utilityDeleteCapsule: (contractAddress: ACVMField[], slot: ACVMField[]): Promise<ACVMField[]> =>
-      oracle.aztec_utl_deleteCapsule(contractAddress, slot),
+      // Last two params represent an Option<AztecAddress> == None, which means the capsule is contract-global,
+      // matching legacy behavior.
+      oracle.aztec_utl_deleteCapsule(contractAddress, slot, [new Fr(0).toString()], [new Fr(0).toString()]),
     utilityAes128Decrypt: (
       ciphertextBVecStorage: ACVMField[],
       ciphertextLength: ACVMField[],

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

@@ -25,6 +25,10 @@ export class UnavailableOracleError extends Error {
   }
 }
 
+function optionalAddressFromAcvmFields(scopeSome: ACVMField, scopeValue: ACVMField) {
+  return Fr.fromString(scopeSome).toNumber() === 1 ? AztecAddress.fromField(Fr.fromString(scopeValue)) : undefined;
+}
+
 /**
  * A data source that has all the apis required by Aztec.nr.
  */
@@ -544,28 +548,36 @@ export class Oracle {
   }
 
   // eslint-disable-next-line camelcase
-  async aztec_utl_storeCapsule(
+  aztec_utl_storeCapsule(
     [contractAddress]: ACVMField[],
     [slot]: ACVMField[],
     capsule: ACVMField[],
+    [scopeSome]: ACVMField[],
+    [scopeValue]: ACVMField[],
   ): Promise<ACVMField[]> {
-    await this.handlerAsUtility().storeCapsule(
+    const scope = optionalAddressFromAcvmFields(scopeSome, scopeValue);
+    this.handlerAsUtility().storeCapsule(
       AztecAddress.fromField(Fr.fromString(contractAddress)),
       Fr.fromString(slot),
       capsule.map(Fr.fromString),
+      scope,
     );
-    return [];
+    return Promise.resolve([]);
   }
 
   // eslint-disable-next-line camelcase
   async aztec_utl_loadCapsule(
     [contractAddress]: ACVMField[],
     [slot]: ACVMField[],
     [tSize]: ACVMField[],
+    [scopeSome]: ACVMField[],
+    [scopeValue]: ACVMField[],
   ): Promise<(ACVMField | ACVMField[])[]> {
+    const scope = optionalAddressFromAcvmFields(scopeSome, scopeValue);
     const values = await this.handlerAsUtility().loadCapsule(
       AztecAddress.fromField(Fr.fromString(contractAddress)),
       Fr.fromString(slot),
+      scope,
     );
 
     // We are going to return a Noir Option struct to represent the possibility of null values. Options are a struct
@@ -580,12 +592,19 @@ export class Oracle {
   }
 
   // eslint-disable-next-line camelcase
-  async aztec_utl_deleteCapsule([contractAddress]: ACVMField[], [slot]: ACVMField[]): Promise<ACVMField[]> {
-    await this.handlerAsUtility().deleteCapsule(
+  aztec_utl_deleteCapsule(
+    [contractAddress]: ACVMField[],
+    [slot]: ACVMField[],
+    [scopeSome]: ACVMField[],
+    [scopeValue]: ACVMField[],
+  ): Promise<ACVMField[]> {
+    const scope = optionalAddressFromAcvmFields(scopeSome, scopeValue);
+    this.handlerAsUtility().deleteCapsule(
       AztecAddress.fromField(Fr.fromString(contractAddress)),
       Fr.fromString(slot),
+      scope,
     );
-    return [];
+    return Promise.resolve([]);
   }
 
   // eslint-disable-next-line camelcase
@@ -594,12 +613,16 @@ export class Oracle {
     [srcSlot]: ACVMField[],
     [dstSlot]: ACVMField[],
     [numEntries]: ACVMField[],
+    [scopeSome]: ACVMField[],
+    [scopeValue]: ACVMField[],
   ): Promise<ACVMField[]> {
+    const scope = optionalAddressFromAcvmFields(scopeSome, scopeValue);
     await this.handlerAsUtility().copyCapsule(
       AztecAddress.fromField(Fr.fromString(contractAddress)),
       Fr.fromString(srcSlot),
       Fr.fromString(dstSlot),
       Fr.fromString(numEntries).toNumber(),
+      scope,
     );
     return [];
   }

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

@@ -12,7 +12,7 @@ import type { AztecNode } from '@aztec/stdlib/interfaces/server';
 import { deriveKeys } from '@aztec/stdlib/keys';
 import { Note, NoteDao } from '@aztec/stdlib/note';
 import { makeL2Tips } from '@aztec/stdlib/testing';
-import { BlockHeader, GlobalVariables, TxHash } from '@aztec/stdlib/tx';
+import { BlockHeader, Capsule, GlobalVariables, TxHash } from '@aztec/stdlib/tx';
 
 import { mock } from 'jest-mock-extended';
 import type { _MockProxy } from 'jest-mock-extended/lib/Mock.js';
@@ -245,6 +245,73 @@ describe('Utility Execution test suite', () => {
       });
     });
 
+    describe('capsules', () => {
+      it('forwards scope to the capsule store', async () => {
+        const scope = await AztecAddress.random();
+        const slot = Fr.random();
+        const srcSlot = Fr.random();
+        const dstSlot = Fr.random();
+        const capsule = [Fr.random()];
+
+        capsuleStore.loadCapsule.mockResolvedValueOnce(capsule);
+
+        utilityExecutionOracle.storeCapsule(contractAddress, slot, capsule, scope);
+        await utilityExecutionOracle.loadCapsule(contractAddress, slot, scope);
+        utilityExecutionOracle.deleteCapsule(contractAddress, slot, scope);
+        await utilityExecutionOracle.copyCapsule(contractAddress, srcSlot, dstSlot, 1, scope);
+
+        expect(capsuleStore.storeCapsule).toHaveBeenCalledWith(contractAddress, slot, capsule, 'test-job-id', scope);
+        expect(capsuleStore.loadCapsule).toHaveBeenCalledWith(contractAddress, slot, 'test-job-id', scope);
+        expect(capsuleStore.deleteCapsule).toHaveBeenCalledWith(contractAddress, slot, 'test-job-id', scope);
+        expect(capsuleStore.copyCapsule).toHaveBeenCalledWith(
+          contractAddress,
+          srcSlot,
+          dstSlot,
+          1,
+          'test-job-id',
+          scope,
+        );
+      });
+
+      it('loads transient capsules by scope', async () => {
+        const scope = await AztecAddress.random();
+        const slot = Fr.random();
+        const transientGlobal = [Fr.random()];
+        const transientScoped = [Fr.random()];
+        const persisted = [Fr.random()];
+
+        utilityExecutionOracle = new UtilityExecutionOracle({
+          contractAddress,
+          authWitnesses: [],
+          capsules: [
+            new Capsule(contractAddress, slot, transientGlobal),
+            new Capsule(contractAddress, slot, transientScoped, scope),
+          ],
+          anchorBlockHeader,
+          contractStore,
+          noteStore,
+          keyStore,
+          addressStore,
+          aztecNode,
+          recipientTaggingStore,
+          senderAddressBookStore,
+          capsuleStore,
+          privateEventStore,
+          messageContextService,
+          jobId: 'test-job-id',
+          scopes: 'ALL_SCOPES',
+        });
+
+        capsuleStore.loadCapsule.mockResolvedValueOnce(persisted);
+
+        expect(await utilityExecutionOracle.loadCapsule(contractAddress, slot)).toEqual(transientGlobal);
+        expect(await utilityExecutionOracle.loadCapsule(contractAddress, slot, AztecAddress.ZERO)).toEqual(
+          transientGlobal,
+        );
+        expect(await utilityExecutionOracle.loadCapsule(contractAddress, slot, scope)).toEqual(transientScoped);
+      });
+    });
+
     describe('utilityResolveMessageContexts', () => {
       const requestSlot = Fr.random();
       const responseSlot = Fr.random();