# 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.