diff --git a/src/ethereum/arrow_glacier/blocks.py b/src/ethereum/arrow_glacier/blocks.py index 8727a0318b..09cbe260b3 100644 --- a/src/ethereum/arrow_glacier/blocks.py +++ b/src/ethereum/arrow_glacier/blocks.py @@ -36,19 +36,18 @@ class Header: parent_hash: Hash32 """ - Hash ([`keccak256`]) of the parent block's header, encoded with [RLP]. - - [`keccak256`]: ref:ethereum.crypto.hash.keccak256 - [RLP]: https://ethereum.github.io/ethereum-rlp/src/ethereum_rlp/rlp.py.html + Hash + ([`keccak256`](../crypto/hash.py.html#ethereum.crypto.hash.keccak256:0)) + of the parent block's header, encoded with + [RLP](https://ethereum.github.io/ethereum-rlp/src/ethereum_rlp/rlp.py.html). """ ommers_hash: Hash32 """ - Hash ([`keccak256`]) of the ommers (uncle blocks) in this block, encoded - with [RLP]. - - [`keccak256`]: ref:ethereum.crypto.hash.keccak256 - [RLP]: https://ethereum.github.io/ethereum-rlp/src/ethereum_rlp/rlp.py.html + Hash + ([`keccak256`](../crypto/hash.py.html#ethereum.crypto.hash.keccak256:0)) + of the ommers (uncle blocks) in this block, encoded with + [RLP](https://ethereum.github.io/ethereum-rlp/src/ethereum_rlp/rlp.py.html). """ coinbase: Address @@ -56,54 +55,54 @@ class Header: Address of the miner (or validator) who mined this block. The coinbase address receives the block reward and the priority fees (tips) - from included transactions. Base fees (introduced in [EIP-1559]) are burned - and do not go to the coinbase. - - [EIP-1559]: https://eips.ethereum.org/EIPS/eip-1559 + from included transactions. Base fees (introduced in + [EIP-1559](https://eips.ethereum.org/EIPS/eip-1559)) are burned and do not + go to the coinbase. """ state_root: Root """ - Root hash ([`keccak256`]) of the state trie after executing all - transactions in this block. It represents the state of the Ethereum Virtual - Machine (EVM) after all transactions in this block have been processed. It - is computed using the [`state_root()`] function, which computes the root - of the Merkle-Patricia [Trie] representing the Ethereum world state. - - [`keccak256`]: ref:ethereum.crypto.hash.keccak256 - [`state_root()`]: ref:ethereum.arrow_glacier.state.state_root - [Trie]: ref:ethereum.arrow_glacier.trie.Trie + Root hash + ([`keccak256`](../crypto/hash.py.html#ethereum.crypto.hash.keccak256:0)) + of the state trie after executing all transactions in this block. It + represents the state of the Ethereum Virtual Machine (EVM) after all + transactions in this block have been processed. It is computed using the + [`state_root()`](./state.py.html#ethereum.arrow_glacier.state.state_root:0) + function, which computes the root of the Merkle-Patricia + [Trie](./trie.py.html#ethereum.arrow_glacier.trie.Trie:0) representing the + Ethereum world state. """ transactions_root: Root """ - Root hash ([`keccak256`]) of the transactions trie, which contains all - transactions included in this block in their original order. It is computed - using the [`root()`] function over the Merkle-Patricia [trie] of - transactions as the parameter. - - [`keccak256`]: ref:ethereum.crypto.hash.keccak256 - [`root()`]: ref:ethereum.arrow_glacier.trie.root - [Trie]: ref:ethereum.arrow_glacier.trie.Trie + Root hash + ([`keccak256`](../crypto/hash.py.html#ethereum.crypto.hash.keccak256:0)) + of the transactions trie, which contains all transactions included in this + block in their original order. It is computed using the + [`root()`](./trie.py.html#ethereum.arrow_glacier.trie.root:0) function + over the Merkle-Patricia + [trie](./trie.py.html#ethereum.arrow_glacier.trie.Trie:0) of transactions + as the parameter. """ receipt_root: Root """ - Root hash ([`keccak256`]) of the receipts trie, which contains all receipts - for transactions in this block. It is computed using the [`root()`] - function over the Merkle-Patricia [trie] constructed from the receipts. - - [`keccak256`]: ref:ethereum.crypto.hash.keccak256 - [`root()`]: ref:ethereum.arrow_glacier.trie.root - [Trie]: ref:ethereum.arrow_glacier.trie.Trie + Root hash + ([`keccak256`](../crypto/hash.py.html#ethereum.crypto.hash.keccak256:0)) + of the receipts trie, which contains all receipts for transactions in this + block. It is computed using the + [`root()`](./trie.py.html#ethereum.arrow_glacier.trie.root:0) function + over the Merkle-Patricia + [trie](./trie.py.html#ethereum.arrow_glacier.trie.Trie:0) constructed from + the receipts. """ bloom: Bloom """ Bloom filter for logs generated by transactions in this block. - Constructed from all logs in the block using the [logs bloom] mechanism. - - [logs bloom]: ref:ethereum.arrow_glacier.bloom.logs_bloom + Constructed from all logs in the block using the + [logs bloom](./bloom.py.html#ethereum.arrow_glacier.bloom.logs_bloom:0) + mechanism. """ difficulty: Uint @@ -111,10 +110,8 @@ class Header: Difficulty of the block, used in Proof-of-Work to determine the effort required to mine the block. This value adjusts over time to maintain a relatively constant block time and is computed using the - [`calculate_block_difficulty()`] function. - - [`calculate_block_difficulty()`]: - ref:ethereum.arrow_glacier.fork.calculate_block_difficulty + [`calculate_block_difficulty()`](./fork.py.html#ethereum.arrow_glacier.fork.calculate_block_difficulty:0) + function. """ number: Uint @@ -124,16 +121,14 @@ class Header: gas_limit: Uint """ - Maximum gas allowed in this block. Pre [EIP-1559], this was the maximum + Maximum gas allowed in this block. Pre + [EIP-1559](https://eips.ethereum.org/EIPS/eip-1559), this was the maximum gas that could be consumed by all transactions in the block. Post - [EIP-1559], this is still the maximum gas limit, but the base fee per gas - is also considered when calculating the effective gas limit. This can be - [adjusted by a factor of 1/1024] from the previous block's gas limit, up - until a maximum of 30 million gas. - - [EIP-1559]: https://eips.ethereum.org/EIPS/eip-1559 - [adjusted by a factor of 1/1024]: - https://ethereum.org/en/developers/docs/blocks/ + [EIP-1559](https://eips.ethereum.org/EIPS/eip-1559), this is still the + maximum gas limit, but the base fee per gas is also + considered when calculating the effective gas limit. This can be adjusted + [by a factor of 1/1024](https://ethereum.org/en/developers/docs/blocks/) + from the previous block's gas limit, up until a maximum of 30 million gas. """ gas_used: Uint @@ -154,28 +149,25 @@ class Header: mix_digest: Bytes32 """ Mix hash used in the mining process, which is a cryptographic commitment - to the block's contents. It [validates] that PoW was done on the correct - block. - - [validates]: ref:ethereum.arrow_glacier.fork.validate_proof_of_work + to the block's contents. It + [validates](./fork.py.html#ethereum.arrow_glacier.fork.validate_proof_of_work:0) + that PoW was done on the correct block. """ nonce: Bytes8 """ Nonce used in the mining process, which is a value that miners - increment to find a valid block hash. This is also used to [validate] the - proof-of-work for this block. - - [validate]: ref:ethereum.arrow_glacier.fork.validate_proof_of_work + increment to find a valid block hash. This is also used to + [validate](./fork.py.html#ethereum.arrow_glacier.fork.validate_proof_of_work:0) + the proof-of-work for this block. """ base_fee_per_gas: Uint """ Base fee per gas for transactions in this block, introduced in - [EIP-1559]. This is the minimum fee per gas that must be paid for a - transaction to be included in this block. - - [EIP-1559]: https://eips.ethereum.org/EIPS/eip-1559 + [EIP-1559](https://eips.ethereum.org/EIPS/eip-1559). This is the minimum + fee per gas that must be paid for a transaction to be included in this + block. """ @@ -183,13 +175,14 @@ class Header: @dataclass class Block: """ - A complete block on Ethereum, which is composed of a block [`header`], - a list of transactions, and a list of ommers (also known as uncle blocks). + A complete block on Ethereum, which is composed of a block + [`header`](#ethereum.arrow_glacier.blocks.Header:0), a list of + transactions, and a list of ommers (also known as uncle blocks). - The block [`header`] includes PoW-specific fields such as `difficulty`, - `nonce`, and `ommersHash`, which relate to the mining process. The - `coinbase` field denotes the address receiving mining and transaction - fees. + The block [`header`](#ethereum.arrow_glacier.blocks.Header:0) includes + PoW-specific fields such as `difficulty`, `nonce`, and `ommersHash`, which + relate to the mining process. The `coinbase` field denotes the address + receiving mining and transaction fees. The header also contains commitments to the current state (`stateRoot`), the transactions (`transactionsRoot`), and the transaction receipts @@ -198,16 +191,13 @@ class Block: Ommers are used to provide rewards for near-valid mined blocks that didn't become part of the canonical chain. - - [`header`]: ref:ethereum.arrow_glacier.blocks.Header """ header: Header """ The block header containing metadata and cryptographic commitments. Refer - [headers] for more details on the fields included in the header. - - [headers]: ref:ethereum.arrow_glacier.blocks.Header + [headers](#ethereum.arrow_glacier.blocks.Header:0) for more details on the + fields included in the header. """ transactions: Tuple[Union[Bytes, LegacyTransaction], ...] @@ -230,15 +220,15 @@ class Block: class Log: """ Data record produced during the execution of a transaction. Logs are used - by smart contracts to emit events (using the EVM log opcodes ([`LOG0`], - [`LOG1`], [`LOG2`], [`LOG3`] and [`LOG4`]), which can be efficiently - searched using the bloom filter in the block header. - - [`LOG0`]: ref:ethereum.arrow_glacier.vm.instructions.log.log0 - [`LOG1`]: ref:ethereum.arrow_glacier.vm.instructions.log.log1 - [`LOG2`]: ref:ethereum.arrow_glacier.vm.instructions.log.log2 - [`LOG3`]: ref:ethereum.arrow_glacier.vm.instructions.log.log3 - [`LOG4`]: ref:ethereum.arrow_glacier.vm.instructions.log.log4 + by smart contracts to emit events (using the EVM log opcodes + ([`LOG0`](./vm/instructions/log.py.html#ethereum.arrow_glacier.vm.instructions.log.log0:0), + [`LOG1`](./vm/instructions/log.py.html#ethereum.arrow_glacier.vm.instructions.log.log1:0), + [`LOG2`](./vm/instructions/log.py.html#ethereum.arrow_glacier.vm.instructions.log.log2:0), + [`LOG3`](./vm/instructions/log.py.html#ethereum.arrow_glacier.vm.instructions.log.log3:0) + and + [`LOG4`](./vm/instructions/log.py.html#ethereum.arrow_glacier.vm.instructions.log.log4:0)), + which can be efficiently searched using the bloom filter in the block + header. """ address: Address diff --git a/src/ethereum/arrow_glacier/bloom.py b/src/ethereum/arrow_glacier/bloom.py index 63db26dab5..769b1046a2 100644 --- a/src/ethereum/arrow_glacier/bloom.py +++ b/src/ethereum/arrow_glacier/bloom.py @@ -1,19 +1,13 @@ """ -Ethereum Logs Bloom -^^^^^^^^^^^^^^^^^^^ +# Ethereum Logs Bloom -.. contents:: Table of Contents - :backlinks: none - :local: - -Introduction ------------- +## Introduction This modules defines functions for calculating bloom filters of logs. For the -general theory of bloom filters see e.g. `Wikipedia -`_. Bloom filters are used to allow -for efficient searching of logs by address and/or topic, by rapidly -eliminating blocks and receipts from their search. +general theory of bloom filters see e.g. +[Wikipedia](https://en.wikipedia.org/wiki/Bloom_filter). Bloom filters are +used to allow for efficient searching of logs by address and/or topic, by +rapidly eliminating blocks and receipts from their search. """ from typing import Tuple @@ -35,12 +29,9 @@ def add_to_bloom(bloom: bytearray, bloom_entry: Bytes) -> None: least significant 11 bits from the first 3 16-bit words of the `keccak_256()` hash of `bloom_entry`. - Parameters - ---------- - bloom : - The bloom filter. - bloom_entry : - An entry which is to be added to bloom filter. + #### Parameters + - bloom: The bloom filter. + - bloom_entry: An entry which is to be added to bloom filter. """ hash = keccak256(bloom_entry) @@ -65,16 +56,13 @@ def logs_bloom(logs: Tuple[Log, ...]) -> Bloom: The address and each topic of a log are added to the bloom filter. - Parameters - ---------- - logs : - List of logs for which the logs bloom is to be obtained. + #### Parameters + - logs: List of logs for which the logs bloom is to be obtained. - Returns - ------- - logs_bloom : `Bloom` - The logs bloom obtained which is 256 bytes with some bits set as per - the caller address and the log topics. + #### Returns + - logs_bloom: `Bloom` + The logs bloom obtained which is 256 bytes with some bits set as per the + caller address and the log topics. """ bloom: bytearray = bytearray(b"\x00" * 256) diff --git a/src/ethereum/arrow_glacier/exceptions.py b/src/ethereum/arrow_glacier/exceptions.py index 59968e94e2..af68df16ca 100644 --- a/src/ethereum/arrow_glacier/exceptions.py +++ b/src/ethereum/arrow_glacier/exceptions.py @@ -11,9 +11,8 @@ class TransactionTypeError(InvalidTransaction): """ - Unknown [EIP-2718] transaction type byte. - - [EIP-2718]: https://eips.ethereum.org/EIPS/eip-2718 + Unknown [EIP-2718](https://eips.ethereum.org/EIPS/eip-2718) transaction + type byte. """ transaction_type: Final[int] diff --git a/src/ethereum/arrow_glacier/fork.py b/src/ethereum/arrow_glacier/fork.py index 9dd6555535..c408bb9768 100644 --- a/src/ethereum/arrow_glacier/fork.py +++ b/src/ethereum/arrow_glacier/fork.py @@ -1,13 +1,7 @@ """ -Ethereum Specification -^^^^^^^^^^^^^^^^^^^^^^ +# Ethereum Specification -.. contents:: Table of Contents - :backlinks: none - :local: - -Introduction ------------- +## Introduction Entry point for the Ethereum specification. """ @@ -95,15 +89,12 @@ def apply_fork(old: BlockChain) -> BlockChain: is used to handle the irregularity. See the :ref:`DAO Fork ` for an example. - Parameters - ---------- - old : - Previous block chain object. + #### Parameters + - old: Previous block chain object. - Returns - ------- - new : `BlockChain` - Upgraded block chain object for this hard fork. + #### Returns + - new: `BlockChain` + Upgraded block chain object for this hard fork. """ return old @@ -118,15 +109,12 @@ def get_last_256_block_hashes(chain: BlockChain) -> List[Hash32]: The ``BLOCKHASH`` opcode needs to access the latest hashes on the chain, therefore this function retrieves them. - Parameters - ---------- - chain : - History and current state. + #### Parameters + - chain: History and current state. - Returns - ------- - recent_block_hashes : `List[Hash32]` - Hashes of the recent 256 blocks in order of increasing block number. + #### Returns + recent_block_hashes: `List[Hash32]` + Hashes of the recent 256 blocks in order of increasing block number. """ recent_blocks = chain.blocks[-255:] # TODO: This function has not been tested rigorously @@ -163,12 +151,9 @@ def state_transition(chain: BlockChain, block: Block) -> None: concerned, only those blocks are accessed. Practically, however, clients should store more blocks to handle reorgs. - Parameters - ---------- - chain : - History and current state. - block : - Block to apply to `chain`. + #### Parameters + - chain: History and current state. + - block: Block to apply to `chain`. """ validate_header(chain, block.header) validate_ommers(block.ommers, block.header, chain) @@ -224,20 +209,15 @@ def calculate_base_fee_per_gas( """ Calculates the base fee per gas for the block. - Parameters - ---------- - block_gas_limit : - Gas limit of the block for which the base fee is being calculated. - parent_gas_limit : - Gas limit of the parent block. - parent_gas_used : - Gas used in the parent block. - parent_base_fee_per_gas : - Base fee per gas of the parent block. - - Returns - ------- - base_fee_per_gas : `Uint` + #### Parameters + - block_gas_limit: Gas limit of the block for which the base fee is being + calculated. + - parent_gas_limit: Gas limit of the parent block. + - parent_gas_used: Gas used in the parent block. + - parent_base_fee_per_gas: Base fee per gas of the parent block. + + #### Returns + - base_fee_per_gas: `Uint` Base fee per gas for the block. """ parent_gas_target = parent_gas_limit // ELASTICITY_MULTIPLIER @@ -288,12 +268,9 @@ def validate_header(chain: BlockChain, header: Header) -> None: Additionally, the block's number should be directly following the parent block's number since it is the next block in the sequence. - Parameters - ---------- - chain : - History and current state. - header : - Header to check for correctness. + #### Parameters + - chain: History and current state. + - header: Header to check for correctness. """ if header.number < Uint(1): raise InvalidBlock @@ -361,15 +338,12 @@ def generate_header_hash_for_pow(header: Header) -> Hash32: because they are being changed by miners in their search for a sufficient proof-of-work. - Parameters - ---------- - header : - The header object for which the hash is to be generated. + #### Parameters + - header: The header object for which the hash is to be generated. - Returns - ------- - hash : `Hash32` - The PoW valid rlp hash of the passed in header. + #### Returns + - hash: `Hash32` + The PoW valid rlp hash of the passed in header. """ header_data_without_pow_artefacts = ( header.parent_hash, @@ -401,10 +375,8 @@ def validate_proof_of_work(header: Header) -> None: is passed through and it confirms whether or not proof-of-work was done on the correct block. The result is the actual hash value of the block. - Parameters - ---------- - header : - Header of interest. + #### Parameters + - header: Header of interest. """ header_hash = generate_header_hash_for_pow(header) # TODO: Memoize this somewhere and read from that data instead of @@ -429,38 +401,30 @@ def check_transaction( """ Check if the transaction is includable in the block. - Parameters - ---------- - block_env : - The block scoped environment. - block_output : - The block output for the current block. - tx : - The transaction. - - Returns - ------- - sender_address : - The sender of the transaction. - effective_gas_price : - The price to charge for gas when the transaction is executed. - - Raises - ------ - InvalidBlock : - If the transaction is not includable. - GasUsedExceedsLimitError : - If the gas used by the transaction exceeds the block's gas limit. - NonceMismatchError : - If the nonce of the transaction is not equal to the sender's nonce. - InsufficientBalanceError : - If the sender's balance is not enough to pay for the transaction. - InvalidSenderError : - If the transaction is from an address that does not exist anymore. - PriorityFeeGreaterThanMaxFeeError : - If the priority fee is greater than the maximum fee per gas. - InsufficientMaxFeePerGasError : - If the maximum fee per gas is insufficient for the transaction. + #### Parameters + - block_env: The block scoped environment. + - block_output: The block output for the current block. + - tx: The transaction. + + #### Returns + - sender_address: The sender of the transaction. + - effective_gas_price: The price to charge for gas when the transaction is + executed. + + #### Raises + - InvalidBlock: If the transaction is not includable. + - GasUsedExceedsLimitError: If the gas used by the transaction exceeds the + block's gas limit. + - NonceMismatchError: If the nonce of the transaction is not equal to the + sender's nonce. + - InsufficientBalanceError: If the sender's balance is not enough to pay + for the transaction. + - InvalidSenderError: If the transaction is from an address that does not + exist anymore. + - PriorityFeeGreaterThanMaxFeeError: If the priority fee is greater than + the maximum fee per gas. + - InsufficientMaxFeePerGasError: If the maximum fee per gas is + insufficient for the transaction. """ gas_available = block_env.block_gas_limit - block_output.block_gas_used if tx.gas > gas_available: @@ -511,22 +475,15 @@ def make_receipt( """ Make the receipt for a transaction that was executed. - Parameters - ---------- - tx : - The executed transaction. - error : - Error in the top level frame of the transaction, if any. - cumulative_gas_used : - The total gas used so far in the block after the transaction was - executed. - logs : - The logs produced by the transaction. - - Returns - ------- - receipt : - The receipt for the transaction. + #### Parameters + - tx: The executed transaction. + - error: Error in the top level frame of the transaction, if any. + - cumulative_gas_used: The total gas used so far in the block after the + transaction was executed. + - logs: The logs produced by the transaction. + + #### Returns + - receipt: The receipt for the transaction. """ receipt = Receipt( succeeded=error is None, @@ -553,20 +510,14 @@ def apply_body( and gas used. This function creates and executes the block that is to be added to the chain. - Parameters - ---------- - block_env : - The block scoped environment. - transactions : - Transactions included in the block. - ommers : - Headers of ancestor blocks which are not direct parents (formerly - uncles.) - - Returns - ------- - block_output : - The block output for the current block. + #### Parameters + - block_env: The block scoped environment. + - transactions: Transactions included in the block. + - ommers: Headers of ancestor blocks which are not direct parents (formerly + uncles.) + + #### Returns + - block_output: The block output for the current block. """ block_output = vm.BlockOutput() @@ -593,14 +544,10 @@ def validate_ommers( there cannot be duplicate ommers in a block. Many of the other ommer constraints are listed in the in-line comments of this function. - Parameters - ---------- - ommers : - List of ommers mentioned in the current block. - block_header: - The header of current block. - chain : - History and current state. + #### Parameters + - ommers: List of ommers mentioned in the current block. + - block_header: The header of current block. + - chain: History and current state. """ block_hash = keccak256(rlp.encode(block_header)) if keccak256(rlp.encode(ommers)) != block_header.ommers_hash: @@ -673,16 +620,12 @@ def pay_rewards( calculated based on the number associated with the ommer block that they mined. - Parameters - ---------- - state : - Current account state. - block_number : - Position of the block within the chain. - coinbase : - Address of account which receives block reward and transaction fees. - ommers : - List of ommers mentioned in the current block. + #### Parameters + - state: Current account state. + - block_number: Position of the block within the chain. + - coinbase: Address of account which receives block reward and transaction + fees. + - ommers: List of ommers mentioned in the current block. """ ommer_count = U256(len(ommers)) miner_reward = BLOCK_REWARD + (ommer_count * (BLOCK_REWARD // U256(32))) @@ -713,16 +656,11 @@ def process_transaction( Accounts that are marked for deletion are processed and destroyed after execution. - Parameters - ---------- - block_env : - Environment for the Ethereum Virtual Machine. - block_output : - The block output for the current block. - tx : - Transaction to execute. - index: - Index of the transaction in the block. + #### Parameters + - block_env: Environment for the Ethereum Virtual Machine. + - block_output: The block output for the current block. + - tx: Transaction to execute. + - index: Index of the transaction in the block. """ trie_set( block_output.transactions_trie, @@ -847,18 +785,13 @@ def check_gas_limit(gas_limit: Uint, parent_gas_limit: Uint) -> bool: check fails because the gas limit doesn't allow for a sufficient or reasonable amount of gas to be used on a block. - Parameters - ---------- - gas_limit : - Gas limit to validate. - - parent_gas_limit : - Gas limit of the parent block. + #### Parameters + - gas_limit: Gas limit to validate. + - parent_gas_limit: Gas limit of the parent block. - Returns - ------- - check : `bool` - True if gas limit constraints are satisfied, False otherwise. + #### Returns + - check: `bool` + True if gas limit constraints are satisfied, False otherwise. """ max_adjustment_delta = parent_gas_limit // GAS_LIMIT_ADJUSTMENT_FACTOR if gas_limit >= parent_gas_limit + max_adjustment_delta: @@ -898,23 +831,16 @@ def calculate_block_difficulty( difficulty is set to the maximum value between the calculated difficulty and the ``GENESIS_DIFFICULTY``. - Parameters - ---------- - block_number : - Block number of the block. - block_timestamp : - Timestamp of the block. - parent_timestamp : - Timestamp of the parent block. - parent_difficulty : - difficulty of the parent block. - parent_has_ommers: - does the parent have ommers. - - Returns - ------- - difficulty : `ethereum.base_types.Uint` - Computed difficulty for a block. + #### Parameters + - block_number: Block number of the block. + - block_timestamp: Timestamp of the block. + - parent_timestamp: Timestamp of the parent block. + - parent_difficulty: difficulty of the parent block. + - parent_has_ommers: does the parent have ommers. + + #### Returns + - difficulty: `ethereum.base_types.Uint` + Computed difficulty for a block. """ offset = ( int(parent_difficulty) diff --git a/src/ethereum/arrow_glacier/fork_types.py b/src/ethereum/arrow_glacier/fork_types.py index c45044c60b..c0d3ee87c9 100644 --- a/src/ethereum/arrow_glacier/fork_types.py +++ b/src/ethereum/arrow_glacier/fork_types.py @@ -1,13 +1,7 @@ """ -Ethereum Types -^^^^^^^^^^^^^^ +# Ethereum Types -.. contents:: Table of Contents - :backlinks: none - :local: - -Introduction ------------- +## Introduction Types re-used throughout the specification, which are specific to Ethereum. """ diff --git a/src/ethereum/arrow_glacier/state.py b/src/ethereum/arrow_glacier/state.py index 23d74a1e3c..080284de59 100644 --- a/src/ethereum/arrow_glacier/state.py +++ b/src/ethereum/arrow_glacier/state.py @@ -1,13 +1,7 @@ """ -State -^^^^^ +# State -.. contents:: Table of Contents - :backlinks: none - :local: - -Introduction ------------- +## Introduction The state contains all information that is preserved between transactions. @@ -66,10 +60,9 @@ def begin_transaction(state: State) -> None: Transactions are entirely implicit and can be nested. It is not possible to calculate the state root during a transaction. - Parameters - ---------- - state : State - The state. + #### Parameters + - state: State + The state. """ state._snapshots.append( ( @@ -83,10 +76,9 @@ def commit_transaction(state: State) -> None: """ Commit a state transaction. - Parameters - ---------- - state : State - The state. + #### Parameters + - state: State + The state. """ state._snapshots.pop() if not state._snapshots: @@ -98,10 +90,9 @@ def rollback_transaction(state: State) -> None: Rollback a state transaction, resetting the state to the point when the corresponding `start_transaction()` call was made. - Parameters - ---------- - state : State - The state. + #### Parameters + - state: State + The state. """ state._main_trie, state._storage_tries = state._snapshots.pop() if not state._snapshots: @@ -116,17 +107,15 @@ def get_account(state: State, address: Address) -> Account: Use `get_account_optional()` if you care about the difference between a non-existent account and `EMPTY_ACCOUNT`. - Parameters - ---------- - state: `State` - The state - address : `Address` - Address to lookup. + #### Parameters + - state: `State` + The state + - address: `Address` + Address to lookup. - Returns - ------- - account : `Account` - Account at address. + #### Returns + - account: `Account` + Account at address. """ account = get_account_optional(state, address) if isinstance(account, Account): @@ -140,17 +129,15 @@ def get_account_optional(state: State, address: Address) -> Optional[Account]: Get the `Account` object at an address. Returns `None` (rather than `EMPTY_ACCOUNT`) if there is no account at the address. - Parameters - ---------- - state: `State` - The state - address : `Address` - Address to lookup. + #### Parameters + - state: `State` + The state + - address: `Address` + Address to lookup. - Returns - ------- - account : `Account` - Account at address. + #### Returns + - account: `Account` + Account at address. """ account = trie_get(state._main_trie, address) return account @@ -163,14 +150,13 @@ def set_account( Set the `Account` object at an address. Setting to `None` deletes the account (but not its storage, see `destroy_account()`). - Parameters - ---------- - state: `State` - The state - address : `Address` - Address to set. - account : `Account` - Account to set at address. + #### Parameters + - state: `State` + The state + - address: `Address` + Address to set. + - account: `Account` + Account to set at address. """ trie_set(state._main_trie, address, account) @@ -183,12 +169,11 @@ def destroy_account(state: State, address: Address) -> None: opcode. It is expected that `SELFDESTRUCT` will be disabled in a future hardfork and this function will be removed. - Parameters - ---------- - state: `State` - The state - address : `Address` - Address of account to destroy. + #### Parameters + - state: `State` + The state + - address: `Address` + Address of account to destroy. """ destroy_storage(state, address) set_account(state, address, None) @@ -198,12 +183,11 @@ def destroy_storage(state: State, address: Address) -> None: """ Completely remove the storage at `address`. - Parameters - ---------- - state: `State` - The state - address : `Address` - Address of account whose storage is to be deleted. + #### Parameters + - state: `State` + The state + - address: `Address` + Address of account whose storage is to be deleted. """ if address in state._storage_tries: del state._storage_tries[address] @@ -219,12 +203,11 @@ def mark_account_created(state: State, address: Address) -> None: account cannot have had code prior to its creation and can't call `get_storage_original()`, this is harmless. - Parameters - ---------- - state: `State` - The state - address : `Address` - Address of the account that has been created. + #### Parameters + - state: `State` + The state + - address: `Address` + Address of the account that has been created. """ state.created_accounts.add(address) @@ -234,19 +217,17 @@ def get_storage(state: State, address: Address, key: Bytes32) -> U256: Get a value at a storage key on an account. Returns `U256(0)` if the storage key has not been set previously. - Parameters - ---------- - state: `State` - The state - address : `Address` - Address of the account. - key : `Bytes` - Key to lookup. + #### Parameters + - state: `State` + The state + - address: `Address` + Address of the account. + - key: `Bytes` + Key to lookup. - Returns - ------- - value : `U256` - Value at the key. + #### Returns + - value: `U256` + Value at the key. """ trie = state._storage_tries.get(address) if trie is None: @@ -265,16 +246,15 @@ def set_storage( Set a value at a storage key on an account. Setting to `U256(0)` deletes the key. - Parameters - ---------- - state: `State` - The state - address : `Address` - Address of the account. - key : `Bytes` - Key to set. - value : `U256` - Value to set at the key. + #### Parameters + - state: `State` + The state + - address: `Address` + Address of the account. + - key: `Bytes` + Key to set. + - value: `U256` + Value to set at the key. """ assert trie_get(state._main_trie, address) is not None @@ -291,17 +271,13 @@ def storage_root(state: State, address: Address) -> Root: """ Calculate the storage root of an account. - Parameters - ---------- - state: - The state - address : - Address of the account. + #### Parameters + - state: The state + - address: Address of the account. - Returns - ------- - root : `Root` - Storage root of the account. + #### Returns + - root: `Root` + Storage root of the account. """ assert not state._snapshots if address in state._storage_tries: @@ -314,15 +290,12 @@ def state_root(state: State) -> Root: """ Calculate the state root. - Parameters - ---------- - state: - The current state. + #### Parameters + - state: The current state. - Returns - ------- - root : `Root` - The state root. + #### Returns + - root: `Root` + The state root. """ assert not state._snapshots @@ -336,17 +309,13 @@ def account_exists(state: State, address: Address) -> bool: """ Checks if an account exists in the state trie - Parameters - ---------- - state: - The state - address: - Address of the account that needs to be checked. + #### Parameters + - state: The state + - address: Address of the account that needs to be checked. - Returns - ------- - account_exists : `bool` - True if account exists in the state trie, False otherwise + #### Returns + - account_exists : `bool` + True if account exists in the state trie, False otherwise """ return get_account_optional(state, address) is not None @@ -355,18 +324,13 @@ def account_has_code_or_nonce(state: State, address: Address) -> bool: """ Checks if an account has non zero nonce or non empty code - Parameters - ---------- - state: - The state - address: - Address of the account that needs to be checked. + #### Parameters + - state: The state + - address: Address of the account that needs to be checked. - Returns - ------- - has_code_or_nonce : `bool` - True if the account has non zero nonce or non empty code, - False otherwise. + #### Returns + - has_code_or_nonce: `bool` + True if the account has non zero nonce or non empty code, False otherwise. """ account = get_account(state, address) return account.nonce != Uint(0) or account.code != b"" @@ -376,17 +340,13 @@ def account_has_storage(state: State, address: Address) -> bool: """ Checks if an account has storage. - Parameters - ---------- - state: - The state - address: - Address of the account that needs to be checked. + #### Parameters + - state: The state + - address: Address of the account that needs to be checked. - Returns - ------- - has_storage : `bool` - True if the account has storage, False otherwise. + #### Returns + - has_storage: `bool` + True if the account has storage, False otherwise. """ return address in state._storage_tries @@ -395,18 +355,14 @@ def is_account_empty(state: State, address: Address) -> bool: """ Checks if an account has zero nonce, empty code and zero balance. - Parameters - ---------- - state: - The state - address: - Address of the account that needs to be checked. + #### Parameters + - state: The state + - address: Address of the account that needs to be checked. - Returns - ------- - is_empty : `bool` - True if an account has zero nonce, empty code and zero balance, - False otherwise. + #### Returns + - is_empty: `bool` + True if an account has zero nonce, empty code and zero balance, False + otherwise. """ account = get_account(state, address) return ( @@ -421,18 +377,14 @@ def account_exists_and_is_empty(state: State, address: Address) -> bool: Checks if an account exists and has zero nonce, empty code and zero balance. - Parameters - ---------- - state: - The state - address: - Address of the account that needs to be checked. + #### Parameters + - state: The state + - address: Address of the account that needs to be checked. - Returns - ------- - exists_and_is_empty : `bool` - True if an account exists and has zero nonce, empty code and zero - balance, False otherwise. + #### Returns + - exists_and_is_empty : `bool` + True if an account exists and has zero nonce, empty code and zero balance, + False otherwise. """ account = get_account_optional(state, address) return ( @@ -447,17 +399,13 @@ def is_account_alive(state: State, address: Address) -> bool: """ Check whether is an account is both in the state and non empty. - Parameters - ---------- - state: - The state - address: - Address of the account that needs to be checked. + #### Parameters + - state: The state + - address: Address of the account that needs to be checked. - Returns - ------- - is_alive : `bool` - True if the account is alive. + #### Returns + - is_alive: `bool` + True if the account is alive. """ account = get_account_optional(state, address) return account is not None and account != EMPTY_ACCOUNT @@ -498,16 +446,10 @@ def set_account_balance(state: State, address: Address, amount: U256) -> None: """ Sets the balance of an account. - Parameters - ---------- - state: - The current state. - - address: - Address of the account whose nonce needs to be incremented. - - amount: - The amount that needs to set in balance. + #### Parameters + - state: The current state. + - address: Address of the account whose nonce needs to be incremented. + - amount: The amount that needs to set in balance. """ def set_balance(account: Account) -> None: @@ -520,13 +462,9 @@ def touch_account(state: State, address: Address) -> None: """ Initializes an account to state. - Parameters - ---------- - state: - The current state. - - address: - The address of the account that need to initialised. + #### Parameters + - state: The current state. + - address: The address of the account that need to initialised. """ if not account_exists(state, address): set_account(state, address, EMPTY_ACCOUNT) @@ -536,13 +474,9 @@ def increment_nonce(state: State, address: Address) -> None: """ Increments the nonce of an account. - Parameters - ---------- - state: - The current state. - - address: - Address of the account whose nonce needs to be incremented. + #### Parameters + - state: The current state. + - address: Address of the account whose nonce needs to be incremented. """ def increase_nonce(sender: Account) -> None: @@ -555,16 +489,10 @@ def set_code(state: State, address: Address, code: Bytes) -> None: """ Sets Account code. - Parameters - ---------- - state: - The current state. - - address: - Address of the account whose code needs to be update. - - code: - The bytecode that needs to be set. + #### Parameters + - state: The current state. + - address: Address of the account whose code needs to be update. + - code: The bytecode that needs to be set. """ def write_code(sender: Account) -> None: @@ -577,14 +505,10 @@ def create_ether(state: State, address: Address, amount: U256) -> None: """ Add newly created ether to an account. - Parameters - ---------- - state: - The current state. - address: - Address of the account to which ether is added. - amount: - The amount of ether to be added to the account of interest. + #### Parameters + - state: The current state. + - address: Address of the account to which ether is added. + - amount: The amount of ether to be added to the account of interest. """ def increase_balance(account: Account) -> None: @@ -599,14 +523,10 @@ def get_storage_original(state: State, address: Address, key: Bytes32) -> U256: transaction began. This function reads the value from the snapshots taken before executing the transaction. - Parameters - ---------- - state: - The current state. - address: - Address of the account to read the value from. - key: - Key of the storage slot. + #### Parameters + - state: The current state. + - address: Address of the account to read the value from. + - key: Key of the storage slot. """ # In the transaction where an account is created, its preexisting storage # is ignored. @@ -631,12 +551,11 @@ def destroy_touched_empty_accounts( ) -> None: """ Destroy all touched accounts that are empty. - Parameters - ---------- - state: `State` - The current state. - touched_accounts: `Iterable[Address]` - All the accounts that have been touched in the current transaction. + #### Parameters + - state: `State` + The current state. + - touched_accounts: `Iterable[Address]` + All the accounts that have been touched in the current transaction. """ for address in touched_accounts: if account_exists_and_is_empty(state, address): diff --git a/src/ethereum/arrow_glacier/transactions.py b/src/ethereum/arrow_glacier/transactions.py index 206a41b88a..63c1584df6 100644 --- a/src/ethereum/arrow_glacier/transactions.py +++ b/src/ethereum/arrow_glacier/transactions.py @@ -55,10 +55,9 @@ class LegacyTransaction: """ Atomic operation performed on the block chain. This represents the original - transaction format used before [EIP-1559], and [EIP-2930]. - - [EIP-1559]: https://eips.ethereum.org/EIPS/eip-1559 - [EIP-2930]: https://eips.ethereum.org/EIPS/eip-2930 + transaction format used before + [EIP-1559](https://eips.ethereum.org/EIPS/eip-1559), and + [EIP-2930](https://eips.ethereum.org/EIPS/eip-2930). """ nonce: U256 @@ -132,13 +131,13 @@ class Access: @dataclass class AccessListTransaction: """ - The transaction type added in [EIP-2930] to support access lists. + The transaction type added in + [EIP-2930](https://eips.ethereum.org/EIPS/eip-2930) to support access + lists. This transaction type extends the legacy transaction with an access list and chain ID. The access list specifies which addresses and storage slots the transaction will access. - - [EIP-2930]: https://eips.ethereum.org/EIPS/eip-2930 """ chain_id: U64 @@ -204,12 +203,11 @@ class AccessListTransaction: @dataclass class FeeMarketTransaction: """ - The transaction type added in [EIP-1559]. + The transaction type added in + [EIP-1559](https://eips.ethereum.org/EIPS/eip-1559). This transaction type introduces a new fee market mechanism with two gas price parameters: max_priority_fee_per_gas and max_fee_per_gas. - - [EIP-1559]: https://eips.ethereum.org/EIPS/eip-1559 """ chain_id: U64 @@ -331,7 +329,7 @@ def validate_transaction(tx: Transaction) -> Uint: be possible to execute a transaction and it will be declared invalid. Additionally, the nonce of a transaction must not equal or exceed the - limit defined in [EIP-2681]. + limit defined in [EIP-2681](https://eips.ethereum.org/EIPS/eip-2681). In practice, defining the limit as ``2**64-1`` has no impact because sending ``2**64-1`` transactions is improbable. It's not strictly impossible though, ``2**64-1`` transactions is the entire capacity of the @@ -340,8 +338,6 @@ def validate_transaction(tx: Transaction) -> Uint: This function takes a transaction as a parameter and returns the intrinsic gas cost of the transaction after validation. It throws an `InvalidTransaction` exception if the transaction is invalid. - - [EIP-2681]: https://eips.ethereum.org/EIPS/eip-2681 """ intrinsic_gas = calculate_intrinsic_cost(tx) if intrinsic_gas > tx.gas: @@ -451,13 +447,11 @@ def recover_sender(chain_id: U64, tx: Transaction) -> Address: def signing_hash_pre155(tx: LegacyTransaction) -> Hash32: """ - Compute the hash of a transaction used in a legacy (pre [EIP-155]) - signature. + Compute the hash of a transaction used in a legacy (pre + [EIP-155](https://eips.ethereum.org/EIPS/eip-155)) signature. This function takes a legacy transaction as a parameter and returns the signing hash of the transaction. - - [EIP-155]: https://eips.ethereum.org/EIPS/eip-155 """ return keccak256( rlp.encode( @@ -475,12 +469,12 @@ def signing_hash_pre155(tx: LegacyTransaction) -> Hash32: def signing_hash_155(tx: LegacyTransaction, chain_id: U64) -> Hash32: """ - Compute the hash of a transaction used in a [EIP-155] signature. + Compute the hash of a transaction used in a + [EIP-155](https://eips.ethereum.org/EIPS/eip-155) signature. This function takes a legacy transaction and a chain ID as parameters - and returns the hash of the transaction used in an [EIP-155] signature. - - [EIP-155]: https://eips.ethereum.org/EIPS/eip-155 + and returns the hash of the transaction used in an + [EIP-155](https://eips.ethereum.org/EIPS/eip-155) signature. """ return keccak256( rlp.encode( @@ -501,12 +495,12 @@ def signing_hash_155(tx: LegacyTransaction, chain_id: U64) -> Hash32: def signing_hash_2930(tx: AccessListTransaction) -> Hash32: """ - Compute the hash of a transaction used in a [EIP-2930] signature. + Compute the hash of a transaction used in a + [EIP-2930](https://eips.ethereum.org/EIPS/eip-2930) signature. This function takes an access list transaction as a parameter - and returns the hash of the transaction used in an [EIP-2930] signature. - - [EIP-2930]: https://eips.ethereum.org/EIPS/eip-2930 + and returns the hash of the transaction used in an + [EIP-2930](https://eips.ethereum.org/EIPS/eip-2930) signature. """ return keccak256( b"\x01" @@ -527,12 +521,12 @@ def signing_hash_2930(tx: AccessListTransaction) -> Hash32: def signing_hash_1559(tx: FeeMarketTransaction) -> Hash32: """ - Compute the hash of a transaction used in an [EIP-1559] signature. + Compute the hash of a transaction used in an + [EIP-1559](https://eips.ethereum.org/EIPS/eip-1559) signature. This function takes a fee market transaction as a parameter - and returns the hash of the transaction used in an [EIP-1559] signature. - - [EIP-1559]: https://eips.ethereum.org/EIPS/eip-1559 + and returns the hash of the transaction used in an + [EIP-1559](https://eips.ethereum.org/EIPS/eip-1559) signature. """ return keccak256( b"\x02" diff --git a/src/ethereum/arrow_glacier/trie.py b/src/ethereum/arrow_glacier/trie.py index 2b09d4c771..5fb4d7f516 100644 --- a/src/ethereum/arrow_glacier/trie.py +++ b/src/ethereum/arrow_glacier/trie.py @@ -1,13 +1,7 @@ """ -State Trie -^^^^^^^^^^ +# State Trie -.. contents:: Table of Contents - :backlinks: none - :local: - -Introduction ------------- +## Introduction The state trie is the structure responsible for storing `.fork_types.Account` objects. @@ -136,15 +130,13 @@ def encode_internal_node(node: Optional[InternalNode]) -> Extended: This function also accepts `None`, representing the absence of a node, which is encoded to `b""`. - Parameters - ---------- - node : Optional[InternalNode] - The node to encode. + #### Parameters + - node: Optional[InternalNode] + The node to encode. - Returns - ------- - encoded : `rlp.RLP` - The node encoded as RLP. + #### Returns + - encoded: `rlp.RLP` + The node encoded as RLP. """ unencoded: Extended if node is None: @@ -204,15 +196,13 @@ def copy_trie(trie: Trie[K, V]) -> Trie[K, V]: Create a copy of `trie`. Since only frozen objects may be stored in tries, the contents are reused. - Parameters - ---------- - trie: `Trie` - Trie to copy. + #### Parameters + - trie: `Trie` + Trie to copy. - Returns - ------- - new_trie : `Trie[K, V]` - A copy of the trie. + #### Returns + - new_trie: `Trie[K, V]` + A copy of the trie. """ return Trie(trie.secured, trie.default, copy.copy(trie._data)) @@ -224,14 +214,13 @@ def trie_set(trie: Trie[K, V], key: K, value: V) -> None: This method deletes the key if `value == trie.default`, because the Merkle Trie represents the default value by omitting it from the trie. - Parameters - ---------- - trie: `Trie` - Trie to store in. - key : `Bytes` - Key to lookup. - value : `V` - Node to insert at `key`. + #### Parameters + - trie: `Trie` + Trie to store in. + - key: `Bytes` + Key to lookup. + - value: `V` + Node to insert at `key`. """ if value == trie.default: if key in trie._data: @@ -246,17 +235,13 @@ def trie_get(trie: Trie[K, V], key: K) -> V: This method returns `trie.default` if the key is missing. - Parameters - ---------- - trie: - Trie to lookup in. - key : - Key to lookup. - - Returns - ------- - node : `V` - Node at `key` in the trie. + #### Parameters + - trie: Trie to lookup in. + - key: Key to lookup. + + #### Returns + - node: `V` + Node at `key` in the trie. """ return trie._data.get(key, trie.default) @@ -292,18 +277,14 @@ def nibble_list_to_compact(x: Bytes, is_leaf: bool) -> Bytes: is used to distinguish leaf and extension nodes. The other two bits are not used. - Parameters - ---------- - x : - Array of nibbles. - is_leaf : - True if this is part of a leaf node, or false if it is an extension - node. - - Returns - ------- - compressed : `bytearray` - Compact byte array. + #### Parameters + - x: Array of nibbles. + - is_leaf: True if this is part of a leaf node, or false if it is an + extension node. + + #### Returns + - compressed: `bytearray` + Compact byte array. """ compact = bytearray() @@ -323,15 +304,13 @@ def bytes_to_nibble_list(bytes_: Bytes) -> Bytes: """ Converts a `Bytes` into to a sequence of nibbles (bytes with value < 16). - Parameters - ---------- - bytes_: - The `Bytes` to convert. + #### Parameters + - bytes_: + The `Bytes` to convert. - Returns - ------- - nibble_list : `Bytes` - The `Bytes` in nibble-list format. + #### Returns + - nibble_list: `Bytes` + The `Bytes` in nibble-list format. """ nibble_list = bytearray(2 * len(bytes_)) for byte_index, byte in enumerate(bytes_): @@ -348,18 +327,14 @@ def _prepare_trie( Prepares the trie for root calculation. Removes values that are empty, hashes the keys (if `secured == True`) and encodes all the nodes. - Parameters - ---------- - trie : - The `Trie` to prepare. - get_storage_root : - Function to get the storage root of an account. Needed to encode - `Account` objects. - - Returns - ------- - out : `Mapping[ethereum.base_types.Bytes, Node]` - Object with keys mapped to nibble-byte form. + #### Parameters + - trie: The `Trie` to prepare. + - get_storage_root : Function to get the storage root of an account. + Needed to encode `Account` objects. + + #### Returns + - out: `Mapping[ethereum.base_types.Bytes, Node]` + Object with keys mapped to nibble-byte form. """ mapped: MutableMapping[Bytes, Bytes] = {} @@ -390,19 +365,15 @@ def root( """ Computes the root of a modified merkle patricia trie (MPT). - Parameters - ---------- - trie : - `Trie` to get the root of. - get_storage_root : - Function to get the storage root of an account. Needed to encode - `Account` objects. + #### Parameters + - trie: `Trie` to get the root of. + - get_storage_root: Function to get the storage root of an account. Needed + to encode `Account` objects. - Returns - ------- - root : `.fork_types.Root` - MPT root of the underlying key-value pairs. + #### Returns + - root: `.fork_types.Root` + MPT root of the underlying key-value pairs. """ obj = _prepare_trie(trie, get_storage_root) @@ -423,17 +394,13 @@ def patricialize( Used to recursively patricialize and merkleize a dictionary. Includes memoization of the tree structure and hashes. - Parameters - ---------- - obj : - Underlying trie key-value pairs, with keys in nibble-list format. - level : - Current trie level. - - Returns - ------- - node : `ethereum.base_types.Bytes` - Root node of `obj`. + #### Parameters + - obj: Underlying trie key-value pairs, with keys in nibble-list format. + - level: Current trie level. + + #### Returns + - node: `ethereum.base_types.Bytes` + Root node of `obj`. """ if len(obj) == 0: return None diff --git a/src/ethereum/arrow_glacier/utils/address.py b/src/ethereum/arrow_glacier/utils/address.py index a19077d4ea..36796bf58c 100644 --- a/src/ethereum/arrow_glacier/utils/address.py +++ b/src/ethereum/arrow_glacier/utils/address.py @@ -1,13 +1,7 @@ """ -Hardfork Utility Functions For Addresses -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +# Hardfork Utility Functions For Addresses -.. contents:: Table of Contents - :backlinks: none - :local: - -Introduction ------------- +## Introduction Address specific functions used in this arrow_glacier version of specification. @@ -28,15 +22,12 @@ def to_address(data: Union[Uint, U256]) -> Address: """ Convert a Uint or U256 value to a valid address (20 bytes). - Parameters - ---------- - data : - The string to be converted to bytes. + #### Parameters + - data: The string to be converted to bytes. - Returns - ------- - address : `Address` - The obtained address. + #### Returns + - address: `Address` + The obtained address. """ return Address(data.to_be_bytes32()[-20:]) @@ -45,18 +36,14 @@ def compute_contract_address(address: Address, nonce: Uint) -> Address: """ Computes address of the new account that needs to be created. - Parameters - ---------- - address : - The address of the account that wants to create the new account. - nonce : - The transaction count of the account that wants to create the new - account. - - Returns - ------- - address: `Address` - The computed address of the new account. + #### Parameters + - address: The address of the account that wants to create the new account. + - nonce: The transaction count of the account that wants to create the new + account. + + #### Returns + - address: `Address` + The computed address of the new account. """ computed_address = keccak256(rlp.encode([address, nonce])) canonical_address = computed_address[-20:] @@ -71,19 +58,14 @@ def compute_create2_contract_address( Computes address of the new account that needs to be created, which is based on the sender address, salt and the call data as well. - Parameters - ---------- - address : - The address of the account that wants to create the new account. - salt : - Address generation salt. - call_data : - The code of the new account which is to be created. - - Returns - ------- - address: `ethereum.arrow_glacier.fork_types.Address` - The computed address of the new account. + #### Parameters + - address: The address of the account that wants to create the new account. + - salt: Address generation salt. + - call_data: The code of the new account which is to be created. + + #### Returns + - address: `ethereum.arrow_glacier.fork_types.Address` + The computed address of the new account. """ preimage = b"\xff" + address + salt + keccak256(call_data) computed_address = keccak256(preimage) diff --git a/src/ethereum/arrow_glacier/utils/hexadecimal.py b/src/ethereum/arrow_glacier/utils/hexadecimal.py index f89513dc57..f96a449ad4 100644 --- a/src/ethereum/arrow_glacier/utils/hexadecimal.py +++ b/src/ethereum/arrow_glacier/utils/hexadecimal.py @@ -1,13 +1,7 @@ """ -Utility Functions For Hexadecimal Strings -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +# Utility Functions For Hexadecimal Strings -.. contents:: Table of Contents - :backlinks: none - :local: - -Introduction ------------- +## Introduction Hexadecimal utility functions used in this specification, specific to Arrow Glacier types. @@ -23,15 +17,12 @@ def hex_to_root(hex_string: str) -> Root: """ Convert hex string to trie root. - Parameters - ---------- - hex_string : - The hexadecimal string to be converted to trie root. + #### Parameters + - hex_string: The hexadecimal string to be converted to trie root. - Returns - ------- - root : `Root` - Trie root obtained from the given hexadecimal string. + #### Returns + - root: `Root` + Trie root obtained from the given hexadecimal string. """ return Root(Bytes.fromhex(remove_hex_prefix(hex_string))) @@ -40,15 +31,12 @@ def hex_to_bloom(hex_string: str) -> Bloom: """ Convert hex string to bloom. - Parameters - ---------- - hex_string : - The hexadecimal string to be converted to bloom. + #### Parameters + - hex_string: The hexadecimal string to be converted to bloom. - Returns - ------- - bloom : `Bloom` - Bloom obtained from the given hexadecimal string. + #### Returns + - bloom: `Bloom` + Bloom obtained from the given hexadecimal string. """ return Bloom(Bytes.fromhex(remove_hex_prefix(hex_string))) @@ -57,14 +45,11 @@ def hex_to_address(hex_string: str) -> Address: """ Convert hex string to Address (20 bytes). - Parameters - ---------- - hex_string : - The hexadecimal string to be converted to Address. + #### Parameters + - hex_string: The hexadecimal string to be converted to Address. - Returns - ------- - address : `Address` - The address obtained from the given hexadecimal string. + #### Returns + - address: `Address` + The address obtained from the given hexadecimal string. """ return Address(Bytes.fromhex(remove_hex_prefix(hex_string).rjust(40, "0"))) diff --git a/src/ethereum/arrow_glacier/utils/message.py b/src/ethereum/arrow_glacier/utils/message.py index 34461d7656..2d3cf1352a 100644 --- a/src/ethereum/arrow_glacier/utils/message.py +++ b/src/ethereum/arrow_glacier/utils/message.py @@ -1,13 +1,7 @@ """ -Hardfork Utility Functions For The Message Data-structure -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +# Hardfork Utility Functions For The Message Data-structure -.. contents:: Table of Contents - :backlinks: none - :local: - -Introduction ------------- +## Introduction Message specific functions used in this arrow_glacier version of specification. @@ -31,19 +25,14 @@ def prepare_message( """ Execute a transaction against the provided environment. - Parameters - ---------- - block_env : - Environment for the Ethereum Virtual Machine. - tx_env : - Environment for the transaction. - tx : - Transaction to be executed. + #### Parameters + - block_env: Environment for the Ethereum Virtual Machine. + - tx_env: Environment for the transaction. + - tx: Transaction to be executed. - Returns - ------- - message: `ethereum.arrow_glacier.vm.Message` - Items containing contract creation or message call specific data. + #### Returns + - message: `ethereum.arrow_glacier.vm.Message` + Items containing contract creation or message call specific data. """ accessed_addresses = set() accessed_addresses.add(tx_env.origin) diff --git a/src/ethereum/arrow_glacier/vm/__init__.py b/src/ethereum/arrow_glacier/vm/__init__.py index ce60ea1105..22894511fe 100644 --- a/src/ethereum/arrow_glacier/vm/__init__.py +++ b/src/ethereum/arrow_glacier/vm/__init__.py @@ -1,13 +1,7 @@ """ -Ethereum Virtual Machine (EVM) -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +# Ethereum Virtual Machine (EVM) -.. contents:: Table of Contents - :backlinks: none - :local: - -Introduction ------------- +## Introduction The abstract computer which runs the code stored in an `.fork_types.Account`. @@ -56,17 +50,16 @@ class BlockOutput: Contains the following: - block_gas_used : `ethereum.base_types.Uint` - Gas used for executing all transactions. - transactions_trie : `ethereum.fork_types.Root` - Trie of all the transactions in the block. - receipts_trie : `ethereum.fork_types.Root` - Trie root of all the receipts in the block. - receipt_keys : - Key of all the receipts in the block. - block_logs : `Bloom` - Logs bloom of all the logs included in all the transactions of the - block. + - block_gas_used: `ethereum.base_types.Uint` + Gas used for executing all transactions. + - transactions_trie: `ethereum.fork_types.Root` + Trie of all the transactions in the block. + - receipts_trie: `ethereum.fork_types.Root` + Trie root of all the receipts in the block. + - receipt_keys: + Key of all the receipts in the block. + - block_logs: `Bloom` + Logs bloom of all the logs included in all the transactions of the block. """ block_gas_used: Uint = Uint(0) @@ -147,12 +140,9 @@ def incorporate_child_on_success(evm: Evm, child_evm: Evm) -> None: """ Incorporate the state of a successful `child_evm` into the parent `evm`. - Parameters - ---------- - evm : - The parent `EVM`. - child_evm : - The child evm to incorporate. + #### Parameters + - evm: The parent `EVM`. + - child_evm: The child evm to incorporate. """ evm.gas_left += child_evm.gas_left evm.logs += child_evm.logs @@ -171,12 +161,9 @@ def incorporate_child_on_error(evm: Evm, child_evm: Evm) -> None: """ Incorporate the state of an unsuccessful `child_evm` into the parent `evm`. - Parameters - ---------- - evm : - The parent `EVM`. - child_evm : - The child evm to incorporate. + #### Parameters + - evm: The parent `EVM`. + - child_evm: The child evm to incorporate. """ # In block 2675119, the empty account at 0x3 (the RIPEMD160 precompile) was # cleared despite running out of gas. This is an obscure edge case that can diff --git a/src/ethereum/arrow_glacier/vm/exceptions.py b/src/ethereum/arrow_glacier/vm/exceptions.py index 6d30e2846d..90fd852102 100644 --- a/src/ethereum/arrow_glacier/vm/exceptions.py +++ b/src/ethereum/arrow_glacier/vm/exceptions.py @@ -1,13 +1,7 @@ """ -Ethereum Virtual Machine (EVM) Exceptions -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +# Ethereum Virtual Machine (EVM) Exceptions -.. contents:: Table of Contents - :backlinks: none - :local: - -Introduction ------------- +## Introduction Exceptions which cause the EVM to halt exceptionally. """ diff --git a/src/ethereum/arrow_glacier/vm/gas.py b/src/ethereum/arrow_glacier/vm/gas.py index 43d2905de1..26bd025598 100644 --- a/src/ethereum/arrow_glacier/vm/gas.py +++ b/src/ethereum/arrow_glacier/vm/gas.py @@ -1,13 +1,7 @@ """ -Ethereum Virtual Machine (EVM) Gas -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +# Ethereum Virtual Machine (EVM) Gas -.. contents:: Table of Contents - :backlinks: none - :local: - -Introduction ------------- +## Introduction EVM gas constants and calculators. """ @@ -69,10 +63,10 @@ class ExtendMemory: """ Define the parameters for memory extension in opcodes - `cost`: `ethereum.base_types.Uint` - The gas required to perform the extension - `expand_by`: `ethereum.base_types.Uint` - The size by which the memory will be extended + - `cost`: `ethereum.base_types.Uint` + The gas required to perform the extension + - `expand_by`: `ethereum.base_types.Uint` + The size by which the memory will be extended """ cost: Uint @@ -85,10 +79,10 @@ class MessageCallGas: Define the gas cost and gas given to the sub-call for executing the call opcodes. - `cost`: `ethereum.base_types.Uint` + - `cost`: `ethereum.base_types.Uint` The gas required to execute the call opcode, excludes memory expansion costs. - `sub_call`: `ethereum.base_types.Uint` + - `sub_call`: `ethereum.base_types.Uint` The portion of gas available to sub-calls that is refundable if not consumed. """ @@ -101,11 +95,10 @@ def charge_gas(evm: Evm, amount: Uint) -> None: """ Subtracts `amount` from `evm.gas_left`. - Parameters - ---------- - evm : + #### Parameters + - evm: The current EVM. - amount : + - amount: The amount of gas the current operation requires. """ @@ -123,15 +116,12 @@ def calculate_memory_gas_cost(size_in_bytes: Uint) -> Uint: to the smallest multiple of 32 bytes, such that the allocated size is at least as big as the given size. - Parameters - ---------- - size_in_bytes : - The size of the data in bytes. + #### Parameters + - size_in_bytes: The size of the data in bytes. - Returns - ------- - total_gas_cost : `ethereum.base_types.Uint` - The gas cost for storing data in memory. + #### Returns + - total_gas_cost: `ethereum.base_types.Uint` + The gas cost for storing data in memory. """ size_in_words = ceil32(size_in_bytes) // Uint(32) linear_cost = size_in_words * GAS_MEMORY @@ -149,13 +139,10 @@ def calculate_gas_extend_memory( """ Calculates the gas amount to extend memory - Parameters - ---------- - memory : - Memory contents of the EVM. - extensions: - List of extensions to be made to the memory. - Consists of a tuple of start position and size. + #### Parameters + - memory: Memory contents of the EVM. + - extensions: List of extensions to be made to the memory. Consists of a + tuple of start position and size. Returns ------- @@ -194,26 +181,19 @@ def calculate_message_call_gas( Calculates the MessageCallGas (cost and gas made available to the sub-call) for executing call Opcodes. - Parameters - ---------- - value: + #### Parameters + - value: The amount of `ETH` that needs to be transferred. - gas : - The amount of gas provided to the message-call. - gas_left : - The amount of gas left in the current frame. - memory_cost : - The amount needed to extend the memory in the current frame. - extra_gas : - The amount of gas needed for transferring value + creating a new - account inside a message call. - call_stipend : - The amount of stipend provided to a message call to execute code while - transferring value(ETH). - - Returns - ------- - message_call_gas: `MessageCallGas` + - gas: The amount of gas provided to the message-call. + - gas_left: The amount of gas left in the current frame. + - memory_cost: The amount needed to extend the memory in the current frame. + - extra_gas: The amount of gas needed for transferring value + creating a + new account inside a message call. + - call_stipend: The amount of stipend provided to a message call to + execute code while transferring value(ETH). + + #### Returns + - message_call_gas: `MessageCallGas` """ call_stipend = Uint(0) if value == 0 else call_stipend if gas_left < extra_gas + memory_cost: @@ -228,14 +208,11 @@ def max_message_call_gas(gas: Uint) -> Uint: """ Calculates the maximum gas that is allowed for making a message call - Parameters - ---------- - gas : - The amount of gas provided to the message-call. + #### Parameters + - gas: The amount of gas provided to the message-call. - Returns - ------- - max_allowed_message_call_gas: `ethereum.base_types.Uint` - The maximum gas allowed for making the message-call. + #### Returns + - max_allowed_message_call_gas: `ethereum.base_types.Uint` + The maximum gas allowed for making the message-call. """ return gas - (gas // Uint(64)) diff --git a/src/ethereum/arrow_glacier/vm/instructions/__init__.py b/src/ethereum/arrow_glacier/vm/instructions/__init__.py index f2bc795f74..32b6dc439d 100644 --- a/src/ethereum/arrow_glacier/vm/instructions/__init__.py +++ b/src/ethereum/arrow_glacier/vm/instructions/__init__.py @@ -1,13 +1,8 @@ """ -EVM Instruction Encoding (Opcodes) -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +# EVM Instruction Encoding (Opcodes) -.. contents:: Table of Contents - :backlinks: none - :local: -Introduction ------------- +## Introduction Machine readable representations of EVM instructions, and a mapping to their implementations. diff --git a/src/ethereum/arrow_glacier/vm/instructions/arithmetic.py b/src/ethereum/arrow_glacier/vm/instructions/arithmetic.py index 28c97db189..f0229b2320 100644 --- a/src/ethereum/arrow_glacier/vm/instructions/arithmetic.py +++ b/src/ethereum/arrow_glacier/vm/instructions/arithmetic.py @@ -1,13 +1,7 @@ """ -Ethereum Virtual Machine (EVM) Arithmetic Instructions -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +# Ethereum Virtual Machine (EVM) Arithmetic Instructions -.. contents:: Table of Contents - :backlinks: none - :local: - -Introduction ------------- +## Introduction Implementations of the EVM Arithmetic instructions. """ @@ -34,10 +28,8 @@ def add(evm: Evm) -> None: Adds the top two elements of the stack together, and pushes the result back on the stack. - Parameters - ---------- - evm : - The current EVM frame. + #### Parameters + - evm: The current EVM frame. """ # STACK @@ -61,10 +53,8 @@ def sub(evm: Evm) -> None: Subtracts the top two elements of the stack, and pushes the result back on the stack. - Parameters - ---------- - evm : - The current EVM frame. + #### Parameters + - evm: The current EVM frame. """ # STACK @@ -88,10 +78,8 @@ def mul(evm: Evm) -> None: Multiply the top two elements of the stack, and pushes the result back on the stack. - Parameters - ---------- - evm : - The current EVM frame. + #### Parameters + - evm: The current EVM frame. """ # STACK @@ -115,10 +103,8 @@ def div(evm: Evm) -> None: Integer division of the top two elements of the stack. Pushes the result back on the stack. - Parameters - ---------- - evm : - The current EVM frame. + #### Parameters + - evm: The current EVM frame. """ # STACK @@ -148,10 +134,8 @@ def sdiv(evm: Evm) -> None: Signed integer division of the top two elements of the stack. Pushes the result back on the stack. - Parameters - ---------- - evm : - The current EVM frame. + #### Parameters + - evm: The current EVM frame. """ # STACK @@ -181,10 +165,8 @@ def mod(evm: Evm) -> None: Modulo remainder of the top two elements of the stack. Pushes the result back on the stack. - Parameters - ---------- - evm : - The current EVM frame. + #### Parameters + - evm: The current EVM frame. """ # STACK @@ -211,10 +193,8 @@ def smod(evm: Evm) -> None: Signed modulo remainder of the top two elements of the stack. Pushes the result back on the stack. - Parameters - ---------- - evm : - The current EVM frame. + #### Parameters + - evm: The current EVM frame. """ # STACK @@ -241,10 +221,8 @@ def addmod(evm: Evm) -> None: Modulo addition of the top 2 elements with the 3rd element. Pushes the result back on the stack. - Parameters - ---------- - evm : - The current EVM frame. + #### Parameters + - evm: The current EVM frame. """ # STACK @@ -272,10 +250,8 @@ def mulmod(evm: Evm) -> None: Modulo multiplication of the top 2 elements with the 3rd element. Pushes the result back on the stack. - Parameters - ---------- - evm : - The current EVM frame. + #### Parameters + - evm: The current EVM frame. """ # STACK @@ -303,10 +279,8 @@ def exp(evm: Evm) -> None: Exponential operation of the top 2 elements. Pushes the result back on the stack. - Parameters - ---------- - evm : - The current EVM frame. + #### Parameters + - evm: The current EVM frame. """ # STACK @@ -336,10 +310,8 @@ def signextend(evm: Evm) -> None: Sign extend operation. In other words, extend a signed number which fits in N bytes to 32 bytes. - Parameters - ---------- - evm : - The current EVM frame. + #### Parameters + - evm: The current EVM frame. """ # STACK diff --git a/src/ethereum/arrow_glacier/vm/instructions/bitwise.py b/src/ethereum/arrow_glacier/vm/instructions/bitwise.py index 3abb58be48..c5b503871a 100644 --- a/src/ethereum/arrow_glacier/vm/instructions/bitwise.py +++ b/src/ethereum/arrow_glacier/vm/instructions/bitwise.py @@ -1,13 +1,7 @@ """ -Ethereum Virtual Machine (EVM) Bitwise Instructions -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +# Ethereum Virtual Machine (EVM) Bitwise Instructions -.. contents:: Table of Contents - :backlinks: none - :local: - -Introduction ------------- +## Introduction Implementations of the EVM bitwise instructions. """ @@ -24,10 +18,8 @@ def bitwise_and(evm: Evm) -> None: Bitwise AND operation of the top 2 elements of the stack. Pushes the result back on the stack. - Parameters - ---------- - evm : - The current EVM frame. + #### Parameters + - evm: The current EVM frame. """ # STACK @@ -49,10 +41,8 @@ def bitwise_or(evm: Evm) -> None: Bitwise OR operation of the top 2 elements of the stack. Pushes the result back on the stack. - Parameters - ---------- - evm : - The current EVM frame. + #### Parameters + - evm: The current EVM frame. """ # STACK @@ -74,10 +64,8 @@ def bitwise_xor(evm: Evm) -> None: Bitwise XOR operation of the top 2 elements of the stack. Pushes the result back on the stack. - Parameters - ---------- - evm : - The current EVM frame. + #### Parameters + - evm: The current EVM frame. """ # STACK @@ -99,10 +87,8 @@ def bitwise_not(evm: Evm) -> None: Bitwise NOT operation of the top element of the stack. Pushes the result back on the stack. - Parameters - ---------- - evm : - The current EVM frame. + #### Parameters + - evm: The current EVM frame. """ # STACK @@ -124,10 +110,8 @@ def get_byte(evm: Evm) -> None: Nth byte (0-indexed and defined by top element of stack) from the left (most significant) to right (least significant). - Parameters - ---------- - evm : - The current EVM frame. + #### Parameters + - evm: The current EVM frame. """ # STACK @@ -158,10 +142,8 @@ def bitwise_shl(evm: Evm) -> None: """ Logical shift left (SHL) operation of the top 2 elements of the stack. Pushes the result back on the stack. - Parameters - ---------- - evm : - The current EVM frame. + #### Parameters + - evm: The current EVM frame. """ # STACK shift = Uint(pop(evm.stack)) @@ -186,10 +168,8 @@ def bitwise_shr(evm: Evm) -> None: """ Logical shift right (SHR) operation of the top 2 elements of the stack. Pushes the result back on the stack. - Parameters - ---------- - evm : - The current EVM frame. + #### Parameters + - evm: The current EVM frame. """ # STACK shift = pop(evm.stack) @@ -214,10 +194,8 @@ def bitwise_sar(evm: Evm) -> None: """ Arithmetic shift right (SAR) operation of the top 2 elements of the stack. Pushes the result back on the stack. - Parameters - ---------- - evm : - The current EVM frame. + #### Parameters + - evm: The current EVM frame. """ # STACK shift = int(pop(evm.stack)) diff --git a/src/ethereum/arrow_glacier/vm/instructions/block.py b/src/ethereum/arrow_glacier/vm/instructions/block.py index 2abe8928f2..f9a63341eb 100644 --- a/src/ethereum/arrow_glacier/vm/instructions/block.py +++ b/src/ethereum/arrow_glacier/vm/instructions/block.py @@ -1,13 +1,7 @@ """ -Ethereum Virtual Machine (EVM) Block Instructions -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -.. contents:: Table of Contents - :backlinks: none - :local: +# Ethereum Virtual Machine (EVM) Block Instructions Introduction ------------- Implementations of the EVM block instructions. """ @@ -24,10 +18,8 @@ def block_hash(evm: Evm) -> None: Push the hash of one of the 256 most recent complete blocks onto the stack. The block number to hash is present at the top of the stack. - Parameters - ---------- - evm : - The current EVM frame. + #### Parameters + - evm: The current EVM frame. """ # STACK @@ -66,10 +58,8 @@ def coinbase(evm: Evm) -> None: Here the current block refers to the block in which the currently executing transaction/call resides. - Parameters - ---------- - evm : - The current EVM frame. + #### Parameters + - evm: The current EVM frame. """ # STACK @@ -93,10 +83,8 @@ def timestamp(evm: Evm) -> None: Here the current block refers to the block in which the currently executing transaction/call resides. - Parameters - ---------- - evm : - The current EVM frame. + #### Parameters + - evm: The current EVM frame. """ # STACK @@ -119,10 +107,8 @@ def number(evm: Evm) -> None: Here the current block refers to the block in which the currently executing transaction/call resides. - Parameters - ---------- - evm : - The current EVM frame. + #### Parameters + - evm: The current EVM frame. """ # STACK @@ -145,10 +131,8 @@ def difficulty(evm: Evm) -> None: Here the current block refers to the block in which the currently executing transaction/call resides. - Parameters - ---------- - evm : - The current EVM frame. + #### Parameters + - evm: The current EVM frame. """ # STACK @@ -171,10 +155,8 @@ def gas_limit(evm: Evm) -> None: Here the current block refers to the block in which the currently executing transaction/call resides. - Parameters - ---------- - evm : - The current EVM frame. + #### Parameters + - evm: The current EVM frame. """ # STACK @@ -194,10 +176,8 @@ def chain_id(evm: Evm) -> None: """ Push the chain id onto the stack. - Parameters - ---------- - evm : - The current EVM frame. + #### Parameters + - evm: The current EVM frame. """ # STACK diff --git a/src/ethereum/arrow_glacier/vm/instructions/comparison.py b/src/ethereum/arrow_glacier/vm/instructions/comparison.py index 275455ba53..2600081045 100644 --- a/src/ethereum/arrow_glacier/vm/instructions/comparison.py +++ b/src/ethereum/arrow_glacier/vm/instructions/comparison.py @@ -1,13 +1,7 @@ """ -Ethereum Virtual Machine (EVM) Comparison Instructions -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +# Ethereum Virtual Machine (EVM) Comparison Instructions -.. contents:: Table of Contents - :backlinks: none - :local: - -Introduction ------------- +## Introduction Implementations of the EVM Comparison instructions. """ @@ -24,10 +18,8 @@ def less_than(evm: Evm) -> None: Checks if the top element is less than the next top element. Pushes the result back on the stack. - Parameters - ---------- - evm : - The current EVM frame. + #### Parameters + - evm: The current EVM frame. """ # STACK @@ -50,10 +42,8 @@ def signed_less_than(evm: Evm) -> None: """ Signed less-than comparison. - Parameters - ---------- - evm : - The current EVM frame. + #### Parameters + - evm: The current EVM frame. """ # STACK @@ -77,10 +67,8 @@ def greater_than(evm: Evm) -> None: Checks if the top element is greater than the next top element. Pushes the result back on the stack. - Parameters - ---------- - evm : - The current EVM frame. + #### Parameters + - evm: The current EVM frame. """ # STACK @@ -103,10 +91,8 @@ def signed_greater_than(evm: Evm) -> None: """ Signed greater-than comparison. - Parameters - ---------- - evm : - The current EVM frame. + #### Parameters + - evm: The current EVM frame. """ # STACK @@ -130,10 +116,8 @@ def equal(evm: Evm) -> None: Checks if the top element is equal to the next top element. Pushes the result back on the stack. - Parameters - ---------- - evm : - The current EVM frame. + #### Parameters + - evm: The current EVM frame. """ # STACK @@ -157,10 +141,8 @@ def is_zero(evm: Evm) -> None: Checks if the top element is equal to 0. Pushes the result back on the stack. - Parameters - ---------- - evm : - The current EVM frame. + #### Parameters + - evm: The current EVM frame. """ # STACK diff --git a/src/ethereum/arrow_glacier/vm/instructions/control_flow.py b/src/ethereum/arrow_glacier/vm/instructions/control_flow.py index 7722661f79..7fd4416444 100644 --- a/src/ethereum/arrow_glacier/vm/instructions/control_flow.py +++ b/src/ethereum/arrow_glacier/vm/instructions/control_flow.py @@ -1,13 +1,7 @@ """ -Ethereum Virtual Machine (EVM) Control Flow Instructions -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +# Ethereum Virtual Machine (EVM) Control Flow Instructions -.. contents:: Table of Contents - :backlinks: none - :local: - -Introduction ------------- +## Introduction Implementations of the EVM control flow instructions. """ @@ -24,10 +18,8 @@ def stop(evm: Evm) -> None: """ Stop further execution of EVM code. - Parameters - ---------- - evm : - The current EVM frame. + #### Parameters + - evm: The current EVM frame. """ # STACK pass @@ -47,10 +39,8 @@ def jump(evm: Evm) -> None: Alter the program counter to the location specified by the top of the stack. - Parameters - ---------- - evm : - The current EVM frame. + #### Parameters + - evm: The current EVM frame. """ # STACK @@ -73,10 +63,8 @@ def jumpi(evm: Evm) -> None: condition is true. If the condition is not true, then the program counter would increase only by 1. - Parameters - ---------- - evm : - The current EVM frame. + #### Parameters + - evm: The current EVM frame. """ # STACK @@ -103,10 +91,8 @@ def pc(evm: Evm) -> None: Push onto the stack the value of the program counter after reaching the current instruction and without increasing it for the next instruction. - Parameters - ---------- - evm : - The current EVM frame. + #### Parameters + - evm: The current EVM frame. """ # STACK @@ -127,10 +113,8 @@ def gas_left(evm: Evm) -> None: Push the amount of available gas (including the corresponding reduction for the cost of this instruction) onto the stack. - Parameters - ---------- - evm : - The current EVM frame. + #### Parameters + - evm: The current EVM frame. """ # STACK @@ -152,10 +136,8 @@ def jumpdest(evm: Evm) -> None: to be used by `JUMP` and `JUMPI` opcodes to verify that their jump is valid. - Parameters - ---------- - evm : - The current EVM frame. + #### Parameters + - evm: The current EVM frame. """ # STACK diff --git a/src/ethereum/arrow_glacier/vm/instructions/environment.py b/src/ethereum/arrow_glacier/vm/instructions/environment.py index 172ce97d70..ef2f14f296 100644 --- a/src/ethereum/arrow_glacier/vm/instructions/environment.py +++ b/src/ethereum/arrow_glacier/vm/instructions/environment.py @@ -1,13 +1,7 @@ """ -Ethereum Virtual Machine (EVM) Environmental Instructions -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +# Ethereum Virtual Machine (EVM) Environmental Instructions -.. contents:: Table of Contents - :backlinks: none - :local: - -Introduction ------------- +## Introduction Implementations of the EVM environment related instructions. """ @@ -41,10 +35,8 @@ def address(evm: Evm) -> None: """ Pushes the address of the current executing account to the stack. - Parameters - ---------- - evm : - The current EVM frame. + #### Parameters + - evm: The current EVM frame. """ # STACK @@ -64,10 +56,8 @@ def balance(evm: Evm) -> None: """ Pushes the balance of the given account onto the stack. - Parameters - ---------- - evm : - The current EVM frame. + #### Parameters + - evm: The current EVM frame. """ # STACK @@ -95,10 +85,8 @@ def origin(evm: Evm) -> None: Pushes the address of the original transaction sender to the stack. The origin address can only be an EOA. - Parameters - ---------- - evm : - The current EVM frame. + #### Parameters + - evm: The current EVM frame. """ # STACK @@ -118,10 +106,8 @@ def caller(evm: Evm) -> None: """ Pushes the address of the caller onto the stack. - Parameters - ---------- - evm : - The current EVM frame. + #### Parameters + - evm: The current EVM frame. """ # STACK @@ -141,10 +127,8 @@ def callvalue(evm: Evm) -> None: """ Push the value (in wei) sent with the call onto the stack. - Parameters - ---------- - evm : - The current EVM frame. + #### Parameters + - evm: The current EVM frame. """ # STACK @@ -165,10 +149,8 @@ def calldataload(evm: Evm) -> None: Push a word (32 bytes) of the input data belonging to the current environment onto the stack. - Parameters - ---------- - evm : - The current EVM frame. + #### Parameters + - evm: The current EVM frame. """ # STACK @@ -190,10 +172,8 @@ def calldatasize(evm: Evm) -> None: """ Push the size of input data in current environment onto the stack. - Parameters - ---------- - evm : - The current EVM frame. + #### Parameters + - evm: The current EVM frame. """ # STACK @@ -216,10 +196,8 @@ def calldatacopy(evm: Evm) -> None: This will also expand the memory, in case that the memory is insufficient to store the data. - Parameters - ---------- - evm : - The current EVM frame. + #### Parameters + - evm: The current EVM frame. """ # STACK @@ -248,10 +226,8 @@ def codesize(evm: Evm) -> None: """ Push the size of code running in current environment onto the stack. - Parameters - ---------- - evm : - The current EVM frame. + #### Parameters + - evm: The current EVM frame. """ # STACK @@ -274,10 +250,8 @@ def codecopy(evm: Evm) -> None: This will also expand the memory, in case that the memory is insufficient to store the data. - Parameters - ---------- - evm : - The current EVM frame. + #### Parameters + - evm: The current EVM frame. """ # STACK @@ -306,10 +280,8 @@ def gasprice(evm: Evm) -> None: """ Push the gas price used in current environment onto the stack. - Parameters - ---------- - evm : - The current EVM frame. + #### Parameters + - evm: The current EVM frame. """ # STACK @@ -329,10 +301,8 @@ def extcodesize(evm: Evm) -> None: """ Push the code size of a given account onto the stack. - Parameters - ---------- - evm : - The current EVM frame. + #### Parameters + - evm: The current EVM frame. """ # STACK @@ -361,10 +331,8 @@ def extcodecopy(evm: Evm) -> None: """ Copy a portion of an account's code to memory. - Parameters - ---------- - evm : - The current EVM frame. + #### Parameters + - evm: The current EVM frame. """ # STACK @@ -403,10 +371,8 @@ def returndatasize(evm: Evm) -> None: """ Pushes the size of the return data buffer onto the stack. - Parameters - ---------- - evm : - The current EVM frame. + #### Parameters + - evm: The current EVM frame. """ # STACK pass @@ -425,10 +391,8 @@ def returndatacopy(evm: Evm) -> None: """ Copies data from the return data buffer code to memory - Parameters - ---------- - evm : - The current EVM frame. + #### Parameters + - evm: The current EVM frame. """ # STACK memory_start_index = pop(evm.stack) @@ -458,10 +422,8 @@ def returndatacopy(evm: Evm) -> None: def extcodehash(evm: Evm) -> None: """ Returns the keccak256 hash of a contract’s bytecode - Parameters - ---------- - evm : - The current EVM frame. + #### Parameters + - evm: The current EVM frame. """ # STACK address = to_address(pop(evm.stack)) @@ -494,10 +456,8 @@ def self_balance(evm: Evm) -> None: """ Pushes the balance of the current address to the stack. - Parameters - ---------- - evm : - The current EVM frame. + #### Parameters + - evm: The current EVM frame. """ # STACK @@ -522,10 +482,8 @@ def base_fee(evm: Evm) -> None: """ Pushes the base fee of the current block on to the stack. - Parameters - ---------- - evm : - The current EVM frame. + #### Parameters + - evm: The current EVM frame. """ # STACK diff --git a/src/ethereum/arrow_glacier/vm/instructions/keccak.py b/src/ethereum/arrow_glacier/vm/instructions/keccak.py index 830d368277..99bb8d0d08 100644 --- a/src/ethereum/arrow_glacier/vm/instructions/keccak.py +++ b/src/ethereum/arrow_glacier/vm/instructions/keccak.py @@ -1,13 +1,7 @@ """ -Ethereum Virtual Machine (EVM) Keccak Instructions -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +# Ethereum Virtual Machine (EVM) Keccak Instructions -.. contents:: Table of Contents - :backlinks: none - :local: - -Introduction ------------- +## Introduction Implementations of the EVM keccak instructions. """ @@ -35,10 +29,8 @@ def keccak(evm: Evm) -> None: This also expands the memory, in case the memory is insufficient to access the data's memory location. - Parameters - ---------- - evm : - The current EVM frame. + #### Parameters + - evm: The current EVM frame. """ # STACK diff --git a/src/ethereum/arrow_glacier/vm/instructions/log.py b/src/ethereum/arrow_glacier/vm/instructions/log.py index 87c06ed6be..2bc9206181 100644 --- a/src/ethereum/arrow_glacier/vm/instructions/log.py +++ b/src/ethereum/arrow_glacier/vm/instructions/log.py @@ -1,13 +1,7 @@ """ -Ethereum Virtual Machine (EVM) Logging Instructions -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +# Ethereum Virtual Machine (EVM) Logging Instructions -.. contents:: Table of Contents - :backlinks: none - :local: - -Introduction ------------- +## Introduction Implementations of the EVM logging instructions. """ @@ -36,12 +30,9 @@ def log_n(evm: Evm, num_topics: int) -> None: This will also expand the memory if the data (required by the log entry) corresponding to the memory is not accessible. - Parameters - ---------- - evm : - The current EVM frame. - num_topics : - The number of topics to be included in the log entry. + #### Parameters + - evm: The current EVM frame. + - num_topics: The number of topics to be included in the log entry. """ # STACK diff --git a/src/ethereum/arrow_glacier/vm/instructions/memory.py b/src/ethereum/arrow_glacier/vm/instructions/memory.py index 807f2a39fc..761e3d1326 100644 --- a/src/ethereum/arrow_glacier/vm/instructions/memory.py +++ b/src/ethereum/arrow_glacier/vm/instructions/memory.py @@ -1,13 +1,7 @@ """ -Ethereum Virtual Machine (EVM) Memory Instructions -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +# Ethereum Virtual Machine (EVM) Memory Instructions -.. contents:: Table of Contents - :backlinks: none - :local: - -Introduction ------------- +## Introduction Implementations of the EVM Memory instructions. """ @@ -31,10 +25,8 @@ def mstore(evm: Evm) -> None: This also expands the memory, if the memory is insufficient to store the word. - Parameters - ---------- - evm : - The current EVM frame. + #### Parameters + - evm: The current EVM frame. """ # STACK @@ -62,10 +54,8 @@ def mstore8(evm: Evm) -> None: This also expands the memory, if the memory is insufficient to store the word. - Parameters - ---------- - evm : - The current EVM frame. + #### Parameters + - evm: The current EVM frame. """ # STACK @@ -92,10 +82,8 @@ def mload(evm: Evm) -> None: """ Load word from memory. - Parameters - ---------- - evm : - The current EVM frame. + #### Parameters + - evm: The current EVM frame. """ # STACK @@ -122,10 +110,8 @@ def msize(evm: Evm) -> None: """ Push the size of active memory in bytes onto the stack. - Parameters - ---------- - evm : - The current EVM frame. + #### Parameters + - evm: The current EVM frame. """ # STACK diff --git a/src/ethereum/arrow_glacier/vm/instructions/stack.py b/src/ethereum/arrow_glacier/vm/instructions/stack.py index d6cbe02ca1..b8fe2c62e0 100644 --- a/src/ethereum/arrow_glacier/vm/instructions/stack.py +++ b/src/ethereum/arrow_glacier/vm/instructions/stack.py @@ -1,13 +1,7 @@ """ -Ethereum Virtual Machine (EVM) Stack Instructions -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +# Ethereum Virtual Machine (EVM) Stack Instructions -.. contents:: Table of Contents - :backlinks: none - :local: - -Introduction ------------- +## Introduction Implementations of the EVM stack related instructions. """ @@ -26,10 +20,8 @@ def pop(evm: Evm) -> None: """ Remove item from stack. - Parameters - ---------- - evm : - The current EVM frame. + #### Parameters + - evm: The current EVM frame. """ # STACK @@ -49,14 +41,10 @@ def push_n(evm: Evm, num_bytes: int) -> None: """ Pushes a N-byte immediate onto the stack. - Parameters - ---------- - evm : - The current EVM frame. - - num_bytes : - The number of immediate bytes to be read from the code and pushed to - the stack. + #### Parameters + - evm: The current EVM frame. + - num_bytes: The number of immediate bytes to be read from the code and + pushed to the stack. """ # STACK @@ -79,14 +67,10 @@ def dup_n(evm: Evm, item_number: int) -> None: """ Duplicate the Nth stack item (from top of the stack) to the top of stack. - Parameters - ---------- - evm : - The current EVM frame. - - item_number : - The stack item number (0-indexed from top of stack) to be duplicated - to the top of stack. + #### Parameters + - evm: The current EVM frame. + - item_number: The stack item number (0-indexed from top of stack) to be + duplicated to the top of stack. """ # STACK @@ -111,14 +95,10 @@ def swap_n(evm: Evm, item_number: int) -> None: If `item_number` is zero, this function does nothing (which should not be possible, since there is no `SWAP0` instruction). - Parameters - ---------- - evm : - The current EVM frame. - - item_number : - The stack item number (0-indexed from top of stack) to be swapped - with the top of stack element. + #### Parameters + - evm: The current EVM frame. + - item_number: The stack item number (0-indexed from top of stack) to be + swapped with the top of stack element. """ # STACK diff --git a/src/ethereum/arrow_glacier/vm/instructions/storage.py b/src/ethereum/arrow_glacier/vm/instructions/storage.py index 319162b381..2c271d7369 100644 --- a/src/ethereum/arrow_glacier/vm/instructions/storage.py +++ b/src/ethereum/arrow_glacier/vm/instructions/storage.py @@ -1,13 +1,7 @@ """ -Ethereum Virtual Machine (EVM) Storage Instructions -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +# Ethereum Virtual Machine (EVM) Storage Instructions -.. contents:: Table of Contents - :backlinks: none - :local: - -Introduction ------------- +## Introduction Implementations of the EVM storage related instructions. """ @@ -33,10 +27,8 @@ def sload(evm: Evm) -> None: Loads to the stack, the value corresponding to a certain key from the storage of the current account. - Parameters - ---------- - evm : - The current EVM frame. + #### Parameters + - evm: The current EVM frame. """ # STACK @@ -64,10 +56,8 @@ def sstore(evm: Evm) -> None: """ Stores a value at a certain key in the current context's storage. - Parameters - ---------- - evm : - The current EVM frame. + #### Parameters + - evm: The current EVM frame. """ # STACK diff --git a/src/ethereum/arrow_glacier/vm/instructions/system.py b/src/ethereum/arrow_glacier/vm/instructions/system.py index cec5eebd51..2f49d432ad 100644 --- a/src/ethereum/arrow_glacier/vm/instructions/system.py +++ b/src/ethereum/arrow_glacier/vm/instructions/system.py @@ -1,13 +1,7 @@ """ -Ethereum Virtual Machine (EVM) System Instructions -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +# Ethereum Virtual Machine (EVM) System Instructions -.. contents:: Table of Contents - :backlinks: none - :local: - -Introduction ------------- +## Introduction Implementations of the EVM system related instructions. """ @@ -141,10 +135,8 @@ def create(evm: Evm) -> None: """ Creates a new account with associated code. - Parameters - ---------- - evm : - The current EVM frame. + #### Parameters + - evm: The current EVM frame. """ # STACK endowment = pop(evm.stack) @@ -182,10 +174,8 @@ def create2(evm: Evm) -> None: It's similar to CREATE opcode except that the address of new account depends on the init_code instead of the nonce of sender. - Parameters - ---------- - evm : - The current EVM frame. + #### Parameters + - evm: The current EVM frame. """ # STACK endowment = pop(evm.stack) @@ -223,10 +213,8 @@ def return_(evm: Evm) -> None: """ Halts execution returning output data. - Parameters - ---------- - evm : - The current EVM frame. + #### Parameters + - evm: The current EVM frame. """ # STACK memory_start_position = pop(evm.stack) @@ -322,10 +310,8 @@ def call(evm: Evm) -> None: """ Message-call into an account. - Parameters - ---------- - evm : - The current EVM frame. + #### Parameters + - evm: The current EVM frame. """ # STACK gas = Uint(pop(evm.stack)) @@ -401,10 +387,8 @@ def callcode(evm: Evm) -> None: """ Message-call into this account with alternative account’s code. - Parameters - ---------- - evm : - The current EVM frame. + #### Parameters + - evm: The current EVM frame. """ # STACK gas = Uint(pop(evm.stack)) @@ -475,10 +459,8 @@ def selfdestruct(evm: Evm) -> None: """ Halt execution and register account for later deletion. - Parameters - ---------- - evm : - The current EVM frame. + #### Parameters + - evm: The current EVM frame. """ # STACK beneficiary = to_address(pop(evm.stack)) @@ -539,10 +521,8 @@ def delegatecall(evm: Evm) -> None: """ Message-call into an account. - Parameters - ---------- - evm : - The current EVM frame. + #### Parameters + - evm: The current EVM frame. """ # STACK gas = Uint(pop(evm.stack)) @@ -597,10 +577,8 @@ def staticcall(evm: Evm) -> None: """ Message-call into an account. - Parameters - ---------- - evm : - The current EVM frame. + #### Parameters + - evm: The current EVM frame. """ # STACK gas = Uint(pop(evm.stack)) @@ -661,10 +639,8 @@ def revert(evm: Evm) -> None: """ Stop execution and revert state changes, without consuming all provided gas and also has the ability to return a reason - Parameters - ---------- - evm : - The current EVM frame. + #### Parameters + - evm: The current EVM frame. """ # STACK memory_start_index = pop(evm.stack) diff --git a/src/ethereum/arrow_glacier/vm/interpreter.py b/src/ethereum/arrow_glacier/vm/interpreter.py index 6d823b468a..310f2e8651 100644 --- a/src/ethereum/arrow_glacier/vm/interpreter.py +++ b/src/ethereum/arrow_glacier/vm/interpreter.py @@ -1,13 +1,7 @@ """ -Ethereum Virtual Machine (EVM) Interpreter -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +# Ethereum Virtual Machine (EVM) Interpreter -.. contents:: Table of Contents - :backlinks: none - :local: - -Introduction ------------- +## Introduction A straightforward interpreter that executes EVM code. """ @@ -73,12 +67,12 @@ class MessageCallOutput: Contains the following: - 1. `gas_left`: remaining gas after execution. - 2. `refund_counter`: gas to refund after execution. - 3. `logs`: list of `Log` generated during execution. - 4. `accounts_to_delete`: Contracts which have self-destructed. - 5. `touched_accounts`: Accounts that have been touched. - 6. `error`: The error from the execution if any. + 1. `gas_left`: remaining gas after execution. + 2. `refund_counter`: gas to refund after execution. + 3. `logs`: list of `Log` generated during execution. + 4. `accounts_to_delete`: Contracts which have self-destructed. + 5. `touched_accounts`: Accounts that have been touched. + 6. `error`: The error from the execution if any. """ gas_left: Uint @@ -94,15 +88,12 @@ def process_message_call(message: Message) -> MessageCallOutput: If `message.current` is empty then it creates a smart contract else it executes a call from the `message.caller` to the `message.target`. - Parameters - ---------- - message : - Transaction specific items. + #### Parameters + - message: Transaction specific items. - Returns - ------- - output : `MessageCallOutput` - Output of the message call + #### Returns + - output: `MessageCallOutput` + Output of the message call """ block_env = message.block_env refund_counter = U256(0) @@ -152,15 +143,12 @@ def process_create_message(message: Message) -> Evm: """ Executes a call to create a smart contract. - Parameters - ---------- - message : - Transaction specific items. + #### Parameters + - message: Transaction specific items. - Returns - ------- - evm: :py:class:`~ethereum.arrow_glacier.vm.Evm` - Items containing execution specific objects. + #### Returns + - evm: :py:class:`~ethereum.arrow_glacier.vm.Evm` + Items containing execution specific objects. """ state = message.block_env.state # take snapshot of state before processing the message @@ -209,15 +197,12 @@ def process_message(message: Message) -> Evm: """ Move ether and execute the relevant code. - Parameters - ---------- - message : - Transaction specific items. + #### Parameters + - message: Transaction specific items. - Returns - ------- - evm: :py:class:`~ethereum.arrow_glacier.vm.Evm` - Items containing execution specific objects + #### Returns + - evm: :py:class:`~ethereum.arrow_glacier.vm.Evm` + Items containing execution specific objects """ state = message.block_env.state if message.depth > STACK_DEPTH_LIMIT: @@ -247,15 +232,12 @@ def execute_code(message: Message) -> Evm: """ Executes bytecode present in the `message`. - Parameters - ---------- - message : - Transaction specific items. + #### Parameters + - message: Transaction specific items. - Returns - ------- - evm: `ethereum.vm.EVM` - Items containing execution specific objects + #### Returns + - evm: `ethereum.vm.EVM` + Items containing execution specific objects """ code = message.code valid_jump_destinations = get_valid_jump_destinations(code) diff --git a/src/ethereum/arrow_glacier/vm/memory.py b/src/ethereum/arrow_glacier/vm/memory.py index aa2e7fdd57..0f1382308a 100644 --- a/src/ethereum/arrow_glacier/vm/memory.py +++ b/src/ethereum/arrow_glacier/vm/memory.py @@ -1,13 +1,7 @@ """ -Ethereum Virtual Machine (EVM) Memory -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +# Ethereum Virtual Machine (EVM) Memory -.. contents:: Table of Contents - :backlinks: none - :local: - -Introduction ------------- +## Introduction EVM memory operations. """ @@ -23,14 +17,10 @@ def memory_write( """ Writes to memory. - Parameters - ---------- - memory : - Memory contents of the EVM. - start_position : - Starting pointer to the memory. - value : - Data to write to memory. + #### Parameters + - memory: Memory contents of the EVM. + - start_position: Starting pointer to the memory. + - value: Data to write to memory. """ memory[start_position : int(start_position) + len(value)] = value @@ -41,19 +31,13 @@ def memory_read_bytes( """ Read bytes from memory. - Parameters - ---------- - memory : - Memory contents of the EVM. - start_position : - Starting pointer to the memory. - size : - Size of the data that needs to be read from `start_position`. + #### Parameters + - memory: Memory contents of the EVM. + - start_position: Starting pointer to the memory. + - size: Size of the data that needs to be read from `start_position`. - Returns - ------- - data_bytes : - Data read from memory. + #### Returns + - data_bytes: Data read from memory. """ return memory[start_position : Uint(start_position) + Uint(size)] @@ -62,19 +46,13 @@ def buffer_read(buffer: Bytes, start_position: U256, size: U256) -> Bytes: """ Read bytes from a buffer. Padding with zeros if necessary. - Parameters - ---------- - buffer : - Memory contents of the EVM. - start_position : - Starting pointer to the memory. - size : - Size of the data that needs to be read from `start_position`. + #### Parameters + - buffer: Memory contents of the EVM. + - start_position: Starting pointer to the memory. + - size: Size of the data that needs to be read from `start_position`. - Returns - ------- - data_bytes : - Data read from memory. + #### Returns + - data_bytes: Data read from memory. """ return right_pad_zero_bytes( buffer[start_position : Uint(start_position) + Uint(size)], size diff --git a/src/ethereum/arrow_glacier/vm/precompiled_contracts/__init__.py b/src/ethereum/arrow_glacier/vm/precompiled_contracts/__init__.py index b1d9c46465..290124cfd5 100644 --- a/src/ethereum/arrow_glacier/vm/precompiled_contracts/__init__.py +++ b/src/ethereum/arrow_glacier/vm/precompiled_contracts/__init__.py @@ -1,13 +1,7 @@ """ -Precompiled Contract Addresses -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +# Precompiled Contract Addresses -.. contents:: Table of Contents - :backlinks: none - :local: - -Introduction ------------- +## Introduction Addresses of precompiled contracts and mappings to their implementations. diff --git a/src/ethereum/arrow_glacier/vm/precompiled_contracts/alt_bn128.py b/src/ethereum/arrow_glacier/vm/precompiled_contracts/alt_bn128.py index 0c82ec5588..08a22390dd 100644 --- a/src/ethereum/arrow_glacier/vm/precompiled_contracts/alt_bn128.py +++ b/src/ethereum/arrow_glacier/vm/precompiled_contracts/alt_bn128.py @@ -1,13 +1,7 @@ """ -Ethereum Virtual Machine (EVM) ALT_BN128 CONTRACTS -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +# Ethereum Virtual Machine (EVM) ALT_BN128 CONTRACTS -.. contents:: Table of Contents - :backlinks: none - :local: - -Introduction ------------- +## Introduction Implementation of the ALT_BN128 precompiled contracts. """ @@ -40,20 +34,16 @@ def bytes_to_g1(data: Bytes) -> Point3D[FQ]: """ Decode 64 bytes to a point on the curve. - Parameters - ---------- - data : - The bytes data to decode. + #### Parameters + - data: The bytes data to decode. - Returns - ------- - point : Point3D - A point on the curve. + #### Returns + - point: Point3D + A point on the curve. - Raises - ------ - InvalidParameter - Either a field element is invalid or the point is not on the curve. + #### Raises + - InvalidParameter: Either a field element is invalid or the point is not + on the curve. """ if len(data) != 64: raise InvalidParameter("Input should be 64 bytes long") @@ -85,20 +75,16 @@ def bytes_to_g2(data: Bytes) -> Point3D[FQ2]: """ Decode 128 bytes to a G2 point. - Parameters - ---------- - data : - The bytes data to decode. + #### Parameters + - data: The bytes data to decode. - Returns - ------- - point : Point2D - A point on the curve. + #### Returns + - point: Point2D + A point on the curve. - Raises - ------ - InvalidParameter - Either a field element is invalid or the point is not on the curve. + #### Raises + - InvalidParameter: Either a field element is invalid or the point is not + on the curve. """ if len(data) != 128: raise InvalidParameter("G2 should be 128 bytes long") @@ -138,10 +124,8 @@ def alt_bn128_add(evm: Evm) -> None: """ The ALT_BN128 addition precompiled contract. - Parameters - ---------- - evm : - The current EVM frame. + #### Parameters + - evm: The current EVM frame. """ data = evm.message.data @@ -165,10 +149,8 @@ def alt_bn128_mul(evm: Evm) -> None: """ The ALT_BN128 multiplication precompiled contract. - Parameters - ---------- - evm : - The current EVM frame. + #### Parameters + - evm: The current EVM frame. """ data = evm.message.data @@ -192,10 +174,8 @@ def alt_bn128_pairing_check(evm: Evm) -> None: """ The ALT_BN128 pairing check precompiled contract. - Parameters - ---------- - evm : - The current EVM frame. + #### Parameters + - evm: The current EVM frame. """ data = evm.message.data diff --git a/src/ethereum/arrow_glacier/vm/precompiled_contracts/blake2f.py b/src/ethereum/arrow_glacier/vm/precompiled_contracts/blake2f.py index 0d86ba6e85..1afd11f493 100644 --- a/src/ethereum/arrow_glacier/vm/precompiled_contracts/blake2f.py +++ b/src/ethereum/arrow_glacier/vm/precompiled_contracts/blake2f.py @@ -1,13 +1,7 @@ """ -Ethereum Virtual Machine (EVM) Blake2 PRECOMPILED CONTRACT -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +# Ethereum Virtual Machine (EVM) Blake2 PRECOMPILED CONTRACT -.. contents:: Table of Contents - :backlinks: none - :local: - -Introduction ------------- +## Introduction Implementation of the `Blake2` precompiled contract. """ @@ -22,10 +16,8 @@ def blake2f(evm: Evm) -> None: """ Writes the Blake2 hash to output. - Parameters - ---------- - evm : - The current EVM frame. + #### Parameters + - evm: The current EVM frame. """ data = evm.message.data if len(data) != 213: diff --git a/src/ethereum/arrow_glacier/vm/precompiled_contracts/ecrecover.py b/src/ethereum/arrow_glacier/vm/precompiled_contracts/ecrecover.py index 1f047d3a44..117d544e6e 100644 --- a/src/ethereum/arrow_glacier/vm/precompiled_contracts/ecrecover.py +++ b/src/ethereum/arrow_glacier/vm/precompiled_contracts/ecrecover.py @@ -1,13 +1,7 @@ """ -Ethereum Virtual Machine (EVM) ECRECOVER PRECOMPILED CONTRACT -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +# Ethereum Virtual Machine (EVM) ECRECOVER PRECOMPILED CONTRACT -.. contents:: Table of Contents - :backlinks: none - :local: - -Introduction ------------- +## Introduction Implementation of the ECRECOVER precompiled contract. """ @@ -28,10 +22,8 @@ def ecrecover(evm: Evm) -> None: Decrypts the address using elliptic curve DSA recovery mechanism and writes the address to output. - Parameters - ---------- - evm : - The current EVM frame. + #### Parameters + - evm: The current EVM frame. """ data = evm.message.data diff --git a/src/ethereum/arrow_glacier/vm/precompiled_contracts/identity.py b/src/ethereum/arrow_glacier/vm/precompiled_contracts/identity.py index 88729c96d7..7fece520eb 100644 --- a/src/ethereum/arrow_glacier/vm/precompiled_contracts/identity.py +++ b/src/ethereum/arrow_glacier/vm/precompiled_contracts/identity.py @@ -1,13 +1,7 @@ """ -Ethereum Virtual Machine (EVM) IDENTITY PRECOMPILED CONTRACT -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +# Ethereum Virtual Machine (EVM) IDENTITY PRECOMPILED CONTRACT -.. contents:: Table of Contents - :backlinks: none - :local: - -Introduction ------------- +## Introduction Implementation of the `IDENTITY` precompiled contract. """ @@ -23,10 +17,8 @@ def identity(evm: Evm) -> None: """ Writes the message data to output. - Parameters - ---------- - evm : - The current EVM frame. + #### Parameters + - evm: The current EVM frame. """ data = evm.message.data diff --git a/src/ethereum/arrow_glacier/vm/precompiled_contracts/mapping.py b/src/ethereum/arrow_glacier/vm/precompiled_contracts/mapping.py index 561ea19287..670c7e79ea 100644 --- a/src/ethereum/arrow_glacier/vm/precompiled_contracts/mapping.py +++ b/src/ethereum/arrow_glacier/vm/precompiled_contracts/mapping.py @@ -1,13 +1,7 @@ """ -Precompiled Contract Addresses -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +# Precompiled Contract Addresses -.. contents:: Table of Contents - :backlinks: none - :local: - -Introduction ------------- +## Introduction Mapping of precompiled contracts their implementations. """ diff --git a/src/ethereum/arrow_glacier/vm/precompiled_contracts/modexp.py b/src/ethereum/arrow_glacier/vm/precompiled_contracts/modexp.py index 790d2fd66f..3ab28adfe6 100644 --- a/src/ethereum/arrow_glacier/vm/precompiled_contracts/modexp.py +++ b/src/ethereum/arrow_glacier/vm/precompiled_contracts/modexp.py @@ -1,13 +1,7 @@ """ -Ethereum Virtual Machine (EVM) MODEXP PRECOMPILED CONTRACT -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +# Ethereum Virtual Machine (EVM) MODEXP PRECOMPILED CONTRACT -.. contents:: Table of Contents - :backlinks: none - :local: - -Introduction ------------- +## Introduction Implementation of the `MODEXP` precompiled contract. """ @@ -69,20 +63,13 @@ def complexity(base_length: U256, modulus_length: U256) -> Uint: """ Estimate the complexity of performing a modular exponentiation. - Parameters - ---------- - - base_length : - Length of the array representing the base integer. - - modulus_length : - Length of the array representing the modulus integer. + #### Parameters + - base_length: Length of the array representing the base integer. + - modulus_length: Length of the array representing the modulus integer. - Returns - ------- - - complexity : `Uint` - Complexity of performing the operation. + #### Returns + - complexity: `Uint` + Complexity of performing the operation. """ max_length = max(Uint(base_length), Uint(modulus_length)) words = (max_length + Uint(7)) // Uint(8) @@ -94,21 +81,15 @@ def iterations(exponent_length: U256, exponent_head: U256) -> Uint: Calculate the number of iterations required to perform a modular exponentiation. - Parameters - ---------- - - exponent_length : - Length of the array representing the exponent integer. - - exponent_head : - First 32 bytes of the exponent (with leading zero padding if it is - shorter than 32 bytes), as a U256. + #### Parameters + - exponent_length: Length of the array representing the exponent integer. - Returns - ------- + - exponent_head: First 32 bytes of the exponent (with leading zero padding + if it is shorter than 32 bytes), as a U256. - iterations : `Uint` - Number of iterations. + #### Returns + - iterations: `Uint` + Number of iterations. """ if exponent_length <= U256(32) and exponent_head == U256(0): count = Uint(0) @@ -140,27 +121,16 @@ def gas_cost( """ Calculate the gas cost of performing a modular exponentiation. - Parameters - ---------- - - base_length : - Length of the array representing the base integer. - - modulus_length : - Length of the array representing the modulus integer. - - exponent_length : - Length of the array representing the exponent integer. - - exponent_head : - First 32 bytes of the exponent (with leading zero padding if it is - shorter than 32 bytes), as a U256. - - Returns - ------- + #### Parameters + - base_length: Length of the array representing the base integer. + - modulus_length: Length of the array representing the modulus integer. + - exponent_length: Length of the array representing the exponent integer. + - exponent_head: First 32 bytes of the exponent (with leading zero padding + if it is shorter than 32 bytes), as a U256. - gas_cost : `Uint` - Gas required for performing the operation. + #### Returns + - gas_cost: `Uint` + Gas required for performing the operation. """ multiplication_complexity = complexity(base_length, modulus_length) iteration_count = iterations(exponent_length, exponent_head) diff --git a/src/ethereum/arrow_glacier/vm/precompiled_contracts/ripemd160.py b/src/ethereum/arrow_glacier/vm/precompiled_contracts/ripemd160.py index 6af1086a82..d312d91535 100644 --- a/src/ethereum/arrow_glacier/vm/precompiled_contracts/ripemd160.py +++ b/src/ethereum/arrow_glacier/vm/precompiled_contracts/ripemd160.py @@ -1,13 +1,7 @@ """ -Ethereum Virtual Machine (EVM) RIPEMD160 PRECOMPILED CONTRACT -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +# Ethereum Virtual Machine (EVM) RIPEMD160 PRECOMPILED CONTRACT -.. contents:: Table of Contents - :backlinks: none - :local: - -Introduction ------------- +## Introduction Implementation of the `RIPEMD160` precompiled contract. """ @@ -26,10 +20,8 @@ def ripemd160(evm: Evm) -> None: """ Writes the ripemd160 hash to output. - Parameters - ---------- - evm : - The current EVM frame. + #### Parameters + - evm: The current EVM frame. """ data = evm.message.data diff --git a/src/ethereum/arrow_glacier/vm/precompiled_contracts/sha256.py b/src/ethereum/arrow_glacier/vm/precompiled_contracts/sha256.py index db33a37967..2792679430 100644 --- a/src/ethereum/arrow_glacier/vm/precompiled_contracts/sha256.py +++ b/src/ethereum/arrow_glacier/vm/precompiled_contracts/sha256.py @@ -1,13 +1,7 @@ """ -Ethereum Virtual Machine (EVM) SHA256 PRECOMPILED CONTRACT -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +# Ethereum Virtual Machine (EVM) SHA256 PRECOMPILED CONTRACT -.. contents:: Table of Contents - :backlinks: none - :local: - -Introduction ------------- +## Introduction Implementation of the `SHA256` precompiled contract. """ @@ -25,10 +19,8 @@ def sha256(evm: Evm) -> None: """ Writes the sha256 hash to output. - Parameters - ---------- - evm : - The current EVM frame. + #### Parameters + - evm: The current EVM frame. """ data = evm.message.data diff --git a/src/ethereum/arrow_glacier/vm/runtime.py b/src/ethereum/arrow_glacier/vm/runtime.py index acead2be90..05a328140f 100644 --- a/src/ethereum/arrow_glacier/vm/runtime.py +++ b/src/ethereum/arrow_glacier/vm/runtime.py @@ -1,13 +1,7 @@ """ -Ethereum Virtual Machine (EVM) Runtime Operations -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +# Ethereum Virtual Machine (EVM) Runtime Operations -.. contents:: Table of Contents - :backlinks: none - :local: - -Introduction ------------- +## Introduction Runtime related operations used while executing EVM code. """ @@ -24,22 +18,19 @@ def get_valid_jump_destinations(code: Bytes) -> Set[Uint]: Analyze the evm code to obtain the set of valid jump destinations. Valid jump destinations are defined as follows: - * The jump destination is less than the length of the code. - * The jump destination should have the `JUMPDEST` opcode (0x5B). - * The jump destination shouldn't be part of the data corresponding to - `PUSH-N` opcodes. + * The jump destination is less than the length of the code. + * The jump destination should have the `JUMPDEST` opcode (0x5B). + * The jump destination shouldn't be part of the data corresponding to + `PUSH-N` opcodes. Note - Jump destinations are 0-indexed. - Parameters - ---------- - code : - The EVM code which is to be executed. + #### Parameters + - code: The EVM code which is to be executed. - Returns - ------- - valid_jump_destinations: `Set[Uint]` - The set of valid jump destinations in the code. + #### Returns + - valid_jump_destinations: `Set[Uint]` + The set of valid jump destinations in the code. """ valid_jump_destinations = set() pc = Uint(0) diff --git a/src/ethereum/arrow_glacier/vm/stack.py b/src/ethereum/arrow_glacier/vm/stack.py index f28a5b3b88..e597cbbb8f 100644 --- a/src/ethereum/arrow_glacier/vm/stack.py +++ b/src/ethereum/arrow_glacier/vm/stack.py @@ -1,13 +1,7 @@ """ -Ethereum Virtual Machine (EVM) Stack -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +# Ethereum Virtual Machine (EVM) Stack -.. contents:: Table of Contents - :backlinks: none - :local: - -Introduction ------------- +## Introduction Implementation of the stack operators for the EVM. """ @@ -23,15 +17,12 @@ def pop(stack: List[U256]) -> U256: """ Pops the top item off of `stack`. - Parameters - ---------- - stack : - EVM stack. + #### Parameters + - stack: EVM stack. - Returns - ------- - value : `U256` - The top element on the stack. + #### Returns + - value: `U256` + The top element on the stack. """ if len(stack) == 0: @@ -44,13 +35,9 @@ def push(stack: List[U256], value: U256) -> None: """ Pushes `value` onto `stack`. - Parameters - ---------- - stack : - EVM stack. - - value : - Item to be pushed onto `stack`. + #### Parameters + - stack: EVM stack. + - value: Item to be pushed onto `stack`. """ if len(stack) == 1024: