HIP-1081: Block Node

Abstract

This HIP introduces Block Nodes. Block Nodes receive block streams from Consensus Nodes (or other block stream publishers), verify the integrity of each block, store the block chain, distribute blocks to downstream clients (including Mirror Nodes and other Block Nodes), maintain a copy of consensus network state, and enable critical capabilities including state proofs, block item proofs, and provide new capabilities for Consensus Nodes such as providing the current state when bootstrapping a new consensus node or catching up to the current consensus network state when a Consensus Node is far behind its peers.

By assuming responsibility for long-term block and state storage, Block Nodes will replace the current use of cloud storage buckets for distributing data to Mirror Nodes and other block stream consuming clients. Additionally, by maintaining latest consensus network state, Block Nodes offload key data management functions from Consensus Nodes, improving scalability and operational efficiency. Block Nodes are the decentralized data lake for the ledger.

Block Nodes expose robust APIs for filtered or full block streams, random block access, and cryptographic proofs of block data. This architecture fosters a decentralized data services layer, enabling independent operators to deliver value-added services such as analytics, aggregation, and real-time data pipelines. This further decentralizes the ledger and enhances data availability, security, and usability.

Block Nodes are free to innovate on payment for access to these features. They can be commercial and have connectivity rules / rate limits / SLAs for customers with settlement in native cryptocurrency, web2 pay walls, or at no cost.

Motivation

The current Hiero network architecture stores records files, event files, sidecars, state snapshots and signatures in S3-compatible cloud storage. Access to this data may be expensive (such as with reader-pays public cloud storage buckets). More importantly, the API used for storing and accessing this data is restricted to the standard S3 object storage API.

While perfectly reasonable as an artifact storage solution, such a design precludes enhanced capabilities that fit-for-purpose APIs would provide, such as targeted data schema, business-inspired performance optimizations, and a streamlined developer experience that supports end users of downstream services. By managing the transport, parsing and storage logic, a Block Node can support optimized streaming and filtering of block data. Additionally, a Block Node is able to decouple the consensus network data stored from the API that it serves, this allows it to provide consensus network supporting services like live state, proof generation and reconnect.

An additional motivation for Block Nodes is to support a more open and inclusive ecosystem, where community members can run full-featured servers with access to the complete consensus network history and state for verification by downstream services.

As such, Block Nodes are designed to decentralize data storage and access, enabling independent operators to serve verified block and state data directly from the consensus network. This allows users and applications to consume the data without relying on enterprise-operated infrastructure or cloud-specific implementations.

Block Nodes will provide a clean architectural separation of responsibilities: Consensus Nodes focus on consensus and transaction execution, while Block Nodes focus on data availability, accessibility, and verifiability. This paves the way for a more decentralized and developer-friendly ledger.

Rationale

The Block Node is introduced to address three strategic goals for the Hiero network: increased data availability, greater decentralization, and improved client diversity. These goals reflect a broader effort to reduce reliance on centralized infrastructure, improve access to consensus network data, and empower a wider range of developers and operators to build on the ledger.

Communication Protocol

To support these goals, Block Nodes will communicate using gRPC over HTTP/2, a protocol chosen for several key reasons:

• High-performance streaming: Enables efficient, low-latency delivery of large volumes of block and state data.
• Cross-platform compatibility: Supported across most modern development environments, improving accessibility for diverse client implementations.
• Native support for protocol buffers: Ensures strong typing, forward compatibility, and extensibility of APIs over time.

This communication model aligns with the protocol stack already used by Hiero Consensus Nodes, reinforcing architectural consistency across the ledger. While gRPC is the initial focus, the design remains extensible. Future enhancements may include support for WebSocket, REST, or GraphQL interfaces to meet evolving developer and community needs—striking a balance between performance, flexibility, and ecosystem adoption.

Upgradeability

A key design goal of the Block Node is upgradeability and ease of operation across diverse environments, including different platforms and cloud hosting providers. Unlike Consensus Nodes—which must run identical versions of the node software to maintain their network integrity—Block Nodes are intentionally decoupled from the consensus layer. This enables independent deployment and upgrade cycles without requiring coordination with the core Consensus Node network. Additionally, there could be many implementations of a Block Node across languages and platforms; they need only confirm to the API specified in this HIP. This independence increases the resilience and diversity of the ledger by allowing open-source developers and operators to maintain Block Nodes on their own cadence and maintenance windows.

