evm-scanner

EVM Scanner 🚀

A high-performance, industrial-grade EVM event scanning and indexing framework. Built for developers who need reliable, real-time access to blockchain data without the overhead of complex indexing solutions.

Features • Installation • Quick Start • Documentation • Contributing

🌟 Features

• ⛓️ Multi-Chain Native: Optimized for Ethereum, BSC, Polygon, Arbitrum, and any EVM-compatible network.
• 💾 Pluggable Storage: Choose your persistence layer—Memory (dev), Redis (performance), or PostgreSQL (durability).
• 🚀 High Performance:
  • Batch Processing: Efficient RPC call batching to minimize latency and costs.
  • Bloom Filter Support: Leverages node-level filtering for massive speed gains.
  • Worker Pool: Parallel output processing (sinks) for high-throughput environments.
• 🔌 Rich Ecosystem (Sinks): Stream data directly to Webhooks, Kafka, RabbitMQ, Redis, PostgreSQL, or flat files.
• 🛡️ Production Ready: Automatic reorg handling with configurable safety windows and cursor management.
• 💎 Human Readable: Built-in ABI decoding turns raw hex logs into structured JSON data automatically.

📦 Installation

Binary (Recommended)

Download the pre-compiled binary for your architecture from the Releases page.

Using Go

go install github.com/84hero/evm-scanner/cmd/scanner-cli@latest

From Source

git clone https://github.com/84hero/evm-scanner.git
cd evm-scanner
make build

🚀 Quick Start

1. Initialize Configuration

cp config.yaml.example config.yaml
cp app.yaml.example app.yaml

2. Run the CLI

# Start scanning based on app.yaml filters
./bin/scanner-cli

3. Docker (One-Liner)

docker-compose up -d

🛠 Usage Examples

CLI Mode (Standalone)

Define your filters in app.yaml:

filters:
  - description: "USDT Transfer Tracker"
    contracts: ["0xdAC17F958D2ee523a2206206994597C13D831ec7"]
    topics: ["0xddf252ad1be2c89b69c2b068fc378daa952ba7f163c4a11628f55a4df523b3ef"]
    abi: '[{"anonymous":false,"inputs":[{"indexed":true,"name":"from","type":"address"},...],"name":"Transfer","type":"event"}]'

SDK Mode (As a Library)

Explore our curated examples to see how to integrate evm-scanner into your stack:

import (
    "github.com/84hero/evm-scanner/pkg/scanner"
    "github.com/84hero/evm-scanner/pkg/rpc"
)

func main() {
    client, _ := rpc.NewClient(ctx, rpcCfg, 10)
    s := scanner.New(client, storage, scanCfg, filter)
    
    s.SetHandler(func(ctx context.Context, logs []types.Log) error {
        // Your custom business logic here
        return nil
    })
    
    s.Start(ctx)
}

⚙️ Configuration

The project uses two primary configuration files:

🏗 Supported Sinks (Outputs)

🛠 Development

We use Makefile for common tasks:

• make test: Run the test suite.
• make lint: Run code quality checks.
• make snapshot: Local build validation with GoReleaser.

🤝 Contributing

Contributions are what make the open source community such an amazing place to learn, inspire, and create. Any contributions you make are greatly appreciated.

1. Fork the Project
2. Create your Feature Branch (git checkout -b feature/AmazingFeature)
3. Commit your Changes (git commit -m 'Add some AmazingFeature')
4. Push to the Branch (git push origin feature/AmazingFeature)
5. Open a Pull Request

📧 Contact

• Telegram: @xNew4
• X (Twitter): @0xNew4

📄 License

Distributed under the MIT License. See LICENSE for more information.

Built with ❤️ for the Web3 Community.