GetBlocks()

Summary

Route	Type	Example
/monitor/getblocks	GET	http://176.113.80.7:62000/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):

[

{

// The Version of format for binary packing of blocks into bytes for storage

"Version": 0,

// Hash of a previous block (requires Hashes: true)

"PreviousHash": "hex_value",

// Hash of the current block (requires Hashes: true)

"Hash": "hex_value",

// Block ordinal number

"Sequence": "u64_value",

// Block timestamp, Unix time in milliseconds (requires ExtraTransactionDetails: false)

"Timestamp": "u64_value",

// User data (list)

"UserFields":

[

// List element, identifier and one of the 3 values

{

// Element identifier

"Key": "u8_value",

// integer value u64_value, if specified

"Integer": null,

// byte values, if the element contains a byte array

"Bytes": "hex_value",

// Amount value decimal_value, if specified

"Money": null

},

...

],

// Sum of all transaction fees in a block

"RoundCost": "decimal_value",

// List of transactions

"Transactions":

[

// Transaction (requires Transactions: true)

{

// Transaction type: 1 - transfer, 2 - delegation, 3- smart contract, 4 - service, 0 - others

"Type": "u8_value",

// Sender or smart contract initiator

"Source": "base58_value",

// Recipient or initiated smart contract

"Target": "base58_value",

// Total amount

"Sum": "decimal_value",

// Fee limit

"MaxFee": "decimal_value",

// User data (list)

"UserFields":

[

// Elements are the same as in Blocks

...

],

// Transaction signed by sender (requires Signatures: true)

"Signature":"hex_value",

// Actual fee

"ActualFee": "decimal_value",

// Identifier (requires ExtraTransactionDetails: true)

"Id": "text",

// Block timestamp, Unix time in milliseconds (requires  ExtraTransactionDetails: true)

"Timestamp": "u64_value",

// Currency (requires ExtraTransactionDetails: true)

"Currency": "text_value"

},

…

],

// Registration of new wallets with identifier assignment

"IntroducedWallets":

[

//  Element of the list with new accounts

{

// Public key

"Key": "base58_value",

// numeric identifier, synonym for this account

"Id": "u32_value"

},

...

],

// Participants of the consensus that signed the block

"TrustedNodes":

[

// Information about each participant (requires ConsensusInfo: true)

{

// Identifier

"Id": "base58_value",

// Block signature or null, if participant failed (requires Signatures: true)

"Signature": "hex_value"

},

...

],

// Approval of a consensus that generated a block by the previous round consensus

"TrustedApproval":

[

// Element for approval (requires ConsensusInfo: true)

{

// Index in the list of the previous round consensus participants

"Key": "u8_value",

// Signature for round table of this block (requires Signatures: true)

"Value": "hex_value"

},

…

],

// Approval of smart contracts (list)

"ContractsApproval":

[

// Result of the smart contract for approval (requires ContractsApproval: true)

{

// Smart contract identifier

"Key": "base58_value",

// Number of a block storing the list of TNs

"CallSequence": "u64_value",

// Signatures of consensus participants on this call

"Signatures":

[

// Specific consensus participant

{

// Index in the list of TNs

"Key": "u8_value",

//  Signature of the package with result (requires Signatures: true)

"Value": "hex_value"

},

…

]

},

….

]

},

…

]