While protocol-level consistency must be maintained—particularly with regard to the block stream’s protobuf schema—Block Nodes are designed with forward compatibility in mind. Even if a node does not fully understand newly added fields, it should still be able to parse, verify, store, and serve block data reliably, ensuring consensus network continuity and access to verifiable data during version transitions. To support transparency and ecosystem interoperability, Block Nodes will expose semantic versioning via API. This allows clients and developers to identify feature sets, manage compatibility, and ensure predictable integration behavior across versions.

User stories

Personas

• Hiero Consensus Node Operators: Enterprise-aligned operators responsible for validating transactions, maintaining network consensus, and producing block streams.
• Independent Block Node Operators: Independent entities running Block Nodes to support decentralized data access, historical state services, or value-added APIs.
• Mirror Node Operators: Infrastructure providers consuming verified data from Block Nodes to serve RESTful endpoints for block explorers dApps and analytics tools.
• Application Developers / dApp Builders: Developers building decentralized applications that depend on reliable access to historical or real-time block and state data
• Auditors / Analysts / Researchers: Users performing independent validation of transactions, querying historical state, or analyzing consensus network behavior for compliance or insight

User Stories

Consensus Node Operators

1. As a Consensus Node Operator, I want to publish block streams to one or more Block Nodes, so that I can offload long term data storage responsibilities and focus server resources on consensus operations.
2. As a consensus node I want to know that the block node(s) I send my blocks to are trustworthy so that I can trust acknowledgement truly represents secure persistence of a verified block.
3. As a Consensus Node Operator I want to know that I can access a reconnect API with high enough priority and performance to effectively recover synchronization with the consensus network.
4. As a Consensus Node Operator I want to implement a shared communication protocol with Block Nodes that defines how success or failure pathways during block stream publishing are communicated back to me in real time. This will allow me to implement optimal data distribution algorithms to ensure blocks are persisted amongst a diverse set of Block Nodes.

Block Node Operators

1. As a Block Node Operator, I want to provide a publishBlockStream API to which one or more Consensus Nodes (or other Block Stream producers) can push block streams, so that I can build a complete and reliable record of consensus network activity.
2. As a Block Node Operator, I want to verify block proofs as part of block stream ingestion, so that I can ensure the authenticity and integrity of the data I store and serve.
3. As a Block Node Operator, I want to persist block data and state snapshots, so that I can provide historical access and recovery capabilities to other nodes and clients.
4. As a Block Node Operator, I want to serve real-time block streams via a subscribeBlockStream API, so that clients can access up-to-date consensus network activity as it happens, on demand.
5. As a Block Node Operator, I want to provide historical block access via a getBlock API, so that users can retrieve and analyze past blocks on demand.
6. As a Block Node Operator, I want to offer APIs for querying current and historical state, so that clients can understand the evolution of Hiero entities (account, smart contracts, files, tokens, topics and schedules) over time.
7. As a Block Node Operator, I want to offer proof APIs for external validation of blocks and state, so that third parties can verify the correctness of consensus network data without relying on trust in my services.
8. As a Block Node Operator, I want to support Reconnect APIs for syncing new or lagging nodes (Consensus or Block), so they can catch up to the latest block and state information from the consensus network efficiently and securely.
9. As a Block Node Operator, I want to subscribe to unverified block streams from other Block Nodes, so that I can increase redundancy, expand coverage, or fill data gaps.
10. As a Block Node Operator, I want to expose a serverStatus API to report my current capabilities, so that clients can discover my block range, and service availability.
11. As a Block Node Operator, I want to offer filtered block streams to external clients (including Block Nodes and Mirror Nodes), so that subscribers only receive the data relevant to their use cases, reducing bandwidth and processing overhead.
12. As a Block Node Operator I want to maintain a block node that only stores the data within blocks that is important to me so that I do not incur the cost of maintaining data within blocks of no value to me.
13. As a Block Node Operator I want to maintain a block node that stores only the block ranges that are important to me so that I do not incur the cost of maintaining blocks that are of no value to me.
14. As a Block Node Operator I want to utilize a storage retention policy that allows me to prune data older than a configurable threshold so that I can optimize my storage resources and costs.
15. As a Block Node Operator I want to implement a shared communication protocol with Consensus Nodes that defines how success or failure pathways during block stream publication are handled. This will allow me to inform Consensus Nodes of the status of their blocks but also implement optimal data ingestion algorithms to ensure blocks are sourced from a diverse set of Consensus Nodes.
16. As a Block Node Operator I want to support the cost-effective backup of my data to external archive solutions so that I can optimize my local storage resources and costs.
17. As a Block Node Operator I want to deliver state snapshots in a well-defined format that is supported by existing tools provided by the Hiero project.

