Vultisig Analytics Dashboard

Analytics dashboard for tracking Vultisig swap metrics across multiple DEX aggregators including THORChain, MayaChain, LiFi, and Arkham.

Architecture

This project follows a clean separation between frontend and backend in a monorepo structure:

analytics-dashboard/
├── dashboard/           # Next.js frontend (React 19, TypeScript, Tailwind)
│   ├── src/
│   │   ├── app/        # Pages and layouts
│   │   ├── components/ # React components
│   │   └── lib/        # Utilities and API client
│   └── package.json    # Frontend dependencies (no database access)
│
├── vultisig-analytics/  # Python backend (Flask API, data ingestion)
│   ├── api_server.py   # REST API endpoints
│   ├── ingestors/      # Data ingestion scripts
│   ├── database/       # Database utilities
│   └── requirements.txt # Python dependencies
│
└── docker-compose.yml   # Full stack orchestration

Separation of Concerns

• Frontend (Next.js): Pure UI layer with no direct database access

  • Communicates with backend via HTTP API calls
  • Proxies all /api/* requests to the backend via Next.js rewrites (configured with BACKEND_URL)
  • All data fetching through /api/* endpoints on backend

• Backend (Python/Flask): Data layer and business logic

  • Direct PostgreSQL/TimescaleDB access
  • RESTful API for all data operations
  • Background data ingestion and sync

• Database (PostgreSQL + TimescaleDB): Data persistence

  • Only accessible by backend and sync services
  • Time-series optimizations for analytics data

Features

• Real-time swap volume, revenue, and user tracking
• Multi-provider analytics (THORChain, MayaChain, LiFi, Arkham)
• Historical data visualization with customizable date ranges
• Automatic data sync from blockchain APIs
• PostgreSQL + TimescaleDB for time-series data
• Holders Tab: $VULT token holder tier distribution and address lookup
• Referrals Tab: Affiliate/referral tracking and performance metrics

Quick Start

Prerequisites

• Docker & Docker Compose
• Git

Run with Docker

# Clone the repository
git clone https://github.com/vultisig/analytics-dashboard.git
cd analytics-dashboard

# Create the database volume (first time only)
docker volume create vultisig-analytics_postgres_data

# Copy the example env file and fill in your values
cp vultisig-analytics/.env_example .env
# Edit .env and set at least POSTGRES_PASSWORD

# Start all services
docker compose up -d

Services will be available at:

• Dashboard: http://localhost:3000
• API: http://localhost:8080
• PostgreSQL: localhost:5432 (or the port set in POSTGRES_PORT)

Environment Variables

Create a .env file in the root directory (see vultisig-analytics/.env_example):

# PostgreSQL (required)
POSTGRES_USER=vultisig_user
POSTGRES_PASSWORD=your_secure_password
POSTGRES_DB=vultisig_analytics
POSTGRES_PORT=5432

# API Keys
ARKHAM_API_KEY=your_key
LIFI_API_KEY=your_key
MORALIS_API_KEY=your_key  # Required for Holders tab (free tier at moralis.io)

Development

Frontend (Next.js)

cd dashboard
npm install

# Set the backend URL for the Next.js proxy (server-side only)
export BACKEND_URL=http://localhost:8080

npm run dev

The frontend will be available at http://localhost:3000

Backend (Python)

cd vultisig-analytics
pip install -r requirements.txt

# Set database credentials
export POSTGRES_PASSWORD=your_password

python api_server.py

The backend API will be available at http://localhost:8080

Running Both Services

For local development, you need to run:

1. PostgreSQL database (via Docker or local install)
2. Python backend (api_server.py)
3. Next.js frontend (npm run dev)

Or simply use Docker Compose to run everything together (recommended).

Manual Data Ingestion

cd vultisig-analytics
python run_ingestion.py

Services

Service	Description	Port
dashboard	Next.js frontend	3000
backend	Flask REST API	8080
postgres	TimescaleDB database	5432
sync	Continuous data ingestion	-

Holders Tab

The Holders tab displays $VULT token holder tier distribution and allows users to check their tier status.

Tier System

Tier	$VULT Required	Discount
Ultimate	1,000,000	50 bps (100% off)
Diamond	100,000	35 bps
Platinum	15,000	25 bps
Gold	7,500	20 bps
Silver	3,000	10 bps
Bronze	1,500	5 bps

THORGuard NFT Boost: Holding a THORGuard NFT upgrades your tier by one level (max to Platinum).

Blacklist Configuration

To exclude addresses from tier calculations (e.g., treasury, LP pools, exchanges), edit:

vultisig-analytics/config/blacklist.json

{
  "description": "Addresses excluded from VULT holder tier calculations",
  "blacklist": [
    {
      "address": "0x...",
      "description": "Description of the address"
    }
  ]
}

Changes are applied on the next daily sync (00:00 UTC).

Data Sync

• Holder data syncs daily at 00:00 UTC
• Uses Moralis API to fetch VULT token and THORGuard NFT holders
• Requires MORALIS_API_KEY environment variable

License

MIT