> For the complete documentation index, see [llms.txt](https://surgeai.gitbook.io/docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://surgeai.gitbook.io/docs/technical/price-oracle.md).

# Price Oracle

### 🎯 Purpose of Price Monitoring

#### Why Monitor Prices?

* **Real-time Valuation**: Get current market value of tokens
* **FDV Calculation**: Calculate FDV based on actual market prices
* **Milestone Triggering**: Automatically trigger milestones when price targets are reached
* **Market Transparency**: Provide transparent and verifiable price data

#### Core Principles

1. **On-chain Price Discovery**: Prices sourced directly from Cetus liquidity pools
2. **Real-time Updates**: Continuous monitoring of price changes
3. **Automated Triggers**: Automatic milestone progression based on price targets
4. **Transparent Calculation**: All calculations performed on-chain and verifiable

### 📊 Price Monitoring Architecture

#### Data Flow

```
Cetus Liquidity Pool
    ↓
Price Oracle (sqrt_price)
    ↓
FDV Calculation Engine
    ↓
Milestone Trigger System
    ↓
Token Unlocking
```

#### Key Components

* **Cetus Pool**: Source of real-time price data
* **Price Oracle**: Extracts sqrt\_price from pool
* **FDV Calculator**: Converts price to FDV
* **Milestone Engine**: Determines unlocking based on FDV

### 🔧 Technical Implementation

#### Price Extraction from Cetus

**Get Token Price Function**

```move
public entry fun get_token_price<CoinTypeA, CoinTypeB>(
    pool: &Pool<CoinTypeA, CoinTypeB>
): u128 {
    pool::current_sqrt_price(pool)
}
```

**Price Calculation Process**

1. **Extract sqrt\_price**: Get square root price from Cetus pool
2. **Calculate FDV**: Convert sqrt\_price to FDV using supply
3. **Compare Targets**: Check if current FDV meets milestone targets
4. **Trigger Unlocking**: Automatically unlock tokens if targets are met

#### FDV Calculation from Price

**Current FDV Calculation**

```move
// Get current sqrt_price from pool
let sqrt_price = cetus::get_token_price(pool);

// Use pre-calculated sqrt supply
let sqrt_supply = milestone_constants::get_max_sqrt_supply();

// Calculate current sqrt_fdv
let current_sqrt_fdv = (sqrt_price * (sqrt_supply as u128)) / SQRT_PRECISION;
```

**Mathematical Formula**

```
current_sqrt_fdv = (sqrt_price × sqrt_supply) / precision
real_fdv = current_sqrt_fdv²
```

### 📈 Price Monitoring Workflow

#### 1. Real-time Price Monitoring

* **Continuous Monitoring**: System constantly monitors pool prices
* **Price Updates**: New prices trigger FDV recalculations
* **Event Emission**: Price changes emit events for tracking

#### 2. FDV Calculation

* **Price Input**: Current sqrt\_price from Cetus pool
* **Supply Factor**: Maximum token supply (1B tokens)
* **Precision Handling**: 6-digit precision for accuracy
* **FDV Output**: Calculated FDV in SUI

#### 3. Milestone Comparison

* **Target Check**: Compare current FDV with milestone targets
* **Progress Calculation**: Determine milestone completion percentage
* **Trigger Decision**: Decide if milestone should be triggered

#### 4. Automatic Unlocking

* **Milestone Achievement**: When FDV reaches target
* **Token Release**: Automatically unlock tokens
* **Event Emission**: Emit unlocking events

### 🔄 Price Update Process

#### Update Milestone Function

```move
public fun update_milestone<Token, USDA>(
    self: &mut Wallet<Token, USDA>,
    pool: &mut Pool<Token, USDA>,
    _: &LaunchAdmin,
) {
    // Get current sqrt_price
    let sqrt_price = cetus::get_token_price(pool);
    
    // Calculate current sqrt_fdv
    let sqrt_supply = milestone_constants::get_max_sqrt_supply();
    let current_sqrt_fdv = (sqrt_price * (sqrt_supply as u128)) / SQRT_PRECISION;
    
    // Get target sqrt_fdv for current round
    let target_sqrt_fdv = milestone_constants::get_sqrt_fdv_target(self.milestone_round);
    
    // Check if milestone is achieved
    if (current_sqrt_fdv >= (target_sqrt_fdv as u128)) {
        // Advance to next round
        self.milestone_round = self.milestone_round + 1;
        
        // Calculate unlock percentage
        let round_unlock = milestone_constants::get_unlock_percentage(self.milestone_round - 1);
        self.current_unlock_percentage = self.current_unlock_percentage + round_unlock;
        
        // Cap at 100%
        if (self.current_unlock_percentage > 100) {
            self.current_unlock_percentage = 100;
        };
    };
    
    // Emit update event
    let current_real_fdv = milestone_constants::sqrt_fdv_to_real_fdv((current_sqrt_fdv as u64));
    let target_real_fdv = milestone_constants::sqrt_fdv_to_real_fdv(target_sqrt_fdv);
    
    emit(MilestoneUpdated {
        project_id: self.project_id,
        milestone_round: self.milestone_round,
        current_unlock_percentage: self.current_unlock_percentage,
        current_sqrt_fdv: (current_sqrt_fdv as u64),
        target_sqrt_fdv: target_sqrt_fdv,
        current_real_fdv: current_real_fdv,
        target_real_fdv: target_real_fdv,
    });
}
```

### 📊 Price Monitoring Queries

#### Get Current Price Information

```move
// Get current sqrt_fdv
public fun get_current_sqrt_fdv<T, R>(
    self: &Wallet<T, R>, 
    pool: &Pool<T, R>
): u64 {
    let sqrt_price = cetus::get_token_price(pool);
    let sqrt_supply = milestone_constants::get_max_sqrt_supply();
    let current_sqrt_fdv = (sqrt_price * (sqrt_supply as u128)) / SQRT_PRECISION;
    (current_sqrt_fdv as u64)
}
```

#### Get Milestone Progress

```move
// Get milestone progress
public fun get_milestone_progress<T, R>(
    self: &Wallet<T, R>,
    pool: &Pool<T, R>
): (u64, u64, u8) {
    let current_sqrt_fdv = get_current_sqrt_fdv(self, pool);
    let target_sqrt_fdv = get_next_milestone_target(self);
    (current_sqrt_fdv, target_sqrt_fdv, self.milestone_round)
}
```

#### Get Debug Information

```move
// Get detailed debug info
public fun get_debug_info<T, R>(
    self: &Wallet<T, R>,
    pool: &Pool<T, R>
): (u64, u64, u64, u64, u8) {
    let current_sqrt_fdv = get_current_sqrt_fdv(self, pool);
    let target_sqrt_fdv = get_next_milestone_target(self);
    let current_real_fdv = milestone_constants::sqrt_fdv_to_real_fdv(current_sqrt_fdv);
    let target_real_fdv = milestone_constants::sqrt_fdv_to_real_fdv(target_sqrt_fdv);
    
    (current_sqrt_fdv, target_sqrt_fdv, current_real_fdv, target_real_fdv, self.milestone_round)
}
```

### ⚡ Performance Optimization

#### Square Root Price Usage

* **Stability**: Using sqrt\_price prevents overflow in calculations
* **Precision**: Maintains high precision for accurate FDV calculation
* **Efficiency**: Optimized for on-chain computation

#### Batch Processing

* **Multiple Updates**: Process multiple wallets simultaneously
* **Gas Efficiency**: Reduce transaction costs
* **Atomic Operations**: Ensure consistency across updates

### 🔗 Integration with Cetus

#### Cetus Pool Integration

* **Liquidity Pool**: Token pairs traded on Cetus
* **Price Oracle**: Real-time price feed from pool
* **AMM Mechanism**: Automated market maker for price discovery
* **Liquidity Provision**: Encourages liquidity provision

#### Pool Management

* **Pool Creation**: Automatic pool creation for new tokens
* **Liquidity Addition**: Initial liquidity provision
* **Price Stability**: Maintain price stability through liquidity
* **Market Making**: Automated market making through AMM

***

**Note**: The price monitoring system provides real-time, transparent, and automated token unlocking based on market performance. All price data is sourced from verified Cetus liquidity pools and calculations are performed on-chain for maximum transparency and security.