hashgraph / hashgraph/solo-weaver
feat(consensus): bootstrap NetworkGenesis for a fresh network on install (--init-genesis)
- Dominant language
- Go
- Stars
- 3
- Forks
- 0
- Avg merge
- 3d 5h
- Merged PRs (30d)
- 47
Description
Add a **fresh-network** genesis bootstrap to `consensus node install`: create a `NetworkGenesis` CR so the operator generates `genesis-network.json`. Without it, on a fresh cluster the consensus pod's `genesis-init` container blocks forever (`genesis-init: fresh cluster, waiting for genesis-network.json (up to 10m)`) and the node never starts.
Parent epic: #408
Relates to: #1044 (consensus node install)
### Background
`genesis-network.json` is produced by a **`NetworkGenesis`** CR, reconciled by the operator's `NetworkGenesisReconciler` into the genesis ConfigMap mounted by consensus pods. The Orbit controller does **not** auto-create it — it is a deployer-created CR (see solo-operator `docs/example/network-genesis/network-genesis.yaml`). solo-weaver install currently creates Orbit + config CRs + ConsensusCapsule + secrets but **no `NetworkGenesis`**, so a fresh network never generates genesis and the pod hangs in `PodInitializing`.
The reconciler builds the roster two ways (`networkgenesis_controller.go`): use `spec.roster` if set, else **discover from the ConsensusCapsules in the orbit namespace** (`MaterialsFromCluster`). So a minimal CR (orbit + operationId, roster omitted) is enough for discovery.
### This is fresh-network only
genesis is a **fresh-network bootstrap** artifact. A node joining an existing network — or any node after the first in the same orbit, or a real/mainnet node whose genesis is provided externally — must **not** regenerate genesis. So this must be gated, not unconditional.
### Proposed design
- New flag `--init-genesis` (bool, default **false**). Only when set does install create the `NetworkGenesis` CR.
- New `EnsureNetworkGenesis` step, gated on the flag, that:
- Skips idempotently if a `NetworkGenesis` CR (or the genesis ConfigMap) already exists for the orbit.
- Creates a `NetworkGenesis` (orbit-scoped, in the namespace) with `spec.orbit` = orbit and a stable `operationId`; roster omitted so the operator discovers it from the cluster.
- Runs after the ConsensusCapsule(s) so discovery sees them.
- Default behavior (flag unset) is unchanged: install never touches genesis (join / mainnet path).
### Open questions to resolve during implementation
- **`genesisProperties` / `genesisPublicKey`**: is it required, and if so does the HIP-1494 deployment package (`test/data/build-v0.74.2`) supply it (resolve like the other config files) or is it operator-optional? (Verify against a manual `NetworkGenesis` apply — discovery-only vs. needing `genesisProperties`.)
- **Multi-node fresh network**: genesis discovery reads the capsules present at generation time, so for an N-node fresh orbit the genesis should be generated once **after all N capsules exist**, not per-node. Decide whether `--init-genesis` is a network-level action (install the nodes, then one flagged bootstrap) or whether the operator re-reconciles as capsules appear.
### Acceptance criteria
- [ ] `--init-genesis` (default false); only creates `NetworkGenesis` when set
- [ ] Fresh single-node install with `--init-genesis` produces `genesis-network.json` and the pod reaches Running/Active
- [ ] Idempotent — skips when genesis already exists for the orbit
- [ ] Default (flag unset) never creates/modifies genesis (join / mainnet path unaffected)
- [ ] Multi-node fresh-network ordering documented/handled
- [ ] Docs updated for the new flag
Contributor guide
Research direction
Start at the `consensus node install` entry point and review the existing ConsensusCapsule creation order; then inspect `networkgenesis_controller.go` and `docs/example/network-genesis/network-genesis.yaml`. Verify the required genesis properties against `test/data/build-v0.74.2` and a manual NetworkGenesis apply. Done means the flag-gated, idempotent fresh-network path generates genesis, preserves the default join path, handles multi-node ordering, and is documented.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- go, kubernetes
- Domain
- cli, infrastructure
- Issue type
- Feature
- Difficulty
- 5/5
- Estimated time
- Over a week
- Activity status
- Active
- Clarity
- Mostly clear
- Newbie friendliness
- 45/100