Public API¶

Schema¶

Primitives¶

class ethereum_rpc.Amount(wei: int)[source]¶

Represents a sum in the chain’s native currency.

Can be subclassed to represent specific currencies of different networks (ETH, MATIC etc). Arithmetic and comparison methods perform strict type checking, so currency objects of different types cannot be compared or added to each other.

as_ether() → float[source]¶: Returns the amount in the main currency unit.

as_gwei() → float[source]¶: Returns the amount in gwei.

as_wei() → int[source]¶: Returns the amount in wei.

classmethod ether(value: float) → CustomAmount[source]¶: Creates a sum from the amount in the main currency unit.

classmethod gwei(value: float) → CustomAmount[source]¶: Creates a sum from the amount in gwei (10^(-9) of the main unit).

classmethod wei(value: int) → CustomAmount[source]¶: Creates a sum from the amount in wei (10^(-18) of the main unit).

class ethereum_rpc._typed_wrappers.CustomAmount¶: A type derived from Amount.

class ethereum_rpc.Address(value: bytes)[source]¶

Represents an Ethereum address.

Can be subclassed to represent specific addresses of different networks. Comparison methods perform strict type checking, so objects of different types cannot be compared to each other.

classmethod from_hex(address_str: str) → CustomAddress[source]¶: Creates the address from a hex representation (with or without the 0x prefix, checksummed or not).

property checksum: str¶: Retunrs the checksummed hex representation of the address.

class ethereum_rpc._typed_wrappers.CustomAddress¶: A type derived from Address.

ethereum_rpc.Block¶: alias of int | BlockLabel

class ethereum_rpc.BlockLabel(value)[source]¶

Block label.

EARLIEST = 'earliest'¶: The earliest/genesis block.

FINALIZED = 'finalized'¶: The latest finalized block.

LATEST = 'latest'¶: The latest mined block.

PENDING = 'pending'¶: The current pending block.

SAFE = 'safe'¶: The latest safe head block.

class ethereum_rpc.TxHash(value: bytes)[source]¶: Transaction hash (32 bytes).

class ethereum_rpc.BlockHash(value: bytes)[source]¶: Block hash (32 bytes).

class ethereum_rpc.LogTopic[source]¶: Log topic (32 bytes).

class ethereum_rpc.TrieHash(value: bytes)[source]¶: Trie hash (32 bytes).

class ethereum_rpc.UnclesHash(value: bytes)[source]¶: Hash of block uncles (32 bytes).

class ethereum_rpc.BlockNonce(value: bytes)[source]¶: Block nonce (8 bytes).

class ethereum_rpc.LogsBloom(value: bytes)[source]¶: Bloom filter for logs (256 bytes).

Inputs¶

Transaction fields for eth_call.

data: None | bytes = None¶: The associated data of the transaction.

from_: None | Address = None¶: The transaction sender. May matter for some contract methods that depend on msg.sender.

gas: None | int = None¶: Gas provided for the transaction execution. eth_call consumes zero gas, but this parameter may be needed by some executions.

gas_price: None | Amount = None¶: The gas price.

to: Address¶: The transaction destination (the contract address).

value: None | Amount = None¶: The associated funds.

Transaction fields for eth_estimateGas.

data: None | bytes = None¶: The associated data of the transaction.

from_: Address¶: The transaction sender.

gas: None | int = None¶: Gas provided for the transaction execution.

gas_price: None | Amount = None¶: The gas price.

nonce: None | int = None¶: The transaction nonce.

to: None | Address = None¶: The destination of the transaction. None if it’s a deployment transaction.

value: None | Amount = None¶: The associated funds.

Filter parameters for eth_getLogs or eth_newFilter.

address: None | Address | tuple[Address, ...] = None¶: Filter by one or several source addresses.

from_block: None | int | BlockLabel = None¶: The starting block of the filter.

to_block: None | int | BlockLabel = None¶: The ending block of the filter (inclusive).

topics: None | tuple[None | LogTopic | tuple[LogTopic, ...], ...] = None¶: Log topics.

Alternative filter parameters for eth_getLogs (introduced in EIP-234).

address: None | Address | tuple[Address, ...] = None¶: Filter by one or several source addresses.

