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"
  }
}