
<!----------------------------------------------------------------------------->
<!-------------------- THIS MARKDOWN FILE IS AUTOGENERATED -------------------->
<!----------------------------------------------------------------------------->

# snarkos-rpc

[![Crates.io](https://img.shields.io/crates/v/snarkos-rpc.svg?color=neon)](https://crates.io/crates/snarkos-rpc)
[![Authors](https://img.shields.io/badge/authors-Aleo-orange.svg)](../AUTHORS)
[![License: GPL v3](https://img.shields.io/badge/License-GPLv3-blue.svg)](./LICENSE.md)

On Aleo, full nodes run a [JSON-RPC](https://www.jsonrpc.org/specification) server
to enable API calls for fetching data and interacting with peers connected to the network.

## RPC Port

```ignore
snarkos --rpc-port 3030
```

The default RPC port is `3030`. A custom RPC port may be specified using the `--rpc-port` flag when starting a node.

## Authentication for Private RPC Endpoints

```ignore
snarkos --rpc-username {USERNAME} --rpc-password {PASSWORD}
```

The RPC server exposes protected RPC endpoints for account specific operations, such as creating an account,
creating a transaction, and fetching record commitments.
RPC requests to protected RPC endpoints can be optionally guarded with an authentication header.

To enable this authentication layer, provide the authentication credentials to
the `--rpc-username` and `--rpc-password` flags when booting up a full node.



## decoderawtransaction
Returns information about a transaction from serialized transaction bytes.

### Arguments

|      Parameter      |  Type  | Required |            Description            |
|:------------------- |:------:|:--------:|:--------------------------------- |
| `transaction_bytes` | string |    Yes   | The raw transaction hex to decode |

### Response

|        Parameter        |  Type  |                Description                |
|:-----------------------:|:------:|:----------------------------------------- |
| `txid`                  | string | The transaction id                        |
| `size`                  | number | The size of the transaction in bytes      |
| `old_serial_numbers`    | array  | The list of old record serial numbers     |
| `new_commitments`       | array  | The list of new record commitments        |
| `memo`                  | string | The transaction memo                      |
| `network_id`            | number | The transaction network id                |
| `digest`                | string | The merkle tree digest                    |
| `transaction_proof`     | string | The transaction zero knowledge proof      |
| `program_commitment`    | string | The program verification key commitment   |
| `local_data_root`       | string | The local data root                       |
| `value balance`         | number | The transaction value balance             |
| `signatures`            | array  | The list of transaction signatures        |
| `encrypted_records`     | array  | The list of new encrypted records         |
| `transaction_metadata`  | object | The transaction metadata                  |

### Example
```ignore
curl --data-binary '{"jsonrpc": "2.0", "id":"documentation", "method": "decoderawtransaction", "params": ["transaction_hexstring"] }' -H 'content-type: application/json' http://127.0.0.1:3030/
```

## getbestblockhash
Returns the block hash of the head of the best valid chain.

### Arguments

None

### Response

| Parameter |  Type  |                  Description                  |
|:---------:|:------:|:---------------------------------------------:|
| `result`  | string | The block hash of the most recent valid block |

### Example
```ignore
curl --data-binary '{"jsonrpc": "2.0", "id":"documentation", "method": "getbestblockhash", "params": [] }' -H 'content-type: application/json' http://127.0.0.1:3030/
```

## getblock
Returns information about a block from a block hash.

### Arguments

|  Parameter   |  Type  | Required |              Description              |
|:------------ |:------:|:--------:|:------------------------------------- |
| `block_hash` | string |    Yes   | The block hash of the requested block |

### Response

|        Parameter       |  Type  |                               Description                              |
|:----------------------:|:------:|:----------------------------------------------------------------------:|
| `confirmations`        | number | The number of confirmations for this block                             |
| `difficulty_target`    | number | The difficulty of the block                                            |
| `hash`                 | string | The block hash (same as provided)                                      |
| `height`               | number | The block height                                                       |
| `merkle_root`          | number | The Merkle root of the transactions in the block                       |
| `nonce`                | number | The nonce for solving the PoSW puzzle                                  |
| `pedersen_merkle_root` | number | The Merkle root of the transactions in the block using a Pedersen hash |
| `previous_block_hash`  | string | The block hash of the parent block                                     |
| `proof`                | string | The Proof of Succinct Work                                             |
| `size`                 | number | The size of the block in bytes                                         |
| `time`                 | number | The block time                                                         |
| `transactions`         | array  | The list of transaction ids included in the block                      |

### Example
```ignore
curl --data-binary '{"jsonrpc": "2.0", "id":"documentation", "method": "getblock", "params": ["caf49293d36f0215cfb3296dbc871a0ef5e5dcfc61f91cd0c9ac2c730f84d853"] }' -H 'content-type: application/json' http://127.0.0.1:3030/
```

## getblockcount
Returns the number of blocks in the best valid chain.

### Arguments

None

### Response

| Parameter |  Type  |                  Description                 |
|:---------:|:------:|:--------------------------------------------:|
| `result`  | number | The number of blocks in the best valid chain |

### Example
```ignore
curl --data-binary '{"jsonrpc": "2.0", "id":"documentation", "method": "getblockcount", "params": [] }' -H 'content-type: application/json' http://127.0.0.1:3030/
```

## getblockhash
Returns the block hash of a block at the given block height in the best valid chain.

### Arguments

|    Parameter   |  Type  | Required |                  Description                 |
|:-------------- |:------:|:--------:|:-------------------------------------------- |
| `block_height` | number |    Yes   | The block height of the requested block hash |

### Response

| Parameter |  Type  |                      Description                      |
|:---------:|:------:|:-----------------------------------------------------:|
| `result`  | string | The block hash of the block at the given block height |

### Example
```ignore
curl --data-binary '{"jsonrpc": "2.0", "id":"documentation", "method": "getblockhash", "params": [100] }' -H 'content-type: application/json' http://127.0.0.1:3030/
```

## getblocktemplate
Returns the current mempool and consensus information known by this node.

### Arguments

None

### Response

|       Parameter       |  Type  |                      Description                      |
|:--------------------- |:------:|:----------------------------------------------------- |
| `previous_block_hash` | string | The hash of current highest block                     |
| `block_height`        | number | The height of the next block                          |
| `time`                | number | The current timestamp                                 |
| `difficulty_target`   | number | The block difficulty target                           |
| `transactions`        | array  | The list of raw transactions to include in the block  |
| `coinbase_value`      | number | The amount spendable by the coinbase transaction      |

### Example
```ignore
curl --data-binary '{"jsonrpc": "2.0", "id":"documentation", "method": "getblocktemplate", "params": [] }' -H 'content-type: application/json' http://127.0.0.1:3030/
```

## getconnectioncount
Returns the number of connected peers this node has.

### Arguments

None

### Response

| Parameter |  Type  |          Description          |
|:---------:|:------:|:----------------------------- |
| `result`  | number | The number of connected nodes |

### Example
```ignore
curl --data-binary '{"jsonrpc": "2.0", "id":"documentation", "method": "getconnectioncount", "params": [] }' -H 'content-type: application/json' http://127.0.0.1:3030/
```

## getnodeinfo
Returns information about the node.

### Arguments

None 

### Response

|   Parameter  | Type |                  Description                  |
|:------------:|:----:|:---------------------------------------------:|
|  `is_miner`  | bool | Flag indicating if the node is a miner        |
| `is_snycing` | bool | Flag indicating if the node currently syncing |

### Example
```ignore
curl --data-binary '{"jsonrpc": "2.0", "id":"documentation", "method": "getnodeinfo", "params": [] }' -H 'content-type: application/json' http://127.0.0.1:3030/
```

## getpeerinfo
Returns the node's connected peers.

### Arguments

None 

### Response

| Parameter |  Type |           Description          |
|:---------:|:-----:|:------------------------------:|
| `peers`   | array | The list of connected peer IPs |

### Example
```ignore
curl --data-binary '{"jsonrpc": "2.0", "id":"documentation", "method": "getpeerinfo", "params": [] }' -H 'content-type: application/json' http://127.0.0.1:3030/
```

## getrawtransaction
Returns hex encoded bytes of a transaction from its transaction id.

### Arguments

|     Parameter    |  Type  | Required |                     Description                     |
|:---------------- |:------:|:--------:|:--------------------------------------------------- |
| `transaction_id` | string |    Yes   | The transaction id of the requested transaction hex |

### Response

| Parameter |  Type  |            Description            |
|:---------:|:------:|:---------------------------------:|
| `result`  | string | The hex-encoded transaction bytes |

### Example
```ignore
curl --data-binary '{"jsonrpc": "2.0", "id":"documentation", "method": "getrawtransaction", "params": ["83fc73b8a104d7cdabe514ec4ddfeb7fd6284ff8e0a757d25d8479ed0ffe608b"] }' -H 'content-type: application/json' http://127.0.0.1:3030/
```

## gettransactioninfo
Returns information about a transaction from a transaction id.

### Arguments

|     Parameter    |  Type  | Required |                      Description                     |
|:---------------- |:------:|:--------:|:---------------------------------------------------- |
| `transaction_id` | string |    Yes   | The transaction id of the requested transaction info |

### Response

|        Parameter        |  Type  |                Description               |
|:-----------------------:|:------:|:---------------------------------------- |
| `txid`                  | string | The transaction id                       |
| `size`                  | number | The size of the transaction in bytes     |
| `old_serial_numbers`    | array  | The list of old record serial numbers    |
| `new_commitments`       | array  | The list of new record commitments       |
| `memo`                  | string | The transaction memo                     |
| `network_id`            | number | The transaction network id               |
| `digest`                | string | The merkle tree digest                   |
| `transaction_proof`     | string | The transaction zero knowledge proof     |
| `program_commitment`    | string | The program verification key commitment  |
| `local_data_root`       | string | The local data root                      |
| `value balance`         | number | The transaction value balance            |
| `signatures`            | array  | The list of transaction signatures       |
| `encrypted_records`     | array  | The list of new encrypted records        |
| `transaction_metadata`  | object | The transaction metadata                 |

### Example
```ignore
curl --data-binary '{"jsonrpc": "2.0", "id":"documentation", "method": "gettransactioninfo", "params": ["83fc73b8a104d7cdabe514ec4ddfeb7fd6284ff8e0a757d25d8479ed0ffe608b"] }' -H 'content-type: application/json' http://127.0.0.1:3030/
```

## sendtransaction
Send raw transaction bytes to this node to be added into the mempool. If valid, the transaction will be stored and propagated to all peers.

### Arguments

|      Parameter      |  Type  | Required |              Description             |
|:------------------- |:------:|:--------:|:------------------------------------ |
| `transaction_bytes` | string |    Yes   | The raw transaction hex to broadcast |

### Response

| Parameter |  Type  |                 Description                |
|:---------:|:------:|:------------------------------------------ |
| `result`  | string | The transaction id of the sent transaction |

### Example
```ignore
curl --data-binary '{"jsonrpc": "2.0", "id":"documentation", "method": "sendtransaction", "params": ["transaction_hexstring"] }' -H 'content-type: application/json' http://127.0.0.1:3030/
```

## validaterawtransaction
Validate and return if the transaction is valid.

### Arguments

|      Parameter      |  Type  | Required |             Description             |
|:------------------- |:------:|:--------:|:----------------------------------- |
| `transaction_bytes` | string |    Yes   | The raw transaction hex to validate |

### Response

| Parameter |   Type  |             Description             |
|:---------:|:-------:|:----------------------------------- |
| `result`  | boolean | Check that the transaction is valid |

### Example
```ignore
curl --data-binary '{"jsonrpc": "2.0", "id":"documentation", "method": "validaterawtransaction", "params": ["transaction_hexstring"] }' -H 'content-type: application/json' http://127.0.0.1:3030/
```



## createaccount
Creates a new account private key and its corresponding account address.

### Protected Endpoint

Yes

### Arguments

`None`

### Response

|   Parameter   |  Type  |         Description         |
|:------------- |:------:|:--------------------------- |
| `private_key` | string | An Aleo account private key |
| `address`     | string | An Aleo account address     |

### Example
```ignore
curl --user username:password --data-binary '{"jsonrpc": "2.0", "id":"documentation", "method": "createaccount", "params": [] }' -H 'content-type: application/json' http://127.0.0.1:3030/ 
```

## createrawtransaction
Creates a new transaction and returns the encoded transaction along with the encoded records.

### Protected Endpoint

Yes

### Arguments

|          Parameter         |  Type  | Required |                        Description                       |
|:-------------------------- |:------:|:--------:|:-------------------------------------------------------- |
| `old_records`              |  array |    Yes   | An array of hex encoded records to be spent              |
| `old_account_private_keys` |  array |    Yes   | An array of private keys authorized to spend the records |
| `recipients`               |  array |    Yes   | The array of transaction recipient objects               |
| `memo`                     | string |    No    | The transaction memo                                     |
| `network_id`               | number |    Yes   | The network id of the transaction                        |

Transaction Recipient Object

| Parameter |  Type  |            Description           |
|:---------:|:------:|:--------------------------------:|
| `address` | string | The recipient address            |
| `value`   | number | The amount sent to the recipient |

### Response

|       Parameter       |  Type  |                  Description                  |
|:---------------------:|:------:|:--------------------------------------------- |
| `encoded_transaction` | string | The hex encoding of the generated transaction |
| `encoded_records`     | array  | The hex encodings of the generated records    |

### Example
```ignore
curl --user username:password --data-binary '{ 
    "jsonrpc":"2.0",
    "id": "1",
    "method": "createrawtransaction",
    "params": [
       {
        "old_records": ["record_hexstring"],
        "old_account_private_keys": ["private_key_string"],
        "recipients": [{
                "address": "address_string",
                "amount": amount
        }],
        "memo": "memo_hexstring",
        "network_id": 0
       }
    ]
}' -H 'content-type: application/json' http://127.0.0.1:3030/
```

## createtransaction
Create a new transaction from a given transaction kernel, returning the encoded transaction and the new records.

### Protected Endpoint

Yes

### Arguments

|       Parameter      |  Type  | Required |             Description            |
|:--------------------:|:------:|:--------:|:----------------------------------:|
| `transaction_kernel` | string |    Yes   | The hex encoded transaction kernel |

### Response

|       Parameter       |  Type  |                  Description                  |
|:---------------------:|:------:|:--------------------------------------------- |
| `encoded_transaction` | string | The hex encoding of the generated transaction |
| `encoded_records`     | array  | The hex encodings of the generated records    |

### Example
```ignore
curl --user username:password --data-binary '{ 
    "jsonrpc":"2.0",
    "id": "1",
    "method": "createtransaction",
    "params": ["transaction_kernel_hexstring"]
}' -H 'content-type: application/json' http://127.0.0.1:3030/
```

## createtransactionkernel
Create a new transaction kernel.

### Protected Endpoint

Yes

### Arguments

|          Parameter         |  Type  | Required |                        Description                       |
|:-------------------------- |:------:|:--------:|:-------------------------------------------------------- |
| `old_records`              |  array |    Yes   | An array of hex encoded records to be spent              |
| `old_account_private_keys` |  array |    Yes   | An array of private keys authorized to spend the records |
| `recipients`               |  array |    Yes   | The array of transaction recipient objects               |
| `memo`                     | string |    No    | The transaction memo                                     |
| `network_id`               | number |    Yes   | The network id of the transaction                        |

Transaction Recipient Object

| Parameter |  Type  |            Description           |
|:---------:|:------:|:--------------------------------:|
| `address` | string | The recipient address            |
| `value`   | number | The amount sent to the recipient |

### Response

|       Parameter      |  Type  | Required |             Description            |
|:--------------------:|:------:|:--------:|:----------------------------------:|
| `transaction_kernel` | string |    Yes   | The hex encoded transaction kernel |

### Example
```ignore
curl --user username:password --data-binary '{ 
    "jsonrpc":"2.0",
    "id": "1",
    "method": "createtransactionkernel",
    "params": [
       {
        "old_records": ["record_hexstring"],
        "old_account_private_keys": ["private_key_string"],
        "recipients": [{
                "address": "address_string",
                "amount": amount
        }],
        "memo": "memo_hexstring",
        "network_id": 0
       }
    ]
}' -H 'content-type: application/json' http://127.0.0.1:3030/
```

## decoderecord
Returns information about a record from serialized record hex.

### Arguments

|    Parameter   |  Type  | Required |          Description         |
|:--------------:|:------:|:--------:|:----------------------------:|
| `record_bytes` | string |    Yes   | The raw record hex to decode |

### Response

|        Parameter        |  Type  |            Description            |
|:-----------------------:|:------:|:---------------------------------:|
| `owner`                 | string | The owner of the record           |
| `is_dummy`              | number | The height of the next block      |
| `value`                 | number | The current timestamp             |
| `payload`               | object | The record payload                |
| `birth_program_id`      | string | The birth program representation  |
| `death_program_id`      | string | The death program representation  |
| `serial_number_nonce`   | string | The serial number nonce           |
| `commitment`            | string | The record commitment             |
| `commitment_randomness` | string | The record commitment randomness  |

### Example
```ignore
curl --data-binary '{"jsonrpc": "2.0", "id":"documentation", "method": "decoderecord", "params": ["record_hexstring"] }' -H 'content-type: application/json' http://127.0.0.1:3030/
```

## decryptrecord
Decrypts the encrypted record and returns the hex encoded bytes of the record.

### Arguments

|      Parameter      |  Type  | Required |                     Description                     |
|:-------------------:|:------:|:--------:|:---------------------------------------------------:|
|  `encrypted_record` | string |    Yes   |                 The encrypted record                |
|  `account_view_key` | string |    Yes   | The account view key used to decrypt the ciphertext |

### Response

| Parameter |  Type  |          Description         |
|:---------:|:------:|:---------------------------- |
| `result`  | string | The hex-encoded record bytes |


### Example
```ignore
curl --user username:password --data-binary '{ 
    "jsonrpc":"2.0",
    "id": "1",
    "method": "decryptrecord",
    "params": [
       {
        "encrypted_record": "encrypted_record_string",
        "account_view_key": "account_view_key_string"
       }
    ]
}' -H 'content-type: application/json' http://127.0.0.1:3030/
```
## getrawrecord
Returns the hex encoded bytes of a record from its record commitment.

### Protected Endpoint

Yes

### Arguments

|      Parameter      |  Type  | Required |      Description      |
|:-------------------:|:------:|:--------:|:--------------------- |
| `record_commitment` | string |    Yes   | The record commitment |

### Response

| Parameter |  Type  |          Description         |
|:---------:|:------:|:---------------------------- |
| `result`  | string | The hex-encoded record bytes |

### Example
```ignore
curl --user username:password --data-binary '{"jsonrpc": "2.0", "id":"documentation", "method": "getrawrecord", "params": ["86be61d5f3bd795e31615d6834efefca01ad023d57c0383e2231e094bcabfc05"] }' -H 'content-type: application/json' http://127.0.0.1:3030/ 
```

## getrecordcommitmentcount
Returns the number of record commitments that are stored on the full node.

### Protected Endpoint

Yes

### Arguments

`None`

### Response

| Parameter |  Type  |               Description               |
|:---------:|:------:|:--------------------------------------- |
| `result`  | number | The number of stored record commitments |

### Example
```ignore
curl --user username:password --data-binary '{"jsonrpc": "2.0", "id":"documentation", "method": "getrecordcommitmentcount", "params": [] }' -H 'content-type: application/json' http://127.0.0.1:3030/ 
```

## getrecordcommitments
Returns a list of record commitments that are stored on the full node.

### Protected Endpoint

Yes

### Arguments

`None`

### Response

| Parameter |  Type |              Description              |
|:---------:|:-----:|:------------------------------------- |
| `result`  | array | The list of stored record commitments |

### Example
```ignore
curl --user username:password --data-binary '{"jsonrpc": "2.0", "id":"documentation", "method": "getrecordcommitments", "params": [] }' -H 'content-type: application/json' http://127.0.0.1:3030/ 
```




## Contributing
 
### How to Update this README

This README is auto-generated during continuous integration.
To update this README, submit a pull request updating the appropriate Markdown file
in [documentation](./documentation) and the [configuration file](./documentation/config.json).

