Symbiotic Finance Analytics Toolkit

A collection of Python scripts for collecting on-chain data from Symbiotic Finance vaults, calculating network-level metrics, and exporting results to Google Sheets.

What It Does

This toolkit builds a complete map of Symbiotic vaults by querying Ethereum smart contracts via multicall, then calculates key metrics for each network and vault:

1. Collects on-chain data — vault TVLs, operator opt-ins, delegator stakes, collateral tokens, and asset prices (via CoinMarketCap)
2. Calculates network metrics — mining rate, restaking score, decentralization score, security rate, and point rates for each network
3. Computes vault-level metrics — per-vault points, points/hour/USD, restake ratios across all networks
4. Exports to Google Sheets — writes structured data to separate sheets for each vault and a network overview
5. Compares with Symbiotic API — validates locally computed metrics against the official Symbiotic analytics API
6. Supports simulation mode — modify vault parameters via a Google Sheet and recalculate metrics to model "what-if" scenarios

Architecture

On-chain data (Ethereum RPC)
        |
        v
build_vault_structure.py  -->  final_vault_structure_with_metrics.json
        |
        v
calculate_network_metrics.py  -->  network_metrics_all.json
        |
        v
vaults_metrics_curator.py  -->  vaults_metrics_curator.json
vaults_metrics_different.py  -->  vaults_metrics_different.json
        |
        v
Google_curator.py  -->  Google Sheets (curator vaults)
Google_differentvaults.py  -->  Google Sheets (comparison vaults)
compare_with_api.py  -->  Google Sheets + CSV (API comparison)

Prerequisites

• Python 3.9+
• An Ethereum RPC endpoint (e.g. Ankr, Infura, Alchemy)
• A CoinMarketCap API key (free tier works)
• A Dune Analytics API key (for compare_with_api.py)
• A Google Cloud service account with Google Sheets API enabled (setup guide)

Installation

git clone https://github.com/Sibirina/symbioticfi-scripts.git
cd symbioticfi-scripts
pip install -r requirements.txt

Configuration

1. Copy the example environment file:

   cp .env.example .env

2. Fill in your credentials in .env:

   RPC_URL=https://rpc.ankr.com/eth/YOUR_TOKEN
   CMC_API_KEY=your-coinmarketcap-api-key
   DUNE_API_KEY=your-dune-api-key
   GOOGLE_CREDENTIALS_PATH=path/to/your-service-account.json
   

3. Place your Google service account JSON file at the path specified above.

Usage

Run the full pipeline

python run_all_scripts.py

This executes in order:

1. build_vault_structure.py — collect on-chain data and build vault structure
2. calculate_network_metrics.py — calculate metrics for all networks
3. vaults_metrics_curator.py — compute per-vault metrics for curator vaults
4. Google_curator.py — export results to Google Sheets
5. compare_with_api.py — compare with Symbiotic API

Run individual scripts

python build_vault_structure.py      # Step 1: Build vault structure
python calculate_network_metrics.py  # Step 2: Calculate network metrics
python vaults_metrics_curator.py     # Step 3: Compute vault metrics
python Google_curator.py             # Step 4: Export to Google Sheets
python compare_with_api.py           # Step 5: API comparison

Simulation mode

The simulation/ directory contains modified versions of the scripts that allow you to test "what-if" scenarios by modifying vault parameters in a Google Sheet:

cd simulation
python build_vault_structure_simulation.py  # Build base structure
python simulation.py                        # Apply modifications and run pipeline

The simulation reads stake adjustments from a Google Sheet (columns: address, subnetwork, operator, stake) and recalculates all metrics with the modified parameters.

Project Structure

symbioticfi-scripts/
├── config.py                        # Centralized environment variable loading
├── .env.example                     # Template for environment variables
├── requirements.txt                 # Python dependencies
├── run_all_scripts.py               # Master script to run full pipeline
├── build_vault_structure.py         # Collect on-chain vault data + prices
├── calculate_network_metrics.py     # Calculate network-level metrics
├── vaults_metrics_curator.py        # Per-vault metrics (curator vaults)
├── vaults_metrics_different.py      # Per-vault metrics (comparison vaults)
├── Google_curator.py                # Export curator metrics to Google Sheets
├── Google_differentvaults.py        # Export comparison metrics to Google Sheets
├── compare_with_api.py              # Compare local vs API metrics
├── abi/                             # Symbiotic contract ABIs
│   ├── VaultABI.json
│   ├── VaultFactoryABI.json
│   ├── FullRestakeDelegatorABI.json
│   └── ... (34 ABI files)
└── simulation/                      # Simulation mode scripts
    ├── simulation.py                # Main simulation orchestrator
    ├── build_vault_structure_simulation.py
    ├── calculate_network_metrics_simulation.py
    ├── vaults_metrics_curator_simulation.py
    ├── Google_curator_simulation.py
    └── abi/                         # Contract ABIs (same as root)

Key Metrics

Metric	Description
Mining Rate	min(target_stake, total_stake) / total_stake — how close the network is to its target
Restaking Score	Weighted average of per-vault restaking scores based on the ratio of total staked vs TVL
Decentralization Score	1 - HHI (Herfindahl-Hirschman Index) — measures stake distribution across vaults
Security Rate	(2 * restaking_score + decentralization_score) / 3
Point Rate	mining_rate * security_rate
Total Points	total_stake_usd * 0.0005 * point_rate

License

MIT