UTXO commitment (LOKAD "UTXO")
The fingerprint of the whole UTXO set written into every coinbase from the Napoleon upgrade.
From Napoleon, the coinbase of every block carries the fingerprint of the UTXO set: a MuHash3072 digest of every unspent coin as it was 10 blocks earlier, in an eMPP segment with the LOKAD id UTXO. Every node recomputes it from its own coins and rejects a block whose commitment is wrong. It is what lets a UTXO snapshot (and a thin node) be trusted by proof of work instead of by a hash pinned in a release or a quorum of peers. This is a consensus rule, not an indexer module. The design and the choices behind it are in doc/research/utxo-commitment.md. The dashboard page is Developers › UTXO snapshots (/dashboard/developers/utxo).
Status in this node #
| Item | Value |
|---|---|
| Kind | Consensus rule (block validity) from Napoleon. No SQLite table, no module entry in /api/v1/modules. |
| Activation | IsUtxoCommitmentEnabled = Napoleon is active for the block (src/consensus/utxocommitment.cpp:163-166). Mainnet median time past 1797886200 = 2026-12-21 20:50 UTC; testnet 21 days earlier; the Napoleon testnet from block 1. |
| Mandatory | From Napoleon itself on mainnet, testnet and the Napoleon testnet (utxoCommitmentMandatoryAtNapoleon, src/chainparams.cpp:171, :371, :511). Regtest: optional but checked when present (src/chainparams.cpp:665); -utxocommitmentmandatorytime=<mtp> makes it mandatory there and is refused on mainnet (src/init.cpp:3210). |
| First block | Block 10 (it commits to the set after block 0). Below height 10 a segment is invalid (UtxoCommittedHeight, src/consensus/utxocommitment.cpp:186-191). |
| Tracker | CChainState::m_utxo_hash (src/node/utxohashtracker.h): always on, updated per block from the block and its undo data, keeps the state of the last 74 blocks (k + 64). |
| Miner | Always written from Napoleon where mandatory; -utxocommitmine (default on) where optional (src/miner.cpp:440-450). getblocktemplate hands external pools the exact output and segment (coinbasetxn.utxocommitment, src/rpc/mining.cpp:1165-1179). |
| Data file | none (the tracker's state is the meta key utxo_hash_state of chainstate.sqlite) |
Envelope #
The segment rides in an eMPP output (OP_RETURN OP_RESERVED <push>..., see eMPP). Our miner writes it in its own output; it may also be one push inside another eMPP output of the coinbase, the POOL record included.
own output (46 bytes): 6a 50 2b <segment of 43 bytes>
OP_RETURN OP_RESERVED push(43)Byte layout #
| Offset | Size | Type | Endianness | Field | Notes |
|---|---|---|---|---|---|
| 0 | 4 | ASCII | n/a | LOKAD id | 55 54 58 4f = UTXO (UTXO_COMMITMENT_LOKAD, src/consensus/utxocommitment.h:51) |
| 4 | 1 | uint8 | n/a | version | 01. Any other version is reserved and ignored by this release (a later commitment, for example an accumulator root, can be added as a soft fork). |
| 5 | 1 | uint8 | n/a | section length | 01 |
| 6 | 1 | ASCII | n/a | section | 4d = M (MuHash3072) |
| 7 | 4 | uint32 | little-endian | committed height | must be the block height − 10 |
| 11 | 32 | bytes | SHA-256 output order | digest | the MuHash3072 digest of the UTXO set after the committed block. The RPC and REST show it reversed, as a uint256 (GetHex). |
Total: 43 bytes (UTXO_COMMITMENT_SEGMENT_SIZE, src/consensus/utxocommitment.h:59).
The digest is the one gettxoutsetinfo muhash and the UTXO snapshot trailer give: every coin is serialized as txid (32) || vout (u32 LE) || u32 LE (height × 2 + coinbase) || amount (i64 LE) || compact size || script, hashed with SHA-256, mapped to 3072 bits with ChaCha20 and multiplied into a running product modulo 2^3072 − 1103717; spending a coin divides it out. The digest is the SHA-256 of the 384-byte value. Provably unspendable outputs (OP_RETURN) are never in the set.
Validation rules #
All in CChainState::CheckUtxoCommitment (src/validation.cpp:2485-2587), reading the coinbase with ScanUtxoCommitment (src/consensus/utxocommitment.cpp:89-127), whose eMPP parser is a copy of the module's, pinned to it by a test, so a module change never changes consensus.
- Before Napoleon nothing is read: the block is byte-for-byte what 12.4.11 accepts.
- Every coinbase output that is a well-formed eMPP envelope (canonical pushes, each at least 4 bytes) is read; a malformed envelope is ignored as a whole.
- A
UTXOsegment with no version byte, or a version-1 segment that is not exactly 43 bytes with sectionM:bad-utxo-commitment-malformed. - Two version-1 segments anywhere in the coinbase:
bad-utxo-commitment-duplicate. - No segment while the rule is mandatory:
bad-utxo-commitment-missing. - A segment below height 10:
bad-utxo-commitment-early. - The committed height must be the block height − 10:
bad-utxo-commitment-height. - The digest must equal this node's hash of the set after the committed block:
bad-utxo-commitment. Before rejecting, the node recomputes its own state from the coins once per tip, so a corrupt tracker never makes it reject a valid block; a missing local state never marks a block invalid (the block is retried). UTXOis a reserved coinbase tag (IsReservedCoinbaseTag,src/miner.cpp:87).
Why k = 10 #
The value for block h is known as soon as block h − 10 is connected, so a pool switching to a new tip never waits for it; a reorganization shorter than 10 blocks (the maximum reorganization depth) never changes it. Snapshots and thin nodes need deep burial anyway: a snapshot of the set at height H is checked against the coinbase of block H + 10, itself buried under at least 100 blocks by default.
RPC and REST #
| Interface | Answer |
|---|---|
getutxocommitment ( height recheck ) (src/rpc/blockchain.cpp:1506) | enabled, mandatory, present, committed_height, committed_blockhash, muhash, vout, local_muhash and match (while this node keeps that height), tracker {ready, height, muhash, kept}; with recheck a full walk of the coins compared with the tracker. |
verifyutxocommitment muhash height ( minconf=100 ) (src/rpc/blockchain.cpp:1658) | Checks a UTXO set hash (for example a snapshot's) for the set after height against the commitment of block height + 10, buried at least minconf deep: valid, reason, confirmations, committed_muhash. |
GET /api/v1/chain/utxo-commitment/<height> (src/api/chain_handler.cpp:598) | getutxocommitment <height>; with ?muhash=<hex>[&minconf=<n>], verifyutxocommitment. Read-only, cached 10 s, listed in /api/v1/openapi.json. |
getblocktemplate | coinbasetxn.utxocommitment {committed_height, muhash, scriptPubKey, segment} from Napoleon. |
What the dashboard shows #
- Developers › UTXO snapshots (
share/www/dashboard/js/utxo-page.js): the activation status, this node's UTXO set hash and height, the commitments of the last blocks with this node's agreement, the segment of the latest one decoded byte by byte in the browser, and the UTXO snapshots when the node serves them (feature-detected from/api/v1/openapi.json). - Block page: a "UTXO commitment" card (committed height, digest, agreement). Transaction page of a coinbase: the
UTXOsegment card, linking to the page. - The eMPP module indexes the segment like any other: Protocols › eMPP › By LOKAD lists it under
UTXO.
Not covered here #
UTXO snapshots themselves (dumptxoutset, loadtxoutset, periodic snapshots, chunked download, quorum and commitment trust) ship in the release after 12.4.12; their design is doc/utxo-snapshot.md on that release.
