Skip to content

About

New Block Node services

Topics

Resources

Code of conduct

Contributing

Security policy

Stars

38 stars

Watchers

7 watching

Forks

Latest commit

 

History

1,693 Commits

Folders and files

NameName
Last commit message
Last commit date
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 

Hiero Block Node

PR Checks E2E Test Suites codecov

OpenSSF Scorecard CII Best Practices Latest Version Made With Documentation Discord License

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.

Block Node Network Architecture


Documentation

Full documentation is organized at docs.hiero.org/block-node-home.

Where do I start?

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.


Try it now - no installation required

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/releases

Step 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-proto

Step 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/serverStatus

A 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 locally (~5 minutes)

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=25
git clone https://github.com/hiero-ledger/hiero-block-node.git
cd hiero-block-node
./gradlew :app:startDockerContainer

Once 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/serverStatus

See the Docker Compose Quickstart for the full stack details, ports, Grafana dashboards, and how to simulate an incoming block stream.


Production Deployment

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/.


Building from Source

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)

Repository layout

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)

Key Documentation

Concepts and reference

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

Operations

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

FAQs

Topic Link
Operator FAQ Operator FAQ
Integration FAQ Integration FAQ

Releases

Releases follow semantic versioning. Each release is published to:

  • GitHub Releases - release notes and a pre-compiled block-node-protobuf-<VERSION>.tgz proto bundle (required for grpcurl and SDK integrations)
  • GitHub Container Registry - OCI application images
  • oci://ghcr.io/hiero-ledger/hiero-block-node/block-node-server - Helm chart (OCI format)

Community and Support

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.


Related Projects

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

Contributing

All contributions are welcome - bug fixes, features, and documentation improvements.

  1. Read the Contributing Guide for branch naming, PR format, and review requirements.
  2. Read the Hiero Contributing Guidelines for the overall project.
  3. Open or pick up an issue before starting work.

PRs require at least two approvals from the @hiero-ledger/hiero-block-node-committers team.

Security

To report a security vulnerability, follow the Hiero security disclosure process. Do not open a public issue.

Code of Conduct

Hiero uses the Linux Foundation Decentralised Trust Code of Conduct.

License

Apache License 2.0

About

New Block Node services

Topics

Resources

Code of conduct

Contributing

Security policy

Stars

38 stars

Watchers

7 watching

Forks

Releases

Packages

Used by

Contributors

Languages