A Block Node is a server that collects, verifies, and distributes the on-chain record of everything that happens on a Hiero network. Hiero is the open-source project under the Linux Foundation Decentralised Trust that powers the Hedera public network.
This repository is the implementation of HIP-1081. The Block Node receives the block stream produced by Consensus Nodes (defined in HIP-1056), verifies each block's cryptographic integrity, stores the verified blockchain, and distributes blocks to Mirror Nodes, other Block Nodes, and applications via gRPC streaming APIs. Block Nodes are the new decentralized data layer replacing centralized cloud storage - and are deployed in production on Hedera mainnet and testnet.
Full documentation is organized at docs.hiero.org/block-node-home.
| I am... | Read first | Then... |
|---|---|---|
| New to Block Nodes - want to understand what they are | Block Node Introduction | Block Node Overview |
| A Tier 1 operator - Council/trusted, connecting directly to a Consensus Node | Block Node Overview | Production Deployment Guide |
| A Tier 2 operator - permissionless, connecting to an existing Block Node | Block Node Overview | Single-Node K8s Deployment |
| A developer or integrator - want to build on Block Node APIs | Block Node Introduction | gRPC API Quickstart |
| A Mirror Node operator - migrating from record files | Record Stream to Block Stream Migration | Connecting a Mirror Node |
| A Consensus Node operator - pairing my CN with a Block Node | CN to Block Node Configuration | On-Chain Registration |
| Evaluating locally - want a Block Node running in minutes | Docker Compose Quickstart | gRPC API Quickstart |
| A contributor - want to fix bugs or add features | Contributing Guide | Architecture Overview |
Not sure if you are Tier 1 or Tier 2? Tier 1 nodes connect directly to Consensus Nodes and require Hiero Governing Council membership or authorization as a trusted network partner. Tier 2 nodes are permissionless - anyone can run one by connecting to an existing Block Node upstream. See Block Node Overview for the full breakdown.
Block Nodes are live on mainnet, testnet, and previewnet. Query them directly with grpcurl - no API key required.
Step 1 - Install grpcurl:
brew install grpcurl # macOS
# Linux: download from https://github.com/fullstorydev/grpcurl/releasesStep 2 - Download the proto bundle (required for all grpcurl calls):
BUNDLE_URL=$(curl -s https://api.github.com/repos/hiero-ledger/hiero-block-node/releases/latest \
| grep "browser_download_url.*block-node-protobuf.*tgz" \
| head -1 | cut -d '"' -f 4)
mkdir -p ~/bn-proto
curl -sL "$BUNDLE_URL" | tar -xzC ~/bn-protoStep 3 - Query testnet server status:
grpcurl -plaintext -emit-defaults \
-import-path ~/bn-proto \
-proto block-node/api/node_service.proto \
-d '{}' \
s01.test.blk.sgp.lat.ope.eng.hashgraph.io:40982 \
org.hiero.block.api.BlockNodeService/serverStatusA successful response looks like this (block numbers will differ):
{
"firstAvailableBlock": "0",
"lastAvailableBlock": "2488393",
"onlyLatestState": true,
"nextExpectedBlock": "2488394"
}Available public endpoints:
| Network | Sample endpoint | Status port |
|---|---|---|
| Previewnet | lfh01.previewnet.blocknode.hashgraph-devops.com |
40982 |
| Testnet | s01.test.blk.sgp.lat.ope.eng.hashgraph.io |
40982 |
| Mainnet | see gRPC API Quickstart | 40982 |
Each network has multiple endpoints. Public Block Node services each run on their own port: subscribe on 40980, block access on 40981, status on 40982, health (HTTP) on 40983.
Block Node APIs are gRPC-based and work with any gRPC-compatible language - Java, Go, Python, Node.js, Rust, and more. The proto files in the bundle above are all you need to generate a client in your language of choice.
See the gRPC API Quickstart for the full endpoint list and complete API call examples including getBlock, subscribeBlockStream, and block proofs.
Run a Block Node on your workstation with a full observability stack (Prometheus, Grafana, Loki). This uses the developer image and is for local testing only - not for mainnet or testnet operation.
Prerequisites: Java 25 and Docker 24+ with Docker Compose v2.
brew install --cask temurin@25 # macOS - install Java 25 (Temurin)
# Linux / Windows: download from https://adoptium.net/temurin/releases/?version=25git clone https://github.com/hiero-ledger/hiero-block-node.git
cd hiero-block-node
./gradlew :app:startDockerContainerOnce running, verify the node is healthy. The proto bundle from Step 2 above is also required here (the local setup uses a single port 40840 for all gRPC services, unlike the per-service ports of public endpoints):
grpcurl -plaintext -emit-defaults \
-import-path ~/bn-proto \
-proto block-node/api/node_service.proto \
-d '{}' \
localhost:40840 \
org.hiero.block.api.BlockNodeService/serverStatusSee the Docker Compose Quickstart for the full stack details, ports, Grafana dashboards, and how to simulate an incoming block stream.
For production and staging environments, the Block Node is deployed on Kubernetes using the Helm chart published at oci://ghcr.io/hiero-ledger/hiero-block-node/block-node-server.
| Guide | Use case |
|---|---|
| Production Deployment Guide | Full Tier 1 production checklist - prerequisites, install, go-live, steady-state |
| Solo Provisioner (GCP VM) | Provisions a GCP VM, installs Kubernetes, and deploys the Helm chart in one flow |
| Bare Metal / Cloud VM | Bring-your-own Kubernetes cluster - Tier 1 or Tier 2 |
| Network Ports and Protocols | Firewall and security group rules required before any deployment |
| Hardware Specifications | CPU, RAM, NVMe, and network requirements by deployment profile |
| On-Chain Registration (HIP-1137) | Required step for Tier 1 operators after deployment |
The Helm chart source is in charts/block-node-server/.
Prerequisites:
- Java 25 (Temurin recommended) - needed to run Gradle
- Docker 24+ with Docker Compose v2 (for integration tests and the local run target)
- IntelliJ IDEA (recommended for development)
The Gradle wrapper is included - no separate Gradle installation required.
./gradlew assemble # compile only - fast feedback during development
./gradlew build # compile, test, and check - run before opening a PR
./gradlew spotlessApply # auto-format (required before any commit)| Directory | What it contains |
|---|---|
block-node/ |
Core Block Node application and plugin modules |
common/ |
Shared utilities, types, and literals used across modules |
tools-and-tests/simulator/ |
Block stream simulator for local testing - docs |
tools-and-tests/tools/ |
Command-line tools for working with block stream files - docs |
tools-and-tests/suites/ |
End-to-end test suites |
charts/ |
Helm chart for Kubernetes deployment |
docs/ |
Source for all documentation (synced to docs.hiero.org) |
| Topic | Link |
|---|---|
| What is a Block Node? | Introduction - Overview |
| Architecture and internals | Architecture Overview - Data Flow - Plugin System |
| Configuration reference | Configuration |
| Metrics and monitoring | Metrics |
| Logging reference | Logging |
| Mirror Node integration | Mirror Node Integration - Record Stream Migration |
| Glossary | Glossary |
| Topic | Link |
|---|---|
| Upgrading and resetting | Resetting and Upgrading |
| Disaster recovery | Disaster Recovery |
| Wrapped Record Block (WRB) cutover preparation | Preparing for WRB Cutover |
| Testing a deployed node | Testing with the Simulator |
| Troubleshooting | Troubleshooting Guide |
| Getting help | Getting Help |
| Topic | Link |
|---|---|
| Operator FAQ | Operator FAQ |
| Integration FAQ | Integration FAQ |
Releases follow semantic versioning. Each release is published to:
- GitHub Releases - release notes and a pre-compiled
block-node-protobuf-<VERSION>.tgzproto bundle (required forgrpcurland SDK integrations) - GitHub Container Registry - OCI application images
oci://ghcr.io/hiero-ledger/hiero-block-node/block-node-server- Helm chart (OCI format)
| Channel | Use for |
|---|---|
| Hiero Discord | General questions, community discussion |
| GitHub Discussions | Design questions, proposals, longer-form Q&A |
| GitHub Issues | Bug reports, documentation improvements |
For production incident escalation, see the Getting Help guide.
Block Node is one component in the Hiero ecosystem:
| Project | Role |
|---|---|
| hiero-consensus-node | Produces the block stream that Block Node receives and verifies |
| hiero-mirror-node | Downstream consumer of Block Node data - provides REST APIs and analytics |
| hiero-sdk-java / js / go / python | Client SDKs for building applications on Hiero |
| hiero-docs | Source for the docs.hiero.org documentation site |
All contributions are welcome - bug fixes, features, and documentation improvements.
- Read the Contributing Guide for branch naming, PR format, and review requirements.
- Read the Hiero Contributing Guidelines for the overall project.
- Open or pick up an issue before starting work.
PRs require at least two approvals from the @hiero-ledger/hiero-block-node-committers team.
To report a security vulnerability, follow the Hiero security disclosure process. Do not open a public issue.
Hiero uses the Linux Foundation Decentralised Trust Code of Conduct.