fetcher.balances

Module for fetching and caching ETH balances from web3.

The main class of this module is BalancesService. It is used for fetching ETH balances from web3 and caching them for subsequent calls.

Example

from web3cat.fetcher.balances import BalancesService

addresses = [
    "0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045",
    "0x88e6a0c2ddd26feeb64f039a2c41296fcb3f5640",
]
blocks = [15700000, 15800000]
service = BalancesService.create()
response = service.get_balances(addresses, blocks)
# => going for web3 rpc

response = service.get_balances(addresses, blocks)
# => serving from cache

response = service.get_balance(addresses[0], blocks[0])
# => serving from cache

class web3cat.fetcher.balances.BalancesService(balances_repo: BalancesRepo, **kwargs)

Bases: Core

Service for getting and caching ETH balances.

Since there’s no easy way of getting ETH balance deltas from Web3, this service queries and caches ETH balance for every desired date and address.

Note

It’s not as effective as querying token balances, based on fetching Transfer events (deltas) in batches. Use it with caution.

Request/Response flow

        +-----------------+                +-------+ +---------------+
        | BalancesService |                | Web3  | | BalancesRepo  |
        +-----------------+                +-------+ +---------------+
---------------  |                             |             |
| Request call |-|                             |             |
|--------------| |                             |             |
                 |                             |             |
                 | Find Balance                |             |
                 |------------------------------------------>|
                 |                             |             |
                 | If not found: call Web3     |             |
                 |---------------------------->|             |
                 |                             |             |
                 | Save response               |             |
                 |------------------------------------------>|
    -----------  |                             |             |
    | Response |-|                             |             |
    |----------| |                             |             |
                 |                             |             |

Parameters:

balances_repo – An instance of BalancesRepo
kwargs – Args for the fetcher.core.Core class

static create(**kwargs) → BalancesService

Create an instance of BalancesService

Parameters:: kwargs – Args for the fetcher.core.Core class
Returns:: An instance of BalancesService

get_balances(addresses: List[str], blocks: List[int]) → List[Balance]

Get ETH balances for a list of blocks and addresses.

Parameters:

addresses – a list of addresses for ETH balances
blocks – a list of blocks for ETH balances

Returns:

A list of Balance for addresses and blocks. The size of a list = len(addresses) * len(blocks)

get_balance(address: str, block_number: int) → Balance

Get ETH balance for a block and an address.

Parameters:

address – The address for the ETH balance
block_number – The block number for which the ETH balance is fetched

Returns:

ETH balance

clear_cache(): Delete all cached ETH balances

class web3cat.fetcher.balances.Balance(chain_id: int, block_number: int, address: str, balance: int)

Bases: object

Balance represents a snapshot of the ETH balance on Ethereum blockchain.

chain_id: int: Ethereum chain_id

block_number: int: The block number of the balance snapshot

address: str: The address for the ETH balance (always stored lowercase)

balance: int: ETH balance

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

Deserialize from web3cat.database row

Parameters:: row – database row

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

Serialize to database row

Returns:: database row

static from_dict(dct: Dict[str, Any]): Create Balance from dctict

to_dict() → Dict[str, Any]: Convert Balance to dict

class web3cat.fetcher.balances.BalancesRepo(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 Balance to database cache.

find(addresses: List[str], from_block: int = 0, to_block: int = 4294967295) → Iterator[Balance]

Find all balances in the database cache.

Parameters:

addresses – Contract / EOA addresses
from_block – starting from this block (inclusive)
to_block – ending with this block (non-inclusive)

Returns:

An iterator over found balances

save(balances: List[Balance])

Save a list of balances into the database cache.

Parameters:: balances – List of balances to save

purge(): Clear all balances entries from the database cache.