# Optimus Protocol Architecture

## Program Structure

The Optimus protocol is organized into several key components:

### Core Components
- `lib.rs`: Main program entry point and instruction router
- `error.rs`: Custom error definitions for the protocol
- `state.rs`: Program state management and account structures

### Instruction Modules
The protocol's functionality is divided into three main instruction categories:

#### Admin Instructions
Located in `instructions/admin/`
- Protocol configuration
- Emergency controls
- System parameter management

#### Creator Instructions
Located in `instructions/creator/`
- Meme coin launch management
- Token configuration
- Initial liquidity setup

#### User Instructions
Located in `instructions/user/`
- Trading operations
- Vault interactions
- Referral system interactions

## State Management

The protocol uses several key state accounts:

1. Global State
   - Protocol-wide configuration
   - System parameters
   - Emergency controls

2. Bonding Curve State
   - Price curve parameters
   - Liquidity pool information
   - Trading statistics

3. Vault States
   - Alpha vault configurations
   - Deposit records
   - Claim status

4. User States
   - Trading positions
   - Referral relationships
   - Balance information

## Error Handling

The protocol implements a comprehensive error handling system with specific error types for:
- Authorization failures
- Invalid state transitions
- Trading restrictions
- Balance validations
- Protocol-specific conditions

## Security Model

The protocol implements a multi-level security model:
1. Account validation
2. Authorization checks
3. State transition validation
4. Balance verification
5. Emergency controls 

ARCHITECTURE

# Deployment Guide

This guide covers the deployment process for the Optimus Protocol on Solana's devnet and mainnet.

## Prerequisites

Before deploying, ensure you have:

1. **Solana Tool Suite**
   ```bash
   sh -c "$(curl -sSfL https://release.solana.com/v1.17.0/install)"
   ```

2. **Anchor Framework**
   ```bash
   cargo install --git https://github.com/coral-xyz/anchor avm --locked --force
   avm install latest
   avm use latest
   ```

3. **Node.js and Yarn**
   ```bash
   curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.0/install.sh | bash
   nvm install node
   npm install -g yarn
   ```

4. **Solana Wallet**
   - Create a new wallet: `solana-keygen new`
   - Configure for devnet: `solana config set --url devnet`
   - Get devnet SOL: `solana airdrop 2`

## Deployment Steps

### 1. Build the Program

```bash
# Build the program
anchor build

# Verify the build artifacts
ls target/deploy/
```

### 2. Configure Deployment

1. Update `Anchor.toml` with your program ID:
   ```toml
   [programs.devnet]
   optimus = "YOUR_PROGRAM_ID"
   ```

2. Ensure your wallet path is correct:
   ```toml
   [provider]
   wallet = "~/.config/solana/id.json"
   ```

### 3. Deploy to Devnet

```bash
# Deploy the program
anchor deploy

# Verify deployment
solana program show YOUR_PROGRAM_ID
```

### 4. Initialize the Program

The deployment script (`migrations/deploy.ts`) will automatically:
- Deploy the program
- Initialize the program state
- Set up the initial authority

### 5. Verify Deployment

1. Check program status:
   ```bash
   solana program show YOUR_PROGRAM_ID
   ```

2. Verify program logs:
   ```bash
   solana logs YOUR_PROGRAM_ID
   ```

## Deployment Configuration

### Environment Variables

The following environment variables can be configured:

- `ANCHOR_PROVIDER_URL`: Custom RPC endpoint
- `ANCHOR_WALLET`: Custom wallet path
- `ANCHOR_PROGRAM_ID`: Custom program ID

### Network Configuration

1. **Devnet**
   - URL: https://api.devnet.solana.com
   - Minimum SOL: 2 SOL for deployment

2. **Mainnet**
   - URL: https://api.mainnet-beta.solana.com
   - Minimum SOL: 5 SOL for deployment

## Post-Deployment

### 1. Program Verification

After deployment, verify:
- Program is deployed to the correct address
- Program is owned by the BPF Loader
- Program data is properly initialized

### 2. Security Checks

1. Verify program permissions
2. Check initial state setup
3. Validate authority configuration
4. Test emergency controls