block_hash: BlockHash¶: The hash of the block to which the filter is applied.

topics: None | tuple[None | LogTopic | tuple[LogTopic, ...], ...] = None¶: Log topics.

class ethereum_rpc.Type2Transaction(chain_id: int, value: Amount, gas: int, max_fee_per_gas: Amount, max_priority_fee_per_gas: Amount, nonce: int, to: None | Address = None, data: None | bytes = None)[source]¶

An EIP-1559 (dynamic fee) transaction.

chain_id: int¶: Chain ID.

data: None | bytes = None¶: The associated data of the transaction.

gas: int¶: Gas limit for the transaction.

max_fee_per_gas: Amount¶: Maximum total fee the sender is willing to pay.

max_priority_fee_per_gas: Amount¶: Maximum miner fee (in addition to the base fee) the sender is willing to pay.

nonce: int¶: The transaction nonce.

to: None | Address = None¶: The destination of the transaction. None if it’s a deployment transaction.

value: Amount¶: Associated funds.

Outputs¶

class ethereum_rpc.TxReceipt[source]¶

Transaction receipt.

block_hash: BlockHash¶: Hash of the block including this transaction.

block_number: int¶: Block number including this transaction.

contract_address: None | Address¶: If it was a successful deployment transaction, contains the address of the deployed contract.

cumulative_gas_used: int¶: The total amount of gas used when this transaction was executed in the block.

effective_gas_price: Amount¶: The actual value per gas deducted from the sender’s account.

from_: Address¶: Address of the sender.

gas_used: int¶: The amount of gas used by the transaction.

logs: tuple[LogEntry, ...]¶: An array of log objects generated by this transaction.

logs_bloom: LogsBloom¶: Bloom filter for light clients to quickly retrieve related logs.

status: int¶: 1 if the transaction was successful, 0 otherwise.

property succeeded: bool¶: True if the transaction succeeded.

to: None | Address¶: Address of the receiver. None when the transaction is a contract creation transaction.

transaction_hash: TxHash¶: Hash of the transaction.

transaction_index: int¶: Integer of the transaction’s index position in the block.

type_: int¶: Transaction type: 0 for legacy transactions, 2 for EIP1559 transactions.

class ethereum_rpc.BlockInfo[source]¶

Block info.

base_fee_per_gas: Amount¶: Base fee per gas in this block.

difficulty: int¶: Block’s difficulty.

extra_data: bytes¶: The “extra data” field of this block.

gas_limit: int¶: Block’s gas limit.

gas_used: int¶: Gas used for the block.

hash_: None | BlockHash¶: Block hash. None for pending blocks.

logs_bloom: None | LogsBloom¶: The bloom filter for the logs of the block. None for pending blocks.

miner: None | Address¶: Block’s miner. None for pending blocks.

nonce: None | BlockNonce¶: Block’s nonce. None for pending blocks.

number: int¶: Block number.

parent_hash: BlockHash¶: Parent block’s hash.

receipts_root: TrieHash¶: The root of the receipts trie of the block.

sha3_uncles: UnclesHash¶: SHA3 of the uncles data in the block.

size: int¶: Block size.

state_root: TrieHash¶: The root of the final state trie of the block.

timestamp: int¶: Block’s timestamp.

total_difficulty: None | int¶: Block’s totat difficulty. None for pending blocks.

transactions: tuple[TxInfo, ...] | tuple[TxHash, ...]¶: A list of transaction hashes in this block, or a list of details of transactions in this block, depending on what was requested.

transactions_root: TrieHash¶: The root of the transaction trie of the block.

uncles: tuple[BlockHash, ...]¶: Array of uncle hashes.

class ethereum_rpc.TxInfo[source]¶

Transaction info.

block_hash: None | BlockHash¶: The hash of the block this transaction belongs to. None for pending transactions.

block_number: int¶: The number of the block this transaction belongs to. May be a pending block.

from_: Address¶: Transaction sender.

gas: int¶: Gas used by the transaction.

gas_price: Amount¶: Gas price used by the transaction.

hash_: TxHash¶: Transaction hash.

input_: None | bytes¶: The data sent along with the transaction.

