Relay Affiliate Fee Listener

A standalone, modular Python application for monitoring Relay transactions and tracking ShapeShift affiliate fees across multiple blockchain networks.

🚀 Features

• Multi-chain Support: Monitors Ethereum, Polygon, Arbitrum, Optimism, Base, and Avalanche
• CSV Output: Stores all transaction data in organized CSV files
• Affiliate Tracking: Automatically detects and tracks ShapeShift affiliate fee transactions
• Block Tracking: Maintains progress across restarts with persistent block tracking
• Rate Limiting: Built-in rate limiting to respect RPC provider limits
• Configurable: Easy configuration via YAML and environment variables

📋 Requirements

• Python 3.8+
• Web3.py
• PyYAML
• python-dotenv
• Alchemy API key (or other RPC provider)

🛠️ Installation

1. Clone the repository

   git clone <your-repo-url>
   cd relay

2. Install dependencies

   pip install -r requirements.txt

3. Set up environment variables

   cp env.example .env
   # Edit .env with your API keys

4. Configure the application

   cp config/config.example.yaml config/config.yaml
   # Edit config.yaml with your settings

⚙️ Configuration

Environment Variables (.env)

ALCHEMY_API_KEY=your_alchemy_api_key_here
INFURA_API_KEY=your_infura_api_key_here  # Optional fallback

Configuration File (config/config.yaml)

api:
  alchemy_api_key: "${ALCHEMY_API_KEY}"
  infura_api_key: "${INFURA_API_KEY}"

shapeshift_affiliates:
  mainnet: "0x90A48D5CF7343B08dA12E067680B4C6dbfE551Be"
  base: "0x9c9aA90363630d4ab1D9dbF416cc3BBC8d3Ed502"
  # ... more addresses

chains:
  ethereum:
    name: "Ethereum Mainnet"
    rpc_url: "https://eth-mainnet.g.alchemy.com/v2/${ALCHEMY_API_KEY}"
    start_block: 19000000
    chunk_size: 100
    delay: 0.5

🚀 Usage

Basic Usage

python relay_listener.py

With Custom Configuration

python relay_listener.py --config custom_config.yaml

Monitor Specific Chains

python relay_listener.py --chains ethereum,base

📊 Output

The listener creates two main CSV files:

1. data/relay_transactions.csv - All detected affiliate transactions
2. data/relay_block_tracker.csv - Processing progress tracking

Transaction Data Fields

• tx_hash - Transaction hash
• chain - Blockchain network
• block_number - Block number
• timestamp - Block timestamp
• from_address - Sender address
• to_address - Recipient address
• affiliate_address - ShapeShift affiliate address
• affiliate_fee_amount - Affiliate fee amount
• affiliate_fee_token - Token used for fee
• affiliate_fee_usd - Fee value in USD
• volume_amount - Transaction volume
• volume_token - Volume token
• volume_usd - Volume in USD
• gas_used - Gas consumed
• gas_price - Gas price
• created_at - Record creation timestamp

🔧 Architecture

relay/
├── relay_listener.py      # Main listener application
├── config/
│   ├── config.yaml        # Configuration file
│   └── config_loader.py   # Configuration management
├── data/                  # Output CSV files
├── requirements.txt       # Python dependencies
├── .env.example          # Environment variables template
└── README.md             # This file

📈 Performance

• Processing Speed: ~100 blocks per batch (configurable)
• Rate Limiting: 0.5 second delay between batches
• Memory Usage: Minimal, processes data in chunks
• Storage: CSV-based for easy analysis and portability

🔍 Monitoring

The listener provides real-time logging and statistics:

INFO:relay_listener:Connected to ethereum: Ethereum Mainnet
INFO:relay_listener:Connected to base: Base
INFO:relay_listener:Found 1642 logs on base
INFO:relay_listener:Saved 1123 Relay affiliate events to CSV

🚨 Troubleshooting

Common Issues

1. RPC Connection Failed

   • Check your API key in .env
   • Verify RPC endpoint URLs
   • Check network connectivity

2. No Transactions Found

   • Verify affiliate addresses in config
   • Check start block numbers
   • Ensure contracts are deployed on specified blocks

3. Rate Limiting Errors

   • Increase delay in config
   • Reduce chunk_size
   • Use premium RPC provider

🤝 Contributing

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Add tests if applicable
5. Submit a pull request

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

🙏 Acknowledgments

• Built for ShapeShift affiliate fee tracking
• Uses Web3.py for blockchain interaction
• CSV output for easy data analysis