ABC

Abstract base classes for documented interfaces

MiningHeaderAPI

class eth.abc.MiningHeaderAPI

A class to define a block header without mix_hash and nonce which can act as a temporary representation during mining before the block header is sealed.

abstract as_dict() → Dict[Hashable, Any]: Return a dictionary representation of the header.

abstract build_changeset(*args: Any, **kwargs: Any) → Any: Open a changeset to modify the header.

abstract property base_fee_per_gas: int | None

Return the base fee per gas of the block.

Set to None in pre-EIP-1559 (London) header.

block_number: BlockNumber

bloom: int

coinbase: Address

difficulty: int

extra_data: bytes

gas_limit: int

gas_used: int

abstract property hash: Hash32: Return the hash of the block header.

abstract property hex_hash: str: Return the hash as a hex string.

abstract property is_genesis: bool: Return True if this header represents the genesis block of the chain, otherwise False.

abstract property mining_hash: Hash32: Return the mining hash of the block header.

parent_hash: Hash32

receipt_root: Hash32

state_root: Hash32

timestamp: int

transaction_root: Hash32

uncles_hash: Hash32

abstract property withdrawals_root: Hash32 | None

Return the withdrawals root of the block.

Set to None in pre-Shanghai header.

BlockHeaderAPI

class eth.abc.BlockHeaderAPI

A class derived from MiningHeaderAPI to define a block header after it is sealed.

abstract copy(*args: Any, **kwargs: Any) → BlockHeaderAPI: Return a copy of the header, optionally overwriting any of its properties.

abstract property blob_gas_used: int: Return blob gas used.

abstract property excess_blob_gas: int: Return excess blob gas.

mix_hash: Hash32

nonce: bytes

abstract property parent_beacon_block_root: Hash32 | None: Return the hash of the parent beacon block.

LogAPI

class eth.abc.LogAPI

A class to define a written log.

address: Address

abstract property bloomables: Tuple[bytes, ...]

data: bytes

topics: Sequence[int]

ReceiptAPI

class eth.abc.ReceiptAPI

A class to define a receipt to capture the outcome of a transaction.

copy(*args: Any, **kwargs: Any) → ReceiptAPI: Return a copy of the receipt, optionally overwriting any of its properties.

abstract encode() → bytes: This encodes a receipt, no matter if it’s: a legacy receipt, a typed receipt, or the payload of a typed receipt. See more context in decode.

abstract property bloom: int

abstract property bloom_filter: BloomFilter

abstract property gas_used: int

abstract property logs: Sequence[LogAPI]

abstract property state_root: bytes

BaseTransactionAPI

class eth.abc.BaseTransactionAPI

A class to define all common methods of a transaction.

abstract copy(**overrides: Any) → T: Return a copy of the transaction.

abstract gas_used_by(computation: ComputationAPI) → int: Return the gas used by the given computation. In Frontier, for example, this is sum of the intrinsic cost and the gas used during computation.

abstract get_intrinsic_gas() → int: Return the intrinsic gas for the transaction which is defined as the amount of gas that is needed before any code runs.

abstract validate() → None: Hook called during instantiation to ensure that all transaction parameters pass validation rules.

abstract property access_list: Sequence[Tuple[Address, Sequence[int]]]: Get addresses to be accessed by a transaction, and their storage slots.

abstract property intrinsic_gas: int: Convenience property for the return value of get_intrinsic_gas

TransactionFieldsAPI

class eth.abc.TransactionFieldsAPI

A class to define all common transaction fields.

abstract property blob_versioned_hashes: Sequence[Hash32]

abstract property chain_id: int | None

abstract property data: bytes

abstract property gas: int

abstract property gas_price: int: Will raise AttributeError if get or set on a 1559 transaction.

abstract property hash: Hash32: Return the hash of the transaction.

abstract property max_fee_per_blob_gas: int

abstract property max_fee_per_gas: int: Will default to gas_price if this is a pre-1559 transaction.

abstract property max_priority_fee_per_gas: int: Will default to gas_price if this is a pre-1559 transaction.

abstract property nonce: int

abstract property r: int

abstract property s: int

abstract property to: Address

abstract property value: int

UnsignedTransactionAPI

class eth.abc.UnsignedTransactionAPI

A class representing a transaction before it is signed.

abstract as_signed_transaction(private_key: PrivateKey, chain_id: int | None = None) → SignedTransactionAPI: Return a version of this transaction which has been signed using the provided private_key

data: bytes

gas: int

gas_price: int

nonce: int

to: Address

value: int

SignedTransactionAPI

class eth.abc.SignedTransactionAPI(*args: Any, **kwargs: Any)

as_dict() → Dict[Hashable, Any]: Return a dictionary representation of the transaction.

abstract check_signature_validity() → None: Check if the signature is valid. Raise a ValidationError if the signature is invalid.

abstract encode() → bytes: This encodes a transaction, no matter if it’s: a legacy transaction, a typed transaction, or the payload of a typed transaction. See more context in decode.

abstract get_message_for_signing() → bytes: Return the bytestring that should be signed in order to create a signed transaction.

abstract get_sender() → Address

Get the 20-byte address which sent this transaction.

This can be a slow operation. transaction.sender is always preferred.

abstract make_receipt(status: bytes, gas_used: int, log_entries: Tuple[Tuple[bytes, Tuple[int, ...], bytes], ...]) → ReceiptAPI

Build a receipt for this transaction.

Transactions have this responsibility because there are different types of transactions, which have different types of receipts. (See access-list transactions, which change the receipt encoding)

Parameters:

status – success or failure (used to be the state root after execution)
gas_used – cumulative usage of this transaction and the previous ones in the header
log_entries – logs generated during execution

abstract validate() → None: Hook called during instantiation to ensure that all transaction parameters pass validation rules.

abstract property is_signature_valid: bool: Return True if the signature is valid, otherwise False.

abstract property sender: Address: Convenience and performance property for the return value of get_sender

type_id: int | None

The type of EIP-2718 transaction

Each EIP-2718 transaction includes a type id (which is the leading byte, as encoded).

If this transaction is a legacy transaction, that it has no type. Then, type_id will be None.

abstract property y_parity: int

The bit used to disambiguate elliptic curve signatures.

The only values this method will return are 0 or 1.

BlockAPI

class eth.abc.BlockAPI(header: BlockHeaderAPI, transactions: Sequence[SignedTransactionAPI], uncles: Sequence[BlockHeaderAPI], withdrawals: Sequence[WithdrawalAPI] | None = None)

A class to define a block.

copy(*args: Any, **kwargs: Any) → BlockAPI: Return a copy of the block, optionally overwriting any of its properties.

abstract classmethod from_header(header: BlockHeaderAPI, chaindb: ChainDatabaseAPI) → BlockAPI: Instantiate a block from the given header and the chaindb.

abstract classmethod get_receipt_builder() → Type[ReceiptBuilderAPI]: Return the receipt builder for the block.

abstract get_receipts(chaindb: ChainDatabaseAPI) → Tuple[ReceiptAPI, ...]: Fetch the receipts for this block from the given chaindb.

abstract classmethod get_transaction_builder() → Type[TransactionBuilderAPI]: Return the transaction builder for the block.

abstract property hash: Hash32: Return the hash of the block.

header: BlockHeaderAPI

abstract property is_genesis: bool: Return True if this block represents the genesis block of the chain, otherwise False.

abstract property number: BlockNumber: Return the number of the block.

receipt_builder: Type[ReceiptBuilderAPI] = None

transaction_builder: Type[TransactionBuilderAPI] = None

