From 94ce15d233fd50873afaa979cc9a062d467d72ef Mon Sep 17 00:00:00 2001 From: Nicholas Dudfield Date: Fri, 13 Feb 2026 12:47:22 +0700 Subject: [PATCH] docs(consensus): add extraction markers for guided code review Add @@start/@@end comment markers to key RNG pipeline sections for automated documentation extraction. No logic changes. --- src/ripple/app/consensus/RCLConsensus.cpp | 10 ++++++++++ src/ripple/app/consensus/RCLCxPeerPos.h | 6 ++++++ src/ripple/app/ledger/impl/BuildLedger.cpp | 2 ++ src/ripple/app/tx/impl/Change.cpp | 2 ++ src/ripple/consensus/Consensus.h | 2 ++ 5 files changed, 22 insertions(+) diff --git a/src/ripple/app/consensus/RCLConsensus.cpp b/src/ripple/app/consensus/RCLConsensus.cpp index fa778ad07..b467aed28 100644 --- a/src/ripple/app/consensus/RCLConsensus.cpp +++ b/src/ripple/app/consensus/RCLConsensus.cpp @@ -1268,6 +1268,7 @@ RCLConsensus::Adaptor::hasAnyReveals() const uint256 RCLConsensus::Adaptor::buildCommitSet(LedgerIndex seq) { + //@@start rng-build-commit-set auto map = std::make_shared(SHAMapType::TRANSACTION, app_.getNodeFamily()); map->setUnbacked(); @@ -1320,11 +1321,13 @@ RCLConsensus::Adaptor::buildCommitSet(LedgerIndex seq) JLOG(j_.debug()) << "RNG: built commitSet SHAMap hash=" << hash << " entries=" << pendingCommits_.size(); return hash; + //@@end rng-build-commit-set } uint256 RCLConsensus::Adaptor::buildEntropySet(LedgerIndex seq) { + //@@start rng-build-entropy-set auto map = std::make_shared(SHAMapType::TRANSACTION, app_.getNodeFamily()); map->setUnbacked(); @@ -1374,6 +1377,7 @@ RCLConsensus::Adaptor::buildEntropySet(LedgerIndex seq) JLOG(j_.debug()) << "RNG: built entropySet SHAMap hash=" << hash << " entries=" << pendingReveals_.size(); return hash; + //@@end rng-build-entropy-set } void @@ -1684,6 +1688,7 @@ RCLConsensus::Adaptor::injectEntropyPseudoTx( uint256 finalEntropy; bool hasEntropy = false; + //@@start rng-inject-entropy-selection // Calculate entropy from collected reveals if (app_.config().standalone()) { @@ -1738,7 +1743,9 @@ RCLConsensus::Adaptor::injectEntropyPseudoTx( << " for ledger " << seq; } } + //@@end rng-inject-entropy-selection + //@@start rng-inject-pseudotx // Synthesize and inject the pseudo-transaction if (hasEntropy) { @@ -1760,6 +1767,7 @@ RCLConsensus::Adaptor::injectEntropyPseudoTx( retriableTxs.insert(std::make_shared(std::move(tx))); } + //@@end rng-inject-pseudotx // Reset RNG state for next round clearRngState(); @@ -1779,6 +1787,7 @@ RCLConsensus::Adaptor::harvestRngData( << " commit=" << (position.myCommitment ? "yes" : "no") << " reveal=" << (position.myReveal ? "yes" : "no"); + //@@start rng-harvest-trust-and-reveal-verification // Reject data from validators not in the active UNL if (!isUNLReportMember(nodeId)) { @@ -1855,6 +1864,7 @@ RCLConsensus::Adaptor::harvestRngData( << *position.myReveal; } } + //@@end rng-harvest-trust-and-reveal-verification // Store proposal proofs for embedding in SHAMap entries. // commitProofs_: only seq=0 (commitments always ride on seq=0, diff --git a/src/ripple/app/consensus/RCLCxPeerPos.h b/src/ripple/app/consensus/RCLCxPeerPos.h index 67dd86d32..2ac020425 100644 --- a/src/ripple/app/consensus/RCLCxPeerPos.h +++ b/src/ripple/app/consensus/RCLCxPeerPos.h @@ -105,6 +105,7 @@ struct ExtendedPosition // entropy result is verified deterministically from collected reveals. // - Leaves (myCommitment, myReveal) are also excluded — they are // per-validator data unique to each proposer. + //@@start rng-extended-position-equality bool operator==(ExtendedPosition const& other) const { @@ -141,8 +142,10 @@ struct ExtendedPosition { return pos.txSetHash != hash; } + //@@end rng-extended-position-equality // CRITICAL: Include ALL fields for signing (prevents stripping attacks) + //@@start rng-extended-position-serialize void add(Serializer& s) const { @@ -173,6 +176,7 @@ struct ExtendedPosition if (myReveal) s.addBitString(*myReveal); } + //@@end rng-extended-position-serialize Json::Value getJson() const @@ -191,6 +195,7 @@ struct ExtendedPosition Returns nullopt if the payload is malformed (truncated for the flags advertised). */ + //@@start rng-extended-position-deserialize static std::optional fromSerialIter(SerialIter& sit, std::size_t totalSize) { @@ -235,6 +240,7 @@ struct ExtendedPosition return pos; } + //@@end rng-extended-position-deserialize }; // For logging/debugging - returns txSetHash as string diff --git a/src/ripple/app/ledger/impl/BuildLedger.cpp b/src/ripple/app/ledger/impl/BuildLedger.cpp index b7a86bb50..8f0fce762 100644 --- a/src/ripple/app/ledger/impl/BuildLedger.cpp +++ b/src/ripple/app/ledger/impl/BuildLedger.cpp @@ -104,6 +104,7 @@ applyTransactions( bool certainRetry = true; std::size_t count = 0; + //@@start rng-entropy-first-application // CRITICAL: Apply consensus entropy pseudo-tx FIRST before any other // transactions. This ensures hooks can read entropy during this ledger. for (auto it = txns.begin(); it != txns.end(); /* manual */) @@ -142,6 +143,7 @@ applyTransactions( it = txns.erase(it); break; // Only one entropy tx per ledger } + //@@end rng-entropy-first-application // Attempt to apply all of the retriable transactions for (int pass = 0; pass < LEDGER_TOTAL_PASSES; ++pass) diff --git a/src/ripple/app/tx/impl/Change.cpp b/src/ripple/app/tx/impl/Change.cpp index 94694cf5c..0487ad4e1 100644 --- a/src/ripple/app/tx/impl/Change.cpp +++ b/src/ripple/app/tx/impl/Change.cpp @@ -238,6 +238,7 @@ Change::applyConsensusEntropy() { auto const entropy = ctx_.tx.getFieldH256(sfDigest); + //@@start rng-consensus-entropy-sle-write auto sle = view().peek(keylet::consensusEntropy()); bool const created = !sle; @@ -255,6 +256,7 @@ Change::applyConsensusEntropy() view().insert(sle); else view().update(sle); + //@@end rng-consensus-entropy-sle-write JLOG(j_.info()) << "ConsensusEntropy: updated entropy to " << entropy << " at ledger " << view().info().seq; diff --git a/src/ripple/consensus/Consensus.h b/src/ripple/consensus/Consensus.h index 715f68e41..65ebd1004 100644 --- a/src/ripple/consensus/Consensus.h +++ b/src/ripple/consensus/Consensus.h @@ -1409,6 +1409,7 @@ Consensus::phaseEstablish() return; } + //@@start rng-phase-establish-substates // --- RNG Sub-state Checkpoints (if adaptor supports RNG) --- // These sub-states use union convergence (not avalanche). // Commits and reveals arrive piggybacked on proposals, so by the time @@ -1590,6 +1591,7 @@ Consensus::phaseEstablish() return; } } + //@@end rng-phase-establish-substates JLOG(j_.info()) << "Converge cutoff (" << currPeerPositions_.size() << " participants)";