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
• Performance Optimized: Block filtering reduces data consumption by 90-95%

Performance Optimization

Block Filtering (Recommended)

This substream includes advanced block filtering that dramatically reduces data consumption and processing time. Instead of processing all blocks, it only processes blocks that contain:

1. ERC20 Transfer events (for token transfers)
2. Transactions to monitored addresses (for incoming transfers)
3. Transactions from monitored addresses (for outgoing transfers)

Expected Performance Improvements:

• 90-95% reduction in data consumption
• 80-90% reduction in processing time
• Significantly lower memory usage

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

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

You can configure the addresses to monitor in two ways:

1. Configuration File (substreams.yaml)

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'

2. Command Line Parameters (Recommended)

The run_live.sh script supports command line parameters for flexible configuration:

# Monitor transactions to a specific address
./run_live.sh --to 0x1234567890123456789012345678901234567890

# Monitor transactions from a specific address
./run_live.sh --from 0xabcdefabcdefabcdefabcdefabcdefabcdefabcd

# Monitor transactions between two addresses
./run_live.sh --to 0x1234567890123456789012345678901234567890 --from 0xabcdefabcdefabcdefabcdefabcdefabcdefabcd

# Use custom parameters string
./run_live.sh --params 'to=0x1234567890123456789012345678901234567890&from=0xabcdefabcdefabcdefabcdefabcdefabcdefabcd'

# Monitor on different networks
./run_live.sh --network mainnet.streamingfast.io:443 --to 0x1234567890123456789012345678901234567890
./run_live.sh --network polygon-mainnet.streamingfast.io:443 --to 0x1234567890123456789012345678901234567890

# Use default parameters from substreams.yaml
./run_live.sh

3. Direct Substreams Command

You can also pass parameters directly to the substreams command:

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

# Run with custom parameters
substreams run -e base-mainnet.streamingfast.io:443 substreams.yaml filter_transactions \
    --params filter_transactions='to=0x1234567890123456789012345678901234567890' \
    --start-block 1000000 \
    --limit-processed-blocks 0

# Run on different networks
substreams run -e mainnet.streamingfast.io:443 substreams.yaml filter_transactions \
    --params filter_transactions='to=0x1234567890123456789012345678901234567890' \
    --start-block 1000000 \
    --limit-processed-blocks 0

Supported Parameters

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

Supported Networks

• base-mainnet.streamingfast.io:443 (default) - Base network
• mainnet.streamingfast.io:443 - Ethereum mainnet
• polygon-mainnet.streamingfast.io:443 - Polygon network
• Any other StreamingFast endpoint

Parameter Format

Parameters use URL query string format:

• Single parameter: to=0x1234567890123456789012345678901234567890
• Multiple parameters: to=0x1234567890123456789012345678901234567890&from=0xabcdefabcdefabcdefabcdefabcdefabcdefabcd
• Multiple addresses: to=0x1234567890123456789012345678901234567890,0xabcdefabcdefabcdefabcdefabcdefabcdefabcd

Examples

See ./examples.sh for a comprehensive list of usage examples.

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

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

Command Line Usage

Quick Start Commands

1. Build the project

   substreams build
   

2. Authenticate with Substreams

   substreams auth
   

3. Paste the token from GraphMarket auth

4. Load the auth token into environment

   source ./.substreams.env
   

5. Run the substream

   substreams run -e base-mainnet.streamingfast.io:4433 substreams.yaml filter_transactions \
       --start-block 73496620 \
       --stop-block +1 \
       --params filter_transactions=to=0x4Cdb559aD4b9Deef56044b3BC5f438A0964a950c
   

6. Update the version in substreams.yaml before releasing

7. Publish to registry

   substreams publish