Ethereal

Ethereal is a lightweight wrapper around the web3.Web3 class that simplifies working with Ethereum smart contracts.

To use it, simply create a regular web3.Web3 instance and write w3 = Ethereal(w3). Then, you can use w3 as usual, but with additional methods accessible under the e property.

For example, you can call w3.e.get_abi("0x...") or w3.e.list_events("0x...", "Mint", "2023-01-01", "2023-02-14").

For more available methods, please refer to the ethereal.facade.EtherealFacade class.

Example

from web3.auto import w3
from ethereal import Ethereal
from ethereal import load_provider_from_uri

# If WEB3_PROVIDER_URI env is not set, uncomment the lines below
# w3 = Web3(load_provider_from_uri("https://alchemy.com/..."))

w3 = Ethereal(w3)

ADDRESS = "0xB0B195aEFA3650A6908f15CdaC7D92F8a5791B0B"
print(w3.e.list_events(ADDRESS))
# Lists event signatures for the contract at ADDRESS

events = w3.e.get_events(ADDRESS, "Transfer", "2023-01-01", "2023-02-14")
# Gets all Transfer events for the contract at ADDRESS between 2023-01-01 and 2023-02-14
print(events[:10])
class ethereal.facade.EtherealFacade(etherscan: Etherscan, web3: Web3, accounts: Accounts, cache: Cache, *args, **kwargs)

Bases: object

The main class containing Ethereal’s functionality.

get_block_by_timestamp(timestamp: int = True) → int

Get the block number for a given timestamp.

Parameters:

timestamp – The timestamp to look up.

get_abi(address: str, resolve_proxy: bool = True) → Dict[str, Any]

Get the ABI for a given address.

Parameters:

  • address – The address to look up.

  • resolve_proxy – Whether to resolve proxies. If true, the ABI for the implementation contract will be returned.

list_events(address: str, resolve_proxy: bool = True) → List[str]

Get a list of events for a given address.

Parameters:

  • address – The address to look up.

  • resolve_proxy – Whether to resolve proxies. If true, the ABI for the

get_contract(address: str, resolve_proxy: bool = True) → Contract

Get a contract for a given address.

Parameters:

  • address – The address to look up.

  • resolve_proxy – Whether to resolve proxies. If true, the ABI for the implementation contract will be used.

derive_account(seed_phrase: str, index: int, passphrase: str | None = None) → Account

Derive public and a private key from a seed phrase (Metamask or other bip 44)

Parameters:

  • seed_phrase – The seed phrase to use

  • index – The index to use

  • passphrase – The passphrase to use

Returns:

The pubic and private key

generate_seed_phrase(strength: int = 128) → str

Generate a mnemonic

Parameters:

strength – The strength of the mnemonic. Default = 128 (12 words)

Returns:

The mnemonic

get_events(address: str, event: str, from_time: int | str | datetime, to_time: int | str | datetime, argument_filters: Dict[str, Any] | None = None, resolve_proxy: bool = True)

Get events for a given address.

Parameters:

  • address – The address to look up.

  • event – The event name to look up.

  • from_time – The start time to look up. Can be a block number, a timestamp, a datetime, or a string with datetime.

  • to_time – The end time to look up. Can be a block number, a timestamp, a datetime , or a string with datetime.

  • argument_filters – A dictionary of argument names and values to filter by.

  • resolve_proxy – Whether to resolve proxies. If true, the ABI for the implementation contract will be used.