hanzo-nchain

Nchain is a Kubernetes operator for deploying and scaling blockchain nodes.

Hanzo Nchain - Composable Blockchain Node Infrastructure Operator

Category: Hanzo Ecosystem Related Skills: hanzo/hanzo-hke.md, hanzo/hanzo-platform.md, hanzo/hanzo-cloud.md

Overview

Nchain is a Kubernetes operator for deploying and scaling blockchain nodes. Built with kubebuilder and controller-runtime, it defines custom resources (CRDs) for managing multi-protocol blockchain infrastructure declaratively. Supports Lux, Ethereum, Bitcoin, Cosmos, Solana, and Substrate via a pluggable protocol driver interface.

Why Nchain?

Tech Stack

When to use

Hard requirements

  1. Kubernetes cluster with CRD support (v1.28+)
  2. controller-gen for CRD manifest generation
  3. Go 1.25+ for building from source

Quick reference

| Item | Value | |------|-------| | Module | github.com/hanzoai/nchain | | Go version | 1.25 | | API group | nchain.hanzo.ai/v1alpha1 | | Image | ghcr.io/hanzoai/nchain:latest | | Default branch | main | | Health probe | :8081/healthz | | Readiness probe | :8081/readyz | | Leader election ID | nchain.hanzo.ai | | Repo | github.com/hanzoai/nchain |

One-file quickstart

Deploy the operator

# Build and push
make docker-push IMG=ghcr.io/hanzoai/nchain:latest

# Generate CRDs and deploy
make deploy

Create a Lux devnet

apiVersion: nchain.hanzo.ai/v1alpha1
kind: NodeCluster
metadata:
 name: lux-devnet-validators
 namespace: lux-devnet
spec:
 protocol: lux
 networkID: "3"
 replicas: 5
 role: validator
 image:
 repository: ghcr.io/luxfi/node
 tag: v1.23.23
 ports:
 rpc: 9650
 p2p: 9651
 storage:
 storageClassName: do-block-storage
 size: 50Gi
 resources:
 requests:
 cpu: "1"
 memory: 2Gi
 limits:
 cpu: "2"
 memory: 4Gi
 consensus:
 algorithm: snow
 params:
 sybilProtectionEnabled: false
 allowPrivateIPs: true

Create a full Network (composer)

apiVersion: nchain.hanzo.ai/v1alpha1
kind: Network
metadata:
 name: lux-mainnet
spec:
 protocol: lux
 networkID: "1"
 clusters:
 - name: validators
 spec:
 replicas: 5
 role: validator
 image:
 repository: ghcr.io/luxfi/node
 tag: v1.23.23
 gateways:
 - name: api
 spec:
 replicas: 2
 nodeClusterRef: lux-mainnet-validators
 autoRoutes: true
 ingress:
 enabled: true
 hosts:
 - api.lux.network
 tls: true

Core Concepts

CRD Hierarchy

Network (top-level composer)
 |-- NodeCluster Stateful node pods (validator, fullnode, archive, bootnode, sentry)
 |-- Chain Blockchain/subnet/L2 definitions (genesis, chainID, VMID)
 |-- Indexer Block indexing services
 |-- Explorer Block explorer UIs (Blockscout, etc.)
 |-- Bridge Cross-chain bridge relayers
 |-- Gateway API gateway / RPC load balancer with rate limits
 |-- Cloud Cloud management platform (bootnode API + web UI)

Controllers (8 reconcilers)

| Controller | CRD | Purpose | |-----------|-----|---------| | NodeClusterReconciler | NodeCluster | Manages StatefulSets for node pods | | ChainReconciler | Chain | Tracks blockchain lifecycle and block height | | IndexerReconciler | Indexer | Deploys and configures indexing services | | ExplorerReconciler | Explorer | Deploys block explorer instances | | BridgeReconciler | Bridge | Manages cross-chain bridge relayers | | GatewayReconciler | Gateway | Deploys API gateway with auto-routing and rate limits | | NetworkReconciler | Network | Top-level composer creating all child resources | | CloudReconciler | Cloud | Cloud management platform deployment |

Protocol Drivers

Each protocol implements the Driver interface:

