feat: handshake-node chart

Signed-off-by: Tripura Repalle <tripura@blinklabs.io>

Author: tripura-repalle

charts/handshake-node/Chart.yaml

@@ -5,7 +5,7 @@ description: |
   full node from Blink Labs. This is distinct from the JavaScript hsd chart.
 type: application
 version: 0.1.0
-appVersion: "0.1.1-rc1"
+appVersion: "0.2.0-rc1"
 # 1.27+ is required for the StatefulSet .spec.persistentVolumeClaimRetentionPolicy
 # field that the chart renders by default. Older clusters silently drop the field.
 kubeVersion: ">=1.27.0-0"

charts/handshake-node/README.md

@@ -22,9 +22,26 @@ PersistentVolumeClaim mounted at `/home/handshake/.handshake-node`.
 Security-relevant defaults:
 
 - The container runs as the non-root `handshake` user baked into the upstream
-  image with `runAsNonRoot: true`, all Linux capabilities dropped, no
-  privilege escalation, `readOnlyRootFilesystem: true`, and the
-  `RuntimeDefault` seccomp profile.
+  image (UID 100 / GID 101), pinned numerically via `runAsUser` /
+  `runAsGroup` so kubelet can enforce `runAsNonRoot: true` without resolving
+  the image's `/etc/passwd`. All Linux capabilities are dropped, no privilege
+  escalation, `readOnlyRootFilesystem: true`, and the `RuntimeDefault`
+  seccomp profile.
+- An `init-chown-data` init container (busybox) fixes ownership of the
+  mounted PVC on every start. It drops all Linux capabilities and adds back
+  only `CAP_CHOWN` (to change owner/group) and `CAP_DAC_READ_SEARCH` (so
+  root can traverse the `0700` directories the daemon creates under the
+  data root on first start; without it, a restart of the pod would fail
+  with `Permission denied`). The container runs a selective
+  `find /home/handshake/.handshake-node \( -not -user <uid> -o -not -group <gid> \) -exec chown <uid>:<gid> {} +`
+  against the mount root, so only entries whose owner or group already
+  differ from the configured `runAsUser` / `runAsGroup` are touched. That
+  keeps the operation idempotent across restarts and cheap on a warm PVC,
+  and it never modifies file modes — the Brontide identity key's `0600`
+  survives, and a pre-populated `persistence.existingClaim` remains fully
+  readable by the non-root main container. `fsGroup` is deliberately not
+  used because kubelet's recursive `fsGroup` chmod adds group r/w to every
+  file, which the daemon rejects for its Brontide identity key.
 - The peer-to-peer Service is `ClusterIP` by default. Public exposure via
   `NodePort` or `LoadBalancer` is an explicit operator choice.
 - The authenticated TLS RPC listener (port `12037`) is not exposed unless
@@ -35,6 +52,10 @@ Security-relevant defaults:
 - The Prometheus metrics endpoint (`12039`) and Stratum server (`12040`) are
   disabled by default. When enabled they are kept on private `ClusterIP`
   Services.
+- Supported `network` values are `main` and `regtest`. The upstream
+  `handshake-node` binary does not implement `--testnet` or `--simnet`; the
+  chart rejects those values at render time to avoid a `CreateContainerError`
+  loop from an unknown flag.
 
 ## Prerequisites
 
@@ -160,6 +181,9 @@ stratum:
   # Optional. Derived from stratum.service.port + allowPublic when unset.
   # listen: ""
   allowPublic: true
+  # Required whenever stratum.enabled=true (even for private/loopback binds).
+  # handshake-node v0.2.0-rc1 refuses to start if --stratumlisten is set
+  # without --miningaddr.
   miningAddress: hs1qyourhandshakeaddress
   auth:
     existingSecret: handshake-node-stratum
