Building an ERC20 Tracker with Hemera in Under 30 Minutes

Prerequisites

• Hemera Indexer: Set up the Hemera Indexer by following the installation instructions in the Hemera documentation.
• Development Environment:
  • Python Environment: Ensure Python is installed on your system.
  • IDE/Text Editor: Use Visual Studio Code or any other code editor.
  • PostgreSQL DB: Hemera uses Postgres as a data output.
• Basic Knowledge of Python and Solidity: Familiarity with Ethereum and ERC20 contracts is recommended.

Step 1: Setting Up the Hemera Indexer

Step 2: Writing User Defined Functions

#!/usr/bin/env python3
# -*- coding: utf-8 -*-
from dataclasses import dataclass
from indexer.domain import FilterData

@dataclass
class ERC721TokenMint(FilterData):
    address: str
    token_address: str
    token_id: int
    block_number: int
    block_timestamp: int
    transaction_hash: str
    log_index: int
                

#!/usr/bin/env python3
# -*- coding: utf-8 -*-
from sqlalchemy import Column, Index, PrimaryKeyConstraint, func, text
from sqlalchemy.dialects.postgresql import BIGINT, BOOLEAN, BYTEA, INTEGER, NUMERIC, TIMESTAMP
from common.models import HemeraModel, general_converter

class ERC721TokenMint(HemeraModel):
    tablename = "erc721_token_mint"
    address = Column(BYTEA)
    token_address = Column(BYTEA, primary_key=True)
    token_id = Column(NUMERIC(100), primary_key=True)
    block_number = Column(BIGINT)
    block_timestamp = Column(TIMESTAMP)
    transaction_hash = Column(BYTEA)
    log_index = Column(INTEGER)
    create_time = Column(TIMESTAMP, server_default=func.now())
    update_time = Column(TIMESTAMP, server_default=func.now())
    reorg = Column(BOOLEAN, server_default=text("false"))
    table_args = (PrimaryKeyConstraint("token_address", "token_id"),)

    @staticmethod
    def model_domain_mapping():
        return [{
            "domain": "ERC721TokenMint",
            "conflict_do_update": True,
            "update_strategy": None,
            "converter": general_converter,
        }]

Index("erc721_token_mint_address_id_index",
    ERC721TokenMint.token_address,
    ERC721TokenMint.token_id,
)
    

from typing import List
from indexer.domain.log import Log
from indexer.domain.token_transfer import TokenTransfer
from indexer.jobs.base_job import Collector, FilterTransactionDataJob
from indexer.utils.abi_setting import ERC20_TRANSFER_EVENT
from common.utils.web3_utils import ZERO_ADDRESS

def _filter_erc20_transfer_event(logs: List[Log]) -> List[TokenTransfer]:
    token_transfers = []
    for log in logs:
        if log.topic0 == ERC20_TRANSFER_EVENT.get_signature():
            decoded_data = ERC20_TRANSFER_EVENT.decode_log(log)
            if decoded_data["from"] != ZERO_ADDRESS:
                token_transfers.append(
                    ERC20TokenTransfer(
                        address=decoded_data["to"],
                        token_address=log.address,
                        value=decoded_data["value"],
                        block_timestamp=log.block_timestamp,
                        block_number=log.block_number,
                        transaction_hash=log.transaction_hash,
                        log_index=log.log_index,
                    )
                )
    return token_transfers

Step 3: Running the System: Detecting Jobs and Executing UDFs

python hemera.py stream \
--provider-uri https://ethereum.publicnode.com \
--postgres-url postgresql://devuser:devpassword@localhost:5432/hemera_indexer \
--output jsonfile://output/eth_blocks_20000001_20010000/json,csvfile://output/hemera_indexer/csv,postgresql://devuser:devpassword@localhost:5432/eth_blocks_20000001_20010000 \
--start-block 20000001 \
--end-block 20010000 \
--entity-types EXPLORER_BASE \
--block-batch-size 200 \
--batch-size 200 \
--max-workers 32
                

Command Breakdown:

• --provider-uri: Specifies the Ethereum node provider to fetch blockchain data.
• --postgres-url: Connection string for the PostgreSQL database where the data will be stored.
• --output: Defines output formats (JSON, CSV, and PostgreSQL in this case) and their destinations.
• --start-block and --end-block: The range of blocks to process.
• --entity-types: Specifies the types of entities to process (EXPLORER_BASE in this case).
• --block-batch-size and --batch-size: Control the processing batch size for blocks and transactions.
• --max-workers: Sets the number of worker threads to parallelize the job.

Testing Output with PostgreSQL

• Check the table structure:
• d erc20_token_transfer;
• View the first 10 rows:
• SELECT * FROM erc20_token_transfer LIMIT 10;
• Count the total number of transfers:
• SELECT COUNT(*) FROM erc20_token_transfer;

GUI-Based Database Inspection

• pgAdmin: A comprehensive PostgreSQL management tool.
• DBeaver: A multi-platform database GUI client.
• TablePlus: A lightweight and modern database management app.

Integrating a Frontend with the Application

1. Expose APIs: Use a backend framework like FastAPI or Express.js to build APIs that query the database. Example endpoints:
   1. /transfers: Fetch paginated token transfers.
   2. /transfer/:hash: Get transfer details by transaction hash.
2. Database Design Considerations:
   1. Optimize database queries for frontend requirements.
   2. Create indexes on frequently queried fields like transaction_hash and block_number.
3. Frontend Framework: Use React.js or Next.js to create dashboards displaying transfer data. Example components:
   1. A table for token transfers.
   2. A chart for transfer trends over time.

Ideas for Extensions

• Custom Alerts: Notify users when large transfers occur.
• Token Analytics: Visualize token transfer trends and volume.
• Real-Time Updates: Add live tracking for token transfers using WebSocket APIs.

Join the Builder Program