Messages

All message contain following basic fields:

Element Data type Bytes Description
magic uint32 4 0x42042042, Indicating that this is a message.
type VarInt >=1, <= 8 Usually 1 bytes
length uint32 4 Length of the message. Currently ignored.
checksum uint32 4 CRC32 checksum.

All messages have a fixed message type. Additional fields of specialized messages will be added behind.

Version Message

This message type = 0 sends out the status of this node, including it’s protocol version, peer address, genesis block hash, and the hash of the latest block in its blockchain (the head). It must be the first message a node sends to another node.

Element Data type Bytes Description
version uint32 4 Version of the protocol
peer address uint32 4 Three address types; see below
genesis hash Hash 32 Hash of Genesis block
head hash Hash 32 Hash of latest block in node’s blockchain.
challenge nonce raw 32 Peer needs to sign to authenticate.

Version Acknowledgement Message

Immediately after receiving the initial version message, a node answers with the version acknowledgement message.

Element Data type Bytes Description
public key raw 32 Public key of peer
signature raw 64 Signature on received address concatinated with challenge nonce

Addresses

Three addresses are being used: Web Socket address, Web RTC address, and plain/dumb address.

All three share following fields:

Element Data type Bytes Description
protocol uint8 1 0..2: dumb, RTC, WS address. See below.
service mask uint32 4 0 none, 1 nano, 2 light, 4 full
timestamp uint64 8 Used by other nodes to calculate offset.
net address string 1 - 17 IPv4 address as string unless the IP is private (then empty string), or <unknown>; first byte specifies length.
public key raw 32 Peer’s public key
signature raw 64 Peer signs net address to make sure it can not be modified by someone else
distance uint8 1 Number of hops to this peer, 1 meaning the peers are connected directly.

Each peer is identified by it’s peer ID, which is obtained by truncating the public key down to 16 bytes. The RTC peer address uses the peer ID as signaling ID.

A WS peer address has following additional fields:

Element Data type Bytes Description
host string >10 Hostname
port number 2 Port number for Web Socket Connector to listen to.

Request and Receive Inventory

A typical situation:

  1. Node A enters the network and needs to synchronize
  2. B sends out a get blocks message
  3. B receives and sends an relay inventory with hashes of blocks that B considers useful for A
  4. B compares the list with the blocks it has already
  5. B uses get data to request the data for the blocks it doesn’t have yet.

Similarily

  1. Node A wants to update it’s mempool and
  2. A sends out a mempool message
  3. Node B receives and sends an relay inventory message with blocks and transaction they have in their mempool
  4. … same like previous

Get Blocks

Element Data type Bytes Description
count uint16 2 Number of hashes requested
locators [Hash] count * 32 List of block hashes from where to start sending more blocks. The receiving node will start sending from the first block it finds in it’s blockchain.
max inventory size uint8 2 The number of blocks that are been asked.
direction uint8 1 1 forward (blocks afterwards); 2 backwards (previous blocks).

The response can be type = 6 for blocks, 7 for header, 8 for transaction, or type = 4 if the requested inventory could not be found.

Relay Inventory

Announcing it’s blocks and transmissions, a node sends out an inventory message:

Element Data type Bytes Description
count uint16 2  
hashes [Type+Hash] count * 36 Depending on type, hashes of transactions or blocks

Requesting Data

Request headers via type = 3, and block or transactions data via type = 2

Element Data type Bytes Description
count uint16 2  
hashes [Type+Hash] count * 36 Depending on type, hashes of transactions or blocks

The type for each element in the hashes list can be 0..2: error, transaction, and block. 0 is not being used.

Block Message

This message is used to send one block at a time (in serialized form).

Element Data type Bytes Description
block Block <= 100kB Full block

Header Message

This message is used to send one header at a time (in serialized form).

Element Data type Bytes Description
header Header 162 Block header

TX Message

This message is used to send one header at a time (in serialized form).

Element Data type Bytes Description
transaction Transaction XXX Transaction

Mempool Message

This message is used to request peers to relay their inventory/mempool content. No additional fields, type = 9, cf. message types.

Reject Message

This message is used to signal to a peer that something they sent to the node was rejected and the reason why it was rejected.

Element Data type Bytes Description
message type VarInt 1 Message type
code uint8 1 Reject message codes
reason length uint8 1  
reason string length The reason why.
extra data length uint16 2  
extra data raw length Extra information that might be useful to the requester.

