README.md

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
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.block_height	u32	The current block height of the node
misc.blocks_mined	u32	The number of blocks the node has mined
misc.block_processing_time	f64	The block processing time in seconds
misc.duplicate_blocks	u64	The number of duplicate blocks received
misc.duplicate_sync_blocks	u64	The number of duplicate sync blocks received
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.