Optimus Protocol State Management

Account Structures

Global State

pub struct Global {
    pub master_authority: Pubkey,                // Authority with highest privileges
    pub config_authority: Pubkey,                // Authority for configuration changes
    pub treasury: Pubkey,                        // Treasury wallet for protocol fees
    pub curve_multiplier: u64,                   // Multiplier for bonding curve calculations
    pub graduation_lamport_amount: u64,          // Required SOL for pool graduation
    pub alpha_duration: u32,                     // Duration of alpha phase in seconds
    pub fee_bps: u16,                            // Protocol fee in basis points
    pub creator_share_bps: u16,                  // Creator's share of fees in basis points
    pub user_share_bps: u16,                     // User's share of fees in basis points
    pub protocol_state: ProgramOperationalState, // Current operational state
    pub bump: u8,                                // PDA bump seed
    pub version: u8,                             // Protocol version
    pub _padding: [u8; 3],                       // Padding for alignment
    pub _reserved: [u8; 256],                    // Reserved space for future fields
}

Bonding Curve State

pub struct BondingCurve {
    pub initializer: Pubkey,       // Creator of the bonding curve
    pub referral: Pubkey,          // Referral address for rewards
    pub total_volume: u64,         // Total trading volume
    pub fees: u64,                 // Accumulated fees
    pub alpha_deposit: u64,        // Total deposits during alpha phase
    pub alpha_token_sold: u64,     // Tokens sold during alpha phase
    pub alpha_amount_claimed: u64, // Amount claimed after alpha phase
    pub lamport_per_token: u64,    // Price per token in lamports
    pub alpha_launch_time: u64,    // Timestamp of alpha phase start
    pub wsol_pool_amount: u64,     // Amount of wrapped SOL in pool
    pub graduated: bool,           // Whether pool has graduated from alpha
    pub bump: u8,                  // PDA bump seed
    pub version: u8,               // Protocol version
    pub _padding: [u8; 5],         // Padding for alignment
    pub _reserved: [u8; 128],      // Reserved space for future fields
}

User Deposit State

pub struct UserDeposit {
    pub owner: Pubkey,      // Owner of the deposit
    pub mint: Pubkey,       // Token mint address
    pub referral: Pubkey,   // Referral address
    pub alpha_deposit: u64, // Amount deposited during alpha
    pub claimed: bool,      // Whether tokens have been claimed
    pub bump: u8,           // PDA bump seed
    pub version: u8,        // Protocol version
    pub _padding: [u8; 5],  // Padding for alignment
    pub _reserved: [u8; 128], // Reserved space for future fields
}

State Transitions

Trading State

1. Pre-trade validation

   • Check account balances
   • Verify authorization
   • Validate trading parameters
   • Check slippage limits
   • Verify wrapped SOL balance

2. Trade execution

   • Calculate price using polynomial curve
   • Update bonding curve state
   • Modify user balances
   • Update trading statistics
   • Handle wrapped SOL conversions
   • Process fees and rewards

3. Post-trade updates

   • Emit events
   • Update global statistics
   • Process fees
   • Update referral rewards
   • Verify state consistency

Alpha Phase State

1. Deposit phase

   • Validate deposit parameters
   • Update vault balance
   • Record deposit information
   • Track alpha phase timing
   • Handle wrapped SOL conversions

2. Claim phase

   • Verify claim eligibility
   • Process claim
   • Update vault status
   • Handle wrapped SOL conversions
   • Update user deposit state

3. Graduation phase

   • Validate graduation requirements
   • Update vault status
   • Initialize main trading
   • Set up bonding curve parameters
   • Handle wrapped SOL conversions

State Validation

Account Validation

• Verify account ownership
• Check account initialization
• Validate account data size
• Verify PDA derivation
• Check version compatibility

Balance Validation

• Check sufficient funds
• Verify token balances
• Validate reserve requirements
• Check wrapped SOL balances
• Verify fee calculations

Authorization Validation

• Verify admin permissions
• Check user authorization
• Validate creator rights
• Verify referral relationships
• Check operational state

State Recovery

Emergency Procedures

• Protocol halt mechanism
• Emergency withdrawals
• State recovery procedures
• Wrapped SOL recovery
• Fee recovery

Error Recovery

• Transaction rollback
• State consistency checks
• Error state handling
• Balance verification
• Wrapped SOL verification