Added comments to core/contract_address module (#900)

Co-authored-by: fannyguthmann <[email protected]>

Author: fguthmann

src/core/contract_address/casm_contract_address.rs

@@ -6,6 +6,7 @@ use starknet_crypto::{poseidon_hash_many, FieldElement};
 
 const CONTRACT_CLASS_VERSION: &[u8] = b"COMPILED_CLASS_V1";
 
+/// Return hashed entry points for a given contract class and entry point type.
 fn get_contract_entry_points_hashed(
     contract_class: &CasmContractClass,
     entry_point_type: &EntryPointType,
@@ -38,6 +39,7 @@ fn get_contract_entry_points_hashed(
     Ok(poseidon_hash_many(&entry_points_flatted))
 }
 
+/// Compute hash for the entire CASM contract class.
 pub fn compute_casm_class_hash(
     contract_class: &CasmContractClass,
 ) -> Result<Felt252, ContractAddressError> {
@@ -80,6 +82,7 @@ pub fn compute_casm_class_hash(
     ))
 }
 
+/// Helper function to fetch entry points based on their type.
 fn get_contract_entry_points(
     contract_class: &CasmContractClass,
     entry_point_type: &EntryPointType,

src/core/contract_address/deprecated_contract_address.rs

@@ -21,6 +21,7 @@ use std::{borrow::Cow, collections::BTreeMap, io};
 /// Instead of doing a Mask with 250 bits, we are only masking the most significant byte.
 pub const MASK_3: u8 = 0x03;
 
+/// Returns the contract entry points.
 fn get_contract_entry_points(
     contract_class: &ContractClass,
     entry_point_type: &EntryPointType,
@@ -40,6 +41,7 @@ fn get_contract_entry_points(
     Ok(entry_points.to_owned())
 }
 
+/// Recursively add extra spaces to Cairo named tuple representations in a JSON structure.
 fn add_extra_space_to_cairo_named_tuples(value: &mut serde_json::Value) {
     match value {
         serde_json::Value::Array(v) => walk_array(v),
@@ -48,12 +50,14 @@ fn add_extra_space_to_cairo_named_tuples(value: &mut serde_json::Value) {
     }
 }
 
+/// Helper function to walk through a JSON array and apply extra space to cairo named tuples.
 fn walk_array(array: &mut [serde_json::Value]) {
     for v in array.iter_mut() {
         add_extra_space_to_cairo_named_tuples(v);
     }
 }
 
+/// Helper function to walk through a JSON map and apply extra space to cairo named tuples.
 fn walk_map(object: &mut serde_json::Map<String, serde_json::Value>) {
     for (k, v) in object.iter_mut() {
         match v {
@@ -68,6 +72,7 @@ fn walk_map(object: &mut serde_json::Map<String, serde_json::Value>) {
     }
 }
 
+/// Add extra space to named tuple type definition.
 fn add_extra_space_to_named_tuple_type_definition<'a>(
     key: &str,
     value: &'a str,
@@ -79,6 +84,7 @@ fn add_extra_space_to_named_tuple_type_definition<'a>(
     }
 }
 
+/// Replaces ": " with " : " and "  :" with " :" for Cairo-specific formatting.
 fn add_extra_space_before_colon(v: &str) -> String {
     // This is required because if we receive an already correct ` : `, we will still
     // "repair" it to `  : ` which we then fix at the end.
@@ -88,11 +94,13 @@ fn add_extra_space_before_colon(v: &str) -> String {
 struct KeccakWriter(sha3::Keccak256);
 
 impl std::io::Write for KeccakWriter {
+    /// Write data into the Keccak256 hasher.
     fn write(&mut self, buf: &[u8]) -> std::io::Result<usize> {
         self.0.update(buf);
         Ok(buf.len())
     }
 
+    /// No operation is required for flushing, as we finalize after writing.
     fn flush(&mut self) -> std::io::Result<()> {
         // noop is fine, we'll finalize after the write phase
         Ok(())
@@ -104,6 +112,7 @@ impl std::io::Write for KeccakWriter {
 struct PythonDefaultFormatter;
 
 impl serde_json::ser::Formatter for PythonDefaultFormatter {
+    /// Handles formatting for array values.
     fn begin_array_value<W>(&mut self, writer: &mut W, first: bool) -> std::io::Result<()>
     where
         W: ?Sized + std::io::Write,
@@ -115,6 +124,7 @@ impl serde_json::ser::Formatter for PythonDefaultFormatter {
         }
     }
 
+    /// Handles formatting for object keys.
     fn begin_object_key<W>(&mut self, writer: &mut W, first: bool) -> std::io::Result<()>
     where
         W: ?Sized + std::io::Write,
@@ -126,13 +136,15 @@ impl serde_json::ser::Formatter for PythonDefaultFormatter {
         }
     }
 
+    /// Handles formatting for object values.
     fn begin_object_value<W>(&mut self, writer: &mut W) -> std::io::Result<()>
     where
         W: ?Sized + std::io::Write,
     {
         writer.write_all(b": ")
     }
 
+    /// Custom logic for writing string fragments, handling non-ASCII characters.
     #[inline]
     fn write_string_fragment<W>(&mut self, writer: &mut W, fragment: &str) -> io::Result<()>
     where
@@ -157,6 +169,7 @@ impl serde_json::ser::Formatter for PythonDefaultFormatter {
 
 #[derive(serde::Deserialize, serde::Serialize)]
 #[serde(deny_unknown_fields)]
+
 pub struct CairoContractDefinition<'a> {
     /// Contract ABI, which has no schema definition.
     pub abi: serde_json::Value,
@@ -268,13 +281,15 @@ pub(crate) fn compute_hinted_class_hash(
     Ok(truncated_keccak(<[u8; 32]>::from(hash.finalize())))
 }
 
+/// Truncate the given Keccak hash to fit within Felt252's constraints.
 pub(crate) fn truncated_keccak(mut plain: [u8; 32]) -> Felt252 {
     // python code masks with (2**250 - 1) which starts 0x03 and is followed by 31 0xff in be
     // truncation is needed not to overflow the field element.
     plain[0] &= MASK_3;
     Felt252::from_bytes_be(&plain)
 }
 
+/// Returns the hashed entry points of a contract class.
 fn get_contract_entry_points_hashed(
     contract_class: &ContractClass,
     entry_point_type: &EntryPointType,
@@ -292,6 +307,7 @@ fn get_contract_entry_points_hashed(
     )?)
 }
 
+/// Compute the hash for a deprecated contract class.
 pub fn compute_deprecated_class_hash(
     contract_class: &ContractClass,
 ) -> Result<Felt252, ContractAddressError> {

src/core/contract_address/sierra_contract_address.rs

@@ -12,6 +12,7 @@ const CONTRACT_CLASS_VERSION: &[u8] = b"CONTRACT_CLASS_V0.1.0";
 //  Version 2 functions and structs
 // ---------------------------------
 
+/// Computes the hash of contract entry points.
 fn get_contract_entry_points_hashed(
     contract_class: &SierraContractClass,
     entry_point_type: &EntryPointType,
@@ -33,6 +34,7 @@ fn get_contract_entry_points_hashed(
     Ok(hasher.finalize())
 }
 
+/// Computes the hash of a given Sierra contract class.
 pub fn compute_sierra_class_hash(
     contract_class: &SierraContractClass,
 ) -> Result<Felt252, ContractAddressError> {
@@ -90,6 +92,7 @@ pub fn compute_sierra_class_hash(
     Ok(Felt252::from_bytes_be(&hash.to_bytes_be()))
 }
 
+/// Returns the contract entry points.
 fn get_contract_entry_points(
     contract_class: &SierraContractClass,
     entry_point_type: &EntryPointType,
@@ -120,6 +123,7 @@ mod tests {
     use cairo_vm::felt::felt_str;
     use std::{fs::File, io::BufReader};
 
+    /// Test the correctness of the compute_sierra_class_hash function for a specific testnet contract.
     #[test]
     fn test_declare_tx_from_testnet() {
         let file = File::open("starknet_programs/cairo2/events.sierra").unwrap();