Skip to main content

QRL Public API

Introduction​

The QRL Public API allows developers to interact with the QRL blockchain network, perform transactions, and access blockchain data. Used to lookup information, send and process transactions, on the network and gather information on the node or network status.

While there is no authentication required to interact with most of the QRL's API's, you will need to be able to reach a node at the API service IP and port in order to interact with the QRL Blockchain. It is recommended that you run a local QRL node and serve the API from the local node. More information can be found to run your own QRL node here.

Prerequisites​

Before using the API, make sure you have the following prerequisites:

  • Connection to a synced QRL Node (remote or local)
  • Open API port (*Default enabled at port 19009)
  • Basic understanding of the QRL blockchain and gRPC

Base URL​

The base URL for accessing the QRL API running on a local node is: 127.0.0.1:19009. This address is configurable and may be different depending on your setup.

info

See the Node Configuration documentation for more information for setting port numbers for your QRL Node. Additional network settings and configuration may be needed to reach a node and is outside the scope of this document.

Protobuf Definition​

The API follows the protobuf definition found in qrl.proto.

Example Usage​

Here's an example of how to use the QRL API in different programming languages:

import grpc
from qrl.protos import qrl_pb2, qrl_pb2_grpc

# Establish a gRPC channel
channel = grpc.insecure_channel('127.0.0.1:19009')

# Create a stub for the QRL service
qrl_stub = qrl_pb2_grpc.QRLServiceStub(channel)

# Make a request to get block information
block_request = qrl_pb2.GetBlockInfoRequest(block_number=123456)
block_info = qrl_stub.GetBlockInfo(block_request)

# Print the block information
print(block_info)

Note: Make sure to import the appropriate Protobuf and gRPC client libraries in your code.

Please refer to the qrl.proto file for the complete API definition.

PublicAPIService​

The PublicAPIService service provides public API methods for interacting with the QRL node.

MethodRequestResponse
GetNodeStateGetNodeStateReqGetNodeStateResp
GetKnownPeersGetKnownPeersReqGetKnownPeersResp
GetPeersStatGetPeersStatReqGetPeersStatResp
GetStatsGetStatsReqGetStatsResp
GetAddressStateGetAddressStateReqGetAddressStateResp
GetOptimizedAddressStateGetAddressStateReqGetOptimizedAddressStateResp
GetMultiSigAddressStateGetMultiSigAddressStateReqGetMultiSigAddressStateResp
IsSlaveIsSlaveReqIsSlaveResp
GetObjectGetObjectReqGetObjectResp
GetLatestDataGetLatestDataReqGetLatestDataResp
PushTransactionPushTransactionReqPushTransactionResp
TransferCoinsTransferCoinsReqTransferCoinsResp
ParseAddressParseAddressReqParseAddressResp
GetChainStatsGetChainStatsReqGetChainStatsResp
GetAddressFromPKGetAddressFromPKReqGetAddressFromPKResp
GetMultiSigCreateTxnMultiSigCreateTxnReqTransferCoinsResp
GetMultiSigSpendTxnMultiSigSpendTxnReqTransferCoinsResp
GetMultiSigVoteTxnMultiSigVoteTxnReqTransferCoinsResp
GetMessageTxnMessageTxnReqTransferCoinsResp
GetTokenTxnTokenTxnReqTransferCoinsResp
GetTransferTokenTxnTransferTokenTxnReqTransferCoinsResp
GetSlaveTxnSlaveTxnReqTransferCoinsResp
GetLatticeTxnLatticeTxnReqTransferCoinsResp
GetTransactionGetTransactionReqGetTransactionResp
GetMiniTransactionsByAddressGetMiniTransactionsByAddressReqGetMiniTransactionsByAddressResp
GetTransactionsByAddressGetTransactionsByAddressReqGetTransactionsByAddressResp
GetTokensByAddressGetTransactionsByAddressReqGetTokensByAddressResp
GetSlavesByAddressGetTransactionsByAddressReqGetSlavesByAddressResp
GetLatticePKsByAddressGetTransactionsByAddressReqGetLatticePKsByAddressResp
GetMultiSigAddressesByAddressGetTransactionsByAddressReqGetMultiSigAddressesByAddressResp
GetMultiSigSpendTxsByAddressGetMultiSigSpendTxsByAddressReqGetMultiSigSpendTxsByAddressResp
GetVoteStatsGetVoteStatsReqGetVoteStatsResp
GetInboxMessagesByAddressGetTransactionsByAddressReqGetInboxMessagesByAddressResp
GetBalanceGetBalanceReqGetBalanceResp
GetTotalBalanceGetTotalBalanceReqGetTotalBalanceResp
GetOTSGetOTSReqGetOTSResp
GetHeightGetHeightReqGetHeightResp
GetBlockGetBlockReqGetBlockResp
GetBlockByNumberGetBlockByNumberReqGetBlockByNumberResp

GetNodeState​

Retrieves the current state of the QRL node queried.

GetNodeState​

service PublicAPI
{
    rpc GetNodeState (GetNodeStateReq) returns (GetNodeStateResp) {
      option (google.api.http) = {
        get: "/node-state"
      };
    };
}

GetKnownPeers​

Need clarification

Returns data on known peers connected to the node queried.

GetKnownPeers​

