openchain-sdk-yxl-wx-request/index.d.ts

openchain sd YxL wx request

/**
 * OpenChain区块链SDK核心类
 * @class
 * @example
 * const sdk = new OpenChainSDK({host: 'http://api.openchain.org'});
 */
export class OpenChainSDK {
  /**
   * 初始化SDK实例
   * @param {Object} config 配置参数
   * @param {string} config.host 区块链节点API地址
   */
  constructor(config: { host: string, chainID?: number, timeout?: number, secure?: boolean});

  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 };
  };

  transaction: {
    buildBlob(params: TransactionParams): Promise<{ errorCode: number; result: TransactionBuildBlobResult }>;
    sign(params: TransactionSignParams): Promise<{ errorCode: number; result: TransactionSignResult }>;
    submit(params: TransactionSubmitParams): Promise<{ errorCode: number; result: TransactionSubmitResult }>;
    getInfo(hash: string): Promise<{ errorCode: number; result: TransactionResult }>;
  };
}

export interface AccountInfoResult {
  address: string;
  balance: string;
  nonce: string;
  type_thresholds: Array<{
    type: string;
    threshold: string;
  }>;
}

/**
 * 区块高度查询结果
 * @interface
 * @property {Object} header 区块头信息
 * @property {string} header.blockNumber 区块高度
 * @property {string} header.timestamp 区块时间戳(毫秒)
 * @property {number} header.txCount 交易数量
 */
export interface BlockNumberResult {
  header: {
    blockNumber: string;
    timestamp: string;
    txCount: number;
  };
}

export interface BlockStatusResult {
  /** 是否完成同步 */
  isSynchronous: boolean;
  
  /**
   * 账本版本号
   * @pattern ^\d+\.\d+\.\d+$
   * @example "1.2.3"
   */
  ledgerVersion: string;
}

export interface TransactionListResult {
  total_count: number;
  transactions: Array<{
    hash: string;
    sourceAddress: string;
    feeLimit: string;
    gasPrice: string;
  }>;
}

/**
 * 合约创建参数
 * @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;
  payload: string;
  initInput?: string;
  metadata?: string;
}

/**
 * 合约调用参数
 * @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
 * @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;
  };
}

export interface ContractAddressInfo {
  /**
   * 合约账户地址
   * @pattern ^adx[a-zA-Z0-9]{34}$
   * @example
   * 'adxSqKcX8wGCMKhzNUBoDWfbeQaMhfnGdtyG2' // 标准地址格式示例
   */
  contract_address: string;

  /**
   * 操作索引号（对应交易中的操作顺序）
   * @minimum 0
   * @maximum 100
   * @example
   * 0 // 第一个操作
   */
  operation_index: number;
}

export interface AssetIssueParams {
  sourceAddress: string;
  code: string;
  assetAmount: string;
  metadata?: string;
}

export interface MetadataResult {
  version: string;
  value: string;
}

export interface MetadataParams {
  key: string;
  value: string;
  version?: string;
  deleteFlag?: number;
}

export interface AccountActivateParams {
  sourceAddress: string;
  destAddress: string;
  initBalance: string;
  metadata?: string;
}

/**
 * 交易参数结构定义
 * @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[];
  gasPrice?: string;
  feeLimit?: string;
  metadata?: string;
}

export interface TransactionBuildBlobResult {
  transactionBlob: string;
  hash: string;
}

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[];
}

export interface TransactionSignResult {
  signatures: Array<{
    signData: string;
    publicKey: string;
  }>;
}

/**
 * 交易提交参数
 * @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;
    publicKey: string;
  }>;
}

export interface TransactionSubmitResult {
  hash: string;
}

/**
 * 交易详情查询结果
 * @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;
    errorCode: number;
    errorDesc: string;
    hash: string;
    ledgerSeq: string;
    signatures: Array<{
      signData: string;
      publicKey: string;
    }>;
    transaction: {
      sourceAddress: string;
      nonce: string;
      gasPrice: string;
      feeLimit: string;
      metadata?: string;
      operations: OperationResult[];
    };
    txSize: number;
  }>;
}