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	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/

getnodeinfo

Returns information about the node.

Arguments

None

Response

Parameter	Type	Description
is_bootnode	bool	Flag indicating if the node is a bootnode
is_miner	bool	Flag indicating if the node is a miner
is_syncing	bool	Flag indicating if the node currently syncing
launched	DateTime	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

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.connected_peers	u16	The number of currently connected peers
connections.connecting_peers	u16	The number of currently connecting peers
connections.disconnected_peers	u16	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
misc.block_height	u32	The current block height of the node
misc.blocks_mined	u32	The number of blocks the node has mined
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.inbound	u32	The number of messages queued in the common inbound channel
queues.outbound	u32	The number of messages queued in the individual outbound channels

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/

createaccount

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

Protected Endpoint

Yes

Arguments

None

Response

Parameter	Type	Description
private_key	string	An Aleo account private key
address	string	An Aleo account address

Example

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
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": ["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.