src/api/block.js

   1 /**
   2  * @typedef {Object} BlockInfo
   3  *
   4  * @property {String} hash hash of block.
   5  * @property {Integer} size size of block.
   6  * @property {Integer} version version of block.
   7  * @property {Integer} height height of block.
   8  * @property {String} previous_block_hash previous block hash.
   9  * @property {Integer} timestamp timestamp of block.
  10  * @property {Integer} nonce nonce value.
  11  * @property {Integer} bits bits of difficulty.
  12  * @property {String} difficulty difficulty value(String type).
  13  * @property {String} transaction_merkle_root merkle root of transaction.
  14  * @property {String} transaction_status_hash merkle root of transaction status.
  15  * @property {Object[]} transactions transaction object:
  16  * @property {String} transactions.id transaction id, hash of the transaction.
  17  * @property {Integer} transactions.version version of transaction.
  18  * @property {Integer} transactions.size size of transaction.
  19  * @property {Integer} transactions.time_range the unix timestamp for when the requst was responsed.
  20  * @property {Boolean} transactions.status_fail whether the state of the request has failed.
  21  * @property {String} transactions.mux_id the previous transaction mux id(source id of utxo).
  22  * @property {Object[]} inputs object of inputs for the transaction.
  23  * @property {String} inputs.type the type of input action, available option include: 'spend', 'issue', 'coinbase'.
  24  * @property {String} inputs.asset_id asset id.
  25  * @property {String} inputs.asset_alias name of asset.
  26  * @property {Object} inputs.asset_definition definition of asset(json object).
  27  * @property {Integer} inputs.amount amount of asset.
  28  * @property {Object} inputs.issuance_program issuance program, it only exist when type is 'issue'.
  29  * @property {Object} inputs.control_program control program of account, it only exist when type is 'spend'.
  30  * @property {String} inputs.address address of account, it only exist when type is 'spend'.
  31  * @property {String} inputs.spent_output_id the front of outputID to be spent in this input, it only exist when type is 'spend'.
  32  * @property {String} inputs.account_id account id.
  33  * @property {String} inputs.account_alias name of account.
  34  * @property {Object} inputs.arbitrary arbitrary infomation can be set by miner, it only exist when type is 'coinbase'.
  35  * @property {String} inputs.input_id hash of input action.
  36  * @property {String[]} inputs.witness_arguments witness arguments.
  37  * @property {Object[]} outputs object of outputs for the transaction.
  38  * @property {String} outputs.type the type of output action, available option include: 'retire', 'control'.
  39  * @property {String} outputs.id outputid related to utxo.
  40  * @property {Integer} outputs.position position of outputs.
  41  * @property {String} outputs.asset_id asset id.
  42  * @property {String} outputs.asset_alias name of asset.
  43  * @property {Object} outputs.asset_definition definition of asset(json object).
  44  * @property {Integer} outputs.amount amount of asset.
  45  * @property {String} outputs.account_id account id.
  46  * @property {String} outputs.account_alias name of account.
  47  * @property {Object} outputs.control_program control program of account.
  48  * @property {String} outputs.address address of account.
  49  */
  50
  51
  52 /**
  53  * API for interacting with {@link Block blocks}.
  54  *
  55  * @module BlockAPI
  56  */
  57
  58 const blockAPI = (connection) => {
  59   return {
  60     /**
  61      * Returns the current block height for blockchain.
  62      *
  63      * @returns {Promise<Object>} Promise resolved on success with block_count returned.
  64      */
  65     getBlockCount: () => connection.request('/get-block-count', {}),
  66
  67
  68     /**
  69      * Returns the current block hash for blockchain.
  70      *
  71      * @returns {Promise<Object>} Requested info of specified Bytom Core with block_hash returned.
  72      */
  73     getBlockHash: () => connection.request('/get-block-hash', {} ),
  74
  75     /**
  76      * Returns the detail block by block height or block hash.
  77      *
  78      * @param {Object} params
  79      * @param {String} params.block_hash hash of block.
  80      * @param {Integer} params.block_height height of block.
  81      * @returns {Promise<BlockInfo>}
  82      */
  83     getBlock: (params) => connection.request('/get-block', params),
  84
  85     /**
  86      * Returns the detail block header by block height or block hash.
  87      *
  88      * @param {Object} params
  89      * @param {String} params.block_hash hash of block.
  90      * @param {Integer} params.block_height height of block.
  91      * @returns {Promise<Object>}
  92      */
  93     getBlockHeader: (params) => connection.request('/get-block-header', params),
  94
  95     /**
  96      * Returns the block difficulty by block height or block hash.
  97      *
  98      * @param {Object} params
  99      * @param {String} params.block_hash hash of block.
 100      * @param {Integer} params.block_height height of block.
 101      * @returns {Promise<Object>}
 102      */
 103     getDifficulty: (params) => connection.request('/get-difficulty', params),
 104
 105     /**
 106      * Returns the block hash rate by block height or block hash,
 107      * it returns the current block hash rate when request is empty.
 108      *
 109      * @param {Object} params
 110      * @param {String} params.block_hash hash of block.
 111      * @param {Integer} params.block_height height of block.
 112      * @returns {Promise<Object>}
 113      */
 114     getHashRate: (params) => connection.request('/get-hash-rate', params)
 115   }
 116 }
 117
 118 module.exports = blockAPI