Links

State

Overview

State APIs provide access to the blockchain state and other database access and management functions. State functions can be accessed from the JSON-API endpoints and within the console environment.

state_getBranches

Returns a list of all known branches.
Parameters: None
Curl Example:
curl -X POST --data '{"jsonrpc":"2.0","method":"state_getBranches" ,"id":21}'

Console Example

> state.getBranches()

Returns:

Array<Object>
Field
Type
Description
height
HexNumber
The height of the branch.
id
String
The unique branch ID.
isBranch
Boolean
Whether the chain is a branch.
length
HexNumber
The number of blocks in the branch.
parentBlockHash
String
The hash of the block where the branch started.
parentBlockNumber
HexNumber
The number of the block where the branch started.
totalDifficulty
HexNumber
The total difficulty of the branch.
timestamp
HexNumber
The unix time of creation of the branch.

Output:

{
"id": 21,
"jsonrpc": "2.0",
"result": [
{
"height": "0x1fdf",
"id": "0xd64e1f13182149cf31a5654aca5df231bce538cf9bc466a919bcc6083d10a913",
"timestamp": "0x1562c9ab49894e99",
"totalDifficulty": "0x13048b3a00"
},
{
"height": "0xb0",
"id": "0x0a08d0a6dae1031f36390fad495072e2e4a243691e54103ead70a1eb7dc4e843",
"isBranch": true,
"length": "0x1",
"parentBlockHash": "0x1c0c76ccfb63bc3aa4dcd096c8db51531529d5522b3a9d6dea93e2ad82cd8fe0",
"parentBlockNumber": "0xaf",
"timestamp": "0x1562cc956b3f41b0",
"totalDifficulty": "0x68e77800"
}
]
}

state_getBlock

Get a block by its number/height.
Parameters
Argument
Type
Description
number
Integer
The block's number
Set number to 0 to return the most recent block on the main branch.
Curl Example:
curl -X POST --data '{"jsonrpc":"2.0","method":"state_getBlock", "params": 2 ,"id":21}'

Console Example

> state.getBlock(number)

Returns:

Block

Output:

{
"id": 21,
"jsonrpc": "2.0",
"result": {
"hash": "0x67e62d1da7bf41a7e7667f9273eefe5255756d14e424a135ea543e4bbb40e659",
"header": {
"creatorPubKey": "48YQpehoRDYsivCbnedrz19DfTvh345PwWAKGN3jdUjPNdG3Lte",
"difficulty": "0x989680",
"extra": "0x",
"nonce": "0x61879fb427b56cef",
"number": "0x2",
"parentHash": "0x211df3aed05b45d620850f40c9b4eac006da7ee0f76a7fa99d5ac16a2c2ca42c",
"stateRoot": "0xc222870b2ca3f71d30b8d06b8e3f633812a8c0473cecc38b6fcc12eb5cad89ec",
"timestamp": "0x5bda0ad4",
"totalDifficulty": "0x1312d00",
"transactionsRoot": "0x0000000000000000000000000000000000000000000000000000000000000000"
},
"sig": "0x3e001b22d640331fbf324138b6182ab851e2989319c37ec33044b5495cd86e2160ca0ca2291e66a06ed329a21f1acc7c1c5fa67d96d0b87f6aaec4892cfcac05",
"transactions": []
}
}

state_getBlockByHash

Get a block by its hash.
Parameters
Argument
Type
Description
hash
String
The block's hash
Curl Example:
curl -X POST --data '{"jsonrpc":"2.0","method":"state_getBlockByHash", "params": "0x67e62d1da7bf41a7e7667f9273eefe5255756d14e424a135ea543e4bbb40e659" ,"id":21}'

Console Example

> state.getBlockByHash("0x67e62d1da7bf41a7e7667f9273eefe5255756d14e424a135ea543e4bbb40e659")

Returns:

Block

Output

{
"id": 21,
"jsonrpc": "2.0",
"result": {
"hash": "0x67e62d1da7bf41a7e7667f9273eefe5255756d14e424a135ea543e4bbb40e659",
"header": {
"creatorPubKey": "48YQpehoRDYsivCbnedrz19DfTvh345PwWAKGN3jdUjPNdG3Lte",
"difficulty": "0x989680",
"extra": "0x",
"nonce": "0x61879fb427b56cef",
"number": "0x2",
"parentHash": "0x211df3aed05b45d620850f40c9b4eac006da7ee0f76a7fa99d5ac16a2c2ca42c",
"stateRoot": "0xc222870b2ca3f71d30b8d06b8e3f633812a8c0473cecc38b6fcc12eb5cad89ec",
"timestamp": "0x5bda0ad4",
"totalDifficulty": "0x1312d00",
"transactionsRoot": "0x0000000000000000000000000000000000000000000000000000000000000000"
},
"sig": "0x3e001b22d640331fbf324138b6182ab851e2989319c37ec33044b5495cd86e2160ca0ca2291e66a06ed329a21f1acc7c1c5fa67d96d0b87f6aaec4892cfcac05",
"transactions": []
}
}