transactions: Tuple[SignedTransactionAPI, ...]

uncles: Tuple[BlockHeaderAPI, ...]

withdrawals: Tuple[WithdrawalAPI, ...]

DatabaseAPI

class eth.abc.DatabaseAPI(*args, **kwds)

A class representing a database.

abstract delete(key: bytes) → None: Delete the given key from the database.

abstract exists(key: bytes) → bool: Return True if the key exists in the database, otherwise False.

abstract set(key: bytes, value: bytes) → None: Assign the value to the key.

AtomicDatabaseAPI

class eth.abc.AtomicDatabaseAPI(*args, **kwds)

Like BatchDB, but immediately write out changes if they are not in an atomic_batch() context.

abstract atomic_batch() → AbstractContextManager[AtomicWriteBatchAPI]: Return a ContextManager to write an atomic batch to the database.

HeaderDatabaseAPI

class eth.abc.HeaderDatabaseAPI(db: AtomicDatabaseAPI)

A class representing a database for block headers.

abstract get_block_header_by_hash(block_hash: Hash32) → BlockHeaderAPI: Return the block header for the given block_hash. Raise HeaderNotFound if no header with the given block_hash exists in the database.

abstract get_canonical_block_hash(block_number: BlockNumber) → Hash32

Return the block hash for the canonical block at the given number.

Raise BlockNotFound if there’s no block header with the given number in the canonical chain.

abstract get_canonical_block_header_by_number(block_number: BlockNumber) → BlockHeaderAPI

Return the block header with the given number in the canonical chain.

Raise HeaderNotFound if there’s no block header with the given number in the canonical chain.

abstract get_canonical_head() → BlockHeaderAPI: Return the current block header at the head of the chain.

abstract get_header_chain_gaps() → Tuple[Tuple[Tuple[BlockNumber, BlockNumber], ...], BlockNumber]

Return information about gaps in the chain of headers. This consists of an ordered sequence of block ranges describing the integrity of the chain. Each block range describes a missing segment in the chain and each range is defined with inclusive boundaries, meaning the first value describes the first missing block of that segment and the second value describes the last missing block of the segment.

In addition to the sequences of block ranges a block number is included that indicates the number of the first header that is known to be missing at the very tip of the chain.

abstract get_score(block_hash: Hash32) → int: Return the score for the given block_hash.

abstract header_exists(block_hash: Hash32) → bool: Return True if the block_hash exists in the database, otherwise False.

abstract persist_checkpoint_header(header: BlockHeaderAPI, score: int) → None: Persist a checkpoint header with a trusted score. Persisting the checkpoint header automatically sets it as the new canonical head.

abstract persist_header(header: BlockHeaderAPI) → Tuple[Tuple[BlockHeaderAPI, ...], Tuple[BlockHeaderAPI, ...]]: Persist the header in the database. Return two iterable of headers, the first containing the new canonical header, the second containing the old canonical headers

abstract persist_header_chain(headers: Sequence[BlockHeaderAPI], genesis_parent_hash: Hash32 | None = None) → Tuple[Tuple[BlockHeaderAPI, ...], Tuple[BlockHeaderAPI, ...]]

Persist a chain of headers in the database. Return two iterable of headers, the first containing the new canonical headers, the second containing the old canonical headers

Parameters:: genesis_parent_hash – optional parent hash of the block that is treated as genesis. Providing a genesis_parent_hash allows storage of headers that aren’t (yet) connected back to the true genesis header.

db: AtomicDatabaseAPI

ChainDatabaseAPI

class eth.abc.ChainDatabaseAPI(db: AtomicDatabaseAPI)

A class representing a database for chain data. This class is derived from HeaderDatabaseAPI.

abstract add_receipt(block_header: BlockHeaderAPI, index_key: int, receipt: ReceiptAPI) → Hash32

Add the given receipt to the provided block header.

Return the updated receipts_root for updated block header.

abstract add_transaction(block_header: BlockHeaderAPI, index_key: int, transaction: SignedTransactionAPI) → Hash32

Add the given transaction to the provided block header.

Return the updated transactions_root for updated block header.

abstract exists(key: bytes) → bool: Return True if the given key exists in the database.

abstract get(key: bytes) → bytes: Return the value for the given key or a KeyError if it doesn’t exist in the database.

abstract get_block_transaction_hashes(block_header: BlockHeaderAPI) → Tuple[Hash32, ...]: Return a tuple cointaining the hashes of the transactions of the given block_header.

abstract get_block_transactions(block_header: BlockHeaderAPI, transaction_decoder: Type[TransactionDecoderAPI]) → Tuple[SignedTransactionAPI, ...]: Return an iterable of transactions for the block speficied by the given block header.

abstract get_block_uncles(uncles_hash: Hash32) → Tuple[BlockHeaderAPI, ...]: Return an iterable of uncle headers specified by the given uncles_hash

abstract get_block_withdrawals(block_header: BlockHeaderAPI) → Tuple[WithdrawalAPI, ...]: Return an iterable of withdrawals for the block specified by the given block header.

abstract get_receipt_by_index(block_number: BlockNumber, receipt_index: int, receipt_decoder: Type[ReceiptDecoderAPI]) → ReceiptAPI: Return the receipt of the transaction at specified index for the block header obtained by the specified block number

abstract get_receipts(header: BlockHeaderAPI, receipt_decoder: Type[ReceiptDecoderAPI]) → Tuple[ReceiptAPI, ...]: Return a tuple of receipts for the block specified by the given block header.

abstract get_transaction_by_index(block_number: BlockNumber, transaction_index: int, transaction_decoder: Type[TransactionDecoderAPI]) → SignedTransactionAPI

Return the transaction at the specified transaction_index from the block specified by block_number from the canonical chain.

Raise TransactionNotFound if no block with that block_number exists.

abstract get_transaction_index(transaction_hash: Hash32) → Tuple[BlockNumber, int]

Return a 2-tuple of (block_number, transaction_index) indicating which block the given transaction can be found in and at what index in the block transactions.

Raise TransactionNotFound if the transaction_hash is not found in the canonical chain.

abstract persist_block(block: BlockAPI, genesis_parent_hash: Hash32 | None = None) → Tuple[Tuple[Hash32, ...], Tuple[Hash32, ...]]

Persist the given block’s header and uncles.

Parameters:

block – the block that gets persisted
genesis_parent_hash – optional parent hash of the header that is treated as genesis. Providing a genesis_parent_hash allows storage of blocks that aren’t (yet) connected back to the true genesis header.

Warning

This API assumes all block transactions have been persisted already. Use eth.abc.ChainDatabaseAPI.persist_unexecuted_block() to persist blocks that were not executed.

abstract persist_trie_data_dict(trie_data_dict: Dict[Hash32, bytes]) → None: Store raw trie data to db from a dict

abstract persist_uncles(uncles: Tuple[BlockHeaderAPI]) → Hash32

Persist the list of uncles to the database.

Return the uncles hash.

abstract persist_unexecuted_block(block: BlockAPI, receipts: Tuple[ReceiptAPI, ...], genesis_parent_hash: Hash32 | None = None) → Tuple[Tuple[Hash32, ...], Tuple[Hash32, ...]]

Persist the given block’s header, uncles, transactions, and receipts. Does not validate if state transitions are valid.

Parameters:

block – the block that gets persisted
receipts – the receipts for the given block
genesis_parent_hash – optional parent hash of the header that is treated as genesis. Providing a genesis_parent_hash allows storage of blocks that aren’t (yet) connected back to the true genesis header.

