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.

as_dict() → Dict[collections.abc.Hashable, Any]

Return a dictionary representation of the header.

build_changeset(*args, **kwargs) → Any

Open a changeset to modify the header.

base_fee_per_gas

Return the base fee per gas of the block.

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

hash

Return the hash of the block header.

hex_hash

Return the hash as a hex string.

is_genesis

Return True if this header represents the genesis block of the chain, otherwise False.

mining_hash

Return the mining hash of the block header.

BlockHeaderAPI

class eth.abc.BlockHeaderAPI

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

copy(*args, **kwargs) → eth.abc.BlockHeaderAPI

Return a copy of the header, optionally overwriting any of its properties.

LogAPI

class eth.abc.LogAPI

A class to define a written log.

ReceiptAPI

class eth.abc.ReceiptAPI

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

copy(*args, **kwargs) → eth.abc.ReceiptAPI

Return a copy of the receipt, optionally overwriting any of its properties.

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.

BaseTransactionAPI

class eth.abc.BaseTransactionAPI

A class to define all common methods of a transaction.

copy(**overrides) → T

Return a copy of the transaction.

gas_used_by(computation: eth.abc.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.

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.

validate() → None

Hook called during instantiation to ensure that all transaction parameters pass validation rules.

access_list

Get addresses to be accessed by a transaction, and their storage slots.

intrinsic_gas

Convenience property for the return value of get_intrinsic_gas

TransactionFieldsAPI

class eth.abc.TransactionFieldsAPI

A class to define all common transaction fields.

gas_price

Will raise AttributeError if get or set on a 1559 transaction.

hash

Return the hash of the transaction.

max_fee_per_gas

Will default to gas_price if this is a pre-1559 transaction.

max_priority_fee_per_gas

Will default to gas_price if this is a pre-1559 transaction.

UnsignedTransactionAPI

class eth.abc.UnsignedTransactionAPI

A class representing a transaction before it is signed.

as_signed_transaction(private_key: eth_keys.datatypes.PrivateKey) → eth.abc.SignedTransactionAPI

Return a version of this transaction which has been signed using the provided private_key

SignedTransactionAPI

class eth.abc.SignedTransactionAPI(*args, **kwargs)
as_dict() → Dict[collections.abc.Hashable, Any]

Return a dictionary representation of the transaction.

check_signature_validity() → None

Check if the signature is valid. Raise a ValidationError if the signature is invalid.

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.

get_message_for_signing() → bytes

Return the bytestring that should be signed in order to create a signed transaction.

get_sender() → NewType.<locals>.new_type

Get the 20-byte address which sent this transaction.

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

make_receipt(status: bytes, gas_used: int, log_entries: Tuple[Tuple[bytes, Tuple[int, ...], bytes], ...]) → eth.abc.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
validate() → None

Hook called during instantiation to ensure that all transaction parameters pass validation rules.

is_signature_valid

Return True if the signature is valid, otherwise False.

sender

Convenience and performance property for the return value of get_sender

type_id = 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.

y_parity

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: eth.abc.BlockHeaderAPI, transactions: Sequence[eth.abc.SignedTransactionAPI], uncles: Sequence[eth.abc.BlockHeaderAPI])

A class to define a block.

copy(*args, **kwargs) → eth.abc.BlockAPI

Return a copy of the block, optionally overwriting any of its properties.

classmethod from_header(header: eth.abc.BlockHeaderAPI, chaindb: eth.abc.ChainDatabaseAPI) → eth.abc.BlockAPI

Instantiate a block from the given header and the chaindb.

classmethod get_receipt_builder() → Type[eth.abc.ReceiptBuilderAPI]

Return the receipt builder for the block.

get_receipts(chaindb: eth.abc.ChainDatabaseAPI) → Tuple[eth.abc.ReceiptAPI, ...]

Fetch the receipts for this block from the given chaindb.

classmethod get_transaction_builder() → Type[eth.abc.TransactionBuilderAPI]

Return the transaction builder for the block.

hash

Return the hash of the block.

is_genesis

Return True if this block represents the genesis block of the chain, otherwise False.

number

Return the number of the block.

DatabaseAPI

class eth.abc.DatabaseAPI

A class representing a database.

delete(key: bytes) → None

Delete the given key from the database.

exists(key: bytes) → bool

Return True if the key exists in the database, otherwise False.

set(key: bytes, value: bytes) → None

Assign the value to the key.

AtomicDatabaseAPI

class eth.abc.AtomicDatabaseAPI

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

atomic_batch() → ContextManager[eth.abc.AtomicWriteBatchAPI]

Return a ContextManager to write an atomic batch to the database.

HeaderDatabaseAPI

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

A class representing a database for block headers.

get_block_header_by_hash(block_hash: NewType.<locals>.new_type) → eth.abc.BlockHeaderAPI

Return the block header for the given block_hash. Raise HeaderNotFound if no header with the given block_hash exists in the database.

get_canonical_block_hash(block_number: NewType.<locals>.new_type) → NewType.<locals>.new_type

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.

get_canonical_block_header_by_number(block_number: NewType.<locals>.new_type) → eth.abc.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.

