# snarkos-rpc [](https://crates.io/crates/snarkos-rpc) [](../AUTHORS) [](./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_hash` | 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/ ``` ## getnetworkgraph Returns the network graph crawled by this node (if it is a crawler). ### Arguments None ### Response | Parameter | Type | Description | | :----------------------------------: | :--------: | :---------------------------------------------------------------------------------------: | | `node_count` | usize | The number of nodes known by the node | | `connection_count` | usize | The number of connection known by the node | | `density` | f64 | The density of the known network | | `algebraic_connectivity` | f64 | The algebraic connectivity, aka the fiedler eigenvalue of the known network | | `degree_centrality_delta` | f64 | The difference between the largest and the smallest peer count in the network | | `potential_tip` | Option | The crawler's best guess at the canon block height and member addresses | | `potential_forks` | array | The crawler's best guess at the forks in the network | | `edges` | array | The list of connections known by the node | | `vertices` | array | The list of nodes known by the node | | `edges[i].source` | SocketAddr | One side of the crawled connection | | `edges[i].target` | SocketAddr | The other side of the crawled connection | | `vertices[i].addr` | SocketAddr | The recorded address of the crawled node | | `vertices[i].is_beacon` | bool | Indicates whether the node is a beacon | | `vertices[i].is_sync_provider` | bool | Indicates whether the node is a sync provider | | `vertices[i].degree_centrality` | u16 | The node's degree centrality, aka its connection count | | `vertices[i].eigenvector_centrality` | f64 | The node's eigenvector centrality, indicates its relative importance in the network | | `vertices[i].fiedler_value` | f64 | The node's fiedler value, can be used to partition the network graph | ### Example ```ignore curl --data-binary '{"jsonrpc": "2.0", "id":"documentation", "method": "getnetworkgraph", "params": [] }' -H 'content-type: application/json' http://127.0.0.1:3030/ ``` ## getnodeinfo Returns information about the node. ### Arguments None ### Response | Parameter | Type | Description | |:----------------:|:-------------:|:---------------------------------------------:| | `node_type` | NodeType | Flag indicating the node type | | `is_miner` | bool | Flag indicating if the node is a miner | | `is_syncing` | bool | Flag indicating if the node currently syncing | | `launched` | timestamp | The timestamp of when the node was launched | | `listening_addr` | SocketAddr | The configured listening address of the node | | `version` | string | The version of the client binary | | `min_peers` | number | The minimum desired number of connected peers | | `max_peers` | number | The maximum allowed number of connected peers | ### Example ```ignore curl --data-binary '{"jsonrpc": "2.0", "id":"documentation", "method": "getnodeinfo", "params": [] }' -H 'content-type: application/json' http://127.0.0.1:3030/ ``` ## getnodestats Returns statistics related to the node. ### Arguments None ### Response | Parameter | Type | Description | | :------------------------------: | :--: | :--------------------------------------------------------------------------: | | `blocks.height` | u32 | The current block height of the node | | `blocks.mined` | u32 | The number of blocks the node has mined | | `blocks.inbound_processing_time` | f64 | The average processing time of an inbound block in seconds | | `blocks.commit_time` | f64 | The block verification and commit time in seconds | | `blocks.duplicates` | u64 | The number of duplicate blocks received | | `blocks.duplicates_sync` | u64 | The number of duplicate sync blocks received | | `connections.all_accepted` | u64 | The number of connection requests the node has received | | `connections.all_initiated` | u64 | The number of connection requests the node has made | | `connections.all_rejected` | u64 | The number of connection requests the node has rejected | | `connections.average_duration` | f64 | The average connection duration in seconds | | `connections.connected_peers` | u32 | The number of currently connected peers | | `connections.connecting_peers` | u32 | The number of currently connecting peers | | `connections.disconnected_peers` | u32 | The number of known disconnected peers | | `handshakes.failures_init` | u64 | The number of failed handshakes as the initiator | | `handshakes.failures_resp` | u64 | The number of failed handshakes as the responder | | `handshakes.successes_init` | u64 | The number of successful handshakes as the initiator | | `handshakes.successes_resp` | u64 | The number of successful handshakes as the responder | | `handshakes.timeouts_init` | u64 | The number of handshake timeouts as the initiator | | `handshakes.timeouts_resp` | u64 | The number of handshake timeouts as the responder | | `inbound.all_successes` | u64 | The number of successfully processed inbound messages | | `inbound.all_failures` | u64 | The number of inbound messages that couldn't be processed | | `inbound.blocks` | u64 | The number of all received Block messages | | `inbound.getblocks` | u64 | The number of all received GetBlocks messages | | `inbound.getmemorypool` | u64 | The number of all received GetMemoryPool messages | | `inbound.getpeers` | u64 | The number of all received GetPeers messages | | `inbound.getsync` | u64 | The number of all received GetSync messages | | `inbound.memorypool` | u64 | The number of all received MemoryPool messages | | `inbound.peers` | u64 | The number of all received Peers messages | | `inbound.pings` | u64 | The number of all received Ping messages | | `inbound.pongs` | u64 | The number of all received Pong messages | | `inbound.syncs` | u64 | The number of all received Sync messages | | `inbound.syncblocks` | u64 | The number of all received SyncBlock messages | | `inbound.transactions` | u64 | The number of all received Transaction messages | | `inbound.unknown` | u64 | The number of all received Unknown messages | | `internal_rtt.getpeer` | f64 | The average internal RTT (query to response) for GetPeer messages in seconds | | `internal_rtt.getsync` | f64 | The average internal RTT for GetSync messages in seconds | | `internal_rtt.getblocks` | f64 | The average internal RTT for GetBlocks messages in seconds | | `internal_rtt.getmemorypool` | f64 | The average internal RTT for GetMemoryPool messages in seconds | | `misc.rpc_requests` | f64 | The number of RPC requests received by the node | | `outbound.all_successes` | u64 | The number of successfully sent messages | | `outbound.all_failures` | u64 | The number of failures to send messages | | `queues.consensus` | u64 | The number of queued consensus requests | | `queues.inbound` | u64 | The number of messages queued in the common inbound channel | | `queues.outbound` | u64 | The number of messages queued in the individual outbound channels | | `queues.peer_events` | u64 | The number of queued peer events | | `queues.storage` | u64 | The number of queued storage requests | | `queues.sync_items` | u64 | The number of queued sync items | ### Example ```ignore curl --data-binary '{"jsonrpc": "2.0", "id":"documentation", "method": "getnodestats", "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/ ``` ## connect Adds the given addresses to the node's list of peers and attempts to connect to them. ### Protected Endpoint Yes ### Arguments | Parameter | Type | Required | Description | |:-------------------:|:------:|:--------:|:------------------------------------------------ | | `addresses` | array | Yes | The addresses to connect to in an IP:port format | ### Response null ### Example ```ignore curl --user username:password --data-binary '{"jsonrpc": "2.0", "id":"1", "method": "connect", "params": ["127.0.0.1:4141", "127.0.0.1:4142"] }' -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 | | `view_key` | string | An Aleo account view 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 | |:--------------------:|:----------:|:--------:|:----------------------------------:| | `private_keys` | \[string\] | Yes | An array of private key strings | | `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": ["[private_key_0, private_key_1]", "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/ ``` ## disconnect Disconnects the node from the given address. ### Protected Endpoint Yes ### Arguments | Parameter | Type | Required | Description | |:-------------------:|:------:|:--------:|:---------------------------------------------- | | `address` | string | Yes | The address to disconnect in an IP:port format | ### Response null ### Example ```ignore curl --user username:password --data-binary '{"jsonrpc": "2.0", "id":"1", "method": "disconnect", "params": ["127.0.0.1:4141"] }' -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).