数据结构定义

本文档列出了 Coinfair CLMM 合约中所有主要的数据结构及其字段定义。

Pool

池子核心数据结构，存储了交易对的所有状态信息。

struct Pool has key {
    index: u64,                          // 池子索引
    collection_name: String,             // 位置NFT集合名称
    store_a: Object<FungibleStore>,       // 代币A的存储对象
    store_b: Object<FungibleStore>,       // 代币B的存储对象
    metadata_a: Object<Metadata>,         // 代币A的元数据对象
    metadata_b: Object<Metadata>,         // 代币B的元数据对象
    tick_spacing: u64,                    // tick间距
    fee_rate: u64,                        // 交易费率（分子，分母为1_000_000）
    liquidity: u128,                      // 当前tick索引处的总流动性
    current_fifrt_price: u128,            // 当前价格的平方根（Q64.64格式）
    current_tick_index: I64,              // 当前tick索引
    fee_growth_global_a: u128,            // 代币A的全局费用增长率（Q64.64格式）
    fee_growth_global_b: u128,            // 代币B的全局费用增长率（Q64.64格式）
    fee_protocol_coin_a: u64,             // 协议应收的代币A费用
    fee_protocol_coin_b: u64,             // 协议应收的代币B费用
    tick_indexes: Table<u64, BitVector>,  // tick索引位向量表
    ticks: Table<I64, Tick>,              // tick数据表
    rewarder_infos: vector<Rewarder>,     // 奖励器信息数组（最多3个）
    rewarder_last_updated_time: u64,      // 奖励器最后更新时间
    positions: Table<u64, Position>,       // 位置信息表
    position_index: u64,                  // 位置计数器
    is_pause: bool,                       // 池子是否暂停
    uri: String,                          // 位置NFT的URI
    signer_cap: account::SignerCapability // 池子账户的签名能力
}

PoolInfo

池子信息数据结构（用于视图函数返回），包含池子的所有可复制字段。

struct PoolInfo has copy, drop, store {
    index: u64,                           // 池子索引
    collection_name: String,              // 池子位置代币NFT集合名称
    metadata_a: Object<Metadata>,         // 代币A的元数据对象
    metadata_b: Object<Metadata>,         // 代币B的元数据对象
    tick_spacing: u64,                    // tick间距
    fee_rate: u64,                        // 交易费率的分子，分母为1_000_000
    liquidity: u128,                      // 当前tick索引处的总流动性
    current_fifrt_price: u128,            // 当前价格的平方根（Q64.64格式）
    current_tick_index: I64,              // 当前tick索引
    fee_growth_global_a: u128,            // 代币A的全局费用增长率（Q64.64格式）
    fee_growth_global_b: u128,            // 代币B的全局费用增长率（Q64.64格式）
    fee_protocol_coin_a: u64,             // 协议应收的代币A费用
    fee_protocol_coin_b: u64,             // 协议应收的代币B费用
    rewarder_infos: vector<Rewarder>,     // 奖励器信息数组
    rewarder_last_updated_time: u64,      // 奖励器最后更新时间
    position_index: u64,                  // 位置计数器
    is_pause: bool,                       // 池子是否暂停
    uri: String,                          // 位置NFT的URI
    initialized_ticks: vector<Tick>        // 所有已初始化的tick信息
}

Position

集中流动性位置数据结构，代表一个流动性提供者在特定价格区间内的流动性位置。

struct Position has copy, drop, store {
    pool: address,                        // 该位置所属的池子地址
    index: u64,                           // 位置的唯一标识符
    liquidity: u128,                      // 该位置提供的流动性数量
    tick_lower_index: I64,                // 位置的下边界tick索引
    tick_upper_index: I64,                // 位置的上边界tick索引
    fee_growth_inside_a: u128,            // 该位置内部代币A的费用增长率
    fee_owed_a: u64,                      // 该位置累计应得的代币A费用
    fee_growth_inside_b: u128,            // 该位置内部代币B的费用增长率
    fee_owed_b: u64,                      // 该位置累计应得的代币B费用
    rewarder_infos: vector<PositionRewarder> // 该位置的奖励器信息数组
}

Tick

集中流动性池子的tick数据结构，每个tick代表一个特定的价格点。

