openchain-nodejs-ts-yxl 1.0.1 → 1.0.3

package/doc/SDK_CN.md

@@ -127,7 +127,7 @@ host|   String   | ip地址:端口
 const OpenChainSDK = require('openchain-sdk');
 
 const options = {
-  host: 'localhost/node/api',
+  host: 'nodeapi.aospub.com',
 };
 
 const sdk = new OpenChainSDK(options);

package/example/atp10TokenDemo.js

@@ -6,7 +6,7 @@ const OpenChainSDK = require('openchain-sdk-nodejs');
 // const OpenChainSDK = require('../index');
 
 const sdk = new OpenChainSDK({
-  host: 'localhost/node/api',
+  host: 'nodeapi.aospub.com',
 });
 
 describe('The demo of atp10Token', function() {

package/example/exchange.js

@@ -5,7 +5,7 @@ const BigNumber = require('bignumber.js');
 const OpenChainSDK = require('openchain-sdk');
 
 const sdk = new OpenChainSDK({
-  host: 'localhost/node/api',
+  host: 'nodeapi.aospub.com',
 });
 
 describe('The demo of openchain-sdk for exchange ', function() {

package/example/offlineSignatureDemo.js

@@ -4,7 +4,7 @@ require('chai').should();
 const OpenChainSDK = require('openchain-sdk');
 
 const sdk = new OpenChainSDK({
-  host: 'localhost/node/api',
+  host: 'nodeapi.aospub.com',
 });
 
 describe('The demo of offline signature', function() {

package/example/submitTransactionDemo.js

@@ -5,7 +5,7 @@ const BigNumber = require('bignumber.js');
 const OpenChainSDK = require('openchain-sdk');
 
 const sdk = new OpenChainSDK({
-  host: 'localhost/node/api',
+  host: 'nodeapi.aospub.com',
 });
 
 describe('The demo of submit transaction ', function() {

package/index.d.ts

@@ -1,30 +1,246 @@
+/**
+ * OpenChain SDK配置参数接口
+ */
+export interface OpenChainSDKConfig {
+  /** 区块链节点API地址 */
+  host: string;
+  /** 链ID */
+  chainID?: number;
+  /** 请求超时时间(ms) */
+  timeout?: number;
+  /** 是否使用HTTPS */
+  secure?: boolean;
+}
+
+/**
+ * OpenChain区块链SDK核心类
+ * @class
+ * @example
+ * const sdk = new OpenChainSDK({host: 'http://api.openchain.org'});
+ */
 declare class OpenChainSDK {
-  constructor(config: { host: string });
+  /**
+   * 初始化SDK实例
+   * @param {OpenChainSDKConfig} config 配置参数
+   * @example
+   * const sdk = new OpenChainSDK({
+   *   host: 'http://api.openchain.org',
+   *   chainID: 0,
+   *   timeout: 3000,
+   *   secure: false
+   * });
+   */
+  constructor(config: OpenChainSDKConfig);
 
   account: {
+    /**
+     * 创建区块链账户
+     * @returns {Promise<{errorCode:number, result:{privateKey:string, publicKey:string, address:string}}>}
+     * @example
+     * sdk.account.create().then(console.log);
+     * 
+     * // 错误码:
+     * // - SYSTEM_ERROR 20000 系统错误
+     */
     create(): Promise<{ errorCode: number; result: { privateKey: string; publicKey: string; address: string } }>;
+    /**
+     * 查询账户信息
+     * @param {string} address 账户地址
+     * @returns {Promise<{errorCode:number, result:AccountInfoResult}>}
+     * @example
+     * sdk.account.getInfo('adxS...').then(console.log);
+     * 
+     * // 错误码:
+     * // - INVALID_SOURCEADDRESS_ERROR 11002 无效地址
+     */
     getInfo(address: string): Promise<{ errorCode: number; result: AccountInfoResult }>;
+    /**
+     * 校验账户地址有效性
+     * @param {string} address 待校验的区块链地址（需符合adx开头base58编码格式）
+     * @returns {Promise<{errorCode:number, result:{isValid:boolean}}>}
+     * @example
+     * sdk.account.checkValid('adxSqKcX8wGCMKhzNUBoDWfbeQaMhfnGdtyG2').then(console.log);
+     * 
+     * // 错误码:
+     * // - INVALID_ADDRESS_ERROR 11002 地址格式错误
+     */
     checkValid(address: string): Promise<{ errorCode: number; result: { isValid: boolean } }>;
+
+    /**
+     * 查询账户余额
+     * @param {string} address 账户地址
+     * @returns {Promise<{errorCode:number, result:{balance:string}}>} 余额单位MO（1 MO = 1e8 stroop）
+     * @example
+     * sdk.account.getBalance('adxS...').then(console.log);
+     * 
+     * // 错误码:
+     * // - INVALID_ADDRESS_ERROR 11002 无效地址
+     * // - ACCOUNT_NOT_EXIST 11003 账户不存在
+     */
     getBalance(address: string): Promise<{ errorCode: number; result: { balance: string } }>;
+
+    /**
+     * 获取账户交易序列号
+     * @param {string} address 账户地址
+     * @returns {Promise<{errorCode:number, result:{nonce:string}}>} nonce值用于防止重放攻击
+     * @example
+     * sdk.account.getNonce('adxS...').then(console.log);
+     * 
+     * // 错误码:
+     * // - INVALID_ADDRESS_ERROR 11002 无效地址
+     * // - ACCOUNT_NOT_EXIST 11003 账户不存在
+     */
     getNonce(address: string): Promise<{ errorCode: number; result: { nonce: string } }>;
+
+    /**
+     * 查询账户元数据
+     * @param {Object} params 查询参数
+     * @param {string} params.address 账户地址
+     * @param {string} params.key 元数据键
+     * @returns {Promise<{errorCode:number, result:MetadataResult}>} 包含版本号和值的元数据
+     * @example
+     * sdk.account.getMetadata({address:'adxS...', key:'kyc_info'}).then(console.log);
+     * 
+     * // 错误码:
+     * // - METADATA_NOT_FOUND 12001 元数据不存在
+     * // - INVALID_ADDRESS_ERROR 11002 无效地址
+     */
     getMetadata(params: { address: string; key: string }): Promise<{ errorCode: number; result: MetadataResult }>;
+
+    /**
+     * 检查账户是否激活
+     * @param {string} address 待检查账户地址
+     * @returns {Promise<{errorCode:number, result:{isActivated:boolean}}>}
+     * @example
+     * 参见test/accountActivateOperation.test.js示例
+     * 
+     * // 错误码:
+     * // - ACCOUNT_NOT_ACTIVATED 11004 账户未激活
+     */
     isActivated(address: string): Promise<{ errorCode: number; result: { isActivated: boolean } }>;
   };
 
   contract: {
+    /**
+     * 查询合约信息
+     * @param {string} contractAddress 合约账户地址（需以'adx'开头的base58编码格式）
+     * @returns {Promise<{errorCode:number, result:ContractInfoResult}>}
+     * @example
+     * sdk.contract.getInfo('adxScpCtbeLP2KGRaCkbtrmz8iB5mu6DQcW3r').then(console.log);
+     * 
+     * // 错误码:
+     * // - INVALID_CONTRACTADDRESS_ERROR 11037 无效合约地址
+     * // - CONTRACTADDRESS_NOT_CONTRACTACCOUNT_ERROR 11038 非合约账户地址
+     * // - SYSTEM_ERROR 20000 系统错误
+     */
     getInfo(contractAddress: string): Promise<{ errorCode: number; result: ContractInfoResult }>;
+
+    /**
+     * 通过交易哈希查询合约地址
+     * @param {string} hash 创建合约的交易哈希（64位十六进制字符串）
+     * @returns {Promise<{errorCode:number, result:ContractAddressInfo[]}>}
+     * @example
+     * sdk.contract.getAddress('cc4c...').then(console.log);
+     * 
+     * // 错误码:
+     * // - INVALID_HASH_ERROR 11025 无效交易哈希
+     * // - QUERY_RESULT_NOT_EXIST 12002 查询结果不存在
+     * // 参见test/contractCreateTransaction.test.js示例
+     */
     getAddress(hash: string): Promise<{ errorCode: number; result: ContractAddressInfo[] }>;
+
+    /**
+     * 创建智能合约
+     * @param {ContractCreateParams} params 合约创建参数
+     * @returns {Promise<{errorCode:number, result:ContractAddressInfo}>}
+     * @example
+     * sdk.contract.createContract({
+     *   sourceAddress: 'adx...',
+     *   initBalance: '10',
+     *   type: 0,
+     *   payload: 'contract code'
+     * }).then(console.log);
+     *
+     * // 错误码:
+     * // - INVALID_SOURCEADDRESS_ERROR 11002 无效源地址
+     * // - PAYLOAD_EMPTY_ERROR 11044 合约代码为空
+     */
+    createContract(params: ContractCreateParams): Promise<{ errorCode: number; result: ContractAddressInfo }>;
+
+    /**
+     * 调用智能合约
+     * @param {ContractInvokeParams} params 合约调用参数
+     * @returns {Promise<{errorCode:number, result:ContractInvokeResult}>}
+     * @example
+     * sdk.contract.invokeContract({
+     *   sourceAddress: 'adx...',
+     *   contractAddress: 'adx...',
+     *   input: 'methodName(param)'
+     * }).then(console.log);
+     *
+     * // 错误码:
+     * // - CONTRACT_EXECUTE_FAILED 12003 合约执行失败
+     */
+    invokeContract(params: ContractInvokeParams): Promise<{ errorCode: number; result: ContractInvokeResult }>;
   };
 
   block: {
+    /**
+     * 获取当前区块高度
+     * @returns {Promise<{errorCode:number, result:BlockNumberResult}>} 返回当前区块高度信息
+     * @example
+     * sdk.block.getNumber().then(console.log);
+     * 
+     * // 错误码:
+     * // - SYSTEM_ERROR 20000 系统错误
+     */
     getNumber(): Promise<{ errorCode: number; result: BlockNumberResult }>;
+
+    /**
+     * 检查区块同步状态
+     * @returns {Promise<{errorCode:number, result:BlockStatusResult}>} 返回区块同步状态
+     * @example
+     * sdk.block.checkStatus().then(console.log);
+     * 
+     * // 错误码:
+     * // - SYSTEM_ERROR 20000 系统错误
+     */
     checkStatus(): Promise<{ errorCode: number; result: BlockStatusResult }>;
+
+    /**
+     * 获取指定区块中的交易列表
+     * @param {string} blockNumber 区块高度
+     * @returns {Promise<{errorCode:number, result:TransactionListResult}>} 返回区块中的交易列表
+     * @example
+     * sdk.block.getTransactions('100').then(console.log);
+     * 
+     * // 错误码:
+     * // - INVALID_BLOCKNUMBER_ERROR 11007 无效区块高度
+     * // - BLOCK_NOT_EXIST 11008 区块不存在
+     */
     getTransactions(blockNumber: string): Promise<{ errorCode: number; result: TransactionListResult }>;
   };
 
   operation: {
+    /**
+     * 创建资产发行操作
+     * @param {AssetIssueParams} params 资产发行参数
+     * @returns {OperationResult} 返回操作结果
+     */
     assetIssueOperation(params: AssetIssueParams): { errorCode: number; result: OperationResult };
+
+    /**
+     * 创建账户激活操作
+     * @param {AccountActivateParams} params 账户激活参数
+     * @returns {OperationResult} 返回操作结果
+     */
     accountActivateOperation(params: AccountActivateParams): { errorCode: number; result: OperationResult };
+
+    /**
+     * 创建账户元数据设置操作
+     * @param {MetadataParams} params 元数据设置参数
+     * @returns {OperationResult} 返回操作结果
+     */
     accountSetMetadataOperation(params: MetadataParams): { errorCode: number; result: OperationResult };
   };
 
@@ -36,7 +252,7 @@ declare class OpenChainSDK {
   };
 }
 
-interface AccountInfoResult {
+export interface AccountInfoResult {
   address: string;
   balance: string;
   nonce: string;
@@ -46,7 +262,15 @@ interface AccountInfoResult {
   }>;
 }
 
-interface BlockNumberResult {
+/**
+ * 区块高度查询结果
+ * @interface
+ * @property {Object} header 区块头信息
+ * @property {string} header.blockNumber 区块高度
+ * @property {string} header.timestamp 区块时间戳(毫秒)
+ * @property {number} header.txCount 交易数量
+ */
+export interface BlockNumberResult {
   header: {
     blockNumber: string;
     timestamp: string;
@@ -54,12 +278,19 @@ interface BlockNumberResult {
   };
 }
 
-interface BlockStatusResult {
+export interface BlockStatusResult {
+  /** 是否完成同步 */
   isSynchronous: boolean;
+  
+  /**
+   * 账本版本号
+   * @pattern ^\d+\.\d+\.\d+$
+   * @example "1.2.3"
+   */
   ledgerVersion: string;
 }
 
-interface TransactionListResult {
+export interface TransactionListResult {
   total_count: number;
   transactions: Array<{
     hash: string;
@@ -69,7 +300,22 @@ interface TransactionListResult {
   }>;
 }
 
-interface ContractCreateParams {
+/**
+ * 合约创建参数
+ * @interface
+ * @property {string} sourceAddress 操作源账户地址
+ * @property {string} initBalance 合约账户初始余额(单位MO)
+ * @property {number} type 合约类型(0-JavaScript, 1-EVM)
+ * @property {string} payload 合约代码
+ * @property {string} [initInput] 合约初始化参数
+ * @property {string} [metadata] 操作备注
+ * @example
+ * 参见test/contractCreateTransaction.test.js示例
+ * 
+ * // 错误码:
+ * // - PAYLOAD_EMPTY_ERROR 11044 合约代码为空
+ */
+export interface ContractCreateParams {
   sourceAddress: string;
   initBalance: string;
   type: number;
@@ -78,52 +324,113 @@ interface ContractCreateParams {
   metadata?: string;
 }
 
-interface OperationResult {
+/**
+ * 合约调用参数
+ * @interface
+ * @property {string} sourceAddress 调用者账户地址
+ * @property {string} contractAddress 合约账户地址
+ * @property {string} input 合约调用输入数据
+ * @property {string} [metadata] 操作备注
+ */
+export interface ContractInvokeParams {
+  sourceAddress: string;
+  contractAddress: string;
+  input: string;
+  metadata?: string;
+}
+
+/**
+ * 合约调用结果
+ * @interface
+ * @property {string} result 合约执行结果
+ * @property {string} logs 合约执行日志
+ */
+export interface ContractInvokeResult {
+  result: string;
+  logs: string;
+}
+
+export interface OperationResult {
   operation: {
     type: string;
     data: Record<string, any>;
   };
 }
 
-interface ContractInfoResult {
+/**
+ * 合约信息查询结果
+ * @interface
+ * @property {Object} contract 合约详情
+ * @property {number} contract.type 合约类型(0-JavaScript, 1-EVM)
+ * @property {string} contract.payload 合约字节码/源代码
+ * @example
+ * 参见doc/SDK_CN.md中'getInfo-合约'示例
+ */
+export interface ContractInfoResult {
   contract: {
     type: number;
     payload: string;
   };
 }
 
-interface ContractAddressInfo {
+export interface ContractAddressInfo {
+  /**
+   * 合约账户地址
+   * @pattern ^adx[a-zA-Z0-9]{34}$
+   * @example
+   * 'adxSqKcX8wGCMKhzNUBoDWfbeQaMhfnGdtyG2' // 标准地址格式示例
+   */
   contract_address: string;
+
+  /**
+   * 操作索引号（对应交易中的操作顺序）
+   * @minimum 0
+   * @maximum 100
+   * @example
+   * 0 // 第一个操作
+   */
   operation_index: number;
 }
 
-interface AssetIssueParams {
+export interface AssetIssueParams {
   sourceAddress: string;
   code: string;
   assetAmount: string;
   metadata?: string;
 }
 
-interface MetadataResult {
+export interface MetadataResult {
   version: string;
   value: string;
 }
 
-interface MetadataParams {
+export interface MetadataParams {
   key: string;
   value: string;
   version?: string;
   deleteFlag?: number;
 }
 
-interface AccountActivateParams {
+export interface AccountActivateParams {
   sourceAddress: string;
   destAddress: string;
   initBalance: string;
   metadata?: string;
 }
 
-interface TransactionParams {
+/**
+ * 交易参数结构定义
+ * @interface
+ * @property {string} sourceAddress 交易发起账户地址
+ * @property {string} nonce 交易序列号（需大于上次交易nonce）
+ * @property {OperationResult[]} operations 操作列表
+ * @property {string} [gasPrice] Gas单价（单位MO)
+ * @property {string} [feeLimit] 交易费上限
+ * @property {string} [metadata] 交易备注信息
+ * @example
+ * 参见test/contractCreateTransaction.test.js中的使用示例
+ */
+export interface TransactionParams {
   sourceAddress: string;
   nonce: string;
   operations: OperationResult[];
@@ -132,24 +439,51 @@ interface TransactionParams {
   metadata?: string;
 }
 
-interface TransactionBuildBlobResult {
+export interface TransactionBuildBlobResult {
   transactionBlob: string;
   hash: string;
 }
 
-interface TransactionSignParams {
+export interface TransactionSignParams {
+  /**
+   * 交易原始数据（序列化后的HEX字符串）
+   * @pattern ^[0-9a-fA-F]+$
+   * @example
+   * 参见test/blob.test.js中的签名示例
+   * @example
+   * '0a246275...' // 完整的交易blob示例
+   */
   transactionBlob: string;
+
+  /**
+   * 签名私钥列表（支持多签）
+   * @minItems 1
+   * @maxItems 8
+   * @items {string} 私钥格式要求：以'priv'开头的base58编码字符串
+   * @example
+   * ['privb3dE...', 'privK28m...'] // 多签示例
+   */
   privateKeys: string[];
 }
 
-interface TransactionSignResult {
+export interface TransactionSignResult {
   signatures: Array<{
     signData: string;
     publicKey: string;
   }>;
 }
 
-interface TransactionSubmitParams {
+/**
+ * 交易提交参数
+ * @interface
+ * @property {string} transactionBlob 交易原始数据
+ * @property {Array} signatures 签名列表
+ * @property {Object[]} signatures.signData 签名数据
+ * @property {string} signatures.publicKey 签名公钥
+ * @example
+ * 参见test/log.transaction.test.js中的使用示例
+ */
+export interface TransactionSubmitParams {
   transactionBlob: string;
   signatures: Array<{
     signData: string;
@@ -157,11 +491,25 @@ interface TransactionSubmitParams {
   }>;
 }
 
-interface TransactionSubmitResult {
+export interface TransactionSubmitResult {
   hash: string;
 }
 
-interface TransactionResult {
+/**
+ * 交易详情查询结果
+ * @interface
+ * @property {number} totalCount 总交易数
+ * @property {Array} transactions 交易列表
+ * @property {string} transactions.closeTime 交易关闭时间
+ * @property {number} transactions.errorCode 错误码
+ * @property {string} transactions.errorDesc 错误描述
+ * @property {string} transactions.hash 交易哈希
+ * @property {string} transactions.ledgerSeq 账本序列号
+ * @property {Object} transactions.transaction 交易详情
+ * @example
+ * 参见sdk.transaction.getInfo方法示例
+ */
+export interface TransactionResult {
   totalCount: number;
   transactions: Array<{
     closeTime: string;
@@ -183,4 +531,5 @@ interface TransactionResult {
     };
     txSize: number;
   }>;
-}
+}
+export default OpenChainSDK;

package/index.js

@@ -1,4 +1,6 @@
 'use strict';
+const createBufferPolyfill = require('./lib/common/buffer-polyfill');
+createBufferPolyfill();
 
 const OpenChainSDK = require('./lib/sdk');
 

package/lib/common/buffer-polyfill.js

@@ -0,0 +1,90 @@
+'use strict';
+
+function createBufferPolyfill() {
+  if (typeof window !== 'undefined' && typeof Buffer === 'undefined') {
+    const BufferPolyfill = {
+      from: function(data, encoding) {
+        if (typeof data === 'string') {
+          if (encoding === 'hex') {
+            // 确保十六进制字符串格式正确
+            if (data.length % 2 !== 0) {
+              throw new Error('Invalid hex string');
+            }
+            return Uint8Array.from(data.match(/.{1,2}/g).map(byte => parseInt(byte, 16)));
+          } else if (encoding === 'utf8' || !encoding) {
+            return new TextEncoder().encode(data);
+          }
+        } else if (data instanceof Uint8Array) {
+          return data;
+        } else if (Array.isArray(data)) {
+          return new Uint8Array(data);
+        }
+        throw new Error('Unsupported data type for Buffer.from');
+      },
+      isBuffer: function(obj) {
+        return obj instanceof Uint8Array;
+      },
+      // 添加concat方法
+      concat: function(list, length) {
+        if (!Array.isArray(list)) {
+          throw new Error('Usage: Buffer.concat(list[, length])');
+        }
+
+        if (list.length === 0) {
+          return new Uint8Array(0);
+        }
+
+        let totalLength = 0;
+        for (const buf of list) {
+          totalLength += buf.length;
+        }
+
+        const result = new Uint8Array(length !== undefined ? length : totalLength);
+        let offset = 0;
+        for (const buf of list) {
+          result.set(buf, offset);
+          offset += buf.length;
+        }
+
+        return result;
+      }
+    };
+
+    // 为Uint8Array原型添加toString方法
+    if (!Uint8Array.prototype.toString) {
+      Uint8Array.prototype.toString = function(encoding) {
+        if (encoding === 'hex') {
+          // 添加手动转换备选方案
+          if (typeof Buffer === 'undefined') {
+            return this.manualToHex();
+          }
+          return Array.from(this).map(byte => byte.toString(16).padStart(2, '0')).join('');
+        } else if (encoding === 'utf8' || !encoding) {
+          return new TextDecoder().decode(this);
+        }
+        throw new Error('Unsupported encoding for toString');
+      };
+    }
+
+    // 将手动转换方法挂载到Uint8Array原型链
+Uint8Array.prototype.manualToHex = function() {
+  if (!(this instanceof Uint8Array)) {
+    return Array.from(new Uint8Array(this)).map(byte =>
+      byte.toString(16).padStart(2, '0')
+    ).join('');
+  }
+  return Array.from(this).map(byte =>
+    byte.toString(16).padStart(2, '0')
+  ).join('');
+};
+
+// 确保在浏览器环境中正确设置全局Buffer对象
+    if (typeof window !== 'undefined') {
+      window.Buffer = BufferPolyfill;
+    } else if (typeof global !== 'undefined') {
+      global.Buffer = BufferPolyfill;
+    }
+  }
+}
+
+module.exports = createBufferPolyfill;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "openchain-nodejs-ts-yxl",
-  "version": "1.0.1",
+  "version": "1.0.3",
   "description": "openchain sdk",
   "main": "index.js",
   "types": "index.d.ts",
@@ -25,7 +25,7 @@
     "protobufjs": "^6.8.8",
     "request": "^2.87.0",
     "request-promise": "^4.2.2",
-    "yxchain-encryption-nodejs": "^1.0.1"
+    "yxchain-encryption-nodejs": "^1.0.2"
   },
   "devDependencies": {
     "chai": "^4.1.2",