ETHHelper Types

Base

class ethhelper.types.IntStr(value: str | int | IntStr)

A class that represents an integer value that can be initialized from a string or another IntStr instance.

This class is designed to work with the orjson library, and provides a way to represent integer values that may be too large to be encoded using 64 bits.

By using an IntStr instance to represent such values, you can ensure that the integers are passed around as Python integers but still allow them to be encoded as strings if necessary.

The value is the value to be initialized. If a string is provided, it will be converted to an integer.

value: int: An integer value.

to_int_or_str() → int | str

Returns the integer value as a string if it has 64 or more bits, otherwise it returns the integer value itself.

Returns:: The integer value as a string if it has 64 or more bits, otherwise the integer value itself.

classmethod validate(value: Any) → Any

Validates and returns the value as an IntStr instance.

Parameters:: value – The value to be validated and returned.
Returns:: An IntStr instance that represents the validated value.
Raises:: TypeError – If the value is not an IntStr, int, or str.

class ethhelper.types.HexBytes(value: str | bytes | HexBytes)

A class that represents a byte string that can be initialized from a string, bytes, hexbytes.HexBytes instance or another HexBytes instance.

classmethod validate(value: Any) → Any

Validates and converts a value to a HexBytes instance.

Parameters:: value – The value to be validated and converted.
Returns:: A HexBytes instance representing the input value.
Raises:: TypeError – If the input value is not a HexBytes, bytes, or string starting with “0x”.

class ethhelper.types.Hash32(value: str | bytes | HexBytes)

A subclass of HexBytes that represents a 32-byte hash value.

to_web3() → Hash32

Returns an eth_typing.Hash32 instance that represents the hash value.

Returns:: An eth_typing.Hash32 instance that represents the hash value.

class ethhelper.types.Address(value: str | bytes | HexBytes)

A subclass of HexBytes that represents an Ethereum address (20 bytes).

to_web3() → Address

Returns a eth_typing.Address instance that represents the address.

Returns:: A eth_typing.Address instance that represents the address.

ethhelper.types.BlockIdentifier: alias of Union[Literal[‘latest’, ‘earliest’, ‘pending’, ‘safe’, ‘finalized’], BlockNumber, Hash32]

class ethhelper.types.Gas

A new type that represents a gas value (an integer).

alias of int

class ethhelper.types.Wei(value: str | int | IntStr)

A subclass of IntStr that represents a value in wei (the smallest unit of ether in Ethereum).

to_web3() → Wei

Returns a web3.types.Wei instance that represents the value in wei.

Returns:: A web3.types.Wei instance that represents the value in wei.

classmethod from_gwei(value: int) → Wei

Class method that converts a value in gigawei to wei.

Parameters:: value – An integer value in gigawei.
Returns:: A Wei instance that represents the converted value in wei.

classmethod from_eth(value: int | float | Decimal) → Wei

Class method that converts a value in ether to wei.

Parameters:: value – A value in ether.
Returns:: A Wei instance that represents the converted value in wei.
Return type:: Wei

Ethereum

class ethhelper.types.AccessEntry(*, address: Address, storageKeys: list[ethhelper.datatypes.base.Hash32])

An entry representing an address with associated storage keys in an access list.

address: Address: The address of the entry.

storage_keys: list[ethhelper.datatypes.base.Hash32]: The storage keys associated with the entry.

class ethhelper.types.AccessList

A new type representing a sequence of AccessEntry instances.

alias of Sequence[AccessEntry]

class ethhelper.types.SyncStatus(*, currentBlock: int, highestBlock: int, startingBlock: int)

The current synchronization status of the Ethereum node.

current_block: int: The current block number.

highest_block: int: The highest block number seen.

starting_block: int: The block number at which the node started syncing.

class ethhelper.types.FeeHistory(*, baseFeePerGas: list[ethhelper.datatypes.base.Wei], gasUsedRatio: list[float], oldestBlock: BlockNumber, reward: list[list[ethhelper.datatypes.base.Wei]] | None = None)

A record of base fees and gas usage ratios.

base_fee_per_gas: list[ethhelper.datatypes.base.Wei]: A list of base fees per gas for each block in the history.

