Head back to Documentation

Documentation

QRL Protocol Documentation

Top

qrl.proto

AddressAmount

Field Type Label Description
address bytes   QRL wallet address
amount uint64   QRL wallet amount

AddressList

Field Type Label Description
addresses bytes repeated  

AddressState

Field Type Label Description
address bytes   QRL wallet address
balance uint64   QRL wallet balance
nonce uint64   FIXME: Discuss. 32 or 64 bits?
ots_bitfield bytes repeated  
transaction_hashes bytes repeated Address transaction hashes
tokens AddressState.TokensEntry repeated Address tokens
latticePK_list LatticePK repeated Address Lattice PKs
slave_pks_access_type AddressState.SlavePksAccessTypeEntry repeated  
ots_counter uint64    

AddressState.SlavePksAccessTypeEntry

Field Type Label Description
key string    
value uint32    

AddressState.TokensEntry

Field Type Label Description
key string    
value uint64    

Block

Field Type Label Description
header BlockHeader   Block header
transactions Transaction repeated Block transactions list
genesis_balance GenesisBalance repeated This is only applicable to genesis blocks

BlockDataPoint

BlockDataPoint message definition

Field Type Label Description
number uint64   Block number
difficulty string   Difficulty at current block
timestamp uint64   Block timestamp in seconds
time_last uint64    
time_movavg uint64    
hash_power float   Hash power (hps)
header_hash bytes   Block header hash
header_hash_prev bytes   Previous block's header hash

BlockExtended

Field Type Label Description
header BlockHeader    
extended_transactions TransactionExtended repeated  
genesis_balance GenesisBalance repeated This is only applicable to genesis blocks
size uint64    

BlockHeader

Field Type Label Description
hash_header bytes   Block's header hash
block_number uint64   Block number
timestamp_seconds uint64   Block timestamp in seconds
hash_header_prev bytes   Previous block's header hash
reward_block uint64   Block's reward in Shor
reward_fee uint64   Block reward's fee in Shor
merkle_root bytes    
mining_nonce uint64    
extra_nonce uint64    

BlockHeaderExtended

Field Type Label Description
header BlockHeader    
transaction_count TransactionCount    

BlockHeightData

Field Type Label Description
block_number uint64    
block_headerhash bytes    
cumulative_difficulty bytes    

BlockMetaData

Field Type Label Description
is_orphan bool    
block_difficulty bytes    
cumulative_difficulty bytes    
child_headerhashes bytes repeated  
last_N_headerhashes bytes repeated Keeps last N headerhashes, for measurement of timestamp difference

BlockMetaDataList

Field Type Label Description
block_number_hashes BlockMetaData repeated  

BlockNumberMapping

Field Type Label Description
headerhash bytes    
prev_headerhash bytes    

CollectEphemeralMessageReq

Field Type Label Description
msg_id bytes    

CollectEphemeralMessageResp

Field Type Label Description
ephemeral_metadata EphemeralMetadata    

Empty

Empty message definition

EncryptedEphemeralMessage

Field Type Label Description
msg_id bytes   b'NEW' or PRF
ttl uint64   Expiry Timestamp in seconds
ttr uint64   Time to relay
channel EncryptedEphemeralMessage.Channel    
nonce uint64   nonce
payload bytes   JSON content, encrypted by aes256_symkey

EncryptedEphemeralMessage.Channel

Field Type Label Description
enc_aes256_symkey bytes   aes256_symkey encrypted by kyber

EphemeralChannelPayload

Field Type Label Description
prf512_seed bytes   PRF512 seed used for further communication after channel established
dilithium_signature bytes   Sign hash of (msg_id, ttl, enc_aes256_symkey, prf512_seed, addr_from,
addr_from bytes   data)
Sender address        
  data bytes   Could be anything, plain-text, binary, JSON etc.

EphemeralMessagePayload

Field Type Label Description
addr_from bytes   Sender address
data bytes   Could be anything, plain-text, binary, JSON etc.

