initial commit

.dockerignore

@@ -0,0 +1,22 @@
+__pycache__
+*.pyc
+*.pyo
+*.pyd
+.Python
+env/
+venv/
+.env
+*.log
+.git/
+.gitignore
+README.md
+*.md
+*.test.py
+tests/
+.pytest_cache/
+.coverage
+htmlcov/
+.idea/
+.vscode/
+*.swp
+*.swo

.github/workflows/release.yaml

@@ -0,0 +1,48 @@
+name: Build and Publish Docker Image
+
+on:
+  release:
+    types: [published]
+  push:
+    tags:
+      - 'v*'
+
+env:
+  REGISTRY: ghcr.io
+  IMAGE_NAME: ${{ github.repository }}
+
+jobs:
+  build-and-push:
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+      packages: write
+
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v4
+
+      - name: Log in to GitHub Container Registry
+        uses: docker/login-action@v3
+        with:
+          registry: ${{ env.REGISTRY }}
+          username: ${{ github.actor }}
+          password: ${{ secrets.GITHUB_TOKEN }}
+
+      - name: Extract metadata (tags, labels) for Docker
+        id: meta
+        uses: docker/metadata-action@v5
+        with:
+          images: ${{ env.REGISTRY }}/${{ env.IMAGE_NAME }}
+          tags: |
+            type=semver,pattern={{version}}
+            type=semver,pattern={{major}}.{{minor}}
+            type=raw,value=latest,enable={{is_default_branch}}
+
+      - name: Build and push Docker image
+        uses: docker/build-push-action@v5
+        with:
+          context: .
+          push: true
+          tags: ${{ steps.meta.outputs.tags }}
+          labels: ${{ steps.meta.outputs.labels }}

Dockerfile