gas_used_ratio: list[float]: A list of gas used ratios for each block in the history.

oldest_block: BlockNumber: The block number of the oldest block in the history.

reward: list[list[ethhelper.datatypes.base.Wei]] | None: A nested list of miner rewards for each block in the history, or None if rewards are not available.

Represents a set of parameters required for creating a transaction.

chain_id: int | None: The chain ID for the transaction.

data: HexBytes | None: The data payload of the transaction.

from_: Address | ENS | None: The sender’s address or ENS name.

gas: Gas | None: The maximum amount of gas to use for the transaction.

gas_price: Wei | None: The price of gas for the transaction. (Legacy pricing)

max_fee_per_gas: Wei | None: The maximum fee per gas for the transaction. (Dynamic fee pricing)

max_priority_fee_per_gas: Wei | None: The maximum priority fee per gas for the transaction. (Dynamic fee pricing)

nonce: Nonce | None: A unique number used to prevent replay attacks.

to: Address | ENS: The recipient’s address or ENS name.

type: int | None: The transaction type, if the chain supports EIP-2718.

value: Wei | None: The amount of Ether to send along with the transaction.

to_web3() → TxParams

Convert the transaction parameters to web3.types.TxParams format.

Returns:: A dictionary representing the transaction parameters in web3.types.TxParams format.

class ethhelper.types.Transaction(*, chainId: int = 1, blockHash: Hash32 | None = None, blockNumber: BlockNumber | None = None, transactionIndex: int | None = None, hash: Hash32, from_: Address, to: Address | None = None, gas: Gas, gasPrice: Wei, maxFeePerGas: Wei | None = None, maxPriorityFeePerGas: Wei | None = None, input: HexBytes, value: Wei, nonce: Nonce, type: int, accessList: AccessList | None = None, r: HexBytes, s: HexBytes, v: int)

A class representing an Ethereum transaction.

chain_id: int: The chain ID for the transaction.

block_hash: Hash32 | None: The hash of the block containing the transaction.

block_number: BlockNumber | None: The block number containing the transaction.

transaction_index: int | None: The transaction index within the block.

hash: Hash32: The hash of the transaction.

from_: Address: The address of the sender of the transaction.

to: Address | None: The address of the recipient of the transaction (if applicable).

gas: Gas: The gas limit for the transaction.

gas_price: Wei: The gas price for the transaction.

max_fee_per_gas: Wei | None: The maximum fee per gas for the transaction (if applicable).

max_priority_fee_per_gas: Wei | None: The maximum priority fee per gas for the transaction (if applicable).

input: HexBytes: The input data for the transaction.

value: Wei: The value of the transaction in Wei.

nonce: Nonce: The nonce of the transaction.

type: int: The type of the transaction (0 for legacy, 1 for EIP-2930, 2 for EIP-1559).

access_list: AccessList | None: The access list for the transaction (if applicable).

r: HexBytes: The r value of the transaction signature.

s: HexBytes: The s value of the transaction signature.

v: int: The v value of the transaction signature.

class ethhelper.types.Block(*, difficulty: IntStr, extraData: HexBytes, gasLimit: Gas, gasUsed: Gas, baseFeePerGas: Wei | None = None, logsBloom: HexBytes, miner: Address, nonce: HexBytes, number: BlockNumber, parentHash: Hash32, hash: Hash32, mixHash: Hash32, receiptsRoot: HexBytes, sha3Uncles: HexBytes, stateRoot: HexBytes, timestamp: int, transactionsRoot: HexBytes, size: int | None = None, totalDifficulty: IntStr | None = None, transactions: list[ethhelper.datatypes.base.Hash32] | list[ethhelper.datatypes.eth.Transaction] | None = None, uncles: list[ethhelper.datatypes.base.Hash32] | None = None)

difficulty: IntStr: The difficulty (in hashes) of mining this block. After the Merge (15537394), this value will be always 0.

extra_data: HexBytes: Additional data provided by the miner. After the Merge (15537394), this value will be always empty bytes.

gas_limit: Gas: The maximum amount of gas that was available to transactions in this block.

gas_used: Gas: The amount of gas that was used to execute transactions in this block.

