Add comments to syscalls/deprecated_business_logic_syscall_handler module

src/syscalls/deprecated_business_logic_syscall_handler.rs

@@ -50,23 +50,34 @@ use num_traits::{One, ToPrimitive, Zero};
 /// Deprecated version of BusinessLogicSyscallHandler.
 #[derive(Debug)]
 pub struct DeprecatedBLSyscallHandler<'a, S: StateReader> {
+    /// Context of the transaction being executed
     pub(crate) tx_execution_context: TransactionExecutionContext,
     /// Events emitted by the current contract call.
     pub(crate) events: Vec<OrderedEvent>,
     /// A list of dynamically allocated segments that are expected to be read-only.
     pub(crate) read_only_segments: Vec<(Relocatable, MaybeRelocatable)>,
+    /// Manages execution resources
     pub(crate) resources_manager: ExecutionResourcesManager,
+    /// Address of the contract
     pub(crate) contract_address: Address,
+    /// Address of the caller
     pub(crate) caller_address: Address,
+    /// Messages from L2 to L1
     pub(crate) l2_to_l1_messages: Vec<OrderedL2ToL1Message>,
+    /// Context information related to the current block
     pub(crate) block_context: BlockContext,
+    /// Pointer to transaction information
     pub(crate) tx_info_ptr: Option<MaybeRelocatable>,
+    /// State of the storage related to Starknet contract
     pub(crate) starknet_storage_state: ContractStorageState<'a, S>,
+    /// Information about internal calls
     pub(crate) internal_calls: Vec<CallInfo>,