Application Developers / dApp Builders

1. As a dApp Developer, I want to stream real-time transaction data filtered by my application’s criteria, so that I can monitor and react to relevant on-chain events efficiently.
2. As a dApp Developer, I want to query historical state from a Block Node, so that I can understand application behavior over time and debug or audit contract interactions.
3. As a dApp Developer, I want to fetch state proofs for validation in a low-trust model from a Block Node, so that I can build applications that do not require trust in centralized infrastructure.

Mirror Node Operators

1. As a Mirror Node Operator, I want to consume verified block and state data from a Block Node, so that I can serve reliable ReSTful APIs to applications and developers.
2. As a Mirror Node Operator, I want to bootstrap quickly and economically using snapshots and recent blocks, so that I can recover from downtime or deploy new infrastructure without full re-sync from stream start.

Auditors / Analysts / Researchers

1. As an Auditor or Analyst, I want to retrieve historical block and state data, so that I can conduct investigations, perform compliance checks, or reconstruct on-chain activity.
2. As a Researcher, I want to analyze transaction and state trends using structured and verified data, so that I can gain insights into network usage, adoption patterns, and protocol behavior.

Specification

Terms and Definitions

Tier 1 Block Nodes

Tier 1 Block Nodes provide high-availability, performance-critical services directly to Mainnet Consensus Nodes (CNs) and other Tier 1 Block Nodes. They receive block streams directly from Consensus Nodes and are typically operated by trusted node operators. For optimal performance, Tier 1 Block Nodes are expected to be deployed in close proximity to Consensus Nodes, minimizing latency in stream processing and delivery.

Tier 2 Block Nodes

Tier 2 Block Nodes extend the capabilities of Tier 1 by offering additional services to developers, applications, and the broader community. They receive block streams from Tier 1 nodes or Tier 2 nodes and may offer both free and monetized data services. These nodes are designed to foster decentralization by allowing independent entities to operate Block Nodes under flexible models, including subscription-based access, pay-per-query APIs, or open data access.

Services

Hiero Block Node functionality can be grouped into two primary categories:

• Consensus Network Support Functionality – Ingesting, verifying, storing and remote archiving block streams generated by Hiero Consensus Nodes.
• Data Access Functionality – Value-added and easy to access information and data insights to users and applications.

This categorization allows for a clear delineation of protocol-level responsibilities from service-layer innovations.

Block Node implementers are encouraged to architect services as loosely coupled, independently deployable components, rather than as tightly integrated or monolithic systems. This modular design promotes lightweight, scalable deployments—making Block Nodes more accessible to community operators and more flexible for developers seeking to innovate on top of the data stream.

Block Stream Publish Service

Block Nodes will expose a streaming endpoint on the BlockStreamPublishService to which a block stream producing client like a Consensus Node can publish block items. Consensus Nodes or other block stream supplying clients act as the Publisher feeding the Block Node data.

By Consensus Nodes pushing block stream data to Block Nodes the traffic and implications of Block Nodes and other clients querying a Consensus are avoided. This allows Consensus Nodes to control their data rate and explicitly configure trusted recipients of its data. As such a block node must be ready and available to accept connections that push the block stream to as blocks are agreed upon by the consensus network.

Block Node operators may optionally configure filters to limit stored content to block items relevant to their use case—for example, filtering by HCS topic. Filtering occurs at the block item level, allowing dApps to store only the data they desire.

Block Stream Subscribe Service

Block Nodes will expose a BlockStreamSubscribeService to which block stream consuming clients like a Mirror Node or dApp can subscribe to block items.

This service enables applications, indexers, and data platforms to initiate a pull-based stream of block items directly from a Block Node to which they can react to consensus network activity as it occurs—without maintaining consensus node infrastructure.

