Hanzo Nchain

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

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?

Multi-protocol -- Single operator handles Lux, Ethereum, Bitcoin, Cosmos, Solana, Substrate, and generic nodes

Composable CRDs -- Network (top-level composer) creates NodeClusters, Chains, Indexers, Explorers, Bridges, and Gateways

Protocol drivers -- Pluggable Driver interface generates container commands, env vars, volumes, health checks per chain

Production features -- Rolling canary upgrades, seed restore from snapshots, automated snapshot schedules, startup gates, KMS secret sync

K8s-native -- Standard kubebuilder patterns, leader election, health/readiness probes, secure metrics

Tech Stack

Language: Go 1.25

Framework: kubebuilder / controller-runtime v0.23

CRD API: nchain.hanzo.ai/v1alpha1

Image: ghcr.io/hanzoai/nchain:latest

Binary: manager (single binary operator)

When to use

Deploying blockchain validator/fullnode/archive clusters on Kubernetes

Managing multi-chain networks (Lux subnets, Ethereum L2s, Cosmos zones)

Running block explorers, indexers, and API gateways alongside nodes

Automating chain data snapshots and seed-based bootstrap

Operating cross-chain bridges under K8s lifecycle management

Hard requirements

Kubernetes cluster with CRD support (v1.28+)

controller-gen for CRD manifest generation

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

hanzo/hanzo-hke.md - Managed Kubernetes Engine (placeholder)

hanzo/hanzo-platform.md - PaaS platform for service deployment

hanzo/hanzo-cloud.md - Cloud dashboard and console

On this page