/**
- * Access tokens are `name:secret-token` pairs that are granted authorization for accessing Chain Core features.
+ * Access tokens are `name:secret-token` pairs that are granted authorization for accessing Bytom Core features.
*
* @typedef {Object} AccessToken
* @global
*
* @returns {Promise<Array<AccessToken>>} All access tokens.
*/
- list: () => connection.request('/list-access-tokens', {}),
+ listAll: () => connection.request('/list-access-tokens', {}),
/**
* Delete the target access token.
*
- * @param {String} id- The to be deleted token id.
+ * @param {String} id The to be deleted token id.
*/
delete: (id) => connection.request('/delete-access-token', {id}),
*
* @param {Object} params - Parameters for access token check.
* @param {String} params.id - The to be deleted token id.
- * @param {String} params.secret, secret of token, the second part of the colon division for token.
+ * @param {String} params.secret secret of token, the second part of the colon division for token.
*/
check: (params) => connection.request('/check-access-token', params),
}
/**
* List accounts whose id is the given one.
*
- * @param {Object} params={} - Filter and pagination information.
+ * @param {Object} params - Filter and pagination information.
* @param {String} params.id - Account id.
* @param {String} params.alias - Account alias.
* @return {Promise<Array<Account>>} Target accounts promise.
/**
* List all addresses for one account.
*
- * @param {Object} params={} - Filter and pagination information.
- * @param {String} params.account_alias, alias of account.
- * @param {String} params.account_id, id of account.
- * @param {Number} params.from, the start position of first address
- * @param {Number} params.count, the number of returned.
+ * @param {Object} params - Filter and pagination information.
+ * @param {String} params.account_alias alias of account.
+ * @param {String} params.account_id id of account.
+ * @param {Number} params.from the start position of first address
+ * @param {Number} params.count the number of returned.
* @return {Promise<module:AccountApi~AddressInfo>} target addresses response.
*
*/
listAddresses: (params) => connection.request('/list-addresses', params),
/**
- * List all addresses for one account.
+ * Validate an address for one account.
*
- * @param {Object} params={} - Filter and pagination information.
- * @param {String} params.account_alias, alias of account.
- * @param {String} params.account_id, id of account.
- * @param {Number} params.from, the start position of first address
- * @param {Number} params.count, the number of returned.
- * @return {Promise<module:AccountApi~AddressInfo>} target addresses response.
+ * @param {string} address - Filter and pagination information.
+ * @return {Promise<Object>} weather the address is local and is valid.
*
*/
validateAddresses: (address) => connection.request('/validate-addresses', {address: address}),
/**
* Delete account.
- * @param {Object} params={} - Deletion information.
+ * @param {Object} params - Deletion information.
* @param {String} params.account_id - Account id.
* @param {String} params.account_alias - Account alias.
*/
/**
* Get asset balances by account.
*
- * @param {Object} params={} - Filter and pagination information.
- * @param {String} params.account_id, account id.
- * @param {String} params.account_alias, name of account.
+ * @param {Object} params - Filter and pagination information.
+ * @param {String} params.account_id account id.
+ * @param {String} params.account_alias name of account.
* @returns {Promise<Array<Balance>>} The result balances.
*/
list: (params) => connection.request('/list-balances', params),
/**
* @typedef {Object} BlockInfo
*
- * @property {String} - hash, hash of block.
- * @property {Integer} - size, size of block.
- * @property {Integer} - version, version of block.
- * @property {Integer} - height, height of block.
- * @property {String} - previous_block_hash, previous block hash.
- * @property {Integer} - timestamp, timestamp of block.
- * @property {Integer} - nonce, nonce value.
- * @property {Integer} - bits, bits of difficulty.
- * @property {String} - difficulty, difficulty value(String type).
- * @property {String} - transaction_merkle_root, merkle root of transaction.
- * @property {String} - transaction_status_hash, merkle root of transaction status.
- * @property {Object[]} - transactions, transaction object:
- * {String} - id, transaction id, hash of the transaction.
- * {Integer} - version, version of transaction.
- * {Integer} - size, size of transaction.
- * {Integer} - time_range, the unix timestamp for when the requst was responsed.
- * {Boolean} - status_fail, whether the state of the request has failed.
- * {String} - mux_id, the previous transaction mux id(source id of utxo).
- * @property {Object[]} - inputs, object of inputs for the transaction.
- * {String} - type, the type of input action, available option include: 'spend', 'issue', 'coinbase'.
- * {String} - asset_id, asset id.
- * {String} - asset_alias, name of asset.
- * {Object} - asset_definition, definition of asset(json object).
- * {Integer} - amount, amount of asset.
- * {Object} - issuance_program, issuance program, it only exist when type is 'issue'.
- * {Object} - control_program, control program of account, it only exist when type is 'spend'.
- * {String} - address, address of account, it only exist when type is 'spend'.
- * {String} - spent_output_id, the front of outputID to be spent in this input, it only exist when type is 'spend'.
- * {String} - account_id, account id.
- * {String} - account_alias, name of account.
- * {Object} - arbitrary, arbitrary infomation can be set by miner, it only exist when type is 'coinbase'.
- * {String} - input_id, hash of input action.
- * {String[]} - witness_arguments, witness arguments.
- * @property {Object[]} - outputs, object of outputs for the transaction.
- * {String} - type, the type of output action, available option include: 'retire', 'control'.
- * {String} - id, outputid related to utxo.
- * {Integer} - position, position of outputs.
- * {String} - asset_id, asset id.
- * {String} - asset_alias, name of asset.
- * {Object} - asset_definition, definition of asset(json object).
- * {Integer} - amount, amount of asset.
- * {String} - account_id, account id.
- * {String} - account_alias, name of account.
- * {Object} - control_program, control program of account.
- * {String} - address, address of account.
-
+ * @property {String} hash hash of block.
+ * @property {Integer} size size of block.
+ * @property {Integer} version version of block.
+ * @property {Integer} height height of block.
+ * @property {String} previous_block_hash previous block hash.
+ * @property {Integer} timestamp timestamp of block.
+ * @property {Integer} nonce nonce value.
+ * @property {Integer} bits bits of difficulty.
+ * @property {String} difficulty difficulty value(String type).
+ * @property {String} transaction_merkle_root merkle root of transaction.
+ * @property {String} transaction_status_hash merkle root of transaction status.
+ * @property {Object[]} transactions transaction object:
+ * @property {String} transactions.id transaction id, hash of the transaction.
+ * @property {Integer} transactions.version version of transaction.
+ * @property {Integer} transactions.size size of transaction.
+ * @property {Integer} transactions.time_range the unix timestamp for when the requst was responsed.
+ * @property {Boolean} transactions.status_fail whether the state of the request has failed.
+ * @property {String} transactions.mux_id the previous transaction mux id(source id of utxo).
+ * @property {Object[]} inputs object of inputs for the transaction.
+ * @property {String} inputs.type the type of input action, available option include: 'spend', 'issue', 'coinbase'.
+ * @property {String} inputs.asset_id asset id.
+ * @property {String} inputs.asset_alias name of asset.
+ * @property {Object} inputs.asset_definition definition of asset(json object).
+ * @property {Integer} inputs.amount amount of asset.
+ * @property {Object} inputs.issuance_program issuance program, it only exist when type is 'issue'.
+ * @property {Object} inputs.control_program control program of account, it only exist when type is 'spend'.
+ * @property {String} inputs.address address of account, it only exist when type is 'spend'.
+ * @property {String} inputs.spent_output_id the front of outputID to be spent in this input, it only exist when type is 'spend'.
+ * @property {String} inputs.account_id account id.
+ * @property {String} inputs.account_alias name of account.
+ * @property {Object} inputs.arbitrary arbitrary infomation can be set by miner, it only exist when type is 'coinbase'.
+ * @property {String} inputs.input_id hash of input action.
+ * @property {String[]} inputs.witness_arguments witness arguments.
+ * @property {Object[]} outputs object of outputs for the transaction.
+ * @property {String} outputs.type the type of output action, available option include: 'retire', 'control'.
+ * @property {String} outputs.id outputid related to utxo.
+ * @property {Integer} outputs.position position of outputs.
+ * @property {String} outputs.asset_id asset id.
+ * @property {String} outputs.asset_alias name of asset.
+ * @property {Object} outputs.asset_definition definition of asset(json object).
+ * @property {Integer} outputs.amount amount of asset.
+ * @property {String} outputs.account_id account id.
+ * @property {String} outputs.account_alias name of account.
+ * @property {Object} outputs.control_program control program of account.
+ * @property {String} outputs.address address of account.
*/
+/**
+ * API for interacting with {@link Block blocks}.
+ *
+ * @module BlockAPI
+ */
const blockAPI = (connection) => {
return {
/**
* Returns the current block height for blockchain.
*
- * @returns {Promise} Promise resolved on success with block_count returned.
+ * @returns {Promise<Object>} Promise resolved on success with block_count returned.
*/
getBlockCount: () => connection.request('/get-block-count', {}),
/**
* Returns the current block hash for blockchain.
*
- * @returns {Promise} Requested info of specified Chain Core with block_hash returned.
+ * @returns {Promise<Object>} Requested info of specified Bytom Core with block_hash returned.
*/
getBlockHash: () => connection.request('/get-block-hash', {} ),
/**
* Returns the detail block by block height or block hash.
*
- * @param params
- * @param {String} params.block_hash, hash of block.
- * @param {Integer} params.block_height, height of block.
+ * @param {Object} params
+ * @param {String} params.block_hash hash of block.
+ * @param {Integer} params.block_height height of block.
* @returns {Promise<BlockInfo>}
*/
getBlock: (params) => connection.request('/get-block', params),
/**
* Returns the detail block header by block height or block hash.
*
- * @param params
- * @param {String} params.block_hash, hash of block.
- * @param {Integer} params.block_height, height of block.
- * @returns {Promise}
+ * @param {Object} params
+ * @param {String} params.block_hash hash of block.
+ * @param {Integer} params.block_height height of block.
+ * @returns {Promise<Object>}
*/
getBlockHeader: (params) => connection.request('/get-block-header', params),
/**
* Returns the block difficulty by block height or block hash.
*
- * @param params
- * @param {String} params.block_hash, hash of block.
- * @param {Integer} params.block_height, height of block.
- * @returns {Promise}
+ * @param {Object} params
+ * @param {String} params.block_hash hash of block.
+ * @param {Integer} params.block_height height of block.
+ * @returns {Promise<Object>}
*/
getDifficulty: (params) => connection.request('/get-difficulty', params),
* Returns the block hash rate by block height or block hash,
* it returns the current block hash rate when request is empty.
*
- * @param params
- * @param {String} params.block_hash, hash of block.
- * @param {Integer} params.block_height, height of block.
- * @returns {Promise}
+ * @param {Object} params
+ * @param {String} params.block_hash hash of block.
+ * @param {Integer} params.block_height height of block.
+ * @returns {Promise<Object>}
*/
getHashRate: (params) => connection.request('/get-hash-rate', params)
}
* More info: {}
* @typedef {Object} CoreInfo
*
- * @property {Boolean} listening, whether the node is listening.
- * @property {Boolean} syncing, whether the node is syncing.
- * @property {Boolean} mining, whether the node is mining.
- * @property {Integer} peer_count, current count of connected peers.
- * @property {Integer} current_block, current block height in the node's blockchain.
- * @property {Integer} highest_block, current highest block of the connected peers.
- * @property {String} network_id, network id.
- * @property {Object} version_info, bytomd version information:
- * @property {String} version, current version of the running bytomd.
- * @property {uint16} update, whether there exists an update.
+ * @property {Boolean} listening whether the node is listening.
+ * @property {Boolean} syncing whether the node is syncing.
+ * @property {Boolean} mining whether the node is mining.
+ * @property {Integer} peer_count current count of connected peers.
+ * @property {Integer} current_block current block height in the node's blockchain.
+ * @property {Integer} highest_block current highest block of the connected peers.
+ * @property {String} network_id network id.
+ * @property {Object} version_info bytomd version information:
+ * @property {String} version current version of the running bytomd.
+ * @property {uint16} update whether there exists an update.
* 0: no update;
* 1: small update;
* 2: significant update.
- * @property {String} new_version, the newest version of bytomd if there is one.
+ * @property {String} new_version the newest version of bytomd if there is one.
*/
/**
* existing blockchain network.
*
* More info: {}
+ * API for interacting with {@link Config configs}.
* @module ConfigApi
*/
const configAPI = (connection) => {
/**
* Get info on specified Bytom Core.
*
- * @param {objectCallback} [callback] - Optional callback. Use instead of Promise return value as desired.
- * @returns {Promise<CoreInfo>} Requested info of specified Bytom Core.
+ * @returns {Promise<CoreInfo>} Requested Net Info of specified Bytom Core.
*/
netInfo: () => connection.request('/net-info',{}),
/**
*
* @param params
- * @param {String} params.address, address for account.
- * @param {String} params.derived_xpub, derived xpub.
- * @param {String} params.message, message for signature by derived_xpub.
- * @param {String} params.signature, signature for message.
- * @returns {*|AxiosPromise<any>}
+ * @param {String} params.address address for account.
+ * @param {String} params.derived_xpub derived xpub.
+ * @param {String} params.message message for signature by derived_xpub.
+ * @param {String} params.signature signature for message.
+ * @returns {Promise<Object>} [Boolean] result, verify result.
*/
verifyMessage: (params) => connection.request('verify-message', params)
}
listAll: () => connection.request('/list-keys'),
/**
- * @param {Object} params={} - Deletion information.
+ * @param {Object} params - Deletion information.
* @param {String} params.xpub - Hex-encoded string representation of the key.
* @param {String} params.password - Key password.
*/
/**
* Reset key password.
*
- * @param {Object} params={} - Password checking information.
+ * @param {Object} params - Password checking information.
* @param {String} params.xpub - Hex-encoded string representation of the key.
* @param {String} params.password - password.
*/
/**
* Reset key password.
*
- * @param {Object} params={} - Key password reset information.
+ * @param {Object} params - Key password reset information.
* @param {String} params.xpub - Hex-encoded string representation of the key.
* @param {String} params.oldPassword - Old password.
* @param {String} params.newPassword - New password.
/**
- * nteger of the time to live in milliseconds, it means utxo will be reserved(locked) for
+ * Integer of the time to live in milliseconds, it means utxo will be reserved(locked) for
* builded transaction in this time range, if the transaction will not to be submitted into block,
* it will be auto unlocked for build transaction again after this ttl time. it will be set to
* 5 minutes(300 seconds) defaultly when ttl is 0.
* @type {Integer}
*/
- // this.ttl = 0
- this.ttl = 1
+ this.ttl = 0
/**
- * Base transaction provided by a third party.
+ * Base data for the transaction, default is null.
* @type {Object}
*/
this.baseTransaction = null
}
/**
- * Add an action that spends an unspent output.
+ * Add an action that spends an account unspent output.
*
* @param {Object} params - Action parameters.
* @param {String} params.output_id - ID of the transaction output to be spent.
*/
- spendUnspentOutput(params) {
+ spendAccountUnspentOutput(params) {
this.actions.push(Object.assign({}, params, {type: 'spend_account_unspent_output'}))
}
* @module TransactionsApi
*/
const transactionsApi = connection => {
+
+ /**
+ * @callback builderCallback
+ * @param {TransactionBuilder} builder
+ */
+
/**
* @typedef {Object} Action
* Basic unit to build a transaction.
*
* @param {module:TransactionsApi~builderCallback} builderBlock - Function that adds desired actions
* to a given builder object.
- * @param {objectCallback} [callback] - Optional callback. Use instead of Promise return value as desired.
* @returns {Promise<Object>} Unsigned transaction template, or error.
*/
build: (builderBlock) => {
* Sign transaction.
*
* @param {Object} params - The built transaction template.
- * @param {String} params.password, signature of the password.
- * @param {Object} params.transaction, builded transaction.
+ * @param {String} params.password signature of the password.
+ * @param {Object} params.transaction builded transaction.
* @returns {Promise<module:TransactionsApi~SignResult>} - Sign result.
*/
sign: (params) => connection.request('/sign-transaction', params),
listAll: () => connection.request('/list-transactions', {unconfirmed: true}),
/**
- * List local transactions by id.
+ * List local transactions by id or filter condition.
*
* @param {Object} params - Transaction filter params.
* @param {String} params.id - transaction id, hash of transaction.
/**
* Get target unspent outputs.
*
- * @param {Object} params={} - Filter and pagination information.
+ * @param {Object} params - Filter and pagination information.
* @param {String} params.id - Unspent output id.
- * @param {Boolean} params.unconfirmed, is include unconfirmed utxo
- * @param {Boolean} params.smart_contract, is contract utxo
- * @param {Integer} params.from, the start position of first utxo
- * @param {Integer} params.count, the number of returned
- * @param {String} params.account_id, account id.
- * @param {String} params.account_alias, name of account.
+ * @param {Boolean} params.unconfirmed is include unconfirmed utxo
+ * @param {Boolean} params.smart_contract is contract utxo
+ * @param {Integer} params.from the start position of first utxo
+ * @param {Integer} params.count the number of returned
+ * @param {String} params.account_id account id.
+ * @param {String} params.account_alias name of account.
* @returns {Promise<Array<UnspentOutput>>} Target unspent outputs.
*/
list: (params) => connection.request('list-unspent-outputs', params)