openchain-sdk-yxl-wx-request/doc/manual/3-transaction-processing.md

openchain sd YxL wx request

# 交易处理

交易处理模块提供了完整的交易生命周期管理，包括交易构建、签名、提交和查询等功能。

## 交易构建

### 基本交易构建
```javascript
// 构建交易数据
const buildBlobResponse = sdk.transaction.buildBlob({
  sourceAddress: sourceAddress,    // 交易发起方地址
  gasPrice: '1000',               // Gas价格
  feeLimit: '1000000',            // 费用限制
  nonce: '1',                     // 交易序号
  operations: operations,         // 操作列表
  ceilLedgerSeq: '',             // 可选，区块高度限制
  metadata: 'transaction info'    // 可选，交易备注
});

// 获取交易的Blob
const blob = buildBlobResponse.result.blob;
```

### 操作列表说明
operations 是一个数组，可以包含多个操作：
```javascript
const operations = [
  {
    type: 'payAsset',           // 操作类型
    data: payAssetOperation     // 操作数据
  },
  {
    type: 'setMetadata',
    data: setMetadataOperation
  }
];
```

## 交易签名

### 单签名
```javascript
// 使用单个私钥签名
const signResponse = sdk.transaction.sign({
  privateKeys: [privateKey],
  blob: blob
});

// 获取签名结果
const signature = signResponse.result.signatures;
```

### 多重签名
```javascript
// 使用多个私钥签名
const multiSignResponse = sdk.transaction.sign({
  privateKeys: [privateKey1, privateKey2],
  blob: blob
});

// 合并多个签名
const signatures = [
  signature1,
  signature2,
  signature3
];
```

## 交易提交

### 提交交易
```javascript
// 提交交易到区块链
const submitResponse = yield sdk.transaction.submit({
  blob: blob,
  signatures: signResponse.result.signatures
});

// 处理提交结果
if (submitResponse.errorCode === 0) {
  console.log('交易提交成功，hash:', submitResponse.result.hash);
} else {
  console.error('交易提交失败:', submitResponse.errorDesc);
}
```

### 批量提交
```javascript
// 批量提交多个交易
const batchSubmit = async (transactions) => {
  const results = [];
  for (const tx of transactions) {
    const response = await sdk.transaction.submit(tx);
    results.push(response);
  }
  return results;
};
```

## 交易查询

### 查询交易信息
```javascript
// 通过交易hash查询交易
const txInfo = yield sdk.transaction.getInfo(txHash);

// 查询交易状态
const txStatus = yield sdk.transaction.getStatus(txHash);
```

### 查询历史交易
```javascript
// 查询账户的历史交易
const txHistory = yield sdk.transaction.getHistory({
  address: accountAddress,
  limit: 10,                // 可选，返回的最大记录数
  offset: 0                 // 可选，起始位置
});
```

## 交易池操作

### 查询交易池
```javascript
// 获取交易池中的交易数量
const pendingCount = yield sdk.transaction.getPendingCount();

// 查询交易池中的交易列表
const pendingQueue = yield sdk.transaction.getPendingQueue();
```

### 交易池状态监控
```javascript
// 监控交易池状态
const monitorPool = async () => {
  const count = await sdk.transaction.getPendingCount();
  if (count > 1000) {
    console.warn('交易池拥堵，当前待处理交易数:', count);
  }
};
```

## 最佳实践

1. Gas费用设置
   ```javascript
   // 根据网络状况动态调整Gas价格
   const getOptimalGasPrice = async () => {
     const networkInfo = await sdk.blockchain.getInfo();
     return Math.max(networkInfo.gasPrice * 1.1, 1000);
   };
   ```

2. 交易重试机制
   ```javascript
   const submitWithRetry = async (transaction, maxRetries = 3) => {
     for (let i = 0; i < maxRetries; i++) {
       try {
         const response = await sdk.transaction.submit(transaction);
         if (response.errorCode === 0) return response;
         
         // 特定错误码才重试
         if ([11007, 19999].includes(response.errorCode)) {
           await new Promise(resolve => setTimeout(resolve, 1000 * (i + 1)));
           continue;
         }
         throw new Error(response.errorDesc);
       } catch (error) {
         if (i === maxRetries - 1) throw error;
       }
     }
   };
   ```

3. 交易确认检查
   ```javascript
   const waitForConfirmation = async (txHash, maxAttempts = 10) => {
     for (let i = 0; i < maxAttempts; i++) {
       const status = await sdk.transaction.getStatus(txHash);
       if (status.confirmed) return true;
       await new Promise(resolve => setTimeout(resolve, 3000));
     }
     return false;
   };
   ```

4. 批量交易处理
   ```javascript
   const processBatchTransactions = async (operations, batchSize = 5) => {
     const batches = [];
     for (let i = 0; i < operations.length; i += batchSize) {
       const batch = operations.slice(i, i + batchSize);
       const batchTx = await sdk.transaction.buildBlob({
         operations: batch,
         // ... 其他参数
       });
       batches.push(batchTx);
     }
     return batches;
   };
   ```

5. 交易监控
   ```javascript
   const monitorTransaction = async (txHash) => {
     const startTime = Date.now();
     const maxWaitTime = 5 * 60 * 1000; // 5分钟
     
     while (Date.now() - startTime < maxWaitTime) {
       const status = await sdk.transaction.getStatus(txHash);
       if (status.confirmed) {
         return { success: true, status };
       }
       await new Promise(resolve => setTimeout(resolve, 3000));
     }
     return { success: false, error: '交易确认超时' };
   };
   ```