{"id":50972812,"url":"https://github.com/pxlvre/usdc-event-tracker","last_synced_at":"2026-06-19T04:01:50.117Z","repository":{"id":313679023,"uuid":"1051778858","full_name":"pxlvre/usdc-event-tracker","owner":"pxlvre","description":"🛰️ USDC event tracker across multiple EVM-based networks, with configurable data sinks for storage and processing","archived":false,"fork":false,"pushed_at":"2026-03-03T21:41:43.000Z","size":177,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-03-04T01:38:24.842Z","etag":null,"topics":["blockchain","erc20","ethereum","event-tracking","evm","golang","usdc"],"latest_commit_sha":null,"homepage":"","language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/pxlvre.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2025-09-06T17:48:21.000Z","updated_at":"2026-03-03T21:41:41.000Z","dependencies_parsed_at":"2025-09-07T20:29:25.793Z","dependency_job_id":"7e247ed4-2ee2-4559-bc10-aee87a10a1ee","html_url":"https://github.com/pxlvre/usdc-event-tracker","commit_stats":null,"previous_names":["vidalpaul/usdc-event-tracker","pxlvre/usdc-event-tracker"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/pxlvre/usdc-event-tracker","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/pxlvre%2Fusdc-event-tracker","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/pxlvre%2Fusdc-event-tracker/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/pxlvre%2Fusdc-event-tracker/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/pxlvre%2Fusdc-event-tracker/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/pxlvre","download_url":"https://codeload.github.com/pxlvre/usdc-event-tracker/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/pxlvre%2Fusdc-event-tracker/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":34516549,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-06-19T02:00:06.005Z","response_time":61,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["blockchain","erc20","ethereum","event-tracking","evm","golang","usdc"],"created_at":"2026-06-19T04:01:49.160Z","updated_at":"2026-06-19T04:01:50.106Z","avatar_url":"https://github.com/pxlvre.png","language":"Go","funding_links":[],"categories":[],"sub_categories":[],"readme":"# USDC Event Tracker\n\nA high-performance blockchain event tracker specifically designed to monitor USDC (USD Coin) transactions across multiple Ethereum-compatible networks. The tracker provides real-time monitoring with configurable data sinks for storage and processing.\n\n## Features\n\n- Real-time block monitoring\n- USDC transaction filtering\n- Event detection (Transfer, Approval)\n- Graceful shutdown handling\n- Structured logging for better readability\n\n### 📊 Flexible Data Sinks\n- **Console** - Real-time console output with formatted display\n- **Filesystem** - Multiple formats (JSON, JSONL, CSV, Text) with rotation\n- **PostgreSQL** - Structured database storage with indexing\n- **MongoDB** - Document-based storage with flexible querying\n- **Apache Kafka** - Event streaming with partitioning and compression\n\n### 🚀 Performance Features\n- **Batch Processing** - Configurable batch sizes for optimal performance\n- **Background Workers** - Async processing with graceful shutdown\n- **Connection Pooling** - Efficient resource management\n- **Error Handling** - Comprehensive error recovery and logging\n- **Metrics** - Built-in performance and health metrics\n\n## Quick Start\n\n### Prerequisites\n- Go 1.21 or higher\n- Access to an Ethereum RPC endpoint (Infura, Alchemy, or self-hosted)\n\n### Installation\n\n```bash\n# Clone the repository\ngit clone https://github.com/your-username/usdc-event-tracker.git\ncd usdc-event-tracker\n\n# Install dependencies\ngo mod tidy\n\n# Copy environment template\ncp .env.example .env\n```\n\n### Configuration\n\nEdit `.env` file with your settings:\n\n```env\n# Ethereum connection (required)\nWEBHOOK_URL=wss://sepolia.infura.io/ws/v3/YOUR_PROJECT_ID\n\n# Network selection\nNETWORK=sepolia\n\n# Data sinks (comma-separated)\nSINKS=console,filesystem\n\n# Filesystem sink settings\nFS_OUTPUT_DIR=./usdc-events\nFS_FORMAT=json\nFS_FILE_PREFIX=sepolia-usdc\n```\n\n### Run\n\n```bash\n# Build the application\ngo build -o usdc-event-tracker .\n\n# Run with your configuration\n./usdc-event-tracker\n```\n\n## Configuration Reference\n\n### Environment Variables\n\n| Variable | Description | Default | Options |\n|----------|-------------|---------|---------|\n| `WEBHOOK_URL` | Ethereum RPC endpoint (required) | - | HTTP/HTTPS/WS/WSS URL |\n| `NETWORK` | Blockchain network | `sepolia` | `mainnet`, `sepolia`, `arbitrum`, `optimism`, `polygon`, `avalanche`, `linea` |\n| `SINKS` | Data output destinations | `console` | `console`, `filesystem`, `sql`, `mongodb`, `kafka` |\n\n### Filesystem Sink\n\n| Variable | Description | Default | Options |\n|----------|-------------|---------|---------|\n| `FS_OUTPUT_DIR` | Output directory | `./usdc-events` | Any valid path |\n| `FS_FORMAT` | File format | `json` | `json`, `jsonl`, `csv`, `text` |\n| `FS_FILE_PREFIX` | File name prefix | `usdc-events` | Any string |\n\n### PostgreSQL Sink\n\n| Variable | Description | Default | Required |\n|----------|-------------|---------|----------|\n| `SQL_CONNECTION_STRING` | PostgreSQL connection string | - | ✅ |\n| `SQL_TABLE_NAME` | Table name for events | `usdc_events` | ❌ |\n| `SQL_SCHEMA_NAME` | Database schema | `public` | ❌ |\n| `SQL_BATCH_SIZE` | Batch size for inserts | `100` | ❌ |\n| `SQL_CREATE_TABLES` | Auto-create tables | `true` | ❌ |\n\n### MongoDB Sink\n\n| Variable | Description | Default | Required |\n|----------|-------------|---------|----------|\n| `MONGO_URI` | MongoDB connection URI | - | ✅ |\n| `MONGO_DATABASE` | Database name | `blockchain` | ❌ |\n| `MONGO_COLLECTION` | Events collection | `usdc_events` | ❌ |\n| `MONGO_LOGS_COLLECTION` | Logs collection | `usdc_logs` | ❌ |\n| `MONGO_BATCH_SIZE` | Batch size | `50` | ❌ |\n\n### Kafka Sink\n\n| Variable | Description | Default | Required |\n|----------|-------------|---------|----------|\n| `KAFKA_BROKERS` | Comma-separated broker list | - | ✅ |\n| `KAFKA_TOPIC` | Main topic name | `usdc-events` | ❌ |\n| `KAFKA_LOGS_TOPIC` | Separate logs topic | - | ❌ |\n| `KAFKA_BATCH_SIZE` | Messages per batch | `100` | ❌ |\n| `KAFKA_COMPRESSION` | Compression algorithm | `gzip` | `gzip`, `snappy`, `lz4`, `zstd` |\n\n## Architecture\n\n### Core Components\n\n```\n┌─────────────────────┐    ┌──────────────────────┐    ┌─────────────────────┐\n│                     │    │                      │    │                     │\n│   Ethereum Client   │────│   Event Tracker      │────│   Sink Manager      │\n│   (WebSocket/HTTP)  │    │   (Block Monitor)    │    │   (Multi-output)    │\n│                     │    │                      │    │                     │\n└─────────────────────┘    └──────────────────────┘    └─────────────────────┘\n                                        │                           │\n                                        │                           │\n                                        ▼                           ▼\n                           ┌──────────────────────┐    ┌─────────────────────┐\n                           │                      │    │                     │\n                           │   USDC Filter        │    │   Console Sink      │\n                           │   (ERC20 Decoder)    │    │   Filesystem Sink   │\n                           │                      │    │   PostgreSQL Sink   │\n                           └──────────────────────┘    │   MongoDB Sink      │\n                                                       │   Kafka Sink        │\n                                                       │                     │\n                                                       └─────────────────────┘\n```\n\n### Data Flow\n\n1. **Block Monitoring** - Continuously polls for new blocks\n2. **Transaction Filtering** - Identifies USDC-related transactions  \n3. **Event Decoding** - Decodes Transfer and Approval events\n4. **Sink Distribution** - Sends events to all configured sinks\n5. **Batch Processing** - Optimizes throughput with batching\n\n### Event Structure\n\n```json\n{\n  \"timestamp\": \"2024-01-01T12:00:00Z\",\n  \"blockNumber\": 19000000,\n  \"txHash\": \"0x1234567890abcdef...\",\n  \"status\": 1,\n  \"gasUsed\": 65000,\n  \"logs\": [\n    {\n      \"type\": \"Transfer\",\n      \"address\": \"0x...\",\n      \"topics\": [\"0x...\", \"0x...\", \"0x...\"],\n      \"data\": \"0x...\",\n      \"from\": \"0x...\",\n      \"to\": \"0x...\",\n      \"value\": \"1000000000\"\n    }\n  ]\n}\n```\n\n## Development\n\n### Project Structure\n\n```\nusdc-event-tracker/\n├── cmd/                    # Application entrypoints\n├── internal/               # Private application code\n│   ├── config/            # Configuration management\n│   ├── erc20/             # ERC20 event definitions\n│   ├── sinks/             # Data output implementations\n│   │   ├── console/       # Console output\n│   │   ├── fs/            # Filesystem output\n│   │   ├── sql/           # PostgreSQL output\n│   │   ├── mongodb/       # MongoDB output\n│   │   └── kafka/         # Kafka output\n│   ├── tracker/           # Core tracking logic\n│   ├── tx/                # Transaction utilities\n│   ├── usdc/              # USDC-specific utilities\n│   └── ws/                # WebSocket client\n├── .env.example           # Environment template\n├── go.mod                 # Go module definition\n└── main.go               # Application entry point\n```\n\n### Dependencies\n\nThe project includes skeleton implementations for all sinks. To implement them, you'll need:\n\n#### Core Dependencies (already included)\n```bash\ngo get github.com/ethereum/go-ethereum\ngo get github.com/joho/godotenv\n```\n\n#### PostgreSQL Sink\n```bash\ngo get github.com/lib/pq\n```\n\n#### MongoDB Sink  \n```bash\ngo get go.mongodb.org/mongo-driver/mongo\ngo get go.mongodb.org/mongo-driver/bson\n```\n\n#### Kafka Sink\n```bash\ngo get github.com/segmentio/kafka-go\n```\n\nAll sinks implement the `Sink` interface:\n\n```go\ntype Sink interface {\n    Name() string\n    Initialize() error\n    Write(ctx context.Context, events []Event) error\n    Close() error\n}\n```\n\n### Building\n\n```bash\n# Install dependencies for all sinks\ngo mod tidy\n\n# Build the application\ngo build -o usdc-event-tracker .\n\n# Run tests\ngo test ./...\n```\n\n## Production Deployment\n\n### Docker Example\n\n```dockerfile\nFROM golang:1.21-alpine AS builder\nWORKDIR /app\nCOPY . .\nRUN go build -o usdc-event-tracker .\n\nFROM alpine:latest\nRUN apk --no-cache add ca-certificates\nWORKDIR /root/\nCOPY --from=builder /app/usdc-event-tracker .\nCMD [\"./usdc-event-tracker\"]\n```\n\n### Environment Variables Summary\n\n#### Required\n- `WEBHOOK_URL` - Ethereum RPC endpoint\n\n#### Optional\n- `NETWORK` - Network to monitor (default: sepolia)\n- `SINKS` - Output destinations (default: console)\n\n#### Sink-Specific\n- **Filesystem**: `FS_OUTPUT_DIR`, `FS_FORMAT`, `FS_FILE_PREFIX`\n- **PostgreSQL**: `SQL_CONNECTION_STRING`, `SQL_TABLE_NAME`, etc.\n- **MongoDB**: `MONGO_URI`, `MONGO_DATABASE`, etc.\n- **Kafka**: `KAFKA_BROKERS`, `KAFKA_TOPIC`, etc.\n\n## Implementation Progress\n\n### ✅ Completed\n- Multi-network support (7 networks)\n- ERC20 event decoding (Transfer, Approval)\n- Sink architecture with interface\n- Console sink (full implementation)\n- Filesystem sink (skeleton + full reference)\n\n### 🚧 To Implement (Skeletons Ready)\n- **SQL Sink** - PostgreSQL with batch processing\n- **MongoDB Sink** - Document storage with indexing  \n- **Kafka Sink** - Event streaming with compression\n\nEach skeleton includes:\n- Complete struct definitions\n- Function signatures with detailed TODO comments\n- Import statements and dependencies\n- Full implementation reference in `/tmp/`\n\n## Contributing\n\n1. Fork the repository\n2. Implement sink skeletons following the TODO comments\n3. Test your implementation thoroughly\n4. Submit a pull request\n\n\n## License\n\nThe tracker displays:\n- Connection information\n- Block processing details\n- USDC transactions with:\n  - Transaction hash\n  - Status (success/failure)\n  - Gas usage\n  - Event types (Transfer/Approval)\n  - Event details (from/to addresses)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fpxlvre%2Fusdc-event-tracker","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fpxlvre%2Fusdc-event-tracker","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fpxlvre%2Fusdc-event-tracker/lists"}