igneum/docs/design/base-unit.md

The base unit of IGN (O-2.6)

Decision proposed for the project lead's word (6 October 2026, 22:xx UK; his answer in docs/plans/ledger-decisions.md row 5 was "18"): one IGN is 10^18 base units on the testnet and on mainnet, the EVM's wei, so a consensus amount and an EVM balance are the same number and the bridge is the identity. The devnet keeps 10^8 (Kaspa's sompi, what it mints today). The unit is a genesis parameter, Params::base_unit_decimals, per network, in the consensus digest once it leaves 8. Every amount in the node becomes a u128 behind one type, kaspa_consensus_core::unit::Amount, end to end, so nothing depends on the cap fitting any type: the emission lane may add a tail or remove the cap and the type does not care (headroom 3.4 x 10^38, which is 10^19 seconds of the 18-decimal full rate).

Why 18: every EVM wallet, bridge, explorer and rollup assumes it (nativeCurrency.decimals: 18 is already what tools/evm-smoke/smoke.mjs tells viem; MetaMask shows 18). Why not keep 8 and bridge at 10^10, as the devnet does: the public text then carries two unit systems ("the coinbase pays 8-decimal units, the EVM shows 18", docs/api/public-stats.md), every exchange integration has to know which API returns which, and a UTXO-side amount with 8 decimals cannot express a wei-level EVM balance, so the two ledgers can never be reconciled to the unit. Why not U256: consensus-core has no alloy dependency, u128 holds every schedule by a factor of 10^11, and u128 to U256 is lossless on the exec side.

1. Where an amount lives today (the fork at ca3-v4-0316, eec34ac3)

Place	File	Type and byte form today	At 18 decimals
UTXO output value	consensus/core/src/tx.rs:175 TransactionOutput.value	u64; borsh 8 LE; the tx hash and id write 8 LE bytes (hashing/tx.rs:125); the sighash covers it through outputs_hash	Amount (u128); 16 LE bytes under a new tx version (section 3)
UTXO set entry	consensus/core/src/utxo/utxo_entry.rs:21 UtxoEntry.amount	u64; bincode in the store (consensus/src/model/stores/utxo_set.rs, CachedDbAccess, database/src/access.rs:134); muhash over the bincode	Amount; store schema version with a u64 legacy decode (the pre-Toccata TLegacy path, access.rs:214, is the pattern)
Mass view of a UTXO	consensus/core/src/mass/mod.rs:141 UtxoCell.amount; calc_storage_mass	u64; C = storage_mass_parameter = 10^12 (constants.rs STORAGE_MASS_PARAMETER = SOMPI_PER_KASPA x 10,000), in Params and the digest	UtxoCellUnits and calc_storage_mass_units (in the tree now); C = Params::storage_mass_parameter_units() = 10^22, which no u64 holds
Coinbase subsidy	consensus/core/src/igneum.rs (block_subsidy, u64 table); consensus/src/processes/coinbase.rs (CoinbaseData.subsidy u64, payload LENGTH_OF_SUBSIDY = 8 LE bytes at :14, :139; BlockRewardData.subsidy)	u64 everywhere	block_subsidy_units (in the tree now, u128); the payload carries 16 LE bytes under the new tx version
Coinbase outputs	coinbase.rs:84 to 118 (producer, pool, red reward sums)	u64 adds	Amount with checked adds
Tx validation caps	consensus/src/processes/transaction_validator/tx_validation_in_isolation.rs:155, 165 MAX_SOMPI	u64 = 4 x 10^9 x 10^8	Params::supply_cap_units() or no cap check at all (a tail removes the meaning of MAX)
Fees (UTXO side)	mining/src/mempool/model/frontier/feerate_key.rs:9 fee: u64; rpc/core/src/model/mempool.rs:8; DEFAULT_MINIMUM_RELAY_TRANSACTION_FEE = 100_000 sompi per kilogram (mining/src/mempool/config.rs:20)	u64	Amount; the relay floor and the dust rule scale with the unit (section 7)
Script introspection	crypto/txscript/src/opcodes/mod.rs:1100 OpTxInputAmount, :1151 OpTxOutputAmount (KIP-10)	amounts pushed as script numbers, i64	16-byte script numbers for these two opcodes under the new tx version, or the opcodes refused above 2^63 (section 7)
P2P wire	protocol/p2p/proto/p2p.proto:62 uint64 value = 1 (output), :190 uint64 amount = 1 (UTXO entry)	varint, 6.0 B per schedule amount measured	low word stays field 1, uint64 value_hi added (section 3); 12.4 B measured
gRPC	rpc/grpc/core/proto/rpc.proto:103, 122 uint64 amount, :310 uint64 fee	varint	the same low and high pair
RPC model, wRPC borsh	rpc/core/src/model/tx.rs:26, 245	u64; borsh 8 LE	Amount; borsh 16 LE; the RPC serializer version steps (3 today for the checkpoints report)
JSON and wasm clients	consensus/client/src/serializable/numeric.rs:34, 236, consensus/client/src/output.rs:56, utxo.rs:69	JSON numbers (lossy past 2^53 in JavaScript)	Amount serialises as a decimal string in JSON (in the tree now); wasm hands out BigInt
Wallet	wallet/core/src/utils.rs:34 to 70 (sompi_to_kaspa as f64), wallet/pskt/src/output.rs:15, wallet/core/src/storage/transaction/*.rs, cli/src/utils.rs	u64 and f64 formatting	Amount::format_ign and parse_ign (in the tree now, exact, never a float); the Igneum wallet lives on the testnet-wallet branch and is not in master yet
UTXO index	indexes/core/src/indexed_utxos.rs:25 and the circulating supply counter	u64	Amount; the supply counter checked
Exec bridge	igneum/exec/src/config.rs:43 WEI_PER_SOMPI = 10^10; executor.rs:145 execute_segment(.., subsidy_sompi: u64, ..), :167 producer as u128 x WEI_PER_SOMPI	u64 in, U256 out	Params::wei_per_unit() (in the tree now, 1 at 18); execute_segment takes Amount; the SP1 guest reads the rewards in wei already (the fixture's rewards and payouts are U256), so its input type changes once and the shard program id is re-pinned at the testnet genesis, never on the devnet
Proving pool accounting	igneum/exec/src/service.rs:1029 (block_subsidy u64 into the segment), proving.rs split_pool_credit (wei)	u64 subsidy, wei credits	Amount subsidy; credits unchanged (already wei)
Pool software	pool/src/state.rs:9 to 11 WEI_PER_IGN, WEI_PER_SOMPI; pool/src/node.rs:251, 366	u64 sompi from RPC, wei out	reads the unit from the node (igneum_getProvingStatus or the params RPC) and drops WEI_PER_SOMPI
App display	app/igneum-app/src/prover.rs:501, 548 (wei as f64 / 1e18 in event lines)	f64 for log lines	format_ign for anything a user reads (section 6)
Observer and public stats	tools/observer/observer.mjs:110 subsidy_sompi bigint, paid_sompi bigint; docs/api/public-stats.md decimals_consensus: 8	Postgres bigint is i64: 9.2 x 10^18, below one 18-decimal block	numeric columns; decimals_consensus reads the network's unit
Signed manifest, tuning kits	app/igneum-app/src/config.rs (update manifest), infra/fleet tuning files	no amount fields (checked 6 October 2026: the manifest carries URLs, versions and hashes; the tuning kits carry miner settings)	nothing

1b. One schedule, one amount type (with the economy lane, 6 October 2026)

The economy lane's EmissionSchedule (fork branch tail-emission-node, 486895d6, merged into decimals at 6ffd5451) holds its rates as bare u128 base units and already computes in u128 with u64 views that refuse rather than wrap. The composition: a schedule is a parameter struct and keeps u128 (its JSON form is a decimal string, as Amount's is); every amount a transaction or a coinbase carries is Amount; the coinbase wraps Amount(table.block_subsidy(..)). Schedules are written at 8 decimals and EmissionSchedule::rescaled(8, 18) carries one to a network's unit, so the testnet pays TESTNET_1 at 18 (100 x 10^18 base units a block) and mainnet CURRENT at 18; the devnet and simnet keep CURRENT at 8 and their digest (pinned c562d70e..., asserted). The closed form at 18 (block_subsidy_units) is defined as the 8-decimal floor times 10^10, so it equals the rescaled table block for block (asserted); a floor taken at the finer unit would mint 4,028,950,237 wei a second more, read the same to 8 digits, and was not chosen. The widening ships in the feature tree as 0.3.17 (0.3.16 went out as the corrective cut of 0.3.15 at 23:13 UK).

2. The type

kaspa_consensus_core::unit::Amount(pub u128): Copy, Ord, Hash, Default, borsh (16 LE bytes), serde (a decimal string in human-readable formats, the u128 in binary ones, reading a JSON number too), checked and saturating arithmetic, percent without an intermediate product, to_le_bytes / from_le_bytes, to_wire / from_wire (16 bytes, or the 8-byte u64 form every rusty-kaspa format carries today), rescale(from, to) (exact, refuses a remainder), to_wei(decimals), format_ign / parse_ign (section 6). Helpers: unit(decimals), wei_per_unit, decimals_valid (0 to 18), IMPLEMENTED_DECIMALS (section 8). A NewType, not a bare u128, so a unit is never added to a count and every serialiser sees one type.

3. Serialisation and versioning (as built, 7 October 2026)

The rule that replaced the version fields of the first draft: the byte width of an amount follows the network's unit, not a transaction or store version. On a network at 8 decimals every form is today's 8-byte u64 form, so every devnet hash, database row, p2p message and JSON field is unchanged byte for byte and no migration or version step exists; on a network at any other unit the forms are 16 bytes (or a decimal string in JSON). The unit is installed process-wide by the daemon from the params (unit::install_base_unit, read by unit::amount_wire_len); a fixed width per network keeps every hash injective (a width that varied with the value could collide in the UTXO commitment). The consensus digest, which carries the unit once it leaves 8, is what separates the networks at the handshake.

Format	At 8 decimals	At 18 decimals	Versioned by
Transaction hash and id, sighash, covenant id (Amount::consensus_bytes)	8 LE bytes, today's	16 LE bytes	the unit; no tx version (a network at 18 has no 8-byte history)
Coinbase payload subsidy field	8 bytes, today's layout	16 bytes; the mainnet and testnet genesis payloads are laid out so (one IGN = 10^18) and their hashes recomputed (GENESIS c93c6757..., TESTNET_GENESIS 494fc9a3...); the daemon refuses a genesis whose payload does not parse at the unit	the unit
UTXO commitment (muhash)	8 bytes	16 bytes	the unit
Stores (bincode of Amount: UTXO set, diffs, block transactions, virtual state fees, the UTXO index and its supply row)	8 bytes, today's rows; the pre-Toccata fixtures unchanged	16 bytes; a fresh network has no legacy rows, so no schema version (B3 found the draft's "store schema version" unnecessary)	the unit
p2p (p2p.proto)	uint64 value = 1 / amount = 1 as today, byte-identical (a fixture encoded on the base tree is asserted)	the low word on field 1 plus value_hi (field 4) and amount_hi (field 6), absent when zero; a non-zero high word on an 8-decimal network is a conversion error	no PROTOCOL_VERSION bump (16 stays; the draft's 17 would have split the live devnet for nothing)
gRPC (rpc.proto)	as today	amountHi, feeHi, valueHi, rewardAmountHi optional pairs; the same high-word rule	additive fields
wRPC borsh	8 bytes, today's	16 bytes	no serializer version step: each struct's own version byte stays; there is no central RPC serializer version (B5)
JSON RPC, wasm	a JSON number, today's shape	a decimal string; wasm getters hand out BigInt	the unit
Script numbers (KIP-10 introspection)	8-byte numbers, today's errors	16-byte numbers for the whole numeric family (i128 inside), so a 10 IGN output introspects	the unit (B8)

4. The EVM side

1 IGN = 10^18 wei, the base unit. Params::wei_per_unit() is 1 at 18 decimals and 10^10 at 8 (today's WEI_PER_SOMPI, which the widening replaces). The executor credits Amount::to_wei(decimals) of the producer and pool shares; the pool escrow, the payouts, the fee splits and the aggregator share are already in wei and do not change. The SP1 guest's statement carries rewards and payouts in wei and changes only at the input type, so the shard program id moves once, at the testnet genesis, where it is pinned fresh anyway; the devnet's pinned id is untouched.

5. What it costs (measured on igneum-build-1, 6 October 2026, consensus/core/src/unit_measure.rs, 1,000,000 synthetic UTXOs of the devnet's shape)

	8 decimals (u64)	18 decimals (u128)	Difference
UTXO set, serialised + 35-byte key	97 B per entry, 97.0 MB	105 B per entry, 105.0 MB	+8 B, +8.25 percent
size_of the entry	112 B	128 B	+16 B (alignment to 16)
Resident memory, 1,000,000 Arc entries	151 B per entry, 152 MB	168 B per entry, 168 MB	+17 B, +10.6 percent
Wire, per output (protobuf overhead included)	6.0 B (varint)	12.4 B (two varints) or 18 B (16-byte bytes)	+6.4 B or +12 B
Wire, a 2-output transaction			+12.8 B or +24 B
Wire as built (B4, two uint64 words, a fixed two-output transaction message)	233 B	245 B	+12 B (+6.0 per output; +7 B above 2^64, +5 B below it)
Wire as built, a UTXO entry message	48 B	55 B	+7 B

Consequences by tier. A home miner's node at 10,000,000 UTXOs (approximate; Kaspa's set is of that order) holds 80 MB more on disk and 170 MB more in memory, against a 1 GiB dataset and a 2 to 4 GB node: no tier changes class, on 8 GB cards or on 32 GB, on Windows, Linux or macOS. A pool or rig node is the same number. At 1 block a second and 100 transactions a block the wire grows 1.3 KB a second with two varints, 110 MB a day; at the 10 BPS step 1.1 GB a day, which is why two varints are the recommendation and not the fixed 16 bytes. Nothing changes for a miner's hash rate, power or deadline. For a wallet or exchange the number is the same as Ethereum's, which is the point.

6. Display

The app and the wallet show IGN with up to 8 digits after the point (unit::VISIBLE_DECIMALS), truncated toward zero, trailing zeros trimmed, no point on a whole number; a user never sees 18 digits (Amount::format_ign: 31,688,087,814,028,950,237 wei reads "31.68808781", the same as the 8-decimal 3,168,808,781 sompi). An amount under 10^-8 IGN reads "0"; a tooltip or a detail view may use format_ign_visible(decimals, 18). Input is parse_ign: digits, one point, at most decimals fraction digits, no float anywhere (the wallet's sompi_to_kaspa f64 helpers are retired at the widening; pool/src/payout.rs and prover.rs keep as f64 / 1e18 for log lines only).

7. Hostile review

Attack or slip	Finding	Answer
Overflow at a multiplication	proving_pool_share (u64) multiplies by 20 before dividing: overflows above 9.2 x 10^17 sompi, unreachable at 8 decimals (above the cap) and reached by the first full-rate block at 18	Amount::percent splits quotient and remainder; the u128 family is exact to u128::MAX (tested)
The launch ramp	launch_ramp goes through u128 and back to u64; at 18 the result itself is above u64	launch_ramp_units with a checked product and an overflow-free fallback (tested at u128::MAX)
The subsidy table	SUBSIDY_PERIODS = 33 is a property of the 8-decimal base (31 bits); at 18 the base is 65 bits and the table is 66 long	subsidy_periods_units(decimals), per_second_subsidy_units with a shift that is zero at 128 and above, never a wrap (tested); the economy lane's EmissionSchedule computes in u128 and is rescaled to the unit
The genesis block	block 1 merges the genesis and reads its coinbase payload for the rewards; a payload laid out at 8 bytes misparses at 18	the mainnet and testnet genesis payloads carry a 16-byte subsidy (hashes recomputed; igneum-testnet-1's genesis must be re-cut on this layout by the testnet lane); the daemon refuses a genesis that does not parse at the unit, so an override file cannot move a devnet's unit over an 8-byte genesis
The inherited Kaspa wallet	wallet/, cli/ and rothschild keep u64 types and meet Amount through pending_u64() (26 sites)	Igneum ships none of them (igneumd, igneum-miner and the app never link them; the Igneum wallet is the testnet-wallet lane); tools/ci/base-unit-pending-check.sh excludes them by rule and counts everything the node runs (0 sites)
Reds in the execution layer	the executor credits producer shares to blue blocks only, while the UTXO coinbase pays a red's 80 percent to the merging miner	pre-existing, not a unit matter; noted for the exec lane
The floor at the finer unit	18 decimals mints 4,028,950,237 wei a second more than 10^10 x the 8-decimal rate (the 8-decimal floor drops them); the display agrees to 8 digits	stated; the total stays under the cap by under 100 IGN at both units (tested)
Storage mass constants assume sompi	C = 10,000 IGN = 10^12 sompi; at 18 it is 10^22, above u64, and C x p^2 at the script-length plurality bound (100) is 10^26	storage_mass_parameter_units(), calc_storage_mass_units in u128; the formula is scale-free, so a transaction weighs the same at both units (tested on the KIP-9 vectors and the three paths); the one floor at the unit (the mean input) can move the answer by at most the input plurality
Dust	KIP-9 refuses a one-unit output by mass (C x p^2 / 1 = 10^22 at 18, saturated to u64::MAX, over every limit), the same answer as 10^12 at 8; the relay floor DEFAULT_MINIMUM_RELAY_TRANSACTION_FEE = 100,000 sompi per kilogram is a unit-bearing constant	the mass rule holds at both units (tested); the relay floor becomes 10^-3 IGN per kilogram at the network's unit, a mempool constant, not consensus
MAX_SOMPI	4 x 10^9 x 10^8 as a transaction cap; at 18 it is 4 x 10^27 and a tail removes its meaning	supply_cap_units() for the check, or the check goes at the widening; nothing in the type depends on it
Script numbers	KIP-10 introspection pushes amounts as i64 script numbers; a wei amount above 2^63 (9.22 IGN at 18 decimals) does not fit	Decided and shipped in B8 (7 October 2026): a script number is 8 bytes at 8 decimals and 16 bytes on any other unit (kaspa_txscript::script_num_len, keyed on the unit like the hashes, not on the tx version); OpTxInputAmount and OpTxOutputAmount push at that width and every numeric opcode runs in i128 and refuses a result the width does not hold; the two opcodes alone would not do (a covenant subtracts and compares one opcode later); tested with the KIP-10 examples at both widths, the devnet's bytes and errors unchanged
JavaScript precision	a JSON number above 2^53 rounds	Amount is a string in JSON (tested)
A peer on the other unit	its coinbases differ by 10^10	the unit is in the digest once it leaves 8; the handshake refuses it (tested)
A half-widened binary starts the testnet	the coinbase, the UTXO value and the wire still carry u64	IMPLEMENTED_DECIMALS = [8]; igneumd refuses to start a network whose unit it cannot mint (section 8)
Postgres bigint in the observer	i64 overflows at one 18-decimal block	numeric at the widening

8. What landed (phase B, 6 to 7 October 2026) and what is left

Fork branch decimals on the box mirror (every commit built and its crates' suites run on igneum-build-1; the two pre-existing reds igneum_m20_tests::witnesses_are_checked_in_epoch_order_under_their_own_seeds and the ban_is_decided_by_the_carrying_block flake skipped, both red on the untouched eec34ac3):

Step	Commit	What
the type	3158571c	unit::Amount and every byte form
the parameter and the schedule	fa61e035	base_unit_decimals in Params, overrides, the digest once not 8; the schedule at any unit
the mass rule	fcd6b6e9	calc_storage_mass_units
the measurement	6d5f2488	section 5
the economy lane	6ffd5451	merge of tail-emission-node 486895d6: one schedule, rescaled to the unit
the width rule	a91fb532	every amount form follows the network's unit; the devnet byte-identical
B1	472664dc	output value, entry amount, mass cells, fees in Amount; hashes through consensus_bytes; u128 rules
B2	eea7971a	the coinbase: subsidy, payload width, manager on the u128 table
B6	20a6fd64	the mempool: fee keys, relay floor at the unit, template fees
B9a	c217eff0	the inherited wallet crates compile at the boundary
B7	637dbfab	the exec bridge: execute_segment(Amount), to_wei at the installed unit, the guest untouched
B3	fa40457a (d98e4f8c, 431390e2)	stores and the UTXO index
B4	8d642f53	p2p: the low and high words, no protocol version bump
B5	b8e5b627 (ec3560da)	RPC: model, converters, gRPC pairs, wRPC, JSON, wasm
B8	23851be1 (65961e3c)	script numbers at the network's width
B10a	0f649f6b	IMPLEMENTED_DECIMALS = [8, 18]; the genesis payloads at 16 bytes; the daemon's genesis check
the miner	df2fbd03	inspect at the network's width; testnet and mainnet prefixes

Suites on the merged tree (release, igneum-build-1): consensus-core 139, consensus 109, txscript 158 + 3, mining 52, rpc-core 134, grpc-core 14, p2p 22 and 33, pow 15, miner 18, exec 22, utxoindex 9, index-core 9, database 22, pskt 5, kaspad 2, db_compat 7; the workspace checks with every target but the two inherited rpc_core_mock.rs files (the finality methods, red on the base tree). tools/ci/base-unit-pending-check.sh: no pending_u64() site in anything the node runs; 26 remain in the inherited Kaspa wallet, cli and rothschild, excluded by rule (Igneum ships none of them; the Igneum wallet is the testnet-wallet lane's).

The Igneum side (repository branch decimals): the observer reads the payload at the network's width and keeps amounts in numeric; the pool reads the subsidy from the installed table in u128 and bridges by the installed unit (it builds against vendor/igneum-node, so it compiles once the fork lands there: unverified tonight); the app's user strings are hash rates and addresses, its reward lines log wei as f64 (no change); site/api/public-stats keeps decimals_consensus: 8 for the devnet it serves and reads the network's unit when the testnet observer exists.

B10, the gate (tools/fleet/base-unit-gate.sh): two nodes on the testnet params on igneum-build-1 start at 18 decimals (the daemon prints Base unit: 10^18 base units per IGN (wei, the EVM's unit), digest 57c4c924...), peer, and mine with the CPU engine; the checks are in the script's header. The CPU engine does 0.147 MH/s on 32 threads against the testnet's 2^28 expected hashes a block, so a block takes 10 to 30 minutes on the box: the hour-long CPU form (MIN_BLOCKS 3) is what runs tonight; the ten-minute, hundreds-of-blocks form needs a GPU wave box from the fleet lane and the same script. Result: appended below when the run ends.

What is left after B10:

• igneum-testnet-1's genesis: the testnet lane re-cuts it on the 16-byte payload layout (the hash in this tree, 494fc9a3..., is the PROPOSED genesis re-laid; the lane's FINAL genesis 87617621... was cut on the 8-byte layout and cannot start at 18).
• the pool's build against the fork (one cargo check when the fork lands in vendor/igneum-node).
• the Igneum wallet lane: amounts as Amount, format_ign for display, parse_ign for input (section 6).
• the inherited Kaspa wallet and cli: 26 pending_u64() sites, if they are ever shipped.
• the exec layer pays producer shares to blue blocks only while the UTXO coinbase pays a red's share to the merging miner (pre-existing; the exec lane's).