openchain-sdk-yxl-wx-request/doc/manual/6-ctp10-token.md

openchain sd YxL wx request

# CTP10 Token

CTP10 Token 是 OpenChain 上的标准代币协议，提供了完整的代币管理功能，包括发行、转移、授权等操作。

## Token 基础信息

### 检查 CTP10 合约
```javascript
// 检查合约是否为有效的 CTP10 Token
const isValid = yield sdk.token.ctp10Token.checkValid(contractAddress);

// 获取 Token 完整信息
const tokenInfo = yield sdk.token.ctp10Token.getInfo(contractAddress);
// 返回结果示例
{
  errorCode: 0,
  result: {
    ctp: "CTP10",
    name: "MyToken",
    symbol: "MT",
    totalSupply: "1000000",
    decimals: 8,
    contractOwner: "did:bid:efqkw1dKHHuWtupG6k1tCu4PNfoRs7us"
  }
}
```

### 查询 Token 属性
```javascript
// 获取 Token 名称
const nameInfo = yield sdk.token.ctp10Token.getName(contractAddress);

// 获取 Token 符号
const symbolInfo = yield sdk.token.ctp10Token.getSymbol(contractAddress);

// 获取 Token 精度
const decimalsInfo = yield sdk.token.ctp10Token.getDecimals(contractAddress);

// 获取 Token 总供应量
const supplyInfo = yield sdk.token.ctp10Token.getTotalSupply(contractAddress);
```

## Token 余额和授权

### 余额查询
```javascript
// 查询账户 Token 余额
const balanceInfo = yield sdk.token.ctp10Token.getBalance({
  contractAddress: 'your-token-contract-address',  // Token 合约地址
  tokenOwner: 'account-address'                    // 要查询的账户地址
});
```

### 授权查询
```javascript
// 查询授权额度
const allowanceInfo = yield sdk.token.ctp10Token.allowance({
  contractAddress: 'your-token-contract-address',  // Token 合约地址
  tokenOwner: 'owner-address',                     // Token 持有者地址
  spender: 'spender-address'                       // 被授权者地址
});
```

## Token 操作

### 发行 Token
```javascript
// 发行 Token
const issueOperation = {
  sourceAddress: address,          // 发行方地址
  name: 'MyToken',                // Token 名称
  symbol: 'MT',                   // Token 符号
  totalSupply: '1000000',         // 发行总量
  decimals: 8,                    // 精度
  metadata: 'token info'          // 可选，Token 元数据
};
const issueResponse = yield sdk.operation.ctp10Token.issue(issueOperation);
```

### 转移 Token
```javascript
// 转移 Token
const transferOperation = {
  sourceAddress: sourceAddress,    // 发送方地址
  destAddress: destAddress,        // 接收方地址
  amount: '100',                  // 转移数量
  metadata: 'transfer info'       // 可选，转移说明
};
const transferResponse = yield sdk.operation.ctp10Token.transfer(transferOperation);
```

### Token 授权
```javascript
// 授权 Token
const approveOperation = {
  sourceAddress: sourceAddress,    // Token 持有者地址
  spender: spenderAddress,        // 被授权者地址
  amount: '1000',                 // 授权数量
  metadata: 'approve info'        // 可选，授权说明
};
const approveResponse = yield sdk.operation.ctp10Token.approve(approveOperation);

// 从授权账户转移 Token
const transferFromOperation = {
  sourceAddress: sourceAddress,    // 操作发起方地址
  from: fromAddress,              // Token 持有者地址
  to: toAddress,                  // 接收方地址
  amount: '100',                  // 转移数量
  metadata: 'transfer info'       // 可选，转移说明
};
const transferFromResponse = yield sdk.operation.ctp10Token.transferFrom(transferFromOperation);
```

## 高级功能

### Token 所有权管理
```javascript
// 更改 Token 所有者
const changeOwnerOperation = {
  sourceAddress: currentOwner,     // 当前所有者地址
  newOwner: newOwnerAddress,       // 新所有者地址
  metadata: 'change owner info'    // 可选，变更说明
};
const changeOwnerResponse = yield sdk.operation.ctp10Token.changeOwner(changeOwnerOperation);
```

### Token 分配
```javascript
// Token 分配操作
const assignOperation = {
  sourceAddress: ownerAddress,     // Token 所有者地址
  destAddress: destAddress,        // 接收方地址
  amount: '1000',                 // 分配数量
  metadata: 'assign info'         // 可选，分配说明
};
const assignResponse = yield sdk.operation.ctp10Token.assign(assignOperation);
```

