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.

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), local to run the bundled node on the rig, or pool://<pool host>:4463 to mine to a pool (spec 09; NODE=local in the extra config adds a verifier node for voting)
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; NODE=local or NODE=grpc://host:26610 for the verifier node in pool mode; 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: 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).

Pool mining (5 October 2026, pool/README.md): with pool://host:4463 each card runs igneum-miner ... --pool host:4463 --evm-address <wallet> --worker-name <label>-gpuN; the pool names this rig's own vote key in every header (one key per rig, IDENTITIES is ignored), pays the wallet by PPLNS on the EVM side, and the miner takes no software dev fee in pool mode (the pool's fee, printed in its welcome line, is the only fee). With NODE=local the bundled node runs beside the cards as the verifier: the miner checks the pool's seeds and templates against it, votes with the rig's key through it and submits found blocks there too. Without a node the rig hashes and does not vote. Untested on a Hive rig, like the rest of this package.

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.

Shipped packs (0.3.22)

make-hive-package.sh --kit <zip> (repeatable) puts program-pack kits under packs/ in the archive: the class v4 sub-version 3 kit (eight packs, program_id a785001687d8688a for the shared devnet's epoch 0) and Devnet 3's epoch-0 pack v4-devnet3-epoch0 (program_id fce15bf61030be57, exported under igneum-pow 017e7037 over genesis 4020cb43 as epoch and era seed, day bytes for 7 October UTC). They are the rig's FIRST-START convenience: h-run.sh seeds packs/devnet from the shipped pack only when the node's own export left nothing, so a rig mines from its first start; the pack is dated, and a rig starting after epoch 0 (3,600 DAA) re-exports from its own node as before. The shipped pack is never the authority; the pack-id gate reads program.json's program_id.

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.