get_canonical_head() → eth.abc.BlockHeaderAPI

Return the current block header at the head of the chain.

get_header_chain_gaps() → Tuple[Tuple[Tuple[NewType.<locals>.new_type, NewType.<locals>.new_type], ...], NewType.<locals>.new_type]

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.

get_score(block_hash: NewType.<locals>.new_type) → int

Return the score for the given block_hash.

header_exists(block_hash: NewType.<locals>.new_type) → bool

Return True if the block_hash exists in the database, otherwise False.

persist_checkpoint_header(header: eth.abc.BlockHeaderAPI, score: int) → None

Persist a checkpoint header with a trusted score. Persisting the checkpoint header automatically sets it as the new canonical head.

persist_header(header: eth.abc.BlockHeaderAPI) → Tuple[Tuple[eth.abc.BlockHeaderAPI, ...], Tuple[eth.abc.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

persist_header_chain(headers: Sequence[eth.abc.BlockHeaderAPI], genesis_parent_hash: NewType.<locals>.new_type = None) → Tuple[Tuple[eth.abc.BlockHeaderAPI, ...], Tuple[eth.abc.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_hashoptional 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.

ChainDatabaseAPI

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

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

add_receipt(block_header: eth.abc.BlockHeaderAPI, index_key: int, receipt: eth.abc.ReceiptAPI) → NewType.<locals>.new_type

Add the given receipt to the provided block header.

Return the updated receipts_root for updated block header.

add_transaction(block_header: eth.abc.BlockHeaderAPI, index_key: int, transaction: eth.abc.SignedTransactionAPI) → NewType.<locals>.new_type

Add the given transaction to the provided block header.

Return the updated transactions_root for updated block header.

exists(key: bytes) → bool

Return True if the given key exists in the database.

get(key: bytes) → bytes

Return the value for the given key or a KeyError if it doesn’t exist in the database.

get_block_transaction_hashes(block_header: eth.abc.BlockHeaderAPI) → Tuple[NewType.<locals>.new_type, ...]

Return a tuple cointaining the hashes of the transactions of the given block_header.

get_block_transactions(block_header: eth.abc.BlockHeaderAPI, transaction_decoder: Type[eth.abc.TransactionDecoderAPI]) → Tuple[eth.abc.SignedTransactionAPI, ...]

Return an iterable of transactions for the block speficied by the given block header.

get_block_uncles(uncles_hash: NewType.<locals>.new_type) → Tuple[eth.abc.BlockHeaderAPI, ...]

Return an iterable of uncle headers specified by the given uncles_hash

get_receipt_by_index(block_number: NewType.<locals>.new_type, receipt_index: int, receipt_decoder: Type[eth.abc.ReceiptDecoderAPI]) → eth.abc.ReceiptAPI

Return the receipt of the transaction at specified index for the block header obtained by the specified block number

get_receipts(header: eth.abc.BlockHeaderAPI, receipt_decoder: Type[eth.abc.ReceiptDecoderAPI]) → Tuple[eth.abc.ReceiptAPI, ...]

Return a tuple of receipts for the block specified by the given block header.

get_transaction_by_index(block_number: NewType.<locals>.new_type, transaction_index: int, transaction_decoder: Type[eth.abc.TransactionDecoderAPI]) → eth.abc.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.

get_transaction_index(transaction_hash: NewType.<locals>.new_type) → Tuple[NewType.<locals>.new_type, 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.

persist_block(block: eth.abc.BlockAPI, genesis_parent_hash: NewType.<locals>.new_type = None) → Tuple[Tuple[NewType.<locals>.new_type, ...], Tuple[NewType.<locals>.new_type, ...]]

Persist the given block’s header and uncles.

Parameters:
  • block – the block that gets persisted
  • genesis_parent_hashoptional 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.

persist_trie_data_dict(trie_data_dict: Dict[NewType.<locals>.new_type, bytes]) → None

Store raw trie data to db from a dict

persist_uncles(uncles: Tuple[eth.abc.BlockHeaderAPI]) → NewType.<locals>.new_type

Persist the list of uncles to the database.

Return the uncles hash.

persist_unexecuted_block(block: eth.abc.BlockAPI, receipts: Tuple[eth.abc.ReceiptAPI, ...], genesis_parent_hash: NewType.<locals>.new_type = None) → Tuple[Tuple[NewType.<locals>.new_type, ...], Tuple[NewType.<locals>.new_type, ...]]

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_hashoptional 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.

GasMeterAPI

class eth.abc.GasMeterAPI

A class to define a gas meter.

consume_gas(amount: int, reason: str) → None

Consume amount of gas for a defined reason.

refund_gas(amount: int) → None

Refund amount of gas.

return_gas(amount: int) → None

Return amount of gas.

MessageAPI

class eth.abc.MessageAPI

A message for VM computation.

OpcodeAPI

class eth.abc.OpcodeAPI

A class representing an opcode.

classmethod as_opcode(logic_fn: Callable[ComputationAPI, None], mnemonic: str, gas_cost: int) → T

Class factory method for turning vanilla functions into Opcodes.

TransactionContextAPI

class eth.abc.TransactionContextAPI(gas_price: int, origin: NewType.<locals>.new_type)

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

get_next_log_counter() → int

Increment and return the log counter.

gas_price

Return the gas price of the transaction context.

origin

Return the origin of the transaction context.

MemoryAPI

class eth.abc.MemoryAPI

A class representing the memory of the VirtualMachineAPI.

extend(start_position: int, size: int) → None

Extend the memory from the given start_position to the provided size.

read(start_position: int, size: int) → memoryview

Return a view into the memory

read_bytes(start_position: int, size: int) → bytes

Read a value from memory and return a fresh bytes instance

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.

dup(position: int) → None

Perform a DUP operation on the stack.

pop1_any() → Union[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.

pop1_bytes() → bytes

Pop and return a bytes element from the stack.

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

pop1_int() → int

Pop and return an integer from the stack.

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

pop_any(num_items: int) → Tuple[Union[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.

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.

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.

push_bytes(value: bytes) → None

Push a bytes item onto the stack.

push_int(value: int) → None

Push an integer item onto the stack.

swap(position: int) → None

Perform a SWAP operation on the stack.

CodeStreamAPI

class eth.abc.CodeStreamAPI

A class representing a stream of EVM code.

is_valid_opcode(position: int) → bool

Return True if a valid opcode exists at position.

peek() → int

Return the ordinal value of the byte at the current program counter.

read(size: int) → bytes

Read and return the code from the current position of the cursor up to size.

seek(program_counter: int) → ContextManager[eth.abc.CodeStreamAPI]

Return a ContextManager with the program counter set to program_counter.

StackManipulationAPI

class eth.abc.StackManipulationAPI
stack_pop1_any() → Union[int, bytes]

Pop one item from the stack and return the value either as byte or the ordinal value of a byte.

stack_pop1_bytes() → bytes

Pop one item from the stack and return the value as bytes.

stack_pop1_int() → int

Pop one item from the stack and return the ordinal value of the represented bytes.

stack_pop_any(num_items: int) → Tuple[Union[int, bytes], ...]

Pop the last num_items from the stack, returning a tuple with potentially mixed values of bytes or ordinal values of bytes.

stack_pop_bytes(num_items: int) → Tuple[bytes, ...]

Pop the last num_items from the stack, returning a tuple of bytes.

stack_pop_ints(num_items: int) → Tuple[int, ...]

Pop the last num_items from the stack, returning a tuple of their ordinal values.

stack_push_bytes(value: bytes) → None

Push value on the stack which must be a 32 byte string.

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.

base_fee_per_gas

Return the base fee per gas of the block

block_number

Return the number of the block.

chain_id

Return the id of the chain.

coinbase

Return the coinbase address of the block.

difficulty

Return the difficulty of the block.

gas_limit

Return the gas limit of the block.

prev_hashes

Return an iterable of block hashes that precede the block.

timestamp

Return the timestamp of the block.

ComputationAPI

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

The base class for all execution computations.

add_child_computation(child_computation: eth.abc.ComputationAPI) → None

Add the given child_computation.

add_log_entry(account: NewType.<locals>.new_type, topics: Tuple[int, ...], data: bytes) → None

Add a log entry.

apply_child_computation(child_msg: eth.abc.MessageAPI) → eth.abc.ComputationAPI

Apply the vm message child_msg as a child computation.

classmethod apply_computation(state: eth.abc.StateAPI, message: eth.abc.MessageAPI, transaction_context: eth.abc.TransactionContextAPI) → eth.abc.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().

classmethod apply_create_message(state: eth.abc.StateAPI, message: eth.abc.MessageAPI, transaction_context: eth.abc.TransactionContextAPI) → eth.abc.ComputationAPI

Execute a VM message to create a new contract. This is where the VM-specific create logic exists.

classmethod apply_message(state: eth.abc.StateAPI, message: eth.abc.MessageAPI, transaction_context: eth.abc.TransactionContextAPI) → eth.abc.ComputationAPI

Execute a VM message. This is where the VM-specific call logic exists.

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.

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.

generate_child_computation(child_msg: eth.abc.MessageAPI) → eth.abc.ComputationAPI

Generate a child computation from the given child_msg.

get_accounts_for_deletion() → Tuple[Tuple[NewType.<locals>.new_type, NewType.<locals>.new_type], ...]

Return a tuple of addresses that are registered for deletion.

get_gas_meter() → eth.abc.GasMeterAPI

Return the GasMeterAPI of the computation.

get_gas_refund() → int

Return the number of refunded gas.

get_gas_remaining() → int

Return the number of remaining gas.

get_gas_used() → int

Return the number of used gas.

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.

get_opcode_fn(opcode: int) → eth.abc.OpcodeAPI

Return the function for the given opcode.

classmethod get_precompiles() → Dict[NewType.<locals>.new_type, Callable[eth.abc.ComputationAPI, None]]

Return a dictionary where the keys are the addresses of precompiles and the values are the precompile functions.

get_raw_log_entries() → Tuple[Tuple[int, bytes, Tuple[int, ...], bytes], ...]

Return a tuple of raw log entries.

memory_read(start_position: int, size: int) → memoryview

Read and return a view of size bytes from memory starting at start_position.

memory_read_bytes(start_position: int, size: int) → bytes

Read and return size bytes from memory starting at start_position.

memory_write(start_position: int, size: int, value: bytes) → None

Write value to memory at start_position. Require that len(value) == size.

prepare_child_message(gas: int, to: NewType.<locals>.new_type, value: int, data: Union[bytes, memoryview], code: bytes, **kwargs) → eth.abc.MessageAPI

Helper method for creating a child computation.

raise_if_error() → None

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

Raises:VMError
refund_gas(amount: int) → None

Add amount of gas to the pool of gas marked to be refunded.

register_account_for_deletion(beneficiary: NewType.<locals>.new_type) → None

Register the address of beneficiary for deletion.

return_gas(amount: int) → None

Return amount of gas to the available gas pool.

stack_dup(position: int) → None

Duplicate the stack item at position and pushes it onto the stack.

stack_swap(position: int) → None

Swap the item on the top of the stack with the item at position.

error

Return the VMError of the computation. Raise AttributeError if no error exists.

is_error

Return True if the computation resulted in an error.

is_origin_computation

Return True if this computation is the outermost computation at depth == 0.

is_success

Return True if the computation did not result in an error.

output

Get the return value of the computation.

precompiles

Return a dictionary where the keys are the addresses of precompiles and the values are the precompile functions.

should_burn_gas

Return True if the remaining gas should be burned.

should_erase_return_data

Return True if the return data should be zerod out due to an error.

should_return_gas

Return True if the remaining gas should be returned.

AccountStorageDatabaseAPI

class eth.abc.AccountStorageDatabaseAPI

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

commit(checkpoint: NewType.<locals>.new_type) → None

Collapse changes into the given checkpoint.

delete() → None

Delete the entire storage at the account.

discard(checkpoint: NewType.<locals>.new_type) → None

Discard the given checkpoint.

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.

get_accessed_slots() → FrozenSet[int]

List all the slots that had been accessed since object creation.

get_changed_root() → NewType.<locals>.new_type

Return the changed root hash. Raise ValidationError if the root has not changed.

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.

make_storage_root() → None

Force calculation of the storage root for this account

persist(db: eth.abc.DatabaseAPI) → None

Persist all changes to the database.

record(checkpoint: NewType.<locals>.new_type) → None

Record changes into the given checkpoint.

set(slot: int, value: int) → None

Write value into slot.

has_changed_root

Return True if the storage root has changed.

AccountDatabaseAPI

class eth.abc.AccountDatabaseAPI(db: eth.abc.AtomicDatabaseAPI, state_root: NewType.<locals>.new_type = b'Vxe8x1fx17x1bxccUxa6xffx83Exe6x92xc0xf8n[Hxe0x1bx99lxadxc0x01b/xb5xe3cxb4!')

A class representing a database for accounts.

account_exists(address: NewType.<locals>.new_type) → bool

Return True if an account exists at address, otherwise False.

account_has_code_or_nonce(address: NewType.<locals>.new_type) → bool

Return True if either code or a nonce exists at address.

account_is_empty(address: NewType.<locals>.new_type) → bool

Return True if an account exists at address.

commit(checkpoint: NewType.<locals>.new_type) → None

Collapse changes into checkpoint.

delete_account(address: NewType.<locals>.new_type) → None

Delete the account at address.

delete_code(address: NewType.<locals>.new_type) → None

Delete the code at address.

delete_storage(address: NewType.<locals>.new_type) → None

Delete the storage at address.

discard(checkpoint: NewType.<locals>.new_type) → None

Discard the given checkpoint.

get_balance(address: NewType.<locals>.new_type) → int

Return the balance at address.

get_code(address: NewType.<locals>.new_type) → bytes

Return the code at the given address.

get_code_hash(address: NewType.<locals>.new_type) → NewType.<locals>.new_type

Return the hash of the code at address.

get_nonce(address: NewType.<locals>.new_type) → int

Return the nonce for address.

get_storage(address: NewType.<locals>.new_type, 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.

has_root(state_root: bytes) → bool

Return True if the state_root exists, otherwise False.

increment_nonce(address: NewType.<locals>.new_type) → None

Increment the nonce for address.

is_address_warm(address: NewType.<locals>.new_type) → bool

Was the account accessed during this transaction?

See EIP-2929

is_storage_warm(address: NewType.<locals>.new_type, slot: int) → bool

Was the storage slot accessed during this transaction?

See EIP-2929

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.

make_state_root() → NewType.<locals>.new_type

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 persistance.

Returns:the new state root
mark_address_warm(address: NewType.<locals>.new_type) → None

Mark the account as accessed during this transaction.

See EIP-2929

mark_storage_warm(address: NewType.<locals>.new_type, slot: int) → None

Mark the storage slot as accessed during this transaction.

See EIP-2929

persist() → eth.abc.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.

record() → NewType.<locals>.new_type

Create and return a new checkpoint.

set_balance(address: NewType.<locals>.new_type, balance: int) → None

Set balance as the new balance for address.

set_code(address: NewType.<locals>.new_type, code: bytes) → None

Set code as the new code at address.

set_nonce(address: NewType.<locals>.new_type, nonce: int) → None

Set nonce as the new nonce for address.

set_storage(address: NewType.<locals>.new_type, slot: int, value: int) → None

Write value into slot for the given address.

touch_account(address: NewType.<locals>.new_type) → None

Touch the account at address.

state_root

Return the state root hash.

TransactionExecutorAPI

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

A class providing APIs to execute transactions on VM state.

build_computation(message: eth.abc.MessageAPI, transaction: eth.abc.SignedTransactionAPI) → eth.abc.ComputationAPI

Apply the message to the VM and use the given transaction to retrieve the context from.

build_evm_message(transaction: eth.abc.SignedTransactionAPI) → eth.abc.MessageAPI

Build and return a MessageAPI from the given transaction.

finalize_computation(transaction: eth.abc.SignedTransactionAPI, computation: eth.abc.ComputationAPI) → eth.abc.ComputationAPI

Finalize the transaction.

validate_transaction(transaction: eth.abc.SignedTransactionAPI) → None

Validate the given transaction. Raise a ValidationError if the transaction is invalid.

ConfigurableAPI

class eth.abc.ConfigurableAPI

A class providing inline subclassing.

StateAPI

class eth.abc.StateAPI(db: eth.abc.AtomicDatabaseAPI, execution_context: eth.abc.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:

account_exists(address: NewType.<locals>.new_type) → bool

Return True if an account exists at address.

account_is_empty(address: NewType.<locals>.new_type) → bool

Return True if the account at address is empty, otherwise False.

apply_transaction(transaction: eth.abc.SignedTransactionAPI) → eth.abc.ComputationAPI

Apply transaction to the vm state

Parameters:transaction – the transaction to apply
Returns:the computation
commit(snapshot: Tuple[NewType.<locals>.new_type, NewType.<locals>.new_type]) → None

Commit the journal to the point where the snapshot was taken. This merges in any changes that were recorded since the snapshot.

costless_execute_transaction(transaction: eth.abc.SignedTransactionAPI) → eth.abc.ComputationAPI

Execute the given transaction with a gas price of 0.

delete_account(address: NewType.<locals>.new_type) → None

Delete the account at the given address.

delete_code(address: NewType.<locals>.new_type) → None

Delete the code at address.

delete_storage(address: NewType.<locals>.new_type) → None

Delete the storage at address

delta_balance(address: NewType.<locals>.new_type, delta: int) → None

Apply delta to the balance at address.

classmethod get_account_db_class() → Type[eth.abc.AccountDatabaseAPI]

Return the AccountDatabaseAPI class that the state class uses.

get_ancestor_hash(block_number: NewType.<locals>.new_type) → NewType.<locals>.new_type

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).

get_balance(address: NewType.<locals>.new_type) → int

Return the balance for the account at address.

get_code(address: NewType.<locals>.new_type) → bytes

Return the code at address.

get_code_hash(address: NewType.<locals>.new_type) → NewType.<locals>.new_type

Return the hash of the code at address.

get_computation(message: eth.abc.MessageAPI, transaction_context: eth.abc.TransactionContextAPI) → eth.abc.ComputationAPI

Return a computation instance for the given message and transaction_context

get_gas_price(transaction: eth.abc.SignedTransactionAPI) → int

Return the gas price of the given transaction.

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

get_nonce(address: NewType.<locals>.new_type) → int

Return the nonce at address.

get_storage(address: NewType.<locals>.new_type, slot: int, from_journal: bool = True) → int

Return the storage at slot for address.

get_tip(transaction: eth.abc.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).

get_transaction_context(transaction: eth.abc.SignedTransactionAPI) → eth.abc.TransactionContextAPI

Return the TransactionContextAPI for the given transaction

classmethod get_transaction_context_class() → Type[eth.abc.TransactionContextAPI]

Return the BaseTransactionContext class that the state class uses.

get_transaction_executor() → eth.abc.TransactionExecutorAPI

Return the transaction executor.

has_code_or_nonce(address: NewType.<locals>.new_type) → bool

Return True if either a nonce or code exists at the given address.

increment_nonce(address: NewType.<locals>.new_type) → None

Increment the nonce at address.

is_address_warm(address: NewType.<locals>.new_type) → bool

Was the account accessed during this transaction?

See EIP-2929

is_storage_warm(address: NewType.<locals>.new_type, slot: int) → bool

Was the storage slot accessed during this transaction?

See EIP-2929

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.

make_state_root() → NewType.<locals>.new_type

Create and return the state root.

mark_address_warm(address: NewType.<locals>.new_type) → None

Mark the account as accessed during this transaction.

See EIP-2929

mark_storage_warm(address: NewType.<locals>.new_type, slot: int) → None

Mark the storage slot as accessed during this transaction.

See EIP-2929

override_transaction_context(gas_price: int) → ContextManager[None]

Return a ContextManager that overwrites the current transaction context, applying the given gas_price.

persist() → eth.abc.MetaWitnessAPI

Persist the current state to the database.

revert(snapshot: Tuple[NewType.<locals>.new_type, NewType.<locals>.new_type]) → None

Revert the VM to the state at the snapshot

set_balance(address: NewType.<locals>.new_type, balance: int) → None

Set balance to the balance at address.

set_code(address: NewType.<locals>.new_type, code: bytes) → None

Set code as the new code at address.

set_nonce(address: NewType.<locals>.new_type, nonce: int) → None

Set nonce as the new nonce at address.

set_storage(address: NewType.<locals>.new_type, slot: int, value: int) → None

Write value to the given slot at address.

snapshot() → Tuple[NewType.<locals>.new_type, NewType.<locals>.new_type]

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.

touch_account(address: NewType.<locals>.new_type) → None

Touch the account at the given address.

validate_transaction(transaction: eth.abc.SignedTransactionAPI) → None

Validate the given transaction.

base_fee

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.

block_number

Return the current block_number from the current execution_context

coinbase

Return the current coinbase from the current execution_context

difficulty

Return the current difficulty from the current execution_context

gas_limit

Return the current gas_limit from the current transaction_context

logger

Return the logger.

state_root

Return the current state_root from the underlying database

timestamp

Return the current timestamp from the current execution_context

VirtualMachineAPI

class eth.abc.VirtualMachineAPI(header: eth.abc.BlockHeaderAPI, chaindb: eth.abc.ChainDatabaseAPI, chain_context: eth.abc.ChainContextAPI, consensus_context: eth.abc.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.
add_receipt_to_header(old_header: eth.abc.BlockHeaderAPI, receipt: eth.abc.ReceiptAPI) → eth.abc.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.

apply_all_transactions(transactions: Sequence[eth.abc.SignedTransactionAPI], base_header: eth.abc.BlockHeaderAPI) → Tuple[eth.abc.BlockHeaderAPI, Tuple[eth.abc.ReceiptAPI, ...], Tuple[eth.abc.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_transaction(header: eth.abc.BlockHeaderAPI, transaction: eth.abc.SignedTransactionAPI) → Tuple[eth.abc.ReceiptAPI, eth.abc.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
classmethod build_state(db: eth.abc.AtomicDatabaseAPI, header: eth.abc.BlockHeaderAPI, chain_context: eth.abc.ChainContextAPI, previous_hashes: Iterable[NewType.<locals>.new_type] = ()) → eth.abc.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.

classmethod compute_difficulty(parent_header: eth.abc.BlockHeaderAPI, timestamp: int) → int

Compute the difficulty for a block header.

Parameters:
  • parent_header – the parent header
  • timestamp – the timestamp of the child header
configure_header(**header_params) → eth.abc.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.

static create_execution_context(header: eth.abc.BlockHeaderAPI, prev_hashes: Iterable[NewType.<locals>.new_type], chain_context: eth.abc.ChainContextAPI) → eth.abc.ExecutionContextAPI

Create and return the ExecutionContextAPI` for the given header, iterable of block hashes that precede the block and the chain_context.

classmethod create_genesis_header(**genesis_params) → eth.abc.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.

classmethod create_header_from_parent(parent_header: eth.abc.BlockHeaderAPI, **header_params) → eth.abc.BlockHeaderAPI

Creates and initializes a new block header from the provided parent_header.

create_transaction(*args, **kwargs) → eth.abc.SignedTransactionAPI

Proxy for instantiating a signed transaction for this VM.

classmethod create_unsigned_transaction(*, nonce: int, gas_price: int, gas: int, to: NewType.<locals>.new_type, value: int, data: bytes) → eth.abc.UnsignedTransactionAPI

Proxy for instantiating an unsigned transaction for this VM.

execute_bytecode(origin: NewType.<locals>.new_type, gas_price: int, gas: int, to: NewType.<locals>.new_type, sender: NewType.<locals>.new_type, value: int, data: bytes, code: bytes, code_address: NewType.<locals>.new_type = None) → eth.abc.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)

finalize_block(block: eth.abc.BlockAPI) → eth.abc.BlockAndMetaWitness

Perform any finalization steps like awarding the block mining reward, and persisting the final state root.

classmethod generate_block_from_parent_header_and_coinbase(parent_header: eth.abc.BlockHeaderAPI, coinbase: NewType.<locals>.new_type) → eth.abc.BlockAPI

Generate block from parent header and coinbase.

get_block() → eth.abc.BlockAPI

Return the current block.

classmethod get_block_class() → Type[eth.abc.BlockAPI]

Return the Block class that this VM uses for blocks.

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

get_header() → eth.abc.BlockHeaderAPI

Return the current header.

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

classmethod get_prev_hashes(last_block_hash: NewType.<locals>.new_type, chaindb: eth.abc.ChainDatabaseAPI) → Optional[Iterable[NewType.<locals>.new_type]]

Return an iterable of block hashes that precede the block with the given last_block_hash.

classmethod get_receipt_builder() → Type[eth.abc.ReceiptBuilderAPI]

Return the class that this VM uses to encode and decode receipts.

classmethod get_state_class() → Type[eth.abc.StateAPI]

Return the class that this VM uses for states.

classmethod get_transaction_builder() → Type[eth.abc.TransactionBuilderAPI]

Return the class that this VM uses to build and encode transactions.

static get_uncle_reward(block_number: NewType.<locals>.new_type, uncle: eth.abc.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

import_block(block: eth.abc.BlockAPI) → eth.abc.BlockAndMetaWitness

Import the given block to the chain.

in_costless_state() → ContextManager[eth.abc.StateAPI]

Return a ContextManager with the current state wrapped in a temporary block. In this state, the ability to pay gas costs is ignored.

make_receipt(base_header: eth.abc.BlockHeaderAPI, transaction: eth.abc.SignedTransactionAPI, computation: eth.abc.ComputationAPI, state: eth.abc.StateAPI) → eth.abc.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

mine_block(block: eth.abc.BlockAPI, *args, **kwargs) → eth.abc.BlockAndMetaWitness

Mine the given block. Proxies to self.pack_block method.

pack_block(block: eth.abc.BlockAPI, *args, **kwargs) → eth.abc.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
set_block_transactions(base_block: eth.abc.BlockAPI, new_header: eth.abc.BlockHeaderAPI, transactions: Sequence[eth.abc.SignedTransactionAPI], receipts: Sequence[eth.abc.ReceiptAPI]) → eth.abc.BlockAPI

Create a new block with the given transactions.

transaction_applied_hook(transaction_index: int, transactions: Sequence[eth.abc.SignedTransactionAPI], base_header: eth.abc.BlockHeaderAPI, partial_header: eth.abc.BlockHeaderAPI, computation: eth.abc.ComputationAPI, receipt: eth.abc.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.

validate_block(block: eth.abc.BlockAPI) → None

Validate the the given block.

classmethod validate_header(header: eth.abc.BlockHeaderAPI, parent_header: eth.abc.BlockHeaderAPI) → None
Raises:eth.exceptions.ValidationError – if the header is not valid
classmethod validate_receipt(receipt: eth.abc.ReceiptAPI) → None

Validate the given receipt.

validate_seal(header: eth.abc.BlockHeaderAPI) → None

Validate the seal on the given header.

validate_seal_extension(header: eth.abc.BlockHeaderAPI, parents: Iterable[eth.abc.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.

validate_transaction_against_header(base_header: eth.abc.BlockHeaderAPI, transaction: eth.abc.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

classmethod validate_uncle(block: eth.abc.BlockAPI, uncle: eth.abc.BlockHeaderAPI, uncle_parent: eth.abc.BlockHeaderAPI) → None

Validate the given uncle in the context of the given block.

previous_hashes

Convenience API for accessing the previous 255 block hashes.

state

Return the current state.

HeaderChainAPI

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

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

classmethod from_genesis_header(base_db: eth.abc.AtomicDatabaseAPI, genesis_header: eth.abc.BlockHeaderAPI) → eth.abc.HeaderChainAPI

Initialize the chain from the genesis header.

get_block_header_by_hash(block_hash: NewType.<locals>.new_type) → eth.abc.BlockHeaderAPI

Direct passthrough to headerdb

get_canonical_block_hash(block_number: NewType.<locals>.new_type) → NewType.<locals>.new_type

Direct passthrough to headerdb

get_canonical_block_header_by_number(block_number: NewType.<locals>.new_type) → eth.abc.BlockHeaderAPI

Direct passthrough to headerdb

get_canonical_head() → eth.abc.BlockHeaderAPI

Direct passthrough to headerdb

classmethod get_headerdb_class() → Type[eth.abc.HeaderDatabaseAPI]

Return the class which should be used for the headerdb

header_exists(block_hash: NewType.<locals>.new_type) → bool

Direct passthrough to headerdb

import_header(header: eth.abc.BlockHeaderAPI) → Tuple[Tuple[eth.abc.BlockHeaderAPI, ...], Tuple[eth.abc.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.

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.

build_block_with_transactions(transactions: Tuple[eth.abc.SignedTransactionAPI, ...], parent_header: eth.abc.BlockHeaderAPI = None) → Tuple[eth.abc.BlockAPI, Tuple[eth.abc.ReceiptAPI, ...], Tuple[eth.abc.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 to the block
  • parent_header – parent of the new block – or canonical head if None
Returns:

(new block, receipts, computations)

create_header_from_parent(parent_header: eth.abc.BlockHeaderAPI, **header_params) → eth.abc.BlockHeaderAPI

Passthrough helper to the VM class of the block descending from the given header.

create_transaction(*args, **kwargs) → eth.abc.SignedTransactionAPI

Passthrough helper to the current VM class.

create_unsigned_transaction(*, nonce: int, gas_price: int, gas: int, to: NewType.<locals>.new_type, value: int, data: bytes) → eth.abc.UnsignedTransactionAPI

Passthrough helper to the current VM class.

estimate_gas(transaction: eth.abc.SignedTransactionAPI, at_header: eth.abc.BlockHeaderAPI = 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.

classmethod from_genesis(base_db: eth.abc.AtomicDatabaseAPI, genesis_params: Dict[str, Union[int, None, NewType.<locals>.new_type, bytes, NewType.<locals>.new_type, NewType.<locals>.new_type]], genesis_state: Dict[NewType.<locals>.new_type, eth.typing.AccountDetails] = None) → eth.abc.ChainAPI

Initialize the Chain from a genesis state.

classmethod from_genesis_header(base_db: eth.abc.AtomicDatabaseAPI, genesis_header: eth.abc.BlockHeaderAPI) → eth.abc.ChainAPI

Initialize the chain from the genesis header.

get_ancestors(limit: int, header: eth.abc.BlockHeaderAPI) → Tuple[eth.abc.BlockAPI, ...]

Return limit number of ancestor blocks from the current canonical head.

get_block() → eth.abc.BlockAPI

Return the current block at the tip of the chain.

get_block_by_hash(block_hash: NewType.<locals>.new_type) → eth.abc.BlockAPI

Return the requested block as specified by block_hash.

Raises:
get_block_by_header(block_header: eth.abc.BlockHeaderAPI) → eth.abc.BlockAPI

Return the requested block as specified by the block_header.

Raises:eth.exceptions.BlockNotFound – if any part of the block body is missing
get_block_header_by_hash(block_hash: NewType.<locals>.new_type) → eth.abc.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.

get_canonical_block_by_number(block_number: NewType.<locals>.new_type) → eth.abc.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.

get_canonical_block_hash(block_number: NewType.<locals>.new_type) → NewType.<locals>.new_type

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.

get_canonical_block_header_by_number(block_number: NewType.<locals>.new_type) → eth.abc.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.

get_canonical_head() → eth.abc.BlockHeaderAPI

Return the block header at the canonical chain head.

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

get_canonical_transaction(transaction_hash: NewType.<locals>.new_type) → eth.abc.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.

get_canonical_transaction_by_index(block_number: NewType.<locals>.new_type, index: int) → eth.abc.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.

get_canonical_transaction_index(transaction_hash: NewType.<locals>.new_type) → Tuple[NewType.<locals>.new_type, 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 canoncial chain.

classmethod get_chaindb_class() → Type[eth.abc.ChainDatabaseAPI]

Return the class for the used ChainDatabaseAPI.

get_score(block_hash: NewType.<locals>.new_type) → int

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

Raise HeaderNotFound if there is no matching block hash.

get_transaction_receipt(transaction_hash: NewType.<locals>.new_type) → eth.abc.ReceiptAPI

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

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

get_transaction_receipt_by_index(block_number: NewType.<locals>.new_type, index: int) → eth.abc.ReceiptAPI

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

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

get_transaction_result(transaction: eth.abc.SignedTransactionAPI, at_header: eth.abc.BlockHeaderAPI) → bytes

Return the result of running the given transaction. This is referred to as a call() in web3.

get_vm(header: eth.abc.BlockHeaderAPI = None) → eth.abc.VirtualMachineAPI

Return the VM instance for the given header.

classmethod get_vm_class(header: eth.abc.BlockHeaderAPI) → Type[eth.abc.VirtualMachineAPI]

Return the VM class for the given header

classmethod get_vm_class_for_block_number(block_number: NewType.<locals>.new_type) → Type[eth.abc.VirtualMachineAPI]

Return the VM class for the given block_number

import_block(block: eth.abc.BlockAPI, perform_validation: bool = True) → eth.abc.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.
validate_block(block: eth.abc.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.

validate_chain(root: eth.abc.BlockHeaderAPI, descendants: Tuple[eth.abc.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.

validate_chain_extension(headers: Tuple[eth.abc.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.

validate_receipt(receipt: eth.abc.ReceiptAPI, at_header: eth.abc.BlockHeaderAPI) → None

Validate the given receipt at the given header.

validate_seal(header: eth.abc.BlockHeaderAPI) → None

Validate the seal on the given header.

validate_uncles(block: eth.abc.BlockAPI) → None

Validate the uncles for the given block.

MiningChainAPI

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

Like ChainAPI but with APIs to create blocks incrementally.

apply_transaction(transaction: eth.abc.SignedTransactionAPI) → Tuple[eth.abc.BlockAPI, eth.abc.ReceiptAPI, eth.abc.ComputationAPI]

Apply the transaction to the current tip block.

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

mine_all(transactions: Sequence[eth.abc.SignedTransactionAPI], *args, parent_header: eth.abc.BlockHeaderAPI = None, **kwargs) → Tuple[eth.abc.BlockImportResult, Tuple[eth.abc.ReceiptAPI, ...], Tuple[eth.abc.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().

mine_block(*args, **kwargs) → eth.abc.BlockAPI

Mines the current block. Proxies to the current Virtual Machine. See VM. mine_block()

mine_block_extended(*args, **kwargs) → eth.abc.BlockAndMetaWitness

Just like mine_block(), but includes extra returned info. Currently, the only extra info returned is the MetaWitness.

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.