feat: v2.3.0-rc0, clean and sort codebase, add documentation

.github/workflows/gas_reports.yml

@@ -26,7 +26,7 @@ jobs:
       - name: Set up Scarb
         uses: software-mansion/setup-scarb@v1
         with:
-          scarb-version: 0.7.0
+          scarb-version: 2.3.0-rc0
 
       - name: Run compare_snapshot script
         id: run-script

.github/workflows/gas_snapshot.yml

@@ -22,7 +22,7 @@ jobs:
       - name: Set up Scarb
         uses: software-mansion/setup-scarb@v1
         with:
-          scarb-version: 0.7.0
+          scarb-version: 2.3.0-rc0
 
       - name: Generate gas snapshot
         run: python scripts/gen_snapshot.py

.github/workflows/test.yml

@@ -15,7 +15,7 @@ jobs:
       - uses: actions/checkout@v3
       - uses: software-mansion/setup-scarb@v1
         with:
-          scarb-version: 0.7.0
+          scarb-version: 2.3.0-rc0
       - run: scarb fmt --check
       - run: scarb build
       - run: scarb test

.tool-versions

@@ -1 +1 @@
-scarb 0.7.0
+scarb 2.3.0-rc0

Scarb.toml

@@ -4,13 +4,16 @@ members = ["crates/*"]
 [workspace.package]
 description = "Kakarot is an (zk)-Ethereum Virtual Machine implementation written in Cairo."
 documentation = "https://www.kakarot.org/"
-cairo-version = "2.2.0"
+cairo-version = "2.3.0-rc0"
 version = "0.1.0"
 readme = "README.md"
 repository = "https://github.com/kkrt-labs/kakarot-ssj/"
 license-file = "LICENSE"
 
 [workspace.dependencies]
-starknet = "2.2.0"
+starknet = "2.3.0-rc0"
 
 [[workspace.tool.starknet-contract]]
+
+[workspace.tool.fmt]
+sort-module-level-items = true

crates/evm/Scarb.toml

@@ -7,3 +7,6 @@ version = "0.1.0"
 [dependencies]
 starknet.workspace = true
 utils = { path = "../utils" }
+
+[tool.fmt]
+sort-module-level-items = true

crates/evm/src/context.cairo

@@ -1,11 +1,11 @@
-use evm::stack::{Stack, StackTrait};
+use debug::PrintTrait;
 use evm::memory::{Memory, MemoryTrait};
 use evm::model::Event;
-use debug::PrintTrait;
+use evm::stack::{Stack, StackTrait};
+use starknet::get_caller_address;
+use starknet::{EthAddress, ContractAddress};
 use utils::helpers::{ArrayExtension, ArrayExtensionTrait};
 use utils::traits::{SpanDefault, EthAddressDefault, ContractAddressDefault};