+    /// Pointer to the expected system call
     pub(crate) expected_syscall_ptr: Relocatable,
 }
 
 impl<'a, S: StateReader> DeprecatedBLSyscallHandler<'a, S> {
+    /// Constructor creates a new DeprecatedBLSyscallHandler instance
     pub fn new(
         tx_execution_context: TransactionExecutionContext,
         state: &'a mut CachedState<S>,
@@ -100,6 +111,7 @@ impl<'a, S: StateReader> DeprecatedBLSyscallHandler<'a, S> {
         }
     }
 
+    /// Constructor with default values, used for testing
     pub fn default_with(state: &'a mut CachedState<S>) -> Self {
         DeprecatedBLSyscallHandler::new_for_testing(BlockInfo::default(), Default::default(), state)
     }
@@ -110,6 +122,7 @@ impl<'a, S: StateReader> DeprecatedBLSyscallHandler<'a, S> {
             .increment_syscall_counter(syscall_name, 1);
     }
 
+    /// Constructor for testing purposes
     pub fn new_for_testing(
         block_info: BlockInfo,
         _contract_address: Address,
@@ -181,6 +194,7 @@ impl<'a, S: StateReader> DeprecatedBLSyscallHandler<'a, S> {
         Ok(())
     }
 
+    /// Checks if constructor entry points are empty
     fn constructor_entry_points_empty(
         &self,
         contract_class: CompiledClass,
@@ -195,6 +209,7 @@ impl<'a, S: StateReader> DeprecatedBLSyscallHandler<'a, S> {
         }
     }
 
+    /// Executes a constructor entry point
     fn execute_constructor_entry_point(
         &mut self,
         contract_address: &Address,
@@ -247,16 +262,18 @@ impl<'a, S: StateReader> DeprecatedBLSyscallHandler<'a, S> {
 }
 
 impl<'a, S: StateReader> DeprecatedBLSyscallHandler<'a, S> {
+    /// Emit an event.
     pub(crate) fn emit_event(
         &mut self,
         vm: &VirtualMachine,
         syscall_ptr: Relocatable,
     ) -> Result<(), SyscallHandlerError> {
+        // Read and validate the syscall request for emitting an event.
         let request = match self.read_and_validate_syscall_request("emit_event", vm, syscall_ptr) {
             Ok(DeprecatedSyscallRequest::EmitEvent(emit_event_struct)) => emit_event_struct,
             _ => return Err(SyscallHandlerError::InvalidSyscallReadRequest),
         };
-
+        // Extract keys and data.
         let keys_len = request.keys_len;
         let data_len = request.data_len;
         let order = self.tx_execution_context.n_emitted_events;
@@ -269,6 +286,7 @@ impl<'a, S: StateReader> DeprecatedBLSyscallHandler<'a, S> {
         Ok(())
     }
 
+    /// Allocate a segment in memory.
     pub(crate) fn allocate_segment(
         &mut self,
         vm: &mut VirtualMachine,
@@ -283,6 +301,7 @@ impl<'a, S: StateReader> DeprecatedBLSyscallHandler<'a, S> {
         Ok(segment_start)
     }
 
+    /// Deploy a contract.
     pub(crate) fn syscall_deploy(
         &mut self,
         vm: &VirtualMachine,
@@ -343,6 +362,7 @@ impl<'a, S: StateReader> DeprecatedBLSyscallHandler<'a, S> {
         Ok(deploy_contract_address)
     }
 
+    /// Call a contract.
     pub(crate) fn syscall_call_contract(
         &mut self,
         syscall_name: &str,
@@ -461,10 +481,12 @@ impl<'a, S: StateReader> DeprecatedBLSyscallHandler<'a, S> {
         Ok(retdata)
     }
 
+    /// Returns the block information associated with the current context.
     pub(crate) fn get_block_info(&self) -> &BlockInfo {
         &self.block_context.block_info
     }
 
+    /// Get the caller's address from a virtual machine, using the syscall pointer.
     pub(crate) fn syscall_get_caller_address(
         &mut self,
         vm: &VirtualMachine,
@@ -483,6 +505,7 @@ impl<'a, S: StateReader> DeprecatedBLSyscallHandler<'a, S> {
         Ok(self.caller_address.clone())
     }
 
+    /// Handles the delegation of an L1 handler call.
     pub(crate) fn delegate_l1_handler(
         &mut self,
         vm: &mut VirtualMachine,
@@ -491,6 +514,7 @@ impl<'a, S: StateReader> DeprecatedBLSyscallHandler<'a, S> {
         self.call_contract_and_write_response("delegate_l1_handler", vm, syscall_ptr)
     }
 
+    /// Get the contract address from a virtual machine, using the syscall pointer.
     pub(crate) fn syscall_get_contract_address(
         &mut self,
         vm: &VirtualMachine,
@@ -509,6 +533,7 @@ impl<'a, S: StateReader> DeprecatedBLSyscallHandler<'a, S> {
         Ok(self.contract_address.clone())
     }
 
+    /// Sends a message from L2 to L1, including the destination address and payload.
     pub(crate) fn send_message_to_l1(
         &mut self,
         vm: &VirtualMachine,
@@ -538,6 +563,7 @@ impl<'a, S: StateReader> DeprecatedBLSyscallHandler<'a, S> {
         Ok(())
     }
 
+    /// Get the pointer to transaction information.
     pub(crate) fn syscall_get_tx_info_ptr(
         &mut self,
         vm: &mut VirtualMachine,
@@ -564,6 +590,7 @@ impl<'a, S: StateReader> DeprecatedBLSyscallHandler<'a, S> {
         Ok(tx_info_ptr_temp)
     }
 
+    /// Performs a storage read operation.
     pub(crate) fn storage_read(
         &mut self,
         vm: &mut VirtualMachine,
@@ -586,6 +613,7 @@ impl<'a, S: StateReader> DeprecatedBLSyscallHandler<'a, S> {
         response.write_syscall_response(vm, syscall_ptr)
     }
 
+    /// Performs a storage write operation.
     pub(crate) fn storage_write(
         &mut self,
         vm: &mut VirtualMachine,
@@ -607,6 +635,7 @@ impl<'a, S: StateReader> DeprecatedBLSyscallHandler<'a, S> {
         Ok(())
     }
 
+    /// Deploys a contract to the virtual machine.
     pub(crate) fn deploy(
         &mut self,
         vm: &mut VirtualMachine,
@@ -627,7 +656,7 @@ impl<'a, S: StateReader> DeprecatedBLSyscallHandler<'a, S> {
         Ok(())
     }
 
-    // Executes the contract call and fills the DeprecatedCallContractResponse struct.
+    /// Executes the contract call and fills the DeprecatedCallContractResponse struct.
     pub(crate) fn call_contract_and_write_response(
         &mut self,
         syscall_name: &str,
@@ -649,7 +678,7 @@ impl<'a, S: StateReader> DeprecatedBLSyscallHandler<'a, S> {
 
         self.write_syscall_response(&response, vm, syscall_ptr)
     }
-
+    /// Writes the response of a syscall to the virtual machine.
     pub(crate) fn write_syscall_response<R: DeprecatedWriteSyscallResponse>(
         &self,
         response: &R,
@@ -659,6 +688,7 @@ impl<'a, S: StateReader> DeprecatedBLSyscallHandler<'a, S> {
         response.write_syscall_response(vm, syscall_ptr)
     }
 
+    /// Get the block number
     pub(crate) fn get_block_number(
         &mut self,
         vm: &mut VirtualMachine,
@@ -669,6 +699,7 @@ impl<'a, S: StateReader> DeprecatedBLSyscallHandler<'a, S> {
             .write_syscall_response(vm, syscall_ptr)
     }
 
+    /// Get the transactino info.
     pub(crate) fn get_tx_info(
         &mut self,
         vm: &mut VirtualMachine,
@@ -686,6 +717,7 @@ impl<'a, S: StateReader> DeprecatedBLSyscallHandler<'a, S> {
         response.write_syscall_response(vm, syscall_ptr)
     }
 
+    /// Get the transaction signature.
     pub(crate) fn get_tx_signature(
         &mut self,
         vm: &mut VirtualMachine,
@@ -709,6 +741,7 @@ impl<'a, S: StateReader> DeprecatedBLSyscallHandler<'a, S> {
         response.write_syscall_response(vm, syscall_ptr)
     }
 
+    /// Get the time stamp of the block.
     pub(crate) fn get_block_timestamp(
         &mut self,
         vm: &mut VirtualMachine,
@@ -731,6 +764,7 @@ impl<'a, S: StateReader> DeprecatedBLSyscallHandler<'a, S> {
         response.write_syscall_response(vm, syscall_ptr)
     }
 
+    /// Get the caller address.
     pub(crate) fn get_caller_address(
         &mut self,
         vm: &mut VirtualMachine,
@@ -741,6 +775,7 @@ impl<'a, S: StateReader> DeprecatedBLSyscallHandler<'a, S> {
         response.write_syscall_response(vm, syscall_ptr)
     }
 
+    /// Get the contract address
     pub(crate) fn get_contract_address(
         &mut self,
         vm: &mut VirtualMachine,
@@ -751,6 +786,7 @@ impl<'a, S: StateReader> DeprecatedBLSyscallHandler<'a, S> {
         response.write_syscall_response(vm, syscall_ptr)
     }
 
+    /// Get the sequencer address
     pub(crate) fn get_sequencer_address(
         &mut self,
         vm: &mut VirtualMachine,
@@ -773,6 +809,7 @@ impl<'a, S: StateReader> DeprecatedBLSyscallHandler<'a, S> {
         response.write_syscall_response(vm, syscall_ptr)
     }
 
+    /// Executes a library call
     pub(crate) fn library_call(
         &mut self,
         vm: &mut VirtualMachine,
@@ -781,6 +818,7 @@ impl<'a, S: StateReader> DeprecatedBLSyscallHandler<'a, S> {
         self.call_contract_and_write_response("library_call", vm, syscall_ptr)
     }
 
+    /// Executes a library call specific to an L1 handler
     pub(crate) fn library_call_l1_handler(
         &mut self,
         vm: &mut VirtualMachine,
@@ -789,6 +827,7 @@ impl<'a, S: StateReader> DeprecatedBLSyscallHandler<'a, S> {
         self.call_contract_and_write_response("library_call_l1_handler", vm, syscall_ptr)
     }
 
+    /// Executes a contract call
     pub(crate) fn call_contract(
         &mut self,
         vm: &mut VirtualMachine,
@@ -797,6 +836,7 @@ impl<'a, S: StateReader> DeprecatedBLSyscallHandler<'a, S> {
         self.call_contract_and_write_response("call_contract", vm, syscall_ptr)
     }
 
+    /// Executes a delegate call
     pub(crate) fn delegate_call(
         &mut self,
         vm: &mut VirtualMachine,
@@ -805,6 +845,7 @@ impl<'a, S: StateReader> DeprecatedBLSyscallHandler<'a, S> {
         self.call_contract_and_write_response("delegate_call", vm, syscall_ptr)
     }
 
+    /// Reads a value from the storage state using the specified address.
     pub(crate) fn syscall_storage_read(
         &mut self,
         address: Address,
@@ -814,6 +855,7 @@ impl<'a, S: StateReader> DeprecatedBLSyscallHandler<'a, S> {
             .read(&felt_to_hash(&address.0))?)
     }
 
+    /// Writes a value to the storage state using the specified address.
     pub(crate) fn syscall_storage_write(
         &mut self,
         address: Address,
@@ -825,6 +867,7 @@ impl<'a, S: StateReader> DeprecatedBLSyscallHandler<'a, S> {
         Ok(())
     }
 
+    /// Reads and validates a syscall request, and updates the expected syscall pointer offset.
     pub(crate) fn read_and_validate_syscall_request(
         &mut self,
         syscall_name: &str,
@@ -838,6 +881,7 @@ impl<'a, S: StateReader> DeprecatedBLSyscallHandler<'a, S> {
         Ok(syscall_request)
     }
 
+    /// Reads and validates syscall requests. Matches syscall names to their corresponding requests.
     pub(crate) fn read_syscall_request(
         &self,
         syscall_name: &str,
@@ -876,6 +920,7 @@ impl<'a, S: StateReader> DeprecatedBLSyscallHandler<'a, S> {
         }
     }
 
+    /// Replaces class at the specified address with a new one based on the request.
     pub(crate) fn replace_class(
         &mut self,
         vm: &mut VirtualMachine,
@@ -897,7 +942,8 @@ impl<'a, S: StateReader> DeprecatedBLSyscallHandler<'a, S> {
 
         Ok(())
     }
-
+    /// Performs validation after the Virtual Machine run. Validates that the stopping pointer is as expected,
+    /// and validates that the read only segments have not been altered.
     pub(crate) fn post_run(
         &self,
         runner: &mut VirtualMachine,
@@ -914,6 +960,7 @@ impl<'a, S: StateReader> DeprecatedBLSyscallHandler<'a, S> {
     }
 }
 
+/// Test module for the syscalls.
 #[cfg(test)]
 mod tests {
     use crate::{
@@ -941,6 +988,7 @@ mod tests {
     type DeprecatedBLSyscallHandler<'a> =
         super::DeprecatedBLSyscallHandler<'a, InMemoryStateReader>;
 
+    /// Tests that the hint application doesn't allow inconsistency in memory.
     #[test]
     fn run_alloc_hint_ap_is_not_empty() {
         let hint_code = "memory[ap] = segments.add()";
@@ -958,6 +1006,7 @@ mod tests {
         );
     }
 
+    /// Tests error handling when trying to deploy from address zero.
     #[test]
     fn deploy_from_zero_error() {
         let mut state = CachedState::<InMemoryStateReader>::default();
@@ -984,6 +1033,7 @@ mod tests {
         )
     }
 
+    /// Tests if a segment can be allocated successfully.
     #[test]
     fn can_allocate_segment() {
         let mut state = CachedState::<InMemoryStateReader>::default();
@@ -1000,6 +1050,7 @@ mod tests {
         assert_eq!(expected_value, 7.into());
     }
 
+    /// Tests if the block number can be retrieved successfully.
     #[test]
     fn test_get_block_number() {
         let mut state = CachedState::<InMemoryStateReader>::default();
@@ -1020,6 +1071,7 @@ mod tests {
         );
     }
 
+    /// Tests if the contract address can be retrieved successfully.
     #[test]
     fn test_get_contract_address_ok() {
         let mut state = CachedState::<InMemoryStateReader>::default();
@@ -1037,6 +1089,7 @@ mod tests {
         )
     }
 
+    /// Tests if the empty storage read returns zero.
     #[test]
     fn test_storage_read_empty() {
         let mut state = CachedState::<InMemoryStateReader>::default();