messages-and-requests.md

Messages and Requests

Nodes communicate in two ways:

• One-to-one communication with messages and requests
• One-to-many communication by gossiping

Nodes identify each message or request by the TYPE_ID and their RequestKind. Messages have a MessageMarker and don’t require a response, and requests have a RequestMarker and always require a response. For simplicity, we will focus on the interactions of messages and requests between node A and node B.

Validator Message/Request

These messages and requests are specific to validators.

10_199 Request Proposal

Tendermint proposals are gossiped among validators so they can vote on them. However, validators can miss a proposal and notice it by witnessing other validators vote on it. In this specific context, the validator missing the proposal can send this request and receive the proposal in question.

Request

Field	Type	Description
validator_id	u16	Identifies the validator sending the request. This allows the receiver to quickly verify that the validator ID matches the sender
block_number	u32	The corresponding block of the proposal
round_number	u32	The round number of the round the node is missing
proposal_hash	Blake2sHash	The hash of the block proposal

Response

Field	Type	Description
proposal	MacroHeader	The macro block header proposal
round	u32	The round number of the corresponding proposal
valid_round	Option<u32>	Indicates if it is a valid proposal
signature	SchnorrSignature	The signature of the block’s leader
signer	u16	The signer of the sender of the request

10_124 Tendermint Update - Message

Field	Type	Description
message	TaggedAggregationMessage<AggregateMessage>	The aggregated message containing validator signatures
height	u32	The height of the Tendermint proposal

10_123 Skip Block Update - Message

Field	Type	Description
level_update	LevelUpdate<SignedSkipBlockMessage>	The level update containing the signed skip block message
info	SkipBlockInfo	Contains information about the skip block

Messages are used to notify other nodes about votes for skip blocks and Tendermint proposals. The Handel aggregation protocol facilitates this process by aggregating small sets of votes into a single signature. These votes are processed in levels, with aggregated signatures passed from one level to the next until a single aggregated signature is obtained. This final signature determines whether the conditions for producing a skip block or a macro block are met.

Requests

Requests guide nodes in the blockchain, whether for sync, resync, to subscribe for addresses, or to locate a node in the chain. Node A requests and node B provides the data requested.

ID Type	Name	Description
200	Request Macro Chain	Request for all the election blocks and the last checkpoint blocks of the latest batch
202	Request Batch Set	Request for the information of a batch
204	Request History Chunk	Request the history chunk of a specific index
207	Request Block	Request for a block given a block hash
209	Request Missing Blocks	Request any missing blocks given a block hash
210	Request Head	Request the block header of a given block hash
211	Request ZKP	Request a zkp for sync or resync
212	Request Chunk	Request for a specific part of the the state trie
213	Request Transactions Proof	Request for a proof on a specific transaction
214	Request Transaction Receipts by Address	Request for a set of receipts of a specific address
215	Request Trie Proof	Request for a proof of a specific address balance
216	Request Blocks Proof	Request for a proof on a specific block
217	Request Subscribe to Address	Request for a specific address subscription
218	Request Trie Diff	Request for differences in the trie to complete a partial trie based on a block hash

200 Request Macro Chain

This request guides a node within the macro chain. If the node is far from the desired point and max_epochs is set low, it may need multiple requests to different peers.

Request

Field	Type	Description
locators	Vec<Blake2bHash>	A vector block hashes that the node knows to guide the network to identify the position of the node
max_epochs	u16	The maximum number of epochs the node wishes to receive in response per request. The node can send this request to multiple peers if necessary

Response

Field	Type	Description
epochs	Option<Vec<Blake2bHash>>	A list of hashes of the election blocks following the provided locators. If the max_epochs limit is not sufficient to reach the most recent election block, the node may need to send additional requests
checkpoint	Option<Checkpoint>	The last checkpoint block of the most recent epoch included in the response

202 Request Batch Set

Given the hash from the last request, node A can request node B's information about the given batch. This request follows the response from request 200, where the vector of hashes received is used to feed into this request.

Request

Field	Type	Description
hash	Blake2bHash	The hash of the last response from request 200; this request should be made for each hash received in the 200 response

Response

Field	Type	Description
election_macro_block	Option<MacroBlock>	The election block of the given batch
batch_sets	Vec<BatchSet>	A vector of batch sets

Each BatchSet includes the following:

Field	Type	Description
macro_block	Option<MacroBlock>	The closing macro block of the given batch
history_len	u32	The total history length of the given macro block

204 Request History Chunk

Transactions are stored in the history tree, and nodes that want to know parts of the transaction history must request it in chunks. Each history chunk has around 1000 items, so the node can request several chunks from multiple other nodes to build its history tree and, in the end, calculate its history root hash against the chain’s history root hash.

Request

Field	Type	Description
epoch_number	u32	The epoch number for which the node wants to receive history items
block_number	u32	The block number of the last macro block of the corresponding chunk index
chunk_index	u64	The range of history items the node wants to receive. For example, if set to 2, the history items from 1000 to 1999 are requested

Response

Field	Type	Description
chunk	Option<HistoryTreeChunk>	The requested chunk of history items, if available

The HistoryTreeChunk provides both the proof and the actual history of transactions within the requested chunk. This ensures the integrity and completeness of the historical data being requested.

207 Request Block

This request allows a node to obtain a specific block by its hash, optionally including the body of a micro block.

Request

Field	Type	Description
hash	Blake2bHash	The hash of the block that is being requested
include_micro_bodies	bool	Indicates whether to include the body if the requested block is a micro block

