# Protocol Documentation

## Table of Contents

## qrl.proto

Top

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

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

### EphemeralMessage

Field | Type | Label | Description
id | bytes |  |
ttl | uint64 |  |
<<<<<<< master =======

### EphemeralMessage.Data

Field | Type | Label | Description
aes256_symkey | bytes |  |
>>>>>>> Adding objectexchage streaming channel
data | bytes |  | Encrypted String containing aes256_symkey, prf512_seed, xmss_address, signature

### GenesisBalance

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

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

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

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

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

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

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 |

## qrlbase.proto

Top

### GetNodeInfoReq

### GetNodeInfoResp

Field | Type | Label | Description
version | string |  |
grpcProto | string |  |

### Base

Method Name | Request Type | Response Type | Description
GetNodeInfo | GetNodeInfoReq | GetNodeInfoResp |

## qrllegacy.proto

Top

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