cypher_substreams Substreams modules

This package was initialized via substreams init, using the evm-minimal template.

Overview

This substream monitors blockchain transactions in real-time, specifically designed to track incoming transactions to specified addresses. It supports both native ETH transfers and ERC20 token transfers.

Features

• Live Monitoring: Continuously monitors blockchain data for incoming transactions
• Address Filtering: Filter transactions by from and to addresses
• ERC20 Support: Detects ERC20 token transfers and extracts relevant data
• Comprehensive Logging: Detailed logging for debugging and monitoring
• Real-time Alerts: Logs matched transactions as they occur

Usage

Quick Start - Live Monitoring

For live monitoring of incoming transactions:

# Make the script executable (first time only)
chmod +x run_live.sh

# Start live monitoring
./run_live.sh

Note: When no start block is specified, the substream automatically starts from the current head of the blockchain and continues monitoring new blocks as they arrive. This ensures you're always monitoring the latest transactions without processing historical data.

Manual Setup

# Build the project
cargo build --target wasm32-unknown-unknown --release

# Authenticate with Substreams
substreams auth

# Run in live mode (starts from current head and continues monitoring new blocks)
substreams run substreams.yaml filter_transactions --log-level=info

Historical Data

To process historical blocks:

# Process from a specific block number
substreams run substreams.yaml filter_transactions --start-block 1000000

# Process a range of blocks
substreams run substreams.yaml filter_transactions --start-block 1000000 --stop-block 1000100

Configuration

Address Filtering

Configure the addresses to monitor in substreams.yaml:

params:
  filter_transactions: 'to=0xcccd218a58b53c67fc17d8c87cb90d83614e35fd'

You can also filter by multiple addresses:

params:
  filter_transactions: 'to=0xcccd218a58b53c67fc17d8c87cb90d83614e35fd&from=0x1234567890123456789012345678901234567890'

Supported Parameters

• to: Monitor incoming transactions to this address (supports both direct transfers and ERC20 transfers)
• from: Monitor outgoing transactions from this address

Output Format

The substream outputs transaction data in the following format:

{
  "transactions": [
    {
      "from": "0x...",
      "to": "0x...",
      "hash": "0x...",
      "value": "1000000000000000000",
      "token_id": "0xeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeee"
    }
  ]
}

Token Types

• Native ETH: token_id will be 0xeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeee
• ERC20 Tokens: token_id will be the contract address of the token

Logging

The substream provides comprehensive logging:

• INFO: Block processing, matched transactions, filter configuration
• DEBUG: Detailed transaction filtering logic
• WARN: Invalid address formats, parsing errors

Example Log Output

INFO: Processing block 12345678 with 150 transactions
INFO: Monitoring for incoming transactions to address: 0xcccd218a58b53c67fc17d8c87cb90d83614e35fd
INFO: MATCHED TRANSACTION: Block 12345678 | Hash: 0x... | From: 0x... | To: 0x... | Value: 1000000000000000000 | Token: 0xeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeee

Publishing

Optionally, you can publish your Substreams to the Substreams Registry.

substreams registry login         # Login to substreams.dev
substreams registry publish       # Publish your Substreams to substreams.dev

Modules

filter_transactions

This module filters and processes blockchain transactions based on specified address filters. It:

• Processes all transactions in each block
• Applies address-based filtering (from/to)
• Detects ERC20 token transfers
• Extracts transaction values and token information
• Provides comprehensive logging for monitoring

Development

Building

cargo build --target wasm32-unknown-unknown --release

Testing

cargo test

Dependencies

Key dependencies:

• substreams: Core Substreams framework
• substreams-ethereum: Ethereum-specific functionality
• num-bigint: Big integer arithmetic for token amounts
• serde: Serialization/deserialization
• anyhow: Error handling