Clients may optionally specify filters to limit streamed content to block items relevant to their use case—for e.g. filtering by StateChange block items. Filtering occurs at the block item level, allowing dApps to receive only the data they need. Future enhancements may include more advanced filtering such as transaction level filter (e.g. on smart contract transactions) or state entity level filtering (e.g. only specific HCS topics).

Block Access Service

Block Nodes will expose a BlockAccessService to which block consuming clients like a Mirror Node or dApp can access historical blocks.

Each block returned by this service is verified, and includes the relevant metadata and signatures necessary for cryptographic validation, ensuring consumers can trust the data without needing direct access to consensus nodes.

Block Node Service

Block Nodes will expose a BlockNodeService to which interested downstream clients like a Mirror Node or dApp can inquire node details regarding the Block Node.

The BlockNodeService provides essential metadata about the operational state and configuration of a Block Node, enabling clients to make informed decisions about connectivity, compatibility, and data availability.

The service exposes key information such as:

• Current and available block ranges
• Supported API version and protocol capabilities
• Availability of historical state snapshots

This service is especially useful for clients bootstrapping a connection, discovering available features, or selecting between multiple Block Nodes based on capabilities or data retention. It also helps ecosystem tools—such as indexers, dashboards, and health check systems—monitor and validate the status of deployed nodes.

State Service

Block Nodes will expose a StateService to which interested downstream clients like a Mirror Node or dApp can query for Hashgraph state details.

In today’s consensus network, consensus nodes periodically take state snapshots and store them in centralized cloud buckets. These backups are primarily used for Consensus Node bootstrapping, disaster recovery, and long-term archival. However, this data has not been made readily accessible to the broader community, limiting its utility for external developers and applications. By maintaining live state and capturing periodic state snapshots, Block Nodes can introduce new state-related services that provide access to consensus network state at any block height.

Note: In the future a block node could offer additional APIs such as on demand Live state, a stream of state changes or single entity state requests.

Proof Service

Block Nodes will expose a ProofService to which interested downstream clients like a Mirror Node or dApps interested in verification can requests proofs for Blocks, State or data within the Block.

The service exposes cryptographic proofs defines in HIP-1056 and HIP 1200 including but not limited to

• BlockContentsProof to verify that a specific BlockItem (e.g., a transaction or event) was included in a given block.
• StateProof to confirm the value of a specific state key at a particular block height.

The ability to request cryptographic proofs of state in particular have long been a desired feature for developers and auditors. However, implementing such functionality directly on consensus nodes would introduce additional computational and bandwidth overhead, detracting from their primary role of executing transactions and maintaining network consensus. Moreover, consensus nodes only maintain live state and are not equipped to provide historical state proofs—limiting their usefulness for applications that require verifiable, point-in-time data.

These proof endpoints empower developers, auditors, and applications to independently verify the integrity of block and state data—strengthening trust and enabling decentralized verification without needing direct access to consensus infrastructure and without trusting any single node.

Reconnect Service

Block Nodes will expose a ReconnectService to which clients interested in maintaining live network details can sync to get the latest blocks and state.

New Consensus Nodes joining the consensus network will utilize ReconnectService to bootstrap and synchronize with the latest state and Hashgraph information so they can begin participating in consensus or data services. Additionally, it is possible for a consensus node to fall behind due to latency, load, or temporary outages. In this case ReconnectService would be used to catch them back. Block Nodes will also utilize the ReconnectService for similar reasons of catching up to latest network activity from existing full History Block Nodes.

Notably, today, Reconnect is handled by consensus nodes, which temporarily assume a “teacher” role, by sharing recent Hashgraph data and state snapshots. While effective, this approach imposes additional bandwidth and processing burdens on consensus node resources that are better dedicated to executing transactions and maintaining consensus integrity.

To support consensus network scalability and improve role specialization, Block Nodes will assume this teacher function. Block Nodes will act as reliable sources for Consensus Nodes or Block Nodes that need to bootstrap or resynchronize with the consensus network, reducing load on consensus infrastructure and improving overall recovery and onboarding performance.

APIs

The following Block Node Service protobuf API specifications are summaries. The full protobuf specifications can be found under this HIPs original protobuf assets.

Block Stream Publish Service

/**
 * Remote procedure calls (RPCs) for the Block-Node block stream publishing services.
 */
service BlockStreamPublishService {
    /**
     * Publish a stream of blocks.
     */
    rpc publishBlockStream(stream PublishStreamRequest) returns (stream PublishStreamResponse);
}