This API should be used to persist blocks that the EVM does not execute but which it stores to make them available. It ensures to persist receipts and transactions which eth.abc.ChainDatabaseAPI.persist_block() in contrast assumes to be persisted separately.

db: AtomicDatabaseAPI

GasMeterAPI

class eth.abc.GasMeterAPI

A class to define a gas meter.

abstract consume_gas(amount: int, reason: str) → None: Consume amount of gas for a defined reason.

abstract refund_gas(amount: int) → None: Refund amount of gas.

abstract return_gas(amount: int) → None: Return amount of gas.

gas_refunded: int

gas_remaining: int

start_gas: int

MessageAPI

class eth.abc.MessageAPI

A message for VM computation.

code: bytes

abstract property code_address: Address

create_address: Address

data: bytes | memoryview

abstract property data_as_bytes: bytes

depth: int

gas: int

abstract property is_create: bool

is_static: bool

sender: Address

should_transfer_value: bool

abstract property storage_address: Address

to: Address

value: int

OpcodeAPI

class eth.abc.OpcodeAPI

A class representing an opcode.

abstract classmethod as_opcode(logic_fn: Callable[[ComputationAPI], None], mnemonic: str, gas_cost: int) → OpcodeAPI: Class factory method for turning vanilla functions into Opcodes.

mnemonic: str

TransactionContextAPI

class eth.abc.TransactionContextAPI(gas_price: int, origin: Address)

Immutable transaction context information that remains constant over the VM execution.

abstract get_next_log_counter() → int: Increment and return the log counter.

abstract property blob_versioned_hashes: Sequence[Hash32]: Return the blob versioned hashes of the transaction context.

abstract property gas_price: int: Return the gas price of the transaction context.

abstract property origin: Address: Return the origin of the transaction context.

MemoryAPI

class eth.abc.MemoryAPI

A class representing the memory of the VirtualMachineAPI.

abstract copy(destination: int, source: int, length: int) → bytes: Copy bytes of memory with size length from source to destination

abstract extend(start_position: int, size: int) → None: Extend the memory from the given start_position to the provided size.

abstract read(start_position: int, size: int) → memoryview: Return a view into the memory

abstract read_bytes(start_position: int, size: int) → bytes: Read a value from memory and return a fresh bytes instance

abstract write(start_position: int, size: int, value: bytes) → None: Write value into memory.

StackAPI

class eth.abc.StackAPI

A class representing the stack of the VirtualMachineAPI.

abstract dup(position: int) → None: Perform a DUP operation on the stack.

abstract pop1_any() → int | bytes

Pop and return an element from the stack. The type of each element will be int or bytes, depending on whether it was pushed with push_bytes or push_int.

Raise eth.exceptions.InsufficientStack if the stack was empty.

abstract pop1_bytes() → bytes

Pop and return a bytes element from the stack.

Raise eth.exceptions.InsufficientStack if the stack was empty.

abstract pop1_int() → int

Pop and return an integer from the stack.

Raise eth.exceptions.InsufficientStack if the stack was empty.

abstract pop_any(num_items: int) → Tuple[int | bytes, ...]

Pop and return a tuple of items of length num_items from the stack. The type of each element will be int or bytes, depending on whether it was pushed with stack_push_bytes or stack_push_int.

Raise eth.exceptions.InsufficientStack if there are not enough items on the stack.

Items are ordered with the top of the stack as the first item in the tuple.

abstract pop_bytes(num_items: int) → Tuple[bytes, ...]

Pop and return a tuple of bytes of length num_items from the stack.

Raise eth.exceptions.InsufficientStack if there are not enough items on the stack.

Items are ordered with the top of the stack as the first item in the tuple.

abstract pop_ints(num_items: int) → Tuple[int, ...]

Pop and return a tuple of integers of length num_items from the stack.

Raise eth.exceptions.InsufficientStack if there are not enough items on the stack.

Items are ordered with the top of the stack as the first item in the tuple.

abstract push_bytes(value: bytes) → None: Push a bytes item onto the stack.

abstract push_int(value: int) → None: Push an integer item onto the stack.

abstract swap(position: int) → None: Perform a SWAP operation on the stack.

CodeStreamAPI

class eth.abc.CodeStreamAPI

A class representing a stream of EVM code.

abstract is_valid_opcode(position: int) → bool: Return True if a valid opcode exists at position.

abstract peek() → int: Return the ordinal value of the byte at the current program counter.

abstract read(size: int) → bytes: Read and return the code from the current position of the cursor up to size.

abstract seek(program_counter: int) → AbstractContextManager[CodeStreamAPI]: Return a ContextManager with the program counter set to program_counter.

program_counter: int

StackManipulationAPI

class eth.abc.StackManipulationAPI

abstract stack_pop1_any() → int | bytes: Pop one item from the stack and return the value either as byte or the ordinal value of a byte.

abstract stack_pop1_bytes() → bytes: Pop one item from the stack and return the value as bytes.

abstract stack_pop1_int() → int: Pop one item from the stack and return the ordinal value of the represented bytes.

abstract stack_pop_any(num_items: int) → Tuple[int | bytes, ...]: Pop the last num_items from the stack, returning a tuple with potentially mixed values of bytes or ordinal values of bytes.

abstract stack_pop_bytes(num_items: int) → Tuple[bytes, ...]: Pop the last num_items from the stack, returning a tuple of bytes.

abstract stack_pop_ints(num_items: int) → Tuple[int, ...]: Pop the last num_items from the stack, returning a tuple of their ordinal values.

abstract stack_push_bytes(value: bytes) → None: Push value on the stack which must be a 32 byte string.

abstract stack_push_int(value: int) → None: Push value on the stack which must be a 256 bit integer.

ExecutionContextAPI

class eth.abc.ExecutionContextAPI

A class representing context information that remains constant over the execution of a block.

abstract property base_fee_per_gas: int | None: Return the base fee per gas of the block

abstract property block_number: BlockNumber: Return the number of the block.

abstract property chain_id: int: Return the id of the chain.

abstract property coinbase: Address: Return the coinbase address of the block.

abstract property difficulty: int: Return the difficulty of the block.

abstract property excess_blob_gas: int | None: Return the excess blob gas of the block

abstract property gas_limit: int: Return the gas limit of the block.

abstract property mix_hash: Hash32: Return the mix hash of the block

abstract property prev_hashes: Iterable[Hash32]: Return an iterable of block hashes that precede the block.

abstract property timestamp: int: Return the timestamp of the block.

ComputationAPI

class eth.abc.ComputationAPI(state: StateAPI, message: MessageAPI, transaction_context: TransactionContextAPI)

The base abstract class for all execution computations.

abstract add_child_computation(child_computation: ComputationAPI) → None: Add the given child_computation.

abstract add_log_entry(account: Address, topics: Tuple[int, ...], data: bytes) → None: Add a log entry.

abstract apply_child_computation(child_msg: MessageAPI) → ComputationAPI: Apply the vm message child_msg as a child computation.

abstract classmethod apply_computation(state: StateAPI, message: MessageAPI, transaction_context: TransactionContextAPI) → ComputationAPI

Execute the logic within the message: Either run the precompile, or step through each opcode. Generally, the only VM-specific logic is for each opcode as it executes.

This should rarely be called directly, because it will skip over other important VM-specific logic that happens before or after the execution.

Instead, prefer apply_message() or apply_create_message().

abstract classmethod apply_create_message(state: StateAPI, message: MessageAPI, transaction_context: TransactionContextAPI, parent_computation: ComputationAPI | None = None) → ComputationAPI: Execute a VM message to create a new contract. This is where the VM-specific create logic exists.

