fetcher.events

Module for fetching and caching events from web3.

The main class of this module is EventsService. It is used for retrieving events from web3 and storing them in cache so that subsequent requests are returned from cache.

It also supports quick incremental fetches. For example, if you fetched ERC20 Transfer events from block 10_000 to block 20_000, then a subsequent request from block 15_000 to block 21_000 will return 15_000 - 20_000 from cache and fetch only 20_000 - 21_000 from web3 and save to cache. A subsequent request for blocks 15_000 - 21_000 will read everything from cache.

Additionally, it supports nesting of the argument filters. Imagine you

  1. Fetched all Transfer events from blocks 2000 - 4000

  2. Fetched Transfer events with filter {"from": "0x1234..."} for blocks 4000 - 6000

  3. Fetched Transfer events with filter {"to": "0x5678..."} for blocks 6000 - 8000

Now when you query events with filter {"from": "0x1234...", "to": "0x5678..."} for blocks 2000 - 8000 EventsService is smart enough to figure out that all events are already in cache and serve the cached result.

Example

from web3cat.fetcher.events import EventsService
from web3cat.fetcher.erc20_metas import ERC20MetasService

erc20 = ERC20MetasService.create()
dai = erc20.get("Dai")

service = EventsService.create()
events = service.get_events(
    dai.contract.events.Transfer, from_block=15830000, to_block=15840100
)
class web3cat.fetcher.events.EventsService(events_repo: EventsRepo, events_indices_repo: EventsIndicesRepo, blocks_service: BlocksService, **kwargs)

Bases: Core

Service for fetching contract events.

This service fetches contract events from web3, cache them, and read from the cache on subsequent calls.

Request/Response flow

           +---------------+              +-------+ +-------------------+ +-------------+
           | EventsService |              | Web3  | | EventsIndicesRepo | | EventsRepo  |
           +---------------+              +-------+ +-------------------+ +-------------+
-----------------  |                          |               |                  |
| Request events |-|                          |               |                  |
|----------------| |                          |               |                  |
                   |                          |               |                  |
                   | Request index            |               |                  |
                   |----------------------------------------->|                  |
                   |                          |               |                  |
                   | Fetch missing events     |               |                  |
                   |------------------------->|               |                  |
                   |                          |               |                  |
                   | Store missing events     |               |                  |
                   |------------------------------------------------------------>|
                   |                          |               |                  |
                   | Fetch all events         |               |                  |
                   |------------------------------------------------------------>|
  ---------------  |                          |               |                  |
  | Response     |-|                          |               |                  |
  |--------------| |                          |               |                  |
                   |                          |               |                  |
Parameters:

  • events_repo – Repo of events

  • events_indices_repo – Repo of events_indices

  • kwargs – Args for the fetcher.core.Core

static create(**kwargs) → EventsService

Create an instance of EventsService

Parameters:

kwargs – Args for the fetcher.core.Core

Returns:

An instance of EventsService

get_events(event: ContractEvent, from_block: int, to_block: int, argument_filters: Optional[Dict[str, Any]] = None) → List[Event]

Get events specified by parameters.

Parameters:

  • event – class:web3.contract.ContractEvent specifying contract and event_name.

  • from_block – fetch events from this block (inclusive)

  • to_block – fetch events from this block (non-inclusive)

  • argument_filters – Additional filters for events search. Example: {"from": "0xfa45..."}

Returns:

A list of fetched events

Exceptions:

See prefetch_events()

prefetch_events(event: ContractEvent, from_block: int, to_block: int, argument_filters: Optional[Dict[str, Any]] = None)

Fetch events specified by parameters and save them to cache.

Parameters:

  • event – class:web3.contract.ContractEvent specifying contract and event_name.

  • from_block – fetch events from this block (inclusive)

  • to_block – fetch events from this block (non-inclusive)

  • argument_filters – Additional filters for events search. Example: {"from": "0xfa45..."}

Exceptions:

This method tries to fetch all events from from_block to to_block at once. More often than not, rpc endpoint will block such attempts and ask to use a narrower block interval for fetch. In this case, the interval is halved, and fetch is retried. This is repeated until success.

However, if at some point the interval is less than fetcher.events_indices.constants.BLOCKS_PER_BIT, RuntimeError is raised.

clear_cache()

Delete all cached entries

class web3cat.fetcher.events.Event(chain_id: int, block_number: int, transaction_hash: str, log_index: int, address: str, event: str, args: Dict[str, Any])

Bases: object

Event represents an event log on Ethereum blockchain.

chain_id: int

Ethereum chain_id

block_number: int

The block this event appeared in

transaction_hash: str

The hash of the transaction this event appeared in

log_index: int

The log number for this event inside the transaction

address: str

The contract address this event appeared in (lowercase)

event: str

Event name

args: Dict[str, Any]

Event arguments (hexes are lowercase)

static from_row(row: Tuple[int, int, str, int, str, str, str]) → Event

Deserialize from web3cat.database row

Parameters:

row – database row

to_row() → Tuple[int, int, str, int, str, str, str]

Serialize to database row

Returns:

database row

to_dict() → Dict[str, Any]

Convert Event to dict

static from_dict(dct: Dict[str, Any])

Create Event from dict

matches_filter(event_filter: Optional[Dict[str, Any]]) → bool

Checks if Event matches given event event_filter.

Parameters:

event_filter – Event event_filter

Returns:

True if matches, False otherwise

class web3cat.fetcher.events.EventsRepo(rpc: Optional[str] = None, cache_path: Optional[str] = None, block_grid_step: int = 1000, w3: Optional[Web3] = None, conn: Optional[Connection] = None)

Bases: Core

Reading and writing Event to database.

find(event: str, address: str, argument_filters: Optional[Dict[str, Any]] = None, from_block: int = 0, to_block: int = 4294967295) → Iterator[Event]

Find all events in the database.

Parameters:

  • event – Event name

  • address – Contract address

  • argument_filters – an additional filter with keys being event fieds (AND query) and values are filter values (list of values for OR query)

  • from_block – starting from this block (inclusive)

  • to_block – ending with this block (non-inclusive)

Returns:

Iterator over found events

save(events: List[Event])

Save a set of events into the database.

Parameters:

events – List of events to save

purge()

Clear all database entries