Coinfair 技术文档

Appearance

CLMM 合约接口文档 ​

本文档详细说明了 Coinfair CLMM (Concentrated Liquidity Market Maker) 合约的所有接口，包括方法签名、参数、返回值和数据结构。

模块概览 ​

Coinfair CLMM 协议由以下核心模块组成：

快速开始 ​

1. 查询池子信息 ​

typescript
// 检查池子是否存在
const exists = await view('factory::pool_exists', [
  tokenA,
  tokenB,
  tickSpacing
]);

// 获取池子地址
const poolAddress = await view('factory::get_pool_address', [
  tokenA,
  tokenB,
  tickSpacing
]);

// 获取完整池子信息
const poolInfo = await view('pool::get_pool_info', [poolAddress]);

2. 创建池子并添加流动性 ​

typescript
// 创建池子并添加初始流动性
await entry('clmm_router::create_pool_and_add_liquidity', [
  account,
  tokenA,
  tokenB,
  tickSpacing,
  initializePrice,
  uri,
  deltaLiquidity,
  maxAmountA,
  maxAmountB,
  tickLower,
  tickUpper
]);

3. 添加流动性 ​

typescript
// 开启新位置并添加流动性
await entry('clmm_router::add_liquidity', [
  account,
  poolAddress,
  deltaLiquidity,
  maxAmountA,
  maxAmountB,
  tickLower,
  tickUpper,
  true,  // is_open: 创建新位置
  0      // index: 无效（因为is_open为true）
]);

4. 执行交换 ​

typescript
// 计算交换结果（预览）
const swapResult = await view('pool::calculate_swap_result', [
  poolAddress,
  true,   // a2b: A换B
  true,   // by_amount_in: 按输入量
  1000    // amount: 输入数量
]);

// 执行交换
await entry('clmm_router::swap', [
  account,
  poolAddress,
  true,   // a_to_b: A换B
  true,   // by_amount_in: 按输入量
  1000,   // amount: 输入数量
  950,    // amount_limit: 最小输出数量
  priceLimit,
  metadataA,
  metadataB
]);

5. 查询用户位置 ​

typescript
// 查询用户在特定池子中的所有位置索引
const userPositions = await view('pool::get_user_positions', [
  poolAddress,
  userAddress
]);

// 查询用户在特定池子中的所有位置详细信息
const userPositionsDetail = await view('pool::get_user_positions_detail', [
  poolAddress,
  userAddress
]);

重要概念 ​

统一费用机制 ​

核心特性: 无论交换方向如何，所有费用都统一从代币B收取。

  • A→B交换: 用户支付精确的代币A数量，费用从输出的代币B中自动扣除
  • B→A交换: 用户支付代币B数量（包含交换量+费用），费用从输入的代币B中扣除

热土豆模式 ​

AddLiquidityReceipt 和 FlashSwapReceipt 是热土豆模式，必须在同一个交易中处理，不能存储或传递。

Tick 值要求 ​

  • tick值必须是 tick_spacing 的倍数
  • tick_lower 必须小于 tick_upper

价格格式 ​

  • 使用 fifrt_price 格式（x^4 * y = k 中的价格）
  • 需要与 tick_math 模块配合进行转换

文档导航 ​

按模块查看 ​

数据结构 ​

数学与设计文档 ​

错误代码 ​

Factory 模块 ​

  • EPOOL_ALREADY_INITIALIZED = 1: 池子已初始化
  • EINVALID_FIFRTPRICE = 2: 无效的初始价格

Router 模块 ​

  • EAMOUNT_IN_ABOVE_MAX_LIMIT = 1: 输入数量超过最大限制
  • EAMOUNT_OUT_BELOW_MIN_LIMIT = 2: 输出数量低于最小限制
  • EIS_NOT_VALID_TICK = 3: 无效的tick值
  • EINVALID_LIQUIDITY = 4: 无效的流动性
  • EPOOL_ADDRESS_ERROR = 5: 池子地址错误
  • EINVALID_POOL_PAIR = 6: 无效的池子对
  • ESWAP_AMOUNT_INCORRECT = 7: 交换数量不正确
  • EPOSITION_INDEX_ERROR = 8: 位置索引错误
  • EPOSITION_IS_NOT_ZERO = 9: 位置不为空

Config 模块 ​

  • ENOT_HAS_PRIVILEGE = 1: 没有权限
  • ECONFIG_ALREADY_INITIALIZED = 2: 配置已初始化
  • EINVALID_PROTOCOL_FEE_RATE = 3: 无效的协议费率
  • EPROTOCOL_IS_PAUSED = 4: 协议已暂停
  • EINVALID_ACL_ROLE = 5: 无效的ACL角色

FeeTier 模块 ​

  • EFEE_TIER_ALREADY_EXIST = 1: 费用等级已存在
  • EFEE_TIER_NOT_FOUND = 2: 费用等级未找到
  • EFEETIER_ALREADY_INITIALIZED = 3: 费用等级已初始化
  • EINVALID_FEE_RATE = 4: 无效的费率
  • EINVALID_TICK_SPACE = 5: 无效的tick间距

版本信息 ​

  • 文档版本: 2.0
  • 合约版本: 基于 Coinfair CLMM v1
  • 最后更新: 2024