base_fee_per_gas: Wei | None: The fee per unit of gas burned by the protocol in this block. Before EIP-1559 (12965000), this value was always None.

logs_bloom: HexBytes: A bloom filter that can be used to check if a block may contain log entries matching a filter.

miner: Address: The address (20 bytes) of the account that mined this block.

nonce: HexBytes: The block nonce, a sequence (8 bytes) determined by the miner.

number: BlockNumber: The number of this block, starting at 0 for the genesis block.

parent_hash: Hash32: The hash (32 bytes) of the parent block of this block.

hash: Hash32: The hash (32 bytes) of this block.

mix_hash: Hash32: The hash (32 bytes) that was used as an input to the PoW process. After the Merge (15537394), this value will be the beacon chain’s RANDAO value.

receipts_root: HexBytes: The keccak256 hash (32 bytes) of the trie of transaction receipts in this block.

sha3_uncles: HexBytes: The keccak256 hash (32 bytes) of all the ommers (AKA uncles) associated with this block.

state_root: HexBytes: The keccak256 hash (32 bytes) of the state trie after this block was processed.

timestamp: int: The unix timestamp at which this block was mined.

transactions_root: HexBytes: The keccak256 hash (32 bytes) of the root of the trie of transactions in this block.

size: int | None: The block size in bytes

total_difficulty: IntStr | None: The sum of all difficulty values up to and including this block. After the Merge (15537394), this value is always 58750003716598352816469.

transactions: list[ethhelper.datatypes.base.Hash32] | list[ethhelper.datatypes.eth.Transaction] | None: A list of the hash (32 bytes) of transactions associated with this block.

uncles: list[ethhelper.datatypes.base.Hash32] | None: A list of hash of the uncle blocks of this block. After the Merge (15537394), this value will be always None.

class ethhelper.types.Log(*, blockNumber: BlockNumber, blockHash: Hash32, logIndex: int, address: Address, topics: list[ethhelper.datatypes.base.Hash32], data: HexBytes, transactionHash: Hash32, transactionIndex: int, removed: bool)

A published Ethereum event log.

block_number: BlockNumber: The number of the block in which the log was generated.

block_hash: Hash32: The hash of the block in which the log was generated.

log_index: int: The index of this log in the block.

address: Address: The address of the contract that generated this log.

topics: list[ethhelper.datatypes.base.Hash32]: A list of up to 4 32-byte indexed topics for the log.

data: HexBytes: The unindexed data for this log.

transaction_hash: Hash32: The hash (32 bytes) of the transaction that generated this log.

transaction_index: int: The index of the transaction in the block.

removed: bool: Whether or not the log was removed from the blockchain.

class ethhelper.types.Receipt(*, blockNumber: BlockNumber, blockHash: Hash32, contractAddress: Address | None = None, cumulativeGasUsed: Gas, effectiveGasPrice: Wei, from_: Address, gasUsed: Gas, logs: list[ethhelper.datatypes.eth.Log], logsBloom: HexBytes, status: int, to: Address, transactionHash: Hash32, transactionIndex: int, type: int)

A transaction receipt.

block_number: BlockNumber: The number of the block this receipt is associated with.

block_hash: Hash32: The hash of the block this receipt is associated with.

contract_address: Address | None: The address of the contract created by this transaction if it is a contract creation transaction, otherwise None.

cumulative_gas_used: Gas: The total amount of gas used in the block up to and including this transaction.

effective_gas_price: Wei: The amount of ETH paid per unit of gas in the transaction, including the amount that is burned by EIP-1559.

from_: Address: The address of the account that sent this transaction.

gas_used: Gas: The amount of gas used by this transaction.

logs: list[ethhelper.datatypes.eth.Log]: The logs emitted by this transaction.

logs_bloom: HexBytes: A bloom filter of the logs emitted by this transaction.

status: int: The status code of this transaction, where 0 represents success and non-zero represents failure.

to: Address: The address of the account or contract that received this transaction.

transaction_hash: Hash32: The hash of the transaction that generated this receipt.

transaction_index: int: The index of this transaction in the block.

type: int: The type of this transaction, where 0 represents a legacy transaction, 1 represents an EIP-2930 transaction, and 2 represents an EIP-1559 transaction.

