19 stable releases

1.3.17 Oct 25, 2021
1.3.14 Aug 23, 2021
1.3.12 Jul 30, 2021
1.2.0 Feb 28, 2021
1.1.4 Aug 27, 2020

#37 in #json-rpc-server

22 downloads per month

GPL-3.0 license

2.5MB
13K SLoC

snarkos-rpc

Crates.io Authors License: GPL v3

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