## 最佳实践

1. Token 发行规范
```javascript
// Token 参数验证
function validateTokenParams(params) {
  // 验证名称
  if (!params.name || params.name.length > 1024) {
    throw new Error('Invalid token name');
  }
  
  // 验证符号
  if (!params.symbol || params.symbol.length > 1024) {
    throw new Error('Invalid token symbol');
  }
  
  // 验证精度
  if (typeof params.decimals !== 'number' || params.decimals < 0 || params.decimals > 8) {
    throw new Error('Invalid decimals');
  }
  
  // 验证发行总量
  if (!params.totalSupply || Number(params.totalSupply) <= 0) {
    throw new Error('Invalid total supply');
  }
}
```

2. 安全转账
```javascript
// 安全的 Token 转账
async function safeTransfer(params) {
  // 检查余额
  const balance = await sdk.token.ctp10Token.getBalance({
    contractAddress: params.contractAddress,
    tokenOwner: params.sourceAddress
  });
  
  if (Number(balance) < Number(params.amount)) {
    throw new Error('Insufficient balance');
  }
  
  // 执行转账
  try {
    const response = await sdk.operation.ctp10Token.transfer(params);
    if (response.errorCode === 0) {
      return {
        success: true,
        hash: response.result.hash
      };
    }
    throw new Error(response.errorDesc);
  } catch (error) {
    console.error('Transfer failed:', error);
    throw error;
  }
}
```

3. 授权管理
```javascript
// 授权管理工具
const approvalManager = {
  // 检查授权额度
  async checkAllowance(params) {
    const allowance = await sdk.token.ctp10Token.allowance({
      contractAddress: params.contractAddress,
      tokenOwner: params.owner,
      spender: params.spender
    });
    return allowance;
  },
  
  // 增加授权额度
  async increaseAllowance(params) {
    const currentAllowance = await this.checkAllowance(params);
    const newAmount = String(Number(currentAllowance) + Number(params.amount));
    
    return await sdk.operation.ctp10Token.approve({
      sourceAddress: params.owner,
      spender: params.spender,
      amount: newAmount
    });
  },
  
  // 减少授权额度
  async decreaseAllowance(params) {
    const currentAllowance = await this.checkAllowance(params);
    const newAmount = String(Math.max(0, Number(currentAllowance) - Number(params.amount)));
    
    return await sdk.operation.ctp10Token.approve({
      sourceAddress: params.owner,
      spender: params.spender,
      amount: newAmount
    });
  }
};
```

4. 交易监控
```javascript
// Token 交易监控
class TokenMonitor {
  constructor(contractAddress) {
    this.contractAddress = contractAddress;
    this.listeners = new Map();
  }
  
  // 添加地址监控
  async addAddressMonitor(address, callback) {
    const monitor = async () => {
      try {
        const balance = await sdk.token.ctp10Token.getBalance({
          contractAddress: this.contractAddress,
          tokenOwner: address
        });
        callback(null, balance);
      } catch (error) {
        callback(error);
      }
    };
    
    this.listeners.set(address, setInterval(monitor, 5000));
  }
  
  // 移除地址监控
  removeAddressMonitor(address) {
    const listener = this.listeners.get(address);
    if (listener) {
      clearInterval(listener);
      this.listeners.delete(address);
    }
  }
  
  // 停止所有监控
  stopAllMonitors() {
    for (const [address, listener] of this.listeners) {
      clearInterval(listener);
    }
    this.listeners.clear();
  }
}
```

5. 批量操作优化
```javascript
// 批量转账优化
async function batchTransfer(params) {
  const { sourceAddress, transfers, contractAddress } = params;
  
  // 检查总转账金额
  const totalAmount = transfers.reduce((sum, t) => sum + Number(t.amount), 0);
  const balance = await sdk.token.ctp10Token.getBalance({
    contractAddress,
    tokenOwner: sourceAddress
  });
  
  if (Number(balance) < totalAmount) {
    throw new Error('Insufficient balance for batch transfer');
  }
  
  // 构建批量操作
  const operations = transfers.map(transfer => ({
    type: 'ctp10TokenTransfer',
    data: {
      sourceAddress,
      destAddress: transfer.to,
      amount: transfer.amount
    }
  }));
  
  // 执行批量转账
  const response = await sdk.transaction.buildBlob({
    sourceAddress,
    operations,
    gasPrice: '1000',
    feeLimit: String(1000000 * operations.length)
  });
  
  return response;
}
```