Skip to content

smart-contract.md

Latest commit

 

History

History
346 lines (259 loc) · 9.31 KB

smart-contract.md

File metadata and controls

346 lines (259 loc) · 9.31 KB

Smart Contract Documentation

Overview

The Collateral Vault smart contract is built using the Anchor framework on Solana. It provides secure, non-custodial management of USDT collateral for a decentralized perpetual futures exchange.

Program ID: ACU6ToU65HNU9nFbFzhA4BqZfZUFryri7UnhwS1FvxyH

Account Structures

CollateralVault

Main vault account storing user collateral and balance information.

pub struct CollateralVault {
    pub owner: Pubkey,              // Owner of the vault
    pub token_account: Pubkey,       // Associated token account holding USDT
    pub total_balance: u64,          // Total balance in vault
    pub locked_balance: u64,         // Locked balance (used as collateral)
    pub available_balance: u64,      // Available balance (total - locked)
    pub total_deposited: u64,        // Total amount ever deposited
    pub total_withdrawn: u64,        // Total amount ever withdrawn
    pub created_at: i64,             // Creation timestamp
    pub bump: u8,                    // PDA bump seed
}

PDA Derivation: [b"vault", user_pubkey]

Size: 137 bytes

VaultAuthority

Manages authorized programs that can lock/unlock collateral.

pub struct VaultAuthority {
    pub authorized_programs: Vec<Pubkey>,  // Authorized programs
    pub admin: Pubkey,                     // Admin pubkey
    pub bump: u8,                          // PDA bump seed
}

PDA Derivation: [b"vault_authority"]

Max Authorized Programs: 10

MultiSigVault

Multi-signature vault configuration requiring M-of-N signatures for withdrawals.

pub struct MultiSigVault {
    pub vault: Pubkey,           // Base vault account
    pub threshold: u8,           // Required signatures
    pub signers: Vec<Pubkey>,    // List of signers
    pub bump: u8,                // PDA bump seed
}

PDA Derivation: [b"multi_sig_vault", vault_pubkey]

SecurityConfig

Security configuration for enhanced protection.

pub struct SecurityConfig {
    pub vault: Pubkey,                      // Vault this config applies to
    pub withdrawal_delay: i64,              // Withdrawal delay in seconds
    pub withdrawal_whitelist: Vec<Pubkey>,  // Whitelisted addresses
    pub daily_withdrawal_limit: u64,        // Max withdrawal per day
    pub withdrawn_today: u64,               // Amount withdrawn today
    pub last_withdrawal_day: i64,           // Last withdrawal date
    pub paused: bool,                       // Emergency pause flag
    pub bump: u8,                           // PDA bump seed
}

PDA Derivation: [b"security_config", vault_pubkey]

Instructions

1. initialize_vault

Creates a new vault for a user.

Accounts:

  • owner (signer, mut): Vault owner
  • vault (mut): Vault PDA to initialize
  • mint: USDT mint
  • vault_token_account (mut): Associated token account for vault
  • token_program: SPL Token program
  • associated_token_program: Associated Token program
  • system_program: System program
  • rent: Rent sysvar

Arguments: None

Events Emitted: VaultInitialized

2. deposit

Deposits USDT collateral into vault.

Accounts:

  • user (signer, mut): User making deposit
  • vault (mut): User's vault PDA
  • owner: Vault owner (for validation)
  • user_token_account (mut): User's USDT token account
  • vault_token_account (mut): Vault's USDT token account
  • token_program: SPL Token program

Arguments:

  • amount: u64: Amount to deposit

CPI: Transfers tokens from user to vault

Events Emitted: DepositEvent

3. withdraw

Withdraws USDT collateral from vault.

Accounts:

  • user (signer, mut): User making withdrawal
  • vault (mut): User's vault PDA
  • owner: Vault owner
  • user_token_account (mut): User's USDT token account
  • vault_token_account (mut): Vault's USDT token account
  • token_program: SPL Token program

Arguments:

  • amount: u64: Amount to withdraw

Validations:

  • available_balance >= amount
  • No locked collateral preventing withdrawal

CPI: Transfers tokens from vault to user (with PDA signer)

Events Emitted: WithdrawalEvent

4. lock_collateral

Locks collateral for margin requirements (called by authorized programs).

Accounts:

  • caller_program: Program invoking this instruction
  • vault (mut): Vault to lock collateral in
  • vault_authority: Authority PDA

Arguments:

  • amount: u64: Amount to lock

Validations:

  • Caller is authorized
  • Sufficient available balance

Events Emitted: LockEvent

5. unlock_collateral

Unlocks collateral when position is closed.

Accounts:

  • caller_program: Program invoking this instruction
  • vault (mut): Vault to unlock collateral in
  • vault_authority: Authority PDA

