Skip to content

architecture.md

Latest commit

 

History

History
316 lines (267 loc) · 12.6 KB

architecture.md

File metadata and controls

316 lines (267 loc) · 12.6 KB

Collateral Vault Management System - Architecture

System Overview

The Collateral Vault Management System is a comprehensive Solana-based solution for managing user collateral in a decentralized perpetual futures exchange. It provides secure, non-custodial vault management with support for deposits, withdrawals, collateral locking, and advanced features like multi-signature vaults and security configurations.

Architecture Diagram

┌─────────────────────────────────────────────────────────────────┐
│                         Frontend/Client                          │
└───────────────┬─────────────────────────────────┬───────────────┘
                │                                 │
                │ HTTP/REST                       │ WebSocket
                │                                 │
┌───────────────▼─────────────────────────────────▼───────────────┐
│                    Backend Service (Rust)                        │
│  ┌──────────────┐  ┌──────────────┐  ┌──────────────┐          │
│  │ REST API     │  │ WebSocket    │  │ Vault        │          │
│  │ (Axum)       │  │ Server       │  │ Monitor      │          │
│  └──────────────┘  └──────────────┘  └──────────────┘          │
│  ┌──────────────┐  ┌──────────────┐  ┌──────────────┐          │
│  │ Vault        │  │ Balance      │  │ Transaction  │          │
│  │ Manager      │  │ Tracker      │  │ Builder      │          │
│  └──────────────┘  └──────────────┘  └──────────────┘          │
│  ┌──────────────┐  ┌──────────────┐                            │
│  │ CPI Manager  │  │ Database     │                            │
│  │              │  │ Client       │                            │
│  └──────────────┘  └──────────────┘                            │
└───────────────┬─────────────────────────────────┬───────────────┘
                │                                 │
                │ Transactions                    │ Queries
                │                                 │
┌───────────────▼─────────────────────────────────▼───────────────┐
│                    Solana Blockchain                             │
│  ┌──────────────────────────────────────────────────────┐      │
│  │         Collateral Vault Program (Anchor)            │      │
│  │  ┌────────────┐  ┌────────────┐  ┌────────────┐     │      │
│  │  │ Vault      │  │ Multi-Sig  │  │ Security   │     │      │
│  │  │ Operations │  │ Support    │  │ Features   │     │      │
│  │  └────────────┘  └────────────┘  └────────────┘     │      │
│  └───────────────────────┬──────────────────────────────┘      │
│                          │ CPI                                  │
│  ┌───────────────────────▼──────────────────────────────┐      │
│  │            SPL Token Program                         │      │
│  └──────────────────────────────────────────────────────┘      │
└──────────────────────────────────────────────────────────────────┘
                          │
┌─────────────────────────▼───────────────────────────┐
│              PostgreSQL Database                    │
│  - Vaults                - Balance Snapshots        │
│  - Transactions          - Reconciliation Logs      │
│  - Audit Trail                                      │
└─────────────────────────────────────────────────────┘

Component Interactions

1. Smart Contract Layer (Anchor Program)

Purpose: On-chain logic for vault management and collateral operations.

Key Components:

  • Vault Operations: Initialize, deposit, withdraw
  • Collateral Management: Lock, unlock, transfer
  • Authority Management: Authorized programs for CPIs
  • Multi-Sig Support: Multi-signature vault operations
  • Security Features: Withdrawal delays, whitelists, rate limiting

PDAs (Program Derived Addresses):

  • vault: [b"vault", user_pubkey]
  • vault_authority: [b"vault_authority"]
  • multi_sig_vault: [b"multi_sig_vault", vault_pubkey]
  • security_config: [b"security_config", vault_pubkey]
  • pending_withdrawal: [b"pending_withdrawal", vault_pubkey, timestamp]

2. Backend Service

Purpose: Off-chain orchestration, transaction building, and monitoring.

Modules:

Vault Manager

  • Creates and manages vault accounts
  • Builds deposit/withdrawal transactions
  • Queries vault state
  • Maintains transaction history

Balance Tracker

  • Real-time monitoring of vault balances
  • Reconciliation between on-chain and database state
  • Discrepancy detection and alerting
  • Balance snapshots for analytics

Transaction Builder

  • Constructs Anchor instructions
  • Handles compute budget optimization
  • Manages priority fees
  • Builds multi-instruction transactions

CPI Manager

  • Interface for external programs
  • Lock/unlock collateral for positions
  • Transfer collateral for settlements/liquidations
  • Error handling and retry logic

Vault Monitor

  • Continuous system monitoring
  • TVL calculation
  • Analytics generation
  • Unusual activity detection

3. Database Layer (PostgreSQL)

Schema:

vaults (
  - user_pubkey
  - vault_pubkey
  - total_balance, locked_balance, available_balance
  - created_at, updated_at
)

transactions (
  - vault_pubkey
  - tx_type (deposit, withdrawal, lock, unlock, transfer)
  - amount
  - signature
  - timestamp
)

