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

   StIdle --MsgLeiosVotesRequest--> StVotes
   StVotes --MsgLeiosVotes-->StIdle

   StIdle --MsgLeiosBlockRangeRequest--> StBlockRange
   StBlockRange --MsgLeiosNextBlockAndTxsInRange--> StBlockRange
   StBlockRange --MsgLeiosLastBlockAndTxsInRange--> StIdle

   class StIdle client
   class StBlock,StBlockTxs,StVotes,StBlockRange server

State agencies

State transitions

Codecs

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

;; messages.cddl
leiosBlockFetchMessage
     = msgLeiosBlockRequest
     / msgLeiosBlock
     / msgLeiosBlockTxsRequest
     / msgLeiosBlockTxs
     / msgLeiosVotesRequest
     / msgLeiosVoteDelivery
     / msgLeiosBlockRangeRequest
     / msgLeiosNextBlockAndTxsInRange
     / msgLeiosLastBlockAndTxsInRange
     / msgClientDone

msgLeiosBlockRequest           = [0, point]
msgLeiosBlock                  = [1, endorser_block]
msgLeiosBlockTxsRequest        = [2, point, bitmaps]
msgLeiosBlockTxs               = [3, tx_list]
msgLeiosVotesRequest           = [4, [1* (slot, voter_id) ]]
msgLeiosVoteDelivery           = [5, [1* vote ]]
msgLeiosBlockRangeRequest      = [6, start_slot, end_slot, start_hash, end_hash]
msgLeiosNextBlockAndTxsInRange = [7, endorser_block, tx_list]
msgLeiosLastBlockAndTxsInRange = [8, endorser_block, tx_list]
msgClientDone                  = [9]

point = (slot, eb_hash)
start_slot = slot
end_slot = slot
start_hash = base.hash
end_hash = base.hash
slot = base.slotNo
voter_id = base.word16  ; REVIEW: size?
eb_hash = base.hash
endorser_block = any ; TODO
bitmaps = any ; TODO
tx_list = [ *tx.tx ] ; REVIEW: length-definite encoding TBD

vote =
  [ election_id           : base.slotNo
  , persistent_voter_id   : base.word16
  , eligibility_signature : leios_bls_signature
  , endorser_block_hash   : base.hash
  , vote_signature        : leios_bls_signature
  ]

leios_bls_signature = bytes .size 48

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