publishBlockStream response codes and their details are noted below

When the publisher is a consensus node it is important to expose error cases that suggest a block node is falling behind or failing to store blocks when expected.

Notably, a block node may consume a block stream from multiple sources e.g. multiple CNs. This approach can be used to increase the reliability and availability of consensus network data.

Note: If the publisher is not a Consensus Node a Block Node may receive a filtered block stream via the publishBlockStream endpoint. Filtering support is expanded upon in the Block Stream HIP 1056 and is characterized by the replacement of block items with hash values while maintaining the ability to carry out block and state proofs on the block information.

Block Stream Subscribe Service

/**
 * Remote procedure calls (RPCs) for the Block Node Stream subscribing services.
 */
service BlockStreamSubscribeService {
    /**
     * Subscribe to a stream of blocks.
     */
    rpc subscribeBlockStream(SubscribeStreamRequest) returns (stream SubscribeStreamResponse);
}

If an error occurs during streaming, the Block Node will terminate the stream with a Code response instead of the next BlockItemSet. Clients may choose to retry the stream from the last successfully received block or switch to a different Block Node for continued access.

subscribeBlockStream response codes and their details are noted below

Block Node Service

/**
 * Remote procedure calls (RPCs) for the Block Node Ancillary services.
 */
service BlockNodeService {
    /**
     * Read the status of this block node server.
     */
    rpc serverStatus(ServerStatusRequest) returns (ServerStatusResponse);
}

In the future a Block Node could expose which value-added services are enabled (e.g., filtering, proofs, streaming modes)

Block Access Service

/**
 * Remote procedure calls (RPCs) for the Block Node block services.
 */
service BlockAccessService {
    /**
     * Read a single verified block from the block node.
     */
    rpc getBlock(BlockRequest) returns (BlockResponse);
}

getBlock response codes and their details are noted below

State Service

/**
 * Remote procedure calls (RPCs) for the Block Node State snapshot
 * and query services.
 */
service StateService {
    /**
     * Read a state snapshot from the block node.
     */
    rpc stateSnapshot(StateSnapshotRequest) returns (StateSnapshotResponse);
}

stateSnapshot response codes and their details are noted below

Proof Service

/**
 * Remote procedure calls (RPCs) for the Block Node block contents proof
 * and state proof query services.
 */
service ProofService {
    /**
     * Request a block contents proof for a given block from the block node.
     */
    rpc getBlockContentsProof(BlockContentsProofRequest) returns (BlockContentsProofResponse);

    /**
     * Request a state proof for a given state item and block from the block node.
     */
    rpc getStateProof(StateProofRequest) returns (StateProofResponse);
}

Protobuf Schema Management

Block Nodes are responsible for streaming and parsing Block Stream messages encoded in Protocol Buffers (protobuf), as defined in the hiero-consensus-node repository. While protobuf offers a structured and extensible format for communication, there are specific scenarios that require careful handling by the Block Node to ensure stream integrity and resilience:

1. Protobuf Version Upgrades: Protocol Buffers are designed with built-in forward and backward compatibility. As a result, versioning the block stream schema is generally unnecessary. Block Nodes must be capable of processing older and newer message formats gracefully, ignoring unknown fields while continuing to verify and store the stream contents reliably.

2. Stream Pauses Due to Consensus Node (CN) Upgrades: Consensus nodes periodically undergo coordinated software upgrades, during which data streams may temporarily pause. Block Nodes should anticipate an end-of-stream signal during these events and handle the interruption gracefully without impacting downstream services.

3. Missing Block Proofs: Each block in the stream—excluding certain record file block items—is typically terminated with a block proof, providing cryptographic assurance that the block was verified by the consensus network. If a block proof is absent for an extended period, this may indicate that the CN has fallen behind, is unable to compute the proof, or is encountering an ISS (Inconsistent State Signature). In such cases, the Block Node should will not immediately terminate the connection, rather it will only terminate when a clear case described by the protocol is encountered. In the case of a connection termination Subscriber connections actively receiving block items may be closed after a configurable timeout. To aid debugging of the stream disruption Block Nodes could persist partial data (e.g., current and previous block contents).