balance_snapshots (
  - vault_pubkey
  - total_balance, locked_balance
  - snapshot_time
)

reconciliation_logs (
  - vault_pubkey
  - expected_balance, actual_balance, discrepancy
  - timestamp
)

audit_trail (
  - action
  - vault_pubkey, user_pubkey
  - details
  - timestamp
)

4. API Layer

REST Endpoints:

  • POST /vault/initialize - Create new vault
  • POST /vault/deposit - Deposit collateral
  • POST /vault/withdraw - Withdraw collateral
  • GET /vault/balance/:user - Get vault balance
  • GET /vault/transactions/:user - Transaction history
  • GET /vault/tvl - Total value locked
  • GET /vault/stats - System statistics

WebSocket Events:

  • balance_update - Real-time balance changes
  • deposit / withdrawal - Transaction notifications
  • lock / unlock - Collateral state changes
  • tvl_update - System-wide TVL updates

Data Flow

Deposit Flow

1. User initiates deposit via API
   ↓
2. Backend validates request
   ↓
3. Transaction Builder creates deposit instruction
   ↓
4. Transaction sent to Solana
   ↓
5. Smart contract validates and executes:
   - SPL Token CPI transfer (user → vault)
   - Update vault state
   - Emit deposit event
   ↓
6. Backend records transaction in database
   ↓
7. WebSocket broadcasts balance update
   ↓
8. Balance Tracker reconciles state

Withdrawal Flow

1. User initiates withdrawal via API
   ↓
2. Backend checks available balance
   ↓
3. (If security config exists) Check:
   - Withdrawal delay
   - Daily limit
   - Whitelist
   ↓
4. Transaction Builder creates withdrawal instruction
   ↓
5. Transaction sent to Solana
   ↓
6. Smart contract validates and executes:
   - Verify available balance
   - SPL Token CPI transfer (vault → user) with PDA signer
   - Update vault state
   - Emit withdrawal event
   ↓
7. Backend records transaction in database
   ↓
8. WebSocket broadcasts balance update

Lock/Unlock Flow (CPI from External Program)

1. External program (e.g., Position Manager) calls lock_collateral
   ↓
2. Smart contract verifies:
   - Caller is authorized
   - Sufficient available balance
   ↓
3. Update vault state:
   - Increment locked_balance
   - Decrement available_balance
   ↓
4. Emit lock event
   ↓
5. Backend monitors event and updates database

Security Model

On-Chain Security

  1. PDA-Based Ownership: Vaults are PDAs owned by the program, ensuring non-custodial control
  2. Authority Validation: Only authorized programs can lock/unlock collateral
  3. Balance Checks: All operations validate sufficient balance
  4. Overflow Protection: Checked arithmetic prevents overflow/underflow
  5. Multi-Sig Support: Optional multi-signature requirement for withdrawals

Off-Chain Security

  1. Database Isolation: User funds tracked separately
  2. Reconciliation: Continuous verification of on-chain vs. database state
  3. Audit Trail: All operations logged for forensic analysis
  4. Rate Limiting: API rate limits to prevent abuse
  5. Monitoring: Real-time alerts on unusual activity

Advanced Security Features

  1. Withdrawal Delay: Time-lock mechanism for withdrawals
  2. Whitelist: Restrict withdrawals to approved addresses
  3. Daily Limits: Cap maximum daily withdrawal amounts
  4. Emergency Pause: Admin can pause vault operations
  5. Proposal System: Multi-sig vault withdrawal proposals with expiry

Scalability Considerations

  1. Database Indexing: Optimized queries with proper indexes
  2. Compute Budget: Configurable compute units for complex transactions
  3. Batch Processing: Support for batch operations (future enhancement)
  4. Caching: Balance caching to reduce RPC calls
  5. Horizontal Scaling: Stateless backend services can be load-balanced

Deployment Architecture

Production Deployment:

┌─────────────────┐
│   Load Balancer │
└────────┬────────┘
         │
    ┌────┴────┐
    │         │
┌───▼────┐ ┌─▼──────┐
│Backend │ │Backend │
│Node 1  │ │Node 2  │
└───┬────┘ └─┬──────┘
    │        │
    └───┬────┘
        │
┌───────▼────────┐
│   PostgreSQL   │
│   (Primary +   │
│   Replicas)    │
└────────────────┘

External:
- Solana RPC Nodes (Mainnet/Devnet)
- WebSocket Proxy for real-time updates

Performance Metrics

Target Performance:

  • Vault operations: < 2 seconds
  • Balance queries: < 50ms
  • Throughput: 100+ operations/second
  • Support: 10,000+ concurrent vaults
  • Uptime: 99.9%

Future Enhancements

  1. Yield Integration: Auto-deposit idle collateral into lending protocols
  2. Compressed Accounts: Reduce storage costs with account compression
  3. Cross-Chain Support: Bridge to other blockchains
  4. Advanced Analytics: ML-based fraud detection
  5. Mobile SDK: Native mobile library for vault management