LeiosFetch

Mini-protocol number: 19

LeiosFetch is the mini-protocol responsible for fetching Endorser Blocks (EBs) and their transaction payloads from peers. It is a pull-based protocol: the client explicitly requests either a full EB or a subset of its transactions (identified by a bitmap), and the server streams the response.

EBs are discovered via LeiosNotify; once a node decides it wants a block or its transactions, it uses LeiosFetch to retrieve the data.

State machine

graph LR
   classDef client color:black,fill:PaleGreen,stroke:DarkGreen;
   classDef server color:black,fill:PowderBlue,stroke:DarkBlue;
   linkStyle default stroke:gray

   StDone(((StDone)))

   i(( )) --> StIdle
   StIdle --MsgDone--> StDone
   StIdle --MsgLeiosBlockRequest--> StBlock
   StBlock --MsgLeiosBlock--> StIdle

   StIdle --MsgLeiosBlockTxsRequest--> StBlockTxs
   StBlockTxs --MsgLeiosBlockTxs--> StIdle

   class StIdle client
   class StBlock,StBlockTxs server

State agencies

State transitions

Codecs

The messages depicted in the state machine follow this CDDL specification:

;; messages.cddl
; Termination first, as in LeiosNotify, then each request beside the response
; it draws.
leiosBlockFetchMessage
     = msgDone
     / msgLeiosBlockRequest
     / msgLeiosBlock
     / msgLeiosBlockTxsRequest
     / msgLeiosBlockTxs

msgDone                        = [0]
msgLeiosBlockRequest           = [1, point]
msgLeiosBlock                  = [2, endorser_block]
msgLeiosBlockTxsRequest        = [3, point, bitmaps]
msgLeiosBlockTxs               = [4, point, bitmaps, tx_list]

point = [slot, eb_hash]
slot = base.slotno
eb_hash = base.hash

; map from tx hash to serialized tx byte size
endorser_block = { * base.hash => base.word32 }

; indefinite-length map from 64-tx window index to 64-bit presence bitmap
bitmaps = { * base.word16 => base.word64 }

tx_list = [ *tx.tx ]

;# import base as base
;# import tx as tx

Note

The endorser_block, bitmaps and tx types remain underspecified pending further protocol design, including whether tx_list is length-definite, and the bitmap-based transaction request (MsgLeiosBlockTxsRequest) may yet change as the roaring bitmap encoding is still under discussion.

Catch-up oriented batch requests were once expected here (MsgLeiosBlockRangeRequest and its replies). They were never implemented and are no longer planned, so they are not specified.