Subscribe Message

This message is used to subscribe to messages from the node that this message is sent to, two version exist, “addresses” and “min fee”.

Element Data type Bytes Description
subscription type uint8 1 2 for “addresses” or 3 for “min fee”

Type “addresses” adds:

Element Data type Bytes Description
address count uint16 2 Number of addresses
addresses [Address] count * 20 List of addresses to subscribe to

Type “min fee” adds:

Element Data type Bytes Description
fee uint64 8 Min fee per byte in Luna required to subscribe

Relay Addresses

This message is used to relay the addresses to other peers.

Get Addresses Message

Ask for for addresses to peers that use the specified protocol and provide the specified services.

Element Data type Bytes Description
protocol mask uint8 1 0 dumb, 1 ws, 2 rtc
service mask uint32 4 0 none, 1 nano, 2 light, 4 full

Addresses Message

A list of address in return for a get addresses message.

Element Data type Bytes Description
address count uint16 2 Number of addresses
addresses [Address] count * 20 List of addresses of other peers in the network.

Heart Beat Messages

This messages are used to make sure that the other peer node is available still.

Element Data type Bytes Description
type uint16 2 22 for ping, 23 for pong (response)
…      
nonce uint32 4 Make pings and pongs unique, avoid replay

Signal Message

Signaling is needed for the browser clients to establish a connection with other clients of the same type.

Element Data type Bytes Description
sender id raw 16 16 bytes address of sender
recipient id raw 16 16 bytes address of recipient
nonce uint32 4 To avoid replay
time to live uint8 1 TTL
flags uint8 1 Unroutable: 0x1, TTL exceeded: 0x2
payload length uint16 2  
payload raw length Signed data, cf. signature
sender public key uint32 32 If payload payload length > 0
signature raw 64 If payload payload length > 0

Relay Proofs

Chain Proof

To get chain proof, sent a basic message with type = 40.

The response (type = 41) contains blocks and headers.

Element Data type Bytes Description
block count uint16 2 Amount of blocks attached
blocks Block max count * 100kB Full blocks
header count uint16 2 Amount of headers attached
header chain Header count * 162 Headers

Accounts Proof

A node can ask (type = 42) for proofs for certain accounts by using the hash of it’s accounts tree root.

Element Data type Bytes Description
block hash Hash 32 Hash of block these accounts should be in
address count uint16 2  
addresses Address count * 20 Addresses to be checked

To get a response (type = 43) with following data:

Element Data type Bytes Description
block hash Hash 32 Block these accounts are in
has proof uint8 1 1 means the proof is attached, otherwise 0
proof count uint16 2  
proofs AccountsTreeNode count * variable size Proofs for the requested accounts as nodes from the Merkle tree.

To request a paricular chunk of of account tree nodes (type = 44)

Element Data type Bytes Description
block hash Hash 32 Hash of block these accounts should be in
start prefix length uint8 1  
start prefix string length Defining the part of the tree where accounts are needed from.

The node should respond a message type = 45:

Element Data type Bytes Description
block hash Hash 32 Hash of block these accounts should be in
has chunks uint8 1 1 means chunks are attached
node count uint16 2  
nodes AccountsTreeNode count * variable size Account tree nodes from the requested part of the tree.
proof count uint16 2  
proofs AccountsTreeNode count * variable size Account tree nodes as proof

Transactions Proof

This message is used to send one transaction at a time (in serialized form) but can also contain an accountsProof.

Request Transaction Proofs

Element Data type Bytes Description
block hash Hash 32 Hash of block the transactions belong to
transactions count uint16 2 Count of transactoins being requested
transactions hash [Transaction] count * 20 Hashes of transactions being requested

Receive Transaction Proofs

Element Data type Bytes Description
block hash Hash 32 Hash of block the transactions belong to
has proof uint8 1 1 means the proof is attached, otherwise 0
proof length uint16 2 If has proof was set
proof raw proof length The proof if has proof was set

Transaction Receipts

Get transactions receipts via message type = 49

Element Data type Bytes Description
address Address 20 Address of transaction

Receive transactions receipts in a type = 50 message:

Element Data type Bytes Description
receipt count uint16 2  
receipts 2x Hash 64 Transaction hash and block hash