EphemeralMetadata

Field Type Label Description
encrypted_ephemeral_message_list EncryptedEphemeralMessage repeated  

GenesisBalance

Field Type Label Description
address bytes   Address is string only here to increase visibility
balance uint64    

GetAddressFromPKReq

Field Type Label Description
pk bytes   XMSS Public key

GetAddressFromPKResp

Field Type Label Description
address bytes   QRL wallet address

GetAddressStateReq

Field Type Label Description
address bytes    

GetAddressStateResp

Field Type Label Description
state AddressState    

GetBlockReq

NOT USED -> RM?

Field Type Label Description
index uint64   Indicates the index number in mainchain
after_hash bytes   request the node that comes after hash

GetBlockResp

NOT USED -> RM?

Field Type Label Description
node_info NodeInfo   NodeInfo object containing node state information
block Block   Block of interest

GetKnownPeersReq

Represents a query to get known peers

GetKnownPeersResp

Represents the reply message to known peers query

Field Type Label Description
node_info NodeInfo   NodeInfo object containing node state information
known_peers Peer repeated List of Peer objects containing peer nodes detailed information

GetLatestDataReq

Field Type Label Description
filter GetLatestDataReq.Filter   Data filter one of (ALL, BLOCKHEADERS, TRANSACTIONS, TRANSACTIONS_UNCONFIRMED)
offset uint32   Offset in the result list (works backwards in this case)
quantity uint32   Number of items to retrive. Capped at 100

GetLatestDataResp

Field Type Label Description
blockheaders BlockHeaderExtended repeated  
transactions TransactionExtended repeated  
transactions_unconfirmed TransactionExtended repeated  

GetLocalAddressesReq

GetLocalAddressesResp

Field Type Label Description
addresses bytes repeated  

GetNodeStateReq

Represents a query to get node state

GetNodeStateResp

Represents the reply message to node state query

Field Type Label Description
info NodeInfo    

GetObjectReq

Field Type Label Description
query bytes    

GetObjectResp

Field Type Label Description
found bool    
address_state AddressState    
transaction TransactionExtended    
block_extended BlockExtended    

GetStatsReq

Represents a query to get statistics about node

Field Type Label Description
include_timeseries bool   Boolean to define if block timeseries should be included in reply or not

GetStatsResp

Represents the reply message to get statistics about node

Field Type Label Description
node_info NodeInfo   NodeInfo object containing node state information
epoch uint64   Current epoch
uptime_network uint64   Indicates uptime in seconds
block_last_reward uint64   Block reward in Shor
block_time_mean uint64   Blocktime average
block_time_sd uint64   Blocktime standard deviation
coins_total_supply uint64   Total coins supply
coins_emitted uint64   Total coins emitted
block_timeseries BlockDataPoint repeated Blocks time series of the recent blocks

LRUStateCache

LatticePK

Field Type Label Description
txhash bytes   Transaction hash
dilithium_pk bytes   Public Key generated from Dilithium
kyber_pk bytes   Public Key generated from Kyber

LatticePublicKeyTxnReq

Field Type Label Description
master_addr bytes   Transaction source address
kyber_pk bytes   Public key generated from Kyber
dilithium_pk bytes   Public key generated from Dilithium
fee uint64   Transaction fee in Shor
xmss_pk bytes   XMSS public key

LatticePublicKeys

Field Type Label Description
lattice_keys Transaction repeated  

NodeChainState

Field Type Label Description
block_number uint64    
header_hash bytes    
cumulative_difficulty bytes    
timestamp uint64    

NodeHeaderHash

Field Type Label Description
block_number uint64    
headerhashes bytes repeated  

NodeInfo

NodeInfo message definition

Field Type Label Description
version string   Node version
state NodeInfo.State   Node state (one of UNKNOWN, UNSYNCED, SYNCING, SYNCED, FORKED)
num_connections uint32    
num_known_peers uint32    
uptime uint64   Uptime in seconds
block_height uint64   Block height
block_last_hash bytes   Block's last hash
network_id string    