abstract classmethod apply_message(state: StateAPI, message: MessageAPI, transaction_context: TransactionContextAPI, parent_computation: ComputationAPI | None = None) → ComputationAPI: Execute a VM message. This is where the VM-specific call logic exists.

abstract consume_gas(amount: int, reason: str) → None: Consume amount of gas from the remaining gas. Raise eth.exceptions.OutOfGas if there is not enough gas remaining.

abstract extend_memory(start_position: int, size: int) → None: Extend the size of the memory to be at minimum start_position + size bytes in length. Raise eth.exceptions.OutOfGas if there is not enough gas to pay for extending the memory.

abstract generate_child_computation(child_msg: MessageAPI) → ComputationAPI: Generate a child computation from the given child_msg.

abstract get_accounts_for_deletion() → List[Address]: Return a tuple of addresses that are registered for deletion.

abstract get_gas_meter() → GasMeterAPI: Return the gas meter for the computation.

abstract get_gas_refund() → int: Return the number of refunded gas.

abstract get_gas_remaining() → int: Return the number of remaining gas.

abstract get_gas_used() → int: Return the number of used gas.

abstract get_log_entries() → Tuple[Tuple[bytes, Tuple[int, ...], bytes], ...]

Return the log entries for this computation and its children.

They are sorted in the same order they were emitted during the transaction processing, and include the sequential counter as the first element of the tuple representing every entry.

abstract get_opcode_fn(opcode: int) → OpcodeAPI: Return the function for the given opcode.

abstract classmethod get_precompiles() → Dict[Address, Callable[[ComputationAPI], None]]: Return a dictionary where the keys are the addresses of precompiles and the values are the precompile functions.

abstract get_raw_log_entries() → Tuple[Tuple[int, bytes, Tuple[int, ...], bytes], ...]: Return a tuple of raw log entries.

abstract get_self_destruct_beneficiaries() → List[Address]: Return a list of addresses that were beneficiaries of the self-destruct opcode - whether or not the contract was self-destructed, post-Cancun.

abstract memory_copy(destination: int, source: int, length: int) → bytes: Copy bytes of memory with size length from source to destination

abstract memory_read_bytes(start_position: int, size: int) → bytes: Read and return size bytes from memory starting at start_position.

abstract memory_write(start_position: int, size: int, value: bytes) → None: Write value to memory at start_position. Require that len(value) == size.

abstract prepare_child_message(gas: int, to: Address, value: int, data: bytes | memoryview, code: bytes, **kwargs: Any) → MessageAPI: Helper method for creating a child computation.

abstract raise_if_error() → None

If there was an error during computation, raise it as an exception immediately.

Raises:: VMError –

abstract refund_gas(amount: int) → None: Add amount of gas to the pool of gas marked to be refunded.

abstract register_account_for_deletion(beneficiary: Address) → None: Register the address of beneficiary for deletion.

abstract return_gas(amount: int) → None: Return amount of gas to the available gas pool.

abstract stack_dup(position: int) → None: Duplicate the stack item at position and pushes it onto the stack.

abstract stack_swap(position: int) → None: Swap the item on the top of the stack with the item at position.

accounts_to_delete: List[Address]

beneficiaries: List[Address]

children: List[ComputationAPI]

code: CodeStreamAPI

contracts_created: List[Address] = []

abstract property error: VMError: Return the VMError of the computation. Raise AttributeError if no error exists.

abstract property is_error: bool: Return True if the computation resulted in an error.

abstract property is_origin_computation: bool: Return True if this computation is the outermost computation at depth == 0.

abstract property is_success: bool: Return True if the computation did not result in an error.

logger: ExtendedDebugLogger

msg: MessageAPI

opcodes: Dict[int, OpcodeAPI]

abstract property output: bytes: Get the return value of the computation.

abstract property precompiles: Dict[Address, Callable[[ComputationAPI], None]]: Return a dictionary where the keys are the addresses of precompiles and the values are the precompile functions.

return_data: bytes = b''

abstract property should_burn_gas: bool: Return True if the remaining gas should be burned.

abstract property should_erase_return_data: bool: Return True if the return data should be zerod out due to an error.

abstract property should_return_gas: bool: Return True if the remaining gas should be returned.

state: StateAPI

transaction_context: TransactionContextAPI

AccountStorageDatabaseAPI

class eth.abc.AccountStorageDatabaseAPI

Storage cache and write batch for a single account. Changes are not merklized until make_storage_root() is called.

abstract commit(checkpoint: JournalDBCheckpoint) → None: Collapse changes into the given checkpoint.

abstract delete() → None: Delete the entire storage at the account.

abstract discard(checkpoint: JournalDBCheckpoint) → None: Discard the given checkpoint.

abstract get(slot: int, from_journal: bool = True) → int: Return the value at slot. Lookups take the journal into consideration unless from_journal is explicitly set to False.

abstract get_accessed_slots() → FrozenSet[int]: List all the slots that had been accessed since object creation.

abstract get_changed_root() → Hash32: Return the changed root hash. Raise ValidationError if the root has not changed.

abstract lock_changes() → None

Locks in changes to storage, typically just as a transaction starts.

This is used, for example, to look up the storage value from the start of the transaction, when calculating gas costs in EIP-2200: net gas metering.

abstract make_storage_root() → None: Force calculation of the storage root for this account

abstract persist(db: DatabaseAPI) → None: Persist all changes to the database.

abstract record(checkpoint: JournalDBCheckpoint) → None: Record changes into the given checkpoint.

abstract set(slot: int, value: int) → None: Write value into slot.

abstract property has_changed_root: bool: Return True if the storage root has changed.

AccountDatabaseAPI

class eth.abc.AccountDatabaseAPI(db: AtomicDatabaseAPI, state_root: Hash32 = b'V\xe8\x1f\x17\x1b\xccU\xa6\xff\x83E\xe6\x92\xc0\xf8n[H\xe0\x1b\x99l\xad\xc0\x01b/\xb5\xe3c\xb4!')

A class representing a database for accounts.

abstract account_exists(address: Address) → bool: Return True if an account exists at address, otherwise False.

abstract account_has_code_or_nonce(address: Address) → bool: Return True if either code or a nonce exists at address.

abstract account_is_empty(address: Address) → bool: Return True if an account exists at address.

abstract commit(checkpoint: JournalDBCheckpoint) → None: Collapse changes into checkpoint.

abstract delete_account(address: Address) → None: Delete the account at address.

abstract delete_code(address: Address) → None: Delete the code at address.

abstract delete_storage(address: Address) → None: Delete the storage at address.

abstract discard(checkpoint: JournalDBCheckpoint) → None: Discard the given checkpoint.

abstract get_balance(address: Address) → int: Return the balance at address.

abstract get_code(address: Address) → bytes: Return the code at the given address.

abstract get_code_hash(address: Address) → Hash32: Return the hash of the code at address.

abstract get_nonce(address: Address) → int: Return the nonce for address.

abstract get_storage(address: Address, slot: int, from_journal: bool = True) → int: Return the value stored at slot for the given address. Take the journal into consideration unless from_journal is set to False.

abstract has_root(state_root: bytes) → bool: Return True if the state_root exists, otherwise False.

abstract increment_nonce(address: Address) → None: Increment the nonce for address.

abstract is_address_warm(address: Address) → bool

Was the account accessed during this transaction?

See EIP-2929

abstract is_storage_warm(address: Address, slot: int) → bool

Was the storage slot accessed during this transaction?

See EIP-2929

abstract lock_changes() → None

Locks in changes across all accounts’ storage databases.

