Coinfair 技术文档

Appearance

Position NFT 模块 ​

模块路径: coinfair_clmm::position_nft

Position NFT 模块负责管理流动性位置的NFT。用户位置权限由代币表示，拥有代币的用户控制该位置。每个池都有一个集合，该池的所有位置都属于这个集合。

Public 方法（可写） ​

create_collection ​

创建位置NFT集合。

move
public fun create_collection(
    creator: &signer,
    tick_spacing: u64,
    description: String,
    uri: String,
    metadata_a: Object<Metadata>,
    metadata_b: Object<Metadata>
): String

参数:

  • creator: &signer - 创建者（池资源账户）
  • tick_spacing: u64 - 池的tick间距
  • description: String - 集合描述
  • uri: String - NFT集合URI
  • metadata_a: Object<Metadata> - 代币A的元数据
  • metadata_b: Object<Metadata> - 代币B的元数据

返回: String - 集合名称

说明: 由pool模块在创建池子时自动调用

集合名称格式: "Coinfair Position | {tokenA}-{tokenB}_tick({tick_spacing})"

mint ​

铸造位置NFT。

move
public fun mint(
    user: &signer,
    creator: &signer,
    pool_index: u64,
    position_index: u64,
    pool_uri: String,
    collection: String
)

参数:

  • user: &signer - NFT接收者
  • creator: &signer - 创建者（池资源账户）
  • pool_index: u64 - 池索引
  • position_index: u64 - 位置索引
  • pool_uri: String - 池URI
  • collection: String - NFT集合名称

说明: 由pool模块在开启位置时自动调用

NFT名称格式: "Coinfair LP | Pool{pool_index}-{position_index}"

属性:

  • index: u64 - 位置索引
  • TOKEN_BURNABLE_BY_CREATOR: bool - 创建者可销毁（true）

burn ​

销毁位置NFT。

move
public fun burn(
    creator: &signer,
    user: address,
    collection_name: String,
    pool_index: u64,
    pos_index: u64
)

参数:

  • creator: &signer - NFT创建者（池资源账户）
  • user: address - NFT所有者
  • collection_name: String - 集合名称
  • pool_index: u64 - 池索引
  • pos_index: u64 - 位置索引

说明: 由pool模块在关闭位置时自动调用

position_name ​

生成位置NFT名称。

move
public fun position_name(pool_index: u64, index: u64): String

参数:

  • pool_index: u64 - 池索引
  • index: u64 - 位置索引

返回: String - 位置名称字符串

格式: "Coinfair LP | Pool{pool_index}-{index}"

collection_name ​

生成位置代币集合唯一名称。

move
public fun collection_name(
    tick_spacing: u64,
    metadata_a: Object<Metadata>,
    metadata_b: Object<Metadata>
): String

参数:

  • tick_spacing: u64 - tick间距
  • metadata_a: Object<Metadata> - 代币A的元数据
  • metadata_b: Object<Metadata> - 代币B的元数据

返回: String - 集合名称字符串

格式: "Coinfair Position | {tokenA}-{tokenB}_tick({tick_spacing})"

mutate_collection_uri ​

修改集合URI（目前在主网不支持）。

move
public fun mutate_collection_uri(
    _creator: &signer,
    _collection: String,
    _uri: String
)

参数:

  • _creator: &signer - 创建者
  • _collection: String - 集合名称
  • _uri: String - 新URI

说明: 目前在主网不支持此功能

使用说明 ​

NFT所有权验证 ​

位置NFT用于验证用户对流动性位置的所有权。在调用pool模块的位置相关操作时，系统会检查用户是否持有对应的位置NFT。

NFT标识符构造 ​

位置NFT的标识符由以下信息构造：

  • 创建者地址: 池资源账户地址（通过 account::get_signer_capability_address 获取）
  • 集合名称: 通过 collection_name 函数生成
  • NFT名称: 通过 position_name 函数生成
  • 属性版本: 0

NFT生命周期 ​

  1. 创建: 当用户调用 pool::open_position 时，自动调用 mint 函数铸造NFT
  2. 转移: NFT可以像普通NFT一样转移，转移后新所有者获得位置控制权
  3. 销毁: 当位置流动性为0且用户调用 pool::checked_close_position 时，自动调用 burn 函数销毁NFT

使用示例 ​

TypeScript 示例 ​

typescript
// 注意：Position NFT 模块的方法通常由 pool 模块内部调用
// 前端通常不需要直接调用这些方法

// 1. 查询用户是否持有位置NFT（通过token标准）
const tokenId = createTokenId(
  poolSignerAddress,
  collectionName,
  positionName,
  0  // 属性版本
);
const balance = await view('token::balance_of', [userAddress, tokenId]);

// 2. 查询位置NFT的元数据
const tokenData = await view('token::get_token_data', [
  poolSignerAddress,
  collectionName,
  positionName
]);

// 3. 转移位置NFT（转移后新所有者获得位置控制权）
await entry('token::transfer', [
  account,
  recipientAddress,
  poolSignerAddress,
  collectionName,
  positionName,
  0,  // 属性版本
  1   // 数量
]);