service PublicAPI
{
    rpc GetKnownPeers (GetKnownPeersReq) returns (GetKnownPeersResp) {
      option (google.api.http) = {
        get: "/known-peers"
      };
    };
}

GetPeersStat​

Returns stats on known peers.

GetPeersStat​

service PublicAPI
{
    rpc GetPeersStat (GetPeersStatReq) returns (GetPeersStatResp) {
      option (google.api.http) = {
        get: "/peers-stat"
      };
    };
}

GetStats​

Returns Node stats for the QRL Node queried with optional block timeseries data returned

GetStats​

service PublicAPI
{
    rpc GetStats (GetStatsReq) returns (GetStatsResp) {
      option (google.api.http) = {
        get: "/stats"
      };
    };
}

GetAddressState​

GetAddressState returns information on a given address.

This function requires a QRL address with optional fields to include OTS Bitfield and Transaction Hashes.

GetAddressState​

service PublicAPI
{
    rpc GetAddressState (GetAddressStateReq) returns (GetAddressStateResp) {
      option (google.api.http) = {
        get: "/address-state"
      };
    };
}

GetOptimizedAddressState​

Returns Optimized Address State information.

GetOptimizedAddressState​

service PublicAPI
{
    rpc GetOptimizedAddressState (GetAddressStateReq) returns (GetOptimizedAddressStateResp) {
      option (google.api.http) = {
        get: "/optimized-address-state"
      };
    };
}

GetMultiSigAddressState​

GetMultiSigAddressState​

service PublicAPI
{
    rpc GetMultiSigAddressState (GetMultiSigAddressStateReq) returns (GetMultiSigAddressStateResp) {
      option (google.api.http) = {
        get: "/multi-sig-address-state"
      };
    };
}

IsSlave​

IsSlave​

service PublicAPI
{
    rpc IsSlave (IsSlaveReq) returns (IsSlaveResp) {
      option (google.api.http) = {
        get: "/is-slave"
      };
    };
}

GetObject​

Returns information based on the query submitted. Can be one of: QRL Address, Transaction Hash, Block height.

GetObject​

service PublicAPI
{
    rpc GetObject(GetObjectReq) returns (GetObjectResp) {
      option (google.api.http) = {
        get: "/object"
      };
    };

}

GetLatestData​

GetLatestData​

service PublicAPI
{
    rpc GetLatestData(GetLatestDataReq) returns (GetLatestDataResp) {
      option (google.api.http) = {
        get: "/latest-data"
      };
    };
}

PushTransaction​

PushTransaction​

service PublicAPI
{
    rpc PushTransaction (PushTransactionReq) returns (PushTransactionResp) {
      option (google.api.http) = {
        post: "/push-transaction"
      };
    };
}

TransferCoins​

TransferCoins​

service PublicAPI
{
    rpc TransferCoins (TransferCoinsReq) returns (TransferCoinsResp) {
      option (google.api.http) = {
        post: "/transfer-coins"
      };
    };

}

ParseAddress​

ParseAddress returns a AddressDescriptor object containing information about the given QRL address, as well as verification that the address is valid.

ParseAddress​

service PublicAPI
{
    rpc ParseAddress (ParseAddressReq) returns (ParseAddressResp) {
      option (google.api.http) = {
        get: "/parse-address"
      };
    };
}

GetChainStats​

GetChainStats​

service PublicAPI
{
    rpc GetChainStats (GetChainStatsReq) returns (GetChainStatsResp) {
      option (google.api.http) = {
        get: "/chain-stats"
      };
    };
}

GetAddressFromPK​

Define this function

GetAddressFromPK​

service PublicAPI
{
    rpc GetAddressFromPK (GetAddressFromPKReq) returns (GetAddressFromPKResp) {
      option (google.api.http) = {
        get: "/address-from-pk"
      };
    };
}

GetMultiSigCreateTxn​

Create a Multisig address transaction

GetMultiSigCreateTxn​

service PublicAPI
{
    rpc GetMultiSigCreateTxn (MultiSigCreateTxnReq) returns (TransferCoinsResp) {
      option (google.api.http) = {
        post: "/multi-sig-create-txn"
      };
    };
}

GetMultiSigSpendTxn​

GetMultiSigSpendTxn​

service PublicAPI
{
    rpc GetMultiSigSpendTxn (MultiSigSpendTxnReq) returns (TransferCoinsResp) {
      option (google.api.http) = {
        post: "/multi-sig-spend-txn"
      };
    };
}

GetMultiSigVoteTxn​

Define this function and parameters

GetMultiSigVoteTxn​

service PublicAPI
{
    rpc GetMultiSigVoteTxn (MultiSigVoteTxnReq) returns (TransferCoinsResp) {
      option (google.api.http) = {
        post: "/multi-sig-vote-txn"
      };
    };
}

GetMessageTxn​

Define this function and parameters

GetMessageTxn​

service PublicAPI
{
    rpc GetMessageTxn (MessageTxnReq) returns (TransferCoinsResp) {
      option (google.api.http) = {
        post: "/message-txn"
      };
    };
}

GetTokenTxn​

Creates a token on the QRL network

GetTokenTxn​

service PublicAPI
{
    rpc GetTokenTxn (TokenTxnReq) returns (TransferCoinsResp) {
      option (google.api.http) = {
        post: "/token-txn"
      };
    };
}

GetTransferTokenTxn​