### 3. Monitoring Setup

1. Set up program monitoring
2. Configure alert systems
3. Set up logging infrastructure

## Troubleshooting

### Common Issues

1. **Insufficient SOL**
   - Solution: Request more devnet SOL or fund mainnet wallet

2. **Build Failures**
   - Solution: Clean build with `anchor clean` and rebuild

3. **Deployment Timeouts**
   - Solution: Increase RPC timeout or use different RPC endpoint

4. **Program ID Mismatch**
   - Solution: Verify program ID in Anchor.toml matches deployed program

### Recovery Procedures

1. **Failed Deployment**
   ```bash
   # Clean and rebuild
   anchor clean
   anchor build
   anchor deploy
   ```

2. **Program Update**
   ```bash
   # Deploy new version
   anchor deploy --program-id YOUR_PROGRAM_ID
   ```

## Security Considerations

1. **Key Management**
   - Secure your deployment wallet
   - Use hardware wallets for mainnet
   - Implement multi-sig for critical operations

2. **Access Control**
   - Verify authority configurations
   - Implement proper access controls
   - Set up emergency controls

3. **Monitoring**
   - Set up program monitoring
   - Configure alert systems
   - Monitor program state

## Support

For deployment support:
- Open an issue on GitHub
- Join our Discord community
- Contact the development team

## Additional Resources

