Collateral Vault Management System

A secure, non-custodial collateral vault management system for decentralized perpetual futures exchanges built on Solana.

Overview

This system provides a foundation for managing user collateral (USDT) in program-controlled vaults, enabling secure deposits, withdrawals, and cross-program invocations for trading operations.

Architecture

Components

1. Anchor Program (programs/collateral_vault/)

   • Solana smart contract for vault management
   • PDA-based vault accounts
   • SPL Token integration
   • Cross-program invocation support

2. Rust Backend Service (backend/)

   • Vault management service
   • Balance tracking and reconciliation
   • REST API endpoints
   • WebSocket streams for real-time updates
   • Database integration (PostgreSQL)

3. Database Schema

   • Vault records
   • Transaction history
   • Balance snapshots

Features

• ✅ Secure PDA-based vault accounts
• ✅ Deposit and withdraw collateral
• ✅ Lock/unlock collateral for positions
• ✅ Transfer collateral between vaults
• ✅ Real-time balance tracking
• ✅ Transaction history
• ✅ Total Value Locked (TVL) tracking
• ✅ WebSocket support for real-time updates

Setup

Prerequisites

• Rust 1.75+
• Anchor 0.30.1+
• Solana CLI tools (including solana-test-validator and spl-token)
• PostgreSQL (optional for localnet, required for backend)
• Node.js (for tests)

Installation

1. Clone the repository:

git clone <repository-url>
cd GoQuant

2. Install dependencies:

# Install Anchor
cargo install --git https://github.com/coral-xyz/anchor avm --locked --force
avm install latest
avm use latest

# Build the program
anchor build

3. Set up the database:

# Create PostgreSQL database
createdb vault_db

# Set environment variables
export DATABASE_URL="postgresql://localhost/vault_db"
export SOLANA_RPC_URL="https://api.devnet.solana.com"
export PROGRAM_ID="<your-program-id>"
export USDT_MINT="<usdt-mint-address>"

4. Run migrations:

cd backend
cargo run --bin migrate

5. Start the backend server:

cd backend
cargo run

Localnet Setup (Development & Testing)

The system can run entirely on Solana localnet with fake SOL and fake USDT tokens. This uses REAL Solana programs, REAL PDAs, and REAL transactions - it's not a mock.

Quick Start (Localnet)

1. Setup localnet environment:

./scripts/setup_localnet.sh

This script will:

• Start solana-test-validator on port 8899
• Create a fake USDT SPL token mint
• Fund test accounts with fake SOL and USDT
• Generate .env.localnet configuration file

2. Deploy the program:

anchor deploy --provider.cluster localnet

3. Start the backend (in localnet mode):

cd backend
source ../.env.localnet
cargo run

4. Run the demo:

./scripts/demo_localnet.sh

Localnet Features

• ✅ Unlimited fake SOL - No need to worry about fees
• ✅ Fake USDT mint - Locally deployed SPL token
• ✅ Real transactions - Uses actual Solana programs
• ✅ Real PDAs - Same derivation as mainnet/devnet
• ✅ Real CPIs - Actual cross-program invocations
• ✅ Identical logic - No code changes, same security

Localnet Configuration

After running setup_localnet.sh, you'll have:

• .env.localnet - Configuration file with all addresses
• .localnet_usdt_mint.json - Fake USDT mint keypair
• .localnet_test_user.json - Test user keypair
• .validator.pid - Validator process ID

Stopping Localnet

./scripts/stop_localnet.sh

Or manually:

kill $(cat .validator.pid)

Localnet vs Devnet/Mainnet

Feature	Localnet	Devnet/Mainnet
SOL	Unlimited fake	Real (limited)
USDT	Fake mint	Real USDT mint
RPC	http://127.0.0.1:8899	Public RPC
Speed	Instant	Network dependent
Cost	Free	Transaction fees
Logic	Identical	Identical

Important: The Anchor program code is identical for localnet and mainnet. Only the mint address changes, which is passed as a parameter (no code changes needed).

Usage

Initialize a Vault

curl -X POST http://localhost:3000/vault/initialize \
  -H "Content-Type: application/json" \
  -d '{"user": "<user-public-key>"}'

Deposit Collateral

curl -X POST http://localhost:3000/vault/deposit \
  -H "Content-Type: application/json" \
  -d '{
    "user": "<user-public-key>",
    "amount": 1000000000
  }'

Withdraw Collateral

curl -X POST http://localhost:3000/vault/withdraw \
  -H "Content-Type: application/json" \
  -d '{
    "user": "<user-public-key>",
    "amount": 500000000
  }'

Get Balance

curl http://localhost:3000/vault/balance/<user-public-key>

Get Transactions

curl http://localhost:3000/vault/transactions/<user-public-key>

Get TVL

curl http://localhost:3000/vault/tvl

API Endpoints

Method	Endpoint	Description
POST	/vault/initialize	Initialize a new vault
POST	/vault/deposit	Deposit collateral
POST	/vault/withdraw	Withdraw collateral
GET	/vault/balance/:user	Get vault balance
GET	/vault/transactions/:user	Get transaction history
GET	/vault/tvl	Get total value locked
GET	/ws	WebSocket connection

Testing

Run Anchor Tests

anchor test

Run Backend Tests

cd backend
cargo test

Security

• All vault operations are secured with PDA-based accounts
• Only vault owners can withdraw
• Only authorized programs can lock/unlock collateral
• Integer overflow/underflow protection
• Atomic state updates

Documentation

See docs/ for detailed documentation:

• Architecture
• API Reference
• Deployment Guide
• Security Analysis

License

MIT