docs: update base layer RFCs (5.1–5.15.6) to match mainnet v5.5.0#191
Merged
SWvheerden merged 10 commits intoJul 24, 2026
Conversation
- Index page: two PoW algorithms -> four (RandomXM, Sha3x, RandomXT, Cuckaroo) with 120s combined target; fix miner list (minotari_miner, minotari_merge_mining_proxy) - RFC-0131: linear (not log) weighted moving average; LWMA target 800s -> 480s; mining hash fields add block_output_mr/validator_node_mr/validator_node_size, remove phantom witness_mr; genesis header version 1 -> 0; C29 uses big-endian difficulty - RFC-0132: four mining algorithms; merge mining hash is Blake2b-256 over 14 header fields; MoneroPowData struct updated (8 fields); MerkleProof has no depth field; serialization is Borsh (not Monero varint); fix proxy link path
- Block header fields: remove phantom witness_mr, rename script_kernel_offset -> total_script_offset and validator_size -> validator_node_size - Output_mmr_size -> Output_smt_size (sparse Merkle tree / JMT, not MMR) - block_output_mr construction (coinbase hashes + non-coinbase MMR root) - coinbase extra data 64 -> 256 bytes - nonce=0 applies to RandomX-M only (not RandomX-T) - pow_data formats added for RandomX-T and Cuckaroo; C29 -> Cuckaroo (C29) - difficulty: T varies by height (240/360/480); ST_max = 6xT (not fixed 2880) - 'two PoW algorithms' -> four independent algorithms - FTL hardcoded 540 (T_chain*N/20, not per-algo T*N/20) - MTP uses median_timestamp_count (11), not difficulty window N - accumulated difficulty: Cuckaroo conditionally included (height 126000+)
- Specification: varint (Base 128) encoding -> Borsh (fixed little-endian with 4-byte LE length prefixes for Vec/array) - Block field ordering: match Borsh struct declaration order; remove phantom witness Merkle root; add block_output_mr, validator_node_mr, validator_node_size; rename Output MMR size -> Output SMT size - Block Header table: same field corrections + reordering - PoW algorithm description: (Monero or SHA3) -> four algorithms (0-3) - Hash domains: remove witness MMR; output MMR -> sparse Merkle tree (JMT)
- chain_metadata: height_of_longest_chain -> best_block_height; best_block 32-bit -> best_block_hash 256-bit; accumulated_difficulty 128-bit -> 512-bit - Add base node state machine states (Starting/DecideNextSync/Waiting/Shutdown) and DecideNextSync strategy selection - Complete sync: block download starts from local best block (not oldest) - Horizon sync: kernels/UTXOs downloaded forwards (not tip->horizon); UTXO MMR -> Jellyfish Merkle Tree; balance equation expanded; finalize step - Keeping in sync: chain length -> accumulated difficulty; add BehindButNotYetLagging thresholds - Reorg bounded by max_reorg_depth_allowed (10000); pruning gated by pruning_interval with background task; archival = pruning_horizon 0
- RFC-0172: Noise IX -> XX (+prologue); add TorTcp/TcpTor/Memory transports; bitflags PROTOCOL_NOT_SUPPORTED -> NOT_SUPPORTED; DHT_STORE_FORWARD legacy; MessageHeader types (u8->int32, u32->uint64); fix PongPong typo; add Chat/Text/TextAck message types; SAF messages deprecated; fixed zero nonce (not CSRNG); broadcast strategies (split Direct, remove ClosestNodes) - RFC-0173: Network enum (remove Ridcully/Stibbons/Weatherwax/Dibbler, add StageNet/NextNet); LIVENESS_WIRE_MODE 0xa6 -> 0xa7; wire byte != discriminant - RFC-0170: Hamming distance -> XOR/Kademlia; address table -> Multiaddr - RFC-0174: fix 'Depricated' -> 'Deprecated'; note chat metadata never implemented
- Mempool sync is bidirectional inventory-based (initial_sync_num_peers=2, initial_sync_max_transactions=10000), not a simple pull; no persistence - Reorg pool queryable via public interface; reorg handling is local (drain+revalidate unconfirmed pool, discard double-spends) - Reorg expiry is block-height based (expiry_height=5) - Duplicate-UTXO transactions coexist; resolved at block construction - Fee threshold is min_fee (50 uT), not min priority - Priority is a composite key (fee/gram, age, sig tiebreaker) - Storage capacity only for unconfirmed pool (40000); reorg uses expiry height - Orphan/dependent transaction support; published block discards conflicts - Propagation only for UnconfirmedPool-stored transactions
- RFC-0110: fix weight pseudocode PER_INPUT_GRAMS(9) -> 8 (matches table/code) - RFC-0111: remove store-and-forward description (SAF removed); note UTXO set is now a Jellyfish Merkle Tree (JMT) backed by LMDB
- RFC-0181 (Bulletproofs+): verified accurate (Ristretto, BulletProofPlus, 64-bit) - RFC-0182 (Commitment signatures): fix broken cross-ref RFC-0120_TariScript -> RFC-0201_TariScript; status image draft -> stable (matches Implemented)
- Script max serialised length 1024 -> 512 bytes (consensus-enforced; TariScript library hard-caps parsing at 4096 bytes) - Opcode set verified to exactly match code (all 33 opcodes); stack height 255 confirmed. Covenants (RFC-0250), stealth addresses (RFC-0203) and hardware transactions (RFC-0205) verified implemented and accurate
m4r1m0
marked this pull request as ready for review
July 24, 2026 05:12
SWvheerden
approved these changes
Jul 24, 2026
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Description
Updates the base layer RFCs (sections 5.1–5.15.6) to match the current mainnet code (release
v5.5.0). Every change is verified against themainnetbranch oftari-project/tari(identical to tagv5.5.0) and cited tofile:linein the source.15 files changed across 10 logical commits (one per RFC cluster). Highlights:
RandomXM,Sha3x,RandomXT,Cuckaroo), all active on mainnet, with the 120 s combined target; fixed the miner list (minotari_miner,minotari_merge_mining_proxy).witness_mr; renamedscript_kernel_offset→total_script_offsetandvalidator_size→validator_node_size;Output_mmr_size→Output_smt_size(sparse Merkle tree / JMT); fixed MTP window (11, not 90), FTL (hardcoded 540, notT*N/20), difficultyT(varies by height: 240/360/480), and the accumulated-difficulty formula (Cuckaroo conditionally included from height 126 000); coinbase extra data 64 → 256 bytes; addedpow_dataformats for RandomX-T and Cuckaroo.MoneroPowDatastruct updated (8 fields);MerkleProofhas nodepthfield; serialization is Borsh (not Monero varint); proxy pathtari_merge_mining_proxy→minotari_merge_mining_proxy.witness_mr; addedblock_output_mr/validator_node_mr/validator_node_size;output_smt_size); PoW algorithm(Monero or SHA3)→ four (0–3); hash domains fixed.chain_metadatatypes fixed (best_block_hash256-bit,accumulated_difficulty512-bit,best_block_height); documentedDecideNextSync/state machine; horizon sync direction corrected; "UTXO MMR" → Jellyfish Merkle Tree; reorg bound (max_reorg_depth_allowed) and pruning interval documented.IX→XX(+prologue);Networkenum (removed Ridcully/Stibbons/Weatherwax/Dibbler, added StageNet/NextNet;LIVENESS_WIRE_MODE0xa6 → 0xa7); Hamming → XOR/Kademlia distance; addresses use Multiaddr;MessageHeadertypes fixed; added missing message types (Chat=2, Text=225, TextAck=226); store-and-forward marked removed/legacy; fixed zero nonce (not CSRNG); broadcast strategies corrected; RFC-0174 "Depricated" → "Deprecated" + noted as unimplemented.min_fee(50 uT); priority is a composite key; reorg expiry is block-height based.PER_INPUT_GRAMS(9)→ 8; removed store-and-forward description; noted UTXO set is a Jellyfish Merkle Tree backed by LMDB.RFC-0120_TariScript→RFC-0201_TariScript; status image draft → stable (matches Implemented).RFC-0181 (Bulletproofs+) and the wallets/addresses RFCs (5.7–5.9) were verified accurate against the code and left unchanged.
Motivation and Context
The base layer RFCs had fallen out of sync with the live mainnet code. The most visible example: the base layer index page stated Tari uses "two Proof of Work algorithms" (Monero merge-mining + SHA3x), while the released code defines and enables four (
RandomXM,Sha3x,RandomXT,Cuckaroo). Similar staleness affected block header fields, the consensus/difficulty constants, the serialization format, networking protocol details, and the mempool behaviour. This PR brings the documentation in line with the code that mainnet is currently running (v5.5.0), so the RFCs accurately describe the network as it operates today.How Has This Been Tested?
mainnetbranch oftari-project/tari(== tagv5.5.0, the live mainnet release), withfile:linecitations.mdbook build: the book builds cleanly (exit 0) after all changes; no broken links or structure errors.witness_mr,800 seconds,Noise_IX,Hamming distance,Depricated,PROTOCOL_NOT_SUPPORTED,height_of_longest_chain, or32-bitblock-hash references remain in the updated RFCs.