@@ -168,10 +192,11 @@ stratum:
     type: ClusterIP
 ```
 
-Public exposure requires `stratum.allowPublic=true` and both
-`miningAddress` and `auth.existingSecret` (validated at render time). The
-Stratum Service is only rendered when `stratum.allowPublic=true` because
-loopback listeners cannot be reached through a ClusterIP.
+`stratum.miningAddress` is required whenever Stratum is enabled. Public
+exposure additionally requires `stratum.allowPublic=true` and
+`stratum.auth.existingSecret` (all validated at render time). The Stratum
+Service is only rendered when `stratum.allowPublic=true` because loopback
+listeners cannot be reached through a ClusterIP.
 
 ## Service exposure
 
@@ -195,6 +220,12 @@ service:
     type: NodePort
     port: 12038
     nodePort: 32038
+config:
+  extra:
+    # handshake-node does not derive its advertised address from the
+    # Service; when using NodePort, set EXTERNALIP to the routable
+    # "<node-ip>:<nodePort>" so peers can dial you back.
+    EXTERNALIP: "203.0.113.10:32038"
 ```
 
 ## Mainnet operations examples
@@ -204,7 +235,7 @@ Full mainnet node with private RPC, metrics enabled, and a beefier PVC:
 ```yaml
 network: main
 image:
-  tag: "0.1.1-rc1"
+  tag: "0.2.0-rc1"
 
 persistence:
   size: 400Gi
@@ -215,8 +246,8 @@ rpc:
   existingSecret: handshake-node-rpc
 
 config:
-  # Required whenever rpc.enabled=true. Substitute the Pod CIDR of the
-  # workloads that should be allowed to call RPC.
+  # Required whenever rpc.enabled=true. Substitute the observed client
+  # source CIDR (Pod CIDR unless CNI SNAT changes it to node IPs).
   rpcallowip: "<trusted-rpc-client-cidr>"
 
 metrics:
@@ -262,8 +293,8 @@ See [`values.yaml`](values.yaml) for the full list of tunables. Key knobs:
 | Key                              | Description                                                  | Default                              |
 | -------------------------------- | ------------------------------------------------------------ | ------------------------------------ |
 | `image.repository`               | Image name                                                   | `ghcr.io/blinklabs-io/handshake-node` |
-| `image.tag`                      | Image tag (never `latest`)                                   | `0.1.1-rc1`                          |
-| `network`                        | Handshake network: `main`, `regtest`, `simnet`, `testnet`    | `main`                               |
+| `image.tag`                      | Image tag (never `latest`)                                   | `0.2.0-rc1`                          |
+| `network`                        | Handshake network: `main`, `regtest`                         | `main`                               |
 | `persistence.size`               | PVC size                                                     | `200Gi`                              |
 | `persistence.storageClass`       | StorageClass name                                            | cluster default                      |
 | `rpc.enabled`                    | Enable authenticated RPC                                     | `false`                              |

charts/handshake-node/templates/_helpers.tpl

@@ -31,24 +31,54 @@ Chart name/version label.
 
 {{/*
 Handshake network selector. Fails template rendering for unsupported values so
-labels and daemon flags cannot silently disagree.
+labels and daemon flags cannot silently disagree. Restricted to the networks
+the upstream handshake-node image actually implements as CLI flags; testnet
+and simnet are rejected by the daemon and therefore not offered here.
 */}}
 {{- define "handshake-node.network" -}}
 {{- $n := default "main" .Values.network -}}
-{{- $valid := list "main" "regtest" "simnet" "testnet" -}}
+{{- $valid := list "main" "regtest" -}}
 {{- if not (has $n $valid) -}}
-{{- fail (printf "handshake-node: unsupported network %q. Supported: main, regtest, simnet, testnet." $n) -}}
+{{- fail (printf "handshake-node: unsupported network %q. Supported: main, regtest." $n) -}}
 {{- end -}}
 {{- $n -}}
 {{- end -}}
 
 {{/*
-Name of the headless Service backing the StatefulSet. Reserved suffix space
-keeps the resulting name within the 63-char DNS label limit even with a long
-fullnameOverride or release name.
+Suffix-aware component name. Truncates the fullname so the returned value
+stays within the 63-character DNS label limit even when a long release name
+or fullnameOverride is combined with a component suffix like "-p2p".
+Call as: include "handshake-node.componentName" (dict "ctx" . "suffix" "-p2p")
+*/}}
+{{- define "handshake-node.componentName" -}}
+{{- $ctx := .ctx -}}
+{{- $suffix := .suffix -}}
+{{- $max := int (sub 63 (len $suffix)) -}}
+{{- printf "%s%s" (include "handshake-node.fullname" $ctx | trunc $max | trimSuffix "-") $suffix -}}
+{{- end -}}
+
+{{/*
+Name of the headless Service backing the StatefulSet.
 */}}
 {{- define "handshake-node.headlessName" -}}
-{{- printf "%s-headless" (include "handshake-node.fullname" . | trunc 54 | trimSuffix "-") -}}
+{{- include "handshake-node.componentName" (dict "ctx" . "suffix" "-headless") -}}
+{{- end -}}
+
+{{/*
+Per-component Service names. Each reserves the suffix length so a maximum
+63-char fullname override still renders a valid Service name.
+*/}}
+{{- define "handshake-node.p2pName" -}}
+{{- include "handshake-node.componentName" (dict "ctx" . "suffix" "-p2p") -}}
+{{- end -}}
+{{- define "handshake-node.rpcName" -}}
+{{- include "handshake-node.componentName" (dict "ctx" . "suffix" "-rpc") -}}
+{{- end -}}
+{{- define "handshake-node.metricsName" -}}
+{{- include "handshake-node.componentName" (dict "ctx" . "suffix" "-metrics") -}}
+{{- end -}}
+{{- define "handshake-node.stratumName" -}}
+{{- include "handshake-node.componentName" (dict "ctx" . "suffix" "-stratum") -}}
 {{- end -}}
 
 {{/*
@@ -66,12 +96,15 @@ handshake_network: {{ include "handshake-node.network" . }}
 {{- end -}}
 
 {{/*
-Selector labels
+Selector labels. Deliberately excludes handshake_network because
+StatefulSet.spec.selector is immutable in Kubernetes; a network change on
+helm upgrade would fail with `spec: Forbidden`. name + instance already
+isolate the release. The network label is still exposed on general resource
+and pod metadata via handshake-node.labels for observability.
 */}}
 {{- define "handshake-node.matchLabels" -}}
 app.kubernetes.io/name: {{ include "handshake-node.name" . }}
 app.kubernetes.io/instance: {{ .Release.Name }}
-handshake_network: {{ include "handshake-node.network" . }}
 {{- end -}}
 
 {{/*

charts/handshake-node/templates/service-metrics.yaml

@@ -3,7 +3,7 @@
 apiVersion: v1
 kind: Service
 metadata:
-  name: {{ include "handshake-node.fullname" . }}-metrics
+  name: {{ include "handshake-node.metricsName" . }}
   labels:
     {{- include "handshake-node.labels" . | nindent 4 }}
     app.kubernetes.io/component: metrics

charts/handshake-node/templates/service-p2p.yaml

@@ -2,7 +2,7 @@
 apiVersion: v1
 kind: Service
 metadata:
-  name: {{ include "handshake-node.fullname" . }}-p2p
+  name: {{ include "handshake-node.p2pName" . }}
   labels:
     {{- include "handshake-node.labels" . | nindent 4 }}
   {{- with (merge (dict) .Values.service.p2p.annotations .Values.serviceAnnotations) }}

charts/handshake-node/templates/service-rpc.yaml

@@ -3,7 +3,7 @@
 apiVersion: v1
 kind: Service
 metadata:
-  name: {{ include "handshake-node.fullname" . }}-rpc
+  name: {{ include "handshake-node.rpcName" . }}
   labels:
     {{- include "handshake-node.labels" . | nindent 4 }}
     app.kubernetes.io/component: rpc

charts/handshake-node/templates/service-stratum.yaml

@@ -3,7 +3,7 @@
 apiVersion: v1
 kind: Service
 metadata:
-  name: {{ include "handshake-node.fullname" . }}-stratum
+  name: {{ include "handshake-node.stratumName" . }}
   labels:
     {{- include "handshake-node.labels" . | nindent 4 }}
     app.kubernetes.io/component: stratum