openchain-sdk-yxl-request/doc/SDK_CN.md

openchain sd YxL request

# OpenChain Node.js SDK 用户手册

## 目录

- [简介](#简介)
- [安装](#安装)
- [快速开始](#快速开始)
- [核心功能](#核心功能)
  - [账户管理](#账户管理)
  - [交易处理](#交易处理)
  - [智能合约](#智能合约)
  - [资产操作](#资产操作)
  - [CTP10 Token](#ctp10-token)
- [错误处理](#错误处理)
- [最佳实践](#最佳实践)

## 简介

OpenChain Node.js SDK 是一个完整的开发工具包，为开发者提供了与OpenChain区块链网络交互的全套功能。SDK支持账户管理、交易处理、智能合约部署和调用、资产管理等核心功能。

### 主要特性

- 完整的账户管理功能
- 安全的交易处理机制
- 智能合约的部署与调用
- 资产发行与转移
- CTP10 Token标准支持
- 丰富的错误处理机制

## 安装

使用npm安装SDK：

```bash
npm install openchain-nodejs-ts
```

## 快速开始

### 初始化SDK

```javascript
const SDK = require('openchain-nodejs-ts');

const sdk = new SDK({
  host: 'http://your-node-url',
  chainId: 0,
});
```

### 创建账户

```javascript
const account = sdk.account.create();
console.log('地址:', account.address);
console.log('公钥:', account.publicKey);
console.log('私钥:', account.privateKey);
```

## 核心功能

### 账户管理

账户模块提供了完整的账户管理功能：

- 创建账户
- 查询账户信息
- 设置账户权限
- 设置账户元数据

```javascript
// 创建新账户
const newAccount = sdk.account.create();

// 查询账户信息
const accountInfo = yield sdk.account.getInfo(address);

// 设置账户元数据
const setMetadataOperation = {
  sourceAddress: address,
  metadata: 'Hello, OpenChain',
  key: 'myKey',
  value: 'myValue',
};
```

### 交易处理

交易模块支持：

- 构建交易
- 签名交易
- 提交交易
- 查询交易状态

```javascript
// 构建交易
const buildBlobResponse = sdk.transaction.buildBlob({
  sourceAddress: sourceAddress,
  gasPrice: '1000',
  feeLimit: '1000000',
  nonce: '1',
  operations: operations,
});

// 签名交易
const signResponse = sdk.transaction.sign({
  privateKeys: [privateKey],
  blob: buildBlobResponse.result.blob,
});

// 提交交易
const submitResponse = yield sdk.transaction.submit({
  blob: buildBlobResponse.result.blob,
  signature: signResponse.result.signatures,
});
```

### 智能合约

智能合约模块提供：

- 合约部署
- 合约调用
- 合约查询

```javascript
// 调用合约
const contractCallResponse = yield sdk.contract.call({
  contractAddress: 'your-contract-address',
  sourceAddress: sourceAddress,
  input: 'your-contract-input',
  feeLimit: '1000000',
  gasPrice: '1000',
});

// 查询合约信息
const contractInfo = yield sdk.contract.getInfo(contractAddress);
```

### 资产操作

资产模块支持：

- 发行资产
- 转移资产
- 查询资产信息

#### 查询资产信息
```javascript
// 查询账户资产信息
const assetInfo = yield sdk.token.asset.getInfo({
  address: 'your-account-address',    // 账户地址（必填）
  code: 'CNY',                        // 资产代码（必填）
  issuer: 'issuer-address'           // 发行方地址（必填）
});

// 返回结果示例
{
  errorCode: 0,
  errorDesc: '',
  result: {
    assets: [
      {
        key: {
          code: 'CNY',
          issuer: 'issuer-address'
        },
        amount: '10000'
      }
    ]
  }
}
```

#### 发行资产
```javascript
// 发行资产操作
const issueOperation = {
  sourceAddress: address,     // 发行方地址
  code: 'CNY',               // 资产代码
  amount: '10000',           // 发行数量
  metadata: 'asset info'     // 资产元数据（可选）
};

// 构建并提交发行资产交易
const response = yield sdk.operation.asset.issue(issueOperation);
```

#### 转移资产
```javascript
// 转移资产操作
const payAssetOperation = {
  sourceAddress: sourceAddress,    // 源账户地址
  destAddress: destAddress,        // 目标账户地址
  code: 'CNY',                     // 资产代码
  issuer: 'issuer-address',        // 资产发行方地址
  amount: '100',                   // 转移数量
  metadata: 'transfer info'        // 转移说明（可选）
};

// 构建并提交转移资产交易
const response = yield sdk.operation.asset.pay(payAssetOperation);
```

### CTP10 Token

CTP10 Token标准实现：

- 发行Token
- 转移Token
- 授权Token
- 查询Token信息

```javascript
// 发行Token
const issueOperation = {
  sourceAddress: address,
  name: 'MyToken',
  symbol: 'MT',
  totalSupply: '1000000',
  decimals: 8,
};

// 转移Token
const transferOperation = {
  sourceAddress: sourceAddress,
  destAddress: destAddress,
  amount: '100',
};

// 授权Token
const approveOperation = {
  sourceAddress: sourceAddress,
  spender: spenderAddress,
  amount: '1000',
};

// 从授权账户转移Token
const transferFromOperation = {
  sourceAddress: sourceAddress,
  from: fromAddress,
  to: toAddress,
  amount: '100',
};
```

## 错误处理

SDK提供了标准化的错误处理机制：

```javascript
try {
  const response = yield sdk.account.getInfo(address);
  if (response.errorCode !== 0) {
    console.error('错误:', response.errorDesc);
  }
} catch (error) {
  console.error('异常:', error.message);
}
```

常见错误码：
- 0: 操作成功
- 11: 无效地址
- 12: 无效私钥
- 13: 无效公钥
- 14: 无效合约地址
- 15: 无效资产
- 16: 余额不足
- 17: 资产不存在
- 20: 系统错误

## 最佳实践

1. 安全建议
   - 私钥妥善保管，避免明文存储
   - 使用环境变量存储敏感配置
   - 定期更新SDK版本
   - 使用安全的密钥生成方法
   - 实现私钥加密存储机制

2. 性能优化
   - 合理设置gasPrice和feeLimit
   - 批量处理交易时使用交易池
   - 使用异步操作处理并发请求
   - 实现请求重试机制
   - 使用连接池管理网络连接

3. 开发建议
   - 使用TypeScript获得更好的类型提示
   - 遵循Promise/async-await最佳实践
   - 实现适当的错误处理机制
   - 保持良好的日志记录
   - 使用ESLint保持代码质量
   - 编写详细的API文档

4. 测试
   - 在测试网络中充分测试
   - 编写单元测试和集成测试
   - 模拟各种异常情况
   - 进行性能测试
   - 实现自动化测试流程

5. 监控
   - 监控交易状态
   - 记录错误日志
   - 设置适当的告警机制
   - 实现健康检查接口
   - 监控系统资源使用情况

6. 部署
   - 使用容器化部署
   - 实现自动化部署流程
   - 配置负载均衡
   - 实现服务健康检查
   - 建立备份和恢复机制