refactor: Rename root_is_on_right to sibling_is_on_right for clarity (#1422)

zlangley · web-flow · commit 9f360e567ab4 · 2025-03-12T09:06:04.000-07:00
Renames the variable `root_is_on_right` to `sibling_is_on_right`
throughout the codebase to better reflect its meaning. The field
represents whether the sibling in the Merkle tree is on the right, not
the root.
diff --git a/extensions/native/circuit/src/poseidon2/air.rs b/extensions/native/circuit/src/poseidon2/air.rs
@@ -327,9 +327,9 @@ impl<AB: InteractionBuilder, const SBOX_REGISTERS: usize> Air<AB>
             index_base_pointer_read,
             commit_pointer_read,
             proof_index,
-            read_initial_height_or_root_is_on_right,
+            read_initial_height_or_sibling_is_on_right,
             read_final_height,
-            root_is_on_right,
+            sibling_is_on_right,
             commit_pointer,
             commit_read,
         } = top_level_specific;
@@ -502,7 +502,7 @@ impl<AB: InteractionBuilder, const SBOX_REGISTERS: usize> Air<AB>
                 MemoryAddress::new(self.address_space, dim_base_pointer + initial_opened_index),
                 [log_height],
                 end_timestamp - AB::F::TWO,
-                &read_initial_height_or_root_is_on_right,
+                &read_initial_height_or_sibling_is_on_right,
             )
             .eval(builder, incorporate_row);
         self.memory_bridge
@@ -532,20 +532,20 @@ impl<AB: InteractionBuilder, const SBOX_REGISTERS: usize> Air<AB>
         self.memory_bridge
             .read(
                 MemoryAddress::new(self.address_space, index_base_pointer + proof_index),
-                [root_is_on_right],
+                [sibling_is_on_right],
                 timestamp_after_initial_reads.clone(),
-                &read_initial_height_or_root_is_on_right,
+                &read_initial_height_or_sibling_is_on_right,
             )
             .eval(builder, incorporate_sibling);
 
         for i in 0..CHUNK {
             builder
                 .when(next.incorporate_sibling)
-                .when(next_top_level_specific.root_is_on_right)
+                .when(next_top_level_specific.sibling_is_on_right)
                 .assert_eq(next_right_input[i], left_output[i]);
             builder
                 .when(next.incorporate_sibling)
-                .when(AB::Expr::ONE - next_top_level_specific.root_is_on_right)
+                .when(AB::Expr::ONE - next_top_level_specific.sibling_is_on_right)
                 .assert_eq(next_left_input[i], left_output[i]);
         }
 
diff --git a/extensions/native/circuit/src/poseidon2/chip.rs b/extensions/native/circuit/src/poseidon2/chip.rs
@@ -65,8 +65,8 @@ pub struct TopLevelRecord<F: Field> {
 #[derive(Debug, Clone, Serialize, Deserialize)]
 #[serde(bound = "F: Field")]
 pub struct IncorporateSiblingRecord<F: Field> {
-    pub read_root_is_on_right: RecordId,
-    pub root_is_on_right: bool,
+    pub read_sibling_is_on_right: RecordId,
+    pub sibling_is_on_right: bool,
     pub p2_input: [F; 2 * CHUNK],
 }
 
@@ -432,13 +432,13 @@ impl<F: PrimeField32, const SBOX_REGISTERS: usize> InstructionExecutor<F>
                         memory.increment_timestamp();
                     }
 
