Liquidity

# Subnet77 Liquidity Auction & Voting

This project manages a liquidity mining system for the Bittensor ecosystem, where token holders vote on liquidity pools and validators process these votes to set miner weights on subnet 77.

## Architecture Overview

The system operates through a server (`https://77.creativebuilds.io`) that handles:
- **Vote Collection**: Token holders submit weighted votes for liquidity pools
- **Weight Calculation**: The server processes votes and calculates final miner weights
- **Validator Integration**: Validators fetch weights from the server and set them on-chain

## Core Components

### Server
- **Vote Management**: Collects and stores user votes with Ed25519 signature verification
- **Weight Calculation**: Processes votes and calculates final miner weights based on token holdings and liquidity positions
- **API Endpoints**: Provides RESTful API for all system operations

### Validator (`validator/index.ts`)
- **Weight Fetching**: Retrieves calculated weights from the server
- **On-chain Updates**: Sets miner weights on the Bittensor network
- **Version Management**: Includes automatic version checking and update capabilities

### Scripts
- **Voting**: Submit weighted votes for liquidity pools
- **Registration**: Link Bittensor hotkeys to Ethereum addresses
- **Pool Management**: View current pool information and voting status
- **Weight Verification**: Independently recompute and audit central API miner weights

## Quick Start

1. **Install dependencies** (Bun is the primary runtime)

```bash
bun install
```

2. **Set up environment variables**

```bash
cp .env.example .env
# Fill in the required variables (see Environment section below)
```

3. **Query current pool weights**

```bash
bun run pools
```

## User Roles & Actions

### 🏦 Token Holders (Voters)

Token holders can vote on which liquidity pools should receive weight in the system.

**What you can do:**
- **Vote on pools**: Submit weighted votes for active liquidity pools
- **Check pool status**: View current pool weights and rankings
- **Monitor your voting power**: Track your influence based on token balance

**Key command:**
```bash
# Submit votes for pools (weights must sum to 10000)
just vote

# Retract all votes (send empty allocation)
just vote --retract
```

**Setup required:**
- `HOLDER_COLDKEY` in `.env` (your Bittensor coldkey for signing votes)

### ⚡ Validators

Validators read weights from the server and periodically push them to subnet 77.

**What you can do:**
- **Run the validator**: Fetch weights from the server and set them on subnet 77
- **Independently verify weights**: Recompute miner weights locally and compare to the central API
- **Monitor system health**: Track voting patterns and pool performance

**Key commands:**
```bash
# Start the validator (processes votes and submits weights)
just validate

# Independently verify central API weights (see Weight Verification below)
just verify-weights

# Run in test mode (compute weights but skip submission)
TEST_MODE=true just validate

# Enable verbose logging
LOG=true just validate
```

**Setup required:**
- `VALIDATOR_HOTKEY_URI` in `.env` (your validator hotkey)
- `THEGRAPH_API_KEY` in `.env` (required for `just verify-weights`; optional for running the validator itself)

### ⛏️ Miners

Miners provide liquidity to pools and can register their addresses to participate in the system.

**What you can do:**
- **Register your address**: Link your Bittensor public key to an EVM address
- **Provide liquidity**: Add liquidity to pools to earn rewards
- **Monitor earnings**: Track your pool performance and rewards

**Key commands:**
```bash
# Register your Bittensor public key with an EVM address
just register

# Check your registration status
bunx tsx scripts/check-key.ts

# View pool analytics and your position
bun run pools
```

**Setup required:**
- `MINER_HOTKEY` in `.env` (your Bittensor hotkey)
- `ETH_KEY` in `.env` (your Ethereum private key)
- Bittensor wallet with stake on subnet 77

## Scripts Reference

| Script | Purpose | Usage |
|--------|---------|-----------------|
| `create-key.ts` | Generate or import an **EVM keypair** and derive the corresponding **SS58** address. Stores everything in `.keys/` and can update `.env`. | `bunx tsx scripts/create-key.ts` |
| `register.ts` | Link a **Bittensor hotkey** → **EVM address** via the server. Requires `MINER_HOTKEY` and `ETH_KEY` environment variables. | `just register` |
| `vote.ts` | Interactive pool-weight voting. Searches and selects pools, then submits weighted votes that sum to 10000. Supports retracting votes with `--retract` flag. | `just vote` |
| `pools.ts` | Display current pool information from the API including pool details, voter information, and alpha token balances. | `just pools` |
| `verify-weights.ts` | Independently recompute miner weights from API inputs + The Graph, then compare to `/weights`. | `just verify-weights` |
| `weights.ts` | Read a validator's weight vector from chain for subnet 77. | `bunx tsx scripts/weights.ts <hotkey>` |

> Run scripts with `LOG=true` to enable verbose logging where available.

## Weight Verification

Validators (or anyone auditing the subnet) can independently confirm that `https://77.creativebuilds.io/weights` matches the published calculation — without trusting the server's LP or scoring logic.

### Quick verify

```bash
cp .env.example .env
just verify-weights
```

If `THEGRAPH_API_KEY` is not set, the script launches an interactive setup: it explains where to get a key ([Subgraph Studio](https://thegraph.com/studio/apikeys/)), prompts you to paste it, optionally saves it to `.env` `[Y/n]`, then runs verification.

On success you'll see a comparison table of local vs server weights. Exit code `0` on completion, `1` on fetch/calculation errors.

### What the script does

1. **From the central API** (inputs only): `/allVotes`, `/allHolders`, `/allMiners`, `/weights`
2. **From The Graph** (your API key): Uniswap V3 LP posit