refactor: improving membership funcs naming (#20065)

As discussed on slack the naming of the `getArchiveMembershipWitness`
function was not great so I renamed it to
`getBlockHashMembershipWitness`.

With that the arg naming became weird so I changed it in all the
endpoint functions.

Author: benesjan

docs/docs-developers/docs/resources/migration_notes.md

@@ -24,7 +24,7 @@ These methods were not used by PXE and returned a subset of the information alre
 |----------------|-------------|
 | `getNullifierSiblingPath` | `getNullifierMembershipWitness` |
 | `getNoteHashSiblingPath` | `getNoteHashMembershipWitness` |
-| `getArchiveSiblingPath` | `getArchiveMembershipWitness` |
+| `getArchiveSiblingPath` | `getBlockHashMembershipWitness` |
 | `getPublicDataSiblingPath` | `getPublicDataWitness` |
 
 The membership witness methods return both the sibling path and additional context (leaf index, preimage data) needed for proofs.
@@ -56,6 +56,29 @@ The nullifier secret key (`nsk_m` / `nsk_app`) has been renamed to nullifier hid
 
 The `GeneratorIndex.NSK_M` enum member is now `GeneratorIndex.NHK_M`.
 
+### [AztecNode/Aztec.nr] `getArchiveMembershipWitness` renamed to `getBlockHashMembershipWitness`
+
+The `getArchiveMembershipWitness` method has been renamed to `getBlockHashMembershipWitness` to better reflect its purpose. 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. This rename clarifies that the method finds a membership witness for a block hash in the archive tree.
+
+**TypeScript (AztecNode interface):**
+
+```diff
+- const witness = await aztecNode.getArchiveMembershipWitness(blockNumber, archiveLeaf);
++ const witness = await aztecNode.getBlockHashMembershipWitness(blockNumber, blockHash);
+```
+
+The second parameter type has also changed from `Fr` to `BlockHash`.
+
+**Noir (aztec-nr):**
+
+```diff
+- use dep::aztec::oracle::get_membership_witness::get_archive_membership_witness;
++ use dep::aztec::oracle::get_membership_witness::get_block_hash_membership_witness;
+
+- let witness = get_archive_membership_witness(block_header, leaf_value);
++ let witness = get_block_hash_membership_witness(anchor_block_header, block_hash);
+```
+
 ### [Aztec.nr] `protocol_types` renamed to `protocol`
 
 The `protocol_types` re-export from the `aztec` crate has been renamed to `protocol`. Update all imports accordingly:

docs/docs-network/operators/reference/node-api-reference.md

@@ -475,14 +475,14 @@ curl -X POST http://localhost:8080 \
   -d '{"jsonrpc":"2.0","method":"node_getPublicDataWitness","params":[12345,"0x0000..."],"id":1}'
 ```
 
-### node_getArchiveMembershipWitness
+### node_getBlockHashMembershipWitness
 
-Gets archive tree membership witness.
+Gets a membership witness for 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.
 
 **Parameters**:
 
-1. `blockNumber` - `number | "latest"` - Block number
-2. `archive` - `string` - Archive leaf value (32-byte hex)
+1. `block` - `number | "latest"` - Block number at which to query the archive tree
+2. `blockHash` - `string` - Block hash to find in the archive tree (32-byte hex)
 
 **Returns**: `MembershipWitness | null`
 
@@ -491,7 +491,7 @@ Gets archive tree membership witness.
 ```bash
 curl -X POST http://localhost:8080 \
   -H 'Content-Type: application/json' \
-  -d '{"jsonrpc":"2.0","method":"node_getArchiveMembershipWitness","params":[12345,"0x1234..."],"id":1}'
+  -d '{"jsonrpc":"2.0","method":"node_getBlockHashMembershipWitness","params":[12345,"0x1234..."],"id":1}'
 ```
 
 ### node_getNoteHashMembershipWitness

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

@@ -1,6 +1,6 @@
 use crate::protocol::{abis::block_header::BlockHeader, merkle_tree::root::root_from_sibling_path, traits::Hash};
 
-use crate::{context::PrivateContext, oracle::get_membership_witness::get_archive_membership_witness};
+use crate::{context::PrivateContext, oracle::get_membership_witness::get_block_hash_membership_witness};
 
 #[oracle(utilityGetBlockHeader)]
 unconstrained fn get_block_header_at_oracle(_block_number: u32) -> BlockHeader {}
@@ -56,7 +56,7 @@ fn constrain_get_block_header_at_internal(
 
     // 2) Get the membership witness of the block in the archive tree.
     // Safety: The witness is only used as a "magical value" that makes the merkle proof below pass. Hence it's safe.
-    let witness = unsafe { get_archive_membership_witness(anchor_block_header, block_hash) };
+    let witness = unsafe { get_block_hash_membership_witness(anchor_block_header, block_hash) };
 
     // 3) Check that the block is in the archive (i.e. the witness is valid)
     assert_eq(

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

@@ -19,33 +19,36 @@ pub struct MembershipWitness<let N: u32, let M: u32> {
 
 #[oracle(utilityGetNoteHashMembershipWitness)]
 unconstrained fn get_note_hash_membership_witness_oracle(
-    block_hash: Field,
-    leaf_value: Field,
+    anchor_block_hash: Field,
+    note_hash: Field,
 ) -> MembershipWitness<NOTE_HASH_TREE_HEIGHT, NOTE_HASH_TREE_HEIGHT + 1> {}
 
-#[oracle(utilityGetArchiveMembershipWitness)]
-unconstrained fn get_archive_membership_witness_oracle(
+#[oracle(utilityGetBlockHashMembershipWitness)]
+unconstrained fn get_block_hash_membership_witness_oracle(
+    anchor_block_hash: Field,
     block_hash: Field,
-    leaf_value: Field,
 ) -> MembershipWitness<ARCHIVE_HEIGHT, ARCHIVE_HEIGHT + 1> {}
 
 // Note: get_nullifier_membership_witness function is implemented in get_nullifier_membership_witness.nr
 
+/// Returns a membership witness for a `note_hash` in the note hash tree whose root is defined in
+// `anchor_block_header`.
 pub unconstrained fn get_note_hash_membership_witness(
-    block_header: BlockHeader,
-    leaf_value: Field,
+    anchor_block_header: BlockHeader,
+    note_hash: Field,
 ) -> MembershipWitness<NOTE_HASH_TREE_HEIGHT, NOTE_HASH_TREE_HEIGHT + 1> {
-    let block_hash = block_header.hash();
-    get_note_hash_membership_witness_oracle(block_hash, leaf_value)
+    let anchor_block_hash = anchor_block_header.hash();
+    get_note_hash_membership_witness_oracle(anchor_block_hash, note_hash)
 }
 
 // There is no `get_public_data_membership_witness` function because it doesn't make sense to be getting a membership
 // witness for a value in the public data tree.
 
-pub unconstrained fn get_archive_membership_witness(
-    block_header: BlockHeader,
-    leaf_value: Field,
+/// Returns a membership witness for a `block_hash` in the archive tree whose root is defined in `anchor_block_header`.
+pub unconstrained fn get_block_hash_membership_witness(
+    anchor_block_header: BlockHeader,
+    block_hash: Field,
 ) -> MembershipWitness<ARCHIVE_HEIGHT, ARCHIVE_HEIGHT + 1> {
-    let block_hash = block_header.hash();
-    get_archive_membership_witness_oracle(block_hash, leaf_value)
+    let anchor_block_hash = anchor_block_header.hash();
+    get_block_hash_membership_witness_oracle(anchor_block_hash, block_hash)
 }

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

@@ -4,7 +4,7 @@
 ///
 /// @dev Whenever a contract function or Noir test is run, the `utilityAssertCompatibleOracleVersion` oracle is called
 /// and if the oracle version is incompatible an error is thrown.
-pub global ORACLE_VERSION: Field = 9;
+pub global ORACLE_VERSION: Field = 10;
 
 /// 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/bootstrap.sh

@@ -126,6 +126,7 @@ function get_contract_hash {
         ../../barretenberg/cpp/.rebuild_patterns \
         ../../barretenberg/ts/.rebuild_patterns \
         "^noir-projects/noir-contracts/contracts/$contract_path/" \
+        "^noir-projects/noir-contracts/contracts/protocol/aztec_sublib/" \
         "^noir-projects/aztec-nr/" \
         "^noir-projects/noir-protocol-circuits/crates/types/")
   fi

noir-projects/noir-contracts/contracts/protocol/aztec_sublib/Nargo.toml

@@ -3,4 +3,5 @@ name = "aztec_sublib"
 type = "lib"
 
 [dependencies]
+aztec = { path = "../../../../aztec-nr/aztec" }
 protocol_types = { path = "../../../../noir-protocol-circuits/crates/types" }

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

@@ -1,7 +1,6 @@
 //! Oracle modules for protocol contracts.
 
 pub mod avm;
-pub mod version;
 pub mod execution_cache;
 pub mod capsules;
 pub mod storage;
@@ -15,3 +14,6 @@ pub mod logs;
 // debug_log oracle is used by both noir-protocol-circuits and this crate and for this reason we just re-export it
 // here from protocol_types.
 pub use protocol_types::debug_log;
+
+// version oracle is defined in aztec-nr and re-exported here as re-defining versions is not practical.
+pub use aztec::oracle::version;

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

@@ -851,11 +851,11 @@ export class AztecNodeService implements AztecNode, AztecNodeAdmin, Traceable {
   }
 
   public async findLeavesIndexes(
-    block: BlockParameter,
+    referenceBlock: BlockParameter,
     treeId: MerkleTreeId,
     leafValues: Fr[],
   ): Promise<(DataInBlock<bigint> | undefined)[]> {
-    const committedDb = await this.#getWorldState(block);
+    const committedDb = await this.#getWorldState(referenceBlock);
     const maybeIndices = await committedDb.findLeafIndices(
       treeId,
       leafValues.map(x => x.toBuffer()),
@@ -913,22 +913,22 @@ export class AztecNodeService implements AztecNode, AztecNodeAdmin, Traceable {
     });
   }
 
-  public async getArchiveMembershipWitness(
-    block: BlockParameter,
-    archive: Fr,
+  public async getBlockHashMembershipWitness(
+    referenceBlock: BlockParameter,
+    blockHash: BlockHash,
   ): Promise<MembershipWitness<typeof ARCHIVE_HEIGHT> | undefined> {
-    const committedDb = await this.#getWorldState(block);
-    const [pathAndIndex] = await committedDb.findSiblingPaths<MerkleTreeId.ARCHIVE>(MerkleTreeId.ARCHIVE, [archive]);
+    const committedDb = await this.#getWorldState(referenceBlock);
+    const [pathAndIndex] = await committedDb.findSiblingPaths<MerkleTreeId.ARCHIVE>(MerkleTreeId.ARCHIVE, [blockHash]);
     return pathAndIndex === undefined
       ? undefined
       : MembershipWitness.fromSiblingPath(pathAndIndex.index, pathAndIndex.path);
   }
 
   public async getNoteHashMembershipWitness(
-    block: BlockParameter,
+    referenceBlock: BlockParameter,
     noteHash: Fr,
   ): Promise<MembershipWitness<typeof NOTE_HASH_TREE_HEIGHT> | undefined> {
-    const committedDb = await this.#getWorldState(block);
+    const committedDb = await this.#getWorldState(referenceBlock);
     const [pathAndIndex] = await committedDb.findSiblingPaths<MerkleTreeId.NOTE_HASH_TREE>(
       MerkleTreeId.NOTE_HASH_TREE,
       [noteHash],
@@ -939,10 +939,10 @@ export class AztecNodeService implements AztecNode, AztecNodeAdmin, Traceable {
   }
 
   public async getL1ToL2MessageMembershipWitness(
-    block: BlockParameter,
+    referenceBlock: BlockParameter,
     l1ToL2Message: Fr,
   ): Promise<[bigint, SiblingPath<typeof L1_TO_L2_MSG_TREE_HEIGHT>] | undefined> {
-    const db = await this.#getWorldState(block);
+    const db = await this.#getWorldState(referenceBlock);
     const [witness] = await db.findSiblingPaths(MerkleTreeId.L1_TO_L2_MESSAGE_TREE, [l1ToL2Message]);
     if (!witness) {
       return undefined;
@@ -996,10 +996,10 @@ export class AztecNodeService implements AztecNode, AztecNodeAdmin, Traceable {
   }
 
   public async getNullifierMembershipWitness(
-    block: BlockParameter,
+    referenceBlock: BlockParameter,
     nullifier: Fr,
   ): Promise<NullifierMembershipWitness | undefined> {
-    const db = await this.#getWorldState(block);
+    const db = await this.#getWorldState(referenceBlock);
     const [witness] = await db.findSiblingPaths(MerkleTreeId.NULLIFIER_TREE, [nullifier.toBuffer()]);
     if (!witness) {
       return undefined;
@@ -1016,7 +1016,8 @@ export class AztecNodeService implements AztecNode, AztecNodeAdmin, Traceable {
 
   /**
    * Returns a low nullifier membership witness for a given nullifier at a given block.
-   * @param block - The block parameter (block number, block hash, or 'latest') at which to get the data.
+   * @param referenceBlock - The block parameter (block number, block hash, or 'latest') at which to get the data
+   * (which contains the root of the nullifier tree in which we are searching for the nullifier).
    * @param nullifier - Nullifier we try to find the low nullifier witness for.
    * @returns The low nullifier membership witness (if found).
    * @remarks Low nullifier witness can be used to perform a nullifier non-inclusion proof by leveraging the "linked
@@ -1029,10 +1030,10 @@ export class AztecNodeService implements AztecNode, AztecNodeAdmin, Traceable {
    * TODO: This is a confusing behavior and we should eventually address that.
    */
   public async getLowNullifierMembershipWitness(
-    block: BlockParameter,
+    referenceBlock: BlockParameter,
     nullifier: Fr,
   ): Promise<NullifierMembershipWitness | undefined> {
-    const committedDb = await this.#getWorldState(block);
+    const committedDb = await this.#getWorldState(referenceBlock);
     const findResult = await committedDb.getPreviousValueIndex(MerkleTreeId.NULLIFIER_TREE, nullifier.toBigInt());
     if (!findResult) {
       return undefined;
@@ -1047,8 +1048,8 @@ export class AztecNodeService implements AztecNode, AztecNodeAdmin, Traceable {
     return new NullifierMembershipWitness(BigInt(index), preimageData as NullifierLeafPreimage, siblingPath);
   }
 
-  async getPublicDataWitness(block: BlockParameter, leafSlot: Fr): Promise<PublicDataWitness | undefined> {
-    const committedDb = await this.#getWorldState(block);
+  async getPublicDataWitness(referenceBlock: BlockParameter, leafSlot: Fr): Promise<PublicDataWitness | undefined> {
+    const committedDb = await this.#getWorldState(referenceBlock);
     const lowLeafResult = await committedDb.getPreviousValueIndex(MerkleTreeId.PUBLIC_DATA_TREE, leafSlot.toBigInt());
     if (!lowLeafResult) {
       return undefined;
@@ -1062,8 +1063,8 @@ export class AztecNodeService implements AztecNode, AztecNodeAdmin, Traceable {
     }
   }
 
-  public async getPublicStorageAt(block: BlockParameter, contract: AztecAddress, slot: Fr): Promise<Fr> {
-    const committedDb = await this.#getWorldState(block);
+  public async getPublicStorageAt(referenceBlock: BlockParameter, contract: AztecAddress, slot: Fr): Promise<Fr> {
+    const committedDb = await this.#getWorldState(referenceBlock);
     const leafSlot = await computePublicDataTreeLeafSlot(contract, slot);
 
     const lowLeafResult = await committedDb.getPreviousValueIndex(MerkleTreeId.PUBLIC_DATA_TREE, leafSlot.toBigInt());