From ddfb1dbeb66feff23cee785061968f3394a6087f Mon Sep 17 00:00:00 2001
From: Nicholas Dudfield <ndudfield@gmail.com>
Date: Tue, 23 Jun 2026 16:42:05 +0700
Subject: [PATCH] docs: clarify entropy and runtime test APIs

---
 hook/extern.h                      | 12 ++++++++++++
 src/xrpld/app/misc/RuntimeConfig.h | 21 ++++++++++++++++++---
 2 files changed, 30 insertions(+), 3 deletions(-)

diff --git a/hook/extern.h b/hook/extern.h
index 3b6e1e419..f527df2a4 100644
--- a/hook/extern.h
+++ b/hook/extern.h
@@ -352,6 +352,18 @@ xport(
 extern int64_t
 xport_cancel(uint32_t ticket_seq);
 
+/*
+    Consensus entropy APIs.
+
+    min_tier is a fail-closed floor:
+      1 = consensus_fallback, 2 = participant_aligned, 3 = validator_quorum.
+    min_count is the minimum validator/reveal count the caller accepts.
+
+    If the most recent finalized entropy object does not satisfy both floors,
+    these APIs return TOO_LITTLE_ENTROPY. Open-ledger and simulate execution
+    are provisional previews over the entropy currently visible to the node;
+    final ordered ledger execution may see a different entropy object.
+*/
 extern int64_t
 dice(uint32_t sides, uint32_t min_tier, uint32_t min_count);
 
diff --git a/src/xrpld/app/misc/RuntimeConfig.h b/src/xrpld/app/misc/RuntimeConfig.h
index 6e8f6511e..c8a89a70f 100644
--- a/src/xrpld/app/misc/RuntimeConfig.h
+++ b/src/xrpld/app/misc/RuntimeConfig.h
@@ -152,21 +152,36 @@ public:
     std::optional<ConsensusTestConfig>
     getConsensusTestConfig() const;
 
-    /** Set daemon-wide consensus/export test config. */
+    /** Set daemon-wide consensus/export test config.
+
+        Direct setters are for in-process tests and test harnesses. External
+        env/RPC mutation is compile-gated; production code should not call
+        these as a runtime configuration surface.
+    */
     void
     setGlobalConfig(ConsensusTestConfig const& cfg);
 
     void
     clearGlobalConfig();
 
-    /** Set default peer send fault config. */
+    /** Set default peer send fault config.
+
+        Direct setters are for in-process tests and test harnesses. External
+        env/RPC mutation is compile-gated; production code should not call
+        these as a runtime configuration surface.
+    */
     void
     setPeerDefaults(PeerFaultConfig const& cfg);
 
     void
     clearPeerDefaults();
 
-    /** Set config for one peer key (without the "peer:" prefix). */
+    /** Set config for one peer key (without the "peer:" prefix).
+
+        Direct setters are for in-process tests and test harnesses. External
+        env/RPC mutation is compile-gated; production code should not call
+        these as a runtime configuration surface.
+    */
     void
     setPeerConfig(std::string const& peerAddress, PeerFaultConfig const& cfg);