Define this function and parameters

GetTransferTokenTxn​

service PublicAPI
{
    rpc GetTransferTokenTxn (TransferTokenTxnReq) returns (TransferCoinsResp) {
      option (google.api.http) = {
        post: "/transfer-token-txn"
      };
    };
}

GetSlaveTxn​

Create slave addresses associated to a master address

GetSlaveTxn​

service PublicAPI
{
    rpc GetSlaveTxn (SlaveTxnReq) returns (TransferCoinsResp) {
      option (google.api.http) = {
        post: "/slave-txn"
      };
    };
}

GetLatticeTxn​

Generate a lattice transaction, sending Crystals public keys into chain

GetLatticeTxn​

service PublicAPI
{
    rpc GetLatticeTxn (LatticeTxnReq) returns (TransferCoinsResp) {
      option (google.api.http) = {
        post: "/lattice-txn"
      };
    };
}

GetTransaction​

Get transaction data from transaction hash provided

GetTransaction​

service PublicAPI
{
    rpc GetTransaction(GetTransactionReq) returns (GetTransactionResp) {
      option (google.api.http) = {
        get: "/transaction"
      };
    };
}

GetMiniTransactionsByAddress​

GetMiniTransactionsByAddress​

service PublicAPI
{
    rpc GetMiniTransactionsByAddress(GetMiniTransactionsByAddressReq) returns (GetMiniTransactionsByAddressResp) {
      option (google.api.http) = {
        get: "/mini-transaction-by-address"
      };
    };
}

GetTransactionsByAddress​

GetTransactionsByAddress​

service PublicAPI
{
    rpc GetTransactionsByAddress(GetTransactionsByAddressReq) returns (GetTransactionsByAddressResp) {
      option (google.api.http) = {
        get: "/transactions-by-address"
      };
    };
}

GetTokensByAddress​

GetTokensByAddress​

service PublicAPI
{
    rpc GetTokensByAddress(GetTransactionsByAddressReq) returns (GetTokensByAddressResp) {
      option (google.api.http) = {
        get: "/tokens-by-address"
      };
    };
}

GetSlavesByAddress​

GetSlavesByAddress​

service PublicAPI
{
    rpc GetSlavesByAddress(GetTransactionsByAddressReq) returns (GetSlavesByAddressResp) {
      option (google.api.http) = {
        get: "/slaves-by-address"
      };
    };
}

GetLatticePKsByAddress​

Returns any Lattice keys associated with the QRL address given.

GetLatticePKsByAddress​

service PublicAPI
{
    rpc GetLatticePKsByAddress(GetTransactionsByAddressReq) returns (GetLatticePKsByAddressResp) {
      option (google.api.http) = {
        get: "/lattice-pks-by-address"
      };
    };
}

GetMultiSigAddressesByAddress​

Lookup and return all multisig addresses associated with a QRL address

GetMultiSigAddressesByAddress​

service PublicAPI
{
    rpc GetMultiSigAddressesByAddress(GetTransactionsByAddressReq) returns (GetMultiSigAddressesByAddressResp) {
      option (google.api.http) = {
        get: "/multi-sig-addresses-by-address"
      };
    };
}

GetMultiSigSpendTxsByAddress​

Returns any multisig spend transactions associated with the address given.

GetMultiSigSpendTxsByAddress​

service PublicAPI
{
    rpc GetMultiSigSpendTxsByAddress(GetMultiSigSpendTxsByAddressReq) returns (GetMultiSigSpendTxsByAddressResp) {
      option (google.api.http) = {
        get: "/multi-sig-spend-txs-by-address"
      };
    };
}

GetVoteStats​

Returns multisig spend vote stats with a given multisig spend transaction hash

GetVoteStats​

service PublicAPI
{
    rpc GetVoteStats(GetVoteStatsReq) returns (GetVoteStatsResp) {
      option (google.api.http) = {
        get: "/vote-stats"
      };
    };

}

GetInboxMessagesByAddress​

GetInboxMessagesByAddress​

service PublicAPI
{
    rpc GetInboxMessagesByAddress(GetTransactionsByAddressReq) returns (GetInboxMessagesByAddressResp) {
      option (google.api.http) = {
        get: "/inbox-messages-by-address"
      };
    };
}

GetBalance​

Returns a given QRL address balance

GetBalance​

service PublicAPI
{
    rpc GetBalance(GetBalanceReq) returns (GetBalanceResp) {
      option (google.api.http) = {
        get: "/balance"
      };
    };
}

GetTotalBalance​

Returns total balance of all addresses given.

GetTotalBalance​

service PublicAPI
{
    rpc GetTotalBalance(GetTotalBalanceReq) returns (GetTotalBalanceResp) {
      option (google.api.http) = {
        get: "/total-balance"
      };
    };
}

GetOTS​

Need clarification

GetOTS​

service PublicAPI
{
    rpc GetOTS(GetOTSReq) returns (GetOTSResp) {
      option (google.api.http) = {
        get: "/ots"
      };
    };
}

GetHeight​

Need clarification

GetHeight​

service PublicAPI
{
    rpc GetHeight(GetHeightReq) returns (GetHeightResp) {
      option (google.api.http) = {
        get: "/height"
      };
    };
}

GetBlock​

Returns QRL block data from given block header hash

GetBlock​