4. Delayed Block Proofs and Cascade Proofs: In some cases, a delayed block proof may arrive indirectly through a cascade proof, where the block proof signature is from a later block that retroactively verifies the block through a chain of prior block hashes. Block Nodes must be capable of recognizing and validating such proofs to maintain a complete and verifiable block history. It is important to keep clear that no block header will be sent for block N+1 until the block proof for N is sent; this is invariant. A delayed proof delays all subsequent blocks as well. Further, the block proof for block N+1 does not prove block N; it is only the signatures gathered by consensus for Block N+1 that are used to build the block proof for block N (and that block proof is still sent for block N, not N+1).

gantt  
    title "Cascade Proof" timing diagram  
    %% We just need order, not days, so (mis)use milliseconds for the times  
    dateFormat SSS  
    axisFormat %L  
    tickInterval 5millisecond  
    section Consensus Node  
      Block 9 Produced :active, 002, 012  
      Block 9 Send :active, 004, 028  
      Block 9 Gather Signatures (fail) :done, 012, 016  
      Block 10 Produced :active, 012, 022  
      Block 10 Gather Signatures :done, 022, 026  
      Block 9 Craft Cascade Proof :done, 026, 027  
      Block 9 Send Proof :active, 027, 028  
      Block 10 Craft Proof :done, 027, 029  
      Block 10 Send :active, 028, 032  
      Block 10 Send Proof :active, 032, 034  
     section BlockNode  
      Block 9 Receive :active, 002, 028  
      Block 9 Verify :active, 028, 029  
      Block 9 Acknowledge :milestone, 030, 030  
      Block 10 Receive :active, 028, 032  
      Block 10 Verify :active, 032, 033  
      Block 10 Acknowledge :milestone, 033, 033 

Communication Protocol

A protocol for communication between Consensus Nodes and Block Nodes is essential to ensure the reliable and efficient processing of consensus output. To facilitate communication from Consensus Node(s).

publishBlockStream Communication Protocol

A summarized handshake of communication between a publisher and BN is as follows

• A publisher will send a batch of items starting with a BlockHeader on connection
• A block node will accept the stream if it is the next block or the Block Node has no cache of previous blocks.
  • If the block is less than the last known block, the block node will respond with a DuplicateBlock response including details of the last known block.
  • If the block is greater than the last known block, the block node will respond with a Behind response including details of the last known block. A publisher must send either an earlier block or an EndStream in response. If an an EndStream is sent by the publisher it must include its earliest known block to signal to the Block Node how large of a catch-up range it must resolve. In this case the Block Node may implement a backfill path from another block node to resolve gaps in blocks, where applicable.
• During streaming errors may occur from either side.
  • If a Publisher detects an error it must send an EndStream response instead of the next BlockItem. A Block Node will drop incomplete blocks from that Publisher.
  • If a Block Node detects an error it will send an EndOfStream response to all publishers specifying the latest verified and persisted block. A publisher may start a new stream and resume after the indicated block. In the case of repeated errors, the publishers may apply exponential back-off.

sequenceDiagram
  participant Publisher
  participant BlockNode
  participant AnotherBlockNode

  loop Stream one complete block
    Publisher->>BlockNode: Connect and send block header with block number N
    alt Multiple Publishers Active
      Note right of Publisher: Continue with Multi-Publisher Extension
    else
      Note right of Publisher: Continue with base protocol
    end
    Note over BlockNode: Block-Node checks block number N
    alt N == last known verified block number + 1
      BlockNode-->>Publisher: Accept and start streaming
    else N < last known verified block number
      BlockNode-->>Publisher: Respond with "DuplicateBlock" (includes last available block L)
      Publisher-->>BlockNode: Send new block header from block L+1 or send EndStream and retry
      Note over Publisher: Reconnect to consensus network, if needed
    else N > last known verified block number + 1
      BlockNode-->>Publisher: Respond with "Behind" (includes last known block L)
      Publisher-->>BlockNode: Send from block L+1 or send EndStream and retry with exponential backoff
      Note over Publisher: Includes earliest and latest available blocks with EndStream
      Note over BlockNode: Needs to catch up from another Block-Node
    end
    critical Validate latest streamed block
      alt Block is verified and persisted
        BlockNode-->>Publisher: Send `BlockAcknowledgement` with block number N
        Note over Publisher: Continue with next block header
      else Block fails verification
        BlockNode-->>Publisher: Send `EndOfStream` "Bad Block Proof" with block number L
        Note over Publisher: End connection and resume stream from block N to the same or a different block node
      else Block fails to persist
        BlockNode-->>Publisher: Send `EndOfStream` "Persistence Failed" with block number L
        Note over Publisher: Mark block node "not healthy" and connect to a different block node.
      end
    end
  end

  Note over Publisher,BlockNode: During this "catch up" Publisher will continue to occasionally<br/>connect and send a block header with the latest block number N
  loop until latest available block number matches next publisher block number
    par
      BlockNode->>AnotherBlockNode: query status API for latest available block.
      Note over BlockNode: Attempting to catch up
    and
      alt Last available block ≥ N
        BlockNode->>AnotherBlockNode: Request blocks from L+1 to last available block
        Note over BlockNode: Catching up before next Publisher connection
      else Last available block < N
        BlockNode->>AnotherBlockNode: Request stream from L+1 onward or find another Block-Node
      end
    end
  end