-use starknet::{EthAddress, ContractAddress};
-use starknet::get_caller_address;
 
 #[derive(Drop, Default, Copy, PartialEq)]
 enum Status {
@@ -125,7 +125,7 @@ impl DefaultBoxCallContext of Default<Box<CallContext>> {
 /// Stores all data relevant to the current execution context.
 #[derive(Drop, Default)]
 struct ExecutionContext {
-    context_id: usize,
+    id: usize,
     evm_address: EthAddress,
     starknet_address: ContractAddress,
     program_counter: u32,
@@ -148,12 +148,13 @@ impl DefaultBoxExecutionContext of Default<Box<ExecutionContext>> {
 
 
 /// `ExecutionContext` implementation.
+
 #[generate_trait]
 impl ExecutionContextImpl of ExecutionContextTrait {
     /// Create a new execution context instance.
     #[inline(always)]
     fn new(
-        context_id: usize,
+        id: usize,
         evm_address: EthAddress,
         starknet_address: ContractAddress,
         call_context: CallContext,
@@ -162,7 +163,7 @@ impl ExecutionContextImpl of ExecutionContextTrait {
         return_data: Array<u8>,
     ) -> ExecutionContext {
         ExecutionContext {
-            context_id,
+            id,
             evm_address,
             starknet_address,
             program_counter: Default::default(),
@@ -287,7 +288,7 @@ impl ExecutionContextImpl of ExecutionContextTrait {
 
     #[inline(always)]
     fn is_root(self: @ExecutionContext) -> bool {
-        *self.context_id == 0
+        *self.id == 0
     }
 
     // TODO: Implement print_debug
@@ -314,8 +315,3 @@ impl ExecutionContextImpl of ExecutionContextTrait {
         *self.program_counter
     }
 }
-
-
-/// The execution summary.
-#[derive(Drop, Copy)]
-struct ExecutionSummary {}

crates/evm/src/errors.cairo

@@ -22,6 +22,7 @@ enum EVMError {
     ReturnDataError: felt252,
     JumpError: felt252,
     NotImplemented,
+    UnknownOpcode: u8
 }
 
 
@@ -34,6 +35,8 @@ impl EVMErrorIntoU256 of Into<EVMError, u256> {
             EVMError::ReturnDataError(error_message) => error_message.into(),
             EVMError::JumpError(error_message) => error_message.into(),
             EVMError::NotImplemented => 'NotImplemented'.into(),
+            // TODO: refactor with dynamic strings once supported
+            EVMError::UnknownOpcode => 'UnknownOpcode'.into()
         }
     }
 }

crates/evm/src/execution.cairo

@@ -1,5 +1,4 @@
-use starknet::{ContractAddress, EthAddress};
-use evm::context::{CallContext, ExecutionContext, ExecutionSummary, ExecutionContextTrait};
+use evm::context::{CallContext, ExecutionContext};
 use evm::interpreter::EVMInterpreterTrait;
 use evm::machine::Machine;
 

crates/evm/src/helpers.cairo

@@ -1,8 +1,14 @@
 use evm::errors::{EVMError, TYPE_CONVERSION_ERROR};
 
-// Try converting u256 to u32
-impl U256IntoResultU32 of Into<u256, Result<u32, EVMError>> {
-    fn into(self: u256) -> Result<u32, EVMError> {
+trait TryIntoResult<T, U> {
+    fn try_into_result(self: T) -> Result<U, EVMError>;
+}
+
+impl U256TryIntoResultU32 of TryIntoResult<u256, u32> {
+    /// Converts a u256 into a Result<u32, EVMError>
+    /// If the u256 is larger than MAX_U32, it returns an error.
+    /// Otherwise, it returns the casted value.
+    fn try_into_result(self: u256) -> Result<u32, EVMError> {
         match self.try_into() {
             Option::Some(value) => Result::Ok(value),
             Option::None(_) => Result::Err(EVMError::TypeConversionError(TYPE_CONVERSION_ERROR))

crates/evm/src/instructions.cairo

@@ -1,32 +1,24 @@
 /// Sub modules.
 mod block_information;
-use block_information::BlockInformationTrait;
-
 mod comparison_operations;
-use comparison_operations::ComparisonAndBitwiseOperationsTrait;
 
 mod duplication_operations;
-use duplication_operations::DuplicationOperationsTrait;
-
 mod environmental_information;
-use environmental_information::EnvironmentInformationTrait;
-
 mod exchange_operations;
-use exchange_operations::ExchangeOperationsTrait;
-
 mod logging_operations;
-
 mod memory_operations;
-use memory_operations::MemoryOperationTrait;
-
 mod push_operations;
-use push_operations::PushOperationsTrait;
-
 mod sha3;
-use sha3::Sha3Trait;
-
 mod stop_and_arithmetic_operations;
-use stop_and_arithmetic_operations::StopAndArithmeticOperationsTrait;
-
 mod system_operations;
+
+use block_information::BlockInformationTrait;
+use comparison_operations::ComparisonAndBitwiseOperationsTrait;
+use duplication_operations::DuplicationOperationsTrait;
+use environmental_information::EnvironmentInformationTrait;
+use exchange_operations::ExchangeOperationsTrait;
+use memory_operations::MemoryOperationTrait;
+use push_operations::PushOperationsTrait;
+use sha3::Sha3Trait;
+use stop_and_arithmetic_operations::StopAndArithmeticOperationsTrait;
 use system_operations::SystemOperationsTrait;

crates/evm/src/instructions/block_information.cairo

@@ -1,13 +1,12 @@
 //! Block Information.
 
+use evm::errors::EVMError;
+use evm::machine::{Machine, MachineCurrentContextTrait};
+use evm::stack::StackTrait;
+
 // Corelib imports
 use starknet::info::{get_block_number, get_block_timestamp};
-
-// Internal imports
-use evm::stack::StackTrait;
-use evm::errors::EVMError;
 use utils::constants::CHAIN_ID;
-use evm::machine::{Machine, MachineCurrentContext};
 
 #[generate_trait]
 impl BlockInformation of BlockInformationTrait {

crates/evm/src/instructions/comparison_operations.cairo

@@ -1,13 +1,13 @@
+use evm::errors::EVMError;
+use evm::errors::STACK_UNDERFLOW;
 // Internal imports
 use evm::machine::Machine;
 use evm::stack::StackTrait;
-use evm::errors::STACK_UNDERFLOW;
-use evm::errors::EVMError;
-use utils::math::{Exponentiation, Bitshift, WrappingBitshift};
+use integer::BoundedInt;
 use utils::constants::{POW_2_127};
-use utils::traits::BoolIntoNumeric;
 use utils::i256::i256;
-use integer::BoundedInt;
+use utils::math::{Exponentiation, Bitshift, WrappingBitshift};
+use utils::traits::BoolIntoNumeric;
 
 #[generate_trait]
 impl ComparisonAndBitwiseOperations of ComparisonAndBitwiseOperationsTrait {

crates/evm/src/instructions/duplication_operations.cairo

@@ -6,9 +6,9 @@ use evm::machine::Machine;
 
 mod internal {
     use evm::context::{ExecutionContext, ExecutionContextTrait,};
-    use evm::stack::StackTrait;
     use evm::errors::EVMError;
     use evm::machine::Machine;
+    use evm::stack::StackTrait;
 
     /// Generic DUP operation
     #[inline(always)]

crates/evm/src/instructions/environmental_information.cairo

@@ -1,13 +1,12 @@
 //! Environmental Information.
-use evm::stack::StackTrait;
 use evm::context::ExecutionContextTrait;
 use evm::errors::{EVMError, RETURNDATA_OUT_OF_BOUNDS_ERROR};
-use evm::helpers::U256IntoResultU32;
-use evm::machine::{Machine, MachineCurrentContext};
-use utils::helpers::{load_word};
-use utils::traits::{EthAddressIntoU256};
+use evm::machine::{Machine, MachineCurrentContextTrait};
 use evm::memory::MemoryTrait;
+use evm::stack::StackTrait;
 use integer::u32_overflowing_add;
+use utils::helpers::{load_word};
+use utils::traits::{EthAddressIntoU256};
 
 #[generate_trait]
 impl EnvironmentInformationImpl of EnvironmentInformationTrait {

crates/evm/src/instructions/exchange_operations.cairo

@@ -1,9 +1,8 @@
 //! Exchange Operations.
 
-// Internal imports
+use evm::errors::EVMError;
 use evm::machine::Machine;
 use evm::stack::StackTrait;
-use evm::errors::EVMError;
 use utils::helpers::load_word;
 
 #[generate_trait]

crates/evm/src/instructions/memory_operations.cairo

@@ -1,9 +1,8 @@
 //! Stack Memory Storage and Flow Operations.
-use evm::machine::{Machine, MachineCurrentContext};
 use evm::errors::{EVMError, INVALID_DESTINATION};
-use evm::stack::StackTrait;
+use evm::machine::{Machine, MachineCurrentContextTrait};
 use evm::memory::MemoryTrait;
-use evm::helpers::U256IntoResultU32;
+use evm::stack::StackTrait;
 
 #[generate_trait]
 impl MemoryOperation of MemoryOperationTrait {
@@ -59,7 +58,7 @@ impl MemoryOperation of MemoryOperationTrait {
 
         // TODO: Currently this doesn't check that byte is actually `JUMPDEST`
         // and not `0x5B` that is a part of PUSHN instruction
-        // 
+        //
         // That can be done by storing all valid jump locations during contract deployment
         // which would also simplify the logic because we would be just checking if idx is
         // present in that list
@@ -71,9 +70,7 @@ impl MemoryOperation of MemoryOperationTrait {
                     return Result::Err(EVMError::JumpError(INVALID_DESTINATION));
                 }
             },
-            Option::None => {
-                return Result::Err(EVMError::JumpError(INVALID_DESTINATION));
-            }
+            Option::None => { return Result::Err(EVMError::JumpError(INVALID_DESTINATION)); }
         }
         self.set_pc(index);
         Result::Ok(())
@@ -104,7 +101,7 @@ impl MemoryOperation of MemoryOperationTrait {
     /// 0x5b - JUMPDEST operation
     /// Serves as a check that JUMP or JUMPI was executed correctly.
     /// # Specification: https://www.evm.codes/#5b?fork=shanghai
-    /// 
+    ///
     /// This doesn't have any affect on execution state, so we don't have
     /// to do anything here. It's a NO-OP.
     fn exec_jumpdest(ref self: Machine) -> Result<(), EVMError> {

crates/evm/src/instructions/push_operations.cairo

@@ -1,13 +1,12 @@
 //! Push Operations.
 
-// Internal imports
-use evm::machine::{Machine, MachineCurrentContext};
 use evm::errors::EVMError;
+use evm::machine::{Machine, MachineCurrentContextTrait};
 use evm::stack::StackTrait;
 
 mod internal {
-    use evm::machine::{Machine, MachineCurrentContext};
     use evm::errors::EVMError;
+    use evm::machine::{Machine, MachineCurrentContextTrait};
     use evm::stack::StackTrait;
     use utils::helpers::load_word;
 

crates/evm/src/instructions/sha3.cairo

@@ -1,16 +1,13 @@
 //! SHA3.
 
+use evm::errors::EVMError;
 // Internal imports
 use evm::machine::Machine;
-use evm::stack::StackTrait;
 use evm::memory::MemoryTrait;
-use evm::errors::EVMError;
-use evm::helpers::U256IntoResultU32;
+use evm::stack::StackTrait;
 use keccak::{cairo_keccak, u128_split};
 use utils::helpers::{ArrayExtensionTrait, U256Trait};
 
-use array::ArrayTrait;
-
 #[generate_trait]
 impl Sha3Impl of Sha3Trait {
     /// SHA3 operation : Hashes n bytes in memory at a given offset in memory
@@ -56,10 +53,10 @@ impl Sha3Impl of Sha3Trait {
 
 
 mod internal {
-    use evm::stack::StackTrait;
+    use evm::machine::Machine;
     use evm::memory::MemoryTrait;
+    use evm::stack::StackTrait;
     use utils::helpers::U256Trait;
-    use evm::machine::Machine;
 
     /// Computes how many words are read from the memory
     /// and how many words must be filled with zeroes

crates/evm/src/instructions/stop_and_arithmetic_operations.cairo

@@ -1,14 +1,15 @@
 //! Stop and Arithmetic Operations.
 
+use evm::errors::EVMError;
+use evm::machine::{Machine, MachineCurrentContextTrait};
+use evm::stack::StackTrait;
+
 use integer::{
     u256_overflowing_add, u256_overflow_sub, u256_overflow_mul, u256_safe_divmod,
     u512_safe_div_rem_by_u256, u256_try_as_non_zero
 };
-use evm::machine::{Machine, MachineCurrentContext};
-use evm::stack::StackTrait;
-use utils::math::{Exponentiation, WrappingExponentiation, u256_wide_add};
-use evm::errors::EVMError;
 use utils::i256::i256;
+use utils::math::{Exponentiation, WrappingExponentiation, u256_wide_add};
 
 #[generate_trait]
 impl StopAndArithmeticOperations of StopAndArithmeticOperationsTrait {