Response

The node receives either a MicroBlock or a MacroBlock.

209 Request Missing Blocks

This request allows node A to fetch any blocks that it misses, using known block hashes as locators to identify the blocks it needs.

Request

Field	Type	Description
target_hash	Blake2bHash	The hash of the block that is being targeted; the nodes knows this hash because of previous requests
include_micro_bodies	bool	Indicates whether to include bodies for micro blocks
locators	Vec<Blake2bHash>	A set of hashes of blocks known to the requester, ordered from newest to oldest
direction	Direction	The direction indicates whether to search forward (main chain blocks only) or backward (including blocks from inferior chains, more resource-intensive)

Response

Field	Type	Description
blocks	Option<Vec<Block>>	An optional vector of blocks. If the request is successful, this field contains the blocks that were requested

210 Request Head

This request has no fields and serves to check if the node is synced with others.

Request

Request	Description
RequestHead{}	empty request

Response

Field	Type	Description
micro	Blake2bHash	The hash of the current micro block
r#macro	Blake2bHash	The hash of the current macro block
election	Blake2bHash	The hash of the current election block

211 Request ZKP

Light and full nodes use this request to sync with the blockchain by obtaining a light proof instead of downloading all blocks.

Request

Field	Type	Description
block_number	u32	Specifies the block number the node already has (can be the Genesis block if it is first connecting).
request_election_block	bool	Indicates whether the node wants only the proof or the proof along with the corresponding election block.

Response

The node receives a RequestZKPResponse enum, which can be one of the following:

Variant	Type	Description
Proof	(ZKProof, Option<MacroBlock>)	Contains a ZKProof and an optional MacroBlock
Outdated	u32	Indicates that the node's given block number is outdated

212 Request Chunk

This request is used by full nodes to sync with the blockchain state by requesting chunks of data as the blockchain progresses. Nodes can request one chunk at a time, using the data received in the previous request to make the subsequent request, until they are up-to-date and their local state matches the network state.

Request

Field	Type	Description
start_key	KeyNibbles	The last part of the state tree the node knows (from the previous response)
limit	u32	The maximum size of the chunk per request

Response

The node receives a ResponseChunk enum, which can be one of the following:

Variant	Type	Description
Chunk	Chunk	Contains the chunk of the state tree that the node needs to add to its partial trie
IncompleteState	None	Indicates that the node's state is incomplete and needs further chunks

Fields of Chunk:

Field	Type	Description
block_number	u32	The block number corresponding to the chunk
block_hash	Blake2bHash	The block hash corresponding to the chunk
chunk	TrieChunk	The chunk of the state tree that the node needs

213 Request Transactions Proof

This request is specific for light nodes that want a proof of a specific transaction. Only history and full nodes respond to this request.

Request

Field	Type	Description
hashes	Vec<Blake2bHash>	The hashes of the transactions
block_number	Option<u32>	The block number of the corresponding transactions (optional)

Response

Field	Type	Description
proof	Option<HistoryTreeProof>	The proof that includes the extended transactions (optional)
block	Option<Block>	The complete block (optional)

214 Request Transaction Receipts by Address

This request is used to obtain transaction receipts for a specific address. Only history nodes can respond to this request.

Request

Field	Type	Description
address	Address	The address for which the node wants to obtain receipts
max	Option<u16>	The maximum number of receipts per request (optional)

Response

Field	Type	Description
receipts	Vec<(Blake2bHash, u32)>	A vector of tuples containing the transaction hashes and corresponding block numbers

215 Request Trie Proof

This request is used to prove the balance of specific addresses.

Request

Field	Type	Description
keys	Vec<KeyNibbles>	Addresses for which the accounts trie proof is requested. This consists of an internal representation of the address

Response

Field	Type	Description
proof	Option<TrieProof>	The accounts’ trie proof (optional)
block_hash	Option<Blake2bHash>	The hash of the block corresponding to the proof (optional)

216 Request Blocks Proof

This request is used to obtain a list of election macro blocks that reference each other. It is used to prove that a block is in the blockchain.

Request

Field	Type	Description
election_head	u32	The block number of the corresponding election macro block header
blocks	Vec<u32>	A vector of block numbers for which proof is requested

Response

Field	Type	Description
proof	Option<BlockInclusionProof>	The proof consists of an interlink chain from the current election head down to the target block (optional)

217 Request Subscribe to Address

This request is used to subscribe or unsubscribe to updates for specific addresses.

Request

Field	Type	Description
operation	AddressSubscriptionOperation	The type of subscription operation: subscribe or unsubscribe
addresses	Vec<Address>	A list of addresses that are of interest to the peer

Response

Field	Type	Description
result	Result<(), SubscribeToAddressesError>	The result of the subscription request. This indicates success or provides an error if the request failed

218 Request Trie Diff

This request is used by nodes that are building their partial trie and may need to download the missing parts to complete their trie. It helps nodes to synchronize their state by obtaining the necessary differences for a specific block, especially when they depend on parts that have not been downloaded yet.

Request

Field	Type	Description
block_hash	Blake2bHash	The hash of the block for which the trie differences are requested

Response

The node receives a ResponseTrieDiff enum, which can be one of the following:

Variant	Description
PartialDiff(TrieDiff)	Contains the differences in the trie needed to complete the partial trie
UnknownBlockHash	Indicates that the provided block hash is unknown
IncompleteState	Indicates that the node's state is incomplete and further differences are needed