sequenceDiagram
    participant Publisher
    participant BlockNode
    participant Subscriber

    Note over Publisher,BlockNode: An error occurs during streaming

    alt Publisher detects an error
        Publisher-->>BlockNode: Send EndStream with error code
        BlockNode-->>BlockNode: Drop in-progress unproven block from Publisher
        alt No remaining active incoming streams
            BlockNode-->>Subscriber: Send Code ("not available")
            BlockNode-->>BlockNode: Await restarted stream
        else Other incoming streams active
            BlockNode-->>Subscriber: Continue streaming from other sources
            Publisher-->>BlockNode: Publisher initiates a new stream after handling the error
        end
    else BlockNode detects an error
        BlockNode-->>Publisher: Send EndOfStream response with error code
        Publisher-->>BlockNode: Retry publishing with exponential backoff
        Note over Publisher: May connect to alternate Block-Node
        BlockNode-->>Subscriber: Send Code with error code "not available"
        Note over Subscriber: Should resume streaming from another Block-Node
        BlockNode-->>BlockNode: Recover or await manual recovery
    else BlockNode receives a `BlockHeader` before<br/>receiving a `BlockProof` for the current block
        BlockNode-->>BlockNode: Drop the current in-progress block
        BlockNode-->>BlockNode: Treat the BlockHeader as the start of a new block
        alt New block header is for the "next" block
            BlockNode-->>Publisher: Continue with "standard" flow.
        else New block header is for an earlier block
            BlockNode-->>Publisher: Send `DUPLICATE_BLOCK` and continue with "standard" flow
        else New block header is for a "future" block
            BlockNode-->>Publisher: Send `BEHIND` and continue with "standard" flow
        end
    end

subscribeBlockStream Communication Protocol

An overview of communication between a Block Node and a subscriber is as follows:

1. A client initiates a subscription request, specifying:
   • A block start (required).
   • A block end (required, may be uint64_max to indicate “forever”).
2. The Block Node validates the request:
   • If the requested start block is earlier than available data, it responds with NOT_AVAILABLE.
   • If the end block is set to uint64_max, the stream is treated as open-ended, continuing until:
     • The client disconnects,
     • The Block Node enforces a streaming limit,
     • A network communication error occurs, or
     • The Block Node restarts.

Backwards Compatibility

Block Nodes propose to completely replace the existing cloud storage buckets and replace the record file format with the block stream format. All consumers of record stream data from the existing cloud storage buckets will need to change the mechanism of access, change the mechanism of payment, and adjust any processing logic to process block stream data.

With consideration for Hiero transaction protobuf type formats - the block node will support the new Block Stream format, which incorporates the existing transactional API formats by reference.

Security Implications

Block Nodes do not sign or co-sign transactions, nor do they participate in consensus. They do not hold custody of user assets and therefore are not custodial in nature.

To support authentication and monetization, each Block Node must possess at least one account on the Hiero network. This account enables identification by consensus nodes—particularly when block items are streamed directly—and facilitates the receipt of payments for services. Operators may optionally use multiple accounts to separate concerns such as authentication, metering, and billing.

In applicable configurations, Block Nodes will acknowledge receipt and verification of blocks back to the stream publisher (whether a Consensus Node or another Block Node). This feedback mechanism allows the publisher to track successful delivery and optionally implement back-pressure or rate control.

A Block Node may receive a block stream directly from a Consensus Node or indirectly from another Block Node. Because each block in the stream includes verifiable cryptographic proofs, the source of the stream does not affect data integrity—only latency, trust assumptions for availability, and potentially the service fees involved.

