erc20activity

ERC20 Activity Tracker

A drop-in, concurrent-safe Go service that tells you which tokens are “alive” on-chain right now—without hammering your node.

Why is this useful?

Use cases include:

• Portfolio dashboards that surface “hot” assets automatically
• Trading/arbitrage bots that filter for tokens with recent flow
• Whale-alert or analytics feeds that trigger on first activity

Features

• Real-time activity tracking – listens to the live block stream, flags every contract that fires a Transfer.
• Bloom-filter shortcut – skips blocks that cannot contain ERC-20 transfers before any RPC call is made, reducing load on your node.
• Thread-safe & race-free – proven with go test -race.
• Configurable “freshness” window – treat tokens as stale after X minutes, prune every Y minutes.
• Pluggable logging – drop in any slog.Handler or custom Logger implementation.
• Graceful shutdown – one context.CancelFunc stops the world without leaks.

Installation

go get github.com/your-repo/erc20activity   # replace with your actual module path

Quick Start

Below is a minimal example that wires the tracker into a running program. Replace the mock implementations with calls to your own Ethereum client (e.g., ethclient.Client from go-ethereum).

package main

import (
    "context"
    "fmt"
    "log"
    "math/big"
    "time"

    "github.com/ethereum/go-ethereum/core/types"
    "github.com/your-repo/erc20activity" // update with your module path
)

// -----------------------------------------------------------------
// Mock plumbing – swap these with real blockchain calls in production.
// -----------------------------------------------------------------

var newBlockEventer = make(chan *types.Block) // incoming blocks

func logFetcher(ctx context.Context, blockNumber uint64) ([]types.Log, error) {
    // return ethClient.FilterLogs(ctx, ethereum.FilterQuery{FromBlock: bn, ToBlock: bn})
    fmt.Printf("Fetching logs for block %d\n", blockNumber)
    return nil, nil
}

func bloomFilterTest(bloom types.Bloom) bool {
    // return types.BloomLookup(bloom, erc20activity.ERC20TransferTopic)
    return true
}

// -----------------------------------------------------------------
// Main
// -----------------------------------------------------------------

func main() {
    ctx, cancel := context.WithCancel(context.Background())
    defer cancel()

    cfg := &erc20activity.Config{
        NewBlockEventer:      newBlockEventer,
        LogFetcher:           logFetcher,
        BloomFilterTest:      bloomFilterTest,
        TokenStaleDuration:   15 * time.Minute,
        ExpiryCheckFrequency: 5 * time.Minute,
        Logger:               log.Default(),
    }

    tracker, err := erc20activity.NewTracker(ctx, cfg)
    if err != nil {
        log.Fatalf("tracker init: %v", err)
    }

    // Simulate blocks
    go func() {
        for i := uint64(0); ; i++ {
            select {
            case newBlockEventer <- types.NewBlockWithHeader(&types.Header{Number: big.NewInt(int64(i))}):
                time.Sleep(10 * time.Second)
            case <-ctx.Done():
                return
            }
        }
    }()

    // Dump active tokens every 30 s
    for {
        select {
        case <-time.After(30 * time.Second):
            for _, t := range tracker.ActiveTokens() {
                fmt.Println(t.Hex())
            }
        case <-ctx.Done():
            return
        }
    }
}

Configuration

How it works under the hood

┌ newBlockEventer (chan *Block) ┐
            │
            ▼
┌────── blockProcessor (1 goroutine) ──────┐
│  • bloom pre-filter                      │
│  • fetch logs only when necessary        │
└──────────────────────────────────────────┘
            │ writes
            ▼
┌────── lastSeen map (protected by RWMutex) ──────┐
│ tokenAddr → lastActivityTimestamp              │
└────────────────────────────────────────────────┘
        ▲                 │
        │ reads           ▼
ActiveTokens()       pruner (every N min)
(many callers)        – purge stale entries

Testing

go test -v -race ./...

Contributing

Pull requests and issues are warmly welcome. Please include:

1. A clear description of the change or bug.
2. Unit tests where reasonable.
3. go vet, go fmt, and go test -race passing locally.

License

MIT