@cetusprotocol/aggregator-sdk 1.2.0 → 1.3.0

package/docs/Cetus_Aggregator_V3_/346/216/245/345/217/243/346/226/207/346/241/243.md

@@ -1,706 +0,0 @@
-# Cetus Aggregator V3 合约接口文档
-
-## 概述
-
-Cetus Aggregator V3 是一个去中心化交易聚合器，通过整合多个 DEX 的流动性来为用户提供最优的交易路径。系统采用分层架构，包含 Move 合约层和 Rust 服务层。
-
-**合约地址**: `0x55317429b88dccaeaba11c5c528d74ce07f3dadf6068727a2a315ac2c104edd2`
-
-## 核心架构
-
-### 1. 核心合约模块
-
-#### `aggregator_v3::router`
-
-核心路由合约，负责管理交易上下文和执行确认。
-
-#### `aggregator_v3::errors`
-
-错误定义模块，包含所有错误代码。
-
-### 2. 支持的 DEX 列表
-
-当前版本支持以下 DEX：
-
-- **CETUS** - CLMM 协议
-- **KRIYA** - AMM 和 CLMM
-- **DEEPBOOKV3** - 订单簿 DEX
-- **FLOWX** - AMM 和 CLMM
-- **AFTERMATH** - AMM
-- **BLUEFIN** - CLMM
-- **TURBOS** - CLMM
-- **STEAMM** - CPMM
-- **STEAMM_OMM** - Oracle 驱动借贷协议
-- **STEAMM_OMM_V2** - Oracle 驱动借贷协议 V2
-- **ALPHAFI** - Vault 协议
-- **MOMENTUM** - CLMM
-- **MAGMA** - CLMM
-- **SEVENK** - Oracle 驱动
-- **SCALLOP** - 借贷协议
-- **HAEDAL** - PMM
-- **VOLO** - AMM
-- **BLUEMOVE** - AMM
-- **OBRIC** - AMM
-- **METASTABLE** - 稳定币 AMM
-- **SPRINGSUI/SUILEND** - 借贷协议
-- **AFSUI** - 流动性质押
-
-## 主要数据结构
-
-### SwapContext
-
-```move
-public struct SwapContext {
-    quote_id: String,           // 报价ID
-    from: TypeName,            // 输入代币类型
-    target: TypeName,          // 输出代币类型
-    amount_in: u64,            // 输入金额
-    expect_amount_out: u64,    // 期望输出金额
-    amount_out_limit: u64,     // 最小输出金额
-    fee_rate: u32,             // 手续费率
-    fee_recipient: address,    // 手续费接收者
-    balances: Bag,             // 余额管理
-}
-```
-
-## 核心接口函数
-
-### 1. 创建交易上下文
-
-```move
-public fun new_swap_context<A, B>(
-    quote_id: String,              // 报价ID
-    expect_amount_out: u64,        // 期望输出金额
-    amount_out_limit: u64,         // 最小输出金额
-    input_coin: Coin<A>,           // 输入代币
-    fee_rate: u32,                 // 手续费率 (0-100000, 对应0%-10%)
-    fee_recipient: address,        // 手续费接收地址
-    ctx: &mut TxContext,
-): SwapContext
-```
-
-**功能**: 创建一个新的交易上下文
-**参数约束**:
-
-- `input_coin.value() > 0`
-- `fee_rate <= 100000` (最大 10%)
-- 如果`fee_rate > 0`，则`fee_recipient != @0x0`
-
-### 2. 余额管理函数
-
-#### 提取余额
-
-```move
-public fun take_balance<T>(
-    swap_ctx: &mut SwapContext,
-    amount: u64
-): Balance<T>
-```
-
-#### 合并余额
-
-```move
-public fun merge_balance<T>(
-    swap_ctx: &mut SwapContext,
-    balance: Balance<T>
-)
-```
-
-#### 转账余额
-
-```move
-public fun transfer_balance<T>(
-    balance: Balance<T>,
-    recipient: address,
-    ctx: &mut TxContext
-)
-```
-
-### 3. 确认交易
-
-```move
-public fun confirm_swap<T>(
-    swap_ctx: SwapContext,
-    ctx: &mut TxContext
-): Coin<T>
-```
-
-**功能**: 确认并完成交易，返回输出代币
-**检查**:
-
-- 输出金额 >= `amount_out_limit`
-- 所有余额已处理完毕
-- 自动扣除手续费并转账给`fee_recipient`
-
-### 4. 工具函数
-
-#### 获取最大输入金额
-
-```move
-public fun max_amount_in(): u64  // 返回 2^64 - 1
-```
-
-#### 转账或销毁代币
-
-```move
-public fun transfer_or_destroy_coin<T>(
-    coin: Coin<T>,
-    ctx: &TxContext
-)
-```
-
-## DEX 集成接口标准
-
-### 1. CLMM 协议类 (类似 UniswapV3)
-
-#### 1.1 Cetus CLMM
-
-```move
-module cetus_router::cetus;
-
-public fun swap<A, B>(
-    swap_ctx: &mut SwapContext,
-    global_config: &GlobalConfig,
-    pool: &mut Pool<A, B>,
-    partner: &mut Partner,
-    a2b: bool,                     // 交易方向
-    amount_in: u64,                // 输入金额
-    clock: &Clock,
-    ctx: &mut TxContext,
-)
-```
-
-#### 1.2 Kriya CLMM
-
-```move
-module kriya_router::kriya_clmm;
-
-public fun swap<A, B>(
-    swap_ctx: &mut SwapContext,
-    pool: &mut Pool<A, B>,
-    version: &Version,
-    a2b: bool,
-    amount_in: u64,
-    clock: &Clock,
-    ctx: &mut TxContext,
-)
-```
-
-#### 1.3 FlowX CLMM
-
-```move
-module flowx_router::flowx_clmm;
-
-public fun swap<A, B>(
-    swap_ctx: &mut SwapContext,
-    pool_register: &mut PoolRegistry,
-    versioned: &Versioned,
-    fee_rate: u64,                 // 费率参数
-    amount_in: u64,
-    a2b: bool,
-    clock: &Clock,
-    ctx: &mut TxContext,
-)
-```
-
-#### 1.4 Bluefin CLMM
-
-```move
-module bluefin_router::bluefin;
-
-public fun swap<A, B>(
-    swap_ctx: &mut SwapContext,
-    global_config: &GlobalConfig,
-    pool: &mut Pool<A, B>,
-    a2b: bool,
-    amount_in: u64,
-    clock: &Clock,
-    ctx: &mut TxContext,
-)
-```
-
-#### 1.5 Turbos CLMM
-
-```move
-module turbos_router::turbos;
-
-public fun swap<A, B, Fee>(
-    swap_ctx: &mut SwapContext,
-    pool: &mut Pool<A, B, Fee>,    // 需要Fee类型参数
-    versioned: &Versioned,
-    a2b: bool,
-    amount_in: u64,
-    clock: &Clock,
-    ctx: &mut TxContext,
-)
-```
-
-#### 1.6 Momentum CLMM
-
-```move
-module momentum_router::momentum;
-
-public fun swap<A, B>(
-    swap_ctx: &mut SwapContext,
-    pool: &mut Pool<A, B>,
-    a2b: bool,
-    amount_in: u64,
-    version: &Version,
-    clock: &Clock,
-    ctx: &mut TxContext,
-)
-```
-
-#### 1.7 Magma CLMM
-
-```move
-module magma_router::magma;
-
-public fun swap<A, B>(
-    swap_ctx: &mut SwapContext,
-    global_config: &GlobalConfig,
-    pool: &mut Pool<A, B>,
-    a2b: bool,
-    amount_in: u64,
-    clock: &Clock,
-    ctx: &mut TxContext,
-)
-```
-
-### 2. AMM 协议类 (类似 UniswapV2)
-
-#### 2.1 Kriya AMM
-
-```move
-module kriya_router::kriya_amm;
-
-public fun swap<A, B>(
-    swap_ctx: &mut SwapContext,
-    pool: &mut Pool<A, B>,
-    a2b: bool,
-    amount_in: u64,
-    ctx: &mut TxContext,
-)
-```
-
-#### 2.2 FlowX AMM
-
-```move
-module flowx_router::flowx_amm;
-
-public fun swap<A, B>(
-    swap_ctx: &mut SwapContext,
-    container: &mut Container,
-    a2b: bool,
-    amount_in: u64,
-    ctx: &mut TxContext,
-)
-```
-
-#### 2.3 BlueMove AMM
-
-```move
-module bluemove_router::bluemove;
-
-// 仅支持单向接口
-public fun swap_a2b<A, B>(
-    swap_ctx: &mut SwapContext,
-    dex_info: &mut Dex_Info,
-    amount_in: u64,
-    ctx: &mut TxContext,
-)
-
-public fun swap_b2a<A, B>(
-    swap_ctx: &mut SwapContext,
-    dex_info: &mut Dex_Info,
-    amount_in: u64,
-    ctx: &mut TxContext,
-)
-```
-
-### 3. 订单簿类
-
-#### DeepBook V3
-
-```move
-module deepbook_router::deepbookv3;
-
-public fun swap<A, B>(
-    swap_ctx: &mut SwapContext,
-    config: &mut GlobalConfig,
-    pool: &mut Pool<A, B>,
-    amount_in: u64,
-    a2b: bool,
-    coin_deep: Coin<DEEP>,         // 需要DEEP代币支付手续费
-    clock: &Clock,
-    ctx: &mut TxContext,
-)
-```
-
-### 4. 复杂协议类
-
-#### 4.1 Aftermath AMM
-
-```move
-module aftermath_router::aftermath;
-
-// 需要多个辅助对象
-public fun swap_a2b<A, B, Fee>(
-    swap_ctx: &mut SwapContext,
-    pool: &mut Pool<Fee>,
-    pool_registry: &PoolRegistry,
-    vault: &ProtocolFeeVault,
-    treasury: &mut Treasury,
-    insurance_fund: &mut InsuranceFund,
-    referral_vault: &ReferralVault,
-    amount_in: u64,
-    expect_amount_out: u64,
-    ctx: &mut TxContext,
-)
-```
-
-#### 4.2 Steamm CPMM
-
-```move
-module steamm_router::steamm_cpmm;
-
-public fun swap<LENDING_MARKET, COIN_A, COIN_B, BCOIN_A, BCOIN_B, LP_TOKEN: drop>(
-    swap_ctx: &mut SwapContext,
-    pool: &mut Pool<BCOIN_A, BCOIN_B, CpQuoter, LP_TOKEN>,
-    bank_a: &mut Bank<LENDING_MARKET, COIN_A, BCOIN_A>,
-    bank_b: &mut Bank<LENDING_MARKET, COIN_B, BCOIN_B>,
-    lending_market: &LendingMarket<LENDING_MARKET>,
-    a2b: bool,
-    amount_in: u64,
-    clock: &Clock,
-    ctx: &mut TxContext,
-)
-```
-
-#### 4.3 Steamm OMM
-
-```move
-module steamm_router::steamm_omm;
-
-public fun swap<LENDING_MARKET, COIN_A, COIN_B, BCOIN_A, BCOIN_B, LP_TOKEN: drop>(
-    swap_ctx: &mut SwapContext,
-    pool: &mut Pool<BCOIN_A, BCOIN_B, OracleQuoter, LP_TOKEN>,
-    bank_a: &mut Bank<LENDING_MARKET, COIN_A, BCOIN_A>,
-    bank_b: &mut Bank<LENDING_MARKET, COIN_B, BCOIN_B>,
-    lending_market: &LendingMarket<LENDING_MARKET>,
-    oracle_price_update_a: OraclePriceUpdate,    // Oracle 价格更新 A
-    oracle_price_update_b: OraclePriceUpdate,    // Oracle 价格更新 B
-    a2b: bool,
-    amount_in: u64,
-    clock: &Clock,
-    ctx: &mut TxContext,
-)
-```
-
-#### 4.4 Steamm OMM V2
-
-```move
-module steamm_router::steamm_omm_v2;
-
-public fun swap<LENDING_MARKET, COIN_A, COIN_B, BCOIN_A, BCOIN_B, LP_TOKEN: drop>(
-    swap_ctx: &mut SwapContext,
-    pool: &mut Pool<BCOIN_A, BCOIN_B, OracleQuoterV2, LP_TOKEN>,
-    bank_a: &mut Bank<LENDING_MARKET, COIN_A, BCOIN_A>,
-    bank_b: &mut Bank<LENDING_MARKET, COIN_B, BCOIN_B>,
-    lending_market: &LendingMarket<LENDING_MARKET>,
-    oracle_price_update_a: OraclePriceUpdate,    // Oracle 价格更新 A
-    oracle_price_update_b: OraclePriceUpdate,    // Oracle 价格更新 B
-    a2b: bool,
-    amount_in: u64,
-    clock: &Clock,
-    ctx: &mut TxContext,
-)
-```
-
-### 5. 借贷协议类
-
-#### 5.1 Scallop
-
-```move
-module scallop_router::scallop;
-
-// mint s_coin: coin -> s_coin
-public fun swap_a2b<A, B>(
-    swap_ctx: &mut SwapContext,
-    version: &Version,
-    market: &mut Market,
-    treasury: &mut SCoinTreasury<B, A>,
-    amount_in: u64,
-    clock: &Clock,
-    ctx: &mut TxContext,
-)
-
-// redeem s_coin: s_coin -> coin
-public fun swap_b2a<B, A>(
-    swap_ctx: &mut SwapContext,
-    version: &Version,
-    market: &mut Market,
-    treasury: &mut SCoinTreasury<B, A>,
-    amount_in: u64,
-    clock: &Clock,
-    ctx: &mut TxContext,
-)
-```
-
-### 6. 流动性质押类
-
-#### 6.1 AlphaFi
-
-```move
-module alphafi_router::alphafi;
-
-public fun swap<P: drop>(
-    swap_ctx: &mut SwapContext,
-    liquid_staking_info: &mut LiquidStakingInfo<P>,
-    system_state: &mut SuiSystemState,
-    a2b: bool,
-    amount_in: u64,
-    ctx: &mut TxContext,
-)
-```
-
-#### 6.2 Volo
-
-```move
-module volo_router::volo;
-
-public fun swap(
-    swap_ctx: &mut SwapContext,
-    pool: &mut StakePool,
-    metadata: &mut Metadata<CERT>,
-    sui_system: &mut SuiSystemState,
-    a2b: bool,
-    amount_in: u64,
-    ctx: &mut TxContext,
-)
-```
-
-### 7. Oracle 驱动类
-
-#### 7.1 Haedal HMM
-
-```move
-module haedal_router::haedal_hmm;
-
-public fun swap<A, B>(
-    swap_ctx: &mut SwapContext,
-    pool: &mut Pool<A, B>,
-    base_price_pair_obj: &PriceInfoObject,   // Pyth价格预言机
-    quote_price_pair_obj: &PriceInfoObject,
-    amount_in: u64,
-    a2b: bool,
-    clock: &Clock,
-    ctx: &mut TxContext,
-)
-```
-
-#### 7.2 Obric
-
-```move
-module obric_router::obric;
-
-public fun swap<A, B>(
-    swap_ctx: &mut SwapContext,
-    pool: &mut TradingPair<A, B>,
-    amount_in: u64,
-    a2b: bool,
-    pyth_state: &PythState,                 // Pyth状态对象
-    a_price_info_object: &PriceInfoObject,
-    b_price_info_object: &PriceInfoObject,
-    clock: &Clock,
-    ctx: &mut TxContext,
-)
-```
-
-### 8. 稳定币专用类
-
-#### Metastable
-
-```move
-module metastable_router::metastable;
-
-// deposit coin => metacoin
-public fun swap_a2b<A, B>(
-    swap_ctx: &mut SwapContext,
-    vault_info: &mut Vault<B>,
-    version: &Version,
-    deposit_cap: DepositCap<B, A>,
-    amount_in: u64,
-    ctx: &mut TxContext,
-)
-
-// withdraw metacoin => coin
-public fun swap_b2a<A, B>(
-    swap_ctx: &mut SwapContext,
-    vault_info: &mut Vault<B>,
-    version: &Version,
-    withdraw_cap: WithdrawCap<B, A>,
-    amount_in: u64,
-    ctx: &mut TxContext,
-)
-```
-
-## SDK 对接标准
-
-### 1. 通用接口模式
-
-所有 DEX 集成都遵循以下模式：
-
-```move
-public fun swap<TypeParams>(
-    swap_ctx: &mut SwapContext,    // 必需：聚合器上下文
-    // DEX特定参数
-    a2b: bool,                     // 可选：交易方向 (部分DEX使用)
-    amount_in: u64,                // 必需：输入金额
-    // 其他DEX特定参数
-    ctx: &mut TxContext,           // 必需：交易上下文
-)
-```
-
-### 2. DEX 分类和参数需求
-
-#### 简单 DEX (只需基本参数)
-
-- **Kriya AMM**, **FlowX AMM**, **BlueMove**
-
-#### CLMM 类 DEX (需要 Clock)
-
-- **Cetus**, **Kriya CLMM**, **FlowX CLMM**, **Bluefin**, **Turbos**, **Momentum**, **Magma**
-
-#### 订单簿 DEX (需要特殊代币)
-
-- **DeepBook V3** (需要 DEEP 代币)
-
-#### Oracle 驱动 DEX (需要价格预言机)
-
-- **Haedal HMM**, **Obric** (需要 Pyth 价格信息)
-- **Steamm OMM**, **Steamm OMM V2** (需要 Oracle 价格更新)
-
-#### 借贷协议 (需要市场/银行对象)
-
-- **Scallop**, **Steamm CPMM**
-
-#### 质押协议 (需要系统状态)
-
-- **AlphaFi**, **Volo** (需要 SuiSystemState)
-
-#### 复杂协议 (需要多个辅助对象)
-
-- **Aftermath** (需要多个金库和注册表)
-
-### 3. SDK 实现建议
-
-1. **参数管理**: 为每个 DEX 类型创建专门的参数结构体
-2. **类型安全**: 利用 Move 的类型系统确保参数正确性
-3. **错误处理**: 统一处理各 DEX 的特定错误情况
-4. **批量操作**: 支持多路径并行执行
-5. **滑点保护**: 在`SwapContext`层面统一管理滑点控制
-
-## REST API 接口
-
-### 路由查找接口
-
-#### 端点
-
-```
-GET/POST /router_v2/find_routes
-```
-
-#### 请求参数
-
-```json
-{
-    "from": "0x2::sui::SUI",                    // 输入代币类型
-    "target": "0x2::coin::COIN",                // 输出代币类型
-    "amount": 1000000000,                       // 金额 (最小单位)
-    "by_amount_in": true,                       // 是否按输入金额计算
-    "depth": 3,                                 // 最大路径深度
-    "split_count": 5,                           // 分割数量
-    "providers": "CETUS,KRIYA,DEEPBOOKV3",     // 指定DEX (可选)
-    "liquidity_change": [...],                  // 流动性变化 (可选)
-    "v": 1000800                               // 客户端版本
-}
-```
-
-#### 响应格式
-
-```json
-{
-  "request_id": "unique_id",
-  "amount_in": 1000000000,
-  "amount_out": 950000000,
-  "routes": [
-    {
-      "path": [
-        {
-          "provider": "CETUS",
-          "pool_id": "0x...",
-          "from": "0x2::sui::SUI",
-          "target": "0x2::coin::COIN",
-          "amount_in": 500000000,
-          "amount_out": 475000000
-        }
-      ],
-      "amount_in": 500000000,
-      "amount_out": 475000000,
-      "initial_price": "0.95"
-    }
-  ],
-  "packages": {
-    "CETUS": "0x...",
-    "KRIYA": "0x..."
-  }
-}
-```
-
-## 错误代码
-
-| 错误码 | 函数                        | 说明                 |
-| ------ | --------------------------- | -------------------- |
-| 1      | `err_less_amount_out`       | 输出金额小于限制     |
-| 2      | `err_remains_balance`       | 存在未处理的余额     |
-| 3      | `err_amount_in_is_zero`     | 输入金额为零         |
-| 4      | `err_invalid_fee_recipient` | 无效的手续费接收者   |
-| 5      | `err_too_large_fee_rate`    | 手续费率过大         |
-| 6      | `err_not_support_b2a`       | 不支持 B 到 A 的交易 |
-
-## 常量定义
-
-```move
-const FEE_DENOMINATOR: u32 = 1000000;      // 手续费分母
-const MAX_FEE_RATE: u32 = 100000;          // 最大手续费率 (10%)
-const MAX_AMOUNT_IN: u64 = 0xFFFFFFFFFFFFFFFF; // 最大输入金额
-```
-
-## 版本兼容性
-
-系统根据客户端版本自动调整支持的 DEX 列表：
-
-- `v1.0.3.18+`: 支持 BLUEFIN, SUILEND, ALPHAFI
-- `v1.0.3.22+`: 支持 HAEDALPMM
-- `v1.0.3.28+`: 支持 TURBOS
-- `v1.0.6.0+`: 支持 DEEPBOOKV3
-- `v1.0.7.0+`: 支持 STEAMM_OMM
-- `v1.0.8.0+`: 支持 MOMENTUM, STEAMM_OMM_V2
-
-## 使用流程
-
-1. **获取报价**: 调用 REST API 获取最优路径和报价 ID
-2. **创建上下文**: 使用`new_swap_context`创建交易上下文
-3. **执行交易**: 按报价路径调用各 DEX 的 swap 函数
-4. **确认交易**: 调用`confirm_swap`完成交易并获得输出代币
-
-## 安全考虑
-
-- 所有金额计算使用精确算术，避免精度损失
-- 滑点保护通过`amount_out_limit`参数实现
-- 手续费率有上限保护 (最大 10%)
-- 余额管理确保无资金遗漏
-- 统一的错误处理和状态管理
-
-这份文档为 SDK 对接提供了完整的 DEX 集成标准，每个 DEX 类型都有明确的接口定义和参数要求，便于开发者正确实现聚合器功能。