service PublicAPI
{
    rpc GetBlock(GetBlockReq) returns (GetBlockResp) {
      option (google.api.http) = {
        get: "/block"
      };
    };
}

GetBlockByNumber​

Returns block data by given block number.

GetBlockByNumber​

service PublicAPI
{
    rpc GetBlockByNumber(GetBlockByNumberReq) returns (GetBlockByNumberResp) {
      option (google.api.http) = {
        get: "/block-by-number"
      };
    };
}

Content​

NodeInfo​

Node info returns the following:

FieldTypeDetails
versionstringThe version of the QRL node
stateStateOne of UNKNOWN, UNSYNCED, SYNCING, SYNCED, FORKED signifying the state of the node
num_connectionsuint32Number of connections seen to node
num_known_peersuint32Number of know peers seen by node
uptimeuint64The uptime of the node in seconds
block_heightuint64Blockheight currently known to node
block_last_hashbytesLast block hash;
network_idstringNetwork ID
message NodeInfo
{
    enum State {
        UNKNOWN = 0;
        UNSYNCED = 1;
        SYNCING = 2;
        SYNCED = 3;
        FORKED = 4;
    }

    string version = 1;
    State  state = 2;
    uint32 num_connections = 3;
    uint32 num_known_peers = 4;
    uint64 uptime = 5;               // Uptime in seconds
    uint64 block_height = 6;
    bytes  block_last_hash = 7;
    string network_id = 8;
}

AddressDescriptor​

NameBitsCountDescription
HF0 .. 34Hash Function
SIG4 .. 74Signature Scheme
P18 .. 114Parameters 1 (ie. height, etc.)
P212 .. 154Address Format
P316 .. 238Parameters 2

In the case of using XMSS, the parameters are used as follows:

NameBitsCountDescription
HF0 .. 34SHA2-256, SHAKE128, SHAKE256
SIG4 .. 74XMSS
P18 .. 114XMSS Height / 2
AF/ P2 12.. 15 4 Address Format
P316 .. 238Not used

// 3 byte scheme, 0-3 bits = hf, 4-7 = sig scheme, 8-11 = params (inc h), 12-15 addr fmt, 16-23 params2
message AddressDescriptor {
    string hash_function = 1;
    string signature_scheme = 2;
    uint32 tree_height = 3;
    uint32 signatures = 4;
    string address_format = 5;
}

StoredPeers​

FieldTypeDetails
peersrepeated Peer Object
Peer Object contains:
ip
message StoredPeers {
    repeated Peer peers = 1;
}

Peer​

FieldTypeDetails
ipstringReturns the public peer IP Address
message Peer {
    string ip = 1;
}

AddressState​

FieldTypeDetails
addressbytesPub Address in bytes
balanceuint64Address balance
nonceuint64Address Nonce
ots_bitfieldrepeated bytesOne Time Signature Bitfield
transaction_hashesrepeated bytesRepeated list of all transaction hashes
tokensmap<string, uint64>Map of tokens found in address
latticePK_listrepeated LatticePKRepeated list of lattice public keys
slave_pks_access_typemap<string, uint32>Map of slave key access type
ots_counteruint64Count of used OTS Keys
message AddressState {
    bytes address = 1;
    uint64 balance = 2;
    uint64 nonce = 3;                           
    repeated bytes ots_bitfield = 4;
    repeated bytes transaction_hashes = 5;
    map<string, uint64> tokens = 6;
    repeated LatticePK latticePK_list = 7;
    map<string, uint32> slave_pks_access_type = 8;
    uint64 ots_counter = 9;
}

OptimizedAddressState​

FieldTypeDetails
addressbytesPub Address in bytes
balanceuint64Address balance
nonceuint64Address Nonce
ots_bitfield_used_pageuint64Keep track of last page till which all ots key has been used
used_ots_key_countuint64Keep track of number of ots key that has been used
transaction_hash_countuint64
tokens_countuint64
slaves_countuint64
lattice_pk_countuint64
multi_sig_address_countuint64
multi_sig_spend_countuint64
inbox_message_countuint64
foundation_multi_sig_spend_txn_hashrepeated
foundation_multi_sig_vote_txn_hashrepeated
unvotesrepeated
proposal_vote_statsrepeated
message OptimizedAddressState {
    bytes address = 1;
    uint64 balance = 2;
    uint64 nonce = 3;
    uint64 ots_bitfield_used_page = 4;  // Keep track of last page till which all ots key has been used
    uint64 used_ots_key_count = 5;  // Keep track of number of ots key that has been used
    uint64 transaction_hash_count = 6;
    uint64 tokens_count = 7;
    uint64 slaves_count = 8;
    uint64 lattice_pk_count = 9;
    uint64 multi_sig_address_count = 10;
    uint64 multi_sig_spend_count = 11;
    uint64 inbox_message_count = 12;

    repeated bytes foundation_multi_sig_spend_txn_hash = 13;
    repeated bytes foundation_multi_sig_vote_txn_hash = 14;
    repeated bytes unvotes = 15;

    repeated Transaction proposal_vote_stats = 16;
}

MultiSigAddressState​

