Chain

BaseChain

class eth.chains.base.BaseChain

The base class for all Chain objects

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

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.

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.

chain_id: int = None
chaindb: ChainDatabaseAPI = None
chaindb_class: Type[ChainDatabaseAPI] = None
consensus_context_class: Type[ConsensusContextAPI] = None
vm_configuration: Tuple[Tuple[BlockNumber, Type[VirtualMachineAPI]], ...] = None

Chain

class eth.chains.base.Chain(base_db: AtomicDatabaseAPI)
chaindb_class

alias of ChainDB

consensus_context_class

alias of ConsensusContext

build_block_with_transactions_and_withdrawals(transactions: Sequence[SignedTransactionAPI], parent_header: BlockHeaderAPI | None = None, withdrawals: Sequence[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)

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.

create_transaction(*args: Any, **kwargs: Any) → SignedTransactionAPI

Passthrough helper to the current VM class.

create_unsigned_transaction(*, nonce: int, gas_price: int, gas: int, to: Address, value: int, data: bytes) → UnsignedTransactionAPI

Passthrough helper to the current VM class.

ensure_header(header: BlockHeaderAPI | None = None) → BlockHeaderAPI

Return header if it is not None, otherwise return the header of the canonical head.

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.

classmethod from_genesis(base_db: AtomicDatabaseAPI, genesis_params: Dict[str, int | None | BlockNumber | bytes | Address | Hash32], genesis_state: Dict[Address, AccountDetails] | None = None) → BaseChain

Initialize the Chain from a genesis state.

classmethod from_genesis_header(base_db: AtomicDatabaseAPI, genesis_header: BlockHeaderAPI) → BaseChain

Initialize the chain from the genesis header.

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

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

get_block() → BlockAPI

Return the current block at the tip of the chain.

get_block_by_hash(block_hash: Hash32) → BlockAPI

Return the requested block as specified by block_hash.

Raises:
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

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.

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.

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.

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.

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.

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.

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.

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.

classmethod get_chaindb_class() → Type[ChainDatabaseAPI]

Return the class for the used ChainDatabaseAPI.

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.

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.

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.

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.

get_vm(at_header: BlockHeaderAPI | None = None) → VirtualMachineAPI

Return the VM instance for the given header.

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.

persist_block(block: BlockAPI, perform_validation: bool = True) → BlockPersistResult
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.

validate_receipt(receipt: ReceiptAPI, at_header: BlockHeaderAPI) → None

Validate the given receipt at the given header.

validate_seal(header: BlockHeaderAPI) → None

Validate the seal on the given header.

validate_uncles(block: BlockAPI) → None

Validate the uncles for the given block.

gas_estimator: StaticMethod[Callable[[StateAPI, SignedTransactionAPI], int]] = None
logger = <Logger eth.chain.chain.Chain (WARNING)>

MiningChain

class eth.chains.base.MiningChain(base_db: AtomicDatabaseAPI, header: BlockHeaderAPI | None = None)
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.

get_vm(at_header: BlockHeaderAPI | None = None) → VirtualMachineAPI

Return the VM instance for the given header.

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.

mine_all(transactions: Sequence[SignedTransactionAPI], *args: Any, parent_header: BlockHeaderAPI | None = None, withdrawals: Sequence[WithdrawalAPI] | 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().

mine_block(*args: Any, **kwargs: Any) → BlockAPI

Mine whatever transactions have been incrementally applied so far.

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.

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 = None