Data Structure

turbos clmm

position_manager.move Core Structs

// Represents a burned position NFT, used as proof of position burn.
struct TurbosPositionBurnNFT has store, key {
    id: UID,                        // Unique identifier for the burn NFT object
    name: String,                   // Name of the burn NFT
    description: String,            // Description of the burn NFT
    img_url: Url,                   // Image URL for the burn NFT
    position_nft: TurbosPositionNFT,// The original position NFT being burned
    position_id: ID,                // ID of the position
    pool_id: ID,                    // ID of the pool this position belongs to
    coin_type_a: TypeName,          // Type of token A
    coin_type_b: TypeName,          // Type of token B
    fee_type: TypeName,             // Type of fee
}

// Stores reward information for a position.
struct PositionRewardInfo has store {
    reward_growth_inside: u128,     // Accumulated reward growth inside the position's tick range
    amount_owed: u64,               // Amount of reward owed to the position
}

// Represents a user's liquidity position in a pool.
struct Position has key, store {
    id: UID,                        // Unique identifier for the position
    tick_lower_index: I32,          // Lower tick index of the position's range
    tick_upper_index: I32,          // Upper tick index of the position's range
    liquidity: u128,                // Amount of liquidity provided
    fee_growth_inside_a: u128,      // Fee growth for token A inside the position's range
    fee_growth_inside_b: u128,      // Fee growth for token B inside the position's range
    tokens_owed_a: u64,             // Amount of token A owed to the position
    tokens_owed_b: u64,             // Amount of token B owed to the position
    reward_infos: vector<PositionRewardInfo>, // List of reward info for each reward type
}

// Stores all positions and NFT metadata for a user.
struct Positions has key, store {
    id: UID,                        // Unique identifier for the Positions object
    nft_minted: u64,                // Number of NFTs minted
    user_position: Table<address, ID>, // Mapping from NFT address to position ID
    nft_name: String,               // Name for the position NFT
    nft_description: String,        // Description for the position NFT
    nft_img_url: String,            // Image URL for the position NFT
}

pool.move Core Structs

// Stores version information for the pool.
struct Versioned has key, store {
    id: UID,                        // Unique identifier for the versioned object
    version: u64,                   // Version number
}

// Stores information about a single tick in the pool.
struct Tick has key, store {
    id: UID,                        // Unique identifier for the tick
    liquidity_gross: u128,          // Total liquidity at this tick
    liquidity_net: I128,            // Net liquidity change when crossing this tick
    fee_growth_outside_a: u128,     // Fee growth for token A outside this tick
    fee_growth_outside_b: u128,     // Fee growth for token B outside this tick
    reward_growths_outside: vector<u128>, // Reward growths outside this tick for each reward type
    initialized: bool,              // Whether this tick is initialized
}

// Read-only info for a tick, used for queries.
struct TickInfo has copy, drop {
    id: ID,                         // Tick ID
    tick_index: I32,                // Tick index
    liquidity_gross: u128,          // Total liquidity at this tick
    liquidity_net: I128,            // Net liquidity change at this tick
    fee_growth_outside_a: u128,     // Fee growth for token A outside this tick
    fee_growth_outside_b: u128,     // Fee growth for token B outside this tick
    reward_growths_outside: vector<u128>, // Reward growths outside this tick
    initialized: bool,              // Whether this tick is initialized
}

// Stores reward information for a position in the pool.
struct PositionRewardInfo has store {
    reward_growth_inside: u128,     // Accumulated reward growth inside the position's tick range
    amount_owed: u64,               // Amount of reward owed to the position
}

// Represents a user's liquidity position in the pool.
struct Position has key, store {
    id: UID,                        // Unique identifier for the position
    liquidity: u128,                // Amount of liquidity provided
    fee_growth_inside_a: u128,      // Fee growth for token A inside the position's range
    fee_growth_inside_b: u128,      // Fee growth for token B inside the position's range
    tokens_owed_a: u64,             // Amount of token A owed to the position
    tokens_owed_b: u64,             // Amount of token B owed to the position
    reward_infos: vector<PositionRewardInfo>, // List of reward info for each reward type
}

// Stores reward vault information for a specific reward coin.
struct PoolRewardVault<phantom RewardCoin> has key, store {
    id: UID,                        // Unique identifier for the reward vault
    coin: Balance<RewardCoin>,      // Balance of the reward coin in the vault
}

// Stores reward configuration for the pool.
struct PoolRewardInfo has key, store {
    id: UID,                        // Unique identifier for the reward info
    vault: address,                 // Address of the reward vault
    vault_coin_type: String,        // Type of the reward coin
    emissions_per_second: u128,     // Emission rate of the reward per second
    growth_global: u128,            // Global reward growth
    manager: address,               // Address of the reward manager
}

// The main pool struct, representing a CLMM pool.
struct Pool<phantom CoinTypeA, phantom CoinTypeB, phantom FeeType> has key, store {
    id: UID,                        // Unique identifier for the pool
    coin_a: Balance<CoinTypeA>,     // Balance of token A in the pool
    coin_b: Balance<CoinTypeB>,     // Balance of token B in the pool
    protocol_fees_a: u64,           // Protocol fees collected in token A
    protocol_fees_b: u64,           // Protocol fees collected in token B
    sqrt_price: u128,               // Current square root price of the pool
    tick_current_index: I32,        // Current tick index
    tick_spacing: u32,              // Tick spacing for the pool
    max_liquidity_per_tick: u128,   // Maximum liquidity allowed per tick
    fee: u32,                       // Fee rate for the pool
    fee_protocol: u32,              // Protocol fee rate
    unlocked: bool,                 // Whether the pool is unlocked for operations
    fee_growth_global_a: u128,      // Global fee growth for token A
    fee_growth_global_b: u128,      // Global fee growth for token B
    liquidity: u128,                // Current total liquidity in the pool
    tick_map: Table<I32, u256>,     // Mapping of tick index to tick word (bitmap)
    deploy_time_ms: u64,            // Deployment timestamp in milliseconds
    reward_infos: vector<PoolRewardInfo>, // List of reward info for each reward type
    reward_last_updated_time_ms: u64,// Last time rewards were updated (ms)
}

Summary

• Position-related structs (Position, Positions, TurbosPositionBurnNFT, PositionRewardInfo) are used to track user liquidity, NFT metadata, and reward accruals for each position.

• Pool-related structs (Pool, Tick, TickInfo, PoolRewardVault, PoolRewardInfo, Versioned) are used to manage the state of the pool, including liquidity, price, ticks, rewards, and protocol configuration.

• All fields are carefully designed to support efficient and precise accounting of liquidity, fees, and rewards in a concentrated liquidity market maker (CLMM) system.

• The use of generics and phantom types ensures type safety for different token and fee configurations.

• The separation of reward, fee, and position tracking allows for extensibility and robust management of user and protocol assets.