@@ -0,0 +1,39 @@
+# Build stage
+FROM python:3.11-slim as builder
+
+WORKDIR /app
+
+# Install build dependencies
+RUN apt-get update && \
+    apt-get install -y --no-install-recommends gcc python3-dev && \
+    rm -rf /var/lib/apt/lists/*
+
+# Copy requirements and install dependencies
+COPY requirements.txt .
+RUN pip install --no-cache-dir --user -r requirements.txt
+
+# Final stage
+FROM python:3.11-slim
+
+WORKDIR /app
+
+# Copy only the necessary files from builder
+COPY --from=builder /root/.local/lib/python3.11/site-packages /usr/local/lib/python3.11/site-packages
+COPY src/ /app/src/
+COPY config/ /app/config/
+
+ENV CONFIG_PATH=/app/config/config.yaml
+ENV PORT=4200
+
+# Install curl for healthcheck (much smaller than gcc and python3-dev)
+RUN apt-get update && \
+    apt-get install -y --no-install-recommends curl && \
+    rm -rf /var/lib/apt/lists/*
+
+EXPOSE 4200
+
+# Add health check
+HEALTHCHECK --interval=30s --timeout=10s --start-period=5s --retries=3 \
+    CMD curl -f http://localhost:4200/health || exit 1
+
+CMD ["python", "-m", "src.main"]

LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 Maksym Chikita
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

README.md

@@ -0,0 +1,174 @@
+# Token Balance Exporter
+
+A Prometheus exporter that monitors USDC token (or any specified token by contact addr) balances across multiple blockchain networks (Ethereum, BSC, etc.). It provides real-time metrics about token balances and network health.
+
+## Features
+
+- Monitors USDC token balances across multiple addresses and networks
+- Provides Prometheus metrics for monitoring and alerting
+- Health checks for each RPC endpoint
+- Built-in HTTP server for metrics and health endpoints
+- Configurable scrape intervals
+- Docker support with health checking
+
+## Metrics
+
+The exporter provides the following metrics:
+
+- `token_balance{network, token, token_address, alias, address}` - Token balance for each monitored address
+- `exporter_health` - Overall health status of the exporter (1 = healthy, 0 = unhealthy)
+- `exporter_last_successful_scrape_timestamp` - Timestamp of the last successful scrape
+- `exporter_scrape_failures_total{network}` - Counter of scrape failures by network
+- `exporter_rpc_health{network}` - RPC endpoint health status by network (1 = healthy, 0 = unhealthy)
+
+## Configuration
+
+Create a `config.yaml` file:
+
+```yaml
+networks:
+  ethereum:
+    rpc_url: "https://mainnet.infura.io/v3/YOUR-PROJECT-ID"
+    tokens:
+      USDC:
+        address: "0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48"
+        decimals: 6
+    addresses:
+      - alias: "bridge_eth"
+        address: "<YOUR-ADDRESS>"
+
+  bsc:
+    rpc_url: "https://bsc-dataseed1.binance.org"
+    tokens:
+      USDC:
+        address: "0x8AC76a51cc950d9822D68b83fE1Ad97B32Cd580d"
+        decimals: 18
+    addresses:
+      - alias: "bridge_bsc"
+        address: "<YOUR-ADDRESS>"
+
+settings:
+  scrape_interval: 60  # in seconds
+  port: 4200
+  health_check_interval: 30
+```
+
+## Installation
+
+### Prerequisites
+
+- Python 3.11 or higher
+- Docker (optional)
+
+### Local Installation
+
+1. Clone the repository:
+```bash
+git clone https://github.com/ambrosus/token_balance_exporter.git
+cd token_balance_exporter
+```
+
+2. Create and activate virtual environment:
+```bash
+python -m venv venv
+source venv/bin/activate  # On Windows: venv\Scripts\activate
+```
+
+3. Install dependencies:
+```bash
+pip install -r requirements.txt
+```
+
+4. Configure your `config.yaml` and run:
+```bash
+python -m src.main
+```
+
+### Docker Installation
+
+1. Build the Docker image:
+```bash
+docker build -t token-monitor .
+```
+
+or pull the image from github registry: 
+```bash
+docker pull ghcr.io/ambrosus/token_balance_exporter:latest
+```
+
+2. Run the container:
+```bash
+docker run -d \
+    --name token-monitor \
+    -p 4200:4200 \
+    -v $(pwd)/config/config.yaml:/app/config/config.yaml \
+    token-monitor:latest
+```
+
+## Usage
+
+### Endpoints
+
+- Metrics: `http://localhost:4200/metrics`
+- Health Check: `http://localhost:4200/health`
+
+### Prometheus Configuration
+
+Add the following to your `prometheus.yml`:
+
+```yaml
+scrape_configs:
+  - job_name: 'token_monitor'
+    static_configs:
+      - targets: ['localhost:4200']
+    scrape_interval: 1m
+```
+
+### Example Grafana Queries
+
+1. Token Balance by Address:
+```
+token_balance{alias="bridge_eth"}
+```
+
+2. RPC Health Status:
+```
+exporter_rpc_health
+```
+
+## Development
+
+Project structure:
+```
+token-monitor/
+├── config/
+│   └── config.yaml
+├── src/
+│   ├── __init__.py
+│   ├── main.py
+│   ├── config.py
+│   ├── metrics.py
+│   ├── monitor.py
+│   └── web.py
+├── requirements.txt
+├── README.md
+└── Dockerfile
+```
+
+## Contributing
+
+1. Fork the repository
+2. Create a feature branch
+3. Commit your changes
+4. Push to the branch
+5. Create a Pull Request
+
+## License
+
+This project is licensed under the MIT License - see the LICENSE file for details.
+
+## Acknowledgments
+
+- Web3.py for blockchain interaction
+- Prometheus for metrics collection
+- aiohttp for async HTTP server

config/config.yaml

@@ -0,0 +1,24 @@
+networks:
+  ethereum:
+    rpc_url: https://mainnet.infura.io/v3/<your_infura_project_id>
+    tokens:
+      USDC:
+        address: "0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48"
+        decimals: 6
+    addresses:
+      - alias: "bridge_eth"
+        address: "<your_bridge_eth_address>"
+
+  bsc:
+    rpc_url: https://bsc-dataseed1.binance.org
+    tokens:
+      USDC:
+        address: "0x8AC76a51cc950d9822D68b83fE1Ad97B32Cd580d"
+        decimals: 18
+    addresses:
+      - alias: "bridge_bsc"
+        address: "<your_bridge_bsc_address>"
+
+settings:
+  scrape_interval: 60
+  port: 4200