# 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:** 

```bash
curl -X POST --data '{"jsonrpc":"2.0","method":"state_getBranches" ,"id":21}'
```

#### Console Example

```javascript
> state.getBranches()
```

#### Returns:

`Array<Object>`&#x20;

| Field             | Type                                                                                                                                    | Description                                       |
| ----------------- | --------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------- |
| height            | [HexNumber](https://ellcrys.gitbook.io/ellcrys/~/edit/drafts/-LPGzTZQXM_D8Pctq4-D/v/master/object-references/hex-value-types#hexnumber) | The height of the branch.                         |
| id                | String                                                                                                                                  | The unique branch ID.                             |
| isBranch          | Boolean                                                                                                                                 | Whether the chain is a branch.                    |
| length            | [HexNumber](https://ellcrys.gitbook.io/ellcrys/~/edit/drafts/-LPGzTZQXM_D8Pctq4-D/v/master/object-references/hex-value-types#hexnumber) | The number of blocks in the branch.               |
| parentBlockHash   | String                                                                                                                                  | The hash of the block where the branch started.   |
| parentBlockNumber | [HexNumber](https://ellcrys.gitbook.io/ellcrys/~/edit/drafts/-LPGzTZQXM_D8Pctq4-D/v/master/object-references/hex-value-types#hexnumber) | The number of the block where the branch started. |
| totalDifficulty   | [HexNumber](https://ellcrys.gitbook.io/ellcrys/~/edit/drafts/-LPGzTZQXM_D8Pctq4-D/v/master/object-references/hex-value-types#hexnumber) | The total difficulty of the branch.               |
| timestamp         | [HexNumber](https://ellcrys.gitbook.io/ellcrys/~/edit/drafts/-LPGzTZQXM_D8Pctq4-D/v/master/object-references/hex-value-types#hexnumber) | The unix time of creation of the branch.          |

#### Output:

```javascript
{
  "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.&#x20;

**Parameters**

| Argument | Type    | Description        |
| -------- | ------- | ------------------ |
| number   | Integer | The block's number |

{% hint style="info" %}
Set number to **0** to return the most recent block on the main branch.
{% endhint %}

**Curl Example:**&#x20;

```bash
curl -X POST --data '{"jsonrpc":"2.0","method":"state_getBlock", "params": 2 ,"id":21}'
```

#### Console Example

```javascript
> state.getBlock(number)
```

#### Returns:

[`Block`](https://ellcrys.gitbook.io/ellcrys/~/edit/drafts/-LPGzTZQXM_D8Pctq4-D/v/master/object-references/block)&#x20;

#### Output:

```javascript
{
  "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.&#x20;

**Parameters**

| Argument | Type   | Description      |
| -------- | ------ | ---------------- |
| hash     | String | The block's hash |

**Curl Example:**&#x20;

```bash
curl -X POST --data '{"jsonrpc":"2.0","method":"state_getBlockByHash", "params": "0x67e62d1da7bf41a7e7667f9273eefe5255756d14e424a135ea543e4bbb40e659" ,"id":21}'
```

#### Console Example

```javascript
> state.getBlockByHash("0x67e62d1da7bf41a7e7667f9273eefe5255756d14e424a135ea543e4bbb40e659")
```

#### Returns:

[`Block`](https://ellcrys.gitbook.io/ellcrys/~/edit/drafts/-LPGzTZQXM_D8Pctq4-D/v/master/object-references/block)&#x20;

#### Output

```javascript
{
  "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.&#x20;

**Parameters**

| Argument      | Type    | Description                                                                                             |
| ------------- | ------- | ------------------------------------------------------------------------------------------------------- |
| limit         | Integer | The maximum number of results to return (default: 25)                                                   |
| lastHash      | String  | <p>Forces the query to return results after the specified </p><p>block hash. Useful for pagination.</p> |
| creatorPubKey | String  | <p>Forces the query to return results for only blocks </p><p>created by a given public key.</p>         |

**Curl Example:**&#x20;

```bash
curl -X POST --data '{"jsonrpc":"2.0","method":"state_getMinedBlock", "params": { "limit": 1 } ,"id":21}'
```

#### Console Example

```javascript
> 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          | [S](https://ellcrys.gitbook.io/ellcrys/~/edit/drafts/-LPGzTZQXM_D8Pctq4-D/v/master/object-references/hex-value-types#hexnumber)tring | 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:

```javascript
{
  "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&#x20;

**Parameters:** None

**Curl Example:**&#x20;

```bash
curl -X POST --data '{"jsonrpc":"2.0","method":"state_getBestChain", "id":21}'
```

#### Console Example

```javascript
> state.getBestChain()
```

#### Returns:&#x20;

`Object`

| Field           | Type                                                                                                                                    | Description                   |
| --------------- | --------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------- |
| id              | String                                                                                                                                  | The chain's unique ID.        |
| height          | [HexNumber](https://ellcrys.gitbook.io/ellcrys/~/edit/drafts/-LPGzTZQXM_D8Pctq4-D/v/master/object-references/hex-value-types#hexnumber) | The height of chain.          |
| totalDifficulty | [HexNumber](https://ellcrys.gitbook.io/ellcrys/~/edit/drafts/-LPGzTZQXM_D8Pctq4-D/v/master/object-references/hex-value-types#hexnumber) | The chain's total difficulty. |
| timestamp       | [HexNumber](https://ellcrys.gitbook.io/ellcrys/~/edit/drafts/-LPGzTZQXM_D8Pctq4-D/v/master/object-references/hex-value-types#hexnumber) | The unix time of creation.    |

#### Output

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

## state\_getOrphans

Get all known orphan blocks&#x20;

**Parameters:** None

**Curl Example:**&#x20;

```bash
curl -X POST --data '{"jsonrpc":"2.0","method":"state_getOrphans", "id":21}'
```

#### Console Example

```javascript
> state.getOrphans()
```

#### Returns:&#x20;

`Array<`[`Block`](https://ellcrys.gitbook.io/ellcrys/~/edit/drafts/-LPGzTZQXM_D8Pctq4-D/v/master/object-references/block)`>`

#### Output

```javascript
{
  "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&#x20;

**Parameters:** None

**Curl Example:**&#x20;

```bash
curl -X POST --data '{"jsonrpc":"2.0","method":"state_getReOrgs", "id":21}'
```

#### Console Example

```javascript
> state.getReOrgs()
```

#### Returns:&#x20;

`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

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

## state\_getAccount

Get an account

**Parameters:**&#x20;

| Argument | Type   | Description                              |
| -------- | ------ | ---------------------------------------- |
| address  | String | The address associated with the account. |

**Curl Example:**&#x20;

```bash
curl -X POST --data '{"jsonrpc":"2.0","method":"state_getAccount", "params": "eGzzf1HtQL7M9Eh792iGHTvb6fsnnPipad", "id":21}'
```

#### Console Example

```javascript
> state.getAccount("eGzzf1HtQL7M9Eh792iGHTvb6fsnnPipad")
```

#### Returns:&#x20;

[`Account`](https://ellcrys.gitbook.io/ellcrys/~/edit/drafts/-LPGzTZQXM_D8Pctq4-D/v/master/object-references/account)

#### Output

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

## state\_listAccounts

List all accounts

**Parameters:** None

**Curl Example:**&#x20;

```bash
curl -X POST --data '{"jsonrpc":"2.0","method":"state_listAccounts", "id":21}'
```

#### Console Example

```javascript
> state.listAccounts()
```

#### Returns:&#x20;

`Array<`[`Account`](https://ellcrys.gitbook.io/ellcrys/~/edit/drafts/-LPGzTZQXM_D8Pctq4-D/v/master/object-references/account)`>`

#### Output

```javascript
{
  "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:**&#x20;

| Argument | Type | Description                      |
| -------- | ---- | -------------------------------- |
| limit    | Int  | The number of accounts to return |

**Curl Example:**&#x20;

```bash
curl -X POST --data '{"jsonrpc":"2.0","method":"state_listTopAccounts", "params": 10, "id":21}'
```

#### Console Example

```javascript
> state.listTopAccounts(10)
```

#### Returns:&#x20;

`Array<`[`Account`](https://ellcrys.gitbook.io/ellcrys/~/edit/drafts/-LPGzTZQXM_D8Pctq4-D/v/master/object-references/account)`>`

#### Output

```javascript
{
  "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:**&#x20;

| Argument | Type   | Description                |
| -------- | ------ | -------------------------- |
| address  | String | The address of the account |

**Curl Example:**&#x20;

```bash
curl -X POST --data '{"jsonrpc":"2.0","method":"state_getAccountNonce", "params": "e2fFNsXAoyzsYQeopt7PRk3KpKj46nYgvB", "id":21}'
```

#### Console Example

```javascript
> state.getAccountNonce("e2fFNsXAoyzsYQeopt7PRk3KpKj46nYgvB")
```

#### Returns:&#x20;

`Integer`

#### Output

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

## state\_getTransaction

Get a transaction by its hash

**Parameters:**&#x20;

| Argument | Type   | Description            |
| -------- | ------ | ---------------------- |
| hash     | String | The transaction's hash |

**Curl Example:**&#x20;

```bash
curl -X POST --data '{"jsonrpc":"2.0","method":"state_getTransaction", "params": "0xf91be74146afb8717834f70969d02edff4316508dc62ec8716104968391fc492", "id":21}'
```

#### Console Example

```javascript
> state.getTransaction("0xf91be74146afb8717834f70969d02edff4316508dc62ec8716104968391fc492")
```

#### Returns:&#x20;

[`Transaction`](https://ellcrys.gitbook.io/ellcrys/~/edit/drafts/-LPGzTZQXM_D8Pctq4-D/v/master/object-references/transaction)

#### Output

```javascript
{
  "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:**&#x20;

```bash
curl -X POST --data '{"jsonrpc":"2.0","method":"state_getDifficulty", "id":21}'
```

#### Console Example

```javascript
> state.getDifficulty()
```

#### Returns:&#x20;

`Object`

| Field           | Type                                                                                                                                    | Description                             |
| --------------- | --------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------- |
| difficulty      | [HexNumber](https://ellcrys.gitbook.io/ellcrys/~/edit/drafts/-LPGzTZQXM_D8Pctq4-D/v/master/object-references/hex-value-types#hexnumber) | The current difficulty.                 |
| totalDifficulty | [HexNumber](https://ellcrys.gitbook.io/ellcrys/~/edit/drafts/-LPGzTZQXM_D8Pctq4-D/v/master/object-references/hex-value-types#hexnumber) | The total difficulty of the main chain. |

#### Output

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