Protocol Documentation

Table of Contents

qrl.proto

Top

AddressList

FieldTypeLabelDescription
addresses bytes repeated

AddressState

FieldTypeLabelDescription
address bytes

balance uint64

nonce uint64

FIXME: Discuss. 32 or 64 bits?

pubhashes bytes repeated

transaction_hashes bytes repeated

Block

FieldTypeLabelDescription
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

FieldTypeLabelDescription
block Block

voted_weight uint64

total_stake_weight uint64

BlockHeader

FieldTypeLabelDescription
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

FieldTypeLabelDescription
header BlockHeader

transaction_count TransactionCount

voted_weight uint64

total_stake_weight uint64

BlockMetaData

FieldTypeLabelDescription
block_number uint64

hash_header bytes

BlockMetaDataList

FieldTypeLabelDescription
block_number_hashes BlockMetaData repeated

EphemeralMessage

<<<<<<< master =======
FieldTypeLabelDescription
id bytes

ttl uint64

EphemeralMessage.Data

>>>>>>> Adding objectexchage streaming channel
FieldTypeLabelDescription
aes256_symkey bytes

data bytes

Encrypted String containing aes256_symkey, prf512_seed, xmss_address, signature

GenesisBalance

FieldTypeLabelDescription
address string

Address is string only here to increase visibility

balance uint64

GetAddressStateReq

FieldTypeLabelDescription
address bytes

GetAddressStateResp

FieldTypeLabelDescription
state AddressState

GetBlockReq

FieldTypeLabelDescription
index uint64

Indicates the index number in mainchain

after_hash bytes

request the node that comes after hash

GetBlockResp

FieldTypeLabelDescription
node_info NodeInfo

block Block

GetKnownPeersReq

GetKnownPeersResp

FieldTypeLabelDescription
node_info NodeInfo

known_peers Peer repeated

GetLatestDataReq

FieldTypeLabelDescription
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

FieldTypeLabelDescription
blockheaders BlockHeaderExtended repeated

transactions TransactionExtended repeated

transactions_unconfirmed TransactionExtended repeated

GetLocalAddressesReq

GetLocalAddressesResp

FieldTypeLabelDescription
addresses bytes repeated

GetNodeStateReq

GetNodeStateResp

FieldTypeLabelDescription
info NodeInfo

GetObjectReq

FieldTypeLabelDescription
query bytes

GetObjectResp

FieldTypeLabelDescription
found bool

address_state AddressState

transaction TransactionExtended

block Block

GetStakersReq

FieldTypeLabelDescription
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

FieldTypeLabelDescription
stakers StakerData repeated

GetStatsReq

GetStatsResp

FieldTypeLabelDescription
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

FieldTypeLabelDescription
address bytes

GetWalletResp

FieldTypeLabelDescription
wallet Wallet

FIXME: Encrypt

LatticePublicKeyTxnReq

FieldTypeLabelDescription
address_from bytes

kyber_pk bytes

dilithium_pk bytes

xmss_pk bytes

xmss_ots_index uint64

MR

FIXME: This is legacy. Plan removal

FieldTypeLabelDescription
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

FieldTypeLabelDescription
ephemeral EphemeralMessage

Overlapping - objects used for 2-way exchanges P2PRequest request = 1; P2PResponse response = 2;

NodeInfo

FieldTypeLabelDescription
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

FieldTypeLabelDescription
ip string

PingReq

PongResp

PushTransactionReq

FieldTypeLabelDescription
transaction_signed Transaction

PushTransactionResp

FieldTypeLabelDescription
some_response string

StakeValidator

FieldTypeLabelDescription
address bytes

slave_public_key bytes

terminator_hash bytes

balance uint64

activation_blocknumber uint64

nonce uint64

is_banned bool

is_active bool

StakeValidatorsList

FieldTypeLabelDescription
stake_validators StakeValidator repeated

StakeValidatorsTracker

FieldTypeLabelDescription
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

FieldTypeLabelDescription
key uint64

value AddressList

StakeValidatorsTracker.FutureStakeAddressesEntry

FieldTypeLabelDescription
key string

value StakeValidator

StakeValidatorsTracker.FutureSvDictEntry

FieldTypeLabelDescription
key uint64

value StakeValidatorsList

StakeValidatorsTracker.SvDictEntry

FieldTypeLabelDescription
key string

value StakeValidator

StakerData

FieldTypeLabelDescription
address_state AddressState

terminator_hash bytes

StoredPeers

FieldTypeLabelDescription
peers Peer repeated

Timestamp

TODO: Avoid using timestamp until the github issue is fixed

import "google/protobuf/timestamp.proto";

FieldTypeLabelDescription
seconds int64

nanos int32

Transaction

FieldTypeLabelDescription
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

FieldTypeLabelDescription
addr_to bytes

amount uint64

Transaction.Destake

Transaction.Duplicate

FieldTypeLabelDescription
block_number uint64

prev_header_hash uint64

coinbase1_hhash bytes

coinbase2_hhash bytes

coinbase1 Transaction

coinbase2 Transaction

Transaction.LatticePublicKey

FieldTypeLabelDescription
kyber_pk bytes

dilithium_pk bytes

Transaction.Stake

FieldTypeLabelDescription
activation_blocknumber uint64

slavePK bytes

hash bytes

Transaction.Transfer

FieldTypeLabelDescription
addr_to bytes

amount uint64

fee uint64

Transaction.Vote

FieldTypeLabelDescription
block_number uint64

hash_header bytes

TransactionCount

FieldTypeLabelDescription
count TransactionCount.CountEntry repeated

TransactionCount.CountEntry

FieldTypeLabelDescription
key uint32

value uint32

TransactionExtended

FieldTypeLabelDescription
header BlockHeader

tx Transaction

TransferCoinsReq

FieldTypeLabelDescription
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

FieldTypeLabelDescription
transaction_unsigned Transaction

Wallet

FieldTypeLabelDescription
address string

FIXME move to bytes

mnemonic string

xmss_index int32

WalletStore

FieldTypeLabelDescription
wallets Wallet repeated

GetLatestDataReq.Filter

NameNumberDescription
ALL 0

BLOCKHEADERS 1

TRANSACTIONS 2

TRANSACTIONS_UNCONFIRMED 3

GetStakersReq.Filter

NameNumberDescription
CURRENT 0

NEXT 1

NodeInfo.State

NameNumberDescription
UNKNOWN 0

UNSYNCED 1

SYNCING 2

SYNCED 3

FORKED 4

Transaction.Type

NameNumberDescription
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 NameRequest TypeResponse TypeDescription
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 NameRequest TypeResponse TypeDescription
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 NameRequest TypeResponse TypeDescription
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

qrlbase.proto

Top

GetNodeInfoReq

GetNodeInfoResp

FieldTypeLabelDescription
version string

grpcProto string

Base

Method NameRequest TypeResponse TypeDescription
GetNodeInfo GetNodeInfoReq GetNodeInfoResp

qrllegacy.proto

Top

BKData

FieldTypeLabelDescription
mrData MRData

block Block

FBData

FieldTypeLabelDescription
index uint64

LegacyMessage

Adding old code to refactor while keeping things working

FieldTypeLabelDescription
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

FieldTypeLabelDescription
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

FieldTypeLabelDescription
index uint64

block Block

PLData

FieldTypeLabelDescription
peer_ips string repeated

PONGData

SYNCData

VEData

FieldTypeLabelDescription
version string

genesis_prev_hash bytes

LegacyMessage.FuncName

NameNumberDescription
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 TypeNotesC++ TypeJava TypePython 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