openchain-nodejs-ts-yxl 1.0.3 → 1.0.5

package/index.d.ts

@@ -39,88 +39,228 @@ declare class OpenChainSDK {
      * @example
      * sdk.account.create().then(console.log);
      * 
+     * // 返回示例：
+     * {
+     *   errorCode: 0,
+     *   result: {
+     *     privateKey: 'priv4FXWYaYMpGMeYtEPyUWBCH5aGVGtGR5uvtXGKxgBU2',
+     *     publicKey: 'b001d8236a15923c91eab5b36dc0ea7c5faad04ed9184246a5d18c4547b06c89e4b',
+     *     address: 'adxSZHxE1YzrDRyQCJVpx7aStghSvyJTQAzF'
+     *   }
+     * }
+     * 
      * // 错误码:
      * // - SYSTEM_ERROR 20000 系统错误
+     * // - KEYPAIR_CREATE_ERROR 11031 密钥对创建失败
      */
     create(): Promise<{ errorCode: number; result: { privateKey: string; publicKey: string; address: string } }>;
+
     /**
      * 查询账户信息
-     * @param {string} address 账户地址
+     * @param {string} address 账户地址（需以'adx'开头的base58编码格式）
      * @returns {Promise<{errorCode:number, result:AccountInfoResult}>}
      * @example
-     * sdk.account.getInfo('adxS...').then(console.log);
+     * sdk.account.getInfo('adxSZHxE1YzrDRyQCJVpx7aStghSvyJTQAzF').then(console.log);
+     * 
+     * // 返回示例：
+     * {
+     *   errorCode: 0,
+     *   result: {
+     *     address: 'adxSZHxE1YzrDRyQCJVpx7aStghSvyJTQAzF',
+     *     balance: '1000000000',
+     *     nonce: '1',
+     *     type_thresholds: [{
+     *       type: 1,
+     *       threshold: '1'
+     *     }]
+     *   }
+     * }
      * 
      * // 错误码:
-     * // - INVALID_SOURCEADDRESS_ERROR 11002 无效地址
+     * // - INVALID_ADDRESS_ERROR 11002 无效地址
+     * // - ACCOUNT_NOT_EXIST 11003 账户不存在
+     * // - ACCOUNT_NOT_ACTIVATED 11004 账户未激活
      */
     getInfo(address: string): Promise<{ errorCode: number; result: AccountInfoResult }>;
+
     /**
      * 校验账户地址有效性
-     * @param {string} address 待校验的区块链地址（需符合adx开头base58编码格式）
+     * @param {string} address 待校验的区块链地址（需以'adx'开头的base58编码格式）
      * @returns {Promise<{errorCode:number, result:{isValid:boolean}}>}
      * @example
-     * sdk.account.checkValid('adxSqKcX8wGCMKhzNUBoDWfbeQaMhfnGdtyG2').then(console.log);
+     * sdk.account.checkValid('adxSZHxE1YzrDRyQCJVpx7aStghSvyJTQAzF').then(console.log);
+     * 
+     * // 返回示例：
+     * {
+     *   errorCode: 0,
+     *   result: {
+     *     isValid: true
+     *   }
+     * }
      * 
      * // 错误码:
      * // - INVALID_ADDRESS_ERROR 11002 地址格式错误
+     * // - ADDRESS_LENGTH_ERROR 11003 地址长度错误
+     * // - ADDRESS_CHECKSUM_ERROR 11004 地址校验和错误
      */
     checkValid(address: string): Promise<{ errorCode: number; result: { isValid: boolean } }>;
 
     /**
      * 查询账户余额
-     * @param {string} address 账户地址
+     * @param {string} address 账户地址（需以'adx'开头的base58编码格式）
      * @returns {Promise<{errorCode:number, result:{balance:string}}>} 余额单位MO（1 MO = 1e8 stroop）
      * @example
-     * sdk.account.getBalance('adxS...').then(console.log);
+     * sdk.account.getBalance('adxSZHxE1YzrDRyQCJVpx7aStghSvyJTQAzF').then(console.log);
+     * 
+     * // 返回示例：
+     * {
+     *   errorCode: 0,
+     *   result: {
+     *     balance: '1000000000'  // 10 MO
+     *   }
+     * }
      * 
      * // 错误码:
      * // - INVALID_ADDRESS_ERROR 11002 无效地址
      * // - ACCOUNT_NOT_EXIST 11003 账户不存在
+     * // - ACCOUNT_NOT_ACTIVATED 11004 账户未激活
      */
     getBalance(address: string): Promise<{ errorCode: number; result: { balance: string } }>;
 
     /**
      * 获取账户交易序列号
-     * @param {string} address 账户地址
+     * @param {string} address 账户地址（需以'adx'开头的base58编码格式）
      * @returns {Promise<{errorCode:number, result:{nonce:string}}>} nonce值用于防止重放攻击
      * @example
-     * sdk.account.getNonce('adxS...').then(console.log);
+     * sdk.account.getNonce('adxSZHxE1YzrDRyQCJVpx7aStghSvyJTQAzF').then(console.log);
+     * 
+     * // 返回示例：
+     * {
+     *   errorCode: 0,
+     *   result: {
+     *     nonce: '1'
+     *   }
+     * }
      * 
      * // 错误码:
      * // - INVALID_ADDRESS_ERROR 11002 无效地址
      * // - ACCOUNT_NOT_EXIST 11003 账户不存在
+     * // - ACCOUNT_NOT_ACTIVATED 11004 账户未激活
      */
     getNonce(address: string): Promise<{ errorCode: number; result: { nonce: string } }>;
 
     /**
      * 查询账户元数据
      * @param {Object} params 查询参数
-     * @param {string} params.address 账户地址
-     * @param {string} params.key 元数据键
+     * @param {string} params.address 账户地址（需以'adx'开头的base58编码格式）
+     * @param {string} params.key 元数据键（不超过1024字节）
      * @returns {Promise<{errorCode:number, result:MetadataResult}>} 包含版本号和值的元数据
      * @example
-     * sdk.account.getMetadata({address:'adxS...', key:'kyc_info'}).then(console.log);
+     * sdk.account.getMetadata({
+     *   address: 'adxSZHxE1YzrDRyQCJVpx7aStghSvyJTQAzF',
+     *   key: 'kyc_info'
+     * }).then(console.log);
+     * 
+     * // 返回示例：
+     * {
+     *   errorCode: 0,
+     *   result: {
+     *     version: '1',
+     *     value: 'metadata value'
+     *   }
+     * }
      * 
      * // 错误码:
      * // - METADATA_NOT_FOUND 12001 元数据不存在
      * // - INVALID_ADDRESS_ERROR 11002 无效地址
+     * // - INVALID_DATAKEY_ERROR 11011 无效的元数据键
+     * // - ACCOUNT_NOT_EXIST 11003 账户不存在
      */
     getMetadata(params: { address: string; key: string }): Promise<{ errorCode: number; result: MetadataResult }>;
 
     /**
      * 检查账户是否激活
-     * @param {string} address 待检查账户地址
+     * @param {string} address 待检查账户地址（需以'adx'开头的base58编码格式）
      * @returns {Promise<{errorCode:number, result:{isActivated:boolean}}>}
      * @example
-     * 参见test/accountActivateOperation.test.js示例
+     * sdk.account.isActivated('adxSZHxE1YzrDRyQCJVpx7aStghSvyJTQAzF').then(console.log);
+     * 
+     * // 返回示例：
+     * {
+     *   errorCode: 0,
+     *   result: {
+     *     isActivated: true
+     *   }
+     * }
      * 
      * // 错误码:
+     * // - INVALID_ADDRESS_ERROR 11002 无效地址
+     * // - ACCOUNT_NOT_EXIST 11003 账户不存在
      * // - ACCOUNT_NOT_ACTIVATED 11004 账户未激活
      */
     isActivated(address: string): Promise<{ errorCode: number; result: { isActivated: boolean } }>;
   };
 
   contract: {
+    /**
+     * 检查合约地址有效性
+     * @param {string} contractAddress 合约账户地址
+     * @returns {Promise<{errorCode:number, result:{isValid:boolean}}>}
+     * @example
+     * sdk.contract.checkValid('adxScpCtbeLP2KGRaCkbtrmz8iB5mu6DQcW3r').then(console.log);
+     * 
+     * // 返回示例：
+     * {
+     *   errorCode: 0,
+     *   result: {
+     *     isValid: true
+     *   }
+     * }
+     * 
+     * // 错误码:
+     * // - INVALID_CONTRACTADDRESS_ERROR 11037 无效合约地址
+     * // - ACCOUNT_NOT_EXIST 11003 账户不存在
+     */
+    checkValid(contractAddress: string): Promise<{ errorCode: number; result: { isValid: boolean } }>;
+
+    /**
+     * 调用合约方法
+     * @param {ContractCallParams} args 合约调用参数
+     * @returns {Promise<{errorCode:number, result:ContractCallResult}>}
+     * @example
+     * sdk.contract.call({
+     *   contractAddress: 'adx...',
+     *   sourceAddress: 'adx...',
+     *   input: 'method(param)',
+     *   contractBalance: '0',
+     *   optType: 2,
+     *   feeLimit: '1000000',
+     *   gasPrice: '100'
+     * }).then(console.log);
+     * 
+     * // 返回示例：
+     * {
+     *   errorCode: 0,
+     *   result: {
+     *     logs: 'execution logs',
+     *     queryRets: ['return value'],
+     *     stat: {
+     *       apply_time: 0,
+     *       memory_usage: 0,
+     *       stack_usage: 0,
+     *       step: 0
+     *     }
+     *   }
+     * }
+     * 
+     * // 错误码:
+     * // - INVALID_ARGUMENTS 11001 无效参数
+     * // - INVALID_OPTTYPE_ERROR 11045 无效的操作类型
+     * // - CONTRACTADDRESS_CODE_BOTH_NULL_ERROR 11046 合约地址和代码不能同时为空
+     * // - INVALID_CONTRACTADDRESS_ERROR 11037 无效合约地址
+     */
+    call(args: ContractCallParams): Promise<{ errorCode: number; result: ContractCallResult }>;
+
     /**
      * 查询合约信息
      * @param {string} contractAddress 合约账户地址（需以'adx'开头的base58编码格式）
@@ -128,26 +268,49 @@ declare class OpenChainSDK {
      * @example
      * sdk.contract.getInfo('adxScpCtbeLP2KGRaCkbtrmz8iB5mu6DQcW3r').then(console.log);
      * 
+     * // 返回示例：
+     * {
+     *   errorCode: 0,
+     *   result: {
+     *     contract: {
+     *       type: 0,
+     *       payload: '...'
+     *     }
+     *   }
+     * }
+     * 
      * // 错误码:
      * // - INVALID_CONTRACTADDRESS_ERROR 11037 无效合约地址
      * // - CONTRACTADDRESS_NOT_CONTRACTACCOUNT_ERROR 11038 非合约账户地址
+     * // - CONTRACT_NOT_EXIST 11039 合约不存在
      * // - SYSTEM_ERROR 20000 系统错误
      */
     getInfo(contractAddress: string): Promise<{ errorCode: number; result: ContractInfoResult }>;
-
+    
     /**
      * 通过交易哈希查询合约地址
      * @param {string} hash 创建合约的交易哈希（64位十六进制字符串）
-     * @returns {Promise<{errorCode:number, result:ContractAddressInfo[]}>}
+     * @returns {Promise<{errorCode:number, result:{contractAddressList:ContractAddressInfo[]}}}>}
      * @example
      * sdk.contract.getAddress('cc4c...').then(console.log);
      * 
+     * // 返回示例：
+     * {
+     *   errorCode: 0,
+     *   result: {
+     *     contractAddressList: [{
+     *       contract_address: 'adx...',
+     *       operation_index: 0
+     *     }]
+     *   }
+     * }
+     * 
      * // 错误码:
      * // - INVALID_HASH_ERROR 11025 无效交易哈希
      * // - QUERY_RESULT_NOT_EXIST 12002 查询结果不存在
-     * // 参见test/contractCreateTransaction.test.js示例
+     * // - INVALID_CONTRACT_HASH 11040 无效的合约哈希
      */
-    getAddress(hash: string): Promise<{ errorCode: number; result: ContractAddressInfo[] }>;
+    getAddress(hash: string): Promise<{ errorCode: number; result: { contractAddressList: ContractAddressInfo[] } }>;
 
     /**
      * 创建智能合约
@@ -158,12 +321,25 @@ declare class OpenChainSDK {
      *   sourceAddress: 'adx...',
      *   initBalance: '10',
      *   type: 0,
-     *   payload: 'contract code'
+     *   payload: 'contract code',
+     *   initInput: 'constructor(param)',
+     *   metadata: 'create contract'
      * }).then(console.log);
+     * 
+     * // 返回示例：
+     * {
+     *   errorCode: 0,
+     *   result: {
+     *     contract_address: 'adx...',
+     *     operation_index: 0
+     *   }
+     * }
      *
      * // 错误码:
      * // - INVALID_SOURCEADDRESS_ERROR 11002 无效源地址
      * // - PAYLOAD_EMPTY_ERROR 11044 合约代码为空
+     * // - INVALID_CONTRACT_TYPE 11041 无效的合约类型
+     * // - INVALID_INIT_BALANCE 11042 无效的初始化余额
      */
     createContract(params: ContractCreateParams): Promise<{ errorCode: number; result: ContractAddressInfo }>;
 
@@ -175,11 +351,24 @@ declare class OpenChainSDK {
      * sdk.contract.invokeContract({
      *   sourceAddress: 'adx...',
      *   contractAddress: 'adx...',
-     *   input: 'methodName(param)'
+     *   input: 'methodName(param)',
+     *   metadata: 'invoke contract'
      * }).then(console.log);
+     * 
+     * // 返回示例：
+     * {
+     *   errorCode: 0,
+     *   result: {
+     *     result: 'execution result',
+     *     logs: 'execution logs'
+     *   }
+     * }
      *
      * // 错误码:
      * // - CONTRACT_EXECUTE_FAILED 12003 合约执行失败
+     * // - INVALID_CONTRACTADDRESS_ERROR 11037 无效合约地址
+     * // - CONTRACT_NOT_EXIST 11039 合约不存在
+     * // - INVALID_INPUT_ERROR 11043 无效的输入参数
      */
     invokeContract(params: ContractInvokeParams): Promise<{ errorCode: number; result: ContractInvokeResult }>;
   };
@@ -219,6 +408,102 @@ declare class OpenChainSDK {
      * // - BLOCK_NOT_EXIST 11008 区块不存在
      */
     getTransactions(blockNumber: string): Promise<{ errorCode: number; result: TransactionListResult }>;
+
+    /**
+     * 获取指定区块信息
+     * @param {string} blockNumber 区块高度
+     * @returns {Promise<{errorCode:number, result:BlockInfoResult}>} 返回区块信息
+     * @example
+     * sdk.block.getInfo('100').then(console.log);
+     * 
+     * // 错误码:
+     * // - INVALID_BLOCKNUMBER_ERROR 11007 无效区块高度
+     * // - QUERY_RESULT_NOT_EXIST 12002 查询结果不存在
+     */
+    getInfo(blockNumber: string): Promise<{ errorCode: number; result: BlockInfoResult }>;
+
+    /**
+     * 获取最新区块信息
+     * @returns {Promise<{errorCode:number, result:BlockInfoResult}>} 返回最新区块信息
+     * @example
+     * sdk.block.getLatestInfo().then(console.log);
+     * 
+     * // 错误码:
+     * // - QUERY_RESULT_NOT_EXIST 12002 查询结果不存在
+     */
+    getLatestInfo(): Promise<{ errorCode: number; result: BlockInfoResult }>;
+
+    /**
+     * 获取指定区块的验证者信息
+     * @param {string} blockNumber 区块高度
+     * @returns {Promise<{errorCode:number, result:ValidatorsResult}>} 返回验证者信息
+     * @example
+     * sdk.block.getValidators('100').then(console.log);
+     * 
+     * // 错误码:
+     * // - INVALID_BLOCKNUMBER_ERROR 11007 无效区块高度
+     * // - QUERY_RESULT_NOT_EXIST 12002 查询结果不存在
+     */
+    getValidators(blockNumber: string): Promise<{ errorCode: number; result: ValidatorsResult }>;
+
+    /**
+     * 获取最新区块的验证者信息
+     * @returns {Promise<{errorCode:number, result:ValidatorsResult}>} 返回最新验证者信息
+     * @example
+     * sdk.block.getLatestValidators().then(console.log);
+     * 
+     * // 错误码:
+     * // - QUERY_RESULT_NOT_EXIST 12002 查询结果不存在
+     */
+    getLatestValidators(): Promise<{ errorCode: number; result: ValidatorsResult }>;
+
+    /**
+     * 获取指定区块的奖励信息
+     * @param {string} blockNumber 区块高度
+     * @returns {Promise<{errorCode:number, result:BlockRewardResult}>} 返回区块奖励信息
+     * @example
+     * sdk.block.getReward('100').then(console.log);
+     * 
+     * // 错误码:
+     * // - INVALID_BLOCKNUMBER_ERROR 11007 无效区块高度
+     * // - QUERY_RESULT_NOT_EXIST 12002 查询结果不存在
+     */
+    getReward(blockNumber: string): Promise<{ errorCode: number; result: BlockRewardResult }>;
+
+    /**
+     * 获取最新区块的奖励信息
+     * @returns {Promise<{errorCode:number, result:BlockRewardResult}>} 返回最新区块奖励信息
+     * @example
+     * sdk.block.getLatestReward().then(console.log);
+     * 
+     * // 错误码:
+     * // - QUERY_RESULT_NOT_EXIST 12002 查询结果不存在
+     */
+    getLatestReward(): Promise<{ errorCode: number; result: BlockRewardResult }>;
+
+    /**
+     * 获取指定区块的手续费信息
+     * @param {string} blockNumber 区块高度
+     * @returns {Promise<{errorCode:number, result:BlockFeesResult}>} 返回区块手续费信息
+     * @example
+     * sdk.block.getFees('100').then(console.log);
+     * 
+     * // 错误码:
+     * // - INVALID_BLOCKNUMBER_ERROR 11007 无效区块高度
+     * // - QUERY_RESULT_NOT_EXIST 12002 查询结果不存在
+     */
+    getFees(blockNumber: string): Promise<{ errorCode: number; result: BlockFeesResult }>;
+
+    /**
+     * 获取最新区块的手续费信息
+     * @returns {Promise<{errorCode:number, result:BlockFeesResult}>} 返回最新区块手续费信息
+     * @example
+     * sdk.block.getLatestFees().then(console.log);
+     * 
+     * // 错误码:
+     * // - QUERY_RESULT_NOT_EXIST 12002 查询结果不存在
+     */
+    getLatestFees(): Promise<{ errorCode: number; result: BlockFeesResult }>;
   };
 
   operation: {
@@ -242,12 +527,369 @@ declare class OpenChainSDK {
      * @returns {OperationResult} 返回操作结果
      */
     accountSetMetadataOperation(params: MetadataParams): { errorCode: number; result: OperationResult };
+
+    /**
+     * 创建合约操作
+     * @param {ContractCreateOperationParams} params 合约创建参数
+     * @returns {OperationResult} 返回操作结果
+     * @example
+     * sdk.operation.contractCreateOperation({
+     *   sourceAddress: 'adx...',
+     *   initBalance: '10000',
+     *   type: 0,
+     *   payload: 'contract code'
+     * });
+     */
+    contractCreateOperation(params: ContractCreateOperationParams): { errorCode: number; result: OperationResult };
+
+    /**
+     * 调用合约操作
+     * @param {ContractInvokeOperationParams} params 合约调用参数
+     * @returns {OperationResult} 返回操作结果
+     * @example
+     * sdk.operation.contractInvokeOperation({
+     *   sourceAddress: 'adx...',
+     *   contractAddress: 'adx...',
+     *   input: 'method(param)'
+     * });
+     */
+    contractInvokeOperation(params: ContractInvokeOperationParams): { errorCode: number; result: OperationResult };
+
+    /**
+     * 发送Gas操作
+     * @param {GasSendOperationParams} params Gas发送参数
+     * @returns {OperationResult} 返回操作结果
+     * @example
+     * sdk.operation.gasSendOperation({
+     *   sourceAddress: 'adx...',
+     *   destAddress: 'adx...',
+     *   amount: '1000'
+     * });
+     */
+    gasSendOperation(params: GasSendOperationParams): { errorCode: number; result: OperationResult };
+
+    /**
+     * 创建日志操作
+     * @param {LogCreateOperationParams} params 日志创建参数
+     * @returns {OperationResult} 返回操作结果
+     * @example
+     * sdk.operation.logCreateOperation({
+     *   sourceAddress: 'adx...',
+     *   topic: 'mytopic',
+     *   data: 'log content'
+     * });
+     */
+    logCreateOperation(params: LogCreateOperationParams): { errorCode: number; result: OperationResult };
+  };
+
+  token: {
+    /**
+     * 发行代币
+     * @param {TokenIssueParams} params 代币发行参数
+     * @returns {Promise<{errorCode:number, result:TokenIssueResult}>}
+     * @example
+     * sdk.token.issue({
+     *   sourceAddress: 'adx...',
+     *   name: 'MyToken',
+     *   code: 'MTK',
+     *   totalSupply: '1000000',
+     *   decimals: 8,
+     *   description: 'My test token'
+     * }).then(console.log);
+     * 
+     * // 返回示例：
+     * {
+     *   errorCode: 0,
+     *   result: {
+     *     hash: '0x...',
+     *     token: {
+     *       code: 'MTK',
+     *       issuer: 'adx...'
+     *     }
+     *   }
+     * }
+     * 
+     * // 错误码:
+     * // - INVALID_SOURCEADDRESS_ERROR 11002 无效源地址
+     * // - TOKEN_CODE_INVALID 11101 无效的代币代码
+     * // - TOKEN_ALREADY_EXISTS 11102 代币已存在
+     * // - TOKEN_SUPPLY_LIMIT_ERROR 11103 代币发行量超出限制
+     */
+    issue(params: TokenIssueParams): Promise<{ errorCode: number; result: TokenIssueResult }>;
+
+    /**
+     * 转移代币
+     * @param {TokenTransferParams} params 代币转移参数
+     * @returns {Promise<{errorCode:number, result:TokenTransferResult}>}
+     * @example
+     * sdk.token.transfer({
+     *   sourceAddress: 'adx...',
+     *   destAddress: 'adx...',
+     *   code: 'MTK',
+     *   amount: '100',
+     *   metadata: 'transfer token'
+     * }).then(console.log);
+     * 
+     * // 返回示例：
+     * {
+     *   errorCode: 0,
+     *   result: {
+     *     hash: '0x...'
+     *   }
+     * }
+     * 
+     * // 错误码:
+     * // - INVALID_SOURCEADDRESS_ERROR 11002 无效源地址
+     * // - INVALID_DESTADDRESS_ERROR 11003 无效目标地址
+     * // - TOKEN_NOT_FOUND 11104 代币不存在
+     * // - INSUFFICIENT_TOKEN_BALANCE 11105 代币余额不足
+     */
+    transfer(params: TokenTransferParams): Promise<{ errorCode: number; result: TokenTransferResult }>;
+
+    /**
+     * 查询代币信息
+     * @param {string} code 代币代码
+     * @returns {Promise<{errorCode:number, result:TokenInfoResult}>}
+     * @example
+     * sdk.token.getInfo('MTK').then(console.log);
+     * 
+     * // 返回示例：
+     * {
+     *   errorCode: 0,
+     *   result: {
+     *     token: {
+     *       code: 'MTK',
+     *       name: 'MyToken',
+     *       description: 'My test token',
+     *       decimals: 8,
+     *       totalSupply: '1000000',
+     *       issuer: 'adx...',
+     *       createTime: '1632047037000'
+     *     }
+     *   }
+     * }
+     * 
+     * // 错误码:
+     * // - TOKEN_NOT_FOUND 11104 代币不存在
+     */
+    getInfo(code: string): Promise<{ errorCode: number; result: TokenInfoResult }>;
+
+    /**
+     * 查询代币余额
+     * @param {TokenBalanceParams} params 余额查询参数
+     * @returns {Promise<{errorCode:number, result:TokenBalanceResult}>}
+     * @example
+     * sdk.token.getBalance({
+     *   address: 'adx...',
+     *   code: 'MTK'
+     * }).then(console.log);
+     * 
+     * // 返回示例：
+     * {
+     *   errorCode: 0,
+     *   result: {
+     *     balance: '100',
+     *     frozen: '0'
+     *   }
+     * }
+     * 
+     * // 错误码:
+     * // - INVALID_ADDRESS_ERROR 11002 无效地址
+     * // - TOKEN_NOT_FOUND 11104 代币不存在
+     */
+    getBalance(params: TokenBalanceParams): Promise<{ errorCode: number; result: TokenBalanceResult }>;
+
+    /**
+     * 查询代币持有者列表
+     * @param {TokenHoldersParams} params 持有者查询参数
+     * @returns {Promise<{errorCode:number, result:TokenHoldersResult}>}
+     * @example
+     * sdk.token.getHolders({
+     *   code: 'MTK',
+     *   limit: 10,
+     *   offset: 0
+     * }).then(console.log);
+     * 
+     * // 返回示例：
+     * {
+     *   errorCode: 0,
+     *   result: {
+     *     total: 100,
+     *     holders: [{
+     *       address: 'adx...',
+     *       balance: '1000',
+     *       percentage: '0.001'
+     *     }]
+     *   }
+     * }
+     * 
+     * // 错误码:
+     * // - TOKEN_NOT_FOUND 11104 代币不存在
+     * // - INVALID_PARAMETER 11001 无效参数
+     */
+    getHolders(params: TokenHoldersParams): Promise<{ errorCode: number; result: TokenHoldersResult }>;
+  };
+
+  util: {
+    /**
+     * 检查对象是否为 BigNumber 类型
+     * @param {any} object 要检查的对象
+     * @returns {boolean} 如果对象是 BigNumber 类型返回 true，否则返回 false
+     * @example
+     * const isBig = sdk.util.isBigNumber(new BigNumber('100'));
+     * console.log(isBig); // true
+     */
+    isBigNumber(object: any): boolean;
+
+    /**
+     * 将输入数据转换为 BigNumber 对象
+     * @param {string | number} data 要转换的数据
+     * @returns {BigNumber} 转换后的 BigNumber 对象
+     * @example
+     * const big = sdk.util.toBigNumber('100');
+     * console.log(big.toString()); // '100'
+     */
+    toBigNumber(data: string | number): any; // 返回 BigNumber 类型
+
+    /**
+     * 将 UTF-8 字符串转换为十六进制字符串
+     * @param {string} str UTF-8 字符串
+     * @returns {string} 转换后的十六进制字符串
+     * @example
+     * const hex = sdk.util.utfToHex('Hello');
+     * console.log(hex); // '48656c6c6f'
+     */
+    utfToHex(str: string): string;
+
+    /**
+     * 将十六进制字符串转换为 UTF-8 字符串
+     * @param {string} str 十六进制字符串
+     * @returns {string} 转换后的 UTF-8 字符串
+     * @example
+     * const text = sdk.util.hexToUtf('48656c6c6f');
+     * console.log(text); // 'Hello'
+     */
+    hexToUtf(str: string): string;
+
+    /**
+     * 将 BU 单位的数值转换为 MO 单位
+     * @param {string} bu BU 单位的数值
+     * @returns {string} MO 单位的数值字符串
+     * @example
+     * const mo = sdk.util.buToMo('1');
+     * console.log(mo); // '100000000'
+     */
+    buToMo(bu: string): string;
+
+    /**
+     * 将 MO 单位的数值转换为 BU 单位
+     * @param {string} mo MO 单位的数值
+     * @returns {string} BU 单位的数值字符串
+     * @example
+     * const bu = sdk.util.moToBu('100000000');
+     * console.log(bu); // '1'
+     */
+    moToBu(mo: string): string;
+
+    /**
+     * 根据指定的小数位数计算代币数量
+     * @param {string} amount 代币数量
+     * @param {string} decimals 小数位数
+     * @returns {string | false} 计算后的数值字符串，如果计算结果无效则返回 false
+     * @example
+     * const amount = sdk.util.unitWithDecimals('100', '8');
+     * console.log(amount); // '10000000000'
+     */
+    unitWithDecimals(amount: string, decimals: string): string | false;
   };
 
   transaction: {
-    buildBlob(params: TransactionParams): Promise<{ errorCode: number; result: TransactionBuildBlobResult }>;
+    /**
+     * 构建交易
+     * @param {TransactionBuildBlobParams} params 交易构建参数
+     * @returns {Promise<{errorCode:number, result:TransactionBuildBlobResult}>} 返回交易blob
+     * @example
+     * sdk.transaction.buildBlob({
+     *   sourceAddress: 'adx...',
+     *   gasPrice: '100',
+     *   feeLimit: '1000000',
+     *   nonce: '1',
+     *   operations: [{...}]
+     * }).then(console.log);
+     * 
+     * // 错误码:
+     * // - INVALID_ARGUMENTS 11001 无效参数
+     * // - INVALID_SOURCEADDRESS_ERROR 11002 无效源地址
+     */
+    buildBlob(params: TransactionBuildBlobParams): Promise<{ errorCode: number; result: TransactionBuildBlobResult }>;
+
+    /**
+     * 签名交易
+     * @param {TransactionSignParams} params 签名参数
+     * @returns {Promise<{errorCode:number, result:TransactionSignResult}>} 返回签名结果
+     * @example
+     * sdk.transaction.sign({
+     *   privateKeys: ['priv...'],
+     *   blob: '0x...'
+     * }).then(console.log);
+     * 
+     * // 错误码:
+     * // - INVALID_ARGUMENTS 11001 无效参数
+     * // - PRIVATEKEY_NULL_ERROR 11057 私钥不能为空
+     * // - INVALID_BLOB_ERROR 11056 无效的blob数据
+     */
     sign(params: TransactionSignParams): Promise<{ errorCode: number; result: TransactionSignResult }>;
+
+    /**
+     * 提交交易
+     * @param {TransactionSubmitParams} params 提交参数
+     * @returns {Promise<{errorCode:number, result:TransactionSubmitResult}>} 返回提交结果
+     * @example
+     * sdk.transaction.submit({
+     *   blob: '0x...',
+     *   signatures: [{
+     *     signData: '0x...',
+     *     publicKey: '0x...'
+     *   }]
+     * }).then(console.log);
+     * 
+     * // 错误码:
+     * // - INVALID_ARGUMENTS 11001 无效参数
+     * // - INVALID_BLOB_ERROR 11056 无效的blob数据
+     * // - SIGNATURE_EMPTY_ERROR 11067 签名数据不能为空
+     */
     submit(params: TransactionSubmitParams): Promise<{ errorCode: number; result: TransactionSubmitResult }>;
+
+    /**
+     * 评估交易费用
+     * @param {TransactionEvaluateFeeParams} params 评估参数
+     * @returns {Promise<{errorCode:number, result:TransactionEvaluateFeeResult}>} 返回费用评估结果
+     * @example
+     * sdk.transaction.evaluateFee({
+     *   sourceAddress: 'adx...',
+     *   nonce: '1',
+     *   operations: [{...}],
+     *   signtureNumber: '1'
+     * }).then(console.log);
+     * 
+     * // 错误码:
+     * // - INVALID_ARGUMENTS 11001 无效参数
+     * // - INVALID_SOURCEADDRESS_ERROR 11002 无效源地址
+     * // - INVALID_NONCE_ERROR 11048 无效nonce值
+     */
+    evaluateFee(params: TransactionEvaluateFeeParams): Promise<{ errorCode: number; result: TransactionEvaluateFeeResult }>;
+
+    /**
+     * 获取交易信息
+     * @param {string} hash 交易哈希
+     * @returns {Promise<{errorCode:number, result:TransactionResult}>} 返回交易详情
+     * @example
+     * sdk.transaction.getInfo('0x...').then(console.log);
+     * 
+     * // 错误码:
+     * // - INVALID_HASH_ERROR 11025 无效的交易哈希
+     * // - QUERY_RESULT_NOT_EXIST 12002 查询结果不存在
+     */
     getInfo(hash: string): Promise<{ errorCode: number; result: TransactionResult }>;
   };
 }
@@ -418,6 +1060,70 @@ export interface AccountActivateParams {
   metadata?: string;
 }
 
+/**
+ * 合约创建操作参数
+ * @interface
+ * @property {string} sourceAddress 操作源账户地址
+ * @property {string} initBalance 合约初始化余额
+ * @property {number} type 合约类型(0-JavaScript, 1-EVM)
+ * @property {string} payload 合约代码
+ * @property {string} [initInput] 合约初始化参数
+ * @property {string} [metadata] 操作备注
+ */
+export interface ContractCreateOperationParams {
+  sourceAddress: string;
+  initBalance: string;
+  type: number;
+  payload: string;
+  initInput?: string;
+  metadata?: string;
+}
+
+/**
+ * 合约调用操作参数
+ * @interface
+ * @property {string} sourceAddress 调用者账户地址
+ * @property {string} contractAddress 合约账户地址
+ * @property {string} input 合约调用输入数据
+ * @property {string} [metadata] 操作备注
+ */
+export interface ContractInvokeOperationParams {
+  sourceAddress: string;
+  contractAddress: string;
+  input: string;
+  metadata?: string;
+}
+
+/**
+ * Gas发送操作参数
+ * @interface
+ * @property {string} sourceAddress 发送方账户地址
+ * @property {string} destAddress 接收方账户地址
+ * @property {string} amount 发送金额(单位MO)
+ * @property {string} [metadata] 操作备注
+ */
+export interface GasSendOperationParams {
+  sourceAddress: string;
+  destAddress: string;
+  amount: string;
+  metadata?: string;
+}
+
+/**
+ * 日志创建操作参数
+ * @interface
+ * @property {string} sourceAddress 操作源账户地址
+ * @property {string} topic 日志主题
+ * @property {string} data 日志内容
+ * @property {string} [metadata] 操作备注
+ */
+export interface LogCreateOperationParams {
+  sourceAddress: string;
+  topic: string;
+  data: string;
+  metadata?: string;
+}
+
 /**
  * 交易参数结构定义
  * @interface
@@ -532,4 +1238,251 @@ export interface TransactionResult {
     txSize: number;
   }>;
 }
+
+
+/**
+ * 区块信息查询结果
+ * @interface
+ */
+export interface BlockInfoResult {
+  closeTime: string;
+  number: string;
+  txCount: string;
+  version: string;
+}
+
+/**
+ * 验证者信息查询结果
+ * @interface
+ */
+export interface ValidatorsResult {
+  validators: Array<{
+    address: string;
+    pledge_coin_amount: string;
+    [key: string]: any;
+  }>;
+}
+
+/**
+ * 区块奖励信息查询结果
+ * @interface
+ */
+export interface BlockRewardResult {
+  blockReward: string;
+  validatorsReward: Array<{
+    validator: string;
+    reward: string;
+  }>;
+}
+
+/**
+ * 区块手续费信息查询结果
+ * @interface
+ */
+export interface BlockFeesResult {
+  fees: {
+    base_reserve: string;
+    gas_price: string;
+    [key: string]: any;
+  };
+}
+
+/**
+ * 代币发行参数
+ * @interface
+ * @property {string} sourceAddress 发行者账户地址
+ * @property {string} name 代币名称
+ * @property {string} code 代币代码（唯一标识）
+ * @property {string} totalSupply 发行总量
+ * @property {number} decimals 小数位数(0-8)
+ * @property {string} [description] 代币描述
+ * @property {string} [icon] 代币图标URL
+ * @property {string} [metadata] 操作备注
+ */
+export interface TokenIssueParams {
+  sourceAddress: string;
+  name: string;
+  code: string;
+  totalSupply: string;
+  decimals: number;
+  description?: string;
+  icon?: string;
+  metadata?: string;
+}
+
+/**
+ * 代币发行结果
+ * @interface
+ * @property {string} hash 交易哈希
+ * @property {Object} token 代币信息
+ */
+export interface TokenIssueResult {
+  hash: string;
+  token: {
+    code: string;
+    issuer: string;
+  };
+}
+
+/**
+ * 代币转移参数
+ * @interface
+ * @property {string} sourceAddress 转出账户地址
+ * @property {string} destAddress 转入账户地址
+ * @property {string} code 代币代码
+ * @property {string} amount 转移数量
+ * @property {string} [metadata] 操作备注
+ */
+export interface TokenTransferParams {
+  sourceAddress: string;
+  destAddress: string;
+  code: string;
+  amount: string;
+  metadata?: string;
+}
+
+/**
+ * 代币转移结果
+ * @interface
+ * @property {string} hash 交易哈希
+ */
+export interface TokenTransferResult {
+  hash: string;
+}
+
+/**
+ * 代币信息查询结果
+ * @interface
+ * @property {Object} token 代币详情
+ */
+export interface TokenInfoResult {
+  token: {
+    code: string;
+    name: string;
+    description?: string;
+    decimals: number;
+    totalSupply: string;
+    issuer: string;
+    createTime: string;
+    icon?: string;
+  };
+}
+
+/**
+ * 代币余额查询参数
+ * @interface
+ * @property {string} address 账户地址
+ * @property {string} code 代币代码
+ */
+export interface TokenBalanceParams {
+  address: string;
+  code: string;
+}
+
+/**
+ * 代币余额查询结果
+ * @interface
+ * @property {string} balance 可用余额
+ * @property {string} frozen 冻结金额
+ */
+export interface TokenBalanceResult {
+  balance: string;
+  frozen: string;
+}
+
+/**
+ * 代币持有者查询参数
+ * @interface
+ * @property {string} code 代币代码
+ * @property {number} [limit] 返回记录数量限制
+ * @property {number} [offset] 起始位置偏移量
+ */
+export interface TokenHoldersParams {
+  code: string;
+  limit?: number;
+  offset?: number;
+}
+
+/**
+ * 代币持有者查询结果
+ * @interface
+ * @property {number} total 总持有者数量
+ * @property {Array} holders 持有者列表
+ */
+export interface TokenHoldersResult {
+  total: number;
+  holders: Array<{
+    address: string;
+    balance: string;
+    percentage: string;
+  }>;
+}
+
+/**
+ * 交易构建参数
+ * @interface
+ * @property {string} sourceAddress 交易发起账户地址
+ * @property {string} nonce 交易序列号
+ * @property {OperationResult[]} operations 操作列表
+ * @property {string} [gasPrice] Gas单价(单位MO)
+ * @property {string} [feeLimit] 交易费用上限
+ * @property {string} [metadata] 交易备注
+ * @example
+ * {
+ *   sourceAddress: 'adx...',
+ *   gasPrice: '100',
+ *   feeLimit: '1000000',
+ *   nonce: '1',
+ *   operations: [{...}]
+ * }
+ */
+export interface TransactionBuildBlobParams {
+  sourceAddress: string;
+  nonce: string;
+  operations: OperationResult[];
+  gasPrice?: string;
+  feeLimit?: string;
+  metadata?: string;
+}
+
+/**
+ * 交易费用评估参数
+ * @interface
+ * @property {string} sourceAddress 交易发起账户地址
+ * @property {string} nonce 交易序列号
+ * @property {OperationResult[]} operations 操作列表
+ * @property {string} signtureNumber 签名数量
+ * @property {string} [metadata] 交易备注
+ * @example
+ * {
+ *   sourceAddress: 'adx...',
+ *   nonce: '1',
+ *   operations: [{...}],
+ *   signtureNumber: '1'
+ * }
+ */
+export interface TransactionEvaluateFeeParams {
+  sourceAddress: string;
+  nonce: string;
+  operations: OperationResult[];
+  signtureNumber: string;
+  metadata?: string;
+}
+
+/**
+ * 交易费用评估结果
+ * @interface
+ * @property {string} gasPrice 建议的Gas单价(单位MO)
+ * @property {string} feeLimit 建议的费用上限
+ * @example
+ * {
+ *   gasPrice: '100',
+ *   feeLimit: '1000000'
+ * }
+ */
+export interface TransactionEvaluateFeeResult {
+  gasPrice: string;
+  feeLimit: string;
+}
+
 export default OpenChainSDK;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "openchain-nodejs-ts-yxl",
-  "version": "1.0.3",
+  "version": "1.0.5",
   "description": "openchain sdk",
   "main": "index.js",
   "types": "index.d.ts",