Arguments:

  • amount: u64: Amount to unlock

Validations:

  • Caller is authorized
  • Sufficient locked balance

Events Emitted: UnlockEvent

6. transfer_collateral

Transfers collateral between vaults (for settlements/liquidations).

Accounts:

  • caller_program: Program invoking this instruction
  • from_vault (mut): Source vault
  • to_vault (mut): Destination vault
  • vault_authority: Authority PDA

Arguments:

  • amount: u64: Amount to transfer

Validations:

  • Caller is authorized
  • Sufficient available balance in source vault
  • No self-transfer

Events Emitted: TransferEvent

Error Codes

pub enum VaultError {
    InvalidAmount,                  // Invalid amount specified
    InsufficientBalance,            // Insufficient balance for operation
    Overflow,                       // Arithmetic overflow
    Underflow,                      // Arithmetic underflow
    Unauthorized,                   // Unauthorized program
    ProgramNotAuthorized,           // Program not authorized
    ProgramAlreadyAuthorized,       // Program already authorized
    TooManyAuthorizedPrograms,      // Too many authorized programs
    InvalidUnlockAmount,            // Invalid unlock amount
    HasLockedCollateral,            // Cannot withdraw with locked collateral
    InvalidVaultAuthority,          // Invalid vault authority
    InvalidTokenAccount,            // Invalid token account
    TokenAccountMismatch,           // Token account mismatch
    InvalidOwner,                   // Invalid owner
    DailyLimitExceeded,             // Daily withdrawal limit exceeded
    NotWhitelisted,                 // Address not whitelisted
    VaultPaused,                    // Vault operations paused
    WithdrawalDelayNotSatisfied,    // Withdrawal delay not satisfied
    // ... more error codes
}

Events

VaultInitialized

pub struct VaultInitialized {
    pub vault: Pubkey,
    pub owner: Pubkey,
    pub token_account: Pubkey,
    pub timestamp: i64,
}

DepositEvent

pub struct DepositEvent {
    pub vault: Pubkey,
    pub user: Pubkey,
    pub amount: u64,
    pub new_balance: u64,
    pub timestamp: i64,
}

WithdrawalEvent

pub struct WithdrawalEvent {
    pub vault: Pubkey,
    pub user: Pubkey,
    pub amount: u64,
    pub new_balance: u64,
    pub timestamp: i64,
}

LockEvent / UnlockEvent

pub struct LockEvent {
    pub vault: Pubkey,
    pub program: Pubkey,
    pub amount: u64,
    pub locked_balance: u64,
    pub available_balance: u64,
    pub timestamp: i64,
}

Cross-Program Invocation (CPI)

Calling the Vault Program

External programs can lock/unlock collateral via CPI:

use anchor_lang::prelude::*;

// In external program
pub fn open_position(ctx: Context<OpenPosition>, size: u64) -> Result<()> {
    // Calculate required collateral
    let collateral_needed = size / leverage;
    
    // CPI to lock collateral
    let cpi_program = ctx.accounts.vault_program.to_account_info();
    let cpi_accounts = LockCollateral {
        caller_program: ctx.program_id.to_account_info(),
        vault: ctx.accounts.vault.to_account_info(),
        vault_authority: ctx.accounts.vault_authority.to_account_info(),
    };
    let cpi_ctx = CpiContext::new(cpi_program, cpi_accounts);
    
    collateral_vault::cpi::lock_collateral(cpi_ctx, collateral_needed)?;
    
    // Open position logic...
    Ok(())
}

Authorization

Programs must be added to the authorized list:

# Add program to authorized list
anchor run add-program <PROGRAM_ID>

Security Considerations

  1. PDA Signer: Withdrawals use PDA as signer for token transfers
  2. Atomic Updates: All balance updates are atomic
  3. Overflow Protection: Checked arithmetic prevents overflow/underflow
  4. Authority Validation: Only authorized programs can lock/unlock
  5. Owner Validation: Only vault owner can deposit/withdraw
  6. Balance Verification: Always verify sufficient balance before operations

Testing

See tests/collateral-vault.ts for comprehensive test suite covering:

  • Vault initialization
  • Deposits and withdrawals
  • Collateral locking/unlocking
  • Multi-sig operations
  • Security features
  • Error cases

Integration Guide

For Position Management Programs

  1. Get authorized by vault authority admin
  2. Call lock_collateral when opening positions
  3. Call unlock_collateral when closing positions
  4. Call transfer_collateral for liquidations

For Frontend Applications

  1. Initialize vault for new users
  2. Use deposit/withdraw for fund management
  3. Query vault state for balance display
  4. Subscribe to events for real-time updates