Orca Whirlpools MVP

A complete MVP application for tracking Orca Whirlpools liquidity positions and fees on Solana Devnet. Users can connect their wallet or enter a public key to view their positions, liquidity ranges, and estimated fee earnings.

🎯 Features

Real-time Position Tracking: View all Orca Whirlpool positions for any wallet
Fee Estimation: Calculate estimated fees earned from liquidity provision
Range Monitoring: Check if positions are in-range or out-of-range
Helius Integration: Real-time webhook events for position updates
Devnet Support: Fully configured for Solana Devnet testing

🏗️ Architecture

┌─────────────────┐    ┌──────────────────┐    ┌─────────────────┐
│   React Frontend │    │  Express Backend │    │  PostgreSQL DB  │
│   (Vite + TS)   │◄──►│   (Node.js TS)   │◄──►│    (Docker)     │
└─────────────────┘    └──────────────────┘    └─────────────────┘
                               ▲
                               │
                    ┌──────────────────┐
                    │  Helius Webhooks │
                    │  (Solana Devnet) │
                    └──────────────────┘

🚀 Quick Start

Prerequisites

Node.js 20+
Docker & Docker Compose
Helius API Key (free tier)

1. Clone and Setup

git clone <your-repo>
cd orca-mvp

2. Start Database

cd infra
docker compose up -d

3. Configure Backend

cd ../backend
cp .env.example .env
# Edit .env with your Helius API key
npm install
npm run dev

4. Start Frontend

cd ../frontend
npm install
npm run dev

5. Configure Helius Webhook

Go to Helius Dashboard
Create a new webhook pointing to: https://your-domain.com/webhook/helius
Filter for Orca program: whirLbMiicVdio4qvUfM5KAg6Ct8VwpYzGff3uctyCc

📁 Project Structure

orca-mvp/
├── backend/                 # Express.js backend
│   ├── src/
│   │   ├── routes/         # API endpoints
│   │   │   ├── webhook.ts  # Helius webhook handler
│   │   │   ├── wallet.ts   # Wallet positions API
│   │   │   └── position.ts # Position details API
│   │   ├── lib/
│   │   │   ├── db.ts       # Database utilities
│   │   │   ├── orca.ts     # Orca SDK integration
│   │   │   └── types.ts    # TypeScript interfaces
│   │   └── index.ts        # Express app setup
│   ├── Dockerfile
│   └── .env.example
├── frontend/                # React frontend
│   ├── src/
│   │   ├── components/
│   │   │   ├── WalletConnect.tsx
│   │   │   └── PositionsList.tsx
│   │   ├── api.ts          # Backend API client
│   │   └── App.tsx
│   └── .env
└── infra/                   # Infrastructure
    ├── docker-compose.yml   # PostgreSQL + Adminer
    └── init.sql            # Database schema

🔧 Environment Variables

Backend (.env)

PORT=3001
HELIUS_API_KEY=your_helius_api_key_here
HELIUS_RPC=https://devnet.helius-rpc.com/?api-key=${HELIUS_API_KEY}
DATABASE_URL=postgres://orca:orca@localhost:5432/orcadata
ORCA_WHIRLPOOLS_PROGRAM_ID=whirLbMiicVdio4qvUfM5KAg6Ct8VwpYzGff3uctyCc

Frontend (.env)

VITE_API_URL=http://localhost:3001

📡 API Endpoints

Health Check

GET /health

Wallet Positions

GET /wallet/:publicKey

Position Details

GET /position/:nftMint

Helius Webhook

POST /webhook/helius

🗄️ Database Schema

-- Pools table
pools (id, token_a, token_b, fee_bps, tick_spacing, whirlpool_pubkey, last_slot_indexed)

-- Events table (webhook data)
events (id, pool_id, slot, ts, sig, kind, raw_json)

-- Positions table
positions (nft_mint, owner, pool_id, tick_lower, tick_upper, liquidity, created_slot, closed_slot)

-- Position fees table
position_fees (nft_mint, token_a_fees, token_b_fees, last_updated)

🧪 Testing

Test Backend

cd backend
npm run dev

# Test health endpoint
curl http://localhost:3001/health

# Test wallet endpoint (example key)
curl http://localhost:3001/wallet/11111111111111111111111111111112

Test Frontend

cd frontend
npm run dev
# Visit http://localhost:5173

🚀 Deployment

Production Deployment

Update environment variables for production
Set up SSL/TLS for webhook endpoints
Configure Helius webhook with production URL
Use a production database (not Docker for production)

VPS Deployment

# On your VPS
git clone <your-repo>
cd orca-mvp

# Start database
cd infra
docker compose up -d

# Build and start backend
cd ../backend
npm install
npm run build
npm start

# Build and serve frontend
cd ../frontend
npm install
npm run build
# Serve dist/ with nginx or similar

🔍 Troubleshooting

Common Issues

Database Connection Failed
- Ensure PostgreSQL is running: docker compose ps
- Check DATABASE_URL in .env file
Helius Webhook Not Working
- Verify webhook URL is publicly accessible
- Check Helius dashboard for webhook status
- Ensure ngrok is running for local development
No Positions Found
- Ensure wallet has positions on Solana Devnet
- Check if positions are created through Orca UI on devnet
- Verify Orca SDK configuration
Frontend API Errors
- Check backend is running on correct port
- Verify VITE_API_URL in frontend .env
- Check CORS configuration in backend

📋 MVP Deliverables Checklist

VPS with Docker + Compose running PostgreSQL + Adminer
Backend Express in Docker or Node, with .env configured
Webhook Helius (Devnet) apontando pro backend
/wallet/:pk retornando lista de NFTs de posição
Cálculo/quote de fees simples via SDK
Frontend React com input de public key e render do JSON
Demo ready: 1 carteira com 1+ posições em devnet

🛠️ Next Steps (Post-MVP)

Enhanced Orca SDK Integration
- Real position data fetching
- Accurate fee calculations
- Pool metadata integration
Real-time Updates
- WebSocket connections
- Live fee tracking
- Position change notifications
Advanced Features
- Phantom wallet integration
- Multiple DEX support (Raydium, Meteora)
- Historical analytics
Production Readiness
- Error handling & retry logic
- Rate limiting
- Monitoring & logging

📖 Learn More

🤝 Contributing

Fork the repository
Create a feature branch
Make your changes
Test thoroughly
Submit a pull request

📄 License

MIT License - see LICENSE file for details.

FilesExpand file tree

README.md

Latest commit

History