igneum-network/igneum
1
0
Fork 0
Code Issues Pull requests Releases Activity
igneum/packaging/hive/README.md
igneum-labs 08547b0cac HiveOS: the bundled node takes the override from the Flight Sheet (C41) 
The finding (release-0.3.11.md section 5): h-run.sh started the rig's node with --devnet --appdir
--rpclisten --listen and the peers and no --override-params-file, so a HiveOS rig in local mode ran
on genesis parameters, printed the no-override digest and was refused by every devnet peer; no
package ever carried the override.

h-config.sh: OVERRIDE=<json object> in the Flight Sheet's extra config, read as a whole line (JSON
may carry spaces; single or double quotes around it are stripped), refused unless it is {...},
written to igneum.conf single-quoted (sq helper; EXTRA gets the same quoting, the same class: a
value with shell characters sourced unquoted). Still sourceable (return, never exit).

h-run.sh, local branch: writes data/override-params.json from OVERRIDE when set and passes
--override-params-file=<that path> to igneumd; when empty, a WARNING in the main log that the node
runs on genesis parameters and devnet peers will refuse it. After the node answers, the switch
lines and the "Consensus params digest" line from node.log are copied into the main log as
"node: ..." so the operator can compare the digest with the downloads page.

README: the Flight Sheet table gains the OVERRIDE row with the four-field devnet object as the
example (nine fields after the 0.3.11 switch; the downloads page carries the live one), the rule
"set OVERRIDE from the downloads page when it changes", the sentence that a rig without it is
refused, the digest check in the requirements, and the gap entry. No "every override publish
needs a package republish" sentence exists in packaging/hive/README.md on this branch or master,
so nothing was replaced; the new rule stands alone.

selftest.sh: a fake igneumd that records its argv and prints the real digest line; OVERRIDE
single-quoted on its own line beside other keys round-trips through the conf; OVERRIDE=notjson
refused; empty OVERRIDE named in the summary; the main h-run run checks the file, the flag on the
node and the digest and switch lines in the main log; a second short run without OVERRIDE checks
the warning and the absence of the flag. bash packaging/hive/selftest.sh on this Mac:

== h-config.sh OVERRIDE
   OVERRIDE (single-quoted, own line) sourced back intact beside the other keys ok
   OVERRIDE that is not {...} refused ok
   no OVERRIDE: empty in the conf and named in the summary ok
== h-run.sh (fake GPUs: 2 NVIDIA, fake node, fake miner)
   data/override-params.json written from OVERRIDE ok
   the node got --override-params-file ok
   the node's digest and switch lines reached the main log ok
   NVIDIA cards got the cuda worker ok
   exit 42 restarted the miner and re-exported the pack ok
== h-stats.sh (sourced)
   stats JSON ok: hs [118500.0, 118500.0] temp [61, 58] ar [24, 0] bus [1, 2]
== h-run.sh without OVERRIDE (the warning)
   no OVERRIDE: warning in the main log, no flag on the node ok
== self-test passed (scripts and stats shape; Hive itself is untested)

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
2026-10-05 23:35:03 +00:00

94 lines
8.4 KiB
Markdown
Raw Blame History

