Head back to Documentation

Documentation

QRL Protocol Documentation

Table of Contents

Top

Addresses

AddressList

Field Type Label Description
addresses bytes repeated  

AddressState

Field Type Label Description
address bytes    
balance uint64    
nonce uint64   FIXME: Discuss. 32 or 64 bits?
pubhashes bytes repeated  
transaction_hashes bytes repeated  

Blocks

Block

Field Type Label Description
header BlockHeader    
transactions Transaction repeated  
dup_transactions Transaction repeated TODO: Review this
vote Transaction repeated  
genesis_balance GenesisBalance repeated This is only applicable to genesis blocks

BlockExtended

Field Type Label Description
block Block    
voted_weight uint64    
total_stake_weight uint64    

BlockHeader

Field Type Label Description
block_number uint64   Header
epoch uint64    
timestamp Timestamp   FIXME: Temporary
hash_header bytes    
hash_header_prev bytes    
reward_block uint64    
reward_fee uint64    
merkle_root bytes    
hash_reveal bytes    
stake_selector bytes    

BlockHeaderExtended

Field Type Label Description
header BlockHeader    
transaction_count TransactionCount    
voted_weight uint64    
total_stake_weight uint64    

BlockMetaData

Field Type Label Description
block_number uint64    
hash_header bytes    

BlockMetaDataList

Field Type Label Description
block_number_hashes BlockMetaData repeated  

Ephemeral Messaging

EphemeralMessage

Field Type Label Description
id bytes    
ttl uint64    
data bytes   Encrypted String containing aes256_symkey, prf512_seed, xmss_address, signature

EphemeralMessage.Data

Field Type Label Description
aes256_symkey bytes    
prf512_seed bytes    
xmss_address bytes    
xmss_signature bytes    

Genesis

GenesisBalance

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

Get

GetAddressStateReq

Field Type Label Description
address bytes    

GetAddressStateResp

Field Type Label Description
state AddressState    

GetBlockReq

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

GetBlockResp

Field Type Label Description
node_info NodeInfo    
block Block    

GetKnownPeersReq

GetKnownPeersResp

Field Type Label Description
node_info NodeInfo    
known_peers Peer repeated  

GetLatestDataReq

Field Type Label Description
filter GetLatestDataReq.Filter    
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

GetNodeStateResp

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 Block    

GetStakersReq

Field Type Label Description
filter GetStakersReq.Filter   Indicates which group of stakers (current / next)
offset uint32   Offset in the staker list
quantity uint32   Number of stakers to retrive. Capped at 100

GetStakersResp

Field Type Label Description
stakers StakerData repeated  

GetStatsReq

GetStatsResp

Field Type Label Description
node_info NodeInfo    
epoch uint64   Current epoch
uptime_network uint64   Indicates uptime in seconds
stakers_count uint64   Number of active stakers
block_last_reward uint64    
block_time_mean uint64    
block_time_sd uint64    
coins_total_supply uint64    
coins_emitted uint64    
coins_atstake uint64    

GetWalletReq

Field Type Label Description
address bytes    

GetWalletResp

Field Type Label Description
wallet Wallet   FIXME: Encrypt

Lattice Public Key

LatticePublicKeyTxnReq

Field Type Label Description
address_from bytes    
kyber_pk bytes    
dilithium_pk bytes    
xmss_pk bytes    
xmss_ots_index uint64    

MR

FIXME: This is legacy. Plan removal

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

MsgObject

Field Type Label Description
ephemeral EphemeralMessage   Overlapping - objects used for 2-way exchanges P2PRequest request = 1; P2PResponse response = 2;

NodeInfo

Field Type Label Description
version string    
state NodeInfo.State    
num_connections uint32    
num_known_peers uint32    
uptime uint64   Uptime in seconds
block_height uint64    
block_last_hash bytes    
stake_enabled bool    
network_id string    

Peer

Field Type Label Description
ip string    

PingReq

PongResp

PushTransactionReq

Field Type Label Description
transaction_signed Transaction    

PushTransactionResp

Field Type Label Description
some_response string    

Stake

StakeValidator

Field Type Label Description
address bytes    
slave_public_key bytes    
terminator_hash bytes    
balance uint64    
activation_blocknumber uint64    
nonce uint64    
is_banned bool    
is_active bool    

StakeValidatorsList

Field Type Label Description
stake_validators StakeValidator repeated  

StakeValidatorsTracker

Field Type Label Description
sv_dict StakeValidatorsTracker.SvDictEntry repeated  
future_stake_addresses StakeValidatorsTracker.FutureStakeAddressesEntry repeated  
expiry StakeValidatorsTracker.ExpiryEntry repeated  
future_sv_dict StakeValidatorsTracker.FutureSvDictEntry repeated  
total_stake_amount uint64    

StakeValidatorsTracker.ExpiryEntry

Field Type Label Description
key uint64    
value AddressList    

StakeValidatorsTracker.FutureStakeAddressesEntry

Field Type Label Description
key string    
value StakeValidator    

StakeValidatorsTracker.FutureSvDictEntry

Field Type Label Description
key uint64    
value StakeValidatorsList    

StakeValidatorsTracker.SvDictEntry

Field Type Label Description
key string    
value StakeValidator    

StakerData

Field Type Label Description
address_state AddressState    
terminator_hash bytes    

StoredPeers

Field Type Label Description
peers Peer repeated  

Timestamp

TODO: Avoid using timestamp until the github issue is fixed import "google/protobuf/timestamp.proto";

Field Type Label Description
seconds int64    
nanos int32    

Transaction

Transaction

Field Type Label Description
type Transaction.Type    
nonce uint64    
addr_from bytes    
public_key bytes    
transaction_hash bytes    
ots_key uint32    
signature bytes    
transfer Transaction.Transfer    
stake Transaction.Stake    
coinbase Transaction.CoinBase    
latticePK Transaction.LatticePublicKey    
duplicate Transaction.Duplicate    
vote Transaction.Vote    

Transaction.CoinBase

Field Type Label Description
addr_to bytes    
amount uint64    

Transaction.Destake

Transaction.Duplicate

Field Type Label Description
block_number uint64    
prev_header_hash uint64    
coinbase1_hhash bytes    
coinbase2_hhash bytes    
coinbase1 Transaction    
coinbase2 Transaction    

Transaction.LatticePublicKey

Field Type Label Description
kyber_pk bytes    
dilithium_pk bytes    

Transaction.Stake

Field Type Label Description
activation_blocknumber uint64    
slavePK bytes    
hash bytes    

Transaction.Transfer

Field Type Label Description
addr_to bytes    
amount uint64    
fee uint64    

Transaction.Vote

Field Type Label Description
block_number uint64    
hash_header bytes    

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    

Transfer

TransferCoinsReq

Field Type Label Description
address_from bytes   Transaction source address
address_to bytes   Transaction destination address
amount uint64   Amount. It should be expressed in Shor
fee uint64   Fee. It should be expressed in Shor
xmss_pk bytes   XMSS Public key
xmss_ots_index uint64   XMSS One time signature index

TransferCoinsResp

Field Type Label Description
transaction_unsigned Transaction    

Wallet

Wallet

Field Type Label Description
address string   FIXME move to bytes
mnemonic string    
xmss_index int32    

WalletStore

Field Type Label Description
wallets Wallet repeated  

GetLatestDataReq.Filter

Name Number Description
ALL 0  
BLOCKHEADERS 1  
TRANSACTIONS 2  
TRANSACTIONS_UNCONFIRMED 3  

GetStakersReq.Filter

Name Number Description
CURRENT 0  
NEXT 1  

NodeInfo.State

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

Transaction.Type

Name Number Description
UNKNOWN 0  
TRANSFER 1  
STAKE 2  
DESTAKE 3  
COINBASE 4  
LATTICE 5  
DUPLICATE 6  
VOTE 7  

AdminAPI

This is a place holder for testing/instrumentation APIs

Method Name Request Type Response Type Description
GetLocalAddresses GetLocalAddressesReq GetLocalAddressesResp FIXME: Use TLS and some signature scheme to validate the cli? At the moment, it will run locally

P2PAPI

This service describes the P2P API

Method Name Request Type Response Type Description
GetNodeState GetNodeStateReq GetNodeStateResp  
GetKnownPeers GetKnownPeersReq GetKnownPeersResp  
GetBlock GetBlockReq GetBlockResp rpc PublishBlock(PublishBlockReq) returns (PublishBlockResp);
ObjectExchange MsgObject MsgObject A bidirectional streaming channel is used to avoid any firewalling/NAT issues.

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  
GetStakers GetStakersReq GetStakersResp  
TransferCoins TransferCoinsReq TransferCoinsResp  
PushTransaction PushTransactionReq PushTransactionResp  
GetLatticePublicKeyTxn LatticePublicKeyTxnReq TransferCoinsResp  

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    
pongData PONGData    
mrData MRData    
sfmData MRData    
bkData BKData    
fbData FBData    
pbData PBData    
pbbData PBData    
syncData SYNCData    

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
index uint64    
block Block    

PLData

Field Type Label Description
peer_ips string repeated  

PONGData

SYNCData

VEData

Field Type Label Description
version string    
genesis_prev_hash bytes    

LegacyMessage.FuncName

Name Number Description
VE 0 Version
PL 1 Peers List
PONG 2 Pong
MR 3 Message received
SFM 4 Send Full Message
BK 5 Block
FB 6 Fetch request for block
PB 7 Push Block
PBB 8 Push Block Buffer
ST 9 Stake Transaction
DST 10 Destake Transaction
DT 11 Duplicate Transaction
TX 12 Transfer Transaction
VT 13 Vote
SYNC 14 Add into synced list, if the node replies

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!