openchain-sdk-yxl/docs/user-manual.md

openchain sdk

# OpenChain SDK for Node.js 使用手册

## 目录

- [安装和配置](#安装和配置)
- [账户管理](#账户管理)
- [区块链交互](#区块链交互)
- [智能合约](#智能合约)
- [资产管理](#资产管理)
- [CTP10代币](#ctp10代币)
- [WebSocket连接](#websocket连接)
- [错误处理](#错误处理)
- [最佳实践](#最佳实践)

## 安装和配置

### 安装SDK

```bash
npm install openchain-sdk-yxl
```

或使用yarn：

```bash
yarn add openchain-sdk-yxl
```

### 初始化SDK

```javascript
const OpenChainSDK = require('openchain-sdk-yxl');

const sdk = new OpenChainSDK({
    // 必需配置
    nodeUrl: 'http://your-node-url',  // 节点URL
    chainId: 'your-chain-id',         // 链ID
    
    // 可选配置
    timeout: 30000,                   // 请求超时时间（毫秒）
    retryTimes: 3,                    // 重试次数
    wsUrl: 'ws://your-ws-url'         // WebSocket URL（如需要）
});
```

## 账户管理

### 创建账户

```javascript
// 创建新账户
const account = sdk.account.create();
console.log('账户地址:', account.address);
console.log('私钥:', account.privateKey);

// 从私钥导入账户
const importedAccount = sdk.account.fromPrivateKey('your-private-key');

// 获取账户余额
const balance = await sdk.account.getBalance(account.address);
```

### 账户操作

```javascript
// 转账
const transferResult = await sdk.account.transfer({
    from: account.address,
    to: 'recipient-address',
    amount: '1000000',  // 金额（基本单位）
    privateKey: account.privateKey
});

// 查询账户信息
const accountInfo = await sdk.account.getAccountInfo(account.address);
```

## 区块链交互

### 区块操作

```javascript
// 获取最新区块
const latestBlock = await sdk.blockchain.getLatestBlock();

// 根据高度获取区块
const block = await sdk.blockchain.getBlockByHeight(100);

// 根据哈希获取区块
const blockByHash = await sdk.blockchain.getBlockByHash('block-hash');
```

### 交易操作

```javascript
// 发送交易
const txResult = await sdk.transaction.send({
    from: account.address,
    to: 'recipient-address',
    value: '1000000',
    data: '0x',  // 可选，合约调用数据
    privateKey: account.privateKey
});

// 获取交易收据
const receipt = await sdk.transaction.getTransactionReceipt('tx-hash');

// 查询交易状态
const txStatus = await sdk.transaction.getTransactionStatus('tx-hash');
```

## 智能合约

### 合约部署

```javascript
// 部署合约
const contract = await sdk.contract.deploy({
    from: account.address,
    privateKey: account.privateKey,
    abi: contractABI,
    bytecode: contractBytecode,
    args: []  // 构造函数参数
});

console.log('合约地址:', contract.address);
```

### 合约调用

```javascript
// 初始化合约实例
const contract = sdk.contract.at(contractAddress, contractABI);

// 调用合约方法（写入方法）
const result = await contract.methods.transfer('recipient', '1000').send({
    from: account.address,
    privateKey: account.privateKey
});

// 调用合约方法（只读方法）
const balance = await contract.methods.balanceOf(account.address).call();

// 监听合约事件
contract.events.Transfer({
    fromBlock: 0
}, (error, event) => {
    if (error) {
        console.error('事件监听错误:', error);
        return;
    }
    console.log('转账事件:', event);
});
```

## 资产管理

### 资产操作

```javascript
// 发行资产
const assetResult = await sdk.asset.issue({
    from: account.address,
    privateKey: account.privateKey,
    name: 'MyAsset',
    symbol: 'MA',
    totalSupply: '1000000000',
    decimals: 18
});

// 转移资产
const transferResult = await sdk.asset.transfer({
    from: account.address,
    to: 'recipient-address',
    assetId: 'asset-id',
    amount: '1000',
    privateKey: account.privateKey
});

// 查询资产余额
const assetBalance = await sdk.asset.getBalance(account.address, 'asset-id');
```

## CTP10代币

### 代币操作

```javascript
// 发行CTP10代币
const tokenResult = await sdk.ctp10Token.deploy({
    from: account.address,
    privateKey: account.privateKey,
    name: 'MyToken',
    symbol: 'MT',
    totalSupply: '1000000000',
    decimals: 18
});

// 转账代币
const token = sdk.ctp10Token.at(tokenAddress);
const transferResult = await token.transfer({
    from: account.address,
    to: 'recipient-address',
    amount: '1000',
    privateKey: account.privateKey
});

// 授权代币
const approveResult = await token.approve({
    from: account.address,
    spender: 'spender-address',
    amount: '1000',
    privateKey: account.privateKey
});
```

## WebSocket连接

### 实时数据订阅

```javascript
// 创建WebSocket客户端
const wsClient = sdk.websocket.createClient();

// 订阅新区块
wsClient.subscribeNewBlock((error, block) => {
    if (error) {
        console.error('订阅错误:', error);
        return;
    }
    console.log('新区块:', block);
});

// 订阅交易
wsClient.subscribeTransaction({
    address: account.address  // 可选，指定地址
}, (error, transaction) => {
    if (error) {
        console.error('订阅错误:', error);
        return;
    }
    console.log('新交易:', transaction);
});
```

## 错误处理

```javascript
try {
    const result = await sdk.transaction.send({
        // 交易参数
    });
} catch (error) {
    if (error.code === 'INVALID_PARAMS') {
        console.error('参数无效:', error.message);
    } else if (error.code === 'INSUFFICIENT_BALANCE') {
        console.error('余额不足:', error.message);
    } else {
        console.error('未知错误:', error);
    }
}
```

## 最佳实践

### 交易确认

```javascript
// 等待交易确认
async function waitForConfirmation(txHash, maxAttempts = 20) {
    for (let i = 0; i < maxAttempts; i++) {
        const receipt = await sdk.transaction.getTransactionReceipt(txHash);
        if (receipt) {
            return receipt;
        }
        await new Promise(resolve => setTimeout(resolve, 1000));
    }
    throw new Error('交易确认超时');
}

// 使用示例
const txResult = await sdk.transaction.send({
    // 交易参数
});
const receipt = await waitForConfirmation(txResult.hash);
```

### 批量操作

```javascript
// 批量转账示例
async function batchTransfer(recipients, amounts, privateKey) {
    const results = [];
    for (let i = 0; i < recipients.length; i++) {
        try {
            const result = await sdk.transaction.send({
                to: recipients[i],
                value: amounts[i],
                privateKey: privateKey
            });
            results.push({ success: true, hash: result.hash });
        } catch (error) {
            results.push({ success: false, error: error.message });
        }
    }
    return results;
}
```

### 安全建议

1. 私钥管理
   - 永远不要在代码中硬编码私钥
   - 使用环境变量或安全的密钥管理系统
   - 定期更换私钥

2. 错误处理
   - 始终使用try-catch处理异步操作
   - 实现适当的重试机制
   - 记录详细的错误日志

3. 资源管理
   - 及时关闭WebSocket连接
   - 实现请求限流
   - 合理设置超时时间

### 性能优化

1. 连接池
   - 重用SDK实例
   - 维护WebSocket连接池

2. 缓存策略
   - 缓存频繁查询的数据
   - 实现智能的缓存失效机制

3. 批处理
   - 合并多个查询请求
   - 使用批量交易接口

## 常见问题解答

1. Q: 如何处理交易失败？
   A: 实现重试机制，检查错误类型，确保参数正确。

2. Q: 如何优化性能？
   A: 使用连接池、实现缓存、批量处理请求。

3. Q: 如何确保交易安全？
   A: 使用安全的私钥管理、实现签名验证、添加适当的错误处理。

4. Q: WebSocket连接断开如何处理？
   A: 实现自动重连机制，监控连接状态。

5. Q: 如何处理大量并发请求？
   A: 实现请求队列、使用限流机制、优化资源利用。