P2PAcknowledgement

Field Type Label Description
bytes_processed uint32    

Peer

Field Type Label Description
ip string    

PeerInfo

Field Type Label Description
peer_ip bytes    
port uint32    
banned_timestamp uint32    
credibility uint32    
last_connections_timestamp uint32 repeated  

Peers

Field Type Label Description
peer_info_list PeerInfo repeated  

PushEphemeralMessageReq

Field Type Label Description
ephemeral_message EncryptedEphemeralMessage    

PushTransactionReq

Field Type Label Description
transaction_signed Transaction    

PushTransactionResp

Field Type Label Description
error_code PushTransactionResp.ResponseCode   Resonse code, one of (UNKNOWN, ERROR, VALIDATION_FAILED, SUBMITTED)
error_description string   Detailed description of the error
tx_hash bytes   Transaction hash

SlaveTxnReq

Field Type Label Description
master_addr bytes   Transaction source address
slave_pks bytes repeated Slave nodes Public keys
access_types uint32 repeated Slave nodes access types
fee uint64   Transaction fee in Shor
xmss_pk bytes   XMSS public key

StateLoader

Field Type Label Description
addresses bytes repeated  
token_txhash bytes repeated  
txhash bytes repeated  
total_coin_supply uint64    

StateObjects

Field Type Label Description
state_loaders bytes repeated  

StoredPeers

Field Type Label Description
peers Peer repeated  

TokenDetailedList

Field Type Label Description
extended_tokens TransactionExtended repeated  

TokenList

Field Type Label Description
token_txhash bytes repeated  

TokenMetadata

Field Type Label Description
token_txhash bytes    
transfer_token_tx_hashes bytes repeated  

TokenTxnReq

Field Type Label Description
master_addr bytes   Transaction source address
symbol bytes   Token symbol
name bytes   Token name
owner bytes   Token owner
decimals uint64   Token decimals
initial_balances AddressAmount repeated  
fee uint64   Transaction fee
xmss_pk bytes   XMSS public key

Transaction

Field Type Label Description
master_addr bytes    
fee uint64   Transaction fee in Shor
public_key bytes    
signature bytes   Dilithium signature
nonce uint64   Transaction nonce
transaction_hash bytes   Transaction hash
transfer Transaction.Transfer    
coinbase Transaction.CoinBase    
latticePK Transaction.LatticePublicKey    
message Transaction.Message    
token Transaction.Token    
transfer_token Transaction.TransferToken    
slave Transaction.Slave    

Transaction.CoinBase

Field Type Label Description
addr_to bytes   Transaction destination address
amount uint64   Amount in Shor

Transaction.LatticePublicKey

Field Type Label Description
kyber_pk bytes   Public Key generated from Kyber
dilithium_pk bytes   Public Key generated from Dilithium

Transaction.Message

Field Type Label Description
message_hash bytes   Hash of message to be transfered

Transaction.Slave

Field Type Label Description
slave_pks bytes repeated Slave nodes public keys
access_types uint32 repeated Slave node access types

Transaction.Token

Field Type Label Description
symbol bytes   Token symbol
name bytes   Token name
owner bytes   Token owner wallet address
decimals uint64   Token decimals
initial_balances AddressAmount repeated  

Transaction.Transfer

Field Type Label Description
addrs_to bytes repeated Transaction destination address
amounts uint64 repeated Amount in Shor

Transaction.TransferToken

Field Type Label Description
token_txhash bytes   Token transaction hash
addrs_to bytes repeated Transaction destination address
amounts uint64 repeated Transaction amount

TransactionCount

Field Type Label Description
count TransactionCount.CountEntry repeated  

TransactionCount.CountEntry

Field Type Label Description
key uint32    
value uint32    

TransactionExtended

Field Type Label Description
header BlockHeader    
tx Transaction    
addr_from bytes    
size uint64    

TransferCoinsReq

