Class BlockStreamPublisher

An open block stream publish session with a block node — the advanced, producer-side surface used by block-producing tooling, simulators and repeaters.

Inheritance

object

BlockStreamPublisher

Implements

IAsyncDisposable

Inherited Members

object.Equals(object)

object.Equals(object, object)

object.GetHashCode()

object.GetType()

object.ReferenceEquals(object, object)

object.ToString()

Namespace: Hiero.BlockNode

Assembly: Hiero.dll

Syntax

[Experimental("HIERO001", UrlFormat = "https://github.com/bugbytesinc/Hiero/blob/main/docs/blocknode-client-plan.md")]
public sealed class BlockStreamPublisher : IAsyncDisposable

Remarks

The publish protocol is a genuine state machine: the node may order the publisher to skip a block, resend one, or declare the publisher ahead of it, and acknowledgements arrive only after the node has verified and persisted a block. This session deliberately performs no automatic skip/resend handling — the caller drives, by consuming Events (which it MUST do) and reacting to directives; the only automation provided is WaitForAcknowledgementAsync(ulong, CancellationToken) resolving off cumulative acknowledgements. Publishers must retain each written block until it is acknowledged, in case the node requests a resend.

When the node ends the stream with an end-of-stream response, a final StreamEnded event carrying the reason is emitted, and a non-success reason faults pending and subsequent writes with a BlockNodeException carrying the mapped reason. If the stream instead drops (a transport failure, or a close without an end-of-stream response), no StreamEnded event is emitted: Events simply completes, and writes fault with a CommunicationError or Unavailable code. End the session gracefully with EndStreamAsync(PublishStreamEndCode, ulong, ulong, CancellationToken); disposing without it aborts the underlying call.

Properties

Events

Node directives and acknowledgements in arrival order. The caller MUST consume this stream: skip, resend and behind directives require action before or during subsequent writes. The channel completes when the stream ends.

Declaration

public ChannelReader<PublishStreamEvent> Events { get; }

Property Value

Type	Description
ChannelReader<PublishStreamEvent>

LastAcknowledgedBlockNumber

The highest cumulatively acknowledged (verified and persisted) block number, if any acknowledgement has arrived yet.

Declaration

public ulong? LastAcknowledgedBlockNumber { get; }

Property Value

Type	Description
ulong?

Methods

CompleteBlockAsync(ulong, CancellationToken)

Sends the block boundary marker for the in-progress block started via WriteBlockItemsAsync(IReadOnlyList<BlockItem>, CancellationToken).

Declaration

public Task CompleteBlockAsync(ulong blockNumber, CancellationToken cancellationToken = default)

Parameters

Type	Name	Description
ulong	blockNumber	The number of the block being completed.
CancellationToken	cancellationToken	An optional token that can interrupt the write.

Returns

Type	Description
Task

Exceptions

Type	Condition
BlockNodeException	If the stream has faulted or the write failed.

DisposeAsync()

.NET Asynchronous dispose method.

Declaration

public ValueTask DisposeAsync()

Returns

Type	Description
ValueTask

Remarks

Aborts the underlying call if the session was not gracefully ended via EndStreamAsync(PublishStreamEndCode, ulong, ulong, CancellationToken).

EndStreamAsync(PublishStreamEndCode, ulong, ulong, CancellationToken)

Gracefully ends the publish stream, telling the node why and what range of blocks this publisher holds, then closes the sending side and waits for the node to close its side.

Declaration

public Task EndStreamAsync(PublishStreamEndCode code, ulong earliestBlockNumber, ulong latestBlockNumber, CancellationToken cancellationToken = default)

Parameters

Type	Name	Description
PublishStreamEndCode	code	The reason for ending the stream.
ulong	earliestBlockNumber	The earliest block this publisher holds.
ulong	latestBlockNumber	The latest block acknowledged by the node (or held, if none were acknowledged).
CancellationToken	cancellationToken	An optional token that can interrupt the write and the wait for the node to close its side; without a cancellable token, that wait lasts until the node closes.

Returns

Type	Description
Task

Exceptions

Type	Condition
BlockNodeException	If the stream has faulted or the write failed.

WaitForAcknowledgementAsync(ulong, CancellationToken)

Returns a task that completes when the cumulative acknowledgement covers the given block number (immediately if it already does), or faults if the stream ends first.

Declaration

public Task WaitForAcknowledgementAsync(ulong blockNumber, CancellationToken cancellationToken = default)

Parameters

Type	Name	Description
ulong	blockNumber	The block number to await acknowledgement of.
CancellationToken	cancellationToken	An optional token that can abandon the wait (the stream is unaffected).

Returns

Type	Description
Task

Exceptions

Type	Condition
BlockNodeException	If the stream ended before the acknowledgement arrived.

WriteBlockAsync(Block, CancellationToken)

Sends a complete block: its items batched into a block item set, followed by the block boundary marker. Returns when the frames are written — NOT when the block is acknowledged; use WaitForAcknowledgementAsync(ulong, CancellationToken) for that.

Declaration

public Task WriteBlockAsync(Block block, CancellationToken cancellationToken = default)

Parameters

Type	Name	Description
Block	block	The complete block to publish (header first, proof last).
CancellationToken	cancellationToken	An optional token that can interrupt the write.

Returns

Type	Description
Task

Exceptions

Type	Condition
ArgumentNullException	If the block is null.
BlockNodeException	If the stream has faulted or the write failed.

WriteBlockItemsAsync(IReadOnlyList<BlockItem>, CancellationToken)

Streams items for the block currently being produced, before its proof exists — the shape a live block producer needs. The first item of a new block must be its header; close the block with CompleteBlockAsync(ulong, CancellationToken) after writing its proof item, or supersede it by writing the next block's header.

Declaration

public Task WriteBlockItemsAsync(IReadOnlyList<BlockItem> items, CancellationToken cancellationToken = default)

Parameters

Type	Name	Description
IReadOnlyList<BlockItem>	items	The items to send, in stream order, as one block item set; a set must never span two blocks.
CancellationToken	cancellationToken	An optional token that can interrupt the write.

Returns

Type	Description
Task

Exceptions

Type	Condition
ArgumentNullException	If the item list is null or empty.
BlockNodeException	If the stream has faulted or the write failed.

Implements

IAsyncDisposable