state_getMinedBlocks

Get information about blocks that were mined on the node.
Parameters
Argument
Type
Description
limit
Integer
The maximum number of results to return (default: 25)
lastHash
String
Forces the query to return results after the specified
block hash. Useful for pagination.
creatorPubKey
String
Forces the query to return results for only blocks
created by a given public key.
Curl Example:
curl -X POST --data '{"jsonrpc":"2.0","method":"state_getMinedBlock", "params": { "limit": 1 } ,"id":21}'

Console Example

> state.getMinedBlocks({ limit: 10 })

Returns

Object
Field
Type
Description
blocks
Array<Object>
The slice of objects describing the blocks.
blocks.creatorPubKey
String
The block creator's public key.
blocks.hash
String
The block's hash.
blocks.number
Integer
The block's number.
blocks.timestamp
Integer
The block's timestamp.
blocks.totalFees
String
The total transaction fees from the block.
blocks.txCount
Integer
The number of transactions in the block.
hasMore
Boolean
Indicates that there are more results to be fetched

Output:

{
"id": 21,
"jsonrpc": "2.0",
"result": {
"blocks": [
{
"creatorPubKey": "48jQzKSZ5U1eH7azq7fjqsYCuT129cBMhByrjUQcfQjTTknkE3v",
"hash": "0x8d51a2c86874744d5c690f1bc789b375d7671bf75a45e913339da16350574cba",
"number": "0x9",
"timestamp": 1552074221,
"totalFees": "0",
"txCount": 0
},
{
"creatorPubKey": "48jQzKSZ5U1eH7azq7fjqsYCuT129cBMhByrjUQcfQjTTknkE3v",
"hash": "0xcfcd98936bea3af39959216e6668c0f83c9aeb50f201cf975c26de7127fcd66d",
"number": "0x8",
"timestamp": 1552074202,
"totalFees": "0",
"txCount": 0
}
],
"hasMore": true
}
}

state_getBestChain

Get the main chain
Parameters: None
Curl Example:
curl -X POST --data '{"jsonrpc":"2.0","method":"state_getBestChain", "id":21}'

Console Example

> state.getBestChain()

Returns:

Object
Field
Type
Description
id
String
The chain's unique ID.
height
HexNumber
The height of chain.
totalDifficulty
HexNumber
The chain's total difficulty.
timestamp
HexNumber
The unix time of creation.

Output

{
"id": 21,
"jsonrpc": "2.0",
"result": {
"height": "0x1fdf",
"id": "0xd64e1f13182149cf31a5654aca5df231bce538cf9bc466a919bcc6083d10a913",
"timestamp": "0x1562c9ab49894e99",
"totalDifficulty": "0x13048b3a00"
}
}

state_getOrphans

Get all known orphan blocks
Parameters: None
Curl Example:
curl -X POST --data '{"jsonrpc":"2.0","method":"state_getOrphans", "id":21}'

Console Example

> state.getOrphans()

Returns:

Array<Block>

Output

{
"id": 21,
"jsonrpc": "2.0",
"result": [
{
"hash": "0x67e62d1da7bf41a7e7667f9273eefe5255756d14e424a135ea543e4bbb40e659",
"header": {
"creatorPubKey": "48YQpehoRDYsivCbnedrz19DfTvh345PwWAKGN3jdUjPNdG3Lte",
"difficulty": "0x989680",
"extra": "0x",
"nonce": "0x61879fb427b56cef",
"number": "0x2",
"parentHash": "0x211df3aed05b45d620850f40c9b4eac006da7ee0f76a7fa99d5ac16a2c2ca42c",
"stateRoot": "0xc222870b2ca3f71d30b8d06b8e3f633812a8c0473cecc38b6fcc12eb5cad89ec",
"timestamp": "0x5bda0ad4",
"totalDifficulty": "0x1312d00",
"transactionsRoot": "0x0000000000000000000000000000000000000000000000000000000000000000"
},
"sig": "0x3e001b22d640331fbf324138b6182ab851e2989319c37ec33044b5495cd86e2160ca0ca2291e66a06ed329a21f1acc7c1c5fa67d96d0b87f6aaec4892cfcac05",
"transactions": [...]
}
]
}

state_getReOrgs

Get records of re-organization events
Parameters: None
Curl Example:
curl -X POST --data '{"jsonrpc":"2.0","method":"state_getReOrgs", "id":21}'

Console Example

> state.getReOrgs()

Returns:

Array<Object>
Field
Type
Description
mainChainID
String
The ID of the main chain before the re-org.
reOrgLen
Int
The number of blocks involved in the reorganization.
branchID
String
The unique branch ID.
branchLen
Int
The number of blocks in the branch.
timestamp
Int
The time of creation.

Output