This is typically used at the end of a transaction, to make sure that a revert doesn’t roll back through the previous transaction, and to be able to look up the “original” value of any account storage, where “original” is the beginning of a transaction (instead of the beginning of a block).

See eth.abc.AccountStorageDatabaseAPI.lock_changes() for what is called on each account’s storage database.

abstract make_state_root() → Hash32

Generate the state root with all the current changes in AccountDB

Current changes include every pending change to storage, as well as all account changes. After generating all the required tries, the final account state root is returned.

This is an expensive operation, so should be called as little as possible. For example, pre-Byzantium, this is called after every transaction, because we need the state root in each receipt. Byzantium+, we only need state roots at the end of the block, so we only call it right before persistence.

Returns:: the new state root

abstract mark_address_warm(address: Address) → None

Mark the account as accessed during this transaction.

See EIP-2929

abstract mark_storage_warm(address: Address, slot: int) → None

Mark the storage slot as accessed during this transaction.

See EIP-2929

abstract persist() → MetaWitnessAPI

Send changes to underlying database, including the trie state so that it will forever be possible to read the trie from this checkpoint.

make_state_root() must be explicitly called before this method. Otherwise persist will raise a ValidationError.

abstract record() → JournalDBCheckpoint: Create and return a new checkpoint.

abstract set_balance(address: Address, balance: int) → None: Set balance as the new balance for address.

abstract set_code(address: Address, code: bytes) → None: Set code as the new code at address.

abstract set_nonce(address: Address, nonce: int) → None: Set nonce as the new nonce for address.

abstract set_storage(address: Address, slot: int, value: int) → None: Write value into slot for the given address.

abstract touch_account(address: Address) → None: Touch the account at address.

abstract property state_root: Hash32: Return the state root hash.

TransactionExecutorAPI

class eth.abc.TransactionExecutorAPI(vm_state: StateAPI)

A class providing APIs to execute transactions on VM state.

abstract build_computation(message: MessageAPI, transaction: SignedTransactionAPI) → ComputationAPI: Apply the message to the VM and use the given transaction to retrieve the context from.

abstract build_evm_message(transaction: SignedTransactionAPI) → MessageAPI: Build and return a MessageAPI from the given transaction.

abstract calc_data_fee(transaction: BlobTransaction) → int: For Cancun and later, calculate the data fee for a transaction.

abstract finalize_computation(transaction: SignedTransactionAPI, computation: ComputationAPI) → ComputationAPI: Finalize the transaction.

abstract validate_transaction(transaction: SignedTransactionAPI) → None: Validate the given transaction. Raise a ValidationError if the transaction is invalid.

ConfigurableAPI

class eth.abc.ConfigurableAPI

A class providing inline subclassing.

abstract classmethod configure(__name__: str | None = None, **overrides: Any) → Type[T]

StateAPI

class eth.abc.StateAPI(db: AtomicDatabaseAPI, execution_context: ExecutionContextAPI, state_root: bytes)

The base class that encapsulates all of the various moving parts related to the state of the VM during execution. Each VirtualMachineAPI must be configured with a subclass of the StateAPI.

Note

Each StateAPI class must be configured with:

computation_class: The ComputationAPI class for vm execution.

transaction_context_class: The TransactionContextAPI class for vm execution.

abstract account_exists(address: Address) → bool: Return True if an account exists at address.

abstract account_is_empty(address: Address) → bool: Return True if the account at address is empty, otherwise False.

apply_all_withdrawals(withdrawals: Sequence[WithdrawalAPI]) → None

abstract apply_transaction(transaction: SignedTransactionAPI) → ComputationAPI

Apply transaction to the vm state

Parameters:: transaction – the transaction to apply
Returns:: the computation

apply_withdrawal(withdrawal: WithdrawalAPI) → None

abstract clear_transient_storage() → None: Clear the transient storage. Should be done at the start of every transaction

abstract commit(snapshot: Tuple[Hash32, JournalDBCheckpoint]) → None: Commit the journal to the point where the snapshot was taken. This merges in any changes that were recorded since the snapshot.

abstract costless_execute_transaction(transaction: SignedTransactionAPI) → ComputationAPI: Execute the given transaction with a gas price of 0.

abstract delete_account(address: Address) → None: Delete the account at the given address.

abstract delete_code(address: Address) → None: Delete the code at address.

abstract delete_storage(address: Address) → None: Delete the storage at address

abstract delta_balance(address: Address, delta: int) → None: Apply delta to the balance at address.

abstract classmethod get_account_db_class() → Type[AccountDatabaseAPI]: Return the AccountDatabaseAPI class that the state class uses.

abstract get_ancestor_hash(block_number: BlockNumber) → Hash32: Return the hash for the ancestor block with number block_number. Return the empty bytestring b'' if the block number is outside of the range of available block numbers (typically the last 255 blocks).

abstract get_balance(address: Address) → int: Return the balance for the account at address.

abstract get_code(address: Address) → bytes: Return the code at address.

abstract get_code_hash(address: Address) → Hash32: Return the hash of the code at address.

abstract get_computation(message: MessageAPI, transaction_context: TransactionContextAPI) → ComputationAPI: Return a computation instance for the given message and transaction_context

abstract get_gas_price(transaction: SignedTransactionAPI) → int

Return the gas price of the given transaction.

Factor in the current block’s base gas price, if appropriate. (See EIP-1559)

abstract get_nonce(address: Address) → int: Return the nonce at address.

abstract get_storage(address: Address, slot: int, from_journal: bool = True) → int: Return the storage at slot for address.

abstract get_tip(transaction: SignedTransactionAPI) → int

Return the gas price that gets allocated to the miner/validator.

Pre-EIP-1559 that would be the full transaction gas price. After, it would be the tip price (potentially reduced, if the base fee is so high that it surpasses the transaction’s maximum gas price after adding the tip).

abstract get_transaction_context(transaction: SignedTransactionAPI) → TransactionContextAPI: Return the TransactionContextAPI for the given transaction

abstract classmethod get_transaction_context_class() → Type[TransactionContextAPI]: Return the BaseTransactionContext class that the state class uses.

abstract get_transaction_executor() → TransactionExecutorAPI: Return the transaction executor.

abstract get_transient_storage(address: Address, slot: int) → bytes: Return the transient storage for address at slot slot.

abstract has_code_or_nonce(address: Address) → bool: Return True if either a nonce or code exists at the given address.

abstract increment_nonce(address: Address) → None: Increment the nonce at address.

abstract is_address_warm(address: Address) → bool

Was the account accessed during this transaction?

See EIP-2929

abstract is_storage_warm(address: Address, slot: int) → bool

Was the storage slot accessed during this transaction?

See EIP-2929

abstract lock_changes() → None

Locks in all changes to state, typically just as a transaction starts.

This is used, for example, to look up the storage value from the start of the transaction, when calculating gas costs in EIP-2200: net gas metering.

abstract make_state_root() → Hash32: Create and return the state root.

abstract mark_address_warm(address: Address) → None

Mark the account as accessed during this transaction.

See EIP-2929

abstract mark_storage_warm(address: Address, slot: int) → None

Mark the storage slot as accessed during this transaction.

See EIP-2929

abstract override_transaction_context(gas_price: int) → AbstractContextManager[None]: Return a ContextManager that overwrites the current transaction context, applying the given gas_price.

abstract persist() → MetaWitnessAPI: Persist the current state to the database.

abstract revert(snapshot: Tuple[Hash32, JournalDBCheckpoint]) → None: Revert the VM to the state at the snapshot

