Docs: the node binary is igneumd; rename table in fork-divergence
Records the 3 Oct 2026 rename pass in vendor/igneum-node (binary, process name, user agent, data and log paths, env vars, address prefixes, DNS seeders, default build set) and what stays Kaspa-named internally. The Windows miner guide and the observer README now start igneumd. Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
This commit is contained in:
igneum-josh
parent
5bfab74cbb
commit
5287e60b5a
3 changed files with 46 additions and 6 deletions
|
|
@ -2,7 +2,7 @@
|
|||
|
||||
Fork: `vendor/igneum-node`, a git clone of `vendor/rusty-kaspa` at v2.1.0 commit `01b532e8` (22 Sep 2026). Every Igneum change is a commit on top of that base, one per subject, so `git log 01b532e8..HEAD` in the fork is the full list. This file is the reading guide: what each change touched, why, how risky it is, and what to do when upstream moves. `docs/fork-map.md` is the plan this implements; row ids there (a1 to f2) are cited below.
|
||||
|
||||
Status: devnet v1, mining layer on the real header-bound lottery hash (3 Oct 2026, later the same day as v0): CPU and GPU miners, three workers (Metal, CUDA, OpenCL). Finality, VDF seeds, the zkEVM and the proving layer are not in the fork yet.
|
||||
Status: devnet v1, mining layer on the real header-bound lottery hash (3 Oct 2026, later the same day as v0): CPU and GPU miners, three workers (Metal, CUDA, OpenCL). The node binary is `igneumd` since the rename pass of 3 Oct 2026 (see "The rename" below). Finality, VDF seeds, the zkEVM and the proving layer are not in the fork yet.
|
||||
|
||||
## The table
|
||||
|
||||
|
|
@ -14,8 +14,9 @@ Status: devnet v1, mining layer on the real header-bound lottery hash (3 Oct 202
|
|||
| `protocol/p2p/proto/p2p.proto`, `protocol/p2p/src/convert/{header,block,messages}.rs`, `protocol/flows/src/v10/request_headers.rs` | `BlockHeader` wire message gains `Hash voteKeyHash = 15`; converters copy it both ways | p2p round trip of the field | Low | Field number 15 must stay unique if upstream adds header fields. Protocol version is still Kaspa's 11; bump it when the fork gets its own peers. |
|
||||
| `rpc/grpc/core/proto/rpc.proto`, `rpc/core/src/model/header.rs`, `rpc/core/src/model/optional/header.rs`, `rpc/core/src/model/verbosity.rs`, `rpc/core/src/convert/verbosity.rs`, `rpc/grpc/core/src/convert/{header,optional/header}.rs`, `rpc/service/src/converter/consensus.rs`, `consensus/client/src/header.rs` | `RpcHeader` and `RpcOptionalHeader` carry `vote_key_hash`; gRPC proto fields (`string voteKeyHash = 16` on the header, `optional string voteKeyHash = 15` on the optional header) and converters; wasm client header | RPC round trip, template to miner and block back | Low | Mechanical. Borsh wire for wRPC changed shape: old wRPC clients cannot decode headers. |
|
||||
| `consensus/src/model/stores/headers.rs`, `consensus/src/test_helpers.rs`, `mining/src/testutils/consensus_mock.rs`, `mining/src/template_limits_tests.rs`, `consensus/src/pipeline/virtual_processor/processor.rs`, `consensus/src/pipeline/body_processor/body_validation_in_isolation.rs` | Header store serde includes the field; template builder passes the field through; tests construct it | Storage and mining paths | Low | Database format changed: a node from before this commit must resync from scratch. |
|
||||
| `consensus/core/src/network.rs` | Network name prefix `igneum-` (was `kaspa-`); devnet ports gRPC 26610, wRPC borsh 27610, wRPC json 28610, P2P 26611 (Kaspa devnet: 166xx to 186xx); error text | The prefixed name is the p2p handshake magic (`FlowContext::handshake` rejects a `Version.network` mismatch), so `igneum-devnet` never completes a handshake with `kaspa-devnet`. Distinct ports stop a Kaspa node on the same host from being dialled by mistake | Low | Mainnet, testnet and simnet ports are still Kaspa's. Change them before any public network. |
|
||||
| `crypto/addresses/src/lib.rs`, `bridge/src/default_client.rs`, `bridge/src/tests.rs` | Devnet address prefix `igneumdev` (was `kaspadev`) | A devnet address can never parse as a Kaspa devnet address | Low | The bech32 prefix is only the devnet one so far. |
|
||||
| `consensus/core/src/network.rs` | Network name prefix `igneum-` (was `kaspa-`) for every network id (`igneum-mainnet`, `igneum-testnet-10`, `igneum-devnet`, `igneum-simnet`); devnet ports gRPC 26610, wRPC borsh 27610, wRPC json 28610, P2P 26611 (Kaspa devnet: 166xx to 186xx); error text | The prefixed name is the p2p handshake magic (`FlowContext::handshake` rejects a `Version.network` mismatch), so `igneum-devnet` never completes a handshake with `kaspa-devnet`. Distinct ports stop a Kaspa node on the same host from being dialled by mistake | Low | Mainnet, testnet and simnet ports are still Kaspa's. Change them before any public network. |
|
||||
| `consensus/core/src/config/params.rs` | `MAINNET_PARAMS.dns_seeders` and `TESTNET_PARAMS.dns_seeders` emptied (upstream: nine Kaspa mainnet seeders, three testnet seeders) | An Igneum node started with `--testnet` or no network flag must never dial Kaspa seeders | Low | Fill with Igneum seeders before any public network. Devnet and simnet were already empty. |
|
||||
| `crypto/addresses/src/lib.rs`, `crypto/txscript/src/standard.rs` (test vectors), `bridge/src/default_client.rs`, `bridge/src/share_handler.rs`, `bridge/src/tests.rs` | Address prefixes `igneum` (mainnet), `igneumtest`, `igneumsim`, `igneumdev` (upstream `kaspa`, `kaspatest`, `kaspasim`, `kaspadev`); devnet first on 3 Oct 2026 v0, the other three in the rename pass later that day | No Igneum address string parses as a Kaspa address on any network. The prefix is only part of the string encoding and its checksum; the script public key behind an address is unchanged, so nothing on chain moved | Low | Any upstream test that spells out a `kaspa:` address fails here; the vectors in `addresses` and `txscript` were regenerated. Wallet, cli and wasm crates (not in the default build) still carry `kaspa:` strings in their own tests. |
|
||||
| `consensus/core/src/config/bps.rs`, `consensus/core/src/config/params.rs` | `OneBps = Bps<1>`; `DEVNET_PARAMS` uses `BlockrateParams::new::<1>()`: 1,000 ms blocks, GHOSTDAG k 18 (`calculate_ghostdag_k(2 x 5 x 1, 0.01)`), 10 max parents, mergeset limit 180, merge depth 3,600 blocks, finality depth 43,200 blocks, pruning depth 108,000 blocks, coinbase maturity 100; `crescendo_activation: always()`; doc table and a test pinning every value | 1 block per second at launch (fork-map f1, f2, e1). Finality and pruning depths are upper bounds only: live finality will be the certified checkpoint | Low; this is Kaspa mainnet's pre-Crescendo path | The `ForkedParam` and `bps_history` plumbing is still present for the other networks. Strip it in one pass when mainnet params are written. |
|
||||
| `consensus/core/src/igneum.rs` (new), `consensus/core/src/lib.rs`, `consensus/core/src/constants.rs` | Emission constants and functions: 1,000,000,000 coins in year one, per-second rate halving every two years (`SUBSIDY_PER_SECOND_BY_PERIOD[i] = 3,168,808,781 >> i`, 33 periods), `block_subsidy(daa_score, bps)`, 30-day linear launch ramp from 10%, `proving_pool_share` 20% and `producer_share` 80%, `proving_pool_script_public_key` (OP_RETURN tagged `igneum-proving-pool-v0`), `POW_EPOCH_BLOCKS = 3,600` | The design's schedule, hard cap 4,000,000,000 (the geometric series sums to it; rounding leaves under 100 coins unminted), no emission treasury (fork-map b1, b2) | Medium: consensus money | Pure addition. Keep as the one source of the schedule. |
|
||||
| `consensus/src/processes/coinbase.rs` | Kaspa's pre-deflationary phase, 426-month table and Crescendo rescaling removed; `CoinbaseManager::new(max_spk_len, max_payload_len, bps)`; `calc_block_subsidy` reads the period table; `expected_coinbase_transaction` pays 80% plus fees per rewarded block to its declared script and pools 20% of every subsidy (blues and reds) into one output to the proving pool script, placed after the blue outputs and before any red reward; tests rewritten | 80/20 split in consensus; the 20% is burned on devnet v0 and becomes the prover payout when the proving layer records prover sets (fork-map b3) | High: changes what every node accepts as a valid coinbase | Upstream edits to `coinbase.rs` will conflict. The payload format is unchanged (full subsidy in the payload, split derived from it), so Kaspa's payload parsing merges cleanly. |
|
||||
|
|
@ -26,6 +27,45 @@ Status: devnet v1, mining layer on the real header-bound lottery hash (3 Oct 202
|
|||
| `consensus/core/src/config/constants.rs` | Comment block only: the DAA constants kept at 1 BPS (sample every 4 blocks, 661 samples, 2,644-block window, min window 150 samples) and the two timestamp rules kept (132 s future tolerance in isolation, strictly above the sampled past median time of 27 samples in context) | Difficulty step verified rather than changed (fork-map c1, c2); the known gap (per-epoch hash-speed step vs a 44-minute window) is recorded there | None | Comment only. |
|
||||
| `igneum/miner/` (new crate `igneum-miner`), `Cargo.toml` (workspace member), `Cargo.lock` | Devnet miner: `--engine stub` (kHeavyHash, v0) or `--engine igneum-pow` (CPU warps through the node's own `IgneumEngine` cache, 64-bit nonces, random start per thread), `--worker <exe>` (GPU serve protocol: `job`/`found`/`done` lines, CPU re-check of every found nonce, one submit per template, `--exit-on-seed-change` exits 42 for ahead-of-time workers, `--worker-args`, `--status-secs`), `export-pack` (the pack for the node's current epoch and day plus `seeds.txt`), `bad-nonce` (submits an unmined nonce, expects a rejection); the epoch seed is derived as the node does it, walking from the sink over gRPC; `watch` and `inspect` as in v0 | Kaspa ships no miner; the devnet needs one that follows the fork's own PoW crate, and the GPU workers need a driver | None to consensus | Internal tool. Depends on `igneum-pow` by path and on `kaspa-pow` with the `igneum-pow` feature. Cross-compiles for `x86_64-pc-windows-gnu` with mingw-w64 (no rocksdb in its closure). |
|
||||
|
||||
## The rename (3 Oct 2026): what a miner, a user or an operating system sees
|
||||
|
||||
Trigger: macOS asked Josh whether "kaspad" may access the local network. Everything visible from outside the source tree now says Igneum. Internal crate names, module paths, protobuf packages and Rust identifiers keep their upstream names (next table) so `git merge` against rusty-kaspa stays mechanical.
|
||||
|
||||
| Surface | Before | After | Where |
|
||||
|---|---|---|---|
|
||||
| Node binary, process name, macOS and firewall prompts | `kaspad` | `igneumd` | `kaspad/Cargo.toml`: package still `kaspad`, `autobins = false`, `[[bin]] name = "igneumd"`; `cargo build --release -p kaspad --features igneum-pow` writes `target/release/igneumd` |
|
||||
| p2p user agent (the `Version` handshake message) | `/kaspad:2.1.0/` | `/igneumd:2.1.0/` | `core/src/kaspad_env.rs` `name()`; used by `protocol/p2p/src/convert/model/version.rs` and `protocol/flows/src/flow_context.rs`. The handshake also checks `network` (`igneum-devnet`) and protocol version (11, unchanged), so an old `kaspad`-named Igneum node and `igneumd` still peer |
|
||||
| CLI name, help, `--version` | `kaspad`, "Kaspa full node daemon (rusty-kaspa) v2.1.0" | `igneumd`, "Igneum full node daemon (igneumd) v2.1.0" | `kaspad/src/args.rs`, `kaspad/Cargo.toml` description |
|
||||
| Network flags | `--devnet` "Use the Igneum development network", `--testnet` "Use the test network" | `--devnet` (alias `--igneum-devnet`), `--testnet` and `--simnet` say Igneum | `kaspad/src/args.rs` |
|
||||
| Environment variables | `KASPAD_APPDIR`, `KASPAD_RPCLISTEN`, ... (40) | `IGNEUMD_APPDIR`, `IGNEUMD_RPCLISTEN`, ... (same suffixes) | `kaspad/src/args.rs` |
|
||||
| Default data directory | `~/.rusty-kaspa` (macOS, Linux), `%LOCALAPPDATA%\rusty-kaspa` (Windows) | `~/.igneum`, `%LOCALAPPDATA%\igneum` | `kaspad/src/daemon.rs` `get_app_dir`. Upstream never used Application Support on macOS; the Go-era help text in the trailing comment of `args.rs` that mentions it is dead text |
|
||||
| Log file names | `rusty-kaspa.log`, `rusty-kaspa_err.log` | `igneumd.log`, `igneumd_err.log` | `core/src/log/consts.rs` |
|
||||
| Startup banner | `kaspad v2.1.0-<hash>` | `igneumd/2.1.0-<hash>` | `kaspad/src/daemon.rs` |
|
||||
| Shutdown, FD-limit, DB-version and confirmation messages | "Kaspad has stopped", "The kaspad node requires", "Kaspad DB version", "pass --yes to the Kaspad command line" | igneumd in each | `kaspad/src/main.rs`, `kaspad/src/daemon.rs` |
|
||||
| Heap profile file (feature `heap`) | `kaspad-heap.json` | `igneumd-heap.json` | `kaspad/src/main.rs` |
|
||||
| UPnP port-mapping description shown by routers | `rusty-kaspa` | `igneum` | `components/addressmanager/src/lib.rs` |
|
||||
| Temp directory for database tests and tools | `<tmp>/rusty-kaspa` | `<tmp>/igneum` | `database/src/utils.rs` |
|
||||
| p2p and gRPC error text | "received kaspad p2p message", "Kaspad gRPC message" | igneumd | `protocol/p2p/src/core/router.rs`, `rpc/grpc/server/src/connection.rs` |
|
||||
| Address prefixes | `kaspa`, `kaspatest`, `kaspasim`, `igneumdev` | `igneum`, `igneumtest`, `igneumsim`, `igneumdev` | `crypto/addresses/src/lib.rs`; the stratum bridge accepts and defaults to the Igneum prefixes |
|
||||
| DNS seeders | nine Kaspa mainnet, three Kaspa testnet hostnames | none | `consensus/core/src/config/params.rs` |
|
||||
| Default build set | `cargo build` at the root built `kaspa-cli`, `kaspa-wallet`, `kaspa-wrpc-proxy` and the wasm bundles too | `default-members` leaves those out; they stay members, so `-p kaspa-cli` and `--workspace` still build them | `Cargo.toml` |
|
||||
| `igneum-miner` | no user-visible string named kaspad (checked) | unchanged | `igneum/miner/` |
|
||||
|
||||
Kept on purpose, not visible outside the tree, so upstream merges stay clean:
|
||||
|
||||
| Stays Kaspa-named | Why |
|
||||
|---|---|
|
||||
| Crate names (`kaspa-consensus`, `kaspa-p2p-lib`, `kaspad` the package, `kaspad_lib`, ...) and every `use kaspa_*` path | Renaming 60 crates touches every file in the tree; each upstream commit would then conflict on its first line |
|
||||
| Protobuf packages and messages (`protowire`, `KaspadMessage`, `KaspadRequest`, `KaspadResponse`, `kaspad_message::Payload`) | The gRPC and p2p wire names are matched by generated code on both sides; changing them is a wire-format fork for no user-visible gain (clients see the port and the methods, not the package name) |
|
||||
| The module name `kaspad_env` in `kaspa-core` | Internal; its `name()` now returns `igneumd` |
|
||||
| `SOMPI_PER_KASPA` and the 8-decimal unit constants | Open decision (8 or 18 decimals) in the table above; rename with the unit decision |
|
||||
| RPC `server_version` (`getInfo`) | Still the bare `2.1.0`, as clients and the observer parse it; the node name is in the p2p user agent and the banner |
|
||||
| p2p protocol version 11 | Not a name. Bump when the fork takes its own peers |
|
||||
| Mainnet, testnet and simnet ports and genesis content | Not names. Ports and Igneum genesis blocks for the public networks are a separate pass (see the rows above) |
|
||||
| Wallet, cli, wasm crates and the fork's README | Not in the default build and not shipped; their `kaspa:` test strings and docs are untouched |
|
||||
|
||||
Devnet compatibility: the devnet genesis, consensus rules, ports, network id `igneum-devnet` and address prefix `igneumdev` are unchanged, so an `igneumd` built from this commit syncs the chain mined by the earlier `kaspad`-named build and the Windows miner keeps submitting to it (it derives `igneumdev` addresses; a change of the devnet prefix would have broken its templates at cut-over). Verified 3 Oct 2026 20:33 to 20:36 BST: a fourth node from `target-rename/release/igneumd` (built with `CARGO_TARGET_DIR=target-rename cargo build --release -p kaspad -p igneum-miner --features igneum-pow`, 2 min 31 s) on gRPC 26630, P2P 26631, appdir `/tmp/igneum-rename-test`, peered to node 1 at 127.0.0.1:26611, logged `igneumd/2.1.0-745d41ef` as its first line, completed IBD in under a second (140 headers, 140 blocks, sink `7f4cba28...3aa11`, the same sink and DAA score node 1 reported) and node 1 kept running. A fifth node peered to the fourth showed in `getConnectedPeerInfo` as `/igneumd:2.1.0/igneumd:2.1.0/` while node 1 showed as `/kaspad:2.1.0/kaspad:2.1.0/` (the doubled agent is upstream behaviour: `Version::default` and `add_user_agent` both write it). Note for test nodes: `--connect` sets the inbound limit to 0 and skips the P2P listener; use `--addpeer` with `--listen` when another node must dial in. Cut-over for node 1: stop the old `kaspad` process, start `igneumd --devnet` with the same `--appdir`, `--rpclisten` and `--listen`; the database format did not change.
|
||||
|
||||
## Decisions recorded as open
|
||||
|
||||
| Decision | v0 choice | Why it is open |
|
||||
|
|
|
|||
|
|
@ -3,7 +3,7 @@
|
|||
Written 3 October 2026 for Josh's PC (RTX 5090 at about 229 MH/s on the memory-hard hash, Ryzen 9800X3D with the
|
||||
gfx1036 integrated AMD GPU at about 4 MH/s; `docs/bench-log.md`). Two ways: the packaged test (one double-click), or by
|
||||
hand from this repository. Both mine against node 1 on the Mac (LAN 192.168.68.64, gRPC 26610, p2p 26611), which runs
|
||||
`kaspad --devnet` built with `--features igneum-pow`, so every block is checked with the real header-bound lottery hash.
|
||||
`igneumd --devnet` (the node binary, renamed from kaspad on 3 October 2026) built with `--features igneum-pow`, so every block is checked with the real header-bound lottery hash.
|
||||
|
||||
## The packaged test (igneum-mine-test.zip)
|
||||
|
||||
|
|
@ -49,7 +49,7 @@ Open a plain command prompt and select the toolset first (every build command be
|
|||
```
|
||||
|
||||
Build the miner (10 to 15 minutes the first time; `rand`, `ring`, `secp256k1-sys` and the gRPC stack build with MSVC;
|
||||
`rocksdb` is not in the miner's dependency closure, so no CMake or clang is needed; a full `cargo build -p kaspad` on
|
||||
`rocksdb` is not in the miner's dependency closure, so no CMake or clang is needed; a full node build (`cargo build -p kaspad`, the package that produces `igneumd`) on
|
||||
Windows would need them and is not required for mining):
|
||||
|
||||
```
|
||||
|
|
|
|||
|
|
@ -19,7 +19,7 @@ Environment, every value optional:
|
|||
A node started by another tool may listen on gRPC only. Then run your own non-mining peer with a JSON listener, on ports that do not clash with the devnet's (gRPC 26610, P2P 26611):
|
||||
|
||||
```
|
||||
vendor/igneum-node/target/release/kaspad --devnet --nodnsseed --disable-upnp \
|
||||
vendor/igneum-node/target/release/igneumd --devnet --nodnsseed --disable-upnp \
|
||||
--appdir=/tmp/igneum-obsnode --rpclisten=127.0.0.1:26640 --rpclisten-json=127.0.0.1:28640 \
|
||||
--listen=127.0.0.1:26641 --connect=127.0.0.1:26611 --nologfiles
|
||||
IGNEUM_RPC=ws://127.0.0.1:28640 node tools/observer/observer.mjs
|
||||
|
|
|
|||
Loading…
Reference in a new issue