docs: improve docs (#591)

* docs: improve docs

* refactor: removed unused fields

* improve docs

* docs: add captions

* docs: add gas_used

---------

Co-authored-by: Elias Tazartes <[email protected]>

README.md

@@ -61,7 +61,7 @@ This repository is a rewrite of
   always matches the one used by Kakarot, you can install Scarb
   [via asdf](https://docs.swmansion.com/scarb/download#install-via-asdf).
 
-- Install [Bun](https://bun.sh/docs/installation) to run the JavaScipt scripts
+- Install [Bun](https://bun.sh/docs/installation) to run the JavaScript scripts
   to compute the Starknet address.
 
 - [Fork](https://docs.github.com/en/get-started/quickstart/fork-a-repo) the

crates/contracts/src/kakarot_core/kakarot.cairo

@@ -365,7 +365,7 @@ mod KakarotCore {
         }
 
         /// Maps an EVM address to a Starknet address
-        /// Triggerred when deployment of an EOA or CA is successful
+        /// Triggered when deployment of an EOA or CA is successful
         fn set_address_registry(
             ref self: ContractState, evm_address: EthAddress, account: StoredAccountType
         ) {

crates/contracts/src/tests/test_kakarot_core.cairo

@@ -94,7 +94,7 @@ fn test_kakarot_core_deploy_eoa() {
     let (native_token, kakarot_core) = contract_utils::setup_contracts_for_testing();
     let eoa_starknet_address = kakarot_core.deploy_eoa(test_utils::evm_address());
     // We drop the first event of Kakarot Core, as it is the initializer from Ownable,
-    // triggerred in the constructor
+    // triggered in the constructor
     contract_utils::drop_event(kakarot_core.contract_address);
 
     let event = contract_utils::pop_log::<KakarotCore::EOADeployed>(kakarot_core.contract_address)
@@ -405,7 +405,7 @@ fn test_eth_send_transaction_deploy_tx() {
 fn test_contract_account_class_hash() {
     let kakarot_core = contract_utils::deploy_kakarot_core(test_utils::native_token());
     // We drop the first event of Kakarot Core, as it is the initializer from Ownable,
-    // triggerred in the constructor
+    // triggered in the constructor
     contract_utils::drop_event(kakarot_core.contract_address);
 
     let class_hash = kakarot_core.ca_class_hash();
@@ -429,7 +429,7 @@ fn test_contract_account_class_hash() {
 fn test_account_class_hash() {
     let kakarot_core = contract_utils::deploy_kakarot_core(test_utils::native_token());
     // We drop the first event of Kakarot Core, as it is the initializer from Ownable,
-    // triggerred in the constructor
+    // triggered in the constructor
     contract_utils::drop_event(kakarot_core.contract_address);
 
     let class_hash = kakarot_core.account_class_hash();
@@ -455,7 +455,7 @@ fn test_account_class_hash() {
 fn test_eoa_class_hash() {
     let kakarot_core = contract_utils::deploy_kakarot_core(test_utils::native_token());
     // We drop the first event of Kakarot Core, as it is the initializer from Ownable,
-    // triggerred in the constructor
+    // triggered in the constructor
     contract_utils::drop_event(kakarot_core.contract_address);
 
     let class_hash = kakarot_core.eoa_class_hash();

crates/evm/src/context.cairo

@@ -136,9 +136,6 @@ struct ExecutionContext {
     program_counter: u32,
     status: Status,
     call_ctx: Box<CallContext>,
-    destroyed_contracts: Array<EthAddress>,
-    events: Array<Event>,
-    create_addresses: Array<EthAddress>,
     // Return data of a child context.
     return_data: Span<u8>,
     parent_ctx: Nullable<ExecutionContext>,
@@ -185,9 +182,6 @@ impl ExecutionContextImpl of ExecutionContextTrait {
             program_counter: Default::default(),
             status: Default::default(),
             call_ctx: BoxTrait::new(call_ctx),
-            destroyed_contracts: Default::default(),
-            events: Default::default(),
-            create_addresses: Default::default(),
             return_data,
             parent_ctx,
         }
@@ -224,21 +218,6 @@ impl ExecutionContextImpl of ExecutionContextTrait {
         (*self.call_ctx).unbox()
     }
 
-    #[inline(always)]
-    fn destroyed_contracts(self: @ExecutionContext) -> Span<EthAddress> {
-        self.destroyed_contracts.span()
-    }
-
-    #[inline(always)]
-    fn events(self: @ExecutionContext) -> Span<Event> {
-        self.events.span()
-    }
-
-    #[inline(always)]
-    fn create_addresses(self: @ExecutionContext) -> Span<EthAddress> {
-        self.create_addresses.span()
-    }
-
     #[inline(always)]
     fn return_data(self: @ExecutionContext) -> Span<u8> {
         *self.return_data
@@ -359,12 +338,6 @@ impl ExecutionContextImpl of ExecutionContextTrait {
         *self.program_counter
     }
 
-
-    #[inline(always)]
-    fn append_event(ref self: ExecutionContext, event: Event) {
-        self.events.append(event);
-    }
-
     fn origin(ref self: ExecutionContext) -> Address {
         if (self.is_root()) {
             return self.call_ctx().caller();

crates/evm/src/execution.cairo

@@ -94,29 +94,15 @@ fn execute(
     let address = machine.address();
     let status = machine.status();
     let return_data = machine.return_data();
-    let destroyed_contracts = machine.destroyed_contracts();
-    let create_addresses = machine.create_addresses();
-    let events = machine.events();
-    ExecutionResult {
-        address,
-        status,
-        return_data,
-        destroyed_contracts,
-        create_addresses,
-        events,
-        state: machine.state,
-    }
+    ExecutionResult { address, status, return_data, state: machine.state }
 }
 
 fn reverted_with_err(mut machine: Machine, error: EVMError) -> ExecutionResult {
     let return_data = Into::<felt252, u256>::into(error.to_string()).to_bytes();
     ExecutionResult {
         address: machine.address(),
         status: Status::Reverted,
-        return_data,
-        destroyed_contracts: Default::default().span(),
-        create_addresses: Default::default().span(),
-        events: Default::default().span(),
+        return_data: Default::default().span(),
         state: machine.state,
     }
 }

crates/evm/src/instructions/logging_operations.cairo

@@ -48,6 +48,7 @@ mod internal {
     use evm::memory::MemoryTrait;
     use evm::model::Event;
     use evm::stack::StackTrait;
+    use evm::state::StateTrait;
 
     /// Store a new event in the dynamic context using topics
     /// popped from the stack and data from the memory.
@@ -70,7 +71,7 @@ mod internal {
         self.memory.load_n(size, ref data, offset);
 
         let event: Event = Event { keys: topics, data };
-        self.append_event(event);
+        self.state.add_event(event);
 
         Result::Ok(())
     }

crates/evm/src/instructions/sha3.cairo

@@ -14,7 +14,7 @@ impl Sha3Impl of Sha3Trait {
     /// and push the hash result to the stack.
     ///
     /// # Inputs
-    /// * `offset` - The offset in memory where to read the datas
+    /// * `offset` - The offset in memory where to read the data
     /// * `size` - The amount of bytes to read
     ///
     /// # Specification: https://www.evm.codes/#20?fork=shanghai

crates/evm/src/instructions/stop_and_arithmetic_operations.cairo

@@ -54,7 +54,7 @@ impl StopAndArithmeticOperations of StopAndArithmeticOperationsTrait {
     fn exec_sub(ref self: Machine) -> Result<(), EVMError> {
         let popped = self.stack.pop_n(2)?;
 
-        // Compute the substraction
+        // Compute the subtraction
         let (result, _) = u256_overflow_sub(*popped[0], *popped[1]);
 
         self.stack.push(result)

crates/evm/src/machine.cairo

@@ -194,30 +194,6 @@ impl MachineImpl of MachineTrait {
         Result::Ok(())
     }
 
-    #[inline(always)]
-    fn destroyed_contracts(ref self: Machine) -> Span<EthAddress> {
-        let current_execution_ctx = self.current_ctx.unbox();
-        let destroyed_contracts = current_execution_ctx.destroyed_contracts.span();
-        self.current_ctx = BoxTrait::new(current_execution_ctx);
-        destroyed_contracts
-    }
-
-    #[inline(always)]
-    fn events(ref self: Machine) -> Span<Event> {
-        let current_execution_ctx = self.current_ctx.unbox();
-        let events = current_execution_ctx.events.span();
-        self.current_ctx = BoxTrait::new(current_execution_ctx);
-        events
-    }
-
-    #[inline(always)]
-    fn create_addresses(ref self: Machine) -> Span<EthAddress> {
-        let current_execution_ctx = self.current_ctx.unbox();
-        let create_addresses = current_execution_ctx.create_addresses.span();
-        self.current_ctx = BoxTrait::new(current_execution_ctx);
-        create_addresses
-    }
-
     #[inline(always)]
     fn return_data(ref self: Machine) -> Span<u8> {
         let current_execution_ctx = self.current_ctx.unbox();
@@ -263,13 +239,6 @@ impl MachineImpl of MachineTrait {
         current_call_ctx.read_only()
     }
 
-    #[inline(always)]
-    fn append_event(ref self: Machine, event: Event) {
-        let mut current_execution_ctx = self.current_ctx.unbox();
-        current_execution_ctx.append_event(event);
-        self.current_ctx = BoxTrait::new(current_execution_ctx);
-    }
-
     #[inline(always)]
     fn gas_limit(ref self: Machine) -> u128 {
         let current_call_ctx = self.call_ctx();
@@ -345,7 +314,7 @@ impl MachineImpl of MachineTrait {
     }
 
     /// Sets the `return_data` field of the appropriate execution context,
-    /// taking into acount EVM specs: If the current context is the root
+    /// taking into account EVM specs: If the current context is the root
     /// context, sets the return_data field of the root context.  If the current
     /// context is a subcontext, sets the return_data field of the parent.
     /// Should be called when returning from a context.

crates/evm/src/model.cairo

@@ -60,9 +60,6 @@ struct ExecutionResult {
     address: Address,
     status: Status,
     return_data: Span<u8>,
-    create_addresses: Span<EthAddress>,
-    destroyed_contracts: Span<EthAddress>,
-    events: Span<Event>,
     state: State,
 }
 

crates/evm/src/model/account.cairo

@@ -231,7 +231,7 @@ impl AccountImpl of AccountTrait {
                 initial_code,
                 deploy_starknet_contract: !is_deployed
             )?;
-        //Storage is handled outside of the account and must be commited after all accounts are commited.
+        //Storage is handled outside of the account and must be committed after all accounts are committed.
         //TODO(bug) uncommenting this bugs, needs to be removed when fixed in the compiler
         // return Result::Ok(());
         };
@@ -241,7 +241,7 @@ impl AccountImpl of AccountTrait {
         };
 
         // If the account was not scheduled for deployment - then update it if it's deployed.
-        // Only CAs have components commited on starknet.
+        // Only CAs have components committed on starknet.
         if is_deployed && is_ca {
             if *self.selfdestruct {
                 return ContractAccountTrait::selfdestruct(self);

crates/evm/src/model/contract_account.cairo

@@ -41,7 +41,7 @@ impl ContractAccountImpl of ContractAccountTrait {
     /// storing the contract bytecode and emitting a ContractAccountDeployed
     /// event.
     ///
-    /// `deploy` is only called when commiting a transaction. We already
+    /// `deploy` is only called when committing a transaction. We already
     /// checked that no account exists at this address prealably.
     /// # Arguments
     /// * `origin` - The EVM address of the transaction sender

crates/evm/src/stack.cairo

@@ -219,7 +219,7 @@ impl StackImpl of StackTrait {
     ///
     /// # Errors
     ///
-    /// If the index is greather than the stack length, returns with a StackUnderflow error.
+    /// If the index is greater than the stack length, returns with a StackUnderflow error.
     #[inline(always)]
     fn peek_at(ref self: Stack, index: usize) -> Result<u256, EVMError> {
         if index >= self.len() {

crates/evm/src/state.cairo

@@ -232,7 +232,7 @@ impl StateImpl of StateTrait {
         match maybe_entry {
             Option::Some((_, key, value)) => { return Result::Ok(value); },
             Option::None => {
-                let account = AccountTrait::fetch_or_create(evm_address);
+                let account = self.get_account(evm_address);
                 return account.read_storage(key);
             }
         }

crates/evm/src/tests/test_execution_context.cairo

@@ -63,9 +63,7 @@ fn test_execution_context_new() {
     let return_data: Array<u8> = ArrayTrait::new();
 
     let address: Address = Default::default();
-    let destroyed_contracts: Array<EthAddress> = Default::default();
     let events: Array<Event> = Default::default();
-    let create_addresses: Array<EthAddress> = Default::default();
     let revert_contract_state: Felt252Dict<felt252> = Default::default();
     let reverted: bool = false;
     let read_only: bool = false;
@@ -83,14 +81,6 @@ fn test_execution_context_new() {
     assert(execution_context.stopped() == stopped, 'wrong stopped');
     assert(execution_context.return_data() == Default::default().span(), 'wrong return_data');
     assert(execution_context.address() == address, 'wrong evm_address');
-    assert(
-        execution_context.destroyed_contracts() == destroyed_contracts.span(),
-        'wrong destroyed_contracts'
-    );
-    assert(execution_context.events().len() == events.len(), 'wrong events');
-    assert(
-        execution_context.create_addresses() == create_addresses.span(), 'wrong create_addresses'
-    );
     assert(execution_context.reverted() == reverted, 'wrong reverted');
     assert(execution_context.is_create() == false, 'wrong is_create');
 }

crates/evm/src/tests/test_instructions/test_logging_operations.cairo

@@ -3,6 +3,7 @@ use evm::instructions::LoggingOperationsTrait;
 use evm::machine::{Machine, MachineTrait};
 use evm::memory::MemoryTrait;
 use evm::stack::StackTrait;
+use evm::state::StateTrait;
 use evm::tests::test_utils::{MachineBuilderTestTrait};
 use integer::BoundedInt;
 use utils::helpers::u256_to_bytes_array;
@@ -24,7 +25,7 @@ fn test_exec_log0() {
     assert(result.is_ok(), 'should have succeeded');
     assert(machine.stack.len() == 0, 'stack should be empty');
 
-    let mut events = machine.events();
+    let mut events = machine.state.events.contextual_logs;
     assert(events.len() == 1, 'context should have one event');
 
     let event = events.pop_front().unwrap();
@@ -53,7 +54,7 @@ fn test_exec_log1() {
     assert(result.is_ok(), 'should have succeeded');
     assert(machine.stack.len() == 0, 'stack should be empty');
 
-    let mut events = machine.events();
+    let mut events = machine.state.events.contextual_logs;
     assert(events.len() == 1, 'context should have one event');
 
     let event = events.pop_front().unwrap();
@@ -84,7 +85,7 @@ fn test_exec_log2() {
     assert(result.is_ok(), 'should have succeeded');
     assert(machine.stack.len() == 0, 'stack should be empty');
 
-    let mut events = machine.events();
+    let mut events = machine.state.events.contextual_logs;
     assert(events.len() == 1, 'context should have one event');
 
     let event = events.pop_front().unwrap();
@@ -118,7 +119,7 @@ fn test_exec_log3() {
     assert(result.is_ok(), 'should have succeeded');
     assert(machine.stack.len() == 0, 'stack should be empty');
 
-    let mut events = machine.events();
+    let mut events = machine.state.events.contextual_logs;
     assert(events.len() == 1, 'context should have one event');
 
     let event = events.pop_front().unwrap();
@@ -156,7 +157,7 @@ fn test_exec_log4() {
     assert(result.is_ok(), 'should have succeeded');
     assert(machine.stack.len() == 0, 'stack should be empty');
 
-    let mut events = machine.events();
+    let mut events = machine.state.events.contextual_logs;
     assert(events.len() == 1, 'context should have one event');
 
     let event = events.pop_front().unwrap();
@@ -211,7 +212,7 @@ fn test_exec_log1_size_0_offset_0() {
     assert(result.is_ok(), 'should have succeeded');
     assert(machine.stack.len() == 0, 'stack should be empty');
 
-    let mut events = machine.events();
+    let mut events = machine.state.events.contextual_logs;
     assert(events.len() == 1, 'context should have one event');
 
     let event = events.pop_front().unwrap();
@@ -293,7 +294,7 @@ fn test_exec_log_multiple_events() {
     assert(result.is_ok(), 'should have succeeded');
     assert(machine.stack.len() == 0, 'stack size should be 0');
 
-    let mut events = machine.events();
+    let mut events = machine.state.events.contextual_logs;
     assert(events.len() == 2, 'context should have 2 events');
 
     let event1 = events.pop_front().unwrap();

crates/evm/src/tests/test_instructions/test_memory_operations.cairo

@@ -463,7 +463,7 @@ fn test_exec_jumpi_invalid_zero() {
 
     // Then
     let pc = machine.pc();
-    // ideally we should assert that it incremented, but incrementing is done by `decode_and_execut`
+    // ideally we should assert that it incremented, but incrementing is done by `decode_and_execute`
     // so we can assume that will be done
     assert(pc == old_pc, 'PC should be same');
 }
@@ -610,7 +610,7 @@ fn test_exec_sstore_finalized() {
     machine.state.commit_storage();
 
     // Then
-    assert(account.fetch_storage(key).unwrap() == value, 'wrong value in journal')
+    assert(account.fetch_storage(key).unwrap() == value, 'wrong committed value')
 }
 
 #[test]