abstract set_balance(address: Address, balance: int) → None: Set balance to the balance at address.

abstract set_code(address: Address, code: bytes) → None: Set code as the new code at address.

abstract set_nonce(address: Address, nonce: int) → None: Set nonce as the new nonce at address.

abstract set_storage(address: Address, slot: int, value: int) → None: Write value to the given slot at address.

abstract set_transient_storage(address: Address, slot: int, value: bytes) → None: Return the transient storage for address at slot slot.

abstract snapshot() → Tuple[Hash32, JournalDBCheckpoint]

Perform a full snapshot of the current state.

Snapshots are a combination of the state_root at the time of the snapshot and the checkpoint from the journaled DB.

abstract touch_account(address: Address) → None: Touch the account at the given address.

abstract validate_transaction(transaction: SignedTransactionAPI) → None: Validate the given transaction.

account_db_class: Type[AccountDatabaseAPI]

abstract property base_fee: int

Return the current base_fee from the current execution_context

Raises a NotImplementedError if called in an execution context prior to the London hard fork.

abstract property blob_base_fee: int

Return the current blob_base_fee from the current execution_context

Raises a NotImplementedError if called in an execution context prior to the Cancun hard fork.

abstract property block_number: BlockNumber: Return the current block_number from the current execution_context

abstract property coinbase: Address: Return the current coinbase from the current execution_context

computation_class: Type[ComputationAPI]

abstract property difficulty: int: Return the current difficulty from the current execution_context

execution_context: ExecutionContextAPI

abstract property gas_limit: int: Return the current gas_limit from the current transaction_context

abstract property logger: ExtendedDebugLogger: Return the logger.

abstract property mix_hash: Hash32: Return the current mix_hash from the current execution_context

abstract property state_root: Hash32: Return the current state_root from the underlying database

abstract property timestamp: int: Return the current timestamp from the current execution_context

transaction_context_class: Type[TransactionContextAPI]

transaction_executor_class: Type[TransactionExecutorAPI] = None

VirtualMachineAPI

class eth.abc.VirtualMachineAPI(header: BlockHeaderAPI, chaindb: ChainDatabaseAPI, chain_context: ChainContextAPI, consensus_context: ConsensusContextAPI)

The VirtualMachineAPI class represents the Chain rules for a specific protocol definition such as the Frontier or Homestead network.

Note

Each VirtualMachineAPI class must be configured with:

block_class: The BlockAPI class for blocks in this
VM ruleset.

_state_class: The StateAPI class used by this
VM for execution.

abstract add_receipt_to_header(old_header: BlockHeaderAPI, receipt: ReceiptAPI) → BlockHeaderAPI: Apply the receipt to the old header, and return the resulting header. This may have storage-related side-effects. For example, pre-Byzantium, the state root hash is included in the receipt, and so must be stored into the database.

abstract apply_all_transactions(transactions: Sequence[SignedTransactionAPI], base_header: BlockHeaderAPI) → Tuple[BlockHeaderAPI, Tuple[ReceiptAPI, ...], Tuple[ComputationAPI, ...]]

Determine the results of applying all transactions to the base header. This does not update the current block or header of the VM.

Parameters:

transactions – an iterable of all transactions to apply
base_header – the starting header to apply transactions to

Returns:

the final header, the receipts of each transaction, and the computations

apply_all_withdrawals(withdrawals: Sequence[WithdrawalAPI]) → None

Updates the state by applying all withdrawals. This does not update the current block or header of the VM.

Parameters:: withdrawals – an iterable of all withdrawals to apply

abstract apply_transaction(header: BlockHeaderAPI, transaction: SignedTransactionAPI) → Tuple[ReceiptAPI, ComputationAPI]

Apply the transaction to the current block. This is a wrapper around apply_transaction() with some extra orchestration logic.

Parameters:

header – header of the block before application
transaction – to apply

abstract classmethod build_state(db: AtomicDatabaseAPI, header: BlockHeaderAPI, chain_context: ChainContextAPI, previous_hashes: Iterable[Hash32] = ()) → StateAPI

You probably want VM().state instead of this.

Occasionally, you want to build custom state against a particular header and DB, even if you don’t have the VM initialized. This is a convenience method to do that.

abstract classmethod compute_difficulty(parent_header: BlockHeaderAPI, timestamp: int) → int

Compute the difficulty for a block header.

Parameters:

parent_header – the parent header
timestamp – the timestamp of the child header

abstract configure_header(**header_params: Any) → BlockHeaderAPI: Setup the current header with the provided parameters. This can be used to set fields like the gas limit or timestamp to value different than their computed defaults.