Parameters used for creating Ethereum filters.

address: Address | list[ethhelper.datatypes.base.Address] | None: An Ethereum address or list of addresses to filter on. If None, all addresses are filtered.

block_hash: Hash32 | None: A block hash (32 bytes) to filter on. If None, all blocks are filtered.

from_block: Literal['latest', 'earliest', 'pending', 'safe', 'finalized'] | BlockNumber | Hash32 | None: The starting block for filtering. If None, the filter will start from the earliest block.

to_block: Literal['latest', 'earliest', 'pending', 'safe', 'finalized'] | BlockNumber | Hash32 | None: The ending block for filtering. If None, the filter will end at the latest block.

topics: Sequence[Hash32 | Sequence[Hash32]] | None: A list of topics (32 bytes) to filter on. Each topic can be a single value or a list of values. If None, all topics are filtered.

to_web3() → FilterParams: Converts the FilterParams object to a web3.types.FilterParams object.

Geth

class ethhelper.types.IdNotMatch: An exception raised when a JSON-RPC response ID doesn’t match the request ID.

class ethhelper.types.GethIsDead: An exception raised when the Geth client is not running.

class ethhelper.types.NoSubscribeToken: An exception raised when attempting to subscribe to an Ethereum event without a subscription token.

class ethhelper.types.GethRequest(*, jsonrpc: str = '2.0', id: int | None = None, method: str, params: list[Any])

A class representing a JSON-RPC request to the Geth client.

jsonrpc: str: The version of the JSON-RPC protocol.

id: int | None: The ID of the request, or None if it is a notification.

method: str: The name of the RPC method to call.

params: list[Any]: A list of parameters to pass to the RPC method.

class ethhelper.types.GethSuccessResponse(*, jsonrpc: str = '2.0', id: int | None = None, result: Any = None)

A class representing a successful JSON-RPC response from the Geth client.

jsonrpc: str: The version of the JSON-RPC protocol.

id: int | None: The ID of the response, or None if it is a notification.

result: Any: The result of the RPC method call.

class ethhelper.types.GethErrorDetail(*, jsonrpc: str = '2.0', code: int, message: str)

A class representing the error details in a JSON-RPC error response from the Geth client.

jsonrpc: str: The version of the JSON-RPC protocol.

code: int: The error code.

message: str: A description of the error.

class ethhelper.types.GethError(error: GethErrorDetail | list[ethhelper.datatypes.geth.GethErrorDetail])

An exception representing an error response from the Geth client.

code: The error code.

msg: A description of the error.

class ethhelper.types.GethGraphQLError(msgs: list[str], data: dict[str, Any])

An exception representing an error response from the Geth graphql.

msgs: The error messages.

data: The data received.

class ethhelper.types.GethErrorResponse(*, jsonrpc: str = '2.0', id: int | None = None, error: GethErrorDetail)

A class representing an error response from the Geth client.

jsonrpc: str: The version of the JSON-RPC protocol.

id: int | None: The ID of the response, or None if it is a notification.

error: GethErrorDetail: The details of the error.

ethhelper.types.GethResponse: alias of GethSuccessResponse | GethErrorResponse

class ethhelper.types.GethWSItem(*, subscription: str, result: Any = None)

A class representing an item in a WebSocket response from the Geth client.

subscription: str: The subscription ID.

result: Any: The result of the subscription.

class ethhelper.types.GethWSResponse(*, jsonrpc: str = '2.0', method: str, params: GethWSItem)

A class representing a WebSocket response from the Geth client.

jsonrpc: str: The version of the JSON-RPC protocol.

method: str: The name of the WebSocket method.

params: GethWSItem: The item contained in the response.

class ethhelper.types.CallOverrideParams(*, balance: Wei | None = None, nonce: Nonce | None = None, code: HexBytes | None = None, state: dict[str, Any] | None = None, stateDiff: dict[eth_typing.evm.ChecksumAddress, dict[str, Any]] | None = None)

A class representing override parameters for a contract function call.

balance: Wei | None: The balance of the caller.

nonce: Nonce | None: The nonce of the caller.

