19 stable releases
1.3.17 | Oct 25, 2021 |
---|---|
1.3.14 | Aug 23, 2021 |
1.3.12 |
|
1.2.0 | Feb 28, 2021 |
1.1.4 | Aug 27, 2020 |
#37 in #json-rpc-server
22 downloads per month
2.5MB
13K
SLoC
snarkos-rpc
On Aleo, full nodes run a JSON-RPC server to enable API calls for fetching data and interacting with peers connected to the network.
RPC Port
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
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
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
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
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
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
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
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
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
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
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
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
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
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
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
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
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
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
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
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
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
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
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
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
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
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
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
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 and the configuration file.
Dependencies
~73MB
~870K SLoC