Field Type Label Description
master_addr bytes   Transaction source address
addresses_to bytes repeated Transaction destination address
amounts uint64 repeated Amount in Shor
fee uint64   Transaction fee in Shor
xmss_pk bytes   XMSS Public key

TransferCoinsResp

Field Type Label Description
extended_transaction_unsigned TransactionExtended    

TransferTokenTxnReq

Field Type Label Description
master_addr bytes   Transaction source address
addresses_to bytes repeated Transaction destination address
token_txhash bytes   Transaction hash
amounts uint64 repeated Amount in Shor
fee uint64   Transaction fee in Shor
xmss_pk bytes   XMSS public key

GetLatestDataReq.Filter

Name Number Description
ALL 0  
BLOCKHEADERS 1  
TRANSACTIONS 2  
TRANSACTIONS_UNCONFIRMED 3  

NodeInfo.State

Node state

Name Number Description
UNKNOWN 0  
UNSYNCED 1  
SYNCING 2  
SYNCED 3  
FORKED 4  

PushTransactionResp.ResponseCode

Name Number Description
UNKNOWN 0  
ERROR 1  
VALIDATION_FAILED 2  
SUBMITTED 3  

AdminAPI

This is a place holder for testing/instrumentation APIs

| Method Name | Request Type | Response Type | Description | | ———– | ———— | ————- | ————|

PublicAPI

This service describes the Public API used by clients (wallet/cli/etc)

Method Name Request Type Response Type Description
GetNodeState GetNodeStateReq GetNodeStateResp  
GetKnownPeers GetKnownPeersReq GetKnownPeersResp  
GetStats GetStatsReq GetStatsResp  
GetAddressState GetAddressStateReq GetAddressStateResp  
GetObject GetObjectReq GetObjectResp  
GetLatestData GetLatestDataReq GetLatestDataResp  
TransferCoins TransferCoinsReq TransferCoinsResp  
PushTransaction PushTransactionReq PushTransactionResp  
GetTokenTxn TokenTxnReq TransferCoinsResp  
GetTransferTokenTxn TransferTokenTxnReq TransferCoinsResp  
GetSlaveTxn SlaveTxnReq TransferCoinsResp  
GetLatticePublicKeyTxn LatticePublicKeyTxnReq TransferCoinsResp  
GetAddressFromPK GetAddressFromPKReq GetAddressFromPKResp  
PushEphemeralMessage PushEphemeralMessageReq PushTransactionResp ——- Ephemeral API ——-
CollectEphemeralMessage CollectEphemeralMessageReq CollectEphemeralMessageResp ——————————
GetTokenDetailedList Empty TokenDetailedList  

Top

qrlbase.proto

GetNodeInfoReq

GetNodeInfoResp

Field Type Label Description
version string    
grpcProto string    

Base

Method Name Request Type Response Type Description
GetNodeInfo GetNodeInfoReq GetNodeInfoResp  

Top

qrllegacy.proto

BKData

Field Type Label Description
mrData MRData    
block Block    

FBData

Field Type Label Description
index uint64    

LegacyMessage

Adding old code to refactor while keeping things working

Field Type Label Description
func_name LegacyMessage.FuncName    
noData NoData    
veData VEData    
plData PLData    
pongData PONGData    
mrData MRData    
block Block    
fbData FBData    
pbData PBData    
bhData BlockHeightData    
stData Transaction    
dstData Transaction    
dtData Transaction    
txData Transaction    
vtData Transaction    
mtData Transaction    
tkData Transaction    
ttData Transaction    
ltData Transaction    
slData Transaction    
ephData EncryptedEphemeralMessage    
syncData SYNCData    
chainStateData NodeChainState    
nodeHeaderHash NodeHeaderHash    
p2pAckData P2PAcknowledgement    

MRData

Field Type Label Description
hash bytes   FIXME: rename this to block_headerhash
type LegacyMessage.FuncName   FIXME: type/string what is this
stake_selector bytes    
block_number uint64    
prev_headerhash bytes    
reveal_hash bytes    

NoData