code: HexBytes | None: The code of the contract.

state: dict[str, Any] | None: The current state of the contract.

state_diff: dict[eth_typing.evm.ChecksumAddress, dict[str, Any]] | None: The difference in the contract state.

to_web3() → CallOverrideParams

Converts the CallOverrideParams instance to an instance of web3.types.CallOverrideParams.

Returns:: The converted web3.types.CallOverrideParams instance.

ethhelper.types.CallOverride: alias of dict[ChecksumAddress, CallOverrideParams]

Txpool

class ethhelper.types.TxpoolStatus(*, pending: int, queued: int)

A class that represents the status of transactions in the Ethereum transaction pool.

pending: int: The number of pending transactions in the pool.

queued: int: The number of queued transactions in the pool.

class ethhelper.types.TxpoolSnapshot(*, contract_creation: bool = False, to_address: Address, fee: Wei, gas: Gas, gas_fee: Wei)

A class that represents a snapshot of the Ethereum transaction pool.

contract_creation: bool: Whether the transaction is a contract creation. Defaults to False.

to_address: Address: The address of the recipient of the transaction.

fee: Wei: The transaction fee in wei.

gas: Gas: The amount of gas used by the transaction.

gas_fee: Wei: The gas fee for the transaction in wei.

classmethod validate(value: Any) → TxpoolSnapshot

Validates the given value and creates a new instance of the TxpoolSnapshot class.

Parameters:: value – The value to be validated and converted.
Returns:: The converted TxpoolSnapshot instance.

class ethhelper.types.TxpoolInspect(*, pending: dict[eth_typing.evm.ChecksumAddress, dict[web3.types.Nonce, ethhelper.datatypes.txpool.TxpoolSnapshot]], queued: dict[eth_typing.evm.ChecksumAddress, dict[web3.types.Nonce, ethhelper.datatypes.txpool.TxpoolSnapshot]])

A class that represents the contents of the Ethereum transaction pool.

pending: dict[eth_typing.evm.ChecksumAddress, dict[web3.types.Nonce, ethhelper.datatypes.txpool.TxpoolSnapshot]]: A dictionary that maps from account address to nonce to snapshot of the corresponding transaction in the pending pool.

queued: dict[eth_typing.evm.ChecksumAddress, dict[web3.types.Nonce, ethhelper.datatypes.txpool.TxpoolSnapshot]]: A dictionary that maps from account address to nonce to snapshot of the corresponding transaction in the queued pool.

class ethhelper.types.TxpoolContent(*, pending: dict[eth_typing.evm.ChecksumAddress, dict[web3.types.Nonce, ethhelper.datatypes.eth.Transaction]], queued: dict[eth_typing.evm.ChecksumAddress, dict[web3.types.Nonce, ethhelper.datatypes.eth.Transaction]])

A class representing the content of the transaction pool on a node.

pending: dict[eth_typing.evm.ChecksumAddress, dict[web3.types.Nonce, ethhelper.datatypes.eth.Transaction]]

A dictionary containing information about all pending transactions in the pool.

The keys are the transaction sender’s address and the values are another dictionary, where the keys are the nonces of the transactions and the values are the corresponding transactions.

queued: dict[eth_typing.evm.ChecksumAddress, dict[web3.types.Nonce, ethhelper.datatypes.eth.Transaction]]

A dictionary containing information about all queued transactions in the pool.

The keys are the transaction sender’s address and the values are another dictionary, where the keys are the nonces of the transactions and the values are the corresponding transactions.

class ethhelper.types.TxpoolContentFrom(*, pending: dict[web3.types.Nonce, ethhelper.datatypes.eth.Transaction], queued: dict[web3.types.Nonce, ethhelper.datatypes.eth.Transaction])

A class that represents the transactions in the transaction pool (txpool) from a specific address.

pending: dict[web3.types.Nonce, ethhelper.datatypes.eth.Transaction]: A dictionary of pending transactions from the specified address. The dictionary is indexed by the nonce of each transaction.

queued: dict[web3.types.Nonce, ethhelper.datatypes.eth.Transaction]: A dictionary of queued transactions from the specified address. The dictionary is indexed by the nonce of each transaction.