doc: addressing review comments

yellow-paper/docs/contract-deployment/classes.md

@@ -109,36 +109,38 @@ private_function_leaf_crh(
 
 Even though not enforced by the protocol, it is suggested for the `artifact_hash` to follow this general structure, in order to be compatible with the definition of the [`broadcast` function below](#broadcast).
 
+Note: below, `sha256_modulo(x) = sha256(x) % FIELD_MODULUS`. This approach must not be used if seeking pseudo-randomness, but can be used for collision resistance.
+
 <!-- HASH DEFINITION -->
 
 ```rust
 artifact_crh(
   artifact // This type is out of protocol, e.g. the format output by Nargo
 ) -> Field {
 
-  let private_functions_artifact_leaves: [u8; 32][] = artifact.private_functions.map(|f|
-    sha256(
+  let private_functions_artifact_leaves: Field[] = artifact.private_functions.map(|f|
+    sha256_modulo(
       be_string_to_bits("az_artifact_private_function_leaf"),
 
       f.selector, // 32-bits
       f.metadata_hash, // 256-bits
       sha256(f.private_bytecode)
     )
   );
-  let private_functions_artifact_tree_root: [u8; 32] = merkleize(private_functions_artifact_leaves);
+  let private_functions_artifact_tree_root: Field = merkleize(private_functions_artifact_leaves);
 
-  let unconstrained_functions_artifact_leaves: [u8; 32][] = artifact.unconstrained_functions.map(|f|
-    sha256(
+  let unconstrained_functions_artifact_leaves: Field[] = artifact.unconstrained_functions.map(|f|
+    sha256_modulo(
       be_string_to_bits("az_artifact_unconstrained_function_leaf"),
 
       f.selector, // 32-bits
       f.metadata_hash, // 256-bits
       sha256(f.unconstrained_bytecode)
     )
   );
-  let unconstrained_functions_artifact_tree_root: [u8; 32] = merkleize(unconstrained_functions_artifact_leaves);
+  let unconstrained_functions_artifact_tree_root: Field = merkleize(unconstrained_functions_artifact_leaves);
 
-  let artifact_hash_256_bit: [u8; 32] = sha256(
+  let artifact_hash: Field = sha256_modulo(
     be_string_to_field("az_artifact"),
 
     private_functions_artifact_tree_root, // 256-bits
@@ -165,10 +167,10 @@ The metadata hash for each function is suggested to be computed as the sha256 of
 ```rust
 function_metadata_crh(
   function // This type is out of protocol, e.g. the format output by Nargo
-) -> [u8; 32] {
+) -> Field {
   let function_metadata = omit(function, "bytecode", "debug_symbols");
 
-  let function_metadata_hash: [u8; 32] = sha256(
+  let function_metadata_hash: Field = sha256_modulo(
     be_string_to_bits("az_function_metadata"),
 
     json_serialize(function_metadata)
@@ -183,10 +185,10 @@ The artifact metadata stores all data that is not contained within the contract
 ```rust
 artifact_metadata_crh(
   artifact // This type is out of protocol, e.g. the format output by Nargo
-) -> [u8; 32] {
+) -> Field {
   let artifact_metadata = omit(artifact, "functions", "file_map");
 
-  let artifact_metadata_hash: [u8; 32] = sha256(
+  let artifact_metadata_hash: Field = sha256_modulo(
     be_string_to_bits("az_artifact_metadata"),
 
     json_serialize(artifact_metadata)

yellow-paper/docs/cryptography/merkle-trees.md

@@ -40,10 +40,6 @@ The leaves of a tree are indexed from `0`. The first, [left-most](#orientation)
 
 All nodes of the tree (including the leaves) can be indexed. The method of indexing might depend on the algorithm being applied to the tree.
 
-### Relationships
-
-The terms "parent", "child", "sibling", "ancestor", "descendant", are the well-known definitions.
-
 ### Path
 
 The path from (or "of") a particular node is a vector of that node's ancestors. That is, the node's parent, then its parent's parent, and so on, all the way up to and including the root.
@@ -53,6 +49,15 @@ The path from (or "of") a particular node is a vector of that node's ancestors.
 The sibling path of a particular node is, loosely, a vector of the siblings of the nodes in its [path](#path), except it also includes the node's sibling, and excludes the root (which has no sibling).
 The first element in the sibling path is the node's sibling. Then, the node's parent's sibling, then its parent's parent's sibling, and so on.
 
+### Membership Witness
+
+The membership witness for a particular leaf, is the minimum data needed to prove that leaf value's existence in the tree. That is:
+
+- The leaf's [leaf index](#leaf-index)
+- The leaf's [sibling path](#sibling-path)
+
+(and the leaf value itself, of course, but we don't include that in this "membership witness" definition).
+
 ## Hashing
 
 Used for computing the parent nodes of all merkle trees.