abstract static create_execution_context(header: BlockHeaderAPI, prev_hashes: Iterable[Hash32], chain_context: ChainContextAPI) → ExecutionContextAPI: Create and return the ExecutionContextAPI` for the given header, iterable of block hashes that precede the block and the chain_context.

abstract classmethod create_genesis_header(**genesis_params: Any) → BlockHeaderAPI

Create a genesis header using this VM’s rules.

This is equivalent to calling create_header_from_parent() with parent_header set to None.

abstract classmethod create_header_from_parent(parent_header: BlockHeaderAPI, **header_params: Any) → BlockHeaderAPI: Creates and initializes a new block header from the provided parent_header.

abstract create_transaction(*args: Any, **kwargs: Any) → SignedTransactionAPI: Proxy for instantiating a signed transaction for this VM.

abstract classmethod create_unsigned_transaction(*, nonce: int, gas_price: int, gas: int, to: Address, value: int, data: bytes) → UnsignedTransactionAPI: Proxy for instantiating an unsigned transaction for this VM.

abstract execute_bytecode(origin: Address, gas_price: int, gas: int, to: Address, sender: Address, value: int, data: bytes, code: bytes, code_address: Address | None = None) → ComputationAPI

Execute raw bytecode in the context of the current state of the virtual machine. Note that this skips over some of the logic that would normally happen during a call. Watch out for:

value (ether) is not transferred

state is not rolled back in case of an error

The target account is not necessarily created

others…

For other potential surprises, check the implementation differences between ComputationAPI.apply_computation() and ComputationAPI.apply_message(). (depending on the VM fork)

abstract finalize_block(block: BlockAPI) → BlockAndMetaWitness: Perform any finalization steps like awarding the block mining reward, and persisting the final state root.

abstract classmethod generate_block_from_parent_header_and_coinbase(parent_header: BlockHeaderAPI, coinbase: Address) → BlockAPI: Generate block from parent header and coinbase.

abstract get_block() → BlockAPI: Return the current block.

abstract classmethod get_block_class() → Type[BlockAPI]: Return the Block class that this VM uses for blocks.

abstract static get_block_reward() → int: Return the amount in wei that should be given to a miner as a reward for this block.

Note

This is an abstract method that must be implemented in subclasses

abstract get_header() → BlockHeaderAPI: Return the current header.

abstract classmethod get_nephew_reward() → int: Return the reward which should be given to the miner of the given nephew.

Note

This is an abstract method that must be implemented in subclasses

abstract classmethod get_prev_hashes(last_block_hash: Hash32, chaindb: ChainDatabaseAPI) → Iterable[Hash32] | None: Return an iterable of block hashes that precede the block with the given last_block_hash.

abstract classmethod get_receipt_builder() → Type[ReceiptBuilderAPI]: Return the class that this VM uses to encode and decode receipts.

abstract classmethod get_state_class() → Type[StateAPI]: Return the class that this VM uses for states.

abstract classmethod get_transaction_builder() → Type[TransactionBuilderAPI]: Return the class that this VM uses to build and encode transactions.

abstract static get_uncle_reward(block_number: BlockNumber, uncle: BlockHeaderAPI) → int: Return the reward which should be given to the miner of the given uncle.

Note

This is an abstract method that must be implemented in subclasses

abstract import_block(block: BlockAPI) → BlockAndMetaWitness: Import the given block to the chain.

abstract in_costless_state() → AbstractContextManager[StateAPI]: Return a ContextManager with the current state wrapped in a temporary block. In this state, the ability to pay gas costs is ignored.

abstract increment_blob_gas_used(old_header: BlockHeaderAPI, transaction: TransactionFieldsAPI) → BlockHeaderAPI: Update the header by incrementing the blob_gas_used for the transaction.

abstract make_receipt(base_header: BlockHeaderAPI, transaction: SignedTransactionAPI, computation: ComputationAPI, state: StateAPI) → ReceiptAPI

Generate the receipt resulting from applying the transaction.

Parameters:

base_header – the header of the block before the transaction was applied.
transaction – the transaction used to generate the receipt
computation – the result of running the transaction computation
state – the resulting state, after executing the computation

Returns:

receipt

abstract mine_block(block: BlockAPI, *args: Any, **kwargs: Any) → BlockAndMetaWitness: Mine the given block. Proxies to self.pack_block method.

abstract pack_block(block: BlockAPI, *args: Any, **kwargs: Any) → BlockAPI

Pack block for mining.

Parameters:

coinbase (bytes) – 20-byte public address to receive block reward
uncles_hash (bytes) – 32 bytes
state_root (bytes) – 32 bytes
transaction_root (bytes) – 32 bytes
receipt_root (bytes) – 32 bytes
bloom (int) –
gas_used (int) –
extra_data (bytes) – 32 bytes
mix_hash (bytes) – 32 bytes
nonce (bytes) – 8 bytes

abstract set_block_transactions_and_withdrawals(base_block: BlockAPI, new_header: BlockHeaderAPI, transactions: Sequence[SignedTransactionAPI], receipts: Sequence[ReceiptAPI], withdrawals: Sequence[WithdrawalAPI] | None = None) → BlockAPI: Create a new block with the given transactions and/or withdrawals.

transaction_applied_hook(transaction_index: int, transactions: Sequence[SignedTransactionAPI], base_header: BlockHeaderAPI, partial_header: BlockHeaderAPI, computation: ComputationAPI, receipt: ReceiptAPI) → None: A hook for a subclass to use as a way to note that a transaction was applied. This only gets triggered as part of apply_all_transactions, which is called by block_import.

abstract validate_block(block: BlockAPI) → None: Validate the given block.

abstract classmethod validate_header(header: BlockHeaderAPI, parent_header: BlockHeaderAPI) → None

Raises:: eth.exceptions.ValidationError – if the header is not valid

abstract classmethod validate_receipt(receipt: ReceiptAPI) → None: Validate the given receipt.

abstract validate_seal(header: BlockHeaderAPI) → None: Validate the seal on the given header.

abstract validate_seal_extension(header: BlockHeaderAPI, parents: Iterable[BlockHeaderAPI]) → None: Validate the seal on the given header when all parents must be present. Parent headers that are not yet in the database must be passed as parents.

abstract validate_transaction_against_header(base_header: BlockHeaderAPI, transaction: SignedTransactionAPI) → None

Validate that the given transaction is valid to apply to the given header.

Parameters:

base_header – header before applying the transaction
transaction – the transaction to validate

Raises:

ValidationError if the transaction is not valid to apply

abstract classmethod validate_uncle(block: BlockAPI, uncle: BlockHeaderAPI, uncle_parent: BlockHeaderAPI) → None: Validate the given uncle in the context of the given block.

chaindb: ChainDatabaseAPI

consensus_class: Type[ConsensusAPI]

consensus_context: ConsensusContextAPI

extra_data_max_bytes: ClassVar[int]

fork: str

abstract property previous_hashes: Iterable[Hash32] | None: Convenience API for accessing the previous 255 block hashes.

abstract property state: StateAPI: Return the current state.

HeaderChainAPI

class eth.abc.HeaderChainAPI(base_db: AtomicDatabaseAPI, header: BlockHeaderAPI | None = None)

Like eth.abc.ChainAPI but does only support headers, not entire blocks.

abstract classmethod from_genesis_header(base_db: AtomicDatabaseAPI, genesis_header: BlockHeaderAPI) → HeaderChainAPI: Initialize the chain from the genesis header.

abstract get_block_header_by_hash(block_hash: Hash32) → BlockHeaderAPI: Direct passthrough to headerdb

get_canonical_block_hash(block_number: BlockNumber) → Hash32: Direct passthrough to headerdb

abstract get_canonical_block_header_by_number(block_number: BlockNumber) → BlockHeaderAPI: Direct passthrough to headerdb

abstract get_canonical_head() → BlockHeaderAPI: Direct passthrough to headerdb

abstract classmethod get_headerdb_class() → Type[HeaderDatabaseAPI]: Return the class which should be used for the headerdb

abstract header_exists(block_hash: Hash32) → bool: Direct passthrough to headerdb

abstract import_header(header: BlockHeaderAPI) → Tuple[Tuple[BlockHeaderAPI, ...], Tuple[BlockHeaderAPI, ...]]

Direct passthrough to headerdb

Also updates the local header property to be the latest canonical head.

Returns an iterable of headers representing the headers that are newly part of the canonical chain.

If the imported header is not part of the canonical chain then an empty tuple will be returned.
If the imported header simply extends the canonical chain then a length-1 tuple with the imported header will be returned.
If the header is part of a non-canonical chain which overtakes the current canonical chain then the returned tuple will contain the headers which are newly part of the canonical chain.

chain_id: int

header: BlockHeaderAPI

vm_configuration: Tuple[Tuple[BlockNumber, Type[VirtualMachineAPI]], ...]

ChainAPI

class eth.abc.ChainAPI

A Chain is a combination of one or more VM classes. Each VM is associated with a range of blocks. The Chain class acts as a wrapper around these other VM classes, delegating operations to the appropriate VM depending on the current block number.

abstract build_block_with_transactions_and_withdrawals(transactions: Tuple[SignedTransactionAPI, ...], parent_header: BlockHeaderAPI | None = None, withdrawals: Tuple[WithdrawalAPI, ...] | None = None) → Tuple[BlockAPI, Tuple[ReceiptAPI, ...], Tuple[ComputationAPI, ...]]

Generate a block with the provided transactions. This does not import that block into your chain. If you want this new block in your chain, run import_block() with the result block from this method.

Parameters:

transactions – an iterable of transactions to insert into the block
parent_header – parent of the new block – or canonical head if None
withdrawals – an iterable of withdrawals to insert into the block

Returns:

(new block, receipts, computations)

abstract create_header_from_parent(parent_header: BlockHeaderAPI, **header_params: int | None | BlockNumber | bytes | Address | Hash32) → BlockHeaderAPI: Passthrough helper to the VM class of the block descending from the given header.

abstract create_transaction(*args: Any, **kwargs: Any) → SignedTransactionAPI: Passthrough helper to the current VM class.

abstract create_unsigned_transaction(*, nonce: int, gas_price: int, gas: int, to: Address, value: int, data: bytes) → UnsignedTransactionAPI: Passthrough helper to the current VM class.

abstract estimate_gas(transaction: SignedTransactionAPI, at_header: BlockHeaderAPI | None = None) → int: Return an estimation of the amount of gas the given transaction will use if executed on top of the block specified by at_header.

abstract classmethod from_genesis(base_db: AtomicDatabaseAPI, genesis_params: Dict[str, int | None | BlockNumber | bytes | Address | Hash32], genesis_state: Dict[Address, AccountDetails] | None = None) → ChainAPI: Initialize the Chain from a genesis state.

abstract classmethod from_genesis_header(base_db: AtomicDatabaseAPI, genesis_header: BlockHeaderAPI) → ChainAPI: Initialize the chain from the genesis header.

abstract get_ancestors(limit: int, header: BlockHeaderAPI) → Tuple[BlockAPI, ...]: Return limit number of ancestor blocks from the current canonical head.

abstract get_block() → BlockAPI: Return the current block at the tip of the chain.

abstract get_block_by_hash(block_hash: Hash32) → BlockAPI

Return the requested block as specified by block_hash.

Raises:

eth.exceptions.HeaderNotFound – if the header is missing
eth.exceptions.BlockNotFound – if any part of the block body is missing

abstract get_block_by_header(block_header: BlockHeaderAPI) → BlockAPI

Return the requested block as specified by the block_header.

Raises:: eth.exceptions.BlockNotFound – if any part of the block body is missing

abstract get_block_header_by_hash(block_hash: Hash32) → BlockHeaderAPI: Return the requested block header as specified by block_hash. Raise BlockNotFound if no block header with the given hash exists in the db.

abstract get_canonical_block_by_number(block_number: BlockNumber) → BlockAPI

Return the block with the given block_number in the canonical chain.

Raise BlockNotFound if no block with the given block_number exists in the canonical chain.

abstract get_canonical_block_hash(block_number: BlockNumber) → Hash32

Return the block hash with the given block_number in the canonical chain.

Raise BlockNotFound if there’s no block with the given number in the canonical chain.

abstract get_canonical_block_header_by_number(block_number: BlockNumber) → BlockHeaderAPI

Return the block header with the given number in the canonical chain.

Raise HeaderNotFound if there’s no block header with the given number in the canonical chain.

abstract get_canonical_head() → BlockHeaderAPI

Return the block header at the canonical chain head.

Raise CanonicalHeadNotFound if there’s no head defined for the canonical chain.

abstract get_canonical_transaction(transaction_hash: Hash32) → SignedTransactionAPI

Return the requested transaction as specified by the transaction_hash from the canonical chain.

Raise TransactionNotFound if no transaction with the specified hash is found in the canonical chain.

abstract get_canonical_transaction_by_index(block_number: BlockNumber, index: int) → SignedTransactionAPI

Return the requested transaction as specified by the block_number and index from the canonical chain.

Raise TransactionNotFound if no transaction exists at index at block_number in the canonical chain.

abstract get_canonical_transaction_index(transaction_hash: Hash32) → Tuple[BlockNumber, int]

Return a 2-tuple of (block_number, transaction_index) indicating which block the given transaction can be found in and at what index in the block transactions.

Raise TransactionNotFound if the transaction does not exist in the canonical chain.

abstract classmethod get_chaindb_class() → Type[ChainDatabaseAPI]: Return the class for the used ChainDatabaseAPI.

abstract get_score(block_hash: Hash32) → int

Return the difficulty score of the block with the given block_hash.

Raise HeaderNotFound if there is no matching block hash.

abstract get_transaction_receipt(transaction_hash: Hash32) → ReceiptAPI

Return the requested receipt for the transaction as specified by the transaction_hash.

Raise ReceiptNotFound if no receipt for the specified transaction_hash is found in the canonical chain.

abstract get_transaction_receipt_by_index(block_number: BlockNumber, index: int) → ReceiptAPI

Return the requested receipt for the transaction as specified by the block_number and index.

Raise ReceiptNotFound if no receipt for the specified block_number and index is found in the canonical chain.

abstract get_transaction_result(transaction: SignedTransactionAPI, at_header: BlockHeaderAPI) → bytes: Return the result of running the given transaction. This is referred to as a call() in web3.

abstract get_vm(header: BlockHeaderAPI | None = None) → VirtualMachineAPI: Return the VM instance for the given header.

abstract classmethod get_vm_class(header: BlockHeaderAPI) → Type[VirtualMachineAPI]: Return the VM class for the given header

classmethod get_vm_class_for_block_number(block_number: BlockNumber) → Type[VirtualMachineAPI]: Return the VM class for the given block_number

abstract import_block(block: BlockAPI, perform_validation: bool = True) → BlockImportResult

Import the given block and return a 3-tuple

the imported block
a tuple of blocks which are now part of the canonical chain.
a tuple of blocks which were canonical and now are no longer canonical.

abstract validate_block(block: BlockAPI) → None

Validate a block that is either being mined or imported.

Since block validation (specifically the uncle validation) must have access to the ancestor blocks, this validation must occur at the Chain level.

Cannot be used to validate genesis block.

abstract validate_chain(root: BlockHeaderAPI, descendants: Tuple[BlockHeaderAPI, ...], seal_check_random_sample_rate: int = 1) → None

Validate that all of the descendents are valid, given that the root header is valid.

By default, check the seal validity (Proof-of-Work on Ethereum 1.x mainnet) of all headers. This can be expensive. Instead, check a random sample of seals using seal_check_random_sample_rate.

abstract validate_chain_extension(headers: Tuple[BlockHeaderAPI, ...]) → None: Validate a chain of headers under the assumption that the entire chain of headers is present. Headers that are not already in the database must exist in headers. Calling this API is not a replacement for calling validate_chain(), it is an additional API to call at a different stage of header processing to enable consensus schemes where the consensus can not be verified out of order.

abstract validate_receipt(receipt: ReceiptAPI, at_header: BlockHeaderAPI) → None: Validate the given receipt at the given header.

abstract validate_seal(header: BlockHeaderAPI) → None: Validate the seal on the given header.

abstract validate_uncles(block: BlockAPI) → None: Validate the uncles for the given block.

chain_id: int

chaindb: ChainDatabaseAPI

consensus_context_class: Type[ConsensusContextAPI]

vm_configuration: Tuple[Tuple[BlockNumber, Type[VirtualMachineAPI]], ...]

MiningChainAPI

class eth.abc.MiningChainAPI(base_db: AtomicDatabaseAPI, header: BlockHeaderAPI | None = None)

Like ChainAPI but with APIs to create blocks incrementally.

abstract apply_transaction(transaction: SignedTransactionAPI) → Tuple[BlockAPI, ReceiptAPI, ComputationAPI]

Apply the transaction to the current tip block.

WARNING: ReceiptAPI and Transaction trie generation is computationally heavy and incurs significant performance overhead.

abstract mine_all(transactions: Sequence[SignedTransactionAPI], *args: Any, parent_header: BlockHeaderAPI | None = None, **kwargs: Any) → Tuple[BlockImportResult, Tuple[ReceiptAPI, ...], Tuple[ComputationAPI, ...]]

Build a block with the given transactions, and mine it.

Optionally, supply the parent block header to mine on top of.

This is much faster than individually running apply_transaction() and then mine_block().

abstract mine_block(*args: Any, **kwargs: Any) → BlockAPI: Mines the current block. Proxies to the current Virtual Machine. See VM. mine_block()

abstract mine_block_extended(*args: Any, **kwargs: Any) → BlockAndMetaWitness: Just like mine_block(), but includes extra returned info. Currently, the only extra info returned is the MetaWitness.

abstract set_header_timestamp(timestamp: int) → None

Set the timestamp of the pending header to mine.

This is mostly useful for testing, as the timestamp will be chosen automatically if this method is not called.

header: BlockHeaderAPI