- [Solana Documentation](https://docs.solana.com)
- [Anchor Documentation](https://www.anchor-lang.com)
- [Program Security Best Practices](https://docs.solana.com/developing/security) 

DEPLOYMENT

# Optimus Protocol Error Handling

## Error Categories

### Authorization Errors
- `Unauthorized`: Thrown when an unauthorized account attempts a privileged operation
- `InvalidGlobal`: Thrown when the global account is invalid or not initialized
- `InvalidBondingCurve`: Thrown when the bonding curve account is invalid
- `InvalidReferral`: Thrown when the referral account is invalid

### State Errors
- `AlphaVaultClosed`: Thrown when attempting to deposit to a closed alpha vault
- `InvalidVaultAccount`: Thrown when the vault account is invalid
- `InvalidTreasury`: Thrown when the treasury account is invalid
- `VaultHasAlreadyGraduated`: Thrown when attempting to graduate an already graduated vault

### Trading Errors
- `BuyNotReady`: Thrown when attempting to buy before alpha phase completion
- `OverSlippage`: Thrown when transaction would exceed allowed slippage
- `PriceMustNotBeZero`: Thrown when price calculation results in zero
- `InvalidWsolAmountInput`: Thrown when wSOL amount doesn't match ATA balance

### Balance Errors
- `InsufficientLamport`: Thrown when insufficient lamports for rent
- `TokenAmountMustNotBeZero`: Thrown when token account has zero balance
- `AmountMustNotBeZero`: Thrown when account has zero balance
- `FailSumMatch`: Thrown when lamport sums don't match expected values

### Protocol State Errors
- `ProtocolHalted`: Thrown when protocol is in halted state
- `LamportTransferRequiredForSync`: Thrown when sync attempted without transfer
- `InstructionAlreadyCalled`: Thrown when instruction has already been called

## Error Handling Flow

### Pre-execution Validation
1. Account validation
   - Check account existence
   - Verify account ownership
   - Validate account data

2. State validation
   - Check protocol state
   - Verify trading conditions
   - Validate vault status

3. Balance validation
   - Check sufficient funds
   - Verify token balances
   - Validate reserve requirements

### Error Recovery

#### Automatic Recovery
- Transaction rollback
- State consistency checks
- Balance verification

#### Manual Recovery
- Emergency protocol halt
- Admin intervention
- State recovery procedures

## Error Prevention

### Input Validation
- Parameter bounds checking
- Account validation
- State transition validation

### State Protection
- Atomic transactions
- State consistency checks
- Balance verification

### Emergency Controls
- Protocol halt mechanism
- Emergency withdrawals
- State recovery procedures 

ERRORS

# Optimus Protocol Instructions

## Admin Instructions

### Protocol Management
- `init_global`: Initialize the protocol with initial parameters
  - Sets curve multiplier, graduation requirements, fees, and durations
  - Configures treasury and authority accounts
  - Initializes protocol state
- `update_global`: Update protocol configuration
  - Modifies curve parameters, fees, and durations
  - Updates treasury and authority settings
  - Can update protocol operational state
- `update_global_authority`: Update the global authority address
  - Only callable by current authority
  - Updates master and config authority

### Emergency Controls
- `emergency_withdraw`: Emergency fund withdrawal
- `pause_trading`: Pause trading operations
- `resume_trading`: Resume trading operations

## Creator Instructions

### Bonding Curve Management
- `init_bonding_curve`: Initialize a new bonding curve
  - Sets up referral system
  - Configures token metadata (name, symbol, URI)
  - Initializes curve parameters
  - Sets up initial pool state

### Pool Management
- `graduate_pool`: Graduate a pool from alpha to main phase
  - Validates graduation requirements
  - Updates pool status
  - Configures main trading parameters
  - Handles wrapped SOL conversions

### Meme Coin Launch
- `initialize_token`: Initialize new meme coin
- `setup_liquidity`: Set up initial liquidity pool
- `configure_bonding_curve`: Configure token bonding curve
- `set_launch_params`: Set launch parameters

### Vault Management
- `create_alpha_vault`: Create new alpha vault
- `configure_vault`: Configure vault parameters
- `update_vault_status`: Update vault status

## User Instructions

### Alpha Phase Operations
- `alpha_deposit`: Deposit SOL during alpha phase
  - Accepts SOL deposits
  - Records referral information
  - Updates alpha phase statistics
  - Validates deposit limits
- `alpha_claim`: Claim tokens after alpha phase
  - Validates claim eligibility
  - Processes token distribution
  - Updates claim status
  - Handles wrapped SOL conversions

### Trading Operations
- `buy`: Buy tokens from bonding curve
  - Calculates price using polynomial curve
  - Handles slippage protection
  - Updates balances and statistics
  - Processes wrapped SOL conversions
- `sell`: Sell tokens back to bonding curve
  - Calculates return amount
  - Validates minimum output
  - Updates pool state
  - Handles wrapped SOL conversions

### Fee Management
- `claim_fees`: Claim accumulated fees
  - Validates claim eligibility
  - Processes fee distribution
  - Updates fee tracking
  - Handles wrapped SOL conversions

### Treasury Operations
- `transfer_bonding_sol`: Transfer SOL from bonding curve to treasury
  - Validates transfer requirements
  - Updates pool balances
  - Handles wrapped SOL conversions

### Vault Operations
- `deposit_to_vault`: Deposit to alpha vault
- `claim_from_vault`: Claim from alpha vault
- `graduate_vault`: Graduate vault to main trading

### Referral System
- `set_referral`: Set referral relationship
- `claim_referral_rewards`: Claim referral rewards
- `update_referral_status`: Update referral status

## Instruction Flow

### Trading Flow
1. User initiates trade
2. Protocol validates:
   - Account authorization
   - Balance sufficiency
   - Trading restrictions
   - Slippage limits
   - Wrapped SOL balance
3. Execute trade through polynomial curve
4. Update state and balances
5. Process fees and rewards
6. Handle wrapped SOL conversions
7. Emit events

### Alpha Phase Flow
1. User deposits to alpha vault
2. Protocol validates:
   - Vault status
   - Deposit limits
   - User eligibility
   - Alpha phase timing
   - Wrapped SOL balance
3. Process deposit
4. Update vault state
5. Track alpha phase progress
6. Handle wrapped SOL conversions
7. Emit events

### Graduation Flow
1. Creator initiates graduation
2. Protocol validates:
   - Graduation requirements
   - Pool status
   - Authority permissions
   - Wrapped SOL balance
3. Update pool status
4. Configure main trading
5. Initialize bonding curve
6. Handle wrapped SOL conversions
7. Emit events 

INSTRUCTIONS

# Optimus Protocol State Management

## Account Structures

### Global State
```rust
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
```rust
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
```rust
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 