comments update

Signed-off-by: Pratik Mankawde <3397372+pratikmankawde@users.noreply.github.com>

.github/scripts/strategy-matrix/generate.py

@@ -235,16 +235,14 @@ def generate_strategy_matrix(all: bool, config: Config) -> list:
         # Add the configuration to the list, with the most unique fields first,
         # so that they are easier to identify in the GitHub Actions UI, as long
         # names get truncated.
-        # Add Address and UB sanitizers as separate configurations for specific
-        # bookworm distros. Thread sanitizer is currently disabled (see below).
-        # GCC-Asan xrpld-embedded tests are failing because of https://github.com/google/sanitizers/issues/856
-        if os[
-            "distro_version"
-        ] == "bookworm" and f"{os['compiler_name']}-{os['compiler_version']}" in [
-            "gcc-15",
-            "clang-20",
-        ]:
-            # Add ASAN configuration.
+        # Add sanitizer jobs for specific bookworm distros.
+        # GCC sanitizers run independently because combining ASAN+UBSAN inflates
+        # GCC data sections past ASAN's 2GB shadow memory limit
+        # (see https://github.com/google/sanitizers/issues/856).
+        # Clang doesn't have this issue, so TSAN+UBSAN stay combined but ASAN and UBSAN are separated.
+        compiler_id = f"{os['compiler_name']}-{os['compiler_version']}"
+        if os["distro_version"] == "bookworm" and compiler_id == "gcc-15":
+            # Add separate ASAN, TSAN, and UBSAN configurations for GCC.
             configurations.append(
                 {
                     "config_name": config_name + "-asan",
@@ -257,7 +255,21 @@ def generate_strategy_matrix(all: bool, config: Config) -> list:
                     "sanitizers": "address",
                 }
             )
-            # Add UBSAN configuration.
+            # TSAN instrumentation significantly increases memory usage during
+            # compilation, so reduce build parallelism to avoid OOM on CI runners.
+            configurations.append(
+                {
+                    "config_name": config_name + "-tsan",
+                    "cmake_args": cmake_args,
+                    "cmake_target": cmake_target,
+                    "build_only": build_only,
+                    "build_type": build_type,
+                    "os": os,
+                    "architecture": architecture,
+                    "sanitizers": "thread",
+                    "nproc_subtract": 20,
+                }
+            )
             configurations.append(
                 {
                     "config_name": config_name + "-ubsan",
@@ -270,21 +282,47 @@ def generate_strategy_matrix(all: bool, config: Config) -> list:
                     "sanitizers": "undefinedbehavior",
                 }
             )