type Driver interface {
 Name() string
 DefaultImage() string
 BuildCommand(spec *NodeClusterSpec) (command, args []string)
 BuildEnv(spec *NodeClusterSpec) []corev1.EnvVar
 HealthEndpoint(spec *NodeClusterSpec) (path string, port int32)
 DefaultPorts() PortConfig
 RecommendedResources(role string) (requests, limits corev1.ResourceList)
 // ... plus volumes, init containers, config maps
}

| Protocol | File | Default Image | |----------|------|---------------| | Lux | internal/protocol/lux.go | ghcr.io/luxfi/node | | Ethereum | internal/protocol/ethereum.go | Geth-based | | Bitcoin | internal/protocol/bitcoin.go | Bitcoin Core | | Cosmos | internal/protocol/cosmos.go | Cosmos SDK | | Solana | internal/protocol/solana.go | Solana validator | | Generic | internal/protocol/generic.go | User-specified |

NodeCluster Roles

| Role | Description | |------|-------------| | validator | Full consensus participation (default) | | fullnode | Validates but doesn't propose blocks | | archive | Full historical state retention | | bootnode | Network bootstrap / peer discovery | | sentry | DDoS protection proxy for validators |

Directory structure

github.com/hanzoai/nchain/
 Dockerfile # Multi-stage build (distroless)
 Makefile # build, test, manifests, docker-build, deploy
 api/v1alpha1/
 chain_types.go # Chain CRD (blockchain/subnet/L2)
 nodecluster_types.go # NodeCluster CRD (node pod management)
 network_types.go # Network CRD (top-level composer)
 bridge_types.go # Bridge CRD (cross-chain relayer)
 explorer_types.go # Explorer CRD (block explorer)
 gateway_types.go # Gateway CRD (API gateway)
 indexer_types.go # Indexer CRD (block indexing)
 cloud_types.go # Cloud CRD (management platform)
 common_types.go # Shared types (ports, storage, consensus, etc.)
 groupversion_info.go # API group registration
 zz_generated_deepcopy.go # Auto-generated DeepCopy methods
 cmd/
 main.go # Operator entrypoint (registers all 8 controllers)
 config/
 crd/ # Generated CRD YAML manifests
 samples/
 lux-mainnet.yaml # Full Lux mainnet Network example
 nodecluster-standalone.yaml # Standalone NodeCluster + Gateway
 ethereum-node.yaml # Ethereum node example
 cloud-multi-brand.yaml # Multi-brand Cloud deployment
 internal/
 controller/
 nodecluster_controller.go # NodeCluster reconciler
 chain_controller.go # Chain reconciler
 network_controller.go # Network reconciler
 bridge_controller.go # Bridge reconciler
 explorer_controller.go # Explorer reconciler
 gateway_controller.go # Gateway reconciler
 indexer_controller.go # Indexer reconciler
 cloud_controller.go # Cloud reconciler
 helpers.go # Shared controller utilities
 predicates.go # Event filter predicates
 manifests/
 builder.go # K8s manifest builder (StatefulSet, Service, etc.)
 labels.go # Label helpers
 mutate.go # CreateOrUpdate mutation helpers
 protocol/
 driver.go # Driver interface definition
 registry.go # Protocol driver registry
 lux.go # Lux protocol driver
 ethereum.go # Ethereum protocol driver
 bitcoin.go # Bitcoin protocol driver
 cosmos.go # Cosmos protocol driver
 solana.go # Solana protocol driver
 generic.go # Generic fallback driver
 status/ # Status tracking utilities

Troubleshooting

| Issue | Cause | Solution | |-------|-------|----------| | CRDs not found | Manifests not applied | Run make manifests && make deploy | | Leader election contention | Multiple operator replicas | Only one replica should run, or enable --leader-elect | | Nodes stuck in Pending | Missing StorageClass | Verify storageClassName exists in cluster | | Protocol not recognized | Invalid protocol enum | Must be one of: lux, ethereum, bitcoin, cosmos, substrate, generic | | Snapshot restore fails | S3 endpoint unreachable | Check seedRestore.objectStoreURL and network policies |

Related Skills

Last Updated: 2026-03-13 Category: Hanzo Ecosystem Related: kubernetes, operator, blockchain, lux, ethereum, bitcoin, cosmos, solana, infrastructure Prerequisites: Kubernetes 1.28+, Go 1.25+, controller-gen