# Igneum Miner for HiveOS
The Igneum miner as a HiveOS custom miner: `igneum-hive-<version>.tar.gz` holds the Linux `igneum-miner`, `igneumd`,
the two GPU workers (`igneum-worker-cuda` for NVIDIA, `igneum-worker-opencl` for AMD) and the four hooks Hive runs
(`h-manifest.conf`, `h-config.sh`, `h-run.sh`, `h-stats.sh`). Built on 4 October 2026. **Hive itself is untested**: the
scripts were self-tested with stub binaries (`selftest.sh`) and the binaries were cross-compiled on a Mac; the first real
run on a Hive rig is still to come. Report what breaks.
**A HiveOS rig mines only.** The package (`make-hive-package.sh`) carries `igneumd`, `igneum-miner` and the two
workers; no `igneum-prove-host`, no `igneum-prove-export`, no SP1 GPU server. So a rig on this package earns from the
80% lottery share and nothing from the 20% proving share until a Linux prover build is published. The Ubuntu rig
installer (`packaging/linux/README.md`, branch `rig-install`, commit dd632c1) carries a prover unit that idles in state
`setup` for the same reason; its per-card table is the fuller version of the one below. What each card could do once
the prover ships, from the app's default (`app/igneum-app/src/provedefault.rs` at 440fd59 on `proving-v1`: proving on
at 24 GB or more, off below) and from the proving agent's S_p curve of 5 October 2026 (`docs/bench-log.md`, "proving
v1": jobs `memsweep-pc2-pv1`, `memminer-pc2-pv1` and the S_p curve, one RTX 5090, SP1 6.8.1's GPU server):
| Card | Once a Linux prover ships | Measured on 5 October 2026 |
|---|---|---|
| 8 GB | mines only | the prover's floor is 13.9 GB for an empty shard |
| 12 GB | mines only; proves nothing on this SP1 build | the same 13.9 GB floor |
| 16 GB | in practice mines only: proves empty shards alone, nothing beside the miner | 13.9 GB alone; 15.7 GB beside the miner leaves nothing for the display |
| 24 GB | proves the adopted v1 shard (30,000 pgas) from the fee switch at DAA 210,000, nothing before it | 20.4 GB alone, about 22 GB beside the miner (approximate, not measured on a 24 GB card); the prototype shard at 28.3 GB does not fit |
| 32 GB | mines and proves, prototype shard included | 28.3 GB alone, 30.0 GB beside the miner, 2.5 GB spare |
## Flight Sheet
| Field | Value |
|---|---|
| Miner | Custom |
| Installation URL | `https://<host>/igneum-hive-<version>.tar.gz` (the archive from `make-hive-package.sh`, published on the download host) |
| Miner name | `igneum` |
| Wallet and worker template | `0x<40 hex>.%WORKER_NAME%`: the payout address is an EVM address you hold the key for; the part after the dot labels this rig's keys |
| Pool URL | `grpc://<your node>:26610` (your own igneumd, solo mining), or `local` to run the bundled node on the rig |
| Pass | empty |
| OVERRIDE | the devnet's consensus override as one JSON object on its own line, needed with `local`: `OVERRIDE={"difficulty_v2_activation_daa":33000,"proving_v0_activation_daa":84100,"fees_v1_activation_daa":210000,"finality_v3_activation_daa":135200}` is the four-field object 0.3.10 shipped; after the 0.3.11 switch it has nine fields, and the downloads page carries the live one. Set OVERRIDE from the downloads page when it changes. **A rig without it is refused**: its node runs on genesis parameters, prints another digest, and every devnet peer drops it (`h-run.sh` warns in the main log) |
| Extra config arguments | `DEV_FEE=1 IDENTITIES=auto WORKER=auto VOTE=1` (one per line also works); `PEERS=a:26611,b:26611` for the bundled node; `EXTRA="..."` for more miner flags |
| IDENTITIES | vote keys per card: 8 for a card with 8 GB or more, else 2 (`IDENTITIES=auto` applies that rule, per card, from `nvidia-smi` or the amdgpu sysfs; 8 when neither answers; a number overrides it for every card). The rule is the app's (`app/igneum-app/src/detect.rs`) |
Solo mining: there is no pool. Each card mines block templates from the node and the block reward pays the wallet in
the template (80% of each block to its finder, 20% to the proving pool; the protocol takes no fee for anyone).
## The dev fee
The Igneum miner software takes a 1% dev fee the way every GPU miner does (lolMiner, T-Rex): one block template in
100 is requested with the dev payout address instead of yours. It is a counter, not a random draw, so it is exactly
1 in 100 and anyone can audit it from the source (`igneum/miner/src/main.rs`, "Software dev fee") or from the chain
(`igneum-miner payouts grpc://<node>:26610` lists blocks per payout address). `DEV_FEE=0` in the extra config turns it
off. The miner prints its own line at start, in each GPU's log:
dev fee 1% (1 block in 100) to 0x<address>; --dev-fee 0 turns it off
The protocol carries no fee: this is the software's, and any other miner client is welcome.
## What the hooks do
| Hook | What |
|---|---|
| `h-config.sh` | writes `igneum.conf` from the Flight Sheet (node URL, wallet, label, DEV_FEE, IDENTITIES, WORKER, VOTE, PEERS, EXTRA, OVERRIDE); refuses an OVERRIDE that is not `{...}`; resolves `IDENTITIES=auto` to `IDENTITIES_GPU<N>` keys by VRAM; refuses a wallet that is not 0x + 40 hex |
| `h-run.sh` | starts the bundled node when the URL is `local` (writes `data/override-params.json` from OVERRIDE and passes `--override-params-file`; warns when OVERRIDE is empty; copies the node's switch lines and its `Consensus params digest` line into the main log), waits for the node, exports the hourly program pack (`igneum-miner export-pack`), then one `igneum-miner` per GPU with its worker (`--identities` from `IDENTITIES_GPU<N>`, else `IDENTITIES`); restarts a miner that exits (exit 42 = program change without prepare support: the pack is re-exported first); per-GPU logs `<log>.gpu<N>.log`, merged into the main log |
| `h-stats.sh` | per-GPU hash rate from each miner's last `STATUS` line (`now=<MH/s>`), accepted and rejected totals, dev-fee block count, temperatures and fans from Hive's `gpu-stats` (else `nvidia-smi`), uptime, version |
Stats JSON (what Hive reads from `$stats`): `hs` (kH/s per GPU), `hs_units` (`khs`), `temp`, `fan`, `uptime` (s),
`ver`, `ar` (`[accepted, rejected]`), `algo` (`igneum`), `bus_numbers`, plus `dev_fee_blocks` (ours). `$khs` is the total.
## Requirements on the rig
- NVIDIA: the driver (`libcuda.so.1`) and NVRTC (`libnvrtc.so.12`, from a CUDA 12 toolkit or the NVRTC redistributable
on the library path). The worker compiles the hourly program at run time with NVRTC; without the library it says so
and the miner retries. Hive images ship the driver; whether `libnvrtc.so.12` is present depends on the image, untested.
- AMD: an OpenCL ICD (`libOpenCL.so.1` from ROCm or amdgpu-pro). The OpenCL worker compiles the program through the ICD.
- The bundled node (`local`) keeps its chain data under the miner folder (`data/`); a devnet chain is small today. It
needs OVERRIDE (the Flight Sheet table): compare the `node: Consensus params digest:` line in the main log with the
digest on the downloads page; a different one means the override is stale and the node is refused.
- Ports: the bundled node listens on 26611 (p2p) and answers RPC on 127.0.0.1:26610 only.
## Building the package
infra/cross/build-linux.sh # igneumd and igneum-miner for Linux (cargo-zigbuild), into infra/cross/out
infra/cross/build-workers-linux.sh # the two workers (zig c++ and zig cc), into infra/cross/out-workers
packaging/hive/make-hive-package.sh # the archive, sha256 and the Flight Sheet lines; NODE_OUT=infra/cross/out-v2 to pick a build
packaging/hive/selftest.sh # bash -n, a stub package, the three hooks the way Hive runs them
## Known gaps (4 October 2026)
- Never run on Hive. The hook contract follows Hive's custom-miner README (archive `name-version.tar.gz` with the
directory `name/`; `h-config.sh` and `h-stats.sh` are sourced; `$khs` and `$stats`), approximate until a rig confirms it.
- GPU order: the CUDA device index is assumed to follow `nvidia-smi` order and Hive's `gpu-stats` arrays (NVIDIA first);
a mixed NVIDIA and AMD rig may show temperatures against the wrong card.
- Each card runs its own `igneum-miner` and node connection; the node's template RPC serves them all.
- Before this change no package carried the override: `h-run.sh` started the node without `--override-params-file`, so
a `local` rig was refused by every devnet peer (release 0.3.11, section 5, C41). Still untested on a rig.
- No prover in the package (the second paragraph above): the rig earns nothing from the proving share until a Linux
prover build ships.
Reference in a new issue View git blame Copy permalink