igneum/packaging/hive/README.md

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.

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
Extra config arguments	DEV_FEE=1 IDENTITIES=8 WORKER=auto VOTE=1 (one per line also works); PEERS=a:26611,b:26611 for the bundled node; EXTRA="..." for more miner flags

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); refuses a wallet that is not 0x + 40 hex
h-run.sh	starts the bundled node when the URL is local, waits for the node, exports the hourly program pack (igneum-miner export-pack), then one igneum-miner per GPU with its worker; 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.
• 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.