FieldTypeDetails
addressbbytesPub Address in bytes
creation_tx_hashbytes
nonceuint64
balanceuint64Address balance
signatoriesbytes
weightsuint32
thresholduint32
transaction_hash_countuint64
multi_sig_spend_countuint64
multi_sig_address_countuint64
foundation_multi_sig_spend_txn_hashbytes
foundation_multi_sig_vote_txn_hashbytes
unvotesbytes
proposal_vote_statsTransaction ObjectReturns a transaction object with address state proposal vote stats
message MultiSigAddressState {
    bytes address = 1;
    bytes creation_tx_hash = 2;
    uint64 nonce = 3;
    uint64 balance = 4;
    repeated bytes signatories = 5;
    repeated uint32 weights = 6;
    uint32 threshold = 7;
    uint64 transaction_hash_count = 8;
    uint64 multi_sig_spend_count = 9;
    // TODO: To be implemented
    uint64 multi_sig_address_count = 10;

    repeated bytes foundation_multi_sig_spend_txn_hash = 11;
    repeated bytes foundation_multi_sig_vote_txn_hash = 12;
    repeated bytes unvotes = 13;

    repeated Transaction proposal_vote_stats = 14;
}

MultiSigAddressesList​

FieldTypeDetails
hashesrepeated bytes
message MultiSigAddressesList {
    repeated bytes hashes = 1;
}

DataList​

FieldTypeDetails
valuesrepeated bytes
message DataList {
    repeated bytes values = 1;
}

Bitfield​

FieldTypeDetails
bitfieldsrepeated bytes
message Bitfield {
    repeated bytes bitfields = 1;
}

TransactionHashList​

FieldTypeDetails
hashesrepeated bytes
message TransactionHashList {
    repeated bytes hashes = 1;
}

LatticePK​

FieldTypeDetails
kyber_pkbytes
dilithium_pkbytes
message LatticePK {
    bytes kyber_pk = 1;
    bytes dilithium_pk = 2;
}

AddressAmount​

FieldTypeDetails
addressbytes
amountuint64
message AddressAmount {
    bytes address = 1;
    uint64 amount = 2;
}

BlockHeader​

FieldTypeDetails
hash_headerbytes
block_numberuint64
timestamp_secondsuint64
hash_header_prevbytes
reward_blockuint64
reward_feeuint64
merkle_rootbytes
mining_nonceuint32
extra_nonceuint64
message BlockHeader {
    // Header
    bytes hash_header = 1;

    uint64 block_number = 2;
    uint64 timestamp_seconds = 3;
    bytes hash_header_prev = 4;
    uint64 reward_block = 5;
    uint64 reward_fee = 6;
    bytes merkle_root = 7;

    uint32 mining_nonce = 8;
    uint64 extra_nonce = 9;
}

BlockHeaderExtended​

FieldTypeDetails
headerBlockHeader Object
transaction_countTransactionCount Object
message BlockHeaderExtended {
    BlockHeader header = 1;
    TransactionCount transaction_count = 2;
}

TransactionCount​

FieldTypeDetails
countmap<uint32, uint32>
message TransactionCount {
    map<uint32, uint32> count = 1;
}

TransactionExtended​

FieldTypeDetails
headerBlockHeader Object
txTransaction Object
addr_frombytes
sizeuint64
timestamp_secondsuint64
message TransactionExtended {
    BlockHeader header = 1;
    Transaction tx = 2;
    bytes addr_from = 3;
    uint64 size = 4;
    uint64 timestamp_seconds = 5;
}

BlockExtended​

FieldTypeDetails
headerBlockHeader Object
extended_transactionsrepeated TransactionExtended Object
*genesis_balancerepeated GenesisBalance ObjectThis is only applicable to genesis blocks
sizeuint64Block size
* Genesis_Balance

genesis_balance is only applicable to genesis blocks.

message BlockExtended {
    BlockHeader header = 1;
    repeated TransactionExtended extended_transactions = 2;

    // This is only applicable to genesis blocks
    repeated GenesisBalance genesis_balance = 3;
    uint64 size = 4;
}

Block​

FieldTypeDetails
headerBlockHeader Object
transactionsTransaction Object
*genesis_balancerepeated GenesisBalance ObjectThis is only applicable to genesis blocks
* Genesis_Balance

genesis_balance is only applicable to genesis blocks.

message Block {
    BlockHeader header = 1;
    repeated Transaction transactions = 2;

    // This is only applicable to genesis blocks
    repeated GenesisBalance genesis_balance = 3;
}

GenesisBalance​

FieldTypeDetails
addressbytesAddress is string only here to increase visibility
balanceuint64
message GenesisBalance
{
    bytes address = 1;                     // Address is string only here to increase visibility
    uint64 balance = 2;
}

BlockMetaDataList​

FieldTypeDetails
block_number_hashesrepeated BlockMetaData Object
BlockMetaData object contains:
block_difficulty
cumulative_difficulty
child_headerhashes
last_N_headerhashes
message BlockMetaDataList {
    repeated BlockMetaData block_number_hashes = 1;
}

Transaction​

