LeiosFetch

Mini-protocol number: 19

Warning

This protocol is proposed and not yet part of the Cardano mainnet. It is specified as part of Leios (CIP-0164), an extension to the Ouroboros consensus protocol aimed at significantly increasing transaction throughput. Details are subject to change.

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
leiosBlockFetchMessage
     = msgLeiosBlockRequest
     / msgLeiosBlock
     / msgLeiosBlockTxsRequest
     / msgLeiosBlockTxs
     / msgClientDone
; TODO not implemented yet in leios-prototype
;     / msgLeiosBlockRangeRequest
;     / msgLeiosNextBlockAndTxsInRange
;     / msgLeiosLastBlockAndTxsInRange

msgLeiosBlockRequest           = [0, point]
msgLeiosBlock                  = [1, endorser_block]
msgLeiosBlockTxsRequest        = [2, point, bitmaps]
msgLeiosBlockTxs               = [3, point, bitmaps, tx_list]
; TODO not implemented yet in leios-prototype
; msgLeiosBlockRangeRequest =
;   [ 6
;   , start_slot  : base.slotno
;   , end_slot    : base.slotno
;   , start_hash  : base.hash
;   , end_hash    : base.hash
;   ]
; msgLeiosNextBlockAndTxsInRange = [7, endorser_block, tx_list]
; msgLeiosLastBlockAndTxsInRange = [8, endorser_block, tx_list]
msgClientDone                  = [9]

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

; map from tx hash to serialized tx byte size
; TODO: add valdity indices analogous to Dijkstra block body
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 ] ; REVIEW: only length-definite?

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

Note

The CBOR tags in this specification are provisional (MsgClientDone at [9] in particular). The endorser_block, bitmaps, and tx types remain underspecified (any) pending further protocol design, including the length-definite encoding for txList. Additionally, the protocol is known to be incomplete: catch-up oriented batch request messages are likely to be added, and the bitmap-based transaction request structure (MsgLeiosBlockTxsRequest) may change significantly as the roaring bitmap encoding is still under discussion. See CIP-0164 PR #1167 for the latest design decisions.