-                    let (read_root_is_on_right, root_is_on_right) = memory.read_cell(
+                    let (read_sibling_is_on_right, sibling_is_on_right) = memory.read_cell(
                         address_space,
                         index_base_pointer + F::from_canonical_usize(sibling_index),
                     );
-                    let root_is_on_right = root_is_on_right == F::ONE;
+                    let sibling_is_on_right = sibling_is_on_right == F::ONE;
                     let sibling = sibling_proof[sibling_index];
-                    let (p2_input, new_root) = if root_is_on_right {
+                    let (p2_input, new_root) = if sibling_is_on_right {
                         self.compress(sibling, root)
                     } else {
                         self.compress(root, sibling)
@@ -447,8 +447,8 @@ impl<F: PrimeField32, const SBOX_REGISTERS: usize> InstructionExecutor<F>
 
                     self.height += 1;
                     Some(IncorporateSiblingRecord {
-                        read_root_is_on_right,
-                        root_is_on_right,
+                        read_sibling_is_on_right,
+                        sibling_is_on_right,
                         p2_input,
                     })
                 };
diff --git a/extensions/native/circuit/src/poseidon2/columns.rs b/extensions/native/circuit/src/poseidon2/columns.rs
@@ -127,16 +127,16 @@ pub struct TopLevelSpecificCols<T> {
     /// Starts at zero in a top-level block and increments by one after each `incorporate_sibling` row.
     pub proof_index: T,
 
-    /// Memory aux columns for either `initial_height` or `root_is_on_right`. On an `incorporate_row`
-    /// row, aux columns for reading `dims[initial_opened_index]`, and otherwise aux columns for
-    /// `index_bits[proof_index]`.
-    pub read_initial_height_or_root_is_on_right: MemoryReadAuxCols<T>,
+    /// Memory aux columns for reading either `initial_height` or `sibling_is_on_right`. On an
+    /// `incorporate_row` row, aux columns for reading `dims[initial_opened_index]`, and otherwise
+    /// aux columns for `index_bits[proof_index]`.
+    pub read_initial_height_or_sibling_is_on_right: MemoryReadAuxCols<T>,
     /// Memory aux columns for reading `dims[final_opened_index]`.
     pub read_final_height: MemoryReadAuxCols<T>,
 
-    /// Indicator for whether `root_is_on_right`. Constrained to equal `index_bits[proof_index]` on
-    /// `incorporate_sibling` rows. Unconstrained on other rows.
-    pub root_is_on_right: T,
+    /// Indicator for whether the sibling being incorporated (if any) is on the right. Constrained
+    /// to equal `index_bits[proof_index]` on `incorporate_sibling` rows. Unconstrained on other rows.
+    pub sibling_is_on_right: T,
     /// Pointer to the Merkle root.
     pub commit_pointer: T,
     /// Memory aux columns for reading the Merkle root.
diff --git a/extensions/native/circuit/src/poseidon2/tests.rs b/extensions/native/circuit/src/poseidon2/tests.rs
@@ -44,7 +44,7 @@ fn compute_commit<F: Field>(
     dim: &[usize],
     opened: &[Vec<F>],
     proof: &[[F; CHUNK]],
-    root_is_on_right: &[bool],
+    sibling_is_on_right: &[bool],
     hash_function: impl Fn([F; CHUNK], [F; CHUNK]) -> ([F; CHUNK], [F; CHUNK]),
 ) -> [F; CHUNK] {
     let mut log_height = dim[0] as isize;
@@ -73,7 +73,7 @@ fn compute_commit<F: Field>(
         }
         if log_height > 0 {
             let sibling = proof[proof_index];
-            let (left, right) = if root_is_on_right[proof_index] {
+            let (left, right) = if sibling_is_on_right[proof_index] {
                 (sibling, root)
             } else {
                 (root, sibling)
@@ -93,7 +93,7 @@ struct VerifyBatchInstance {
     dim: Vec<usize>,
     opened: Vec<Vec<F>>,
     proof: Vec<[F; CHUNK]>,
-    root_is_on_right: Vec<bool>,
+    sibling_is_on_right: Vec<bool>,
     commit: [F; CHUNK],
 }
 
@@ -106,7 +106,7 @@ fn random_instance(
     let mut dims = vec![];
     let mut opened = vec![];
     let mut proof = vec![];
-    let mut root_is_on_right = vec![];
+    let mut sibling_is_on_right = vec![];
     for (log_height, row_lengths) in row_lengths.iter().enumerate() {
         for &row_length in row_lengths {
             dims.push(log_height);
@@ -118,22 +118,22 @@ fn random_instance(
         }
         if log_height > 0 {
             proof.push(std::array::from_fn(|_| rng.gen()));
-            root_is_on_right.push(rng.gen());
+            sibling_is_on_right.push(rng.gen());
         }
     }
 
     dims.reverse();
     opened.reverse();
     proof.reverse();
-    root_is_on_right.reverse();
+    sibling_is_on_right.reverse();
 
-    let commit = compute_commit(&dims, &opened, &proof, &root_is_on_right, hash_function);
+    let commit = compute_commit(&dims, &opened, &proof, &sibling_is_on_right, hash_function);
 
     VerifyBatchInstance {
         dim: dims,
         opened,
         proof,
-        root_is_on_right,
+        sibling_is_on_right,
         commit,
     }
 }
@@ -184,7 +184,7 @@ fn test<const N: usize>(cases: [Case; N]) {
             dim,
             opened,
             proof,
-            root_is_on_right,
+            sibling_is_on_right,
             commit,
         } = instance;
 
@@ -225,7 +225,7 @@ fn test<const N: usize>(cases: [Case; N]) {
             .hint_space
             .push(proof.iter().flatten().copied().collect());
         drop(streams);
-        for (i, &bit) in root_is_on_right.iter().enumerate() {
+        for (i, &bit) in sibling_is_on_right.iter().enumerate() {
             tester.write_cell(address_space, index_base_pointer + i, F::from_bool(bit));
         }
         tester.write(address_space, commit_pointer, commit);
diff --git a/extensions/native/circuit/src/poseidon2/trace.rs b/extensions/native/circuit/src/poseidon2/trace.rs
@@ -63,12 +63,12 @@ impl<F: PrimeField32, const SBOX_REGISTERS: usize> NativePoseidon2Chip<F, SBOX_R
         log_height: usize,
     ) {
         let &IncorporateSiblingRecord {
-            read_root_is_on_right,
-            root_is_on_right,
+            read_sibling_is_on_right,
+            sibling_is_on_right,
             p2_input,
         } = record;
 
-        let read_root_is_on_right = memory.record_by_id(read_root_is_on_right);
+        let read_sibling_is_on_right = memory.record_by_id(read_sibling_is_on_right);
 
         self.generate_subair_cols(p2_input, slice);
         let cols: &mut NativePoseidon2Cols<F, SBOX_REGISTERS> = slice.borrow_mut();
@@ -82,13 +82,13 @@ impl<F: PrimeField32, const SBOX_REGISTERS: usize> NativePoseidon2Chip<F, SBOX_R
         cols.opened_element_size_inv = parent.opened_element_size_inv();
         cols.very_first_timestamp = F::from_canonical_u32(parent.from_state.timestamp);
         cols.start_timestamp =
-            F::from_canonical_u32(read_root_is_on_right.timestamp - NUM_INITIAL_READS as u32);
+            F::from_canonical_u32(read_sibling_is_on_right.timestamp - NUM_INITIAL_READS as u32);
 
         let specific: &mut TopLevelSpecificCols<F> =
             cols.specific[..TopLevelSpecificCols::<F>::width()].borrow_mut();
 
         specific.end_timestamp =
-            F::from_canonical_usize(read_root_is_on_right.timestamp as usize + 1);
+            F::from_canonical_usize(read_sibling_is_on_right.timestamp as usize + 1);
         cols.initial_opened_index = F::from_canonical_usize(opened_index);
         specific.final_opened_index = F::from_canonical_usize(opened_index - 1);
         specific.log_height = F::from_canonical_usize(log_height);
@@ -99,10 +99,10 @@ impl<F: PrimeField32, const SBOX_REGISTERS: usize> NativePoseidon2Chip<F, SBOX_R
 
         specific.proof_index = F::from_canonical_usize(proof_index);
         aux_cols_factory.generate_read_aux(
-            read_root_is_on_right,
-            &mut specific.read_initial_height_or_root_is_on_right,
+            read_sibling_is_on_right,
+            &mut specific.read_initial_height_or_sibling_is_on_right,
         );
-        specific.root_is_on_right = F::from_bool(root_is_on_right);
+        specific.sibling_is_on_right = F::from_bool(sibling_is_on_right);
     }
     fn correct_last_top_level_row(
         &self,
@@ -220,7 +220,7 @@ impl<F: PrimeField32, const SBOX_REGISTERS: usize> NativePoseidon2Chip<F, SBOX_R
         specific.proof_index = F::from_canonical_usize(proof_index);
         aux_cols_factory.generate_read_aux(
             initial_height_read,
-            &mut specific.read_initial_height_or_root_is_on_right,
+            &mut specific.read_initial_height_or_sibling_is_on_right,
         );
         aux_cols_factory.generate_read_aux(final_height_read, &mut specific.read_final_height);
     }
