Skip to content
This repository has been archived by the owner on Jan 9, 2025. It is now read-only.

Commit

Permalink
docs: improve docs
Browse files Browse the repository at this point in the history
  • Loading branch information
@enitrat
enitrat committed Sep 24, 2024
1 parent b2dcd91 commit 7773c6a
Show file tree
Hide file tree
Showing 6 changed files with 105 additions and 51 deletions.
10 changes: 5 additions & 5 deletions src/kakarot/eth_rpc.cairo
View file
Original file line number Diff line number Diff line change
Expand Up @@ -52,7 +52,7 @@ func eth_get_transaction_count{syscall_ptr: felt*, pedersen_ptr: HashBuiltin*, r
// @notice The eth_chainId function as described in the spec
// see https://ethereum.org/en/developers/docs/apis/json-rpc/#eth_chainid
// This is a view only function, meaning that it doesn't make any state change.
// @return chain_id Chaind id of the chain
// @return chain_id Chain id of the chain
@view
func eth_chain_id{syscall_ptr: felt*, pedersen_ptr: HashBuiltin*, range_check_ptr}() -> (
chain_id: felt
Expand All @@ -76,7 +76,7 @@ func eth_chain_id{syscall_ptr: felt*, pedersen_ptr: HashBuiltin*, range_check_pt
// @param access_list The access list passed in the transaction
// @return return_data_len The length of the return_data
// @return return_data An array of returned felts
// @return success An boolean, TRUE if the transaction succeeded, FALSE otherwise
// @return success A boolean, TRUE if the transaction succeeded, FALSE otherwise
// @return gas_used The amount of gas used by the transaction
@view
func eth_call{
Expand Down Expand Up @@ -130,7 +130,7 @@ func eth_call{
// @param access_list The access list passed in the transaction
// @return return_data_len The length of the return_data
// @return return_data An array of returned felts
// @return success An boolean, TRUE if the transaction succeeded, FALSE otherwise
// @return success A boolean, TRUE if the transaction succeeded, FALSE otherwise
// @return required_gas The amount of gas required by the transaction to successfully execute. This is different
// from the gas used by the transaction as it doesn't take into account any refunds.
@view
Expand Down Expand Up @@ -183,7 +183,7 @@ func eth_estimate_gas{
// @param access_list The access list passed in the transaction
// @return return_data_len The length of the return_data
// @return return_data An array of returned felts
// @return success An boolean, TRUE if the transaction succeeded, FALSE otherwise
// @return success A boolean, TRUE if the transaction succeeded, FALSE otherwise
// @return gas_used The amount of gas used by the transaction
func eth_send_transaction{
syscall_ptr: felt*, pedersen_ptr: HashBuiltin*, range_check_ptr, bitwise_ptr: BitwiseBuiltin*
Expand Down Expand Up @@ -233,7 +233,7 @@ func eth_send_transaction{
// @param tx_data The unsigned transaction data
// @return return_data_len The length of the return_data
// @return return_data An array of returned felts
// @return success An boolean, TRUE if the transaction succeeded, FALSE otherwise
// @return success A boolean, TRUE if the transaction succeeded, FALSE otherwise
// @return gas_used The amount of gas used by the transaction
@external
func eth_send_raw_unsigned_tx{
Expand Down
36 changes: 25 additions & 11 deletions src/kakarot/evm.cairo
View file
Original file line number Diff line number Diff line change
Expand Up @@ -26,7 +26,8 @@ namespace EVM {
// @notice Initialize the execution context.
// @dev Initialize the execution context of a specific contract.
// @param message The message (see model.Message) to be executed.
// @return EVM The initialized execution context.
// @param gas_left The amount of gas left for execution.
// @return model.EVM* The initialized execution context.
func init(message: model.Message*, gas_left: felt) -> model.EVM* {
let (return_data: felt*) = alloc();
Expand All @@ -42,6 +43,8 @@ namespace EVM {
);
}

// @notice Finalize the execution context.
// @dev Finalize the execution context by squashing the valid jump destinations.
func finalize{range_check_ptr, evm: model.EVM*}() {
let (squashed_start, squashed_end) = default_dict_finalize(
evm.message.valid_jumpdests_start, evm.message.valid_jumpdests, 0
Expand Down Expand Up @@ -86,7 +89,7 @@ namespace EVM {
// @param return_data The pointer to the return_data array.
// @param reverted A code indicating whether the EVM is reverted or not.
// can be either 0 - not reverted, Errors.REVERTED or Errors.EXCEPTIONAL_HALT
// @return EVM The pointer to the updated execution context.
// @return model.EVM* The pointer to the updated execution context.
func stop(
self: model.EVM*, return_data_len: felt, return_data: felt*, reverted: felt
) -> model.EVM* {
Expand All @@ -102,6 +105,10 @@ namespace EVM {
);
}

// @notice Handle out of gas scenario.
// @param self The pointer to the execution context.
// @param amount The amount of gas required.
// @return model.EVM* The pointer to the updated execution context.
func out_of_gas{range_check_ptr}(self: model.EVM*, amount: felt) -> model.EVM* {
let (revert_reason_len, revert_reason) = Errors.outOfGas(self.gas_left, amount);
return new model.EVM(
Expand All @@ -120,7 +127,7 @@ namespace EVM {
// @param self The pointer to the execution context.
// @param return_data_len The length of the return_data.
// @param return_data The pointer to the return_data array.
// @return EVM The pointer to the updated execution context.
// @return model.EVM* The pointer to the updated execution context.
func update_return_data(
self: model.EVM*, return_data_len: felt, return_data: felt*
) -> model.EVM* {
Expand All @@ -140,7 +147,7 @@ namespace EVM {
// @dev The program counter is incremented by the given value.
// @param self The pointer to the execution context.
// @param inc_value The value to increment the program counter with.
// @return EVM The pointer to the updated execution context.
// @return model.EVM* The pointer to the updated execution context.
func increment_program_counter(self: model.EVM*, inc_value: felt) -> model.EVM* {
return new model.EVM(
message=self.message,
Expand All @@ -160,7 +167,7 @@ namespace EVM {
// Assumption: gas_left < 2 ** 128
// @param self The pointer to the current execution context.
// @param amount The amount of gas the current operation requires.
// @return EVM The pointer to the updated execution context.
// @return model.EVM* The pointer to the updated execution context.
func charge_gas{range_check_ptr}(self: model.EVM*, amount: felt) -> model.EVM* {
// This is equivalent to is_nn(self.gas_left - amount)
tempvar a = self.gas_left - amount; // a is necessary for using the whitelisted hint
Expand Down Expand Up @@ -211,6 +218,9 @@ namespace EVM {
);
}

// @notice Handle validation failure.
// @param self The pointer to the execution context.
// @return model.EVM* The pointer to the updated execution context.
func halt_validation_failed{range_check_ptr}(self: model.EVM*) -> model.EVM* {
let (revert_reason_len, revert_reason) = Errors.eth_validation_failed();
return new model.EVM(
Expand All @@ -227,10 +237,10 @@ namespace EVM {

// @notice Update the array of events to emit in the case of a execution context successfully running to completion (see `EVM.finalize`).
// @param self The pointer to the execution context.
// @param topics_len The length of the topics
// @param topics The topics Uint256 array
// @param data_len The length of the data
// @param data The data bytes array
// @param topics_len The length of the topics.
// @param topics The topics Uint256 array.
// @param data_len The length of the data.
// @param data The data bytes array.
func push_event{state: model.State*}(
self: model.EVM*, topics_len: felt, topics: Uint256*, data_len: felt, data: felt*
) {
Expand All @@ -257,10 +267,10 @@ namespace EVM {
}

// @notice Update the program counter.
// @dev The program counter is updated to a given value. This is only ever called by JUMP or JUMPI
// @dev The program counter is updated to a given value. This is only ever called by JUMP or JUMPI.
// @param self The pointer to the execution context.
// @param new_pc_offset The value to update the program counter by.
// @return EVM The pointer to the updated execution context.
// @return model.EVM* The pointer to the updated execution context.
func jump{syscall_ptr: felt*, pedersen_ptr: HashBuiltin*, range_check_ptr, state: model.State*}(
self: model.EVM*, new_pc_offset: felt
) -> model.EVM* {
Expand Down Expand Up @@ -327,6 +337,10 @@ namespace EVM {
}

namespace Internals {
// @notice Check if the given index is a valid jump destination.
// @param code_address The address of the code.
// @param index The index to check.
// @return felt 1 if valid, 0 otherwise.
func is_valid_jumpdest{
syscall_ptr: felt*,
pedersen_ptr: HashBuiltin*,
Expand Down
16 changes: 12 additions & 4 deletions src/kakarot/instructions/system_operations.cairo
View file
Original file line number Diff line number Diff line change
Expand Up @@ -862,7 +862,8 @@ namespace CallHelper {
// execution frame of the call and returns it.
// @param evm The current EVM, which is the parent of the new EVM.
// @param gas The gas to be used by the new EVM.
// @param value The value to be transferred in the call
// @param value The value to be transferred in the call.
// @param caller The address of the caller.
// @param to The address of the target account.
// @param code_address The address of the account whose code will be executed.
// @param is_staticcall A boolean indicating whether the call is a static call.
Expand Down Expand Up @@ -941,6 +942,8 @@ namespace CallHelper {
return child_evm;
}

// @notice Finalizes the parent context after a call.
// @param evm The current EVM context.
// @return EVM The pointer to the updated calling context.
func finalize_parent{
syscall_ptr: felt*,
Expand Down Expand Up @@ -1059,9 +1062,8 @@ namespace CreateHelper {
// keccak256(rlp([sender_address,sender_nonce])).
// See [CREATE](https://www.evm.codes/#f0).
// @param sender_address The evm sender address.
// @param bytecode_len The length of the initialization code.
// @param nonce The nonce given to the create opcode.
// @return EVM The pointer to the updated calling context.
// @return evm_contract_address The computed EVM contract address.
func get_create_address{
syscall_ptr: felt*,
pedersen_ptr: HashBuiltin*,
Expand Down Expand Up @@ -1121,7 +1123,7 @@ namespace CreateHelper {
// @param bytecode_len The length of the initialization code.
// @param bytecode The offset to store the element at.
// @param salt The salt given to the create2 opcode.
// @return EVM The pointer to the updated calling context.
// @return create2_address The computed EVM contract address.
func get_create2_address{
syscall_ptr: felt*,
pedersen_ptr: HashBuiltin*,
Expand Down Expand Up @@ -1173,6 +1175,12 @@ namespace CreateHelper {
}

// @notice Pre-compute the evm address of a contract account before deploying it.
// @param evm_address The EVM address of the sender.
// @param popped_len The length of the popped stack elements.
// @param popped The popped stack elements.
// @param bytecode_len The length of the initialization code.
// @param bytecode The initialization code.
// @return The computed EVM contract address.
func get_evm_address{
syscall_ptr: felt*,
pedersen_ptr: HashBuiltin*,
Expand Down
11 changes: 8 additions & 3 deletions src/utils/eth_transaction.cairo
View file
Original file line number Diff line number Diff line change
Expand Up @@ -24,6 +24,7 @@ namespace EthTransaction {
// transaction data, which includes the chain ID in accordance with EIP-155.
// @param tx_data_len The length of the raw transaction data
// @param tx_data The raw transaction data
// @return model.EthTransaction* The decoded Ethereum transaction
func decode_legacy_tx{bitwise_ptr: BitwiseBuiltin*, range_check_ptr}(
tx_data_len: felt, tx_data: felt*
) -> model.EthTransaction* {
Expand Down Expand Up @@ -96,6 +97,7 @@ namespace EthTransaction {
// @dev See https://github.com/ethereum/EIPs/blob/master/EIPS/eip-2930.md
// @param tx_data_len The length of the raw transaction data
// @param tx_data The raw transaction data
// @return model.EthTransaction* The decoded Ethereum transaction
func decode_2930{bitwise_ptr: BitwiseBuiltin*, range_check_ptr}(
tx_data_len: felt, tx_data: felt*
) -> model.EthTransaction* {
Expand Down Expand Up @@ -158,6 +160,7 @@ namespace EthTransaction {
// @dev See https://github.com/ethereum/EIPs/blob/master/EIPS/eip-1559.md
// @param tx_data_len The length of the raw transaction data
// @param tx_data The raw transaction data
// @return model.EthTransaction* The decoded Ethereum transaction
func decode_1559{bitwise_ptr: BitwiseBuiltin*, range_check_ptr}(
tx_data_len: felt, tx_data: felt*
) -> model.EthTransaction* {
Expand Down Expand Up @@ -224,6 +227,7 @@ namespace EthTransaction {
// See https://eips.ethereum.org/EIPS/eip-2718#transactiontype-only-goes-up-to-0x7f
// @param tx_data_len The len of the raw transaction data
// @param tx_data The raw transaction data
// @return felt The type of the transaction
func get_tx_type{range_check_ptr}(tx_data_len: felt, tx_data: felt*) -> felt {
with_attr error_message("tx_data_len is zero") {
assert_not_zero(tx_data_len);
Expand All @@ -240,6 +244,7 @@ namespace EthTransaction {
// @notice Decode a raw Ethereum transaction
// @param tx_data_len The length of the raw transaction data
// @param tx_data The raw transaction data
// @return model.EthTransaction* The decoded Ethereum transaction
func decode{bitwise_ptr: BitwiseBuiltin*, range_check_ptr}(
tx_data_len: felt, tx_data: felt*
) -> model.EthTransaction* {
Expand Down Expand Up @@ -267,9 +272,9 @@ namespace EthTransaction {
// @dev the parsed format is [address, storage_keys_len, *[storage_keys], address, storage_keys_len, *[storage_keys]]
// where keys_len is the number of storage keys, and each storage key takes 2 felts.
// @param parsed_list The pointer to the next free cell in the parsed access list.
// @param list_len The remaining length of the RLP-decoded access list to parse.
// @param list_items The pointer to the current RLP-decoded access list item to parse.
// @return The length of the serialized access list, expressed in total amount of felts in the list.
// @param access_list_len The remaining length of the RLP-decoded access list to parse.
// @param access_list The pointer to the current RLP-decoded access list item to parse.
// @return felt The length of the serialized access list, expressed in total amount of felts in the list.
func parse_access_list{range_check_ptr}(
parsed_list: felt*, access_list_len: felt, access_list: RLP.Item*
) -> felt {
Expand Down
15 changes: 13 additions & 2 deletions src/utils/rlp.cairo
View file
Original file line number Diff line number Diff line change
Expand Up @@ -22,7 +22,7 @@ namespace RLP {
is_list: felt,
}

// @notive Decode the type of an RLP item.
// @notice Decode the type of an RLP item.
// @dev Unsafe function, does not check if the data is long enough (can be exploited by a malicious prover).
// Always check afterwards that outputs are compatible with the associated data_len.
// @param data The RLP encoded data.
Expand Down Expand Up @@ -72,7 +72,7 @@ namespace RLP {
}

// @notice Decodes a Recursive Length Prefix (RLP) encoded data.
// @notice This function decodes the RLP encoded data into a list of items.
// @dev This function decodes the RLP encoded data into a list of items.
// Each item is a struct containing the length of the data, the data itself, and a flag indicating whether the data is a list.
// The function first determines the type of the RLP data (string or list) and then processes it accordingly.
// If the data is a string, it is simply added to the items.
Expand Down Expand Up @@ -115,6 +115,17 @@ namespace RLP {
return 1 + items_len;
}

// @notice Decodes a Recursive Length Prefix (RLP) encoded data.
// @dev This function decodes the RLP encoded data into a list of items.
// Each item is a struct containing the length of the data, the data itself, and a flag indicating whether the data is a list.
// The function first determines the type of the RLP data (string or list) and then processes it accordingly.
// If the data is a string, it is simply added to the items.
// If the data is a list, it is recursively decoded.
// After processing the first item, the function checks if there is more data to decode and if so,
// it recursively decodes the remaining data and adds the decoded items to the list of items.
// @param data_len The length of the data to decode.
// @param data The RLP encoded data.
// @param items The pointer to the next free cell in the list of items decoded.
func decode{range_check_ptr}(items: Item*, data_len: felt, data: felt*) {
alloc_locals;
let (rlp_type, offset, len) = decode_type_unsafe(data);
Expand Down
Loading

0 comments on commit 7773c6a

Please sign in to comment.