A publisher may also explore additional network protocols in their deployment architecture to increase trust and reliability of the target of their stream. Examples of this include TLS to provide additional authentication, encryption and data integrity checks for the block streams data being transmitted. Similarly Block Node operators may consider additional network protections such as rate limiting in their deployment depending on business justification.

Block Nodes may also implement targeted metrics that observe the nature and latency of blocks received from Consensus Nodes and provide actionable details to operators.

How to Teach This

To effectively educate and inform users about block node operation, comprehensive technical documentation, blogs, and webinars will be essential. Technical documentation will provide detailed and in-depth explanations of operation modes, usage, and best practices, ensuring that developers and mirror node operators can fully understand and transition to block stream consumption from a block node as well as block node hosting.

Blogs will offer more accessible and engaging content, highlighting use cases, real-world applications, and the benefits of a block node, catering to a broader audience of Hiero stakeholders. Webinars will serve as interactive platforms for live demonstrations, Q&A sessions, and expert insights, enabling participants to gain a deeper understanding through direct engagement with subject matter experts.

Reference Implementation

Rejected Ideas

BN to CN staking as a requirement for a CN before streaming to a BN.

It was suggested that to help incentivize long term block nodes that a BN would stake some minimum amount of HBAR to a CN. In which upon reward of the full staking period a BN would recuperate staking rewards but also additional reward for offering DA

BN to CN staking as a mechanism to ensure long term Date Availability (DA)

It was suggested that to help incentivize long term block nodes that staked and consumed a stream for at least the staking period would receive an additional reward for offering DA

App to BN allowances to pay for API usage

It was suggested that one mechanism of paying in advance would be for a client such as a BN or MN or app to first offer a BN an allowance of some amount of HBAR. The BN would then periodically debit from the allowance to pay itself after responding to a clients calls. The issue was there was a fear that the client to rescind the allowance after time and a BN would be 1 or 2 blocks in time off of the accurate allowances which could result in services offered for free if the client was being malicious. Additionally, there were possible write-amplification concerns where a poorly implemented debit process could create significant additional transactions every block, resulting in a large number of unnecessary transfers.

BlockItem Service

Returning a single request BlockItem seemed to not be a valuable service out of the gate. Especially without the ability to cleanly identify an item it doesn’t seem worthwhile for a BN to return a BlockItem vs a Block.

Periodic CN provided state snap shots

With record streams the CN creates a state snapshot every 15 mins. A question was asked if this should be exposed to allow BNs to start up or compare state periodically. However, this would add additional low usage process on the CN. It would also defeat the goal of removing the bandwidth, processing, and complexity of managing state snapshot transfers from the CN. Block Nodes that manage live state or produce state snapshots require a state snapshot to start up if not active since genesis for that network. That snapshot should, however, be transferred manually (either from cloud storage or another block node). The consensus node will continue to maintain state snapshot for local backup only and will be short-lived ephemeral data (if stored at all). A running block node that requires a state snapshot for some reason should retrieve it from another block node.

Gossiping Block Node

Open Issues/Ideas/Tasks

• Add diagram showing BN system location in overall Hiero architecture in Rationale section
  • Highlight CN(s) -> BN -> MN + block stream clients
• Flesh out Proof Service response components, Noting additional proof types
  • Block Proof
  • HinTS Proof
• Expand Reconnect Service
  • Speak to the need and value of BN provided reconnect vs CN
  • Highlight BN -> BN reconnect
  • Note details of what reconnect will provide i.e. latest state + x
• Q: Does the block node require or rely on a transmission of full state from a CN? If so what’s the contract between nodes here? Previously the CN output state every 15 mins
• Improve Block Stream Schema section regarding streaming interruptions
  • Protobuf version upgrades - Expand section and confirm
  • Pause in stream due to CN upgrades - Confirm and improve explanation
  • Pauses in stream due to no Block Proof - Confirm and improve explanation
• Flesh out Single entity state query e.g. return account 0.0.x
• Complete communication overview with potential diagrams

References

A collections of URLs used as references through the HIP.

Copyright/license

This document is licensed under the Apache License, Version 2.0 – see LICENSE or (https://www.apache.org/licenses/LICENSE-2.0)

Citation

Please cite this document as: