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: 
​Transaction​
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"
  }
}
​