{
"id": 21,
"jsonrpc": "2.0",
"result": [
{
"mainChainID": "0xd64e1f13182149cf31a5654aca5df231bce538cf9bc466a919bcc6083d10a913",
"reOrgLen": 2,
"branchID": "0x1429ab07a29f5f13b0b360803be463e160df113556313b24db6d90f5c686f53f",
"branchLen": 2,
"timestamp": 1541020805
}
]
}

state_getAccount

Get an account
Parameters:
Argument
Type
Description
address
String
The address associated with the account.
Curl Example:
curl -X POST --data '{"jsonrpc":"2.0","method":"state_getAccount", "params": "eGzzf1HtQL7M9Eh792iGHTvb6fsnnPipad", "id":21}'

Console Example

> state.getAccount("eGzzf1HtQL7M9Eh792iGHTvb6fsnnPipad")

Returns:

Account

Output

{
"id": 21,
"jsonrpc": "2.0",
"result": {
"address": "eGzzf1HtQL7M9Eh792iGHTvb6fsnnPipad",
"balance": "100.000000000000000000",
"nonce": 0,
"type": 0
}
}

state_listAccounts

List all accounts
Parameters: None
Curl Example:
curl -X POST --data '{"jsonrpc":"2.0","method":"state_listAccounts", "id":21}'

Console Example

> state.listAccounts()

Returns:

Array<Account>

Output

{
"id": 21,
"jsonrpc": "2.0",
"result": [
{
"address": "e27wBivep3B7XXJWsLhdur5Zq7qvYW8m8c",
"balance": "100.000000000000000000",
"nonce": 0,
"type": 0
},
{
"address": "e27uMdGs5w8vXPJFfGyeFb7ikJTaNThjSV",
"balance": "100.000000000000000000",
"nonce": 0,
"type": 0
}
]
}

state_listTopAccounts

List accounts ordered by their balance in descending order.
Parameters:
Argument
Type
Description
limit
Int
The number of accounts to return
Curl Example:
curl -X POST --data '{"jsonrpc":"2.0","method":"state_listTopAccounts", "params": 10, "id":21}'

Console Example

> state.listTopAccounts(10)

Returns:

Array<Account>

Output

{
"id": 21,
"jsonrpc": "2.0",
"result": [
{
"address": "e27wBivep3B7XXJWsLhdur5Zq7qvYW8m8c",
"balance": "100.000000000000000000",
"nonce": 0,
"type": 0
},
{
"address": "e27uMdGs5w8vXPJFfGyeFb7ikJTaNThjSV",
"balance": "100.000000000000000000",
"nonce": 0,
"type": 0
}
]
}

state_getAccountNonce

Get the current nonce of an account
Parameters:
Argument
Type
Description
address
String
The address of the account
Curl Example:
curl -X POST --data '{"jsonrpc":"2.0","method":"state_getAccountNonce", "params": "e2fFNsXAoyzsYQeopt7PRk3KpKj46nYgvB", "id":21}'

Console Example

> state.getAccountNonce("e2fFNsXAoyzsYQeopt7PRk3KpKj46nYgvB")

Returns:

Integer

Output

{
"id": 21,
"jsonrpc": "2.0",
"result": 2
}

state_getTransaction

Get a transaction by its hash
Parameters:
Argument
Type
Description
hash
String
The transaction's hash
Curl Example:
curl -X POST --data '{"jsonrpc":"2.0","method":"state_getTransaction", "params": "0xf91be74146afb8717834f70969d02edff4316508dc62ec8716104968391fc492", "id":21}'

Console Example

> state.getTransaction("0xf91be74146afb8717834f70969d02edff4316508dc62ec8716104968391fc492")

Returns:

Output

{
"id": 21,
"jsonrpc": "2.0",
"result": {
"fee": "0",
"from": "eNGGuhVSrXWWFYmVQBid9hFhiNLAfvPwzS",
"hash": "0xf91be74146afb8717834f70969d02edff4316508dc62ec8716104968391fc492",
"nonce": "0x0",
"senderPubKey": "497a8Z5sTvCgFZYyQQ8Uh3tgm726uPBzM4v3fNpcygevyCcTJf6",
"sig": "0xe579837d73b45af9cc9e381cfe7009106c5ea6c65a22356a61103e9724b92bbb8a7243a4765d28d9e2aa89d34df585efc08c07fff9eb4a649f60f03f3310890e",
"timestamp": "0x5bcc82b7",
"to": "eGzzf1HtQL7M9Eh792iGHTvb6fsnnPipad",
"type": "0x2",
"value": "100"
}
}

state_getDifficulty

Get the current difficulty and total difficulty of the main chain.
Parameters: None
Curl Example:
curl -X POST --data '{"jsonrpc":"2.0","method":"state_getDifficulty", "id":21}'

Console Example

> state.getDifficulty()

Returns:

Object
Field
Type
Description
difficulty
HexNumber
The current difficulty.
totalDifficulty
HexNumber
The total difficulty of the main chain.

Output

{
"id": 21,
"jsonrpc": "2.0",
"result": {
"difficulty": "0x98fdea",
"totalDifficulty": "0x13048b3a00"
}
}