PBData

Field Type Label Description
block Block    

PLData

Field Type Label Description
peer_ips string repeated  

PONGData

SYNCData

Field Type Label Description
state string    

VEData

Field Type Label Description
version string    
genesis_prev_hash bytes    
rate_limit uint64    

LegacyMessage.FuncName

Name Number Description
VE 0 Version
PL 1 Peers List
PONG 2 Pong TODO: Obsolete
MR 3 Message received
SFM 4 Send Full Message
BK 5 Block
FB 6 Fetch request for block
PB 7 Push Block
BH 8 Block Height
ST 9 Stake Transaction
DST 10 Destake Transaction
DT 11 Duplicate Transaction
TX 12 Transfer Transaction
VT 13 Vote
LT 14 Lattice Transaction
EPH 15 Ephemeral
MT 16 Message Transaction
TK 17 Token Transaction
TT 18 Transfer Token Transaction
SL 19 Slave Transaction
SYNC 20 Add into synced list, if the node replies
CHAINSTATE 21 Chain State
HEADERHASHES 22  
P2P_ACK 23 P2P Acknowledgement

Top

qrlmining.proto

GetBlockMiningCompatibleReq

Field Type Label Description
height uint64   Used for getlastblockheader and getblockheaderbyheight
if height = 0, this means getlastblockheader

GetBlockMiningCompatibleResp

Field Type Label Description
blockheader BlockHeader    
blockmetadata BlockMetaData    

GetBlockToMineReq

Field Type Label Description
wallet_address bytes    

GetBlockToMineResp

Field Type Label Description
blocktemplate_blob string   max length 112 bytes, otherwise xmr-stak will hiccup
difficulty uint64   difficulty that the new block should meet
height uint64    
reserved_offset uint32    

GetLastBlockHeaderReq

Field Type Label Description
height uint64    

GetLastBlockHeaderResp

Field Type Label Description
difficulty uint64    
height uint64    
timestamp uint64    
reward uint64    
hash string    
depth uint64    

SubmitMinedBlockReq

Field Type Label Description
blob bytes   blocktemplate_blob with the correct nonce

SubmitMinedBlockResp

Field Type Label Description
error bool   It seems there are no special fields for success/error reporting, does gRPC automatically give me something?

MiningAPI

Method Name Request Type Response Type Description
GetBlockMiningCompatible GetBlockMiningCompatibleReq GetBlockMiningCompatibleResp  
GetLastBlockHeader GetLastBlockHeaderReq GetLastBlockHeaderResp  
GetBlockToMine GetBlockToMineReq GetBlockToMineResp  
SubmitMinedBlock SubmitMinedBlockReq SubmitMinedBlockResp  

Scalar Value Types

.proto Type Notes C++ Type Java Type Python Type
double   double double float
float   float float float
int32 Uses variable-length encoding. Inefficient for encoding negative numbers – if your field is likely to have negative values, use sint32 instead. int32 int int
int64 Uses variable-length encoding. Inefficient for encoding negative numbers – if your field is likely to have negative values, use sint64 instead. int64 long int/long
uint32 Uses variable-length encoding. uint32 int int/long
uint64 Uses variable-length encoding. uint64 long int/long
sint32 Uses variable-length encoding. Signed int value. These more efficiently encode negative numbers than regular int32s. int32 int int
sint64 Uses variable-length encoding. Signed int value. These more efficiently encode negative numbers than regular int64s. int64 long int/long
fixed32 Always four bytes. More efficient than uint32 if values are often greater than 2^28. uint32 int int
fixed64 Always eight bytes. More efficient than uint64 if values are often greater than 2^56. uint64 long int/long
sfixed32 Always four bytes. int32 int int
sfixed64 Always eight bytes. int64 long int/long
bool   bool boolean boolean
string A string must always contain UTF-8 encoded or 7-bit ASCII text. string String str/unicode
bytes May contain any arbitrary sequence of bytes. string ByteString str

Still stuck? There's help over on Discord!