GetBlocks()
Summary
Route | Type | Example |
---|---|---|
/monitor/getblocks | GET | http://apinode.credits.com/api/monitor/getblocks |
Description
Gets a block or blocks from the blockchain. The method retrieves information about the blocks as a "list" with a single request. Transmitted data volume can be reduced by specifying in the request what data is of interest to the client. Necessary set of information depends on the scenario for how the data will be used in the response, for example:
- Operations analysis, wallet balances update, and so on require *_Transactions *_that allows getting all operations including:
- Transferred amount
- Sender / Recipient (initiator / contract for smart contract transactions)
- Fee and fee limit
- User data
- Signature
Analysis of nodes performance in consensus requires ConsensusInfo that allows getting:
- List of Trusted Nodes (TNs) that participated in block generation
- Signatures of TNs with successful performance
- Lack of signatures as an indicator of poorly performing nodes
- List of TNs of the previous round that selected the current TNs
- Their signatures of the round table
Analysis of nodes participation in consensus on smart contract calls requires *_ContractsApproval *_that allows getting results of smart contract calls (so-called, transactions with new states) for each contract in a block, provided that there are such results in the block:
- Smart contract identifier
- Number of a block containing corresponding to the result call
- List of TNs that participated in consensus for the result on smart contract call
- Package with their signatures and new smart contract state
Signatures verification requires signatures’ values, otherwise setting False to Signatures will disable transmission of signatures’ values (128 characters) sending instead indicators “Signature available” - empty string “” or “No Signature” - null value.
Verification of blockchain connectivity and integrity with hashes requires their value, otherwise setting False to Hashes will disable transmission of hashes (64 characters) sending instead indicators “Hash available” - empty string “” or “No hash” - null value.
Request
General rule: if the information would have returned in a complete data package but was disabled in the request, it returns in the form of an empty value: empty array [] for a list, empty string for a string value. If an element is missing completely, it returns as null.
Request Structure
{
// Parameters common for all requests
"NetworkAlias":"text",
// Parameters specific for this request
// Request for information about the consensus (default false)
“ConsensusInfo”: Bool,
// Request for information about transactions (default false)
“Transactions”: Bool,
// Request for information about the consensus on smart contracts (default false)
“ContractsApproval”: Bool,
// Include values of signatures (default false)
“Signatures”: Bool,
// Include values of hashes (default false)
“Hashes”: Bool,
// Include additional information about transactions. This info can be output on the client based on the response data (default false)
"ExtraTransactionDetails": Bool
}
Request Parameters
bool: ConsensusInfo - response requires detailed information about the consensus, including:
- List of TNs that generated a block, TNs and block signatures
- List of TNs of the previous block that selected TNs from p. 1 and their signatures of the corresponding round table
bool: Transactions - response requires detailed information about all transactions in a block including smart contract calls
bool: ContractsApproval - response requires detailed information about consensus approval of the results for smart contracts calls
bool: Signatures - response requires including of signatures’ byte values
If enabled, each signature is returned in 16-bit (HEX) string representation with the size of 128 characters, corresponding to 64 bytes
If disabled (not required), the signature is returned in 2 possible forms:
- empty string “” - means the signature is available, its value is of no interest to the recipient
- null - signature is missing
bool: Hashes - response requires including of hashes’ byte values
If enabled, each hash is returned in 16-bit (HEX) string representation with the size of 64 characters, corresponding to 32 bytes
If disabled (not required), signature is returned in 2 possible forms:
- empty string “” - means the hash is available, its value is of no interest to the recipient
- null - the hash is missing
u64: BeginSequence - start of the block range
u64: EndSequence - end of the block range
Start and end of the requested range can be set in both in direct order, from the smallest to the biggest, and in reverse order of blocks.
Response
JSON output depends on the request type and its success
If there’s an error accessing the node, the request returns basic Result:
- Success: False
- Message: Upon a successful result, an array of blocks is returned. The set and volume of information for each block are defined by the request.
Response formation begins from the start of the block range and is applied to each block until the end of the block range. A list of blocks for the response ends with either the end of block range or with finding the missing block (usually this is the case when the block is outside of the responding node’s blockchain).
An empty array of blocks is allowed as a result of incorrect range, such as range outside of the blockchain.
Response Structure
If an error occurred during request execution:
{
"success": False,
"message": "Error description text"
}
Upon successful request execution (formatting lines, indentation, and comments are not present in the real response):
[
{ },
…
]