FieldTypeDetails
master_addrbytes
feeuint64
public_keybytes
signaturebytes
nonceuint64
transaction_hashbytes
transactionTypeOne of:
transactionType:
transfer
coinbase
latticePK
message
token
transfer_token
slave
multi_sig_create
multi_sig_spend
multi_sig_vote
proposal_create
proposal_vote
message Transaction {
    bytes master_addr = 1;
    uint64 fee = 2;
    bytes public_key = 3;
    bytes signature = 4;
    uint64 nonce = 5;
    bytes transaction_hash = 6;

    oneof transactionType {
        Transfer transfer = 7;
        CoinBase coinbase = 8;
        LatticePublicKey latticePK = 9;
        Message message = 10;
        Token token = 11;
        TransferToken transfer_token = 12;
        Slave slave = 13;

        MultiSigCreate multi_sig_create = 14;
        MultiSigSpend multi_sig_spend = 15;
        MultiSigVote multi_sig_vote = 16;

        ProposalCreate proposal_create = 17;
        ProposalVote proposal_vote = 18;
    }

    message Transfer {
        repeated bytes addrs_to = 1;
        repeated uint64 amounts = 2;
        bytes message_data = 3;
    }

    message CoinBase {
        bytes addr_to = 1;
        uint64 amount = 2;
    }

    message LatticePublicKey {
        bytes pk1 = 1;  // kyber_pk
        bytes pk2 = 2;  // dilithium_pk
        bytes pk3 = 3;  // ecdsa_pk
    }

    message Message {
        bytes message_hash = 1;
        bytes addr_to = 2;
    }

    message Token {
        bytes symbol = 1;
        bytes name = 2;
        bytes owner = 3;
        uint64 decimals = 4;
        repeated AddressAmount initial_balances = 5;
    }

    message TransferToken {
        bytes token_txhash = 1;
        repeated bytes addrs_to = 2;
        repeated uint64 amounts = 3;
    }

    message Slave {
        repeated bytes slave_pks = 1;
        repeated uint32 access_types = 2;
    }

    message MultiSigCreate {
        repeated bytes signatories = 1;
        repeated uint32 weights = 2;
        uint32 threshold = 3;
    }

    message MultiSigSpend {
        bytes multi_sig_address = 1;
        repeated bytes addrs_to = 2;
        repeated uint64 amounts = 3;
        uint64 expiry_block_number = 4;
    }

    message MultiSigVote {
        bytes shared_key = 1;
        bool unvote = 2;

        bytes prev_tx_hash = 3;  // To be used internally by State
    }

    message ProposalCreate {
        uint64 expiry_block_number = 1;
        string description = 2;

        oneof proposalType {
            QIP qip = 3;
            Config config = 4;
            Other other = 5;
        }

        message QIP {
            string qip_link = 1;
        }

        message Config {
            repeated bytes changes_bitfield = 1;

            uint64 reorg_limit = 2;
            uint64 max_coin_supply = 3;
            uint64 complete_emission_time_span_in_years = 4;

            uint64 mining_nonce_offset = 5;
            uint64 extra_nonce_offset = 6;
            uint64 mining_blob_size_in_bytes = 7;
            uint64 block_timing_in_seconds = 8;

            uint64 number_of_blocks_analyze = 9;
            uint64 block_size_multiplier = 10;  // Support upto 2 decimal places
            uint64 block_min_size_limit_in_bytes = 11;

            uint64 transaction_multi_output_limit = 12;

            uint64 message_max_length = 13;

            uint64 token_symbol_max_length = 14;
            uint64 token_name_max_length = 15;

            uint64 lattice_pk1_max_length = 16;
            uint64 lattice_pk2_max_length = 17;
            uint64 lattice_pk3_max_length = 18;

            uint64 foundation_multi_sig_address_threshold_percentage = 19;

            uint64 proposal_threshold_per = 20;
            repeated string proposal_default_options = 21;
            uint64 description_max_length = 22;
            uint64 options_max_number = 23;
            uint64 option_max_text_length = 24;
            uint64 proposal_config_activation_delay = 25;

            uint64 N_measurement = 26;
            uint64 kp = 27;
        }

        message Other {
            repeated string options = 1;
        }
    }

    message ProposalVote {
        bytes shared_key = 1;
        uint32 option = 2;
    }
}

MiniTransaction​

FieldTypeDetails
transaction_hashstring
outbool
amountuint64
message MiniTransaction {
    string transaction_hash = 1;
    bool out = 2;
    uint64 amount = 3;
}

GetTransactionResp​

FieldTypeDetails
txTransaction
confirmationsuint64
block_numberuint64
block_header_hashbytes
timestampuint64
addr_frombytes
message GetTransactionResp {
    Transaction tx = 1;
    uint64 confirmations = 2;
    uint64 block_number = 3;
    bytes block_header_hash = 4;
    uint64 timestamp = 5;
    bytes addr_from = 6;
}

TokenDetail​

FieldTypeDetails
token_txhashbytes
namebytes
symbolbytes
balanceuint64
message TokenDetail {
    bytes token_txhash = 1;
    bytes name = 2;
    bytes symbol = 3;
    uint64 balance = 4;
}

SlaveDetail​

FieldTypeDetails
slave_addressbytes
access_typeuint64
message SlaveDetail {
    bytes slave_address = 1;
    uint64 access_type = 2;
}

LatticePKsDetail​

FieldTypeDetails
pk1bytes
pk2bytes
pk3bytes
tx_hashbytes
message LatticePKsDetail {
    bytes pk1 = 1;
    bytes pk2 = 2;
    bytes pk3 = 3;
    bytes tx_hash = 4;
}

MultiSigDetail​

FieldTypeDetails
addressbytes
balanceuint64
message MultiSigDetail {
    bytes address = 1;
    uint64 balance = 2;
}

