Public API

Typed

class alysis.Node(*, root_balance_wei: int, evm_version: EVMVersion = EVMVersion.PRAGUE, chain_id: int = 107118521969011, net_version: int = 1, auto_mine_transactions: bool = True)

An Ethereum node maintaining its own local chain.

If auto_mine_transactions is True, a new block is mined after every successful transaction.

delete_filter(filter_id: int) → None

Deletes the filter with the given identifier.

disable_auto_mine_transactions() → None

Turns automining off.

enable_auto_mine_transactions() → None

Turns automining on and mines a new block.

eth_block_number() → int

Returns the number of most recent block.

eth_call(params: EthCallParams, block: int | BlockLabel) → bytes

Executes a new message call immediately without creating a transaction on the blockchain.

If the transaction is invalid, raises ValidationError. If the transaction is sent to the EVM but is reverted during execution, raises TransactionReverted. If there were other problems with the transaction, raises TransactionFailed.

eth_chain_id() → int

Returns the chain ID used for signing replay-protected transactions.

eth_estimate_gas(params: EstimateGasParams, block: int | BlockLabel) → int

Generates and returns an estimate of how much gas is necessary to allow the transaction to complete. The transaction will not be added to the blockchain.

If the transaction is invalid, raises ValidationError. If the transaction is sent to the EVM but is reverted during execution, raises TransactionReverted. If there were other problems with the transaction, raises TransactionFailed.

eth_gas_price() → Amount

Returns an estimate of the current price per gas in wei.

eth_get_balance(address: Address, block: int | BlockLabel) → int

Returns the balance (in wei) of the account of given address.

eth_get_block_by_hash(block_hash: BlockHash, *, with_transactions: bool) → BlockInfo

Returns information about a block by hash.

Raises BlockNotFound if the requested block does not exist.

eth_get_block_by_number(block: int | BlockLabel, *, with_transactions: bool) → BlockInfo

Returns information about a block by block number.

Raises BlockNotFound if the requested block does not exist.

eth_get_code(address: Address, block: int | BlockLabel) → bytes

Returns code of the contract at a given address.

eth_get_filter_changes(filter_id: int) → list[LogEntry] | list[TxHash] | list[BlockHash]

Polling method for a filter, which returns an array of logs which occurred since last poll.

Note

This method will not return the events that happened before the filter creation, even if they satisfy the filter predicate. Call eth_get_filter_logs() to get those.

eth_get_filter_logs(filter_id: int) → list[LogEntry]

Returns an array of all logs matching filter with given id.

eth_get_logs(params: FilterParams | FilterParamsEIP234) → list[LogEntry]

Returns an array of all logs matching a given filter object.

eth_get_storage_at(address: Address, slot: int, block: int | BlockLabel) → bytes

Returns the value from a storage position at a given address.

eth_get_transaction_by_hash(transaction_hash: TxHash) → TxInfo

Returns the information about a transaction requested by transaction hash.

Raises TransactionNotFound if the transaction with this hash has not been included in a block yet.

eth_get_transaction_count(address: Address, block: int | BlockLabel) → int

Returns the number of transactions sent from an address.

eth_get_transaction_receipt(transaction_hash: TxHash) → TxReceipt

Returns the receipt of a transaction by transaction hash.

Raises TransactionNotFound if the transaction with this hash has not been included in a block yet.

eth_new_block_filter() → int

Creates a filter in the node, to notify when a new block arrives. Returns the identifier of the created filter.

eth_new_filter(params: FilterParams) → int

Creates a filter object, based on filter options, to notify when the state changes (logs). Returns the identifier of the created filter.

eth_new_pending_transaction_filter() → int

Creates a filter in the node, to notify when new pending transactions arrive. Returns the identifier of the created filter.

eth_send_raw_transaction(raw_transaction: bytes) → TxHash

Attempts to add a signed RLP-encoded transaction to the current block. Returns the transaction hash on success.

If the transaction is invalid, raises ValidationError. If the transaction is sent to the EVM but is reverted during execution, raises TransactionReverted. If there were other problems with the transaction, raises TransactionFailed.

mine_block(timestamp: None | int = None) → None

Mines a new block containing all the pending transactions.

If timestamp is not None, sets the new block’s timestamp to the given value.

net_version() → int

Returns the current network id.

root_private_key: bytes

The private key of the funded address created with the chain.

class alysis.EVMVersion(value)

Supported EVM versions. Some may not be available depending on the compiler version.

BERLIN = 'berlin'

Berlin fork, Apr 15, 2021.

BYZANTIUM = 'byzantium'

Byzantium fork, Oct 16, 2017.

CANCUN = 'cancun'

Cancun fork, Mar 13, 2024.

CONSTANTINOPLE = 'constantinople'

Constantinople fork, Feb 28, 2019.

HOMESTEAD = 'homestead'

Homestead fork, Mar 14, 2016.

ISTANBUL = 'istanbul'

Istanbul fork, Dec 8, 2019.

LONDON = 'london'

London fork, Aug 5, 2021.

PARIS = 'paris'

Paris fork, Sep 15, 2022.

PRAGUE = 'prague'

Prague fork, May 7, 2025.

SHANGHAI = 'shanghai'

Shanghai fork, Apr 12, 2023.

SPURIOUS_DRAGON = 'spuriousDragon'

Spurious Dragon fork, Nov 22, 2016.

TANGERINE_WHISTLE = 'tangerineWhistle'

Tangerine Whistle fork, Oct 18, 2016.

RPC

class alysis.RPCNode(node: Node)

A wrapper for Node exposing an RPC-like interface, taking and returning JSON-compatible data structures.

rpc(method_name: str, *params: None | bool | int | float | str | Sequence[JSON] | Mapping[str, JSON]) → None | bool | int | float | str | Sequence[JSON] | Mapping[str, JSON]

Makes an RPC request to the chain and returns the result on success, or raises ethereum_rpc.RPCError on failure.

Exceptions

class alysis.ValidationError

Invalid values of some of the arguments.

class alysis.BlockNotFound

Requested block cannot be found.

class alysis.TransactionNotFound

Requested transaction cannot be found.

class alysis.FilterNotFound

Requested filter cannot be found.

class alysis.TransactionFailed

Transaction could not be executed.

class alysis.TransactionReverted

Transaction was partially executed, but had to be reverted.