max_fee_per_gas: None | Amount¶: maxFeePerGas value specified by the sender. Only for EIP1559 transactions.

max_priority_fee_per_gas: None | Amount¶: maxPriorityFeePerGas value specified by the sender. Only for EIP1559 transactions.

nonce: int¶: Transaction nonce.

r: int¶: ECDSA signature r.

s: int¶: ECDSA signature s.

to: None | Address¶: Transaction recipient. None when it’s a contract creation transaction.

transaction_index: None | int¶: Transaction index. None for pending transactions.

type_: int¶: Transaction type: 0 for legacy transactions, 2 for EIP1559 transactions.

v: int¶: ECDSA recovery id.

value: Amount¶: Associated funds.

class ethereum_rpc.LogEntry[source]¶

Log entry metadata.

address: Address¶: The contract address from which this log originated.

block_hash: BlockHash¶: Hash of the block where this log was in.

block_number: int¶: The block number where this log was.

data: bytes¶: ABI-packed non-indexed arguments of the event.

log_index: int¶: Log’s position in the block.

removed: bool¶: True if log was removed, due to a chain reorganization. False if it is a valid log.

topics: tuple[LogTopic, ...]¶: Values of indexed event fields. For a named event, the first topic is the event’s selector.

transaction_hash: TxHash¶: Hash of the transactions this log was created from.

transaction_index: int¶: Transaction’s position in the block.

RPC errors¶

class ethereum_rpc.ErrorCode¶

NewType creates simple unique types with almost zero runtime overhead. NewType(name, tp) is considered a subtype of tp by static type checkers. At runtime, NewType(name, tp) returns a dummy callable that simply returns its argument. Usage:

UserId = NewType('UserId', int)

def name_by_id(user_id: UserId) -> str:
    ...

UserId('user')          # Fails type check

name_by_id(42)          # Fails type check
name_by_id(UserId(42))  # OK

num = UserId(5) + 1     # type: int

alias of int

class ethereum_rpc.RPCError(code: ErrorCode, message: str, data: None | bytes = None)[source]¶

Bases: Exception

A general problem with fulfilling the request at the provider’s side.

This means the provider sent a correct response with an error code and possibly some associated data ("error": {"code": ..., "message": ..., "data": ...} sub-dictionary in the RPC response).

classmethod with_code(code: RPCErrorCode, message: str, data: None | bytes = None) → RPCError[source]¶: Creates this error given a known error code.

code: ErrorCode¶: The error type.

data: None | bytes = None¶: The associated data (if any).

message: str¶: The associated message.

property parsed_code: None | RPCErrorCode¶: If the error code is known, returns the corresponding enum entry.

class ethereum_rpc.RPCErrorCode(value)[source]¶

Standard RPC error codes returned by providers.

EXECUTION_ERROR = 3¶: Contract transaction failed during execution. See the data for details.

INTERNAL_ERROR = -32603¶: Internal JSON-RPC error.

INVALID_PARAMETER = -32602¶: Invalid method parameter(s).

INVALID_REQUEST = -32600¶: The JSON sent is not a valid Request object.

METHOD_NOT_FOUND = -32601¶: The method does not exist / is not available.

PARSE_ERROR = -32700¶: Invalid JSON was received by the server. An error occurred on the server while parsing the JSON text.

SERVER_ERROR = -32000¶: Reserved for implementation-defined server-errors. See the message for details.

Serialization¶

class ethereum_rpc.JSON¶: A JSON-ifiable object (bool, int, float, str, None, iterable of JSON, or mapping of str to JSON).

ethereum_rpc.structure(structure_into: type[_T], obj: None | bool | int | float | str | Sequence[JSON] | Mapping[str, JSON]) → _T[source]¶: Structures incoming JSON data into the given Ethereum RPC type. Raises compages.StructuringError on failure.

ethereum_rpc.unstructure(obj: Any, unstructure_as: Any | None = None) → None | bool | int | float | str | Sequence[JSON] | Mapping[str, JSON][source]¶: Unstructures a given Ethereum RPC entity into a JSON-serializable value. Raises compages.UntructuringError on failure.

Keccak¶

ethereum_rpc.keccak(data: bytes) → bytes[source]¶: Calculates Keccak-256 hash of the given data.