VoteStats​

FieldTypeDetails
multi_sig_addressbytes
shared_keybytes
signatoriesrepeated bytes
tx_hashesrepeated bytes
unvotesrepeated bool
expiry_block_numberuint64
total_weightuint64
executedbool
message VoteStats {
    bytes multi_sig_address = 1;
    bytes shared_key = 2;
    repeated bytes signatories = 3;
    repeated bytes tx_hashes = 4;
    repeated bool unvotes = 5;
    uint64 expiry_block_number = 6;
    uint64 total_weight = 7;
    bool executed = 8;
}

ProposalVoteStats​

FieldTypeDetails
addr_frombytes
shared_keybytes
proposal_typestring
weight_by_optionrepeated uint64
expiry_block_numberuint64
executedbool
number_of_tx_hashesuint64Keep track of number of pages for vote txn hash
message ProposalVoteStats {
    bytes addr_from = 1;
    bytes shared_key = 2;
    string proposal_type = 3;
    repeated uint64 weight_by_option = 4;
    uint64 expiry_block_number = 5;
    bool executed = 6;

    uint64 number_of_tx_hashes = 7;  // Keep track of number of pages for vote txn hash
}

ProposalRecord​

FieldTypeDetails
number_of_tx_hashesuint64
message ProposalRecord {
    uint64 number_of_tx_hashes = 1;
}

TokenList​

FieldTypeDetails
token_txhashrepeated bytes
message TokenList {
    repeated bytes token_txhash = 1;
}

TokenBalance​

FieldTypeDetails
balanceuint64
decimalsuint64
tx_hashbytesTx hash responsible for the creation of this data
deleteboolFor internal use only
message TokenBalance {
    uint64 balance = 1;
    uint64 decimals = 2;
    bytes tx_hash = 3; // Tx hash responsible for the creation of this data
    bool delete = 4;  // For internal use only
}

OTSBitfieldByPage​

FieldTypeDetails
ots_bitfieldrepeated bytes
page_numberuint64
message OTSBitfieldByPage {
    repeated bytes ots_bitfield = 1;
    uint64 page_number = 2;
}

SlaveMetadata​

FieldTypeDetails
access_typeuint64
tx_hashbytes
deletebool
message SlaveMetadata {
    uint64 access_type = 1;
    bytes tx_hash = 2;
    bool delete = 3;
}

LatticePKMetadata​

FieldTypeDetails
enabledbool
tx_hashbytes
deletebool
message LatticePKMetadata {
    bool enabled = 1;
    bytes tx_hash = 2;
    bool delete = 3;
}

TokenMetadata​

FieldTypeDetails
token_txhashbytes
transfer_token_tx_hashesrepeated bytes
message TokenMetadata {
    bytes token_txhash = 1;
    repeated bytes transfer_token_tx_hashes = 2;
}

EncryptedEphemeralMessage​

FieldTypeDetails
msg_idbytesNEW or PRF
ttluint64Expiry Timestamp in seconds
ttruint64Time to relay
channelChannel Object
Channel object contains:
enc_aes256_symkey
nonceuint64nonce
payloadbytesJSON content, encrypted by aes256_symkey
message EncryptedEphemeralMessage {
    bytes msg_id = 1;                       // b'NEW' or PRF
    uint64 ttl = 2;                         // Expiry Timestamp in seconds
    uint64 ttr = 3;                         // Time to relay
    message Channel {
        bytes enc_aes256_symkey = 4;        // aes256_symkey encrypted by kyber
    }
    Channel channel = 5;
    uint64 nonce = 6;                       // nonce
    bytes payload = 7;                      // JSON content, encrypted by aes256_symkey
}

AddressList​

FieldTypeDetails
addressesrepeated bytes
message AddressList {
    repeated bytes addresses = 1;
}

BlockHeightData​

FieldTypeDetails
block_number
block_headerhash
cumulative_difficulty
message BlockHeightData {
    uint64 block_number = 1;
    bytes block_headerhash = 2;
    bytes cumulative_difficulty = 3;
}

BlockMetaData​

FieldTypeDetails
block_difficultybytes
cumulative_difficultybytes
child_headerhashesrepeated bytes
last_N_headerhashesrepeated bytesKeeps last N headerhashes, for measurement of timestamp difference
message BlockMetaData {
    bytes block_difficulty = 1;
    bytes cumulative_difficulty = 2;
    repeated bytes child_headerhashes = 3;
    repeated bytes last_N_headerhashes = 4;     // Keeps last N headerhashes, for measurement of timestamp difference
}

BlockNumberMapping​

FieldTypeDetails
headerhashbytes
prev_headerhashbytes
message BlockNumberMapping {
    bytes headerhash = 1;
    bytes prev_headerhash = 2;
}

PeerStat​

PeerStat returns stats on a peer.

FieldTypeDetails
peer_ipbytesPeer public IP address
portuint32peer p2p open port
node_chain_stateNodeChainState Object
NodeChainState object contains:
block_number
header_hash
cumulative_difficulty
version
timestamp
message PeerStat {
    bytes peer_ip = 1;
    uint32 port = 2;
    NodeChainState node_chain_state = 3;
}
note

See the NodeChainState object for more information

NodeChainState​

