blockfetch

BlockFetch Protocol

The BlockFetch protocol retrieves blocks by hash from a peer node. It is used in node-to-node communication to fetch full block bodies after discovering headers via ChainSync.

Protocol Identifiers

State Machine

┌──────┐  RequestRange   ┌──────┐
│ Idle │ ───────────────►│ Busy │
└──┬───┘                 └──┬───┘
   │                        │
   │ ClientDone             │ StartBatch
   │                        │ NoBlocks
   │                        │
   ▼                        ▼
┌──────┐              ┌───────────┐
│ Done │◄─────────────│ Streaming │◄───┐
└──────┘              └─────┬─────┘    │
                            │          │
                            │ Block    │
                            └──────────┘
                            │
                            │ BatchDone
                            ▼
                       ┌──────┐
                       │ Idle │
                       └──────┘

States

Messages

State Transitions

From Idle (Client Agency)

From Busy (Server Agency)

From Streaming (Server Agency)

Timeouts

Limits

Configuration Options

blockfetch.NewConfig(
    blockfetch.WithBlockFunc(blockCallback),
    blockfetch.WithBlockRawFunc(blockRawCallback),
    blockfetch.WithBatchDoneFunc(batchDoneCallback),
    blockfetch.WithRequestRangeFunc(requestRangeCallback),
    blockfetch.WithBatchStartTimeout(5 * time.Second),
    blockfetch.WithBlockTimeout(60 * time.Second),
    blockfetch.WithRecvQueueSize(384),
    // Client request pipelining
    blockfetch.WithRequestPipelining(true),
    blockfetch.WithRangeDoneFunc(rangeDoneCallback),
    blockfetch.WithMaxInFlightBytes(blockfetch.DefaultMaxInFlightBytes),
)

Usage Example

// Request a range of blocks. One request is outstanding at a time; a second
// call blocks until the first batch completes.
startPoint := Point{Slot: 1000, Hash: startHash}
endPoint := Point{Slot: 2000, Hash: endHash}

if err := client.GetBlockRange(startPoint, endPoint); err != nil {
    return err
}

// Blocks arrive via BlockFunc/BlockRawFunc callback
// BatchDoneFunc called when range complete

Request Pipelining

MsgRequestRange is the pipelined client message of this mini-protocol, while MsgBlock is the server response that streams blocks back. cardano-node runs up to 100 outstanding requests per peer. A client that waits for a batch to finish before sending the next request idles the peer for a round trip at every batch boundary.

A client configured with RequestPipelining keeps a FIFO queue of outstanding MsgRequestRange. Responses are ordered, so queue position identifies the request a StartBatch, Block, NoBlocks, or BatchDone belongs to; no wire change is involved. CallbackContext.RequestId carries that identity to the block callbacks, and RangeDoneFunc is called exactly once per request with the terminal outcome.

id, err := client.RequestRange(ctx, blockfetch.RangeRequest{
    Start:         startPoint,
    End:           endPoint,
    ExpectedBytes: expectedRangeBytes, // from the chain-sync header sizes
})

RequestRange returns as soon as the request is queued and sent, and blocks only while admitting it would exceed MaxInFlightBytes. The bound is in bytes rather than requests because consumer range sizes vary by orders of magnitude; a caller that supplies no estimate is charged one maximum-size block body per request, which reproduces cardano-node's limit of 100 outstanding requests.

RequestPipelining is protocol request pipelining. It is unrelated to the Pipeline option, which is a processing pipeline for blocks that have already been received.

Block Format

Blocks are wrapped in CBOR with a type identifier:

type WrappedBlock struct {
    Type     uint   // Block type identifier (era)
    RawBlock []byte // Raw CBOR block data
}

Notes

• Used in conjunction with ChainSync (headers) + BlockFetch (bodies)
• Blocks are streamed in order from start to end point, and batches are answered in request order
• Large receive queue supports high-throughput block streaming
• The Streaming state has a higher pending byte limit for efficiency