-            # TSAN is deactivated due to seg faults with latest compilers.
-            activate_tsan = False
-            if activate_tsan:
-                configurations.append(
-                    {
-                        "config_name": config_name + "-tsan-ubsan",
-                        "cmake_args": cmake_args,
-                        "cmake_target": cmake_target,
-                        "build_only": build_only,
-                        "build_type": build_type,
-                        "os": os,
-                        "architecture": architecture,
-                        "sanitizers": "thread,undefinedbehavior",
-                    }
-                )
+        elif os["distro_version"] == "bookworm" and compiler_id == "clang-20":
+            # Add combined ASAN+UBSAN and TSAN+UBSAN configurations for Clang.
+            configurations.append(
+                {
+                    "config_name": config_name + "-asan",
+                    "cmake_args": cmake_args,
+                    "cmake_target": cmake_target,
+                    "build_only": build_only,
+                    "build_type": build_type,
+                    "os": os,
+                    "architecture": architecture,
+                    "sanitizers": "address",
+                }
+            )
+            configurations.append(
+                {
+                    "config_name": config_name + "-ubsan",
+                    "cmake_args": cmake_args,
+                    "cmake_target": cmake_target,
+                    "build_only": build_only,
+                    "build_type": build_type,
+                    "os": os,
+                    "architecture": architecture,
+                    "sanitizers": "undefinedbehavior",
+                }
+            )
+            # TSAN instrumentation significantly increases memory usage during
+            # compilation, so reduce build parallelism to avoid OOM on CI runners.
+            configurations.append(
+                {
+                    "config_name": config_name + "-tsan-ubsan",
+                    "cmake_args": cmake_args,
+                    "cmake_target": cmake_target,
+                    "build_only": build_only,
+                    "build_type": build_type,
+                    "os": os,
+                    "architecture": architecture,
+                    "sanitizers": "thread,undefinedbehavior",
+                    "nproc_subtract": 20,
+                }
+            )
         else:
             configurations.append(
                 {

.github/workflows/reusable-build-test.yml

@@ -58,5 +58,6 @@ jobs:
       image: ${{ contains(matrix.architecture.platform, 'linux') && format('ghcr.io/xrplf/ci/{0}-{1}:{2}-{3}-sha-{4}', matrix.os.distro_name, matrix.os.distro_version, matrix.os.compiler_name, matrix.os.compiler_version, matrix.os.image_sha) || '' }}
       config_name: ${{ matrix.config_name }}
       sanitizers: ${{ matrix.sanitizers }}
+      nproc_subtract: ${{ matrix.nproc_subtract && matrix.nproc_subtract || 2 }}
     secrets:
       CODECOV_TOKEN: ${{ secrets.CODECOV_TOKEN }}

cmake/deps/Boost.cmake

@@ -61,3 +61,14 @@ if(enable_asan)
         INTERFACE BOOST_USE_ASAN BOOST_USE_UCONTEXT
     )
 endif()
+
+# TSAN also requires the ucontext backend so that Boost.Context uses
+# POSIX ucontext (not fcontext assembly) for fiber switching. This
+# allows TSAN to properly track context switches and avoids false positives.
+# These defines must match what Boost was compiled with (see conan/profiles/sanitizers).
+if(enable_tsan)
+    target_compile_definitions(
+        xrpl_boost
+        INTERFACE BOOST_USE_TSAN BOOST_USE_UCONTEXT
+    )
+endif()

cspell.config.yaml

@@ -103,6 +103,7 @@ words:
   - dxrpl
   - enabled
   - endmacro
+  - eventfd
   - exceptioned
   - Falco
   - fcontext

include/xrpl/basics/sanitizers.h

@@ -1,13 +1,31 @@
 #pragma once
 
-// Helper to disable ASan/HwASan for specific functions
-/*
- ASAN flags some false positives with sudden jumps in control flow, like
- exceptions, or when encountering coroutine stack switches. This macro can be used to disable ASAN
- intrumentation for specific functions.
-*/
+// Helper to disable ASan/HwASan for specific functions.
+// ASAN flags some false positives with sudden jumps in control flow, like
+// exceptions, or when encountering coroutine stack switches. This macro can
+// be used to disable ASAN instrumentation for specific functions.
 #if defined(__GNUC__) || defined(__clang__)
 #define XRPL_NO_SANITIZE_ADDRESS __attribute__((no_sanitize("address", "hwaddress")))
 #else
 #define XRPL_NO_SANITIZE_ADDRESS
 #endif
+
+/** Detect whether a memory sanitizer (TSAN or ASAN) is active at compile time.
+ *
+ *  Evaluates to 1 when the translation unit is compiled with ThreadSanitizer
+ *  or AddressSanitizer instrumentation, 0 otherwise.
+ *
+ *  GCC defines __SANITIZE_THREAD__ / __SANITIZE_ADDRESS__ directly.
+ *  Clang uses __has_feature(thread_sanitizer) / __has_feature(address_sanitizer).
+ */
+#if defined(__SANITIZE_THREAD__) || defined(__SANITIZE_ADDRESS__)
+#define XRPL_SANITIZER_ACTIVE 1
+#elif defined(__has_feature)
+#if __has_feature(thread_sanitizer) || __has_feature(address_sanitizer)
+#define XRPL_SANITIZER_ACTIVE 1
+#else
+#define XRPL_SANITIZER_ACTIVE 0
+#endif
+#else
+#define XRPL_SANITIZER_ACTIVE 0
+#endif

include/xrpl/beast/core/List.h

@@ -307,7 +307,7 @@ public:
     reference
     front() noexcept
     {
-        return element_from(head_.next_);
+        return elementFrom(head_.next_);
     }
 
     /** Obtain a const reference to the first element.

include/xrpl/beast/test/yield_to.h

@@ -11,12 +11,34 @@
 #include <boost/thread/csbl/memory/allocator_arg.hpp>
 
 #include <condition_variable>
+#include <cstddef>
 #include <mutex>
 #include <thread>
 #include <vector>
 
 namespace beast::test {
 
+/** Stack size for yield_to coroutines.
+ *
+ *  Sanitizers significantly increase stack frame sizes
+ *  (TSAN ~3-5x, ASAN ~2-3x), requiring larger coroutine stacks.
+ *
+ *  @note This duplicates the detection logic from xrpl/basics/sanitizers.h
+ *        because xrpl.beast cannot depend on xrpl.basics (levelization
+ *        constraint).
+ */
+#if defined(__SANITIZE_THREAD__) || defined(__SANITIZE_ADDRESS__)
+inline constexpr std::size_t yieldStackSize = 2 * 1024 * 1024;
+#elif defined(__has_feature)
+#if __has_feature(thread_sanitizer) || __has_feature(address_sanitizer)
+inline constexpr std::size_t yieldStackSize = 2 * 1024 * 1024;
+#else
+inline constexpr std::size_t yieldStackSize = 1.5 * 1024 * 1024;
+#endif
+#else
+inline constexpr std::size_t yieldStackSize = 1.5 * 1024 * 1024;
+#endif
+
 /** Mix-in to support tests using asio coroutines.
 
     Derive from this class and use yield_to to launch test
@@ -111,7 +133,7 @@ EnableYieldTo::spawn(F0&& f, FN&&... fn)
     boost::asio::spawn(
         ios_,
         boost::allocator_arg,
-        boost::context::fixedsize_stack(2 * 1024 * 1024),
+        boost::context::fixedsize_stack(yieldStackSize),
         [&](yield_context yield) {
             f(yield);
             std::scoped_lock const lock{m_};

include/xrpl/beast/utility/Journal.h

@@ -2,6 +2,7 @@
 
 #include <xrpl/beast/utility/instrumentation.h>
 
+#include <atomic>
 #include <sstream>
 
 namespace beast {
@@ -57,7 +58,7 @@ public:
     class Sink
     {
     protected:
-        explicit Sink(Sink const& sink) = default;
+        explicit Sink(Sink const& sink);
         Sink(Severity thresh, bool console);
 
     public:
@@ -107,7 +108,9 @@ public:
         writeAlways(Severity level, std::string const& text) = 0;
 
     private:
-        Severity thresh_;
+        /// Minimum severity level. Atomic for safe concurrent reads/writes
+        /// (e.g. RPC threshold changes vs. hot-path log checks).
+        std::atomic<Severity> thresh_;
         bool console_;
     };
 

include/xrpl/core/Coro.ipp

@@ -1,12 +1,20 @@
 #pragma once
 
+#include <xrpl/basics/ByteUtilities.h>
+#include <xrpl/basics/sanitizers.h>
+
+#include <cstddef>
 #include <utility>
 
 namespace xrpl {
 
-/// Coroutine stack size (1.5 MB). Increased from 1 MB because
-/// ASAN-instrumented deep call stacks exceeded the original limit.
-constexpr std::size_t kCORO_STACK_SIZE = 1536 * 1024;
+/** Stack size for JobQueue coroutines.
+ *
+ *  Sanitizers significantly increase stack frame sizes
+ *  (TSAN ~3-5x, ASAN ~2-3x), requiring larger coroutine stacks.
+ */
+inline constexpr std::size_t kCORO_STACK_SIZE =
+    XRPL_SANITIZER_ACTIVE ? megabytes(2) : megabytes(1.5);
 
 template <class F>
 JobQueue::Coro::Coro(CoroCreateT, JobQueue& jq, JobType type, std::string name, F&& f)

include/xrpl/nodestore/Database.h

@@ -32,13 +32,28 @@ public:
 
     /** Construct the node store.
 
+        Construction configures the database but does not start read threads.
+        Call startReadThreads() after construction to begin asynchronous reads.
+
         @param scheduler The scheduler to use for performing asynchronous tasks.
-        @param readThreads The number of asynchronous read threads to create.
-        @param config The configuration settings
+        @param readThreads The desired number of asynchronous read threads.
+        @param config The configuration settings.
         @param journal Destination for logging output.
     */
     Database(Scheduler& scheduler, int readThreads, Section const& config, beast::Journal j);
 
+    /** Start the asynchronous read threads.
+
+        Must be called after construction to start read threads. It is safe
+        to destroy the Database without calling this; in that case no
+        asynchronous reads will be serviced.
+
+        @note Not thread-safe. Must be called exactly once, before any
+              concurrent access to the database.
+    */
+    void
+    startReadThreads();
+
     /** Destroy the node store.
         All pending operations are completed, pending writes flushed,
         and files closed before this returns.
@@ -251,6 +266,9 @@ private:
     std::atomic<int> readThreads_ = 0;
     std::atomic<int> runningThreads_ = 0;
 
+    /// The number of read threads to create when startReadThreads() is called.
+    int const desiredReadThreads_;
+
     virtual std::shared_ptr<NodeObject>
     fetchNodeObject(
         uint256 const& hash,

include/xrpl/resource/ResourceManager.h

@@ -21,6 +21,15 @@ protected:
 public:
     ~Manager() override = 0;
 
+    /** Start the manager's background thread.
+        Must be called after construction to begin periodic charge decay
+        and inactive-consumer sweeps.
+        @note Not thread-safe. Must be called exactly once, before any
+              concurrent access to the manager.
+    */
+    virtual void
+    start() = 0;
+
     /** Create a new endpoint keyed by inbound IP address or the forwarded
      * IP if proxied. */
     virtual Consumer

include/xrpl/shamap/SHAMap.h

@@ -14,6 +14,7 @@
 #include <xrpl/shamap/SHAMapMissingNode.h>
 #include <xrpl/shamap/SHAMapTreeNode.h>
 
+#include <atomic>
 #include <set>
 #include <stack>
 #include <vector>
@@ -82,8 +83,11 @@ private:
     /** ID to distinguish this map for all others we're sharing nodes with. */
     std::uint32_t cowid_ = 1;
 
-    /** The sequence of the ledger that this map references, if any. */
-    std::uint32_t ledgerSeq_ = 0;
+    /** The sequence of the ledger that this map references, if any.
+     *  Atomic because it is written during ledger acquisition and read
+     *  concurrently by node fetch and sync operations.
+     */
+    std::atomic<std::uint32_t> ledgerSeq_ = 0;
 
     intr_ptr::SharedPtr<SHAMapTreeNode> root_;
     mutable SHAMapState state_;
@@ -537,7 +541,7 @@ SHAMap::setFull()
 inline void
 SHAMap::setLedgerSeq(std::uint32_t lseq)
 {
-    ledgerSeq_ = lseq;
+    ledgerSeq_.store(lseq, std::memory_order_relaxed);
 }
 
 inline void

sanitizers/suppressions/tsan.supp

@@ -1,102 +1,64 @@
-# The idea is to empty this file gradually by fixing the underlying issues and removing suppresions.
+# TSAN suppression file for rippled.
+# Only suppress issues in third-party libraries and TSAN's own instrumentation.
+# Races in rippled's own code should be fixed, not suppressed.
 
-# Suppress race in Boost ASIO scheduler detected by GCC-15
-# This is a false positive in Boost's internal pipe() synchronization
+# Boost ASIO / Boost Context false positives
+# These are internal to Boost's reactor, fiber context switching, and memory management.
 race:boost/asio/
 race:boost/context/
 race:boost/asio/executor.hpp
 race:boost::asio
-
-# Suppress tsan related issues in xrpld code.
-race:src/libxrpl/basics/make_SSLContext.cpp
-race:src/libxrpl/basics/Number.cpp
-race:src/libxrpl/json/json_value.cpp
-race:src/libxrpl/json/to_string.cpp
-race:src/libxrpl/ledger/OpenView.cpp
-race:src/libxrpl/net/HTTPClient.cpp
-race:src/libxrpl/nodestore/backend/NuDBFactory.cpp
-race:src/libxrpl/protocol/InnerObjectFormats.cpp
-race:src/libxrpl/protocol/STParsedJSON.cpp
-race:src/libxrpl/resource/ResourceManager.cpp
-race:src/test/app/Flow_test.cpp
-race:src/test/app/LedgerReplay_test.cpp
-race:src/test/app/NFToken_test.cpp
-race:src/test/app/Offer_test.cpp
-race:src/test/app/ValidatorSite_test.cpp
-race:src/test/consensus/NegativeUNL_test.cpp
-race:src/test/jtx/impl/Env.cpp
-race:src/test/jtx/impl/JSONRPCClient.cpp
-race:src/test/jtx/impl/pay.cpp
-race:src/test/jtx/impl/token.cpp
-race:src/test/rpc/Book_test.cpp
-race:src/xrpld/app/ledger/detail/InboundTransactions.cpp
-race:src/xrpld/app/main/Application.cpp
-race:src/xrpld/app/main/BasicApp.cpp
-race:src/xrpld/app/main/GRPCServer.cpp
-race:src/xrpld/app/misc/detail/AmendmentTable.cpp
-race:src/xrpld/app/misc/FeeVoteImpl.cpp
-race:src/xrpld/app/rdb/detail/Wallet.cpp
-race:src/xrpld/overlay/detail/OverlayImpl.cpp
-race:src/xrpld/peerfinder/detail/PeerfinderManager.cpp
-race:src/xrpld/peerfinder/detail/SourceStrings.cpp
-race:src/xrpld/rpc/detail/ServerHandler.cpp
-race:xrpl/server/detail/Door.h
-race:xrpl/server/detail/Spawn.h
-race:xrpl/server/detail/ServerImpl.h
-race:xrpl/nodestore/detail/DatabaseNodeImp.h
-race:src/libxrpl/beast/utility/beast_Journal.cpp
-race:src/test/beast/LexicalCast_test.cpp
-race:ServerHandler
-
-# More suppressions in external library code.
-race:crtstuff.c
-race:pipe
-
-# Deadlock / lock-order-inversion suppressions
-# Note: GCC's TSAN may not fully support all deadlock suppression patterns
-deadlock:src/libxrpl/beast/utility/beast_Journal.cpp
-deadlock:src/libxrpl/beast/utility/beast_PropertyStream.cpp
-deadlock:src/test/beast/beast_PropertyStream_test.cpp
-deadlock:src/xrpld/core/detail/Workers.cpp
-deadlock:src/xrpld/app/misc/detail/Manifest.cpp
-deadlock:src/xrpld/app/misc/detail/ValidatorList.cpp
-deadlock:src/xrpld/app/misc/detail/ValidatorSite.cpp
-
-signal:src/libxrpl/beast/utility/beast_Journal.cpp
-signal:src/xrpld/core/detail/Workers.cpp
-signal:src/xrpld/core/JobQueue.cpp
-signal:Workers::Worker
-
-# Aggressive suppressing of deadlock tsan errors
-deadlock:pthread_create
-deadlock:pthread_rwlock_rdlock
-deadlock:boost::asio
-
-# Suppress SEGV crashes in TSAN itself during stringbuf operations
-# This appears to be a GCC-15 TSAN instrumentation issue with basic_stringbuf::str()
-# Commonly triggered in beast::Journal::ScopedStream destructor
-signal:std::__cxx11::basic_stringbuf
-signal:basic_stringbuf
-signal:basic_ostringstream
-
-called_from_lib:libclang_rt
-race:ostreambuf_iterator
-race:basic_ostream
-
-# Suppress SEGV in Boost ASIO memory allocation with GCC-15 TSAN
-signal:boost::asio::aligned_new
-signal:boost::asio::detail::memory
-
-# Suppress SEGV in execute_native_thread_routine
-signal:execute_native_thread_routine
-
-# Suppress data race in Boost Context fiber management
-# This is a false positive in Boost's exception state management during fiber context switching
-race:__cxxabiv1::manage_exception_state
 race:boost::context::fiber::resume
 race:boost::asio::detail::spawned_fiber_thread
 race:boost::asio::detail::spawned_fiber_thread::suspend_with
 race:boost::asio::detail::spawned_fiber_thread::destroy
-
-# Suppress data race in __tsan_memcpy called from Boost fiber operations
+race:__cxxabiv1::manage_exception_state
 race:__tsan_memcpy
+
+# TSAN's own syscall interceptors (false positives from fd tracking)
+race:crtstuff.c
+race:pipe
+race:epoll_ctl
+race:epoll_create
+race:closedir
+race:close
+race:socket
+race:accept
+race:eventfd
+
+# C++ standard library internals
+race:ostreambuf_iterator
+race:basic_ostream
+called_from_lib:libclang_rt
+
+# Deadlock false positives in Boost and threading primitives
+deadlock:pthread_create
+deadlock:pthread_rwlock_rdlock
+deadlock:boost::asio
+
+# Known lock-order-inversion between getMasterMutex() and RCLConsensus::mutex_.
+# NetworkOPsImp::processHeartbeatTimer acquires master → consensus, while
+# RCLConsensus::startRound (via acceptLedger) acquires consensus → master.
+# Requires a larger lock-ordering redesign to fix properly.
+deadlock:RCLConsensus
+
+# Lock-order-inversion in LedgerReplay subsystem.
+# LedgerDeltaAcquire::notify() calls LedgerReplayTask::deltaReady() while
+# holding LedgerDeltaAcquire's mutex, which then acquires LedgerReplayTask's
+# mutex. The reverse order also occurs. Pre-existing design issue.
+deadlock:LedgerReplayTask
+deadlock:LedgerDeltaAcquire
+
+# Data race on LedgerHeader::validated (bool mutable).
+# This is a monotonic flag (false→true, never back) set by LedgerMaster
+# worker threads and read by test/RPC code. Benign but technically UB.
+# Proper fix: make validated std::atomic<bool>.
+race:Ledger::setValidated
+
+# Signal/crash suppressions for GCC TSAN instrumentation issues
+signal:std::__cxx11::basic_stringbuf
+signal:basic_stringbuf
+signal:basic_ostringstream
+signal:boost::asio::aligned_new
+signal:boost::asio::detail::memory
+signal:execute_native_thread_routine

src/libxrpl/beast/utility/beast_Journal.cpp

@@ -68,6 +68,11 @@ Journal::getNullSink()
 
 //------------------------------------------------------------------------------
 
+Journal::Sink::Sink(Sink const& sink)
+    : thresh_(sink.thresh_.load(std::memory_order_relaxed)), console_(sink.console_)
+{
+}
+
 Journal::Sink::Sink(Severity thresh, bool console) : thresh_(thresh), console_(console)
 {
 }
@@ -77,7 +82,7 @@ Journal::Sink::~Sink() = default;
 bool
 Journal::Sink::active(Severity level) const
 {
-    return level >= thresh_;
+    return level >= thresh_.load(std::memory_order_relaxed);
 }
 
 bool
@@ -95,13 +100,13 @@ Journal::Sink::console(bool output)
 severities::Severity
 Journal::Sink::threshold() const
 {
-    return thresh_;
+    return thresh_.load(std::memory_order_relaxed);
 }
 
 void
 Journal::Sink::threshold(Severity thresh)
 {
-    thresh_ = thresh;
+    thresh_.store(thresh, std::memory_order_relaxed);
 }
 
 //------------------------------------------------------------------------------

src/libxrpl/beast/utility/beast_PropertyStream.cpp

@@ -158,9 +158,18 @@ PropertyStream::Source::Source(std::string name) : name_(std::move(name)), item_
 
 PropertyStream::Source::~Source()
 {
-    std::scoped_lock const _(lock_);
-    if (parent_ != nullptr)
-        parent_->remove(*this);
+    // Read parent_ under lock, then release before calling remove()
+    // to maintain consistent lock ordering (parent before child),
+    // matching the order used in find_one_deep().
+    Source* parent = nullptr;
+    {
+        std::lock_guard const _(lock_);
+        parent = parent_;
+    }
+    if (parent != nullptr)
+    {
+        parent->remove(*this);
+    }
     removeAll();
 }
 
@@ -196,10 +205,12 @@ void
 PropertyStream::Source::removeAll()
 {
     std::scoped_lock const _(lock_);
-    for (auto iter = children_.begin(); iter != children_.end();)
+    while (!children_.empty())
     {
-        std::scoped_lock const cl((*iter)->lock_);
-        remove(*(*iter));
+        Source& child = children_.front().source();
+        std::scoped_lock const _cl(child.lock_);
+        children_.erase(children_.iteratorTo(child.item_));
+        child.parent_ = nullptr;
     }
 }
 

src/libxrpl/nodestore/Database.cpp

@@ -40,7 +40,7 @@ Database::Database(
     , scheduler_(scheduler)
     , earliestLedgerSeq_(get<std::uint32_t>(config, "earliest_seq", kXRP_LEDGER_EARLIEST_SEQ))
     , requestBundle_(get<int>(config, "rq_bundle", 4))
-    , readThreads_(std::max(1, readThreads))
+    , desiredReadThreads_(std::max(1, readThreads))
 {
     XRPL_ASSERT(readThreads, "xrpl::NodeStore::Database::Database : nonzero threads input");
 
@@ -49,8 +49,14 @@ Database::Database(
 
     if (requestBundle_ < 1 || requestBundle_ > 64)
         Throw<std::runtime_error>("Invalid rq_bundle");
+}
 
-    for (int i = readThreads_.load(); i != 0; --i)
+void
+Database::startReadThreads()
+{
+    readThreads_ = desiredReadThreads_;
+
+    for (int i = desiredReadThreads_; i != 0; --i)
     {
         std::thread t(
             [this](int i) {

src/libxrpl/nodestore/ManagerImp.cpp

@@ -90,8 +90,10 @@ ManagerImp::makeDatabase(
 {
     auto backend{makeBackend(config, burstSize, scheduler, journal)};
     backend->open();
-    return std::make_unique<DatabaseNodeImp>(
+    auto db = std::make_unique<DatabaseNodeImp>(
         scheduler, readThreads, std::move(backend), config, journal);
+    db->startReadThreads();
+    return db;
 }
 
 void

src/libxrpl/resource/ResourceManager.cpp

@@ -38,6 +38,11 @@ private:
 public:
     ManagerImp(beast::insight::Collector::ptr const& collector, beast::Journal journal)
         : journal_(journal), logic_(collector, stopwatch(), journal)
+    {
+    }
+
+    void
+    start() override
     {
         thread_ = std::thread{&ManagerImp::run, this};
     }
@@ -49,12 +54,15 @@ public:
 
     ~ManagerImp() override
     {
+        if (thread_.joinable())
         {
-            std::scoped_lock const lock(mutex_);
-            stop_ = true;
-            cond_.notify_one();
+            {
+                std::scoped_lock const lock(mutex_);
+                stop_ = true;
+                cond_.notify_one();
+            }
+            thread_.join();
         }
-        thread_.join();
     }
 
     Consumer

src/libxrpl/shamap/SHAMap.cpp

@@ -77,7 +77,7 @@ SHAMap::SHAMap(SHAMap const& other, bool isMutable)
     : f_(other.f_)
     , journal_(other.f_.journal())
     , cowid_(other.cowid_ + 1)
-    , ledgerSeq_(other.ledgerSeq_)
+    , ledgerSeq_(other.ledgerSeq_.load(std::memory_order_relaxed))
     , root_(other.root_)
     , state_(isMutable ? SHAMapState::Modifying : SHAMapState::Immutable)
     , type_(other.type_)
@@ -169,7 +169,8 @@ intr_ptr::SharedPtr<SHAMapTreeNode>
 SHAMap::fetchNodeFromDB(SHAMapHash const& hash) const
 {
     XRPL_ASSERT(backed_, "xrpl::SHAMap::fetchNodeFromDB : is backed");
-    auto obj = f_.db().fetchNodeObject(hash.asUint256(), ledgerSeq_);
+    auto obj =
+        f_.db().fetchNodeObject(hash.asUint256(), ledgerSeq_.load(std::memory_order_relaxed));
     return finishFetch(hash, obj);
 }
 
@@ -185,7 +186,8 @@ SHAMap::finishFetch(SHAMapHash const& hash, std::shared_ptr<NodeObject> const& o
             if (full_)
             {
                 full_ = false;
-                f_.missingNodeAcquireBySeq(ledgerSeq_, hash.asUint256());
+                f_.missingNodeAcquireBySeq(
+                    ledgerSeq_.load(std::memory_order_relaxed), hash.asUint256());
             }
             return {};
         }
@@ -218,7 +220,12 @@ SHAMap::checkFilter(SHAMapHash const& hash, SHAMapSyncFilter* filter) const
             auto node = SHAMapTreeNode::makeFromPrefix(makeSlice(*nodeData), hash);
             if (node)
             {
-                filter->gotNode(true, hash, ledgerSeq_, std::move(*nodeData), node->getType());
+                filter->gotNode(
+                    true,
+                    hash,
+                    ledgerSeq_.load(std::memory_order_relaxed),
+                    std::move(*nodeData),
+                    node->getType());
                 if (backed_)
                     canonicalize(hash, node);
             }
@@ -399,7 +406,7 @@ SHAMap::descendAsync(
         {
             f_.db().asyncFetch(
                 hash.asUint256(),
-                ledgerSeq_,
+                ledgerSeq_.load(std::memory_order_relaxed),
                 [this, hash, cb{std::move(callback)}](std::shared_ptr<NodeObject> const& object) {
                     auto node = finishFetch(hash, object);
                     cb(node, hash);
@@ -947,7 +954,11 @@ SHAMap::writeNode(NodeObjectType t, intr_ptr::SharedPtr<SHAMapTreeNode> node) co
 
     Serializer s;
     node->serializeWithPrefix(s);
-    f_.db().store(t, std::move(s.modData()), node->getHash().asUint256(), ledgerSeq_);
+    f_.db().store(
+        t,
+        std::move(s.modData()),
+        node->getHash().asUint256(),
+        ledgerSeq_.load(std::memory_order_relaxed));
     return node;
 }
 

src/libxrpl/shamap/SHAMapSync.cpp

@@ -537,7 +537,11 @@ SHAMap::addRootNode(SHAMapHash const& hash, Slice const& rootNode, SHAMapSyncFil
         Serializer s;
         root_->serializeWithPrefix(s);
         filter->gotNode(
-            false, root_->getHash(), ledgerSeq_, std::move(s.modData()), root_->getType());
+            false,
+            root_->getHash(),
+            ledgerSeq_.load(std::memory_order_relaxed),
+            std::move(s.modData()),
+            root_->getType());
     }
 
     return SHAMapAddNode::useful();
@@ -643,7 +647,11 @@ SHAMap::addKnownNode(SHAMapNodeID const& node, Slice const& rawNode, SHAMapSyncF
             Serializer s;
             newNode->serializeWithPrefix(s);
             filter->gotNode(
-                false, childHash, ledgerSeq_, std::move(s.modData()), newNode->getType());
+                false,
+                childHash,
+                ledgerSeq_.load(std::memory_order_relaxed),
+                std::move(s.modData()),
+                newNode->getType());
         }
 
         return SHAMapAddNode::useful();

src/xrpld/app/main/Application.cpp

@@ -307,7 +307,7 @@ public:
         std::unique_ptr<Config> config,
         std::unique_ptr<Logs> logs,
         std::unique_ptr<TimeKeeper> timeKeeper)
-        : BasicApp(numberOfThreads(*config))
+        : BasicApp(numberOfThreads(*config), DeferStart{})
         , config_(std::move(config))
         , logs_(std::move(logs))
         , timeKeeper_(std::move(timeKeeper))
@@ -1145,6 +1145,14 @@ private:
 bool
 ApplicationImp::setup(boost::program_options::variables_map const& cmdline)
 {
+    // NOTE: The main io_context threads are NOT started until start().
+    // However, subsystem-specific threads (resource manager, nodestore
+    // read threads) are started here because they use their own
+    // threading and do not contend with io_context setup work.
+
+    resourceManager_->start();
+    nodeStore_->startReadThreads();
+
     // We want to intercept CTRL-C and the standard termination signal SIGTERM
     // and terminate the process. This handler will NEVER be invoked twice.
     //
@@ -1485,6 +1493,11 @@ ApplicationImp::start(bool withTimers)
 {
     JLOG(journal_.info()) << "Application starting. Version is " << BuildInfo::getVersionString();
 
+    // Start IO threads now that all setup is complete.
+    // This must happen before starting subsystems that post work
+    // to the io_context (resolver, overlay, etc.).
+    startIOThreads();
+
     if (withTimers)
     {
         setSweepTimer();

src/xrpld/app/main/BasicApp.cpp

@@ -7,15 +7,26 @@
 #include <cstddef>
 #include <string>
 
-BasicApp::BasicApp(std::size_t numberOfThreads)
+BasicApp::BasicApp(std::size_t numberOfThreads) : numberOfThreads_(numberOfThreads)
 {
     work_.emplace(boost::asio::make_work_guard(io_context_));
-    threads_.reserve(numberOfThreads);
+    startIOThreads();
+}
 
-    for (std::size_t i = 0; i < numberOfThreads; ++i)
+BasicApp::BasicApp(std::size_t numberOfThreads, DeferStart) : numberOfThreads_(numberOfThreads)
+{
+    work_.emplace(boost::asio::make_work_guard(io_context_));
+}
+
+void
+BasicApp::startIOThreads()
+{
+    threads_.reserve(numberOfThreads_);
+
+    for (std::size_t i = 0; i < numberOfThreads_; ++i)
     {
-        threads_.emplace_back([this, i]() {
-            beast::setCurrentThreadName("io svc #" + std::to_string(i));
+        threads_.emplace_back([this, n = i]() {
+            beast::setCurrentThreadName("io svc #" + std::to_string(n));
             this->io_context_.run();
         });
     }

src/xrpld/app/main/BasicApp.h

@@ -6,7 +6,12 @@
 #include <thread>
 #include <vector>
 
-// This is so that the io_context can outlive all the children
+/** Manages an io_context and its worker threads.
+ *  Ensures the io_context outlives all derived classes by joining worker
+ *  threads in the destructor. Supports immediate or deferred thread startup.
+ *  @note Thread-safe after construction completes. The deferred-start
+ *        constructor and startIOThreads() must be called from a single thread.
+ */
 class BasicApp
 {
 private:
@@ -14,6 +19,9 @@ private:
     std::vector<std::thread> threads_;
     boost::asio::io_context io_context_;
 
+    /// Number of IO worker threads to create.
+    std::size_t numberOfThreads_;
+
 public:
     BasicApp(std::size_t numberOfThreads);
     ~BasicApp();
@@ -29,4 +37,26 @@ public:
     {
         return threads_.size();
     }
+
+protected:
+    /** Tag type for deferred thread startup.
+     *  Pass to the protected constructor to construct without starting IO
+     *  threads. The derived class must call startIOThreads() once its own
+     *  construction is complete.
+     */
+    struct DeferStart
+    {
+    };
+
+    /** Construct without starting IO threads.
+     *  @param numberOfThreads Desired number of IO worker threads.
+     *  @param  Tag to select deferred startup.
+     */
+    BasicApp(std::size_t numberOfThreads, DeferStart);
+
+    /** Start the IO worker threads.
+     *  @note Must be called exactly once after the deferred-start constructor.
+     */
+    void
+    startIOThreads();
 };

src/xrpld/app/misc/SHAMapStoreImp.cpp

@@ -15,7 +15,9 @@
 #include <xrpl/beast/utility/instrumentation.h>
 #include <xrpl/ledger/Ledger.h>
 #include <xrpl/nodestore/Database.h>
+#include <xrpl/nodestore/Manager.h>
 #include <xrpl/nodestore/Scheduler.h>
+#include <xrpl/nodestore/detail/DatabaseNodeImp.h>
 #include <xrpl/nodestore/detail/DatabaseRotatingImp.h>
 #include <xrpl/protocol/Protocol.h>
 #include <xrpl/server/NetworkOPs.h>