struct Tick has copy, drop, store {
    index: I64,                           // tick索引，对应特定的价格点
    fifrt_price: u128,                    // 该tick对应的价格平方根
    liquidity_net: I128,                   // 流动性净变化量（有符号）
    liquidity_gross: u128,                 // 流动性总量（无符号）
    fee_growth_outside_a: u128,           // 代币A在该tick外部的费用增长率
    fee_growth_outside_b: u128,           // 代币B在该tick外部的费用增长率
    rewarders_growth_outside: vector<u128> // 各个奖励器在该tick外部的增长率
}

Rewarder

流动性挖矿奖励器数据结构，负责管理流动性挖矿的奖励分配。

struct Rewarder has copy, drop, store {
    token: Object<Metadata>,              // 奖励代币的类型信息
    authority: address,                   // 奖励器的管理权限地址
    pending_authority: address,          // 待转移的权限地址
    emissions_per_second: u128,           // 每秒钟的奖励发放数量
    growth_global: u128                    // 全局奖励增长率
}

PositionRewarder

位置奖励器数据结构，记录每个位置在特定奖励器中的奖励分配情况。

struct PositionRewarder has drop, copy, store {
    growth_inside: u128,                   // 该位置内部的奖励增长率
    amount_owed: u64                       // 该位置累计应得的奖励数量
}

FlashSwapReceipt

闪电交换收据，用于记录闪电交换的关键信息。

struct FlashSwapReceipt {
    pool_address: address,                // 进行闪电交换的池子地址
    a2b: bool,                            // 交换方向：true表示A换B，false表示B换A
    pay_amount: u64                       // 需要支付的代币数量
}

AddLiquidityReceipt

添加流动性收据，用于添加流动性操作的两阶段提交。

struct AddLiquidityReceipt {
    pool_address: address,                // 操作的池子地址
    amount_a: u64,                        // 需要支付的代币A数量
    amount_b: u64                         // 需要支付的代币B数量
}

SwapResult

交换结果数据结构，记录一次交换操作的完整结果信息。

struct SwapResult has copy, drop {
    amount_in: u64,                       // 实际输入的代币数量
    amount_out: u64,                      // 实际输出的代币数量
    fee_amount: u64,                      // 支付的交易费用
    ref_fee_amount: u64                   // 合作伙伴推荐费用
}

CalculatedSwapResult

计算出的交换结果数据结构，包含交换操作的详细计算结果。

struct CalculatedSwapResult has copy, drop, store {
    amount_in: u64,                       // 计算的输入代币数量
    amount_out: u64,                      // 计算的输出代币数量
    fee_amount: u64,                      // 计算的交易费用
    fee_rate: u64,                        // 使用的费率
    after_fifrt_price: u128,              // 交换后的价格平方根
    is_exceed: bool,                      // 是否超出了价格限制
    step_results: vector<SwapStepResult>  // 每一步的交换结果详情
}

SwapStepResult

单步交换结果数据结构，记录交换过程中每一步的详细信息。

struct SwapStepResult has copy, drop, store {
    current_fifrt_price: u128,            // 当前步骤开始时的价格平方根
    target_fifrt_price: u128,             // 目标价格平方根
    current_liquidity: u128,               // 当前步骤的流动性
    amount_in: u64,                        // 该步骤的输入数量
    amount_out: u64,                       // 该步骤的输出数量
    fee_amount: u64,                       // 该步骤的费用
    remainer_amount: u64                  // 剩余未处理的数量
}

PoolId

池子ID，用于唯一标识一个池子。

struct PoolId has store, copy, drop {
    token_a: Object<Metadata>,            // 代币A类型
    token_b: Object<Metadata>,            // 代币B类型
    tick_spacing: u64                     // tick间距
}

FeeTier

费用等级数据结构。

struct FeeTier has store, copy, drop {
    tick_spacing: u64,                    // tick间距
    fee_rate: u64                         // 默认费率
}

GlobalConfig

CLMM池的全局配置。

struct GlobalConfig has key {
    protocol_authority: address,          // 协议权限地址
    protocol_pending_authority: address,  // 待转移的协议权限地址
    protocol_fee_claim_authority: address, // 协议费用领取权限地址
    pool_create_authority: address,       // 池子创建权限地址（@0x0表示任何人都可以创建）
    protocol_fee_rate: u64,               // 协议费率
    creator_fee_rate: u64,                // 创建者费率
    referrer_fee_rate: u64,                // 推荐者费率
    is_pause: bool                        // 协议是否暂停
}