FieldTypeDetails
block_numberuint64
header_hashbytes
cumulative_difficultybytes
versionstring
timestampuint64
message NodeChainState {
    uint64 block_number = 1;
    bytes header_hash = 2;
    bytes cumulative_difficulty = 3;
    string version = 4;
    uint64 timestamp = 5;
}

NodeHeaderHash​

FieldTypeDetails
block_numberuint64
headerhashesrepeated bytes
message NodeHeaderHash {
    uint64 block_number = 1;
    repeated bytes headerhashes = 2;
}

P2PAcknowledgement​

FieldTypeDetails
bytes_processeduint32
message P2PAcknowledgement {
    uint32 bytes_processed = 1;
}

PeerInfo​

PeerInfo returns data on a peer.

FieldTypeDetails
peer_ipbytesPeer's public IP address
portuint32p2p open port of peer
banned_timestampuint32timestamp if peer has ban
credibilityuint32credibility rating
last_connections_timestamprepeated uint32last seen connection time
message PeerInfo {
    bytes peer_ip = 1;
    uint32 port = 2;
    uint32 banned_timestamp = 3;
    uint32 credibility = 4;
    repeated uint32 last_connections_timestamp = 5;
}

Peers​

Peers message returns all information from the PeerInfo message function.

FieldTypeDetails
peer_info_listrepeated PeerInfo Object
PeerInfo object contains:
peer_ip
port
banned_timestamp
credibility
last_connections_timestamp
message Peers {
    repeated PeerInfo peer_info_list = 1;
}

BlockDataPoint​

FieldTypeDetails
numberuint64Block number
difficultystringBlock difficulty
timestampuint64Block timestamp
time_lastuint64
time_movavguint64
hash_powerfloatHash power
header_hashbytesBlock header hash
header_hash_prevbytesPrevious block's header hash
/**
 * BlockDataPoint message definition
*/
message BlockDataPoint
{
    uint64 number = 1;                      // Block number
    string difficulty = 2;                  // Block difficulty
    uint64 timestamp = 3;                   // Block timestamp
    uint64 time_last = 4;
    uint64 time_movavg = 5;
    float hash_power = 6;                   // Hash power

    bytes header_hash = 7;                  // Block header hash
    bytes header_hash_prev = 8;             // Previous block's header hash
}

DevConfig​

FieldTypeDetails
prev_state_keybytes
current_state_keybytes
activation_header_hashbytes
activation_block_numberuint64
chainChain Object
Dev Chain object contains:
reorg_limit
max_coin_supply
complete_emission_time_span_in_years
blockBlock Object
Dev Block object contains:
mining_nonce_offset
extra_nonce_offset
mining_blob_size_in_bytes
block_timing_in_seconds
block_size_controller
number_of_blocks_analyze
size_multiplier
block_min_size_limit_in_bytes
transactionTransaction Object
Dev Transaction object contains:
multi_output_limit
message
max_length
slave
slave_pk_max_length
token
symbol_max_length
name_max_length
lattice
pk1_max_length
pk2_max_length
pk3_max_length
foundation_multi_sig
threshold_percentage
proposal
threshold_per
default_options
description_max_length
options_max_number
option_max_text_length
proposal_config_activation_delay
powPOW Object
POW object contains:
N_measurement
kp
message DevConfig {
    bytes prev_state_key = 1;
    bytes current_state_key = 2;
    bytes activation_header_hash = 3;
    uint64 activation_block_number = 4;

    Chain chain = 5;
    Block block = 6;
    Transaction transaction = 7;
    POW pow = 8;

    message Chain {
        uint64 reorg_limit = 1;
        uint64 max_coin_supply = 2;
        uint64 complete_emission_time_span_in_years = 3;
    }

    message Block {
        uint64 mining_nonce_offset = 1;
        uint64 extra_nonce_offset = 2;
        uint64 mining_blob_size_in_bytes = 3;
        uint64 block_timing_in_seconds = 4;
        BlockSizeController block_size_controller = 5;

        message BlockSizeController {
            uint64 number_of_blocks_analyze = 1;
            uint64 size_multiplier = 2;  // Support upto 2 decimal places
            uint64 block_min_size_limit_in_bytes = 3;
        }
    }

    message Transaction {
        uint64 multi_output_limit = 1;
        Message message = 2;
        Slave slave = 3;
        Token token = 4;
        Lattice lattice = 5;
        FoundationMultiSig foundation_multi_sig = 6;
        Proposal proposal = 7;

        message Message {
            uint64 max_length = 1;
        }

        message Slave {
            uint64 slave_pk_max_length = 2;
        }

        message Token {
            uint64 symbol_max_length = 1;
            uint64 name_max_length = 2;
        }

        message Lattice {
            uint64 pk1_max_length = 1;
            uint64 pk2_max_length = 2;
            uint64 pk3_max_length = 3;
        }

        message FoundationMultiSig {
            uint64 threshold_percentage = 1;  // Support upto 2 decimal places
        }

        message Proposal {
            uint64 threshold_per = 1;  // Support upto 2 decimal places
            repeated string default_options = 2;  // Convention: All strings must be in capital letters

            uint64 description_max_length = 3;
            uint64 options_max_number = 4;
            uint64 option_max_text_length = 5;
            uint64 proposal_config_activation_delay = 6;
        }
    }

    message POW {
        uint64 N_measurement = 1;
        uint64 kp = 2;
    }
}