diff --git a/include/xrpl/protocol/TER.h b/include/xrpl/protocol/TER.h
index c89610f354..083fbdf8b6 100644
--- a/include/xrpl/protocol/TER.h
+++ b/include/xrpl/protocol/TER.h
@@ -1,3 +1,15 @@
+/** @file
+ *  Transaction Engine Result (TER) code taxonomy for the XRP Ledger.
+ *
+ *  Defines the six result-code enumerations (tel/tem/tef/ter/tes/tec),
+ *  the strongly-typed `TERSubset<Trait>` wrapper that enforces which
+ *  categories are permitted in a given context, the `NotTEC` and `TER`
+ *  aliases, comparison operators, and lookup utilities.
+ *
+ *  Every code value is part of the wire protocol: numeric values are
+ *  stored in ledger metadata and consumed by `ripple-binary-codec`.
+ *  @see https://xrpl.org/transaction-results.html
+ */
 #pragma once
 
 // NOLINTBEGIN(readability-identifier-naming)
@@ -12,15 +24,29 @@
 
 namespace xrpl {
 
-// See https://xrpl.org/transaction-results.html
-//
-// "Transaction Engine Result"
-// or Transaction ERror.
-//
+/** Underlying integer type shared by all TER code enumerations.
+ *
+ *  Using a named typedef allows `TERSubset` to store a plain `int`
+ *  without naming a specific enum, and lets `TERtoInt` overloads share
+ *  a single return type that triggers the comparison-operator SFINAE.
+ *
+ *  @see https://xrpl.org/transaction-results.html
+ */
 using TERUnderlyingType = int;
 
 //------------------------------------------------------------------------------
 
+/** Local-error result codes (range −399..−300).
+ *
+ *  A `tel` result means this node alone rejected the transaction; the
+ *  decision is not propagated to the network. The transaction is not
+ *  forwarded to peers and no fee check is performed. Common causes:
+ *  fee below the local minimum, or path counts that exceed node-local
+ *  limits. These codes are only valid during non-consensus processing.
+ *
+ *  @note Numeric values are stable and encoded in `ripple-binary-codec`.
+ *      Never renumber or remove existing enumerators.
+ */
 // Protocol-critical, mixed with custom TER wrapper type, hundreds of usages
 // NOLINTNEXTLINE(cppcoreguidelines-use-enum-class)
 enum TELcodes : TERUnderlyingType {
@@ -28,11 +54,6 @@ enum TELcodes : TERUnderlyingType {
     // Exact numbers are used in ripple-binary-codec:
     //     https://github.com/XRPLF/xrpl.js/blob/main/packages/ripple-binary-codec/src/enums/definitions.json
     // Use tokens.
-
-    // -399 .. -300: L Local error (transaction fee inadequate, exceeds local
-    // limit) Only valid during non-consensus processing. Implications:
-    // - Not forwarded
-    // - No fee check
     telLOCAL_ERROR = -399,
     telBAD_DOMAIN,
     telBAD_PATH_COUNT,
@@ -54,6 +75,15 @@ enum TELcodes : TERUnderlyingType {
 
 //------------------------------------------------------------------------------
 
+/** Malformed-transaction result codes (range −299..−200).
+ *
+ *  A `tem` result means the transaction is structurally corrupt and
+ *  cannot succeed in any possible ledger state. The transaction is
+ *  rejected without being applied or forwarded, and no fee is charged.
+ *
+ *  @note Numeric values are stable and encoded in `ripple-binary-codec`.
+ *      Never renumber or remove existing enumerators.
+ */
 // Protocol-critical, mixed with custom TER wrapper type, hundreds of usages
 // NOLINTNEXTLINE(cppcoreguidelines-use-enum-class)
 enum TEMcodes : TERUnderlyingType {
@@ -61,15 +91,6 @@ enum TEMcodes : TERUnderlyingType {
     // Exact numbers are used in ripple-binary-codec:
     //     https://github.com/XRPLF/xrpl.js/blob/main/packages/ripple-binary-codec/src/enums/definitions.json
     // Use tokens.
-
-    // -299 .. -200: M Malformed (bad signature)
-    // Causes:
-    // - Transaction corrupt.
-    // Implications:
-    // - Not applied
-    // - Not forwarded
-    // - Reject
-    // - Cannot succeed in any imagined ledger.
     temMALFORMED = -299,
 
     temBAD_AMOUNT,
@@ -106,8 +127,8 @@ enum TEMcodes : TERUnderlyingType {
     temCANNOT_PREAUTH_SELF,
     temINVALID_COUNT,
 
-    temUNCERTAIN,  // An internal intermediate result; should never be returned.
-    temUNKNOWN,    // An internal intermediate result; should never be returned.
+    temUNCERTAIN,  ///< Internal sentinel — in the process of determining a result; never returned to callers.
+    temUNKNOWN,    ///< Internal sentinel — logic not yet implemented; never returned to callers.
 
     temSEQ_AND_TICKET,
     temBAD_NFTOKEN_TRANSFER_FEE,
@@ -132,6 +153,17 @@ enum TEMcodes : TERUnderlyingType {
 
 //------------------------------------------------------------------------------
 
+/** Failure result codes (range −199..−100).
+ *
+ *  A `tef` result means the transaction cannot be applied because of the
+ *  current ledger state (e.g., sequence already used, bad signature, or
+ *  an unexpected C++ exception). The transaction is not applied, not
+ *  forwarded, and no fee is charged. Unlike `tem`, a `tef` transaction
+ *  could theoretically succeed in a different ledger state.
+ *
+ *  @note Numeric values are stable and encoded in `ripple-binary-codec`.
+ *      Never renumber or remove existing enumerators.
+ */
 // Protocol-critical, mixed with custom TER wrapper type, hundreds of usages
 // NOLINTNEXTLINE(cppcoreguidelines-use-enum-class)
 enum TEFcodes : TERUnderlyingType {
@@ -139,19 +171,6 @@ enum TEFcodes : TERUnderlyingType {
     // Exact numbers are used in ripple-binary-codec:
     //     https://github.com/XRPLF/xrpl.js/blob/main/packages/ripple-binary-codec/src/enums/definitions.json
     // Use tokens.
-
-    // -199 .. -100: F
-    //    Failure (sequence number previously used)
-    //
-    // Causes:
-    // - Transaction cannot succeed because of ledger state.
-    // - Unexpected ledger state.
-    // - C++ exception.
-    //
-    // Implications:
-    // - Not applied
-    // - Not forwarded
-    // - Could succeed in an imagined ledger.
     tefFAILURE = -199,
     tefALREADY,
     tefBAD_ADD_AUTH,
@@ -178,6 +197,18 @@ enum TEFcodes : TERUnderlyingType {
 
 //------------------------------------------------------------------------------
 
+/** Retry result codes (range −99..−1).
+ *
+ *  A `ter` result means the transaction cannot succeed right now, but
+ *  might succeed after other transactions are applied — for example,
+ *  if the sequence number is too high or there are insufficient funds
+ *  for the fee. The transaction is not applied and leaves a sequence
+ *  gap that can block later transactions. It may be held in the
+ *  transaction queue (`terQUEUED`) to retry when fee levels drop.
+ *
+ *  @note Numeric values are stable and encoded in `ripple-binary-codec`.
+ *      Never renumber or remove existing enumerators.
+ */
 // Protocol-critical, mixed with custom TER wrapper type, hundreds of usages
 // NOLINTNEXTLINE(cppcoreguidelines-use-enum-class)
 enum TERcodes : TERUnderlyingType {
@@ -185,23 +216,6 @@ enum TERcodes : TERUnderlyingType {
     // Exact numbers are used in ripple-binary-codec:
     //     https://github.com/XRPLF/xrpl.js/blob/main/packages/ripple-binary-codec/src/enums/definitions.json
     // Use tokens.
-
-    // -99 .. -1: R Retry
-    //   sequence too high, no funds for txn fee, originating -account
-    //   non-existent
-    //
-    // Cause:
-    //   Prior application of another, possibly non-existent, transaction could
-    //   allow this transaction to succeed.
-    //
-    // Implications:
-    // - Not applied
-    // - May be forwarded
-    //   - Results indicating the txn was forwarded: terQUEUED
-    //   - All others are not forwarded.
-    // - Might succeed later
-    // - Hold
-    // - Makes hole in sequence which jams transactions.
     terRETRY = -99,
     terFUNDS_SPENT,             // DEPRECATED.
     terINSUF_FEE_B,             // Can't pay fee, therefore don't burden network.
@@ -224,57 +238,50 @@ enum TERcodes : TERUnderlyingType {
 
 //------------------------------------------------------------------------------
 
+/** Success result code (value 0).
+ *
+ *  `tesSUCCESS` is the sole member: the transaction was applied to the
+ *  ledger and forwarded to peers. Its numeric value (0) is stored in
+ *  ledger metadata and must never change.
+ *
+ *  @note `TERSubset::operator bool()` returns `false` for this code
+ *      (success = falsy), mirroring the conventional C error-code idiom.
+ */
 // Protocol-critical, mixed with custom TER wrapper type, hundreds of usages
 // NOLINTNEXTLINE(cppcoreguidelines-use-enum-class)
 enum TEScodes : TERUnderlyingType {
     // Note: Exact number must stay stable.  This code is stored by value
     // in metadata for historic transactions.
-
-    // 0: S Success (success)
-    // Causes:
-    // - Success.
-    // Implications:
-    // - Applied
-    // - Forwarded
     tesSUCCESS = 0
 };
 
 //------------------------------------------------------------------------------
 
+/** Fee-claim result codes (range 100..255).
+ *
+ *  A `tec` result means the fee is consumed and the sequence number is
+ *  spent, but no other effect is applied to the ledger. The transaction
+ *  is still applied and forwarded to peers. Typical causes: a payment
+ *  with no valid path, or a transaction that is logically invalid but
+ *  well-formed enough to charge a fee.
+ *
+ *  When `tapRETRY` is set during application, `tec` codes are demoted
+ *  to `terRETRY` so the transaction can be retried rather than
+ *  consuming the sequence number.
+ *
+ *  @note **DO NOT CHANGE THESE NUMBERS.** They are stored by value in
+ *      ledger metadata and parsed by external tools such as
+ *      `ripple-binary-codec`. Append new codes; never renumber or remove.
+ *  @note Naming convention: use `tecNO_ENTRY` when the primary ledger
+ *      object targeted by the transaction is missing; use
+ *      `tecOBJECT_NOT_FOUND` when an auxiliary object required to
+ *      complete the transaction cannot be found.
+ */
 // Protocol-critical, mixed with custom TER wrapper type, hundreds of usages
 // NOLINTNEXTLINE(cppcoreguidelines-use-enum-class)
 enum TECcodes : TERUnderlyingType {
     // Note: Exact numbers must stay stable.  These codes are stored by
     // value in metadata for historic transactions.
-
-    // 100 .. 255 C
-    //   Claim fee only (ripple transaction with no good paths, pay to
-    //   non-existent account, no path)
-    //
-    // Causes:
-    // - Success, but does not achieve optimal result.
-    // - Invalid transaction or no effect, but claim fee to use the sequence
-    //   number.
-    //
-    // Implications:
-    // - Applied
-    // - Forwarded
-    //
-    // Only allowed as a return code of appliedTransaction when !tapRETRY.
-    // Otherwise, treated as terRETRY.
-    //
-    // DO NOT CHANGE THESE NUMBERS: They appear in ledger meta data.
-    //
-    // Note:
-    //   tecNO_ENTRY is often used interchangeably with tecOBJECT_NOT_FOUND.
-    //   While there does not seem to be a clear rule which to use when, the
-    //   following guidance will help to keep errors consistent with the
-    //   majority of (but not all) transaction types:
-    // - tecNO_ENTRY : cannot find the primary ledger object on which the
-    //   transaction is being attempted
-    // - tecOBJECT_NOT_FOUND : cannot find the additional object(s) needed to
-    //   complete the transaction
-
     tecCLAIM = 100,
     tecPATH_PARTIAL = 101,
     tecUNFUNDED_ADD = 102,  // Unused legacy code
@@ -362,37 +369,56 @@ enum TECcodes : TERUnderlyingType {
 
 //------------------------------------------------------------------------------
 
-// For generic purposes, a free function that returns the value of a TE*codes.
+/** Convert a TEL/TEM/TEF/TER/TES/TEC code to its underlying integer value.
+ *
+ *  These overloads form the single conversion point used by `TERSubset`,
+ *  comparison operators, and any code that needs to inspect the raw
+ *  integer. A free-function overload set is used rather than an explicit
+ *  conversion operator on `TERSubset` to prevent silent implicit
+ *  conversions in constructor-initialization contexts (e.g., `Status(TER)`
+ *  would compile silently even with `explicit` — a named function does not).
+ *
+ *  A matching `friend` overload for `TERSubset<Trait>` is defined inside
+ *  the class template; the six overloads below cover the raw enum types.
+ *
+ *  @param v The enum code to convert.
+ *  @return The underlying `int` value of `v`.
+ */
 constexpr TERUnderlyingType
 TERtoInt(TELcodes v)
 {
     return safeCast<TERUnderlyingType>(v);
 }
 
+/** @copydoc TERtoInt(TELcodes) */
 constexpr TERUnderlyingType
 TERtoInt(TEMcodes v)
 {
     return safeCast<TERUnderlyingType>(v);
 }
 
+/** @copydoc TERtoInt(TELcodes) */
 constexpr TERUnderlyingType
 TERtoInt(TEFcodes v)
 {
     return safeCast<TERUnderlyingType>(v);
 }
 
+/** @copydoc TERtoInt(TELcodes) */
 constexpr TERUnderlyingType
 TERtoInt(TERcodes v)
 {
     return safeCast<TERUnderlyingType>(v);
 }
 
+/** @copydoc TERtoInt(TELcodes) */
 constexpr TERUnderlyingType
 TERtoInt(TEScodes v)
 {
     return safeCast<TERUnderlyingType>(v);
 }
 
+/** @copydoc TERtoInt(TELcodes) */
 constexpr TERUnderlyingType
 TERtoInt(TECcodes v)
 {
@@ -400,15 +426,37 @@ TERtoInt(TECcodes v)
 }
 
 //------------------------------------------------------------------------------
-// Template class that is specific to selected ranges of error codes.  The
-// Trait tells std::enable_if which ranges are allowed.
+
+/** Strongly-typed wrapper around a TER integer that restricts which
+ *  result-code categories may be implicitly assigned or constructed.
+ *
+ *  The `Trait` policy class template determines which `TE*codes` enum
+ *  types are accepted. A specialization of `Trait<T>` that inherits from
+ *  `std::true_type` permits `T`; one inheriting from `std::false_type`
+ *  rejects it at compile time via `std::enable_if`. This provides
+ *  category-level type safety without runtime overhead.
+ *
+ *  Two concrete aliases are provided:
+ *  - `NotTEC` — permits `tel`, `tem`, `tef`, `ter`, `tes`; **excludes
+ *    `tec`**. Used as the return type of `preflight()` to prevent fee-theft
+ *    via unsigned transactions (see `CanCvtToNotTEC`).
+ *  - `TER` — permits all six categories including `tec` and `NotTEC`
+ *    (widening assignment from `NotTEC` to `TER` is always valid).
+ *
+ *  Default-constructs to `tesSUCCESS`. Truthy (`operator bool`) when the
+ *  stored code is anything other than `tesSUCCESS`.
+ *
+ *  @tparam Trait A class template whose specializations for each `TE*codes`
+ *      type inherit from `std::true_type` (allowed) or `std::false_type`
+ *      (disallowed).
+ */
 template <template <typename> class Trait>
 class TERSubset
 {
     TERUnderlyingType code_;
 
 public:
-    // Constructors
+    /** Default-constructs to `tesSUCCESS`. */
     constexpr TERSubset() : code_(tesSUCCESS)
     {
     }
@@ -421,13 +469,30 @@ private:
     }
 
 public:
+    /** Construct from a raw integer, bypassing the Trait type check.
+     *
+     *  This escape hatch is intended for deserialization contexts (e.g.,
+     *  reconstructing a `TER` from ledger metadata) where the integer
+     *  originates from a validated source. Prefer enum-typed construction
+     *  everywhere else.
+     *
+     *  @param from The raw integer code to wrap.
+     *  @return A `TERSubset` holding `from`.
+     */
     static constexpr TERSubset
     fromInt(int from)
     {
         return TERSubset(from);
     }
 
-    // Trait tells enable_if which types are allowed for construction.
+    /** Construct from any `TE*codes` enum type permitted by `Trait`.
+     *
+     *  The constructor is disabled via `std::enable_if_t` for enum types
+     *  whose `Trait` specialization inherits from `std::false_type`, turning
+     *  category violations into hard compile errors.
+     *
+     *  @param rhs The source enum value.
+     */
     template <
         typename T,
         typename = std::enable_if_t<Trait<std::remove_cv_t<std::remove_reference_t<T>>>::value>>
@@ -435,13 +500,19 @@ public:
     {
     }
 
-    // Assignment
     constexpr TERSubset&
     operator=(TERSubset const& rhs) = default;
     constexpr TERSubset&
     operator=(TERSubset&& rhs) = default;
 
-    // Trait tells enable_if which types are allowed for assignment.
+    /** Assign from any `TE*codes` enum type permitted by `Trait`.
+     *
+     *  Disabled via `std::enable_if_t` for categories not allowed by
+     *  `Trait`, matching the construction constraint.
+     *
+     *  @param rhs The source enum value.
+     *  @return `*this`.
+     */
     template <typename T>
     constexpr auto
     operator=(T rhs) -> std::enable_if_t<Trait<T>::value, TERSubset&>
@@ -450,43 +521,46 @@ public:
         return *this;
     }
 
-    // Conversion to bool.
+    /** Return `true` when the code is anything other than `tesSUCCESS`.
+     *
+     *  Mirrors conventional C error-code semantics: a falsy result is
+     *  success, a truthy result means something went wrong. Use
+     *  `isTesSuccess()` for the positive sense.
+     */
     explicit
     operator bool() const
     {
         return code_ != tesSUCCESS;
     }
 
-    // Conversion to json::Value allows assignment to json::Objects
-    // without casting.
+    /** Implicit conversion to `json::Value` for use in JSON object assembly.
+     *
+     *  Allows `jsonObj["result"] = ter;` without an explicit cast.
+     */
     operator json::Value() const
     {
         return json::Value{code_};
     }
 
-    // Streaming operator.
+    /** Stream the raw integer code to `os`. */
     friend std::ostream&
     operator<<(std::ostream& os, TERSubset const& rhs)
     {
         return os << rhs.code_;
     }
 
-    // Return the underlying value.  Not a member so similarly named free
-    // functions can do the same work for the enums.
-    //
-    // It's worth noting that an explicit conversion operator was considered
-    // and rejected.  Consider this case, taken from Status.h
-    //
-    // class Status {
-    //     int code_;
-    // public:
-    //     Status (TER ter)
-    //     : code_ (ter) {}
-    // }
-    //
-    // This code compiles with no errors or warnings if TER has an explicit
-    // (unnamed) conversion to int.  To avoid silent conversions like these
-    // we provide (only) a named conversion.
+    /** Return the underlying integer value of this result code.
+     *
+     *  Implemented as a named `friend` free function rather than an
+     *  `explicit` conversion operator. An explicit operator would still
+     *  allow silent conversion in constructor-initialization contexts
+     *  (e.g., `Status(TER ter) : code_(ter) {}` compiles without warning
+     *  even with `explicit`). A named function forces the conversion to
+     *  be visible at every call site.
+     *
+     *  @param v The `TERSubset` to extract from.
+     *  @return The raw `int` code.
+     */
     friend constexpr TERUnderlyingType
     TERtoInt(TERSubset v)
     {
@@ -494,8 +568,16 @@ public:
     }
 };
 
-// Comparison operators.
-// Only enabled if both arguments return int if TERtiInt is called with them.
+/** @name TER comparison operators
+ *
+ *  Heterogeneous comparisons across any combination of raw `TE*codes`
+ *  enum types and `TERSubset` wrappers. Each operator is enabled only
+ *  when both operands have a `TERtoInt` overload returning `int`, so
+ *  unrelated types (e.g., plain `int`) are excluded by SFINAE — no
+ *  accidental numeric comparisons.
+ *
+ *  @{
+ */
 template <typename L, typename R>
 constexpr auto
 operator==(L const& lhs, R const& rhs) -> std::enable_if_t<
@@ -549,17 +631,23 @@ operator>=(L const& lhs, R const& rhs) -> std::enable_if_t<
 {
     return TERtoInt(lhs) >= TERtoInt(rhs);
 }
+/** @} */
 
 //------------------------------------------------------------------------------
 
-// Use traits to build a TERSubset that can convert from any of the TE*codes
-// enums *except* TECcodes: NotTEC
-
-// NOTE: NotTEC is useful for codes returned by preflight in transactors.
-// Preflight checks occur prior to signature checking.  If preflight returned
-// a tec code, then a malicious user could submit a transaction with a very
-// large fee and have that fee charged against an account without using that
-// account's valid signature.
+/** Trait that permits `tel`, `tem`, `tef`, `ter`, and `tes` but
+ *  explicitly **excludes** `TECcodes` for use with `NotTEC`.
+ *
+ *  The exclusion of `tec` is a security invariant. `preflight()`
+ *  executes before signature verification. If it could return a `tec`
+ *  code, a malicious actor could craft a transaction with a very large
+ *  fee and have that fee deducted from an account without supplying a
+ *  valid signature. Restricting `preflight` return types to `NotTEC`
+ *  makes this class of fee-theft structurally impossible at compile time.
+ *
+ *  @tparam FROM The candidate source type; only the five non-tec enums
+ *      yield `std::true_type`.
+ */
 template <typename FROM>
 class CanCvtToNotTEC : public std::false_type
 {
@@ -585,12 +673,27 @@ class CanCvtToNotTEC<TEScodes> : public std::true_type
 {
 };
 
+/** A `TERSubset` restricted to non-`tec` result categories.
+ *
+ *  Use as the return type of `preflight()` and any function that must
+ *  not be allowed to claim a fee. Assigning a `TECcodes` value to a
+ *  `NotTEC` variable is a compile-time error. A `NotTEC` can be
+ *  widened to a `TER` without a cast.
+ */
 using NotTEC = TERSubset<CanCvtToNotTEC>;
 
 //------------------------------------------------------------------------------
 
-// Use traits to build a TERSubset that can convert from any of the TE*codes
-// enums as well as from NotTEC.
+/** Trait that permits all six result-code categories plus `NotTEC` for
+ *  use with the `TER` alias.
+ *
+ *  The `NotTEC` specialization enables the widening assignment from
+ *  `NotTEC` to `TER` that is required in contexts where a function
+ *  returning `NotTEC` passes its result to code expecting `TER`.
+ *
+ *  @tparam FROM The candidate source type; all six `TE*codes` enums
+ *      and `NotTEC` yield `std::true_type`.
+ */
 template <typename FROM>
 class CanCvtToTER : public std::false_type
 {
@@ -624,35 +727,68 @@ class CanCvtToTER<NotTEC> : public std::true_type
 {
 };
 
-// TER allows all of the subsets.
+/** A `TERSubset` that accepts all six result-code categories.
+ *
+ *  This is the general result type used throughout the transaction engine
+ *  for `doApply()` and most ledger-application code. Use `NotTEC` for
+ *  `preflight()` return types where `tec` codes must be excluded.
+ */
 using TER = TERSubset<CanCvtToTER>;
 
 //------------------------------------------------------------------------------
 
+/** Return `true` if `x` is a local-error (`tel`) code (−399..−300).
+ *
+ *  @param x The code to test; accepts any `TER`-compatible value.
+ *  @return `true` iff `x` falls in the `tel` range.
+ */
 inline bool
 isTelLocal(TER x) noexcept
 {
     return (x >= telLOCAL_ERROR && x < temMALFORMED);
 }
 
+/** Return `true` if `x` is a malformed-transaction (`tem`) code (−299..−200).
+ *
+ *  @param x The code to test.
+ *  @return `true` iff `x` falls in the `tem` range.
+ */
 inline bool
 isTemMalformed(TER x) noexcept
 {
     return (x >= temMALFORMED && x < tefFAILURE);
 }
 
+/** Return `true` if `x` is a failure (`tef`) code (−199..−100).
+ *
+ *  @param x The code to test.
+ *  @return `true` iff `x` falls in the `tef` range.
+ */
 inline bool
 isTefFailure(TER x) noexcept
 {
     return (x >= tefFAILURE && x < terRETRY);
 }
 
+/** Return `true` if `x` is a retry (`ter`) code (−99..−1).
+ *
+ *  @param x The code to test.
+ *  @return `true` iff `x` falls in the `ter` range.
+ */
 inline bool
 isTerRetry(TER x) noexcept
 {
     return (x >= terRETRY && x < tesSUCCESS);
 }
 
+/** Return `true` if `x` is `tesSUCCESS` (0).
+ *
+ *  Relies on `TERSubset::operator bool()` returning `false` for
+ *  `tesSUCCESS` (the only falsy value), so this is equivalent to `!x`.
+ *
+ *  @param x The code to test.
+ *  @return `true` iff `x == tesSUCCESS`.
+ */
 inline bool
 isTesSuccess(TER x) noexcept
 {
@@ -660,24 +796,75 @@ isTesSuccess(TER x) noexcept
     return !(x);
 }
 
+/** Return `true` if `x` is a fee-claim (`tec`) code (≥ 100).
+ *
+ *  Any value at or above `tecCLAIM` (100) is treated as a fee-claim
+ *  result regardless of whether it is a recognized code.
+ *
+ *  @param x The code to test.
+ *  @return `true` iff `x >= tecCLAIM`.
+ */
 inline bool
 isTecClaim(TER x) noexcept
 {
     return ((x) >= tecCLAIM);
 }
 
+/** Return the complete registry mapping every known TER code to its
+ *  symbolic token and human-readable description.
+ *
+ *  The map is keyed by the underlying integer value and maps to a pair
+ *  of C-string literals: `{token, description}`. Token strings match
+ *  the enum identifier exactly (generated via preprocessor stringification).
+ *  The registry is a Meyers singleton — initialized once on first call,
+ *  thread-safe per C++11, and immutable thereafter.
+ *
+ *  @return A `const` reference to the singleton map, valid for the
+ *      lifetime of the process.
+ */
 std::unordered_map<TERUnderlyingType, std::pair<char const* const, char const* const>> const&
 transResults();
 
+/** Look up the token and human-readable description for a TER code.
+ *
+ *  @param code  The TER result code to look up.
+ *  @param token On success, populated with the symbolic token string
+ *      (e.g., `"tecNO_DST"`). Unchanged on failure.
+ *  @param text  On success, populated with the English description.
+ *      Unchanged on failure.
+ *  @return `true` if `code` is a registered code; `false` otherwise.
+ */
 bool
 transResultInfo(TER code, std::string& token, std::string& text);
 
+/** Return the symbolic token string for a TER code.
+ *
+ *  @param code The TER result code to look up.
+ *  @return The token string (e.g., `"tecNO_DST"`) for known codes, or
+ *      `"-"` if `code` is not in the registry.
+ */
 std::string
 transToken(TER code);
 
+/** Return the human-readable description for a TER code.
+ *
+ *  @param code The TER result code to look up.
+ *  @return The English description string for known codes, or `"-"` if
+ *      `code` is not in the registry.
+ */
 std::string
 transHuman(TER code);
 
+/** Convert a symbolic token string to the corresponding TER code.
+ *
+ *  Provides the reverse direction of `transToken()`. The reverse map is
+ *  built lazily as a function-local static on the first call by inverting
+ *  the primary registry; the two maps stay in sync automatically.
+ *
+ *  @param token The symbolic token string to look up (e.g., `"tecNO_DST"`).
+ *  @return The matching `TER` wrapped in `std::optional`, or
+ *      `std::nullopt` if `token` is not a recognized code name.
+ */
 std::optional<TER>
 transCode(std::string const& token);
 
diff --git a/include/xrpl/protocol/TxFlags.h b/include/xrpl/protocol/TxFlags.h
index 4652cc1bf0..a64540b6f2 100644
--- a/include/xrpl/protocol/TxFlags.h
+++ b/include/xrpl/protocol/TxFlags.h
@@ -1,3 +1,17 @@
+/** @file
+ *  Canonical, single-source-of-truth definitions for every transaction flag in
+ *  the XRPL protocol.
+ *
+ *  Flag values are embedded in signed transactions and therefore form part of
+ *  the consensus protocol. Altering any constant without a coordinated amendment
+ *  and special handling will cause a hard fork.
+ *
+ *  The file uses three X-macro instantiations of a single `XMACRO` table to
+ *  emit, from one authoritative list, the flag value constants, the per-type
+ *  validation masks, and the Meyer's-singleton getter functions consumed by the
+ *  `server_definitions` RPC endpoint.
+ */
+
 #pragma once
 
 // NOLINTBEGIN(readability-identifier-naming)
@@ -36,14 +50,33 @@ namespace xrpl {
     @ingroup protocol
 */
 
+/** Underlying integer type for all transaction flag bitmasks. */
 using FlagValue = std::uint32_t;
 
-// Universal Transaction flags:
+// --- Universal Transaction flags ---
+
+/** Require that the transaction signature use the canonical (low-S) ECDSA
+ *  form.  The network now enforces this unconditionally, but the flag must
+ *  remain defined so that historical transactions that set it remain valid. */
 inline constexpr FlagValue tfFullyCanonicalSig = 0x80000000;
+
+/** Marks a transaction as an inner member of a `Batch` transaction.
+ *
+ *  Set by the batch submitter on every inner transaction; the outer `Batch`
+ *  wrapper must NOT carry this flag (enforced by `tfBatchMask` and the
+ *  compile-time `static_assert` below). */
 inline constexpr FlagValue tfInnerBatchTxn = 0x40000000;
+
+/** Bitwise OR of all universal flags; occupies the high 8 bits of `Flags`. */
 inline constexpr FlagValue tfUniversal = tfFullyCanonicalSig | tfInnerBatchTxn;
+
+/** Complement of `tfUniversal`; ANDing an unknown `Flags` value with this mask
+ *  isolates any transaction-type-specific bits. */
 inline constexpr FlagValue tfUniversalMask = ~tfUniversal;
 
+// The push/pop guards protect any caller that has its own macros with the same
+// short names (XMACRO, TO_VALUE, etc.) from having them clobbered when this
+// header is included.
 #pragma push_macro("XMACRO")
 #pragma push_macro("TO_VALUE")
 #pragma push_macro("VALUE_TO_MAP")
@@ -70,16 +103,36 @@ inline constexpr FlagValue tfUniversalMask = ~tfUniversal;
 // clang-format off
 #undef ALL_TX_FLAGS
 
-// XMACRO parameters:
-// - TRANSACTION: handles the transaction name, its flags, and mask adjustment
-// - TF_FLAG: defines a new flag constant
-// - TF_FLAG2: references an existing flag constant (no new definition)
-// - MASK_ADJ: specifies flags to add back to the mask (making them invalid for this tx type)
-//
-// Note: MASK_ADJ is used when a universal flag should be invalid for a specific transaction.
-// For example, Batch uses MASK_ADJ(tfInnerBatchTxn) because the outer Batch transaction
-// must not have tfInnerBatchTxn set (only inner transactions should have it).
-//
+/** Master X-macro table of all per-transaction-type flag groups.
+ *
+ *  This macro is the single source of truth for every flag in the system.
+ *  It is instantiated three times with different argument bindings to produce:
+ *    1. Inline `constexpr FlagValue tf*` declarations.
+ *    2. Inline `constexpr FlagValue tf*Mask` validation masks.
+ *    3. `inline FlagMap const& get*Flags()` Meyer's-singleton getters consumed
+ *       by the `server_definitions` RPC endpoint.
+ *
+ *  @param TRANSACTION  Macro invoked once per transaction type; receives the
+ *      type name, the expansion of its flag list, and the mask adjustment.
+ *  @param TF_FLAG      Declares a new flag constant unique to this transaction
+ *      type (or the first transaction that defines a shared constant).
+ *  @param TF_FLAG2     References an already-declared flag constant; suppresses
+ *      redeclaration. Used when two transaction types share a numeric value
+ *      (e.g., `tfLPToken` is declared by `AMMDeposit` and referenced by
+ *      `AMMWithdraw`).
+ *  @param MASK_ADJ     Specifies additional bits to OR back into the generated
+ *      mask, making those bits invalid for this transaction type even though
+ *      they are otherwise universal. `Batch` uses `MASK_ADJ(tfInnerBatchTxn)`
+ *      because the outer wrapper must not carry that flag; all other entries
+ *      use `MASK_ADJ(0)`.
+ *
+ *  @note To add a new flag: add a `TF_FLAG(name, value)` row inside the
+ *      appropriate `TRANSACTION(...)` block and nowhere else. The value,
+ *      mask, and getter are all derived automatically.
+ *
+ *  @warning Flag values are protocol-stable. Changing or reusing a numeric
+ *      value without an amendment causes a hard fork.
+ */
 // TODO: Consider rewriting this using reflection in C++26 or later. Alternatively this could be a DSL processed by a script at build time.
 #define XMACRO(TRANSACTION, TF_FLAG, TF_FLAG2, MASK_ADJ)                                                                                                       \
     TRANSACTION(AccountSet,                                                                                                                                    \
@@ -218,39 +271,38 @@ inline constexpr FlagValue tfUniversalMask = ~tfUniversal;
 
 // clang-format on
 
-// Create all the flag values.
-//
-// example:
-// inline constexpr FlagValue tfAccountSetRequireDestTag = 0x00010000;
+// --- Instantiation 1: emit `inline constexpr FlagValue tf* = 0x...;` ---
+// TF_FLAG  → declares a new constant.
+// TF_FLAG2 → no-op (constant already declared by a prior TRANSACTION block).
+// Example output:
+//   inline constexpr FlagValue tfRequireDestTag = 0x00010000;
 #define TO_VALUE(name, value) inline constexpr FlagValue name = value;
 #define NULL_NAME(name, values, maskAdj) values
 #define NULL_OUTPUT(name, value)
 #define NULL_MASK_ADJ(value)
 XMACRO(NULL_NAME, TO_VALUE, NULL_OUTPUT, NULL_MASK_ADJ)
 
-// Create masks for each transaction type that has flags.
-//
-// example:
-// inline constexpr FlagValue tfAccountSetMask = ~(tfUniversal | tfRequireDestTag |
-//     tfOptionalDestTag | tfRequireAuth | tfOptionalAuth | tfDisallowXRP | tfAllowXRP);
-//
-// The mask adjustment (maskAdj) allows adding flags back to the mask, making them invalid.
-// For example, Batch uses MASK_ADJ(tfInnerBatchTxn) to reject tfInnerBatchTxn on outer Batch.
+// --- Instantiation 2: emit `inline constexpr FlagValue tf*Mask` ---
+// Each mask is the bitwise complement of (tfUniversal | all valid flags for
+// this tx type) OR'd with any MASK_ADJ bits.  A transaction whose `Flags`
+// field ANDed with the mask is non-zero is rejected as carrying unknown or
+// forbidden flags.
+// Example output:
+//   inline constexpr FlagValue tfAccountSetMask =
+//       ~(tfUniversal | tfRequireDestTag | tfOptionalDestTag | ...);
 #define TO_MASK(name, values, maskAdj) \
     inline constexpr FlagValue tf##name##Mask = ~(tfUniversal values) | (maskAdj);
 #define VALUE_TO_MASK(name, value) | name
 #define MASK_ADJ_TO_MASK(value) value
 XMACRO(TO_MASK, VALUE_TO_MASK, VALUE_TO_MASK, MASK_ADJ_TO_MASK)
 
-// Verify that tfBatchMask correctly rejects tfInnerBatchTxn.
-// The outer Batch transaction must NOT have tfInnerBatchTxn set; only inner transactions should
-// have it.
+// Compile-time invariants for the MASK_ADJ(tfInnerBatchTxn) mechanism:
+// The outer Batch transaction rejects tfInnerBatchTxn (bit must appear in its
+// mask); all other transaction types allow it so inner transactions can carry
+// the flag legally.
 static_assert(
     (tfBatchMask & tfInnerBatchTxn) == tfInnerBatchTxn,
     "tfBatchMask must include tfInnerBatchTxn to reject it on outer Batch");
-
-// Verify that other transaction masks correctly allow tfInnerBatchTxn.
-// Inner transactions need tfInnerBatchTxn to be valid, so these masks must not reject it.
 static_assert(
     (tfPaymentMask & tfInnerBatchTxn) == 0,
     "tfPaymentMask must not reject tfInnerBatchTxn");
@@ -258,19 +310,13 @@ static_assert(
     (tfAccountSetMask & tfInnerBatchTxn) == 0,
     "tfAccountSetMask must not reject tfInnerBatchTxn");
 
-// Create getter functions for each set of flags using Meyer's singleton pattern.
-// This avoids static initialization order fiasco while still providing efficient access.
-// This is used below in `getAllTxFlags()` to generate the server_definitions RPC
-// output.
-//
-// example:
-// inline FlagMap const& getAccountSetFlags() {
-//     static FlagMap const flags = {
-//         {"tfRequireDestTag", 0x00010000},
-//         {"tfOptionalDestTag", 0x00020000},
-//     ...};
-//     return flags;
-// }
+// --- Instantiation 3: emit `inline FlagMap const& get*Flags()` getters ---
+// Each function initialises a local static on first call (Meyer's singleton)
+// and returns a reference to it on every subsequent call.  The map is keyed
+// by flag name string and valued by the numeric FlagValue.  These are
+// aggregated by getAllTxFlags() and served to clients via server_definitions.
+
+/** Maps flag names to their numeric values for a single transaction type. */
 using FlagMap = std::map<std::string, FlagValue>;
 #define VALUE_TO_MAP(name, value) {#name, value},
 #define TO_MAP(name, values, maskAdj)          \
@@ -281,6 +327,14 @@ using FlagMap = std::map<std::string, FlagValue>;
     }
 XMACRO(TO_MAP, VALUE_TO_MAP, VALUE_TO_MAP, NULL_MASK_ADJ)
 
+/** Returns the universal transaction flags by name.
+ *
+ *  The returned map contains `tfFullyCanonicalSig` and `tfInnerBatchTxn`.
+ *  It is initialised once (Meyer's singleton) and safe to call from any
+ *  thread after static initialisation completes.
+ *
+ *  @return A reference to the singleton `FlagMap` for universal flags.
+ */
 inline FlagMap const&
 getUniversalFlags()
 {
@@ -289,18 +343,21 @@ getUniversalFlags()
     return flags;
 }
 
-// Create a getter function for all transaction flag maps using Meyer's singleton pattern.
-// This is used to generate the server_definitions RPC output.
-//
-// example:
-// inline FlagMapPairList const& getAllTxFlags() {
-//     static FlagMapPairList const flags = {
-//         {"AccountSet", getAccountSetFlags()},
-//     ...};
-//     return flags;
-// }
+/** Ordered list of `{transaction-type-name, FlagMap}` pairs covering every
+ *  transaction type and the universal flag group.  Consumed by the
+ *  `server_definitions` RPC endpoint so clients can discover the protocol's
+ *  flag vocabulary at runtime. */
 using FlagMapPairList = std::vector<std::pair<std::string, FlagMap>>;
 #define ALL_TX_FLAGS(name, values, maskAdj) {#name, get##name##Flags()},
+
+/** Returns all per-transaction-type flag maps, prefixed by the universal group.
+ *
+ *  Initialised once (Meyer's singleton). The first entry is always
+ *  `{"universal", getUniversalFlags()}`; subsequent entries follow the
+ *  declaration order in `XMACRO`.
+ *
+ *  @return A reference to the singleton `FlagMapPairList`.
+ */
 inline FlagMapPairList const&
 getAllTxFlags()
 {
@@ -334,68 +391,142 @@ getAllTxFlags()
 #pragma pop_macro("NULL_MASK_ADJ")
 #pragma pop_macro("MASK_ADJ_TO_MASK")
 
-// Additional transaction masks and combos
+// --- Additional composite masks ---
+
+/** Validation mask for `Payment` transactions that involve MPTokens.
+ *
+ *  MPToken payments support only `tfPartialPayment`; all other
+ *  transaction-type-specific bits are rejected. */
 inline constexpr FlagValue tfMPTPaymentMask = ~(tfUniversal | tfPartialPayment);
+
+/** Validation mask for `TrustSet` transactions submitted under a granular
+ *  delegation permission.
+ *
+ *  Only `tfSetfAuth`, `tfSetFreeze`, and `tfClearFreeze` are permitted when
+ *  the `TrustlineUnfreeze` permission applies; any other flags cause the
+ *  transactor to return `terNO_DELEGATE_PERMISSION`. */
 inline constexpr FlagValue tfTrustSetPermissionMask =
     ~(tfUniversal | tfSetfAuth | tfSetFreeze | tfClearFreeze);
 
-// MPTokenIssuanceCreate MutableFlags:
-// Indicating specific fields or flags may be changed after issuance.
+// --- MPTokenIssuanceCreate mutable-flag declarations (tmf* prefix) ---
+// These alias the corresponding lsmf* ledger-state mutable-flag values from
+// LedgerFormats.h so that the same numeric bit can be stored verbatim on the
+// MPTokenIssuance object without a translation step.  Each flag, when set on
+// the creation transaction, means the named property may be updated by a
+// subsequent MPTokenIssuanceSet transaction.
+
+/** Permits the `CanLock` property to be changed after issuance. */
 inline constexpr FlagValue tmfMPTCanMutateCanLock = lsmfMPTCanMutateCanLock;
+/** Permits the `RequireAuth` property to be changed after issuance. */
 inline constexpr FlagValue tmfMPTCanMutateRequireAuth = lsmfMPTCanMutateRequireAuth;
+/** Permits the `CanEscrow` property to be changed after issuance. */
 inline constexpr FlagValue tmfMPTCanMutateCanEscrow = lsmfMPTCanMutateCanEscrow;
+/** Permits the `CanTrade` property to be changed after issuance. */
 inline constexpr FlagValue tmfMPTCanMutateCanTrade = lsmfMPTCanMutateCanTrade;
+/** Permits the `CanTransfer` property to be changed after issuance. */
 inline constexpr FlagValue tmfMPTCanMutateCanTransfer = lsmfMPTCanMutateCanTransfer;
+/** Permits the `CanClawback` property to be changed after issuance. */
 inline constexpr FlagValue tmfMPTCanMutateCanClawback = lsmfMPTCanMutateCanClawback;
+/** Permits the metadata URI to be changed after issuance. */
 inline constexpr FlagValue tmfMPTCanMutateMetadata = lsmfMPTCanMutateMetadata;
+/** Permits the transfer fee to be changed after issuance. */
 inline constexpr FlagValue tmfMPTCanMutateTransferFee = lsmfMPTCanMutateTransferFee;
+
+/** Validation mask for the `MutableFlags` field of `MPTokenIssuanceCreate`.
+ *
+ *  Any bit outside the recognised `tmfMPTCanMutate*` set causes
+ *  `MPTokenIssuanceCreate::preflight` to return `temINVALID_FLAG`.
+ *  A value of zero is also rejected — at least one mutable property must be
+ *  declared. */
 inline constexpr FlagValue tmfMPTokenIssuanceCreateMutableMask =
     ~(tmfMPTCanMutateCanLock | tmfMPTCanMutateRequireAuth | tmfMPTCanMutateCanEscrow |
       tmfMPTCanMutateCanTrade | tmfMPTCanMutateCanTransfer | tmfMPTCanMutateCanClawback |
       tmfMPTCanMutateMetadata | tmfMPTCanMutateTransferFee);
 
-// MPTokenIssuanceSet MutableFlags:
-// Set or Clear flags.
+// --- MPTokenIssuanceSet mutable-flag Set/Clear pairs ---
+// Each property has two complementary flags: one to enable and one to disable
+// the property in an existing MPTokenIssuance object.  Setting both bits in the
+// same transaction is a logical error and is rejected by the transactor.
 
+/** Enable the `CanLock` property on an existing MPTokenIssuance. */
 inline constexpr FlagValue tmfMPTSetCanLock = 0x00000001;
+/** Disable the `CanLock` property on an existing MPTokenIssuance. */
 inline constexpr FlagValue tmfMPTClearCanLock = 0x00000002;
+/** Enable the `RequireAuth` property on an existing MPTokenIssuance. */
 inline constexpr FlagValue tmfMPTSetRequireAuth = 0x00000004;
+/** Disable the `RequireAuth` property on an existing MPTokenIssuance. */
 inline constexpr FlagValue tmfMPTClearRequireAuth = 0x00000008;
+/** Enable the `CanEscrow` property on an existing MPTokenIssuance. */
 inline constexpr FlagValue tmfMPTSetCanEscrow = 0x00000010;
+/** Disable the `CanEscrow` property on an existing MPTokenIssuance. */
 inline constexpr FlagValue tmfMPTClearCanEscrow = 0x00000020;
+/** Enable the `CanTrade` property on an existing MPTokenIssuance. */
 inline constexpr FlagValue tmfMPTSetCanTrade = 0x00000040;
+/** Disable the `CanTrade` property on an existing MPTokenIssuance. */
 inline constexpr FlagValue tmfMPTClearCanTrade = 0x00000080;
+/** Enable the `CanTransfer` property on an existing MPTokenIssuance. */
 inline constexpr FlagValue tmfMPTSetCanTransfer = 0x00000100;
+/** Disable the `CanTransfer` property on an existing MPTokenIssuance. */
 inline constexpr FlagValue tmfMPTClearCanTransfer = 0x00000200;
+/** Enable the `CanClawback` property on an existing MPTokenIssuance. */
 inline constexpr FlagValue tmfMPTSetCanClawback = 0x00000400;
+/** Disable the `CanClawback` property on an existing MPTokenIssuance. */
 inline constexpr FlagValue tmfMPTClearCanClawback = 0x00000800;
+
+/** Validation mask for the `MutableFlags` field of `MPTokenIssuanceSet`.
+ *
+ *  Any bit outside the recognised `tmfMPTSet*` / `tmfMPTClear*` set causes
+ *  `MPTokenIssuanceSet::preflight` to return `temINVALID_FLAG`.
+ *  A zero value is also rejected. */
 inline constexpr FlagValue tmfMPTokenIssuanceSetMutableMask = ~(
     tmfMPTSetCanLock | tmfMPTClearCanLock | tmfMPTSetRequireAuth | tmfMPTClearRequireAuth |
     tmfMPTSetCanEscrow | tmfMPTClearCanEscrow | tmfMPTSetCanTrade | tmfMPTClearCanTrade |
     tmfMPTSetCanTransfer | tmfMPTClearCanTransfer | tmfMPTSetCanClawback | tmfMPTClearCanClawback);
 
-// Prior to fixRemoveNFTokenAutoTrustLine, transfer of an NFToken between accounts allowed a
-// TrustLine to be added to the issuer of that token without explicit permission from that issuer.
-// This was enabled by minting the NFToken with the tfTrustLine flag set.
+// --- NFTokenMint backward-compatibility mask variants ---
+// Three mask variants exist to accommodate two amendment-gated changes to the
+// set of valid NFTokenMint flags:
 //
-// That capability could be used to attack the NFToken issuer.
-// It would be possible for two accounts to trade the NFToken back and forth building up any number
-// of TrustLines on the issuer, increasing the issuer's reserve without bound.
+//   1. fixRemoveNFTokenAutoTrustLine — closed a reserve-exhaustion attack where
+//      two accounts could endlessly trade an NFToken, forcing unbounded trust
+//      lines onto the issuer. After this amendment, tfTrustLine is forbidden.
+//   2. featureDynamicNFT — adds tfMutable, allowing the token URI to be updated
+//      after minting.
 //
-// The fixRemoveNFTokenAutoTrustLine amendment disables minting with the tfTrustLine flag as a way
-// to prevent the attack. But until the amendment passes we still need to keep the old behavior
-// available.
-inline constexpr FlagValue tfTrustLine = 0x00000004;  // needed for backwards compatibility
+// Nodes processing historical ledger data must still accept tfTrustLine on pre-
+// amendment mints, which is why the constant and the old mask remain defined.
+
+/** NFTokenMint flag that once allowed automatic trust-line creation on the
+ *  issuer.  Forbidden after the `fixRemoveNFTokenAutoTrustLine` amendment;
+ *  retained only for historical ledger replay. */
+inline constexpr FlagValue tfTrustLine = 0x00000004;
+
+/** Baseline `NFTokenMint` validation mask (post `fixRemoveNFTokenAutoTrustLine`,
+ *  pre `featureDynamicNFT`).  Rejects `tfTrustLine` and `tfMutable`. */
 inline constexpr FlagValue tfNFTokenMintMaskWithoutMutable =
     ~(tfUniversal | tfBurnable | tfOnlyXRP | tfTransferable);
 
+/** `NFTokenMint` validation mask for ledgers before `fixRemoveNFTokenAutoTrustLine`.
+ *  Allows `tfTrustLine` in addition to the standard flags. */
 inline constexpr FlagValue tfNFTokenMintOldMask = ~(~tfNFTokenMintMaskWithoutMutable | tfTrustLine);
 
-// if featureDynamicNFT enabled then new flag allowing mutable URI available.
+/** `NFTokenMint` validation mask for ledgers before `fixRemoveNFTokenAutoTrustLine`
+ *  but after `featureDynamicNFT` — allows both `tfTrustLine` and `tfMutable`. */
 inline constexpr FlagValue tfNFTokenMintOldMaskWithMutable = ~(~tfNFTokenMintOldMask | tfMutable);
 
+/** Union of all mutually-exclusive `AMMWithdraw` mode flags.
+ *
+ *  The transactor checks `std::popcount(flags & tfWithdrawSubTx) == 1` to
+ *  ensure exactly one withdrawal mode is selected; zero or more than one
+ *  causes `temMALFORMED`. */
 inline constexpr FlagValue tfWithdrawSubTx = tfLPToken | tfSingleAsset | tfTwoAsset |
     tfOneAssetLPToken | tfLimitLPToken | tfWithdrawAll | tfOneAssetWithdrawAll;
+
+/** Union of all mutually-exclusive `AMMDeposit` mode flags.
+ *
+ *  The transactor checks `std::popcount(flags & tfDepositSubTx) == 1` to
+ *  ensure exactly one deposit mode is selected; zero or more than one
+ *  causes `temMALFORMED`. */
 inline constexpr FlagValue tfDepositSubTx =
     tfLPToken | tfSingleAsset | tfTwoAsset | tfOneAssetLPToken | tfLimitLPToken | tfTwoAssetIfEmpty;
 
@@ -403,7 +534,21 @@ inline constexpr FlagValue tfDepositSubTx =
 #pragma push_macro("ACCOUNTSET_FLAG_TO_VALUE")
 #pragma push_macro("ACCOUNTSET_FLAG_TO_MAP")
 
-// AccountSet SetFlag/ClearFlag values
+/** X-macro table of `AccountSet` `SetFlag`/`ClearFlag` integer values.
+ *
+ *  These are **small integers** (1–17), not bitmasks, and are carried in the
+ *  `SetFlag` or `ClearFlag` field of an `AccountSet` transaction rather than
+ *  in the `Flags` bitmask.  Value 11 is reserved for the Hooks amendment
+ *  (`asfTshCollect`) and is intentionally absent here.
+ *
+ *  The macro is instantiated twice: once to declare inline constants and once
+ *  to build the map returned by `getAsfFlagMap()`.
+ *
+ *  @param ASF_FLAG  Receives `(name, integer_value)` for each `asf*` constant.
+ *
+ *  @warning These values are protocol-stable; changing them breaks existing
+ *      signed `AccountSet` transactions.
+ */
 #define ACCOUNTSET_FLAGS(ASF_FLAG)                \
     ASF_FLAG(asfRequireDest, 1)                   \
     ASF_FLAG(asfRequireAuth, 2)                   \
@@ -429,6 +574,14 @@ inline constexpr FlagValue tfDepositSubTx =
 
 ACCOUNTSET_FLAGS(ACCOUNTSET_FLAG_TO_VALUE)
 
+/** Returns all `AccountSet` `SetFlag`/`ClearFlag` values by name.
+ *
+ *  The map keys are the `asf*` constant names; values are the corresponding
+ *  small integers.  Initialised once (Meyer's singleton) and consumed by the
+ *  `server_definitions` RPC endpoint alongside `getAllTxFlags()`.
+ *
+ *  @return A reference to the singleton `asf*` flag map.
+ */
 inline std::map<std::string, FlagValue> const&
 getAsfFlagMap()
 {
diff --git a/include/xrpl/protocol/TxFormats.h b/include/xrpl/protocol/TxFormats.h
index 77ab069feb..ca842c6042 100644
--- a/include/xrpl/protocol/TxFormats.h
+++ b/include/xrpl/protocol/TxFormats.h
@@ -6,34 +6,30 @@
 
 namespace xrpl {
 
-/** Transaction type identifiers.
-
-    These are part of the binary message format.
-
-    @ingroup protocol
-*/
-/** Transaction type identifiers
-
-    Each ledger object requires a unique type identifier, which is stored
-    within the object itself; this makes it possible to iterate the entire
-    ledger and determine each object's type and verify that the object you
-    retrieved from a given hash matches the expected type.
-
-    @warning Since these values are included in transactions, which are signed
-             objects, and used by the code to determine the type of transaction
-             being invoked, they are part of the protocol. **Changing them
-             should be avoided because without special handling, this will
-             result in a hard fork.**
-
-    @note When retiring types, the specific values should not be removed but
-          should be marked as [[deprecated]]. This is to avoid accidental
-          reuse of identifiers.
-
-    @todo The C++ language does not enable checking for duplicate values
-          here. If it becomes possible then we should do this.
-
-    @ingroup protocol
-*/
+/** Wire-format identifiers for every XRPL transaction type.
+ *
+ *  The numeric values are generated by the X-macro expansion of
+ *  `transactions.macro` and are embedded inside signed transaction objects.
+ *  They are therefore **immutable protocol surface**: a validator that
+ *  assigns a different meaning to a given numeric value cannot participate
+ *  in consensus with its peers, which would cause a hard fork.
+ *
+ *  Deprecated types (`TtNicknameSet`, `TtContract`, `TtSpinalTap`) are
+ *  retained as tombstoned, `[[deprecated]]`-annotated enumerators so that
+ *  their numeric slots can never be accidentally reused by a future
+ *  transaction type — doing so would cause historical ledger data to be
+ *  misclassified.
+ *
+ *  @warning Do not change any existing enumerator value.  Numeric IDs are
+ *           part of the signed binary format and altering them constitutes
+ *           a consensus-breaking protocol change.
+ *
+ *  @note The language cannot detect duplicate enumerator values at compile
+ *      time; duplicate-ID protection is enforced instead at static-init time
+ *      by `TxFormats::TxFormats()` via `KnownFormats::add()`.
+ *
+ *  @ingroup protocol
+ */
 // clang-format off
 // Protocol-critical, hundreds of usages
 // NOLINTNEXTLINE(cppcoreguidelines-use-enum-class)
@@ -64,20 +60,76 @@ enum TxType : std::uint16_t
 };
 // clang-format on
 
-/** Manages the list of known transaction formats.
+/** Singleton registry mapping every XRPL transaction type to its field schema.
+ *
+ *  `TxFormats` inherits `KnownFormats<TxType, TxFormats>`, which stores one
+ *  `Item` per transaction type.  Each `Item` pairs the type's human-readable
+ *  name and `TxType` discriminant with an `SOTemplate` — the ordered list of
+ *  `SOElement` descriptors specifying which SFields the transaction accepts
+ *  and whether each is required, optional, or default.
+ *
+ *  The singleton is constructed lazily on the first call to `getInstance()`.
+ *  During construction, `transactions.macro` is expanded via an X-macro to
+ *  call `KnownFormats::add()` once per transaction type.  Registering a
+ *  duplicate `TxType` value causes an immediate `logicError()` (process
+ *  abort), making collisions visible at startup rather than at request time.
+ *
+ *  Every transaction's `SOTemplate` is formed by merging the type-specific
+ *  fields from `transactions.macro` with the universal common fields returned
+ *  by `getCommonFields()`.  The resulting schema is consulted by the
+ *  deserializer and validator for every transaction that enters the ledger.
+ *
+ *  @note This class is non-copyable.  Obtain the single instance via
+ *      `getInstance()`.
+ *
+ *  @see KnownFormats, TxType, SOTemplate
  */
 class TxFormats : public KnownFormats<TxType, TxFormats>
 {
 private:
-    /** Create the object.
-        This will load the object with all the known transaction formats.
-    */
+    /** Populate the registry with every known transaction format.
+     *
+     *  Called exactly once by `getInstance()`.  Expands `transactions.macro`
+     *  and registers each transaction type via `KnownFormats::add()`.
+     */
     TxFormats();
 
 public:
+    /** Return the process-wide singleton registry of all transaction formats.
+     *
+     *  The registry is constructed on the first call via a function-local
+     *  static, guaranteeing thread-safe initialization under C++11 rules for
+     *  local statics.  The same reference is returned on every subsequent
+     *  call.
+     *
+     *  @return A stable `const` reference to the singleton `TxFormats`
+     *      instance.
+     */
     static TxFormats const&
     getInstance();
 
+    /** Return the fields shared by every XRPL transaction, regardless of type.
+     *
+     *  The returned vector is merged with each transaction's unique fields
+     *  inside `KnownFormats::add()` to form the complete `SOTemplate` for
+     *  that type.  Required entries are `sfTransactionType`, `sfAccount`,
+     *  `sfSequence`, `sfFee`, and `sfSigningPubKey`; a transaction missing
+     *  any of them fails template validation.
+     *
+     *  Notable optional fields and their roles:
+     *  - `sfTicketSequence` — consume a pre-issued ticket instead of the
+     *      account's current sequence, enabling out-of-order submission.
+     *  - `sfSigners` — multi-signature array; coexists with `sfSigningPubKey`
+     *      because single-sig and multi-sig are orthogonal format modes.
+     *  - `sfNetworkID` — distinguishes sidechain transactions from mainnet
+     *      ones at the wire level.
+     *  - `sfDelegate` — authorizes a second account to act on behalf of the
+     *      fee-paying account.
+     *
+     *  @return A stable `const` reference to the static common-field vector.
+     *      The vector is initialized on the first call and lives for the
+     *      lifetime of the process.
+     */
     static std::vector<SOElement> const&
     getCommonFields();
 };
diff --git a/include/xrpl/protocol/TxMeta.h b/include/xrpl/protocol/TxMeta.h
index 6895350e9f..de25392faf 100644
--- a/include/xrpl/protocol/TxMeta.h
+++ b/include/xrpl/protocol/TxMeta.h
@@ -11,71 +11,245 @@
 
 namespace xrpl {
 
+/** Metadata record for a single transaction applied to a closed XRPL ledger.
+ *
+ *  Every validated transaction carries a metadata blob alongside the
+ *  transaction itself. This class owns that metadata: the result code, the
+ *  transaction's ordinal position within the ledger, and the `AffectedNodes`
+ *  array — one entry per ledger object that was created, modified, or deleted.
+ *
+ *  The primary lifecycle is: construct empty via `TxMeta(txid, ledger)`,
+ *  accumulate node records through `setAffectedNode` / `getAffectedNode` (both
+ *  called by `ApplyStateTable`), then finalize with a single call to
+ *  `addRaw()`. Calling `getAsObject()` or `getJson()` before `addRaw()` will
+ *  trigger an assertion because `result_` still holds the sentinel value 255.
+ *
+ *  The two deserializing constructors handle the opposite direction: loading
+ *  existing metadata from raw bytes (database / wire) or from an already-parsed
+ *  `STObject` (ledger replay, RPC).
+ *
+ *  @note `TxMeta` is a passive data container. All change-detection and
+ *      field-diff logic lives in `ApplyStateTable::apply()`, which drives the
+ *      accumulation protocol.
+ *  @note `addRaw()` sorts `nodes_` by `sfLedgerIndex` before serializing.
+ *      This sort is consensus-critical: validators must produce byte-identical
+ *      metadata blobs for the SHAMap hash to agree.
+ */
 class TxMeta
 {
 public:
+    /** Construct an empty metadata shell for a transaction being applied.
+     *
+     *  Initializes `result_` to 255 and `index_` to `UINT32_MAX` as sentinels
+     *  indicating the object has not yet been finalized. Pre-reserves 32 slots
+     *  in `nodes_` to absorb typical transaction complexity without
+     *  reallocation. Must be finalized by `addRaw()` before serialization.
+     *
+     *  @param transactionID Hash of the transaction this metadata describes.
+     *  @param ledger        Sequence number of the ledger in which the
+     *      transaction is included.
+     */
     TxMeta(uint256 const& transactionID, std::uint32_t ledger);
+
+    /** Deserialize metadata from a raw byte blob.
+     *
+     *  Wraps `vec` in a `SerialIter`, materializes an `STObject` tagged
+     *  `sfMetadata`, and extracts `sfTransactionResult`, `sfTransactionIndex`,
+     *  and `sfAffectedNodes`. Also reads optional `sfDeliveredAmount` and
+     *  `sfParentBatchID` via `setAdditionalFields`. Used when loading existing
+     *  metadata from the ledger database or from the wire.
+     *
+     *  @param txID   Hash of the transaction this metadata describes.
+     *  @param ledger Sequence number of the containing ledger.
+     *  @param vec    Raw serialized metadata bytes.
+     */
     TxMeta(uint256 const& txID, std::uint32_t ledger, Blob const&);
+
+    /** Construct from an already-parsed STObject.
+     *
+     *  Extracts `sfTransactionResult`, `sfTransactionIndex`, and
+     *  `sfAffectedNodes` from `obj`, plus any optional fields. Used during
+     *  ledger replay and in RPC code paths where the metadata has already been
+     *  deserialized into the `STObject` type hierarchy.
+     *
+     *  @param txID   Hash of the transaction this metadata describes.
+     *  @param ledger Sequence number of the containing ledger.
+     *  @param obj    Fully deserialized metadata object (e.g. `sfMetadata`).
+     */
     TxMeta(uint256 const& txID, std::uint32_t ledger, STObject const&);
 
+    /** Return the hash of the transaction this metadata record describes. */
     [[nodiscard]] uint256 const&
     getTxID() const
     {
         return transactionID_;
     }
+
+    /** Return the sequence number of the ledger that included this transaction. */
     [[nodiscard]] std::uint32_t
     getLgrSeq() const
     {
         return ledgerSeq_;
     }
+
+    /** Return the raw integer representation of the transaction result code.
+     *
+     *  Holds 255 until `addRaw()` has been called; callers that need a typed
+     *  result should prefer `getResultTER()`.
+     *
+     *  @return Raw `TER` integer value (0 = tesSUCCESS, 101–255 = tec codes).
+     */
     [[nodiscard]] int
     getResult() const
     {
         return result_;
     }
+
+    /** Return the transaction result as a typed `TER` code.
+     *
+     *  @note Returns a meaningless value if called before `addRaw()`.
+     */
     [[nodiscard]] TER
     getResultTER() const
     {
         return TER::fromInt(result_);
     }
+
+    /** Return the transaction's ordinal position within its ledger.
+     *
+     *  Holds `UINT32_MAX` until `addRaw()` has been called.
+     */
     [[nodiscard]] std::uint32_t
     getIndex() const
     {
         return index_;
     }
 
+    /** Register or reclassify a ledger entry in the affected-nodes list.
+     *
+     *  If a node with the given key already exists, its field name and
+     *  `sfLedgerEntryType` are updated in place — allowing a caller to
+     *  upgrade an entry from `sfModifiedNode` to `sfDeletedNode`, for
+     *  example. Otherwise a new entry is appended to `nodes_`.
+     *
+     *  @param node     The `sfLedgerIndex` key of the affected ledger entry.
+     *  @param type     Node category: `sfCreatedNode`, `sfModifiedNode`, or
+     *      `sfDeletedNode`.
+     *  @param nodeType The `sfLedgerEntryType` value (e.g. `ltACCOUNT_ROOT`).
+     */
     void
     setAffectedNode(uint256 const&, SField const& type, std::uint16_t nodeType);
+
+    /** Retrieve or create the metadata node for a live ledger entry.
+     *
+     *  Finds the node whose `sfLedgerIndex` matches `node->key()`, creating a
+     *  new entry (copying the entry type from the live SLE) if none exists.
+     *  Used by `ApplyStateTable` to attach `sfPreviousFields`, `sfFinalFields`,
+     *  or `sfNewFields` sub-objects after the node has been registered via
+     *  `setAffectedNode`.
+     *
+     *  @param node Live ledger entry whose metadata node is requested.
+     *  @param type Node category used when a new entry must be created.
+     *  @return Mutable reference to the matching `STObject` in `nodes_`.
+     */
     STObject&
     getAffectedNode(SLE::ref node, SField const& type);  // create if needed
+
+    /** Retrieve the metadata node for a ledger-entry key, asserting it exists.
+     *
+     *  Used after `setAffectedNode` has guaranteed registration of the key.
+     *  Calls `UNREACHABLE` in debug builds and throws in release if the key is
+     *  absent — absence indicates a programming error, not a data error.
+     *
+     *  @param node The `sfLedgerIndex` key to look up.
+     *  @return Mutable reference to the matching `STObject` in `nodes_`.
+     *  @throws std::runtime_error If the node is not found (should never occur
+     *      in correct callers).
+     */
     STObject&
     getAffectedNode(uint256 const&);
 
-    /** Return a list of accounts affected by this transaction */
+    /** Return the set of every account implicated by this transaction's metadata.
+     *
+     *  Scans `sfNewFields` for created nodes and `sfFinalFields` for modified
+     *  and deleted nodes, extracting `AccountID` values from `STAccount`
+     *  fields, from the issuers embedded in `sfLowLimit`, `sfHighLimit`,
+     *  `sfTakerPays`, and `sfTakerGets` amounts, and from the issuer encoded in
+     *  `sfMPTokenIssuanceID`.
+     *
+     *  @note The behavior must remain identical to that of the JavaScript
+     *      `Meta#getAffectedAccounts` method for cross-platform consistency.
+     *  @return Sorted, deduplicated flat set of affected `AccountID` values.
+     */
     [[nodiscard]] boost::container::flat_set<AccountID>
     getAffectedAccounts() const;
 
+    /** Serialize the metadata as JSON via the underlying `STObject`.
+     *
+     *  Delegates to `getAsObject().getJson(p)`. Must not be called before
+     *  `addRaw()` finalizes `result_`.
+     *
+     *  @param p JSON formatting options.
+     *  @return JSON representation of the complete metadata object.
+     */
     [[nodiscard]] json::Value
     getJson(JsonOptions p) const
     {
         return getAsObject().getJson(p);
     }
+
+    /** Finalize and append the metadata bytes to a Serializer.
+     *
+     *  Records `result` and `index`, then sorts `nodes_` by `sfLedgerIndex`
+     *  before calling `getAsObject().add(s)`. The sort is consensus-critical:
+     *  nodes are accumulated in execution order, which is not deterministic
+     *  across implementations; sorting by key ensures all validators produce
+     *  byte-identical metadata blobs for the same transaction.
+     *
+     *  Must be called exactly once per `TxMeta` instance, before any call to
+     *  `getAsObject()` or `getJson()`.
+     *
+     *  @param s      Serializer to append the metadata bytes to.
+     *  @param result The `TER` outcome of the transaction.
+     *  @param index  The transaction's ordinal position within the closed ledger.
+     */
     void
     addRaw(Serializer&, TER, std::uint32_t index);
 
+    /** Assemble the complete metadata as an `STObject`.
+     *
+     *  Constructs an `sfTransactionMetaData` object containing
+     *  `sfTransactionResult`, `sfTransactionIndex`, `sfAffectedNodes`, and
+     *  optionally `sfDeliveredAmount` and `sfParentBatchID`.
+     *
+     *  @note Asserts `result_ != 255`; call `addRaw()` first.
+     *  @return Fully populated `STObject` tagged `sfTransactionMetaData`.
+     */
     [[nodiscard]] STObject
     getAsObject() const;
+
+    /** Return a mutable reference to the raw affected-nodes array. */
     STArray&
     getNodes()
     {
         return nodes_;
     }
+
+    /** Return a read-only reference to the raw affected-nodes array. */
     [[nodiscard]] STArray const&
     getNodes() const
     {
         return nodes_;
     }
 
+    /** Extract and store optional fields from an existing metadata object.
+     *
+     *  Reads `sfDeliveredAmount` and `sfParentBatchID` from `obj` when
+     *  present. Called by the deserializing constructors immediately after
+     *  extracting the required fields.
+     *
+     *  @param obj Source object from which to read optional metadata fields.
+     */
     void
     setAdditionalFields(STObject const& obj)
     {
@@ -86,18 +260,40 @@ public:
             parentBatchID_ = obj.getFieldH256(sfParentBatchID);
     }
 
+    /** Return the optional delivered amount recorded for this transaction.
+     *
+     *  Present only for payment transactions where the amount actually
+     *  delivered may differ from the `Amount` field (e.g. partial payments).
+     *  Absent for all other transaction types.
+     */
     [[nodiscard]] std::optional<STAmount> const&
     getDeliveredAmount() const
     {
         return deliveredAmount_;
     }
 
+    /** Set the optional delivered amount for a payment transaction.
+     *
+     *  Called by `ApplyStateTable` after the payment engine resolves path
+     *  execution. Pass `std::nullopt` to clear a previously set value.
+     *
+     *  @param amount The actual amount delivered, or `std::nullopt` to clear.
+     */
     void
     setDeliveredAmount(std::optional<STAmount> const& amount)
     {
         deliveredAmount_ = amount;
     }
 
+    /** Set the optional parent Batch transaction ID.
+     *
+     *  Links this transaction's metadata to the enclosing Batch transaction
+     *  (Batch amendment). Propagated from `ApplyContext`, which receives it
+     *  from the outermost batch-processing layer.
+     *
+     *  @param id The hash of the parent Batch transaction, or `std::nullopt`
+     *      if this transaction is not part of a batch.
+     */
     void
     setParentBatchID(std::optional<uint256> const& id)
     {
diff --git a/include/xrpl/protocol/TxSearched.h b/include/xrpl/protocol/TxSearched.h
index c3359ee5ac..7eb5f29408 100644
--- a/include/xrpl/protocol/TxSearched.h
+++ b/include/xrpl/protocol/TxSearched.h
@@ -2,6 +2,47 @@
 
 namespace xrpl {
 
-enum class TxSearched { All, Some, Unknown };
+/** Coverage completeness of a transaction search over the node's local ledger history.
+ *
+ *  When a client queries for a transaction by hash and the transaction is not
+ *  found, the result is ambiguous: the transaction may genuinely not exist in
+ *  the requested range, or the node may simply lack some of those ledgers
+ *  locally. This enum is the discriminant that resolves that ambiguity.
+ *
+ *  It is the alternative type in the `std::variant` returned by
+ *  `TransactionMaster::fetch()` and `RelationalDatabase::getTransaction()`:
+ *  when no transaction is found, the variant holds a `TxSearched` value
+ *  encoding both the "not found" signal and the confidence level of that
+ *  determination.
+ *
+ *  The RPC layer collapses `All` and `Some` into a boolean `searched_all`
+ *  field in the JSON response, and suppresses the field entirely when the
+ *  state is `Unknown`.
+ *
+ *  @see TransactionMaster::fetch()
+ *  @see RelationalDatabase::getTransaction()
+ */
+enum class TxSearched {
+    /** The node searched its entire local history for the requested ledger
+     *  range and confirmed the transaction is absent. The search was
+     *  exhaustive; a client can be confident the transaction was not
+     *  included in that range.
+     */
+    All,
+
+    /** The node attempted the search but its local ledger store is
+     *  incomplete for the requested range — some ledgers were missing from
+     *  the database. Absence of the transaction is therefore inconclusive.
+     */
+    Some,
+
+    /** Coverage information is unavailable. This occurs when no ledger
+     *  range was specified, a deserialization error occurred, or the
+     *  database layer could not determine search coverage. The
+     *  `searched_all` field is suppressed in the JSON response when this
+     *  state is active.
+     */
+    Unknown,
+};
 
 }  // namespace xrpl
diff --git a/include/xrpl/protocol/UintTypes.h b/include/xrpl/protocol/UintTypes.h
index 322c58ea1f..ead1bd5c80 100644
--- a/include/xrpl/protocol/UintTypes.h
+++ b/include/xrpl/protocol/UintTypes.h
@@ -1,3 +1,19 @@
+/** @file
+ *  Defines the strongly-typed fixed-width integer identifiers used throughout
+ *  the XRPL protocol layer.
+ *
+ *  Rather than passing bare `uint160` or `uint256` values, this header creates
+ *  a family of mutually-incompatible types via the tag-parameter mechanism of
+ *  `BaseUInt<Bits, Tag>`.  A `Currency`, a `NodeID`, and an `AccountID` are
+ *  all 160-bit values at the hardware level but are distinct C++ types, so the
+ *  compiler rejects accidental substitutions at compile time.  The tag classes
+ *  themselves contribute no data members and no runtime overhead.
+ *
+ *  Also declares the three sentinel `Currency` values (`xrpCurrency`,
+ *  `noCurrency`, `badCurrency`) and the string ↔ `Currency` conversion
+ *  functions that implement the XRPL wire-format currency encoding.
+ */
+
 #pragma once
 
 #include <xrpl/basics/UnorderedContainers.h>
@@ -8,18 +24,38 @@
 namespace xrpl {
 namespace detail {
 
+/** Phantom tag type that makes `Currency` a distinct strong type.
+ *
+ *  Passed as the second template argument to `BaseUInt<160, Tag>` so that
+ *  a 160-bit currency value cannot be silently used where a `NodeID` or raw
+ *  hash is expected, and vice versa.  The class has no data members or
+ *  behaviour; it exists only to produce a unique template instantiation.
+ */
 class CurrencyTag
 {
 public:
     explicit CurrencyTag() = default;
 };
 
+/** Phantom tag type that makes `Directory` a distinct strong type.
+ *
+ *  Passed as the second template argument to `BaseUInt<256, Tag>`.  Without
+ *  this tag, a `Directory` and an untagged `uint256` would share the same
+ *  type and be freely interchangeable.  The class has no data members or
+ *  behaviour.
+ */
 class DirectoryTag
 {
 public:
     explicit DirectoryTag() = default;
 };
 
+/** Phantom tag type that makes `NodeID` a distinct strong type.
+ *
+ *  Passed as the second template argument to `BaseUInt<160, Tag>` so that
+ *  a 160-bit validator node ID cannot be silently used where a `Currency` or
+ *  `AccountID` is expected.  The class has no data members or behaviour.
+ */
 class NodeIDTag
 {
 public:
@@ -28,66 +64,170 @@ public:
 
 }  // namespace detail
 
-/** Directory is an index into the directory of offer books.
-    The last 64 bits of this are the quality. */
+/** A 256-bit index into the DEX offer-book directory.
+ *
+ *  The last 64 bits of this value encode the order-book quality (in big-endian
+ *  byte order), so that the natural `SHAMap` sort order over directory keys
+ *  matches price-ascending order.  The `detail::DirectoryTag` phantom type
+ *  makes this a distinct C++ type from untagged `uint256`.
+ *
+ *  @see keylet::quality(), Quality
+ */
 using Directory = BaseUInt<256, detail::DirectoryTag>;
 
-/** Currency is a hash representing a specific currency. */
+/** A 160-bit identifier for an XRP Ledger currency.
+ *
+ *  Distinct from `NodeID` and `AccountID` at the C++ type level, even though
+ *  all three are 160-bit values.  The canonical encoding of the native asset
+ *  (XRP) is the all-zero value; use `xrpCurrency()` and `isXRP()` rather than
+ *  constructing zero directly.  ISO-style 3-character codes occupy bytes 12–14
+ *  of the 20-byte wire representation, with all other bytes zero.
+ *
+ *  @see xrpCurrency(), noCurrency(), badCurrency(), isXRP(), to_string(),
+ *      toCurrency()
+ */
 using Currency = BaseUInt<160, detail::CurrencyTag>;
 
-/** NodeID is a 160-bit hash representing one node. */
+/** A 160-bit identifier for a validator node.
+ *
+ *  Distinct from `Currency` and `AccountID` at the C++ type level via the
+ *  `detail::NodeIDTag` phantom parameter.  Derived from the node's public key
+ *  via SHA-256 + RIPEMD-160 (the same derivation as `AccountID`).
+ */
 using NodeID = BaseUInt<160, detail::NodeIDTag>;
 
-/** MPTID is a 192-bit value representing MPT Issuance ID,
- * which is a concatenation of a 32-bit sequence (big endian)
- * and a 160-bit account */
+/** A 192-bit identifier for an MPT (Multi-Purpose Token) issuance.
+ *
+ *  Composed of a 32-bit sequence number (big-endian) in the high bits followed
+ *  by the 160-bit issuer `AccountID`.  No tag parameter is used because no
+ *  other 192-bit type exists in the protocol; the added friction of an empty
+ *  tag class is not justified when there is nothing to confuse it with.
+ */
 using MPTID = BaseUInt<192>;
 
-/** Domain is a 256-bit hash representing a specific domain. */
+/** A 256-bit generic domain hash.
+ *
+ *  No tag parameter is used because there is no other untagged 256-bit type it
+ *  could be confused with in the same contexts; see `Directory` for the tagged
+ *  256-bit counterpart.
+ */
 using Domain = BaseUInt<256>;
 
-/** XRP currency. */
+/** Return the canonical encoding of XRP, the ledger's native asset.
+ *
+ *  The all-zero 160-bit value (`beast::kZERO`) is the protocol-defined
+ *  representation of XRP.  `isXRP(Currency const&)` tests equality against
+ *  this value.  The returned reference points to a function-local static and
+ *  is valid for the lifetime of the process.
+ *
+ *  @return A `const` reference to the singleton zero `Currency`.
+ *  @see isXRP(Currency const&), noCurrency(), badCurrency()
+ */
 Currency const&
 xrpCurrency();
 
-/** A placeholder for empty currencies. */
+/** Return a placeholder sentinel used when no currency is meaningful.
+ *
+ *  Holds the value `1`.  Data structures that require a `Currency` slot but
+ *  have no actual currency to store use this sentinel rather than zero (which
+ *  would be mistaken for XRP).  The returned reference is to a function-local
+ *  static valid for the process lifetime.
+ *
+ *  @return A `const` reference to the singleton `Currency{1}`.
+ *  @see xrpCurrency(), badCurrency()
+ */
 Currency const&
 noCurrency();
 
-/** We deliberately disallow the currency that looks like "XRP" because too
-    many people were using it instead of the correct XRP currency. */
+/** Return the poisoned sentinel for the "XRP as ISO code" misuse.
+ *
+ *  Early adopters sometimes encoded XRP using the three-letter ISO code
+ *  `"XRP"` (byte value `0x5852500000000000` placed at bytes 12–14), rather
+ *  than the correct all-zero form.  This sentinel lets code paths detect and
+ *  reject that mistake explicitly.  `to_string()` on this value produces a
+ *  40-character hex string, not `"XRP"`, making the anomaly visible.  The
+ *  returned reference is to a function-local static valid for the process
+ *  lifetime.
+ *
+ *  @return A `const` reference to the singleton `Currency{0x5852500000000000}`.
+ *  @see xrpCurrency(), noCurrency(), toCurrency()
+ */
 Currency const&
 badCurrency();
 
+/** Test whether a `Currency` represents the native XRP asset.
+ *
+ *  @param c The currency to test.
+ *  @return `true` if `c` equals `beast::kZERO` (i.e., equals `xrpCurrency()`).
+ */
 inline bool
 isXRP(Currency const& c)
 {
     return c == beast::kZERO;
 }
 
-/** Returns "", "XRP", or three letter ISO code. */
+/** Convert a `Currency` to its canonical string representation.
+ *
+ *  Applies a priority-ordered decision tree:
+ *  - Zero value → `"XRP"` (native asset).
+ *  - `noCurrency()` → `"1"`.
+ *  - All non-ISO bytes zero and the 3-character code in the allowed character
+ *    set (alphanumeric plus `<>(){}[]|?!@#$%^&*`) and not equal to `"XRP"` →
+ *    the three-character string.
+ *  - Everything else → a 40-character uppercase hex string.
+ *
+ *  @param c The currency value to convert.
+ *  @return A string in one of the four forms described above.
+ *  @note A currency whose ISO bytes spell `"XRP"` but whose surrounding bytes
+ *      are non-zero is returned as hex, making the anomaly visible rather than
+ *      silently aliasing to the native currency.
+ */
 std::string
 to_string(Currency const& c);
 
-/** Tries to convert a string to a Currency, returns true on success.
-
-    @note This function will return success if the resulting currency is
-          badCurrency(). This legacy behavior is unfortunate; changing this
-          will require very careful checking everywhere and may mean having
-          to rewrite some unit test code.
-*/
+/** Parse a string into a `Currency`, reporting success via the return value.
+ *
+ *  Accepted forms:
+ *  - Empty string or `"XRP"` → sets `currency` to `xrpCurrency()` (all zero).
+ *  - Exactly 3 characters from the XRPL ISO character set → zero-pads and
+ *    writes the code at byte offset 12 of `currency`.
+ *  - 40-character hex string → parsed directly into `currency`.
+ *  - Anything else → returns `false` and leaves `currency` unmodified.
+ *
+ *  @param currency Output: receives the parsed `Currency` on success.
+ *  @param code The string to parse.
+ *  @return `true` if parsing succeeded; `false` otherwise.
+ *  @note Returns `true` even when the result equals `badCurrency()`.  This
+ *      legacy behaviour is preserved to avoid breaking existing callers;
+ *      validate the output value separately if `badCurrency()` must be
+ *      excluded.
+ */
 bool
 toCurrency(Currency&, std::string const&);
 
-/** Tries to convert a string to a Currency, returns noCurrency() on failure.
-
-    @note This function can return badCurrency(). This legacy behavior is
-          unfortunate; changing this will require very careful checking
-          everywhere and may mean having to rewrite some unit test code.
-*/
+/** Parse a string into a `Currency`, returning `noCurrency()` on failure.
+ *
+ *  Convenience wrapper around `toCurrency(Currency&, std::string const&)`.
+ *  Prefer the two-argument overload when the caller must distinguish a parse
+ *  failure from a legitimately absent currency.
+ *
+ *  @param code The string to parse.
+ *  @return The parsed `Currency`, or `noCurrency()` if the string is invalid.
+ *  @note Can return `badCurrency()` for hex input that encodes that sentinel.
+ *      This legacy behaviour is preserved; callers should validate the result
+ *      if they need to exclude `badCurrency()`.
+ */
 Currency
 toCurrency(std::string const&);
 
+/** Write the string representation of a `Currency` to an output stream.
+ *
+ *  Delegates to `to_string(Currency const&)`.
+ *
+ *  @param os The stream to write to.
+ *  @param x The currency to format.
+ *  @return `os`, to allow chaining.
+ */
 inline std::ostream&
 operator<<(std::ostream& os, Currency const& x)
 {
@@ -99,24 +239,48 @@ operator<<(std::ostream& os, Currency const& x)
 
 namespace std {
 
+/** `std::hash` specialization for `xrpl::Currency`.
+ *
+ *  Inherits the `hasher` inner type provided by `BaseUInt`, enabling
+ *  `Currency` to be used directly as a key in `std::unordered_map` and
+ *  `std::unordered_set`.
+ */
 template <>
 struct hash<xrpl::Currency> : xrpl::Currency::hasher
 {
     hash() = default;
 };
 
+/** `std::hash` specialization for `xrpl::NodeID`.
+ *
+ *  Inherits the `hasher` inner type provided by `BaseUInt`, enabling
+ *  `NodeID` to be used directly as a key in `std::unordered_map` and
+ *  `std::unordered_set`.
+ */
 template <>
 struct hash<xrpl::NodeID> : xrpl::NodeID::hasher
 {
     hash() = default;
 };
 
+/** `std::hash` specialization for `xrpl::Directory`.
+ *
+ *  Inherits the `hasher` inner type provided by `BaseUInt`, enabling
+ *  `Directory` to be used directly as a key in `std::unordered_map` and
+ *  `std::unordered_set`.
+ */
 template <>
 struct hash<xrpl::Directory> : xrpl::Directory::hasher
 {
     hash() = default;
 };
 
+/** `std::hash` specialization for `xrpl::uint256`.
+ *
+ *  Inherits the `hasher` inner type provided by `BaseUInt`.  Included here
+ *  because `uint256` is used in the same contexts as `Currency`, `NodeID`,
+ *  and `Directory`, even though it is not exclusively defined in this file.
+ */
 template <>
 struct hash<xrpl::uint256> : xrpl::uint256::hasher
 {
diff --git a/include/xrpl/protocol/Units.h b/include/xrpl/protocol/Units.h
index dd5cfdeffd..260b9ec414 100644
--- a/include/xrpl/protocol/Units.h
+++ b/include/xrpl/protocol/Units.h
@@ -1,3 +1,12 @@
+/** @file
+ *  Type-safe unit arithmetic for the XRP Ledger.
+ *
+ *  Defines the `ValueUnit<UnitTag, T>` phantom-typed wrapper and its concrete
+ *  aliases (`FeeLevel64`, `Bips32`, etc.) that prevent silent mixing of
+ *  conceptually different integer quantities (drops, fee levels, basis points).
+ *  Also provides `mulDiv`, an overflow-safe scaled-arithmetic helper that
+ *  preserves unit constraints across cross-type computations.
+ */
 #pragma once
 
 #include <xrpl/basics/safe_cast.h>
@@ -16,35 +25,59 @@ namespace xrpl {
 
 namespace unit {
 
-/** "drops" are the smallest divisible amount of XRP. This is what most
-    of the code uses. */
+/** Tag type identifying a quantity measured in drops (the smallest XRP unit).
+ *
+ *  Used as the `UnitTag` parameter of `ValueUnit` to produce drop-valued
+ *  types. `XRPAmount` (defined in `XRPAmount.h`) is the primary alias.
+ */
 struct dropTag;
-/** "fee levels" are used by the transaction queue to compare the relative
-    cost of transactions that require different levels of effort to process.
-    See also: src/xrpld/app/misc/FeeEscalation.md#fee-level */
+
+/** Tag type identifying a fee-level quantity used by the transaction queue.
+ *
+ *  Fee levels are dimensionless ratios that let the queue compare the relative
+ *  cost of transactions with different processing effort.
+ *  @see src/xrpld/app/misc/FeeEscalation.md#fee-level
+ */
 struct feelevelTag;
-/** unitless values are plain scalars wrapped in a ValueUnit. They are
-    used for calculations in this header. */
+
+/** Tag type for plain scalars participating in unit-checked arithmetic.
+ *
+ *  Raw `uint64_t` arguments passed to `mulDiv` are wrapped in
+ *  `ValueUnit<unitlessTag, uint64_t>` via `unit::scalar()` so the inner
+ *  `mulDivU` implementation only needs to handle the typed case.
+ */
 struct unitlessTag;
 
-/** Units to represent basis points (bips) and 1/10 basis points */
+/** Tag type identifying a quantity measured in basis points (1/100 of 1%). */
 class BipsTag;
+
+/** Tag type identifying a quantity measured in tenth-basis-points (1/1000 of 1%). */
 class TenthBipsTag;
 
 // These names don't have to be too descriptive, because we're in the "unit"
 // namespace.
 
+/** Concept satisfied by any `ValueUnit` specialization.
+ *
+ *  Requires the nested `unit_type` and `value_type` aliases that every
+ *  `ValueUnit` exposes.  Used as the base constraint for all other
+ *  unit-system concepts.
+ *
+ *  @tparam T The type to check.
+ */
 template <class T>
 concept Valid = std::is_class_v<T> && std::is_object_v<typename T::unit_type> &&
     std::is_object_v<typename T::value_type>;
 
-/** `Usable` is checked to ensure that only values with
-    known valid type tags can be used (sometimes transparently) in
-    non-unit contexts. At the time of implementation, this includes
-    all known tags, but more may be added in the future, and they
-    should not be added automatically unless determined to be
-    appropriate.
-*/
+/** Concept satisfied by `ValueUnit` types whose tag is an approved known unit.
+ *
+ *  Acts as an explicit whitelist: new tags do not automatically gain access
+ *  to JSON serialisation (`jsonClipped`) or other non-unit-domain operations.
+ *  Currently admits `dropTag`, `feelevelTag`, `unitlessTag`, `BipsTag`, and
+ *  `TenthBipsTag`.
+ *
+ *  @tparam T The type to check.
+ */
 template <class T>
 concept Usable = Valid<T> &&
     (std::is_same_v<typename T::unit_type, feelevelTag> ||
@@ -53,21 +86,73 @@ concept Usable = Valid<T> &&
      std::is_same_v<typename T::unit_type, BipsTag> ||
      std::is_same_v<typename T::unit_type, TenthBipsTag>);
 
+/** Concept satisfied when `Other` is an arithmetic type convertible to `VU`'s
+ *  value type.
+ *
+ *  Enables cross-scalar arithmetic on a `ValueUnit` (e.g. multiplying a
+ *  `FeeLevel64` by a raw `uint64_t`).
+ *
+ *  @tparam Other The scalar type to check.
+ *  @tparam VU    The `ValueUnit` specialization to check compatibility with.
+ */
 template <class Other, class VU>
 concept Compatible =
     Valid<VU> && std::is_arithmetic_v<Other> && std::is_arithmetic_v<typename VU::value_type> &&
     std::is_convertible_v<Other, typename VU::value_type>;
 
+/** Concept satisfied when `T` is an integral type. */
 template <class T>
 concept Integral = std::is_integral_v<T>;
 
+/** Concept satisfied when a `ValueUnit`'s value type is integral.
+ *
+ *  Required for modulo (`%=`) and cast operations.
+ *
+ *  @tparam VU The `ValueUnit` specialization to check.
+ */
 template <class VU>
 concept IntegralValue = Integral<typename VU::value_type>;
 
+/** Concept satisfied when two `ValueUnit` types share the same unit tag and
+ *  both have integral value types.
+ *
+ *  Guards `safe_cast` and `unsafe_cast` between `ValueUnit` specializations
+ *  (e.g. `FeeLevel<uint32_t>` to `FeeLevel64`).
+ *
+ *  @tparam VU1 Source `ValueUnit` type.
+ *  @tparam VU2 Destination `ValueUnit` type.
+ */
 template <class VU1, class VU2>
 concept CastableValue = IntegralValue<VU1> && IntegralValue<VU2> &&
     std::is_same_v<typename VU1::unit_type, typename VU2::unit_type>;
 
+/** Phantom-typed wrapper that attaches a compile-time unit tag to an
+ *  arithmetic value, preventing silent mixing of incompatible quantities.
+ *
+ *  The `UnitTag` type is never instantiated; it only serves as a type-system
+ *  discriminator.  Arithmetic operators are generated by `boost::operators`
+ *  mixins from a small set of explicitly defined primitives:
+ *
+ *  - **Addition / subtraction** between two `ValueUnit` of the same unit, or
+ *    between a `ValueUnit` and a raw scalar, preserve the unit.
+ *  - **Multiplication** by a raw scalar preserves the unit (commutativity is
+ *    handled by a `friend operator*`).
+ *  - **Division** of two same-unit `ValueUnit`s returns the raw `value_type`
+ *    (a dimensionless ratio); division by a scalar preserves the unit.
+ *  - **Negation** is compile-time-rejected for unsigned value types via
+ *    `static_assert`.
+ *
+ *  A `ValueUnit<Unit, Wide>` can be implicitly constructed from
+ *  `ValueUnit<Unit, Narrow>` when `SafeToCast<Narrow, Wide>` is satisfied
+ *  (same-sign widening).  The reverse requires `safe_cast` or `unsafe_cast`.
+ *
+ *  Integrates with `beast::Zero`: an explicit constructor from `beast::Zero`
+ *  and `signum()` let the beast zero-comparison machinery generate all six
+ *  relational operators against zero without a temporary allocation.
+ *
+ *  @tparam UnitTag An empty tag type (e.g. `dropTag`, `feelevelTag`).
+ *  @tparam T       The underlying arithmetic value type.
+ */
 template <class UnitTag, class T>
 class ValueUnit : private boost::totally_ordered<ValueUnit<UnitTag, T>>,
                   private boost::additive<ValueUnit<UnitTag, T>>,
@@ -89,10 +174,12 @@ public:
     constexpr ValueUnit&
     operator=(ValueUnit const& other) = default;
 
+    /** Construct a zero-valued unit, integrating with `beast::Zero`. */
     constexpr explicit ValueUnit(beast::Zero) : value_(0)
     {
     }
 
+    /** Assign zero, integrating with `beast::Zero`. */
     constexpr ValueUnit&
     operator=(beast::Zero)
     {
@@ -100,10 +187,20 @@ public:
         return *this;
     }
 
+    /** Construct from a raw value of the underlying arithmetic type.
+     *
+     *  Explicit to prevent accidental construction from unrelated integers.
+     *
+     *  @param value The raw value to wrap.
+     */
     constexpr explicit ValueUnit(value_type value) : value_(value)
     {
     }
 
+    /** Assign from a raw value of the underlying arithmetic type.
+     *
+     *  @param value The raw value to wrap.
+     */
     constexpr ValueUnit&
     operator=(value_type value)
     {
@@ -111,9 +208,16 @@ public:
         return *this;
     }
 
-    /** Instances with the same unit, and a type that is
-        "safe" to convert to this one can be converted
-        implicitly */
+    /** Implicit widening conversion from a narrower same-unit `ValueUnit`.
+     *
+     *  Enabled only when `SafeToCast<Other, value_type>` is satisfied, i.e.
+     *  same signedness and `value_type` is at least as wide as `Other`.
+     *  This allows e.g. `FeeLevel<uint32_t>` to widen to `FeeLevel64`
+     *  without an explicit cast, mirroring ordinary C++ arithmetic widening.
+     *
+     *  @tparam Other The narrower underlying type of the source.
+     *  @param value  The source `ValueUnit` to convert from.
+     */
     template <Compatible<ValueUnit> Other>
     constexpr ValueUnit(ValueUnit<unit_type, Other> const& value)
         requires SafeToCast<Other, value_type>
@@ -121,12 +225,23 @@ public:
     {
     }
 
+    /** Add a raw scalar to this unit value, preserving the unit.
+     *
+     *  @param rhs Scalar to add.
+     *  @return A new `ValueUnit` of the same unit.
+     */
     constexpr ValueUnit
     operator+(value_type const& rhs) const
     {
         return ValueUnit{value_ + rhs};
     }
 
+    /** Add a `ValueUnit` to a raw scalar (commutative form).
+     *
+     *  @param lhs Scalar left-hand side.
+     *  @param rhs `ValueUnit` right-hand side.
+     *  @return A new `ValueUnit` of the same unit.
+     */
     friend constexpr ValueUnit
     operator+(value_type lhs, ValueUnit const& rhs)
     {
@@ -134,12 +249,25 @@ public:
         return rhs + lhs;
     }
 
+    /** Subtract a raw scalar from this unit value, preserving the unit.
+     *
+     *  @param rhs Scalar to subtract.
+     *  @return A new `ValueUnit` of the same unit.
+     */
     constexpr ValueUnit
     operator-(value_type const& rhs) const
     {
         return ValueUnit{value_ - rhs};
     }
 
+    /** Subtract a `ValueUnit` from a raw scalar.
+     *
+     *  Computed as `lhs + (-rhs)` so that addition commutativity applies.
+     *
+     *  @param lhs Scalar left-hand side.
+     *  @param rhs `ValueUnit` to subtract.
+     *  @return A new `ValueUnit` of the same unit.
+     */
     friend constexpr ValueUnit
     operator-(value_type lhs, ValueUnit const& rhs)
     {
@@ -148,12 +276,23 @@ public:
         return -rhs + lhs;
     }
 
+    /** Scale this unit value by a raw scalar, preserving the unit.
+     *
+     *  @param rhs Scalar multiplier.
+     *  @return A new `ValueUnit` of the same unit.
+     */
     constexpr ValueUnit
     operator*(value_type const& rhs) const
     {
         return ValueUnit{value_ * rhs};
     }
 
+    /** Scale a `ValueUnit` by a raw scalar (commutative form).
+     *
+     *  @param lhs Scalar left-hand side.
+     *  @param rhs `ValueUnit` right-hand side.
+     *  @return A new `ValueUnit` of the same unit.
+     */
     friend constexpr ValueUnit
     operator*(value_type lhs, ValueUnit const& rhs)
     {
@@ -161,6 +300,13 @@ public:
         return rhs * lhs;
     }
 
+    /** Divide two same-unit values to produce a dimensionless raw ratio.
+     *
+     *  Same-unit / same-unit = unitless scalar (e.g. drops / drops = 1).
+     *
+     *  @param rhs The divisor.
+     *  @return The raw `value_type` quotient.
+     */
     constexpr value_type
     operator/(ValueUnit const& rhs) const
     {
@@ -209,6 +355,11 @@ public:
         return *this;
     }
 
+    /** Modulo-assign by a raw scalar.  Only available when value type is integral.
+     *
+     *  @tparam Transparent Deduced; constrains the overload to integral value types.
+     *  @param rhs The divisor for the modulo operation.
+     */
     template <Integral Transparent = value_type>
     ValueUnit&
     operator%=(value_type const& rhs)
@@ -217,6 +368,12 @@ public:
         return *this;
     }
 
+    /** Negate this value.
+     *
+     *  @note Fails to compile with a `static_assert` when `T` is unsigned,
+     *      preventing silent integer wrapping on types like `uint64_t`.
+     *  @return A new `ValueUnit` holding `-value_`.
+     */
     ValueUnit
     operator-() const
     {
@@ -256,14 +413,23 @@ public:
         return value_ < other.value_;
     }
 
-    /** Returns true if the amount is not zero */
+    /** Returns `true` when the stored value is non-zero.
+     *
+     *  Allows `if (amount)` idiom analogous to pointer truthiness.
+     */
     explicit constexpr
     operator bool() const noexcept
     {
         return value_ != 0;
     }
 
-    /** Return the sign of the amount */
+    /** Returns the sign of the stored value as -1, 0, or +1.
+     *
+     *  Used by the `beast::Zero` comparison infrastructure to generate all
+     *  six relational operators against `zero` without a temporary allocation.
+     *
+     *  @return -1 if negative, 0 if zero, +1 if positive.
+     */
     [[nodiscard]] constexpr int
     signum() const noexcept
     {
@@ -272,7 +438,15 @@ public:
         return value_ ? 1 : 0;
     }
 
-    /** Returns the number of drops */
+    /** Returns the raw underlying value.
+     *
+     *  Named `fee()` for historical reasons; intended to migrate to a
+     *  dedicated tagged-fee class.
+     *
+     *  @note Prefer `value()` in generic code.  This accessor exists for
+     *      call sites that treat a `ValueUnit` specifically as a fee amount.
+     *  @return The raw `value_type`.
+     */
     // TODO: Move this to a new class, maybe with the old "TaggedFee" name
     [[nodiscard]] constexpr value_type
     fee() const
@@ -280,6 +454,15 @@ public:
         return value_;
     }
 
+    /** Express this value as a decimal fraction of a reference value.
+     *
+     *  Used to produce load-factor metrics for the JSON RPC layer (e.g.
+     *  `openLedgerFeeLevel / referenceFeeLevel`).
+     *
+     *  @tparam Other The underlying type of the reference (must share this unit).
+     *  @param reference The denominator value; behaviour is undefined if zero.
+     *  @return `static_cast<double>(value_) / reference.value()`.
+     */
     template <class Other>
     [[nodiscard]] constexpr double
     decimalFromReference(ValueUnit<unit_type, Other> reference) const
@@ -287,10 +470,19 @@ public:
         return static_cast<double>(value_) / reference.value();
     }
 
-    // `Usable` is checked to ensure that only values with
-    // known valid type tags can be converted to JSON. At the time
-    // of implementation, that includes all known tags, but more may
-    // be added in the future.
+    /** Convert this value to a `Json::Value`, clamping to the JSON integer range.
+     *
+     *  For integral value types, the result is clamped to
+     *  `[numeric_limits<json::Int>::min(), numeric_limits<json::UInt>::max()]`
+     *  to avoid JSON serialization overflow (JSON integers are 32-bit on many
+     *  platforms).  For floating-point value types, the value is returned
+     *  as-is.
+     *
+     *  Only available for `Usable` unit tags (explicit whitelist), so that
+     *  internal intermediate types cannot be accidentally exposed via RPC.
+     *
+     *  @return A `Json::Value` holding the clamped integer or double.
+     */
     [[nodiscard]] json::Value
     jsonClipped() const
         requires Usable<ValueUnit>
@@ -315,16 +507,20 @@ public:
         }
     }
 
-    /** Returns the underlying value. Code SHOULD NOT call this
-        function unless the type has been abstracted away,
-        e.g. in a templated function.
-    */
+    /** Returns the underlying raw value.
+     *
+     *  @note Prefer named accessors at call sites where the unit is known.
+     *      This function is intended for generic (templated) code where the
+     *      unit type has been abstracted away.
+     *  @return The stored `value_type`.
+     */
     [[nodiscard]] constexpr value_type
     value() const
     {
         return value_;
     }
 
+    /** Read a raw value from a stream into this `ValueUnit`. */
     friend std::istream&
     operator>>(std::istream& s, ValueUnit& val)
     {
@@ -333,7 +529,11 @@ public:
     }
 };
 
-// Output Values as just their numeric value.
+/** Write the raw numeric value of a `ValueUnit` to an output stream.
+ *
+ *  The unit tag is not written; the output is identical to streaming the
+ *  underlying `value_type`.
+ */
 template <class Char, class Traits, class UnitTag, class T>
 std::basic_ostream<Char, Traits>&
 operator<<(std::basic_ostream<Char, Traits>& os, ValueUnit<UnitTag, T> const& q)
@@ -341,6 +541,13 @@ operator<<(std::basic_ostream<Char, Traits>& os, ValueUnit<UnitTag, T> const& q)
     return os << q.value();
 }
 
+/** Convert a `ValueUnit` to a `std::string` representation of its raw value.
+ *
+ *  Equivalent to `std::to_string(amount.value())`.
+ *
+ *  @param amount The value to convert.
+ *  @return A string representation of the underlying value.
+ */
 template <class UnitTag, class T>
 std::string
 to_string(ValueUnit<UnitTag, T> const& amount)
@@ -348,27 +555,80 @@ to_string(ValueUnit<UnitTag, T> const& amount)
     return std::to_string(amount.value());
 }
 
+/** Concept satisfied by a `ValueUnit` whose value type is convertible to
+ *  `uint64_t`.  Constrains `mulDiv` source arguments.
+ *
+ *  @tparam Source The `ValueUnit` type to check.
+ */
 template <class Source>
 concept muldivSource =
     Valid<Source> && std::is_convertible_v<typename Source::value_type, std::uint64_t>;
 
+/** Concept satisfied by a `ValueUnit` that can also receive the result of a
+ *  `mulDiv` computation.
+ *
+ *  In addition to satisfying `muldivSource`, the destination type must accept
+ *  a `uint64_t` (the intermediate quotient) and its value type must be at
+ *  least 64 bits wide.
+ *
+ *  @tparam Dest The candidate destination `ValueUnit` type.
+ */
 template <class Dest>
 concept muldivDest = muldivSource<Dest> &&  // Dest is also a source
     std::is_convertible_v<std::uint64_t, typename Dest::value_type> &&
     sizeof(typename Dest::value_type) >= sizeof(std::uint64_t);
 
+/** Concept satisfied when two `ValueUnit` types are both valid `mulDiv`
+ *  sources with the same unit tag.
+ *
+ *  Ensures the numerator (`value`) and denominator (`div`) of a `mulDiv`
+ *  call are dimensionally compatible.
+ *
+ *  @tparam Source2 The type of the divisor argument.
+ *  @tparam Source1 The type of the value argument.
+ */
 template <class Source2, class Source1>
 concept muldivSources = muldivSource<Source1> && muldivSource<Source2> &&
     std::is_same_v<typename Source1::unit_type, typename Source2::unit_type>;
 
+/** Concept satisfied when a `mulDiv` call is well-typed: both source
+ *  arguments share a unit tag and the destination satisfies `muldivDest`.
+ *
+ *  Source and `Dest` may share the same unit (same-unit scaling).
+ *
+ *  @tparam Dest    The result `ValueUnit` type.
+ *  @tparam Source1 The value argument type.
+ *  @tparam Source2 The divisor argument type.
+ */
 template <class Dest, class Source1, class Source2>
 concept muldivable = muldivSources<Source1, Source2> && muldivDest<Dest>;
-// Source and Dest can be the same by default
 
+/** Concept satisfied when a `mulDiv` overload may reorder arguments
+ *  (commuted form).
+ *
+ *  Extends `muldivable` with the additional constraint that `Dest`'s unit
+ *  tag differs from the source unit tags.  This prevents the commuted
+ *  overload from being ambiguous with the non-commuted one when all three
+ *  types share the same unit.
+ *
+ *  @tparam Dest    The result `ValueUnit` type.
+ *  @tparam Source1 One source argument type.
+ *  @tparam Source2 The other source argument type.
+ */
 template <class Dest, class Source1, class Source2>
 concept muldivCommutable = muldivable<Dest, Source1, Source2> &&
     !std::is_same_v<typename Source1::unit_type, typename Dest::unit_type>;
 
+/** Wrap a raw scalar in a `unitlessTag` `ValueUnit` for use with `mulDivU`.
+ *
+ *  Raw integers cannot be passed directly to `mulDivU`, which requires typed
+ *  arguments.  `scalar()` provides the necessary wrapping without introducing
+ *  a named unit.
+ *
+ *  @tparam T The scalar arithmetic type.
+ *  @param value The value to wrap.
+ *  @return `ValueUnit<unitlessTag, T>{value}`.
+ */
 template <class T>
 ValueUnit<unitlessTag, T>
 scalar(T value)
@@ -376,6 +636,27 @@ scalar(T value)
     return ValueUnit<unitlessTag, T>{value};
 }
 
+/** Core overflow-safe multiply-then-divide for typed `ValueUnit` arguments.
+ *
+ *  Computes `(value * mul) / div` using a `boost::multiprecision::uint128_t`
+ *  intermediate to prevent overflow on the product.  Two fast paths avoid the
+ *  128-bit multiply when `value == div` (returns `mul`) or `mul == div`
+ *  (returns `value` after a range check).
+ *
+ *  All inputs must be non-negative; negative inputs trigger `XRPL_ASSERT` in
+ *  addition to returning `std::nullopt`.
+ *
+ *  The public `mulDiv` overloads in the `xrpl` namespace forward to this
+ *  function after normalising raw scalars with `unit::scalar()`.
+ *
+ *  @tparam Source1 Value and divisor unit type (must share a unit tag).
+ *  @tparam Source2 Divisor unit type (same constraint as Source1).
+ *  @tparam Dest    Result unit type; must satisfy `muldivable<Source1, Source2>`.
+ *  @param value    The value to scale.
+ *  @param mul      The multiplier (in `Dest`'s unit).
+ *  @param div      The divisor (in `Source`'s unit).
+ *  @return The scaled result, or `std::nullopt` on overflow or negative input.
+ */
 template <class Source1, class Source2, unit::muldivable<Source1, Source2> Dest>
 std::optional<Dest>
 mulDivU(Source1 value, Dest mul, Source2 div)
@@ -422,22 +703,69 @@ mulDivU(Source1 value, Dest mul, Source2 div)
 
 }  // namespace unit
 
-// Fee Levels
+/** Fee level as a `ValueUnit` parameterised on the underlying arithmetic type.
+ *
+ *  Fee levels are dimensionless ratios used by the transaction queue to compare
+ *  relative transaction cost independent of processing effort.
+ *
+ *  @tparam T The underlying arithmetic type (`uint64_t`, `double`, etc.).
+ */
 template <class T>
 using FeeLevel = unit::ValueUnit<unit::feelevelTag, T>;
+
+/** Fee level backed by a 64-bit unsigned integer.  The primary fee-level type
+ *  used by `TxQ` and the load-fee tracker. */
 using FeeLevel64 = FeeLevel<std::uint64_t>;
+
+/** Fee level backed by a `double`.  Used where a fractional fee-level ratio
+ *  must be represented (e.g. load-factor RPC fields). */
 using FeeLevelDouble = FeeLevel<double>;
 
-// Basis points (Bips)
+/** Basis-point quantity parameterised on the underlying type.
+ *
+ *  One basis point = 1/100 of one percent.
+ *
+ *  @tparam T The underlying arithmetic type.
+ */
 template <class T>
 using Bips = unit::ValueUnit<unit::BipsTag, T>;
+
+/** Basis points as a 16-bit unsigned integer. */
 using Bips16 = Bips<std::uint16_t>;
+
+/** Basis points as a 32-bit unsigned integer. */
 using Bips32 = Bips<std::uint32_t>;
+
+/** Tenth-of-a-basis-point quantity parameterised on the underlying type.
+ *
+ *  One tenth-bip = 1/1000 of one percent.  Used for interest rates and
+ *  management fees in the lending protocol where basis-point granularity
+ *  is insufficient.
+ *
+ *  @tparam T The underlying arithmetic type.
+ */
 template <class T>
 using TenthBips = unit::ValueUnit<unit::TenthBipsTag, T>;
+
+/** Tenth-basis-points as a 16-bit unsigned integer. */
 using TenthBips16 = TenthBips<std::uint16_t>;
+
+/** Tenth-basis-points as a 32-bit unsigned integer. */
 using TenthBips32 = TenthBips<std::uint32_t>;
 
+/** Compute `(value * mul) / div` with overflow protection, preserving unit types.
+ *
+ *  Delegates to `unit::mulDivU`.  Both `value` and `div` must share a unit
+ *  tag; `mul` carries the destination unit.  All inputs must be non-negative.
+ *
+ *  @tparam Source1 Type of `value` and `div` (same unit tag required).
+ *  @tparam Source2 Type of `div` (same unit tag as Source1).
+ *  @tparam Dest    Type of `mul` and the return value.
+ *  @param value    The value to scale.
+ *  @param mul      The multiplier in `Dest`'s unit.
+ *  @param div      The divisor in `Source`'s unit.
+ *  @return The scaled result, or `std::nullopt` on overflow or negative input.
+ */
 template <class Source1, class Source2, unit::muldivable<Source1, Source2> Dest>
 std::optional<Dest>
 mulDiv(Source1 value, Dest mul, Source2 div)
@@ -445,6 +773,21 @@ mulDiv(Source1 value, Dest mul, Source2 div)
     return unit::mulDivU(value, mul, div);
 }
 
+/** Compute `(value * mul) / div` with the `value` and `mul` arguments swapped
+ *  (commuted form for cross-unit conversions).
+ *
+ *  This overload is selected when `Dest`'s unit tag differs from the source
+ *  unit tags, avoiding ambiguity with the non-commuted form.  It reorders
+ *  the arguments to `unit::mulDivU` rather than duplicating the implementation.
+ *
+ *  @tparam Source1 Type of `mul` (same unit tag as Source2).
+ *  @tparam Source2 Type of `div` (same unit tag as Source1).
+ *  @tparam Dest    Type of `value` and the return value (different unit from sources).
+ *  @param value    The value to scale (in `Dest`'s unit).
+ *  @param mul      The multiplier (in the source unit).
+ *  @param div      The divisor (in the source unit).
+ *  @return The scaled result, or `std::nullopt` on overflow or negative input.
+ */
 template <class Source1, class Source2, unit::muldivCommutable<Source1, Source2> Dest>
 std::optional<Dest>
 mulDiv(Dest value, Source1 mul, Source2 div)
@@ -453,6 +796,17 @@ mulDiv(Dest value, Source1 mul, Source2 div)
     return unit::mulDivU(mul, value, div);
 }
 
+/** Compute `(value * mul) / div` when both scalars are raw `uint64_t`.
+ *
+ *  Wraps `value` and `div` in `unit::scalar()` so the typed `mulDivU`
+ *  path handles them uniformly.
+ *
+ *  @tparam Dest  The typed destination unit.
+ *  @param value  Raw scalar numerator.
+ *  @param mul    Typed multiplier (carries the destination unit).
+ *  @param div    Raw scalar divisor.
+ *  @return The scaled result, or `std::nullopt` on overflow.
+ */
 template <unit::muldivDest Dest>
 std::optional<Dest>
 mulDiv(std::uint64_t value, Dest mul, std::uint64_t div)
@@ -462,6 +816,15 @@ mulDiv(std::uint64_t value, Dest mul, std::uint64_t div)
     return unit::mulDivU(unit::scalar(value), mul, unit::scalar(div));
 }
 
+/** Compute `(value * mul) / div` when both scalars are raw `uint64_t`
+ *  and `value` carries the destination unit (commuted form).
+ *
+ *  @tparam Dest  The typed destination unit.
+ *  @param value  Typed value (carries the destination unit).
+ *  @param mul    Raw scalar multiplier.
+ *  @param div    Raw scalar divisor.
+ *  @return The scaled result, or `std::nullopt` on overflow.
+ */
 template <unit::muldivDest Dest>
 std::optional<Dest>
 mulDiv(Dest value, std::uint64_t mul, std::uint64_t div)
@@ -470,6 +833,19 @@ mulDiv(Dest value, std::uint64_t mul, std::uint64_t div)
     return mulDiv(mul, value, div);
 }
 
+/** Compute `(value * mul) / div` returning a raw `uint64_t` when `mul` is
+ *  a raw scalar.
+ *
+ *  Wraps `mul` in `unit::scalar()` and unwraps the typed result, allowing
+ *  callers to stay in the untyped domain for the output.
+ *
+ *  @tparam Source1 Type of `value` (must satisfy `muldivSource`).
+ *  @tparam Source2 Type of `div`   (same unit tag as Source1).
+ *  @param value    Typed numerator value.
+ *  @param mul      Raw scalar multiplier.
+ *  @param div      Typed divisor (same unit as `value`).
+ *  @return The raw quotient, or `std::nullopt` on overflow or negative input.
+ */
 template <unit::muldivSource Source1, unit::muldivSources<Source1> Source2>
 std::optional<std::uint64_t>
 mulDiv(Source1 value, std::uint64_t mul, Source2 div)
@@ -484,6 +860,16 @@ mulDiv(Source1 value, std::uint64_t mul, Source2 div)
     return unitresult->value();
 }
 
+/** Compute `(value * mul) / div` returning a raw `uint64_t` when `value` is
+ *  a raw scalar (commuted form of the scalar-`mul` overload).
+ *
+ *  @tparam Source1 Type of `mul` (must satisfy `muldivSource`).
+ *  @tparam Source2 Type of `div` (same unit tag as Source1).
+ *  @param value    Raw scalar numerator.
+ *  @param mul      Typed multiplier.
+ *  @param div      Typed divisor (same unit as `mul`).
+ *  @return The raw quotient, or `std::nullopt` on overflow or negative input.
+ */
 template <unit::muldivSource Source1, unit::muldivSources<Source1> Source2>
 std::optional<std::uint64_t>
 mulDiv(std::uint64_t value, Source1 mul, Source2 div)
@@ -492,6 +878,17 @@ mulDiv(std::uint64_t value, Source1 mul, Source2 div)
     return mulDiv(mul, value, div);
 }
 
+/** Checked narrowing or widening cast between two `ValueUnit`s of the same unit.
+ *
+ *  Unwraps `s`, applies the scalar `safeCast` to the underlying value, and
+ *  rewraps the result in `Dest`.  Requires that both types share a unit tag
+ *  and have integral value types (`CastableValue` concept).
+ *
+ *  @tparam Dest The destination `ValueUnit` type.
+ *  @tparam Src  The source `ValueUnit` type (same unit tag, integral value).
+ *  @param s     The source value.
+ *  @return `Dest` holding the safely cast value.
+ */
 template <unit::IntegralValue Dest, unit::CastableValue<Dest> Src>
 constexpr Dest
 safeCast(Src s) noexcept
@@ -500,6 +897,15 @@ safeCast(Src s) noexcept
     return Dest{safeCast<typename Dest::value_type>(s.value())};
 }
 
+/** Checked cast from a raw integral scalar into a `ValueUnit`.
+ *
+ *  Applies the scalar `safeCast` to `s` and wraps the result in `Dest`.
+ *
+ *  @tparam Dest The destination `ValueUnit` type (must have integral value type).
+ *  @tparam Src  An integral scalar type.
+ *  @param s     The raw scalar to cast.
+ *  @return `Dest` holding the safely cast value.
+ */
 template <unit::IntegralValue Dest, unit::Integral Src>
 constexpr Dest
 safeCast(Src s) noexcept
@@ -508,6 +914,17 @@ safeCast(Src s) noexcept
     return Dest{safeCast<typename Dest::value_type>(s)};
 }
 
+/** Unchecked narrowing cast between two `ValueUnit`s of the same unit.
+ *
+ *  Equivalent to `safeCast` but asserts at compile time that the cast is not
+ *  trivially safe, preventing misuse as a drop-in replacement for `safeCast`.
+ *  Use only when the value is known by contract to fit in `Dest`.
+ *
+ *  @tparam Dest The destination `ValueUnit` type.
+ *  @tparam Src  The source `ValueUnit` type (same unit tag, integral value).
+ *  @param s     The source value.
+ *  @return `Dest` holding the unsafely cast value.
+ */
 template <unit::IntegralValue Dest, unit::CastableValue<Dest> Src>
 constexpr Dest
 unsafeCast(Src s) noexcept
@@ -516,6 +933,15 @@ unsafeCast(Src s) noexcept
     return Dest{unsafeCast<typename Dest::value_type>(s.value())};
 }
 
+/** Unchecked cast from a raw integral scalar into a `ValueUnit`.
+ *
+ *  Use only when the value is known by contract to fit in `Dest`'s value type.
+ *
+ *  @tparam Dest The destination `ValueUnit` type (must have integral value type).
+ *  @tparam Src  An integral scalar type.
+ *  @param s     The raw scalar to cast.
+ *  @return `Dest` holding the unsafely cast value.
+ */
 template <unit::IntegralValue Dest, unit::Integral Src>
 constexpr Dest
 unsafeCast(Src s) noexcept
diff --git a/include/xrpl/protocol/XChainAttestations.h b/include/xrpl/protocol/XChainAttestations.h
index d8a35a29e3..61b8df4bbb 100644
--- a/include/xrpl/protocol/XChainAttestations.h
+++ b/include/xrpl/protocol/XChainAttestations.h
@@ -1,3 +1,20 @@
+/** @file
+ *  Type system foundation for XRPL's cross-chain bridge attestation protocol.
+ *
+ *  Witness servers attest to cross-chain transfer events by constructing and
+ *  signing objects from the `Attestations` namespace, then submitting them to
+ *  the destination chain.  The destination chain stores a stripped, signature-
+ *  free form directly in ledger objects.  Two parallel hierarchies serve these
+ *  roles:
+ *
+ *  - `Attestations::AttestationClaim` / `AttestationCreateAccount` — full
+ *    witness-submitted proofs including raw signature bytes.
+ *  - `XChainClaimAttestation` / `XChainCreateAccountAttestation` — on-ledger
+ *    storage forms retaining only the signer key identity and event fields.
+ *
+ *  @see STXChainBridge
+ */
+
 #pragma once
 
 #include <xrpl/basics/Buffer.h>
@@ -22,25 +39,52 @@ namespace xrpl {
 
 namespace Attestations {
 
+/** Common fields shared by all witness-server attestation types.
+ *
+ *  Holds the signer identity, raw signature, source account, amount, reward
+ *  account, and transfer direction for a single cross-chain event attestation.
+ *  Subclasses add the event-specific identifier (`claimID` or `createCount`)
+ *  and supply the virtual `message()` implementation that determines the exact
+ *  bytes that were signed.
+ *
+ *  @note This type carries the raw `signature` bytes and is only used in the
+ *      witness-submission path.  On-ledger storage uses the signature-free
+ *      `XChainClaimAttestation` / `XChainCreateAccountAttestation` types.
+ */
 struct AttestationBase
 {
-    // Account associated with the public key
+    /** Account ID associated with the signer's public key. */
     AccountID attestationSignerAccount;
-    // Public key from the witness server attesting to the event
+
+    /** Public key used by the witness server to sign the attestation. */
     PublicKey publicKey;
-    // Signature from the witness server attesting to the event
+
+    /** Raw cryptographic signature over the canonical message bytes. */
     Buffer signature;
-    // Account on the sending chain that triggered the event (sent the
-    // transaction)
+
+    /** Account on the sending chain that originated the cross-chain transfer. */
     AccountID sendingAccount;
-    // Amount transferred on the sending chain
+
+    /** Amount transferred on the sending chain. */
     STAmount sendingAmount;
-    // Account on the destination chain that collects a share of the attestation
-    // reward
+
+    /** Destination-chain account that collects this witness's reward share. */
     AccountID rewardAccount;
-    // Amount was transferred on the locking chain
+
+    /** `true` if the transfer was initiated on the locking chain. */
     bool wasLockingChainSend;
 
+    /** Construct from individual field values supplied by the witness server.
+     *
+     *  @param attestationSignerAccount Account ID for the signer's public key.
+     *  @param publicKey Witness server's public key.
+     *  @param signature Pre-computed signature over the canonical message.
+     *  @param sendingAccount Source account on the sending chain.
+     *  @param sendingAmount Amount transferred on the sending chain.
+     *  @param rewardAccount Destination-chain account receiving the reward share.
+     *  @param wasLockingChainSend `true` if the transfer originated on the
+     *      locking chain.
+     */
     explicit AttestationBase(
         AccountID attestationSignerAccount,
         PublicKey const& publicKey,
@@ -57,34 +101,122 @@ struct AttestationBase
     AttestationBase&
     operator=(AttestationBase const&) = default;
 
-    // verify that the signature attests to the data.
+    /** Cryptographically verify the witness signature against the stored fields.
+     *
+     *  Re-derives the canonical message bytes via the virtual `message()` call,
+     *  then checks them against `publicKey` and `signature`.
+     *
+     *  @param bridge The bridge this attestation relates to; included in the
+     *      signed payload to scope the proof to a specific bridge instance.
+     *  @return `true` if the signature is valid.
+     */
     [[nodiscard]] bool
     verify(STXChainBridge const& bridge) const;
 
 protected:
+    /** Deserialize from a ledger `STObject`. */
     explicit AttestationBase(STObject const& o);
+
+    /** Deserialize from a JSON value.
+     *
+     *  @throws std::runtime_error if any required field is missing or has the
+     *      wrong type.
+     */
     explicit AttestationBase(json::Value const& v);
 
+    /** Compare all fields of two `AttestationBase` instances, including signer
+     *  identity and raw signature bytes.
+     *
+     *  Used by subclass `operator==` to test whether two attestations are
+     *  identical in every respect.  Compare with `sameEventHelper`, which
+     *  intentionally excludes signer fields.
+     *
+     *  @param lhs Left-hand attestation.
+     *  @param rhs Right-hand attestation.
+     *  @return `true` if every base field matches.
+     */
     [[nodiscard]] static bool
     equalHelper(AttestationBase const& lhs, AttestationBase const& rhs);
 
+    /** Check whether two attestations witness the same cross-chain event,
+     *  ignoring signer identity.
+     *
+     *  Two attestations from different witnesses for the same transfer share
+     *  identical `sendingAccount`, `sendingAmount`, and `wasLockingChainSend`
+     *  values.  Signer fields are excluded so that distinct witnesses
+     *  corroborating the same event can be counted toward quorum.
+     *
+     *  @param lhs Left-hand attestation.
+     *  @param rhs Right-hand attestation.
+     *  @return `true` if the event-identity fields match.
+     */
     [[nodiscard]] static bool
     sameEventHelper(AttestationBase const& lhs, AttestationBase const& rhs);
 
+    /** Populate `o` with the base attestation fields shared by both claim types.
+     *
+     *  Subclass `toSTObject()` implementations call this before setting their
+     *  own type-specific fields.
+     *
+     *  @param o The `STObject` to populate.
+     */
     void
     addHelper(STObject& o) const;
 
 private:
+    /** Produce the canonical byte sequence that the witness signed.
+     *
+     *  Pure virtual: each subclass encodes a different set of fields to prevent
+     *  the base class from silently producing an incomplete message.  The static
+     *  overloads on each subclass expose the same logic for callers that want to
+     *  verify a signature without constructing a full attestation object.
+     *
+     *  @param bridge Bridge context bound into the signed payload.
+     *  @return Serialized bytes suitable for passing to `xrpl::verify()`.
+     */
     [[nodiscard]] virtual std::vector<std::uint8_t>
     message(STXChainBridge const& bridge) const = 0;
 };
 
-// Attest to a regular cross-chain transfer
+/** Full witness-server attestation for a regular cross-chain transfer.
+ *
+ *  Extends `AttestationBase` with the claim-specific `claimID` (a monotonic
+ *  counter on the bridge that prevents replay) and an optional destination
+ *  account override on the receiving chain.
+ *
+ *  Two constructors support the two call sites: one accepts a pre-computed
+ *  `Buffer signature` (used on the destination chain when verifying incoming
+ *  attestations), and one accepts a `SecretKey` and signs inline (used by
+ *  witness servers and test harnesses generating attestations from scratch).
+ */
 struct AttestationClaim : AttestationBase
 {
+    /** Monotonic bridge counter that scopes this claim to a specific transfer,
+     *  preventing replay across different events on the same bridge. */
     std::uint64_t claimID;
+
+    /** Optional destination account on the receiving chain.  Witnesses may
+     *  attest to the same transfer with different `dst` opinions; the
+     *  three-state `AttestationMatch` distinguishes these cases during quorum
+     *  collection. */
     std::optional<AccountID> dst;
 
+    /** Construct from individual field values with a pre-computed signature.
+     *
+     *  Used on the destination chain when receiving and verifying attestations
+     *  submitted by witness servers.
+     *
+     *  @param attestationSignerAccount Account ID for the signer's public key.
+     *  @param publicKey Witness server's public key.
+     *  @param signature Pre-computed signature over the canonical message.
+     *  @param sendingAccount Source account on the sending chain.
+     *  @param sendingAmount Amount transferred on the sending chain.
+     *  @param rewardAccount Destination-chain account receiving the reward share.
+     *  @param wasLockingChainSend `true` if the transfer originated on the
+     *      locking chain.
+     *  @param claimId Bridge claim counter for this transfer.
+     *  @param dst Optional destination account override on the receiving chain.
+     */
     explicit AttestationClaim(
         AccountID attestationSignerAccount,
         PublicKey const& publicKey,
@@ -96,6 +228,26 @@ struct AttestationClaim : AttestationBase
         std::uint64_t claimId,
         std::optional<AccountID> const& dst);
 
+    /** Construct and immediately sign using `secretKey`.
+     *
+     *  Derives the canonical message bytes from all supplied fields and
+     *  `bridge`, then signs them.  Intended for witness servers and test
+     *  harnesses that generate attestations from scratch.
+     *
+     *  @param bridge Bridge context included in the signed payload; binds the
+     *      attestation to a specific bridge instance.
+     *  @param attestationSignerAccount Account ID for the signer's public key.
+     *  @param publicKey Witness server's public key.
+     *  @param secretKey Signing key; the resulting signature is stored in
+     *      `AttestationBase::signature`.
+     *  @param sendingAccount Source account on the sending chain.
+     *  @param sendingAmount Amount transferred on the sending chain.
+     *  @param rewardAccount Destination-chain account receiving the reward share.
+     *  @param wasLockingChainSend `true` if the transfer originated on the
+     *      locking chain.
+     *  @param claimId Bridge claim counter for this transfer.
+     *  @param dst Optional destination account override on the receiving chain.
+     */
     explicit AttestationClaim(
         STXChainBridge const& bridge,
         AccountID attestationSignerAccount,
@@ -108,16 +260,57 @@ struct AttestationClaim : AttestationBase
         std::uint64_t claimId,
         std::optional<AccountID> const& dst);
 
+    /** Deserialize from a ledger `STObject`. */
     explicit AttestationClaim(STObject const& o);
+
+    /** Deserialize from a JSON value.
+     *
+     *  @throws std::runtime_error if any required field is missing or has the
+     *      wrong type.
+     */
     explicit AttestationClaim(json::Value const& v);
 
+    /** Serialize this attestation to an `STObject` for inclusion in a
+     *  transaction or `STArray`.
+     *
+     *  @return An inner object tagged
+     *      `sfXChainClaimAttestationCollectionElement` containing all claim
+     *      attestation fields.
+     */
     [[nodiscard]] STObject
     toSTObject() const;
 
-    // return true if the two attestations attest to the same thing
+    /** Check whether `rhs` witnesses the same cross-chain claim event,
+     *  ignoring signer identity fields.
+     *
+     *  Both the base event fields and the claim-specific `claimID` and `dst`
+     *  must agree.  Two attestations satisfying this condition came from
+     *  different witnesses for the same transfer and each count toward quorum.
+     *
+     *  @param rhs The attestation to compare against.
+     *  @return `true` if both attestations describe the same claim event.
+     */
     [[nodiscard]] bool
     sameEvent(AttestationClaim const& rhs) const;
 
+    /** Produce the canonical bytes that a witness signs for a claim attestation.
+     *
+     *  Fields are serialized in `SField` sort order so that independent
+     *  implementations (e.g., Python witness servers) produce byte-for-byte
+     *  identical output.  The `bridge` is embedded in the payload, scoping
+     *  the proof to a specific bridge instance so it cannot be replayed on
+     *  another.
+     *
+     *  @param bridge Bridge context scoping the proof.
+     *  @param sendingAccount Source account on the sending chain.
+     *  @param sendingAmount Amount transferred on the sending chain.
+     *  @param rewardAccount Destination-chain account receiving the reward share.
+     *  @param wasLockingChainSend `true` if the transfer originated on the
+     *      locking chain.
+     *  @param claimID Monotonic counter from the bridge that prevents replay.
+     *  @param dst Optional destination override on the issuing chain.
+     *  @return Serialized bytes suitable for signing or verification.
+     */
     [[nodiscard]] static std::vector<std::uint8_t>
     message(
         STXChainBridge const& bridge,
@@ -128,6 +321,10 @@ struct AttestationClaim : AttestationBase
         std::uint64_t claimID,
         std::optional<AccountID> const& dst);
 
+    /** Check that `sendingAmount` is a legal network amount.
+     *
+     *  @return `true` if the amount is valid for wire transmission.
+     */
     [[nodiscard]] bool
     validAmounts() const;
 
@@ -139,6 +336,11 @@ private:
     operator==(AttestationClaim const& lhs, AttestationClaim const& rhs);
 };
 
+/** Comparator that orders `AttestationClaim` objects by their `claimID`.
+ *
+ *  Used to sort or binary-search a collection of claim attestations by the
+ *  bridge's monotonic sequence counter.
+ */
 struct CmpByClaimID
 {
     bool
@@ -148,22 +350,58 @@ struct CmpByClaimID
     }
 };
 
-// Attest to a cross-chain transfer that creates an account
+/** Full witness-server attestation for a cross-chain account-creation transfer.
+ *
+ *  Extends `AttestationBase` with the account-creation–specific `createCount`
+ *  (the value of `XChainAccountCreateCount` on the sending-chain bridge at
+ *  event time), the destination account to create, and the total size of the
+ *  witness reward pool.  Unlike `AttestationClaim`, the destination is not
+ *  optional — account-creation attestations always specify the account to
+ *  create on the receiving chain.
+ *
+ *  As with `AttestationClaim`, two constructors support pre-computed signatures
+ *  (verification path) and inline signing (witness server / test harness path).
+ */
 struct AttestationCreateAccount : AttestationBase
 {
-    // createCount on the sending chain. This is the value of the `CreateCount`
-    // field of the bridge on the sending chain when the transaction was
-    // executed.
+    /** Value of `XChainAccountCreateCount` on the sending-chain bridge when
+     *  the account-creation transaction was executed.  Scopes this attestation
+     *  to a specific event and prevents replay. */
     std::uint64_t createCount;
-    // Account to create on the destination chain
+
+    /** Account to create on the destination chain. */
     AccountID toCreate;
-    // Total amount of the reward pool
+
+    /** Total amount of the witness reward pool for this event. */
     STAmount rewardAmount;
 
+    /** Deserialize from a ledger `STObject`. */
     explicit AttestationCreateAccount(STObject const& o);
 
+    /** Deserialize from a JSON value.
+     *
+     *  @throws std::runtime_error if any required field is missing or has the
+     *      wrong type.
+     */
     explicit AttestationCreateAccount(json::Value const& v);
 
+    /** Construct from individual field values with a pre-computed signature.
+     *
+     *  Used on the destination chain when receiving and verifying attestations
+     *  submitted by witness servers.
+     *
+     *  @param attestationSignerAccount Account ID for the signer's public key.
+     *  @param publicKey Witness server's public key.
+     *  @param signature Pre-computed signature over the canonical message.
+     *  @param sendingAccount Source account on the sending chain.
+     *  @param sendingAmount Amount transferred on the sending chain.
+     *  @param rewardAmount Total witness reward pool for this event.
+     *  @param rewardAccount Destination-chain account receiving the reward share.
+     *  @param wasLockingChainSend `true` if the transfer originated on the
+     *      locking chain.
+     *  @param createCount Bridge account-creation counter for this event.
+     *  @param toCreate Account to create on the destination chain.
+     */
     explicit AttestationCreateAccount(
         AccountID attestationSignerAccount,
         PublicKey const& publicKey,
@@ -176,6 +414,27 @@ struct AttestationCreateAccount : AttestationBase
         std::uint64_t createCount,
         AccountID const& toCreate);
 
+    /** Construct and immediately sign using `secretKey`.
+     *
+     *  Derives the canonical message bytes from all supplied fields and
+     *  `bridge`, then signs them.  Intended for witness servers and test
+     *  harnesses that generate account-creation attestations from scratch.
+     *
+     *  @param bridge Bridge context included in the signed payload; binds the
+     *      attestation to a specific bridge instance.
+     *  @param attestationSignerAccount Account ID for the signer's public key.
+     *  @param publicKey Witness server's public key.
+     *  @param secretKey Signing key; the resulting signature is stored in
+     *      `AttestationBase::signature`.
+     *  @param sendingAccount Source account on the sending chain.
+     *  @param sendingAmount Amount transferred on the sending chain.
+     *  @param rewardAmount Total witness reward pool for this event.
+     *  @param rewardAccount Destination-chain account receiving the reward share.
+     *  @param wasLockingChainSend `true` if the transfer originated on the
+     *      locking chain.
+     *  @param createCount Bridge account-creation counter for this event.
+     *  @param toCreate Account to create on the destination chain.
+     */
     explicit AttestationCreateAccount(
         STXChainBridge const& bridge,
         AccountID attestationSignerAccount,
@@ -189,16 +448,54 @@ struct AttestationCreateAccount : AttestationBase
         std::uint64_t createCount,
         AccountID const& toCreate);
 
+    /** Serialize this attestation to an `STObject` for inclusion in a
+     *  transaction or `STArray`.
+     *
+     *  @return An inner object tagged
+     *      `sfXChainCreateAccountAttestationCollectionElement` containing all
+     *      account-creation attestation fields.
+     */
     [[nodiscard]] STObject
     toSTObject() const;
 
-    // return true if the two attestations attest to the same thing
+    /** Check whether `rhs` witnesses the same cross-chain account-creation
+     *  event, ignoring signer identity fields.
+     *
+     *  The base event fields plus `createCount`, `toCreate`, and `rewardAmount`
+     *  must all agree.  Two attestations satisfying this condition came from
+     *  different witnesses for the same transfer and each count toward quorum.
+     *
+     *  @param rhs The attestation to compare against.
+     *  @return `true` if both attestations describe the same account-creation
+     *      event.
+     */
     [[nodiscard]] bool
     sameEvent(AttestationCreateAccount const& rhs) const;
 
     friend bool
     operator==(AttestationCreateAccount const& lhs, AttestationCreateAccount const& rhs);
 
+    /** Produce the canonical bytes that a witness signs for an account-creation
+     *  attestation.
+     *
+     *  Fields are serialized in `SField` sort order so that independent
+     *  implementations (e.g., Python witness servers) produce byte-for-byte
+     *  identical output.  The `bridge` is embedded in the payload, scoping
+     *  the proof to a specific bridge instance.
+     *
+     *  @param bridge Bridge context scoping the proof.
+     *  @param sendingAccount Source account on the sending chain.
+     *  @param sendingAmount Amount transferred on the sending chain.
+     *  @param rewardAmount Total size of the witness reward pool for this event.
+     *  @param rewardAccount Destination-chain account receiving this witness's
+     *      reward share.
+     *  @param wasLockingChainSend `true` if the transfer originated on the
+     *      locking chain.
+     *  @param createCount Value of `XChainAccountCreateCount` on the sending-
+     *      chain bridge at the time of the event; prevents replay.
+     *  @param dst Account to create on the destination chain.
+     *  @return Serialized bytes suitable for signing or verification.
+     */
     [[nodiscard]] static std::vector<std::uint8_t>
     message(
         STXChainBridge const& bridge,
@@ -210,6 +507,11 @@ struct AttestationCreateAccount : AttestationBase
         std::uint64_t createCount,
         AccountID const& dst);
 
+    /** Check that both `sendingAmount` and `rewardAmount` are legal network
+     *  amounts.
+     *
+     *  @return `true` if both amounts are valid for wire transmission.
+     */
     [[nodiscard]] bool
     validAmounts() const;
 
@@ -218,6 +520,11 @@ private:
     message(STXChainBridge const& bridge) const override;
 };
 
+/** Comparator that orders `AttestationCreateAccount` objects by `createCount`.
+ *
+ *  Used to sort or binary-search a collection of account-creation attestations
+ *  by the bridge's monotonic account-creation sequence counter.
+ */
 struct CmpByCreateCount
 {
     bool
@@ -229,40 +536,113 @@ struct CmpByCreateCount
 
 };  // namespace Attestations
 
-// Result when checking when two attestation match.
+/** Three-state result of comparing a stored ledger attestation against incoming
+ *  fields.
+ *
+ *  The extra granularity beyond a simple boolean is required because
+ *  `XChainClaim` transactions allow the user to specify their own destination
+ *  account, so the system must distinguish "everything matches" from "same
+ *  transfer, different destination":
+ *
+ *  - `XChainAddClaimAttestation` requires `Match` — witnesses must agree on
+ *    the destination.
+ *  - `XChainClaim` (user-specified destination) also accepts `MatchExceptDst`.
+ */
 enum class AttestationMatch {
-    // One of the fields doesn't match, and it isn't the dst field
+    /** At least one non-destination field differs; the attestations describe
+     *  different events or amounts. */
     NonDstMismatch,
-    // all of the fields match, except the dst field
+    /** All fields agree except the optional destination account. */
     MatchExceptDst,
-    // all of the fields match
+    /** All fields, including the destination, agree completely. */
     Match
 };
 
+/** Ledger-stored form of a regular cross-chain transfer attestation.
+ *
+ *  This is the signature-free projection of `Attestations::AttestationClaim`
+ *  that lives inside `XChainOwnedClaimID` ledger entries.  The raw `Buffer
+ *  signature` and full `sendingAccount` are not persisted; only the signer's
+ *  `keyAccount` and `publicKey`, the event amount, reward account, transfer
+ *  direction, and optional destination are retained.
+ *
+ *  The `TSignedAttestation` typedef links this type back to its full
+ *  counterpart.  The converting constructor from `TSignedAttestation` is the
+ *  canonical way to project a submitted attestation into its on-ledger form.
+ *
+ *  @see AttestationMatch
+ */
 struct XChainClaimAttestation
 {
+    /** Full witness-submitted attestation type that this ledger form is derived
+     *  from. */
     using TSignedAttestation = Attestations::AttestationClaim;
+
+    /** `SField` naming the `STArray` that holds these entries in ledger
+     *  objects (`sfXChainClaimAttestations`). */
     static SField const& arrayFieldName;
 
+    /** Account ID corresponding to the signer's public key. */
     AccountID keyAccount;
+
+    /** Witness server's public key. */
     PublicKey publicKey;
+
+    /** Amount transferred on the sending chain. */
     STAmount amount;
+
+    /** Destination-chain account that collects this witness's reward share. */
     AccountID rewardAccount;
+
+    /** `true` if the transfer was initiated on the locking chain. */
     bool wasLockingChainSend;
+
+    /** Optional destination account on the receiving chain. */
     std::optional<AccountID> dst;
 
+    /** Fields used to compare a stored attestation against an incoming one
+     *  during quorum matching.
+     *
+     *  Constructed from either a full `TSignedAttestation` or explicit values;
+     *  holds only the event-describing fields that `match()` inspects.
+     */
     struct MatchFields
     {
+        /** Amount transferred on the sending chain. */
         STAmount amount;
+        /** `true` if the transfer was initiated on the locking chain. */
         bool wasLockingChainSend;
+        /** Optional destination account on the receiving chain. */
         std::optional<AccountID> dst;
+
+        /** Project from a full signing-side attestation.
+         *
+         *  @param att Full witness-submitted attestation to extract from.
+         */
         MatchFields(TSignedAttestation const& att);
+
+        /** Construct from explicit values.
+         *
+         *  @param a Amount transferred on the sending chain.
+         *  @param b `true` if the transfer originated on the locking chain.
+         *  @param d Optional destination account.
+         */
         MatchFields(STAmount a, bool b, std::optional<AccountID> const& d)
             : amount{std::move(a)}, wasLockingChainSend{b}, dst{d}
         {
         }
     };
 
+    /** Construct from explicit field values.
+     *
+     *  @param keyAccount Account ID corresponding to the signer's public key.
+     *  @param publicKey Witness server's public key.
+     *  @param amount Amount transferred on the sending chain.
+     *  @param rewardAccount Destination-chain account receiving the reward share.
+     *  @param wasLockingChainSend `true` if the transfer originated on the
+     *      locking chain.
+     *  @param dst Optional destination account on the receiving chain.
+     */
     explicit XChainClaimAttestation(
         AccountID const& keyAccount,
         PublicKey const& publicKey,
@@ -271,6 +651,20 @@ struct XChainClaimAttestation
         bool wasLockingChainSend,
         std::optional<AccountID> const& dst);
 
+    /** Construct from `STAccount`-wrapped field values, unwrapping the
+     *  `AccountID` values.
+     *
+     *  Convenience overload used when deserializing from an `STObject` whose
+     *  account fields are already typed as `STAccount`.
+     *
+     *  @param keyAccount Wrapped account ID for the signer's public key.
+     *  @param publicKey Witness server's public key.
+     *  @param amount Amount transferred on the sending chain.
+     *  @param rewardAccount Wrapped destination-chain reward account.
+     *  @param wasLockingChainSend `true` if the transfer originated on the
+     *      locking chain.
+     *  @param dst Optional wrapped destination account.
+     */
     explicit XChainClaimAttestation(
         STAccount const& keyAccount,
         PublicKey const& publicKey,
@@ -279,15 +673,40 @@ struct XChainClaimAttestation
         bool wasLockingChainSend,
         std::optional<STAccount> const& dst);
 
+    /** Project a full `AttestationClaim` into its ledger-storage form,
+     *  dropping the raw signature.
+     *
+     *  @param claimAtt The full witness-submitted attestation to convert.
+     */
     explicit XChainClaimAttestation(TSignedAttestation const& claimAtt);
 
+    /** Deserialize from a ledger `STObject`. */
     explicit XChainClaimAttestation(STObject const& o);
 
+    /** Deserialize from a JSON value.
+     *
+     *  @throws std::runtime_error if any required field is missing or has the
+     *      wrong type.
+     */
     explicit XChainClaimAttestation(json::Value const& v);
 
+    /** Determine how closely this stored attestation matches the supplied fields.
+     *
+     *  Returns `Match` when all fields agree, `MatchExceptDst` when only the
+     *  destination differs, and `NonDstMismatch` when a core event field
+     *  (amount or direction) does not agree.
+     *
+     *  @param rhs The fields from the incoming attestation or claim request.
+     *  @return `Match`, `MatchExceptDst`, or `NonDstMismatch`.
+     */
     [[nodiscard]] AttestationMatch
     match(MatchFields const& rhs) const;
 
+    /** Serialize this ledger-stored attestation to an `STObject`.
+     *
+     *  @return An inner object tagged `sfXChainClaimProofSig` containing the
+     *      ledger-side claim attestation fields (no raw signature).
+     */
     [[nodiscard]] STObject
     toSTObject() const;
 
@@ -295,29 +714,87 @@ struct XChainClaimAttestation
     operator==(XChainClaimAttestation const& lhs, XChainClaimAttestation const& rhs);
 };
 
+/** Ledger-stored form of a cross-chain account-creation attestation.
+ *
+ *  This is the signature-free projection of
+ *  `Attestations::AttestationCreateAccount` that lives inside
+ *  `XChainOwnedCreateAccountClaimID` ledger entries.  Unlike the claim
+ *  variant, the destination account (`dst`) is mandatory — account-creation
+ *  attestations always specify the account to create on the receiving chain.
+ *
+ *  The `TSignedAttestation` typedef links this type back to its full
+ *  counterpart.  The converting constructor from `TSignedAttestation` is the
+ *  canonical way to project a submitted attestation into its on-ledger form.
+ *
+ *  @see AttestationMatch
+ */
 struct XChainCreateAccountAttestation
 {
+    /** Full witness-submitted attestation type that this ledger form is derived
+     *  from. */
     using TSignedAttestation = Attestations::AttestationCreateAccount;
+
+    /** `SField` naming the `STArray` that holds these entries in ledger
+     *  objects (`sfXChainCreateAccountAttestations`). */
     static SField const& arrayFieldName;
 
+    /** Account ID corresponding to the signer's public key. */
     AccountID keyAccount;
+
+    /** Witness server's public key. */
     PublicKey publicKey;
+
+    /** Amount transferred on the sending chain. */
     STAmount amount;
+
+    /** Total witness reward pool for this account-creation event. */
     STAmount rewardAmount;
+
+    /** Destination-chain account that collects this witness's reward share. */
     AccountID rewardAccount;
+
+    /** `true` if the transfer was initiated on the locking chain. */
     bool wasLockingChainSend;
+
+    /** Account to create on the destination chain. */
     AccountID dst;
 
+    /** Fields used to compare a stored attestation against an incoming one
+     *  during quorum matching.
+     *
+     *  For account-creation attestations, `amount`, `rewardAmount`, and
+     *  `wasLockingChainSend` are all checked before the destination is
+     *  compared.
+     */
     struct MatchFields
     {
+        /** Amount transferred on the sending chain. */
         STAmount amount;
+        /** Total witness reward pool for this event. */
         STAmount rewardAmount;
+        /** `true` if the transfer was initiated on the locking chain. */
         bool wasLockingChainSend;
+        /** Account to create on the destination chain. */
         AccountID dst;
 
+        /** Project from a full signing-side attestation.
+         *
+         *  @param att Full witness-submitted attestation to extract from.
+         */
         MatchFields(TSignedAttestation const& att);
     };
 
+    /** Construct from explicit field values.
+     *
+     *  @param keyAccount Account ID corresponding to the signer's public key.
+     *  @param publicKey Witness server's public key.
+     *  @param amount Amount transferred on the sending chain.
+     *  @param rewardAmount Total witness reward pool for this event.
+     *  @param rewardAccount Destination-chain account receiving the reward share.
+     *  @param wasLockingChainSend `true` if the transfer originated on the
+     *      locking chain.
+     *  @param dst Account to create on the destination chain.
+     */
     explicit XChainCreateAccountAttestation(
         AccountID const& keyAccount,
         PublicKey const& publicKey,
@@ -327,15 +804,41 @@ struct XChainCreateAccountAttestation
         bool wasLockingChainSend,
         AccountID const& dst);
 
+    /** Project a full `AttestationCreateAccount` into its ledger-storage form,
+     *  dropping the raw signature.
+     *
+     *  @param claimAtt The full witness-submitted attestation to convert.
+     */
     explicit XChainCreateAccountAttestation(TSignedAttestation const& claimAtt);
 
+    /** Deserialize from a ledger `STObject`. */
     explicit XChainCreateAccountAttestation(STObject const& o);
 
+    /** Deserialize from a JSON value.
+     *
+     *  @throws std::runtime_error if any required field is missing or has the
+     *      wrong type.
+     */
     explicit XChainCreateAccountAttestation(json::Value const& v);
 
+    /** Serialize this ledger-stored attestation to an `STObject`.
+     *
+     *  @return An inner object tagged `sfXChainCreateAccountProofSig`
+     *      containing the ledger-side account-creation attestation fields
+     *      (no raw signature).
+     */
     [[nodiscard]] STObject
     toSTObject() const;
 
+    /** Determine how closely this stored attestation matches the supplied fields.
+     *
+     *  Returns `Match` when all fields agree, `MatchExceptDst` when only the
+     *  destination account differs, and `NonDstMismatch` when a core event
+     *  field (amount, reward amount, or direction) does not agree.
+     *
+     *  @param rhs The fields from the incoming attestation or claim request.
+     *  @return `Match`, `MatchExceptDst`, or `NonDstMismatch`.
+     */
     [[nodiscard]] AttestationMatch
     match(MatchFields const& rhs) const;
 
@@ -345,23 +848,39 @@ struct XChainCreateAccountAttestation
         XChainCreateAccountAttestation const& rhs);
 };
 
-// Attestations from witness servers for a particular claim ID and bridge.
-// Only one attestation per signature is allowed.
+/** Container for a collection of witness-server attestations for a single
+ *  bridge event.
+ *
+ *  Wraps a `std::vector<TAttestation>` and adds serialization to/from
+ *  `STArray` and `Json::Value`.  At most `kMAX_ATTESTATIONS` (256) entries
+ *  are accepted at either parse path; this cap prevents memory exhaustion from
+ *  crafted oversized arrays while remaining far above any realistic quorum
+ *  size.
+ *
+ *  The destructor is `protected` to prevent slicing: the two concrete
+ *  subclasses (`XChainClaimAttestations` and `XChainCreateAccountAttestations`)
+ *  add no virtual methods, so accidental deletion through a base pointer would
+ *  silently be incorrect.
+ *
+ *  @tparam TAttestation Either `XChainClaimAttestation` or
+ *      `XChainCreateAccountAttestation`.
+ */
 template <class TAttestation>
 class XChainAttestationsBase
 {
 public:
+    /** Underlying storage type for the attestation collection. */
     using AttCollection = std::vector<TAttestation>;
 
 private:
-    // Set a max number of allowed attestations to limit the amount of memory
-    // allocated and processing time. This number is much larger than the actual
-    // number of attestation a server would ever expect.
+    /** Maximum number of attestations accepted from either `STArray` or JSON
+     *  input.  Far above practical quorum sizes; guards against memory
+     *  exhaustion from maliciously crafted messages. */
     static constexpr std::uint32_t kMAX_ATTESTATIONS = 256;
     AttCollection attestations_;
 
 protected:
-    // Prevent slicing to the base class
+    /** Protected destructor prevents slicing through a base-class pointer. */
     ~XChainAttestationsBase() = default;
 
 public:
@@ -370,45 +889,88 @@ public:
     XChainAttestationsBase&
     operator=(XChainAttestationsBase const& rhs) = default;
 
+    /** Construct from a pre-built attestation vector, taking ownership.
+     *
+     *  @param sigs Attestation collection to move into this container.
+     */
     explicit XChainAttestationsBase(AttCollection&& sigs);
 
+    /** Deserialize from a JSON value containing an `"attestations"` array.
+     *
+     *  @throws std::runtime_error if `v` is not a JSON object, if the array
+     *      exceeds `kMAX_ATTESTATIONS`, or if any element fails to
+     *      deserialize.
+     */
     explicit XChainAttestationsBase(json::Value const& v);
 
+    /** Deserialize from an `STArray` read out of a ledger object.
+     *
+     *  @throws std::runtime_error if `arr` contains more than
+     *      `kMAX_ATTESTATIONS` elements.
+     */
     explicit XChainAttestationsBase(STArray const& arr);
 
+    /** Serialize the collection to an `STArray` for storage in a ledger object.
+     *
+     *  @return An `STArray` tagged with `TAttestation::arrayFieldName` whose
+     *      elements are the `STObject` representations of each attestation.
+     */
     [[nodiscard]] STArray
     toSTArray() const;
 
+    /** @return Const iterator to the first attestation. */
     [[nodiscard]] typename AttCollection::const_iterator
     begin() const;
 
+    /** @return Const iterator past the last attestation. */
     [[nodiscard]] typename AttCollection::const_iterator
     end() const;
 
+    /** @return Mutable iterator to the first attestation. */
     typename AttCollection::iterator
     begin();
 
+    /** @return Mutable iterator past the last attestation. */
     typename AttCollection::iterator
     end();
 
+    /** Remove all attestations satisfying predicate `f`.
+     *
+     *  @tparam F Unary predicate type; called with `TAttestation const&`.
+     *  @param f Predicate; returns `true` for attestations to remove.
+     *  @return Number of attestations removed.
+     */
     template <class F>
     std::size_t
     eraseIf(F&& f);
 
+    /** @return Number of attestations in the collection. */
     [[nodiscard]] std::size_t
     size() const;
 
+    /** @return `true` if the collection contains no attestations. */
     [[nodiscard]] bool
     empty() const;
 
+    /** @return Read-only reference to the underlying attestation vector. */
     [[nodiscard]] AttCollection const&
     attestations() const;
 
+    /** Append an attestation to the collection.
+     *
+     *  @tparam T Must be convertible to `TAttestation`.
+     *  @param att Attestation to append (forwarded).
+     */
     template <class T>
     void
     emplaceBack(T&& att);
 };
 
+/** Compare two attestation collections for equality.
+ *
+ *  @return `true` if both containers hold identical attestations in the same
+ *      order.
+ */
 template <class TAttestation>
 [[nodiscard]] inline bool
 operator==(
@@ -455,12 +1017,25 @@ XChainAttestationsBase<TAttestation>::empty() const
     return attestations_.empty();
 }
 
+/** Typed container for ledger-stored claim attestations.
+ *
+ *  Thin named wrapper around `XChainAttestationsBase<XChainClaimAttestation>`
+ *  that provides a distinct type for the type system without adding behavior.
+ *  All constructors are inherited from the base.
+ */
 class XChainClaimAttestations final : public XChainAttestationsBase<XChainClaimAttestation>
 {
     using TBase = XChainAttestationsBase<XChainClaimAttestation>;
     using TBase::TBase;
 };
 
+/** Typed container for ledger-stored account-creation attestations.
+ *
+ *  Thin named wrapper around
+ *  `XChainAttestationsBase<XChainCreateAccountAttestation>` that provides a
+ *  distinct type for the type system without adding behavior.  All constructors
+ *  are inherited from the base.
+ */
 class XChainCreateAccountAttestations final
     : public XChainAttestationsBase<XChainCreateAccountAttestation>
 {
diff --git a/include/xrpl/protocol/XRPAmount.h b/include/xrpl/protocol/XRPAmount.h
index 067ea511da..38f37c86df 100644
--- a/include/xrpl/protocol/XRPAmount.h
+++ b/include/xrpl/protocol/XRPAmount.h
@@ -1,3 +1,11 @@
+/** @file
+ *  Defines XRPAmount, the canonical type-safe representation of XRP in drops.
+ *
+ *  One XRP equals exactly 1,000,000 drops. All XRP quantities in the ledger
+ *  are stored and computed as integer drop counts to avoid floating-point
+ *  imprecision. The companion constant `kDROPS_PER_XRP` and the
+ *  `mulRatio()` helper are defined here as well.
+ */
 #pragma once
 
 #include <xrpl/basics/Number.h>
@@ -16,13 +24,35 @@
 
 namespace xrpl {
 
+/** Type-safe representation of an XRP quantity in drops.
+ *
+ *  All XRP values are stored as integer drop counts (1 XRP = 1,000,000 drops).
+ *  The class derives comparison, addition, and subtraction operators from
+ *  `boost::operators` mixins; only `operator==`, `operator<`, `operator+=`,
+ *  and `operator-=` are implemented directly, and the rest are generated.
+ *  Mixed arithmetic with raw `std::int64_t` literals is supported for fee
+ *  and reserve computations.
+ *
+ *  Negative drop values are representable and used in internal calculations;
+ *  callers are responsible for ensuring ledger amounts are non-negative where
+ *  required.
+ *
+ *  @note Satisfies the `unit::Valid` and `unit::Usable` concepts from
+ *      `Units.h` via the `unit_type` / `value_type` member typedefs, but
+ *      is not a `ValueUnit<>` specialization. Its value accessor is named
+ *      `drops()`, not `value()`.
+ *  @see IOUAmount, MPTAmount, STAmount, mulRatio()
+ */
 class XRPAmount : private boost::totally_ordered<XRPAmount>,
                   private boost::additive<XRPAmount>,
                   private boost::equality_comparable<XRPAmount, std::int64_t>,
                   private boost::additive<XRPAmount, std::int64_t>
 {
 public:
+    /** Unit tag satisfying the `unit::Valid` / `unit::Usable` concepts. */
     using unit_type = unit::dropTag;
+
+    /** Underlying integer type holding the drop count. */
     using value_type = std::int64_t;
 
 private:
@@ -34,15 +64,28 @@ public:
     constexpr XRPAmount&
     operator=(XRPAmount const& other) = default;
 
-    // Round to nearest, even on tie.
+    /** Construct from a `Number`, rounding to nearest, with ties to even.
+     *
+     *  Used when high-precision `Number` arithmetic produces a result that
+     *  must be expressed as an integer drop count, e.g. computed fees and
+     *  reserves that may not fall exactly on integer boundaries.
+     *
+     *  @param x The `Number` value to convert.
+     */
     explicit XRPAmount(Number const& x) : XRPAmount(static_cast<value_type>(x))
     {
     }
 
+    /** Construct a zero-drop amount from a `beast::Zero` sentinel.
+     *
+     *  Enables use in generic contexts that pass `beast::zero` without
+     *  knowing the concrete amount type, e.g. `XRPAmount x = beast::zero`.
+     */
     constexpr XRPAmount(beast::Zero) : drops_(0)
     {
     }
 
+    /** Assign zero drops from a `beast::Zero` sentinel. */
     constexpr XRPAmount&
     operator=(beast::Zero)
     {
@@ -50,10 +93,20 @@ public:
         return *this;
     }
 
+    /** Construct from a raw drop count.
+     *
+     *  Explicit to prevent silent integer-to-XRPAmount coercions.
+     *
+     *  @param drops The amount in drops.
+     */
     constexpr explicit XRPAmount(value_type drops) : drops_(drops)
     {
     }
 
+    /** Assign from a raw drop count.
+     *
+     *  @param drops The amount in drops.
+     */
     XRPAmount&
     operator=(value_type drops)
     {
@@ -61,12 +114,21 @@ public:
         return *this;
     }
 
+    /** Scale by a scalar integer, returning a new amount.
+     *
+     *  Multiplication is exact (no rounding); overflow is unchecked.
+     *  Use `mulRatio()` for ratio-based scaling with overflow detection.
+     *
+     *  @param rhs The integer multiplier.
+     *  @return The scaled amount.
+     */
     constexpr XRPAmount
     operator*(value_type const& rhs) const
     {
         return XRPAmount{drops_ * rhs};
     }
 
+    /** Scale by a scalar integer (commutative overload). */
     friend constexpr XRPAmount
     operator*(value_type lhs, XRPAmount const& rhs)
     {
@@ -109,6 +171,7 @@ public:
         return *this;
     }
 
+    /** Negate the amount (unary minus). */
     XRPAmount
     operator-() const
     {
@@ -140,12 +203,24 @@ public:
         return drops_ != 0;
     }
 
+    /** Implicitly convert to `Number` for use in high-precision arithmetic.
+     *
+     *  Non-explicit so that `XRPAmount` values participate transparently in
+     *  `Number`-based expressions used throughout the payment engine.
+     */
     operator Number() const noexcept
     {
         return drops();
     }
 
-    /** Return the sign of the amount */
+    /** Return the sign of the amount as -1, 0, or +1.
+     *
+     *  Follows the mathematical signum convention. Used widely in path and
+     *  transaction validation to detect non-positive amounts without branching
+     *  on the raw value.
+     *
+     *  @return -1 if negative, 0 if zero, +1 if positive.
+     */
     [[nodiscard]] constexpr int
     signum() const noexcept
     {
@@ -161,9 +236,29 @@ public:
         return drops_;
     }
 
+    /** Convert the drop count to a decimal XRP quantity.
+     *
+     *  Divides by `kDROPS_PER_XRP` (1,000,000) using floating-point
+     *  arithmetic. The result is an approximation; do not use for
+     *  ledger-critical calculations.
+     *
+     *  @return The equivalent XRP amount as a `double`.
+     */
     [[nodiscard]] constexpr double
     decimalXRP() const;
 
+    /** Safely narrow the drop count to a smaller integer type.
+     *
+     *  Returns `std::nullopt` if the value cannot be represented in `Dest`:
+     *  - value exceeds `std::numeric_limits<Dest>::max()`, or
+     *  - `Dest` is unsigned and the drop count is negative, or
+     *  - `Dest` is signed and the value is below `Dest::lowest()`.
+     *
+     *  Primarily used when serializing fee fields that use 32-bit wire types.
+     *
+     *  @tparam Dest The target integer type.
+     *  @return The drop count as `Dest`, or `std::nullopt` on range error.
+     */
     template <class Dest>
     [[nodiscard]] std::optional<Dest>
     dropsAs() const
@@ -177,6 +272,12 @@ public:
         return static_cast<Dest>(drops_);
     }
 
+    /** Safely narrow the drop count, returning a default on range error.
+     *
+     *  @tparam Dest The target integer type.
+     *  @param defaultValue Value to return when the drop count is out of range.
+     *  @return The drop count as `Dest`, or `defaultValue` on range error.
+     */
     template <class Dest>
     Dest
     dropsAs(Dest defaultValue) const
@@ -184,6 +285,12 @@ public:
         return dropsAs<Dest>().value_or(defaultValue);
     }
 
+    /** Safely narrow the drop count, using another `XRPAmount` as the fallback.
+     *
+     *  @tparam Dest The target integer type.
+     *  @param defaultValue `XRPAmount` whose drop count is returned on range error.
+     *  @return The drop count as `Dest`, or `defaultValue.drops()` on range error.
+     */
     template <class Dest>
     [[nodiscard]] Dest
     dropsAs(XRPAmount defaultValue) const
@@ -191,9 +298,14 @@ public:
         return dropsAs<Dest>().value_or(defaultValue.drops());
     }
 
-    /* Clips a 64-bit value to a 32-bit JSON number. It is only used
-     * in contexts that don't expect the value to ever approach
-     * the 32-bit limits (i.e. fees and reserves).
+    /** Saturate-cast the drop count to a 32-bit JSON integer.
+     *
+     *  Clamps values outside `[json::Int::min(), json::Int::max()]` to the
+     *  respective bound rather than throwing or wrapping. Only valid in
+     *  contexts where the value is never expected to approach 32-bit limits,
+     *  specifically fees and reserves.
+     *
+     *  @return A `json::Value` containing the (possibly clamped) drop count.
      */
     [[nodiscard]] json::Value
     jsonClipped() const
@@ -222,6 +334,7 @@ public:
         return drops_;
     }
 
+    /** Read a drop count from a stream into this amount. */
     friend std::istream&
     operator>>(std::istream& s, XRPAmount& val)
     {
@@ -229,6 +342,13 @@ public:
         return s;
     }
 
+    /** Return the smallest representable positive XRP amount (1 drop).
+     *
+     *  Used as a dust threshold: offers whose effective in- or out-amount
+     *  does not exceed this value are considered stale and removed.
+     *
+     *  @return `XRPAmount{1}`.
+     */
     static XRPAmount
     minPositiveAmount()
     {
@@ -236,7 +356,12 @@ public:
     }
 };
 
-/** Number of drops per 1 XRP */
+/** Number of drops per 1 XRP (1,000,000).
+ *
+ *  Declared as `constexpr XRPAmount` rather than a plain integer so it
+ *  participates in the type system and prevents inadvertent mixing with
+ *  unrelated integer values.
+ */
 constexpr XRPAmount kDROPS_PER_XRP{1'000'000};
 
 constexpr double
@@ -245,7 +370,7 @@ XRPAmount::decimalXRP() const
     return static_cast<double>(drops_) / kDROPS_PER_XRP.drops();
 }
 
-// Output XRPAmount as just the drops value.
+/** Write the drop count of an `XRPAmount` to an output stream. */
 template <class Char, class Traits>
 std::basic_ostream<Char, Traits>&
 operator<<(std::basic_ostream<Char, Traits>& os, XRPAmount const& q)
@@ -253,12 +378,31 @@ operator<<(std::basic_ostream<Char, Traits>& os, XRPAmount const& q)
     return os << q.drops();
 }
 
+/** Return a decimal string representation of the drop count. */
 inline std::string
 to_string(XRPAmount const& amount)
 {
     return std::to_string(amount.drops());
 }
 
+/** Scale an XRPAmount by the rational factor `num / den` with controlled rounding.
+ *
+ *  Uses a 128-bit intermediate product to avoid overflow when multiplying a
+ *  64-bit drop count by a 32-bit numerator. After division, sign-aware
+ *  rounding is applied: for a positive amount with a nonzero remainder,
+ *  `roundUp=true` increments the result by one drop; for a negative amount,
+ *  `roundUp=false` decrements (moves toward more negative), maintaining
+ *  symmetric semantics across signs.
+ *
+ *  @param amt     The amount to scale.
+ *  @param num     Numerator of the scaling ratio (32-bit, treated as unsigned).
+ *  @param den     Denominator of the scaling ratio (must be non-zero).
+ *  @param roundUp When `true`, round away from zero (positive) or toward
+ *      more-negative (negative) on a fractional remainder.
+ *  @return The scaled amount.
+ *  @throws std::runtime_error  if `den == 0`.
+ *  @throws std::overflow_error if the result exceeds `XRPAmount::value_type` range.
+ */
 inline XRPAmount
 mulRatio(XRPAmount const& amt, std::uint32_t num, std::uint32_t den, bool roundUp)
 {
diff --git a/include/xrpl/protocol/detail/STVar.h b/include/xrpl/protocol/detail/STVar.h
index 52045965fd..c411a237ae 100644
--- a/include/xrpl/protocol/detail/STVar.h
+++ b/include/xrpl/protocol/detail/STVar.h
@@ -1,3 +1,14 @@
+/** @file
+ *  Type-erased variant storage for all XRPL serialized field types.
+ *
+ *  Declares `STVar`, the small-object-optimized container that `STObject`
+ *  uses to store heterogeneous `STBase`-derived values by value. Also
+ *  declares the tag types and the `makeStvar<T>()` factory.
+ *
+ *  @see xrpl::detail::STVar
+ *  @see xrpl::STObject
+ */
+
 #pragma once
 
 #include <xrpl/protocol/SField.h>
@@ -9,32 +20,92 @@
 
 namespace xrpl::detail {
 
+/** Tag type that selects the default-valued construction path in `STVar`.
+ *
+ *  Pass the global `gDefaultObject` singleton to `STVar(DefaultObjectT,
+ *  SField)` to construct a field whose value is the type default. The
+ *  explicit constructor prevents accidental implicit use.
+ */
 struct DefaultObjectT
 {
     explicit DefaultObjectT() = default;
 };
 
+/** Tag type that selects the absent-field (not-present) construction path in
+ *  `STVar`.
+ *
+ *  Pass the global `gNonPresentObject` singleton to
+ *  `STVar(NonPresentObjectT, SField)` to create a bare `STBase` sentinel
+ *  representing a schema slot that carries no value in a particular object
+ *  instance (`STI_NOTPRESENT`). The explicit constructor prevents accidental
+ *  implicit use.
+ */
 struct NonPresentObjectT
 {
     explicit NonPresentObjectT() = default;
 };
 
+/** Global sentinel for default-valued object construction.
+ *
+ *  Passed as the first argument to `STVar(DefaultObjectT, SField)`.
+ */
 extern DefaultObjectT gDefaultObject;
+
+/** Global sentinel for absent-field object construction.
+ *
+ *  Passed as the first argument to `STVar(NonPresentObjectT, SField)`.
+ */
 extern NonPresentObjectT gNonPresentObject;
 
-// Concept to constrain STVar constructors, which
-// instantiate ST* types from SerializedTypeID
+/** Concept constraining the variadic argument lists accepted by `constructST`.
+ *
+ *  Permits exactly two calling forms:
+ *  - `(SField)` — default-constructs the concrete `ST*` type.
+ *  - `(SerialIter, SField)` — deserializes the concrete `ST*` type from a
+ *    wire-format stream.
+ *
+ *  Any other argument combination is a compile-time error, preventing misuse
+ *  of the template dispatch switch.
+ */
 template <typename... Args>
 concept ValidConstructSTArgs =
     (std::is_same_v<std::tuple<std::remove_cvref_t<Args>...>, std::tuple<SField>> ||
      std::is_same_v<std::tuple<std::remove_cvref_t<Args>...>, std::tuple<SerialIter, SField>>);
 
-// "variant" that can hold any type of serialized object
-// and includes a small-object allocation optimization.
+/** Type-erased, small-object-optimized container for any XRPL serialized type.
+ *
+ *  `STVar` is the storage primitive underlying `STObject`: every field in a
+ *  transaction or ledger entry is stored as a `detail::STVar` inside
+ *  `STObject`'s field vector. Because fields span roughly two dozen concrete
+ *  `STBase` subclasses, `STVar` provides uniform value semantics over the
+ *  polymorphic hierarchy.
+ *
+ *  **Small-object optimization:** objects whose `sizeof` fits within
+ *  `kMAX_SIZE` (72 bytes) are placement-new'd directly into the inline
+ *  aligned-storage buffer `d_`, avoiding a heap allocation. Larger types
+ *  (e.g., `STPathSet`, `STObject`, `STArray`) fall back to `new`. The
+ *  `onHeap()` predicate distinguishes the two cases by comparing `p_`
+ *  against `&d_`.
+ *
+ *  **Move semantics:** moving a heap-resident object is a zero-copy pointer
+ *  transfer. Moving an inline object requires calling the virtual
+ *  `STBase::move()` to relocate it into the new buffer, because the source
+ *  buffer address becomes invalid once the source `STVar` is destroyed.
+ *
+ *  **Depth guard:** the deserialization constructor enforces a maximum nesting
+ *  depth of 10 for `STObject`/`STArray` containers to prevent stack
+ *  exhaustion from malformed or malicious wire data.
+ *
+ *  @note `STVar` is an internal implementation detail (`xrpl::detail`). Public
+ *      callers interact with fields through `STObject` and its proxy accessors.
+ *  @see STBase
+ *  @see STObject
+ */
 class STVar
 {
 private:
-    // The largest "small object" we can accommodate
+    /** Inline buffer size in bytes; objects at or below this threshold are
+     *  stored in-place rather than on the heap. */
     static std::size_t constexpr kMAX_SIZE = 72;
 
     std::aligned_storage<kMAX_SIZE>::type d_ = {};
@@ -49,45 +120,102 @@ public:
     STVar&
     operator=(STVar&& rhs);
 
+    /** Move-construct from a bare `STBase` rvalue.
+     *
+     *  Delegates to `STBase::move()`, which places the object into `d_` if
+     *  it fits or heap-allocates it otherwise. The source object is in a
+     *  valid-but-unspecified state after this call.
+     *
+     *  @param t The `STBase`-derived rvalue to move into this container.
+     */
     STVar(STBase&& t)  // NOLINT(cppcoreguidelines-rvalue-reference-param-not-moved)
     {
         p_ = t.move(kMAX_SIZE, &d_);
     }
 
+    /** Copy-construct from a bare `STBase` lvalue.
+     *
+     *  Delegates to `STBase::copy()`, which places a copy of @p t into `d_`
+     *  if it fits or heap-allocates it otherwise.
+     *
+     *  @param t The `STBase`-derived object to copy into this container.
+     */
     STVar(STBase const& t)
     {
         p_ = t.copy(kMAX_SIZE, &d_);
     }
 
+    /** Construct a default-valued field.
+     *
+     *  Creates an instance of the concrete `ST*` type identified by
+     *  `name.fieldType`, initialized to that type's default value. Pass
+     *  `gDefaultObject` as the tag argument.
+     *
+     *  @param name The field descriptor; `name.fieldType` selects the
+     *      concrete subtype to construct.
+     */
     STVar(DefaultObjectT, SField const& name);
+
+    /** Construct an absent-field sentinel.
+     *
+     *  Creates a bare `STBase` with `getSType() == STI_NOTPRESENT`,
+     *  representing a schema slot that has no value in this particular
+     *  object instance. Pass `gNonPresentObject` as the tag argument.
+     *
+     *  @param name The field that is absent.
+     */
     STVar(NonPresentObjectT, SField const& name);
+
+    /** Deserialize a field from a wire-format byte stream.
+     *
+     *  Dispatches to the appropriate `ST*` deserialization constructor based
+     *  on `name.fieldType`. For `STObject` and `STArray`, the current
+     *  `depth` is incremented before recursing into nested `STVar`
+     *  construction to enforce the nesting limit.
+     *
+     *  @param sit   Iterator positioned at the start of the serialized value.
+     *  @param name  The field descriptor; `name.fieldType` selects the type.
+     *  @param depth Current nesting depth; must not exceed 10.
+     *  @throws std::runtime_error if `depth` exceeds 10.
+     */
     STVar(SerialIter& sit, SField const& name, int depth = 0);
 
+    /** Return a mutable reference to the contained `STBase` object. */
     STBase&
     get()
     {
         return *p_;
     }
+
+    /** Dereference to a mutable `STBase` reference. */
     STBase&
     operator*()
     {
         return get();
     }
+
+    /** Arrow operator for mutable member access on the contained object. */
     STBase*
     operator->()
     {
         return &get();
     }
+
+    /** Return a const reference to the contained `STBase` object. */
     [[nodiscard]] STBase const&
     get() const
     {
         return *p_;
     }
+
+    /** Dereference to a const `STBase` reference. */
     STBase const&
     operator*() const
     {
         return get();
     }
+
+    /** Arrow operator for const member access on the contained object. */
     STBase const*
     operator->() const
     {
@@ -106,6 +234,15 @@ private:
     void
     destroy();
 
+    /** Placement-new a `T` into the inline buffer or the heap.
+     *
+     *  If `sizeof(T) > kMAX_SIZE`, allocates via `new`. Otherwise,
+     *  placement-news directly into `d_`. Sets `p_` to point at the result.
+     *
+     *  @tparam T    The concrete `STBase` subtype to construct.
+     *  @tparam Args Constructor argument types forwarded to `T`.
+     *  @param args  Arguments forwarded to the `T` constructor.
+     */
     template <class T, class... Args>
     void
     construct(Args&&... args)
@@ -120,15 +257,34 @@ private:
         }
     }
 
-    /** Construct requested Serializable Type according to id.
-     * The variadic args are: (SField), or (SerialIter, SField).
-     * depth is ignored in former case.
+    /** Dispatch construction of the concrete `ST*` type identified by `id`.
+     *
+     *  Maps every `SerializedTypeID` to the appropriate `construct<T>()` call.
+     *  For `STObject` and `STArray`, forwards `depth` so the nesting limit
+     *  propagates into their own recursive `STVar` construction.
+     *  `STI_NOTPRESENT` always constructs a bare `STBase` regardless of
+     *  `args`.
+     *
+     *  @tparam Args Constrained by `ValidConstructSTArgs` to `(SField)` or
+     *      `(SerialIter, SField)`.
+     *  @param id    Selects the concrete `ST*` subtype.
+     *  @param depth Current nesting depth; forwarded only to `STObject` and
+     *      `STArray` constructors.
+     *  @param args  Construction arguments forwarded to the selected type.
+     *  @throws std::runtime_error if `id` is not a recognised
+     *      `SerializedTypeID`.
      */
     template <typename... Args>
         requires ValidConstructSTArgs<Args...>
     void
     constructST(SerializedTypeID id, int depth, Args&&... arg);
 
+    /** Return `true` if the contained object was allocated on the heap.
+     *
+     *  Compares `p_` against the address of the inline buffer `d_`. Used by
+     *  the move constructor and destructor to select between pointer-steal
+     *  and virtual-move / explicit-destruct paths respectively.
+     */
     [[nodiscard]] bool
     onHeap() const
     {
@@ -136,6 +292,19 @@ private:
     }
 };
 
+/** Construct an `STVar` holding a concrete `T` directly, bypassing type-ID
+ *  dispatch.
+ *
+ *  Use this factory in well-typed contexts where the exact `STBase` subclass
+ *  is already known, avoiding the overhead of the `constructST` switch. The
+ *  small-object optimization applies: `T` is placement-new'd into the inline
+ *  buffer when `sizeof(T) <= 72`, otherwise heap-allocated.
+ *
+ *  @tparam T    The concrete `STBase` subtype to store.
+ *  @tparam Args Constructor argument types forwarded to `T`.
+ *  @param args  Arguments forwarded to the `T` constructor.
+ *  @return An `STVar` owning the newly constructed `T` instance.
+ */
 template <class T, class... Args>
 inline STVar
 makeStvar(Args&&... args)
@@ -145,12 +314,28 @@ makeStvar(Args&&... args)
     return st;
 }
 
+/** Value equality: delegates to `STBase::isEquivalent()`.
+ *
+ *  Compares field values but not field names, consistent with `STBase`
+ *  semantics — two fields of equal value but different names are considered
+ *  equivalent at the `STVar` level.
+ *
+ *  @param lhs Left-hand operand.
+ *  @param rhs Right-hand operand.
+ *  @return `true` if the contained values are equivalent.
+ */
 inline bool
 operator==(STVar const& lhs, STVar const& rhs)
 {
     return lhs.get().isEquivalent(rhs.get());
 }
 
+/** Value inequality: opposite of `operator==`.
+ *
+ *  @param lhs Left-hand operand.
+ *  @param rhs Right-hand operand.
+ *  @return `true` if the contained values are not equivalent.
+ */
 inline bool
 operator!=(STVar const& lhs, STVar const& rhs)
 {
diff --git a/include/xrpl/protocol/detail/b58_utils.h b/include/xrpl/protocol/detail/b58_utils.h
index f860dc40c4..ee3dd73feb 100644
--- a/include/xrpl/protocol/detail/b58_utils.h
+++ b/include/xrpl/protocol/detail/b58_utils.h
@@ -13,21 +13,65 @@
 
 namespace xrpl {
 
+/** Idiomatic return type for the Base58 codec.
+ *
+ *  Pairs a success value of type `T` with a `std::error_code` drawn from
+ *  `TokenCodecErrc`. Using `boost::outcome` rather than exceptions keeps the
+ *  codec allocation-free and gives callers fine-grained error inspection
+ *  without try/catch overhead.
+ *
+ *  @tparam T The success value type.
+ */
 template <class T>
 using Result = boost::outcome_v2::result<T, std::error_code>;
 
 #ifndef _MSC_VER
 
+/** @file
+ *  Arithmetic primitives for XRPL's fast Base58 codec.
+ *
+ *  The fast path achieves 10–15× the throughput of the reference
+ *  Bitcoin-derived algorithm by using base 58¹⁰ as an intermediate
+ *  representation. Because 58¹⁰ = 430,804,206,899,405,824 fits in a
+ *  `uint64_t`, the codec operates on far fewer, much larger "digits",
+ *  dramatically reducing inner-loop iterations.
+ *
+ *  All functions in this namespace rely on GCC/Clang's `unsigned __int128`
+ *  extension. The entire namespace is therefore excluded on MSVC (`#ifndef
+ *  _MSC_VER`); `tokens.cpp` falls back to the reference implementation on
+ *  Windows.
+ */
 namespace b58_fast::detail {
 
-// This optimizes to what hand written asm would do (single divide)
+/** Compute quotient and remainder in a single hardware divide instruction.
+ *
+ *  A combined `divRem` call allows the compiler to emit one `divq`
+ *  instruction rather than two, avoiding the cost of a redundant division.
+ *
+ *  @param a The dividend.
+ *  @param b The divisor.
+ *  @return A tuple `{a / b, a % b}`.
+ */
 [[nodiscard]] inline std::tuple<std::uint64_t, std::uint64_t>
 divRem(std::uint64_t a, std::uint64_t b)
 {
     return {a / b, a % b};
 }
 
-// This optimizes to what hand written asm would do (single multiply)
+/** Multiply two 64-bit values and add a carry term without overflow.
+ *
+ *  Uses `unsigned __int128` as a 128-bit intermediate so that GCC/Clang can
+ *  fuse the operation into a single `mulq` instruction. This is the
+ *  per-limb step of hardware long-multiplication, used by
+ *  `inplaceBigintMul` to scale a multi-precision integer by a scalar.
+ *
+ *  @param a     First multiplicand.
+ *  @param b     Second multiplicand.
+ *  @param carry Carry value accumulated from a previous limb (may be zero).
+ *  @return A tuple `{low64, high64}` where `low64` is the new coefficient
+ *      (the low 64 bits of the 128-bit product) and `high64` is the carry
+ *      to propagate to the next limb.
+ */
 [[nodiscard]] inline std::tuple<std::uint64_t, std::uint64_t>
 carryingMul(std::uint64_t a, std::uint64_t b, std::uint64_t carry)
 {
@@ -37,6 +81,16 @@ carryingMul(std::uint64_t a, std::uint64_t b, std::uint64_t carry)
     return {c & 0xffff'ffff'ffff'ffff, c >> 64};
 }
 
+/** Add two 64-bit values and detect carry into the 65th bit.
+ *
+ *  Uses `unsigned __int128` as a 128-bit intermediate so that GCC/Clang
+ *  generates a single `addq`/`adcq` pair. Used by `inplaceBigintAdd` to
+ *  ripple carry through the limbs of a multi-precision integer.
+ *
+ *  @param a First addend.
+ *  @param b Second addend.
+ *  @return A tuple `{sum & 0xFFFF…F, carry}` where `carry` is 0 or 1.
+ */
 [[nodiscard]] inline std::tuple<std::uint64_t, std::uint64_t>
 carryingAdd(std::uint64_t a, std::uint64_t b)
 {
@@ -46,11 +100,27 @@ carryingAdd(std::uint64_t a, std::uint64_t b)
     return {c & 0xffff'ffff'ffff'ffff, c >> 64};
 }
 
-// Add a u64 to a "big uint" value inplace.
-// The bigint value is stored with the smallest coefficients first
-// (i.e a[0] is the 2^0 coefficient, a[n] is the 2^(64*n) coefficient)
-// panics if overflows (this is a specialized adder for b58 decoding.
-// it should never overflow).
+/** Add a `uint64_t` scalar to a multi-precision big integer in place.
+ *
+ *  The big integer is stored as a `span` of `uint64_t` limbs in
+ *  **little-endian limb order**: `a[0]` holds the 2⁰ coefficient,
+ *  `a[n]` holds the 2⁶⁴ⁿ coefficient. The scalar is added to `a[0]` and
+ *  any resulting carry is rippled forward through subsequent limbs.
+ *
+ *  Early return is the common case: once carry becomes zero the function
+ *  stops walking the span, so short carries (spanning one or two limbs) are
+ *  essentially free.
+ *
+ *  @param a The big integer to modify, with limbs in ascending power order.
+ *      Must contain at least 2 elements (one data limb + one carry limb).
+ *  @param b The scalar value to add.
+ *  @return `TokenCodecErrc::Success` on success.
+ *      `TokenCodecErrc::InputTooSmall` if `a.size() <= 1`.
+ *      `TokenCodecErrc::OverflowAdd` if carry propagates past the end of
+ *      `a`; this represents a programming invariant violation — valid
+ *      Base58 inputs are never large enough to trigger it.
+ *  @note `[[nodiscard]]` — the caller must inspect the return value.
+ */
 [[nodiscard]] inline TokenCodecErrc
 inplaceBigintAdd(std::span<std::uint64_t> a, std::uint64_t b)
 {
@@ -77,6 +147,26 @@ inplaceBigintAdd(std::span<std::uint64_t> a, std::uint64_t b)
     return TokenCodecErrc::Success;
 }
 
+/** Multiply a multi-precision big integer by a `uint64_t` scalar in place.
+ *
+ *  Limbs are stored in **little-endian limb order** (same convention as
+ *  `inplaceBigintAdd`). The function multiplies every limb except the last
+ *  by `b`, propagating carry forward. The final carry is written into
+ *  `a[last_index]`, which must be zero on entry — it acts as a reserved
+ *  overflow slot.
+ *
+ *  `tokens.cpp` always passes a span one element larger than the live
+ *  portion so that this overflow slot is always available.
+ *
+ *  @param a The big integer to scale in place. `a[a.size()-1]` must be zero
+ *      on entry; it receives the overflow carry on exit.
+ *  @param b The scalar multiplier.
+ *  @return `TokenCodecErrc::Success` on success.
+ *      `TokenCodecErrc::InputTooSmall` if `a` is empty.
+ *      `TokenCodecErrc::InputTooLarge` if `a[last]` is non-zero on entry,
+ *      indicating the value would overflow the allocated limb array.
+ *  @note `[[nodiscard]]` — the caller must inspect the return value.
+ */
 [[nodiscard]] inline TokenCodecErrc
 inplaceBigintMul(std::span<std::uint64_t> a, std::uint64_t b)
 {
@@ -100,8 +190,29 @@ inplaceBigintMul(std::span<std::uint64_t> a, std::uint64_t b)
     return TokenCodecErrc::Success;
 }
 
-// divide a "big uint" value inplace and return the mod
-// numerator is stored so smallest coefficients come first
+/** Divide a multi-precision big integer in place by a scalar, returning the remainder.
+ *
+ *  Performs long division from the most significant limb down, maintaining a
+ *  running `prevRem`. At each step it forms a 128-bit dividend
+ *  `(prevRem << 64) | numerator[i]` and divides it by `divisor` using an
+ *  inner lambda that keeps the `unsigned __int128` logic localized.
+ *  `XRPL_ASSERT` guards verify that neither quotient nor remainder
+ *  overflows 64 bits (guaranteed by the invariant that `prevRem < divisor`
+ *  at every step).
+ *
+ *  Limbs are stored in **little-endian limb order**: `numerator[0]` is the
+ *  2⁰ coefficient, `numerator[n]` is the 2⁶⁴ⁿ coefficient. On return,
+ *  `numerator` is overwritten with the quotient in the same layout.
+ *
+ *  This is the workhorse of the encoding path: `tokens.cpp` calls it in a
+ *  loop to extract successive base-58¹⁰ coefficients from the binary
+ *  representation of the value being encoded.
+ *
+ *  @param numerator The big integer to divide, modified in place to hold
+ *      the quotient. An empty span is treated as zero (returns 0).
+ *  @param divisor   The scalar divisor. Behavior is undefined if zero.
+ *  @return The remainder of the division (`numerator % divisor`).
+ */
 [[nodiscard]] inline std::uint64_t
 inplaceBigintDivRem(std::span<uint64_t> numerator, std::uint64_t divisor)
 {
@@ -149,9 +260,20 @@ inplaceBigintDivRem(std::span<uint64_t> numerator, std::uint64_t divisor)
     return prevRem;
 }
 
-// convert from base 58^10 to base 58
-// put largest coeffs first
-// the `_be` suffix stands for "big endian"
+/** Decompose a single base-58¹⁰ coefficient into 10 base-58 digits, most significant first.
+ *
+ *  Repeatedly divides `input` by 58, filling the result array from the back
+ *  so that the most significant digit occupies index 0 (big-endian digit
+ *  order). The caller (`tokens.cpp`) maps each digit through
+ *  `alphabetForward[]` to produce the final Base58 character.
+ *
+ *  @param input A value in [0, 58¹⁰). The precondition `input < 58¹⁰` is
+ *      checked by `XRPL_ASSERT`; a value at or above this bound indicates a
+ *      logic error in the preceding division step.
+ *  @return An array of 10 `uint8_t` values in [0, 58), ordered
+ *      most-significant digit first.
+ *  @note `[[nodiscard]]` — the caller must use the returned digit array.
+ */
 [[nodiscard]] inline std::array<std::uint8_t, 10>
 b5810ToB58Be(std::uint64_t input)
 {
diff --git a/include/xrpl/protocol/detail/secp256k1.h b/include/xrpl/protocol/detail/secp256k1.h
index 17dfa3ff25..c82ab927d4 100644
--- a/include/xrpl/protocol/detail/secp256k1.h
+++ b/include/xrpl/protocol/detail/secp256k1.h
@@ -1,13 +1,50 @@
+/** @file
+ *  Process-wide singleton accessor for the libsecp256k1 context.
+ *
+ *  This header is an implementation detail of the XRPL protocol layer.
+ *  External code should use `SecretKey` and `PublicKey` rather than
+ *  including this header directly.
+ */
+
 #pragma once
 
 #include <secp256k1.h>
 
 namespace xrpl {
 
+/** Returns the process-wide, read-only libsecp256k1 context.
+ *
+ *  The context is created on the first call with both
+ *  `SECP256K1_CONTEXT_VERIFY` and `SECP256K1_CONTEXT_SIGN` flags so that
+ *  the same instance can service signing (in `SecretKey.cpp`) and
+ *  verification (in `PublicKey.cpp`) without any additional setup. It is
+ *  destroyed when the process exits.
+ *
+ *  The function template with a defaulted, unused type parameter is a
+ *  standard C++ idiom for defining a function that owns a `static` local
+ *  variable in a header file without violating the One Definition Rule
+ *  (ODR). The `static Holder` is initialized exactly once regardless of
+ *  how many translation units include this header.
+ *
+ *  @tparam Unused Defaulted to `void`; callers should never supply a
+ *      value. The parameter exists solely to satisfy the ODR.
+ *  @return A `const` pointer to the shared `secp256k1_context`. The
+ *      `const` qualifier matches the secp256k1 library's thread-safety
+ *      contract: concurrent reads through a `const*` require no locking.
+ *  @note Do not call `secp256k1_context_destroy` on the returned pointer;
+ *      lifetime is managed internally by the `Holder` RAII wrapper.
+ */
 template <class = void>
 secp256k1_context const*
 secp256k1Context()
 {
+    /** RAII owner for the shared `secp256k1_context`.
+     *
+     *  Allocates the context with both `SECP256K1_CONTEXT_VERIFY` and
+     *  `SECP256K1_CONTEXT_SIGN` on construction, and destroys it on
+     *  destruction. The single `static` instance inside
+     *  `secp256k1Context()` lives for the duration of the process.
+     */
     struct Holder
     {
         secp256k1_context* impl;
diff --git a/include/xrpl/protocol/detail/token_errors.h b/include/xrpl/protocol/detail/token_errors.h
index 9d5e98e646..df068c1466 100644
--- a/include/xrpl/protocol/detail/token_errors.h
+++ b/include/xrpl/protocol/detail/token_errors.h
@@ -1,41 +1,101 @@
+/** @file
+ *  Error taxonomy for the XRPL Base58Check token codec.
+ *
+ *  Defines `TokenCodecErrc` and wires it into the `std::error_code`
+ *  machinery so that codec failures compose cleanly with `B58Result<T>`
+ *  (`Expected<T, std::error_code>`) without exceptions or casts.
+ */
+
 #pragma once
 
 #include <system_error>
 
 namespace xrpl {
+
+/** Error codes produced by the Base58Check token codec.
+ *
+ *  Every distinct failure mode the encode/decode pipeline can signal is
+ *  represented here. `Success` is zero so that a default-constructed
+ *  `std::error_code` built from this enum compares equal to no-error.
+ *
+ *  The enumerators fall into four groups:
+ *  - **Size** (`InputTooLarge`, `InputTooSmall`, `OutputTooSmall`): bounds
+ *    violations detected before or during a conversion pass.
+ *  - **Alphabet** (`BadB58Character`, `InvalidEncodingChar`): invalid bytes
+ *    in a Base58 string, distinguished by context — a character outside the
+ *    58-symbol alphabet vs. one that is invalid for the specific encoding.
+ *  - **Semantic** (`MismatchedTokenType`, `MismatchedChecksum`): structurally
+ *    valid input that fails XRPL-specific validation — wrong one-byte type
+ *    prefix or a four-byte checksum mismatch.
+ *  - **Arithmetic** (`OverflowAdd`): bignum addition overflow during the
+ *    multi-precision fast-path decode, indicating the encoded value exceeds
+ *    the expected output width. Valid Base58Check inputs never trigger this;
+ *    it surfaces only on malformed or adversarial input.
+ */
 enum class TokenCodecErrc {
-    Success = 0,
-    InputTooLarge,
-    InputTooSmall,
-    BadB58Character,
-    OutputTooSmall,
-    MismatchedTokenType,
-    MismatchedChecksum,
-    InvalidEncodingChar,
-    OverflowAdd,
-    Unknown,
+    Success = 0,           /**< Conversion succeeded. Zero value is the
+                                `std::error_code` no-error sentinel. */
+    InputTooLarge,         /**< Input buffer exceeds the maximum accepted size. */
+    InputTooSmall,         /**< Input buffer is shorter than the minimum required. */
+    BadB58Character,       /**< A byte in the input is not in the Base58 alphabet. */
+    OutputTooSmall,        /**< Caller-supplied output buffer is too small for the result. */
+    MismatchedTokenType,   /**< Decoded one-byte token-type prefix does not match
+                                the expected `TokenType`. */
+    MismatchedChecksum,    /**< Decoded four-byte checksum does not match the
+                                recomputed value; the token is corrupt or truncated. */
+    InvalidEncodingChar,   /**< A character is syntactically invalid for this
+                                encoding context (distinct from `BadB58Character`). */
+    OverflowAdd,           /**< Bignum addition overflowed the fixed-size limb array;
+                                the encoded value is too large for the output type. */
+    Unknown,               /**< Catch-all for unrecognised internal error states. */
 };
+
 }  // namespace xrpl
 
 namespace std {
+
+/** Opt `TokenCodecErrc` into the `std::error_code` implicit-conversion protocol.
+ *
+ *  With this specialisation a bare `TokenCodecErrc` enumerator can be stored
+ *  in or compared against a `std::error_code` without an explicit
+ *  `make_error_code` call, enabling natural use in `Unexpected(errc)` and
+ *  `ec == TokenCodecErrc::X` comparisons.
+ */
 template <>
 struct is_error_code_enum<xrpl::TokenCodecErrc> : true_type
 {
 };
+
 }  // namespace std
 
 namespace xrpl {
 namespace detail {
+
+/** `std::error_category` singleton for the Base58Check codec error domain.
+ *
+ *  Provides the stable category name `"TokenCodecError"` and human-readable
+ *  messages for every `TokenCodecErrc` enumerator. Declared `final` — only
+ *  one category exists for this error domain.
+ *
+ *  Obtain the singleton via `tokenCodecErrcCategory()` rather than
+ *  constructing this class directly.
+ */
 class TokenCodecErrcCategory : public std::error_category
 {
 public:
-    // Return a short descriptive name for the category
+    /** Return the stable name of this error category. */
     [[nodiscard]] char const*
     name() const noexcept final
     {
         return "TokenCodecError";
     }
-    // Return what each enum means in text
+
+    /** Translate a `TokenCodecErrc` integer value into a human-readable string.
+     *
+     *  @param c An integer cast of a `TokenCodecErrc` enumerator.
+     *  @return A short English description of the error condition; returns
+     *      `"unknown"` for unrecognised values.
+     */
     [[nodiscard]] std::string
     message(int c) const final
     {
@@ -64,8 +124,18 @@ public:
         }
     }
 };
+
 }  // namespace detail
 
+/** Return the `TokenCodecErrc` error category singleton.
+ *
+ *  Uses a function-local static to guarantee thread-safe, zero-overhead
+ *  initialisation (C++11 magic-static semantics). Called by
+ *  `make_error_code` and by the implicit `std::error_code` conversion
+ *  enabled through `is_error_code_enum`.
+ *
+ *  @return A `const` reference to the single `TokenCodecErrcCategory` instance.
+ */
 inline xrpl::detail::TokenCodecErrcCategory const&
 tokenCodecErrcCategory()
 {
@@ -73,9 +143,21 @@ tokenCodecErrcCategory()
     return kC;
 }
 
+/** Construct a `std::error_code` from a `TokenCodecErrc` enumerator.
+ *
+ *  This is the ADL-located overload required by the `std::error_code`
+ *  implicit-conversion protocol. Combined with the `is_error_code_enum`
+ *  specialisation, it allows `TokenCodecErrc` values to be returned
+ *  directly wherever a `std::error_code` is expected — including inside
+ *  `Unexpected(errc)` expressions in `B58Result<T>` return sites.
+ *
+ *  @param e The codec error enumerator to wrap.
+ *  @return A `std::error_code` pairing `e` with `tokenCodecErrcCategory()`.
+ */
 inline std::error_code
 make_error_code(xrpl::TokenCodecErrc e)
 {
     return {static_cast<int>(e), tokenCodecErrcCategory()};
 }
+
 }  // namespace xrpl
diff --git a/include/xrpl/protocol/digest.h b/include/xrpl/protocol/digest.h
index 6564237771..d9e869a6bc 100644
--- a/include/xrpl/protocol/digest.h
+++ b/include/xrpl/protocol/digest.h
@@ -9,21 +9,32 @@
 
 namespace xrpl {
 
-/** Message digest functions used in the codebase
-
-    @note These are modeled to meet the requirements of `Hasher` in the
-          `hash_append` interface, discussed in proposal:
-
-          N3980 "Types Don't Know #"
-          http://www.open-std.org/jtc1/sc22/wg21/docs/papers/2014/n3980.html
-*/
+/** @file
+ *  Cryptographic digest primitives for the XRPL protocol layer.
+ *
+ *  Defines all hasher structs used to compute ledger object identifiers,
+ *  transaction IDs, account addresses, and signing payloads. Every type
+ *  satisfies the `Hasher` concept from N3980 ("Types Don't Know #"), enabling
+ *  `beast::hash_append` to drive any of them generically.
+ *
+ *  @see https://www.open-std.org/jtc1/sc22/wg21/docs/papers/2014/n3980.html
+ */
 
 //------------------------------------------------------------------------------
 
-/** RIPEMD-160 digest
-
-    @note This uses the OpenSSL implementation
-*/
+/** RIPEMD-160 hasher backed by the OpenSSL `RIPEMD160_CTX` implementation.
+ *
+ *  Satisfies the `Hasher` concept: feed data via `operator()`, then extract the
+ *  20-byte digest with `explicit operator result_type()`.
+ *
+ *  The OpenSSL context is stored in an opaque `char ctx_[96]` buffer so that
+ *  this header never needs to include any OpenSSL headers. A `static_assert` in
+ *  the constructor verifies the buffer size matches `sizeof(RIPEMD160_CTX)` at
+ *  compile time; if an OpenSSL upgrade changes the struct size the build fails
+ *  rather than silently corrupting memory.
+ *
+ *  @note Prefer the `ripemd160_hasher` alias over this name at call sites.
+ */
 struct OpensslRipemd160Hasher
 {
 public:
@@ -33,9 +44,15 @@ public:
 
     OpensslRipemd160Hasher();
 
+    /** Feed bytes into the running digest.
+     *
+     *  @param data Pointer to the input bytes.
+     *  @param size Number of bytes to consume.
+     */
     void
     operator()(void const* data, std::size_t size) noexcept;
 
+    /** Finalize and return the 20-byte RIPEMD-160 digest. */
     explicit
     operator result_type() noexcept;
 
@@ -43,10 +60,19 @@ private:
     char ctx_[96]{};
 };
 
-/** SHA-512 digest
-
-    @note This uses the OpenSSL implementation
-*/
+/** SHA-512 hasher backed by the OpenSSL `SHA512_CTX` implementation.
+ *
+ *  Satisfies the `Hasher` concept: feed data via `operator()`, then extract the
+ *  64-byte digest with `explicit operator result_type()`.
+ *
+ *  Like `OpensslRipemd160Hasher`, the context is stored in an opaque
+ *  `char ctx_[216]` buffer to avoid exposing OpenSSL headers, with a
+ *  compile-time size check in the constructor.
+ *
+ *  @note Prefer the `sha512_hasher` alias over this name at call sites. Most
+ *      callers should use `sha512_half_hasher` / `sha512Half()` instead, which
+ *      truncate the output to the 256-bit XRPL canonical form.
+ */
 struct OpensslSha512Hasher
 {
 public:
@@ -56,9 +82,15 @@ public:
 
     OpensslSha512Hasher();
 
+    /** Feed bytes into the running digest.
+     *
+     *  @param data Pointer to the input bytes.
+     *  @param size Number of bytes to consume.
+     */
     void
     operator()(void const* data, std::size_t size) noexcept;
 
+    /** Finalize and return the 64-byte SHA-512 digest. */
     explicit
     operator result_type() noexcept;
 
@@ -66,10 +98,17 @@ private:
     char ctx_[216]{};
 };
 
-/** SHA-256 digest
-
-    @note This uses the OpenSSL implementation
-*/
+/** SHA-256 hasher backed by the OpenSSL `SHA256_CTX` implementation.
+ *
+ *  Satisfies the `Hasher` concept: feed data via `operator()`, then extract the
+ *  32-byte digest with `explicit operator result_type()`.
+ *
+ *  Like `OpensslRipemd160Hasher`, the context is stored in an opaque
+ *  `char ctx_[112]` buffer to avoid exposing OpenSSL headers, with a
+ *  compile-time size check in the constructor.
+ *
+ *  @note Prefer the `sha256_hasher` alias over this name at call sites.
+ */
 struct OpensslSha256Hasher
 {
 public:
@@ -79,9 +118,15 @@ public:
 
     OpensslSha256Hasher();
 
+    /** Feed bytes into the running digest.
+     *
+     *  @param data Pointer to the input bytes.
+     *  @param size Number of bytes to consume.
+     */
     void
     operator()(void const* data, std::size_t size) noexcept;
 
+    /** Finalize and return the 32-byte SHA-256 digest. */
     explicit
     operator result_type() noexcept;
 
@@ -91,27 +136,34 @@ private:
 
 //------------------------------------------------------------------------------
 
+/** Implementation-neutral alias for the RIPEMD-160 hasher. */
 using ripemd160_hasher = OpensslRipemd160Hasher;
+
+/** Implementation-neutral alias for the SHA-256 hasher. */
 using sha256_hasher = OpensslSha256Hasher;
+
+/** Implementation-neutral alias for the SHA-512 hasher. */
 using sha512_hasher = OpensslSha512Hasher;
 
 //------------------------------------------------------------------------------
 
-/** Returns the RIPEMD-160 digest of the SHA256 hash of the message.
-
-    This operation is used to compute the 160-bit identifier
-    representing an XRPL account, from a message. Typically the
-    message is the public key of the account - which is not
-    stored in the account root.
-
-    The same computation is used regardless of the cryptographic
-    scheme implied by the public key. For example, the public key
-    may be an ed25519 public key or a secp256k1 public key. Support
-    for new cryptographic systems may be added, using the same
-    formula for calculating the account identifier.
-
-    Meets the requirements of Hasher (in hash_append)
-*/
+/** Hasher that computes RIPEMD-160(SHA-256(msg)) — the XRPL account ID formula.
+ *
+ *  This is the Bitcoin-lineage two-pass construction used throughout XRPL to
+ *  derive a 160-bit `AccountID` from a public key. Data is accumulated into a
+ *  `sha256_hasher`; on conversion, SHA-256 is finalized and its 32-byte output
+ *  is immediately fed into a fresh `ripemd160_hasher` — no intermediate buffer
+ *  escapes the function.
+ *
+ *  The formula is deliberately key-type-agnostic: both secp256k1 and Ed25519
+ *  public keys are hashed the same way, decoupling account addresses from the
+ *  underlying cryptographic scheme. Future key types can be added without
+ *  changing the address derivation.
+ *
+ *  Satisfies the `Hasher` concept (N3980 `hash_append` interface).
+ *
+ *  @see calcAccountID() in AccountID.h
+ */
 struct RipeshaHasher
 {
 private:
@@ -122,12 +174,20 @@ public:
 
     using result_type = std::array<std::uint8_t, 20>;
 
+    /** Feed bytes into the running SHA-256 accumulator.
+     *
+     *  @param data Pointer to the input bytes.
+     *  @param size Number of bytes to consume.
+     */
     void
     operator()(void const* data, std::size_t size) noexcept
     {
         h_(data, size);
     }
 
+    /** Finalize SHA-256, hash its output through RIPEMD-160, and return the
+     *  20-byte account ID digest.
+     */
     explicit
     operator result_type() noexcept
     {
@@ -142,11 +202,26 @@ public:
 
 namespace detail {
 
-/** Returns the SHA512-Half digest of a message.
-
-    The SHA512-Half is the first 256 bits of the
-    SHA-512 digest of the message.
-*/
+/** SHA-512-Half hasher: computes SHA-512 and returns the first 256 bits as a
+ *  `uint256`.
+ *
+ *  SHA-512 is used (rather than SHA-256) because it is faster on 64-bit
+ *  hardware due to wider register operations, while truncating to 256 bits
+ *  still provides strong security. This is the dominant hash construction
+ *  across XRPL's protocol layer — transaction IDs, ledger node hashes, signing
+ *  payloads, and manifest digests all use it.
+ *
+ *  `kENDIAN = big` ensures that when `beast::hash_append` serializes multi-byte
+ *  integers before feeding them to this hasher, the bytes are in network
+ *  (big-endian) order — matching the XRPL wire format.
+ *
+ *  @tparam Secure When `true`, the destructor calls `secure_erase()` on the
+ *      internal SHA-512 context to prevent sensitive key material from
+ *      lingering in memory. When `false`, the destructor is a no-op with zero
+ *      overhead. Use `sha512_half_hasher_s` (Secure=true) when hashing
+ *      private keys or seed material; use `sha512_half_hasher` (Secure=false)
+ *      for all other ledger computations.
+ */
 template <bool Secure>
 struct BasicSha512HalfHasher
 {
@@ -163,12 +238,18 @@ public:
         erase(std::integral_constant<bool, Secure>{});
     }
 
+    /** Feed bytes into the running SHA-512 accumulator.
+     *
+     *  @param data Pointer to the input bytes.
+     *  @param size Number of bytes to consume.
+     */
     void
     operator()(void const* data, std::size_t size) noexcept
     {
         h_(data, size);
     }
 
+    /** Finalize SHA-512 and return the first 256 bits as a `uint256`. */
     explicit
     operator result_type() noexcept
     {
@@ -191,14 +272,41 @@ private:
 
 }  // namespace detail
 
+/** Standard SHA-512-Half hasher for ledger computations.
+ *
+ *  The destructor is a no-op. Use this for transaction IDs, ledger node
+ *  hashes, and any non-sensitive protocol payload. Use `sha512_half_hasher_s`
+ *  when hashing key or seed material.
+ */
 using sha512_half_hasher = detail::BasicSha512HalfHasher<false>;
 
-// secure version
+/** Secure SHA-512-Half hasher that zeroes internal state on destruction.
+ *
+ *  Identical to `sha512_half_hasher` except the destructor calls
+ *  `secure_erase()` on the embedded SHA-512 context, preventing sensitive
+ *  material from remaining in memory after the hasher goes out of scope.
+ */
 using sha512_half_hasher_s = detail::BasicSha512HalfHasher<true>;
 
 //------------------------------------------------------------------------------
 
-/** Returns the SHA512-Half of a series of objects. */
+/** Compute the SHA-512-Half of one or more objects and return a `uint256`.
+ *
+ *  Constructs a `sha512_half_hasher`, drives it with `beast::hash_append` over
+ *  all arguments in order, and returns the 256-bit result. Because
+ *  `hash_append` is overloaded for all XRPL protocol types — including
+ *  `HashPrefix`, `STObject`, `Serializer`, and primitive integers — a single
+ *  call can serialize and hash an entire transaction or ledger node.
+ *
+ *  Always prepend a `HashPrefix` constant as the first argument to enforce
+ *  domain separation and prevent cross-context hash collisions.
+ *
+ *  @param args One or more `hash_append`-compatible values to hash in order.
+ *  @return The first 256 bits of the SHA-512 digest of the serialized input.
+ *
+ *  @see sha512HalfS() for the secure variant that zeroes internal state.
+ *  @see HashPrefix.h for the domain-separation prefix constants.
+ */
 template <class... Args>
 sha512_half_hasher::result_type
 sha512Half(Args const&... args)
@@ -209,12 +317,19 @@ sha512Half(Args const&... args)
     return static_cast<typename sha512_half_hasher::result_type>(h);
 }
 
-/** Returns the SHA512-Half of a series of objects.
-
-    Postconditions:
-        Temporary memory storing copies of
-        input messages will be cleared.
-*/
+/** Compute the SHA-512-Half of one or more objects, zeroing internal state
+ *  after extraction.
+ *
+ *  Identical to `sha512Half()` except the internal `sha512_half_hasher_s`
+ *  context is erased via `secure_erase()` on destruction, preventing
+ *  sensitive material (e.g., a private key or seed) from lingering on the
+ *  stack after the call returns.
+ *
+ *  @param args One or more `hash_append`-compatible values to hash in order.
+ *  @return The first 256 bits of the SHA-512 digest of the serialized input.
+ *
+ *  @see sha512Half() for the non-secure, lower-overhead variant.
+ */
 template <class... Args>
 sha512_half_hasher_s::result_type
 sha512HalfS(Args const&... args)
diff --git a/include/xrpl/protocol/json_get_or_throw.h b/include/xrpl/protocol/json_get_or_throw.h
index 9399f25827..7a5f7f3c8d 100644
--- a/include/xrpl/protocol/json_get_or_throw.h
+++ b/include/xrpl/protocol/json_get_or_throw.h
@@ -1,5 +1,22 @@
 #pragma once
 
+/** @file
+ *  Typed JSON extraction with SField keys and structured exceptions.
+ *
+ *  Provides `json::getOrThrow<T>` and `json::getOptional<T>`: replacements for
+ *  raw `Json::Value` access that throw structured exceptions instead of
+ *  silently returning defaults or coercing types.  The key type is
+ *  `xrpl::SField` rather than a plain string, tying every lookup to a declared
+ *  XRPL protocol field and eliminating magic string literals.
+ *
+ *  @note Additional specializations for `xrpl::AccountID`, `xrpl::PublicKey`,
+ *      and `xrpl::STAmount` are defined in their respective headers, following
+ *      the same pattern established here.  The primary consumer is
+ *      `XChainAttestations.cpp`, which calls `getOrThrow` in constructor
+ *      initializer lists to reject partially-initialized attestation objects
+ *      before they reach validation logic.
+ */
+
 #include <xrpl/basics/Buffer.h>
 #include <xrpl/basics/StringUtilities.h>
 #include <xrpl/basics/contract.h>
@@ -11,13 +28,29 @@
 #include <optional>
 
 namespace json {
+
+/** Exception thrown when a required JSON key is absent from the object.
+ *
+ *  The diagnostic message is constructed lazily on the first call to `what()`
+ *  to avoid a string allocation at the throw site.
+ */
 struct JsonMissingKeyError : std::exception
 {
+    /** The missing key name, pointing into the `StaticString` storage. */
     char const* const key;
+
+    /** Lazily-populated message returned by `what()`. */
     mutable std::string msg;
+
+    /** Construct with the name of the missing key. */
     JsonMissingKeyError(json::StaticString const& k) : key{k.cStr()}
     {
     }
+
+    /** Return a human-readable description of the missing key.
+     *
+     *  The message string is built on the first call and cached in `msg`.
+     */
     char const*
     what() const noexcept override
     {
@@ -29,15 +62,32 @@ struct JsonMissingKeyError : std::exception
     }
 };
 
+/** Exception thrown when a JSON key is present but its value has the wrong type.
+ *
+ *  The diagnostic message is constructed lazily on the first call to `what()`
+ *  to avoid a string allocation at the throw site.
+ */
 struct JsonTypeMismatchError : std::exception
 {
+    /** The key whose value had an unexpected type. */
     char const* const key;
+
+    /** Human-readable name of the expected type (e.g., `"string"`, `"uint64"`). */
     std::string const expectedType;
+
+    /** Lazily-populated message returned by `what()`. */
     mutable std::string msg;
+
+    /** Construct with the key name and the name of the expected type. */
     JsonTypeMismatchError(json::StaticString const& k, std::string et)
         : key{k.cStr()}, expectedType{std::move(et)}
     {
     }
+
+    /** Return a human-readable description of the type mismatch.
+     *
+     *  The message string is built on the first call and cached in `msg`.
+     */
     char const*
     what() const noexcept override
     {
@@ -50,6 +100,28 @@ struct JsonTypeMismatchError : std::exception
     }
 };
 
+/** Extract a typed value from a JSON object using an XRPL protocol field key.
+ *
+ *  The key is taken from `field.getJsonName()`, a `Json::StaticString` that
+ *  avoids dynamic allocation in the JSON library's hash map and ties every
+ *  lookup to a declared XRPL protocol field.
+ *
+ *  This primary template is intentionally unimplementable: the
+ *  `static_assert` fires for any `T` that lacks an explicit specialization,
+ *  turning unsupported types into a compile error rather than a runtime
+ *  surprise.  Specializations exist for `std::string`, `bool`,
+ *  `std::uint64_t`, and `xrpl::Buffer` in this header, and for
+ *  `xrpl::AccountID`, `xrpl::PublicKey`, and `xrpl::STAmount` in their
+ *  respective headers.
+ *
+ *  @tparam T The target C++ type.  Must have an explicit specialization.
+ *  @param v The JSON object to read from.
+ *  @param field The SField identifying the key to look up.
+ *  @return The extracted and type-checked value.
+ *  @throws JsonMissingKeyError if the key is absent from `v`.
+ *  @throws JsonTypeMismatchError if the key is present but the value cannot
+ *      be interpreted as `T`.
+ */
 template <class T>
 T
 getOrThrow(json::Value const& v, xrpl::SField const& field)
@@ -57,6 +129,17 @@ getOrThrow(json::Value const& v, xrpl::SField const& field)
     static_assert(sizeof(T) == -1, "This function must be specialized");
 }
 
+/** Extract a UTF-8 string from a JSON object field.
+ *
+ *  No type coercion is applied: the value must be a JSON string (`isString()`).
+ *  Numeric values are not accepted.
+ *
+ *  @param v The JSON object to read from.
+ *  @param field The SField identifying the key to look up.
+ *  @return The string value.
+ *  @throws JsonMissingKeyError if the key is absent.
+ *  @throws JsonTypeMismatchError if the value is not a JSON string.
+ */
 template <>
 inline std::string
 getOrThrow(json::Value const& v, xrpl::SField const& field)
@@ -72,7 +155,20 @@ getOrThrow(json::Value const& v, xrpl::SField const& field)
     return inner.asString();
 }
 
-// Note, this allows integer numeric fields to act as bools
+/** Extract a boolean from a JSON object field.
+ *
+ *  Accepts either a native JSON boolean or any integral value, where any
+ *  non-zero integer maps to `true`.  This mirrors a common XRPL convention
+ *  where boolean-semantic fields such as `sfWasLockingChainSend` are encoded
+ *  as `0`/`1` integers in JSON rather than as JSON `true`/`false`.
+ *
+ *  @param v The JSON object to read from.
+ *  @param field The SField identifying the key to look up.
+ *  @return The boolean value.
+ *  @throws JsonMissingKeyError if the key is absent.
+ *  @throws JsonTypeMismatchError if the value is neither a JSON boolean nor an
+ *      integral type.
+ */
 template <>
 inline bool
 getOrThrow(json::Value const& v, xrpl::SField const& field)
@@ -90,6 +186,26 @@ getOrThrow(json::Value const& v, xrpl::SField const& field)
     return inner.asInt() != 0;
 }
 
+/** Extract a 64-bit unsigned integer from a JSON object field.
+ *
+ *  Three source formats are accepted, in order of preference:
+ *  1. Native JSON unsigned integer (`isUInt()`).
+ *  2. Signed JSON integer that is non-negative (negative values throw).
+ *  3. Hex-encoded string, parsed via `std::from_chars` in base 16.
+ *
+ *  The hex string path exists because 64-bit values exceed JavaScript's
+ *  safe integer range (`2^53 - 1`), so some XRPL JSON producers encode
+ *  large integers as hex strings.  A partial parse — where `from_chars`
+ *  succeeds but does not consume the entire string — is treated as a type
+ *  error.
+ *
+ *  @param v The JSON object to read from.
+ *  @param field The SField identifying the key to look up.
+ *  @return The extracted value as `std::uint64_t`.
+ *  @throws JsonMissingKeyError if the key is absent.
+ *  @throws JsonTypeMismatchError if the value is a negative integer, a string
+ *      that is not valid hex, or a type that does not match any accepted form.
+ */
 template <>
 inline std::uint64_t
 getOrThrow(json::Value const& v, xrpl::SField const& field)
@@ -111,7 +227,6 @@ getOrThrow(json::Value const& v, xrpl::SField const& field)
     if (inner.isString())
     {
         auto const s = inner.asString();
-        // parse as hex
         std::uint64_t val = 0;
 
         auto [p, ec] = std::from_chars(s.data(), s.data() + s.size(), val, 16);
@@ -123,6 +238,23 @@ getOrThrow(json::Value const& v, xrpl::SField const& field)
     Throw<JsonTypeMismatchError>(key, "uint64");
 }
 
+/** Extract a raw byte buffer from a JSON object field encoded as a hex string.
+ *
+ *  Delegates to `getOrThrow<std::string>` to fetch the raw hex string, then
+ *  decodes it with `strUnHex`.  A decode failure (e.g., odd length, non-hex
+ *  characters) throws `JsonTypeMismatchError`.
+ *
+ *  @note There is a conceptual mismatch between `xrpl::Buffer` (raw bytes) and
+ *      the `STBlob` wire type.  This specialization bridges that gap for fields
+ *      like `sfSignature` when deserializing witness-server JSON.
+ *
+ *  @param v The JSON object to read from.
+ *  @param field The SField identifying the key to look up.
+ *  @return The decoded byte buffer.
+ *  @throws JsonMissingKeyError if the key is absent.
+ *  @throws JsonTypeMismatchError if the value is not a string or contains
+ *      invalid hex data.
+ */
 template <>
 inline xrpl::Buffer
 getOrThrow(json::Value const& v, xrpl::SField const& field)
@@ -137,7 +269,24 @@ getOrThrow(json::Value const& v, xrpl::SField const& field)
     Throw<JsonTypeMismatchError>(field.getJsonName(), "Buffer");
 }
 
-// This function may be used by external projects (like the witness server).
+/** Extract a typed value from a JSON object, returning `std::nullopt` on any
+ *  error.
+ *
+ *  Wraps `getOrThrow<T>` in a catch-all handler so that a missing key, a type
+ *  mismatch, or any other exception simply yields `std::nullopt`.  The
+ *  catch-all is intentional: the caller's only question is whether the field is
+ *  present and valid, not which specific error occurred.
+ *
+ *  @note This function is part of the public API consumed by external projects
+ *      such as the witness server, which runs outside the rippled process and
+ *      needs to parse XRPL JSON payloads without depending on rippled internals.
+ *
+ *  @tparam T The target C++ type.  Must have a `getOrThrow` specialization.
+ *  @param v The JSON object to read from.
+ *  @param field The SField identifying the key to look up.
+ *  @return The extracted value, or `std::nullopt` if the field is absent or
+ *      cannot be decoded as `T`.
+ */
 template <class T>
 std::optional<T>
 getOptional(json::Value const& v, xrpl::SField const& field)
diff --git a/include/xrpl/protocol/jss.h b/include/xrpl/protocol/jss.h
index 8a2a112542..f33b272c6b 100644
--- a/include/xrpl/protocol/jss.h
+++ b/include/xrpl/protocol/jss.h
@@ -1,26 +1,80 @@
+/** @file
+ *  Centralized registry of every JSON key name used in the XRPL rippled
+ *  implementation.
+ *
+ *  Rather than scattering string literals across hundreds of translation
+ *  units, this header declares each key exactly once as a
+ *  `constexpr json::StaticString` inside `xrpl::jss`.  Any code that
+ *  builds or inspects a `json::Value` — RPC handlers, ledger serializers,
+ *  transaction processors, network-operation code — includes this header
+ *  and writes `jss::account_data` instead of the raw string literal
+ *  `"account_data"`.
+ *
+ *  ## Naming conventions
+ *
+ *  - **PascalCase** names (`Account`, `Amount`, `TransactionType`, …) are
+ *    canonical transaction and ledger-entry field names defined by the XRPL
+ *    wire protocol.  Their casing is part of the protocol specification.
+ *  - **snake_case** names (`account_data`, `ledger_index`, …) belong to the
+ *    RPC API layer — the JSON objects exchanged over HTTP or WebSocket.
+ *
+ *  ## Trailing comment legend
+ *
+ *  Each declaration carries a compact trailing comment:
+ *  - `in:`    — an RPC handler reads this field from its input `json::Value`
+ *  - `out:`   — an RPC handler writes this field into its response
+ *  - `field:` — a protocol-level field of a transaction or ledger entry
+ *  - `RPC:`   — part of the RPC request/response envelope
+ *  - `error:` — part of the standard error-response shape
+ *
+ *  ## ODR safety
+ *
+ *  Every declaration uses `constexpr`, giving each variable internal
+ *  linkage in C++17 and later.  Including this header from many `.cpp`
+ *  files does not violate the One Definition Rule.
+ *
+ *  ## Transaction and ledger-entry names
+ *
+ *  The tail of the file uses X-macros to derive `jss::Payment`,
+ *  `jss::EscrowCreate`, `jss::Offer`, and every other transaction or
+ *  ledger-entry type name directly from the canonical macro tables in
+ *  `detail/transactions.macro` and `detail/ledger_entries.macro`.
+ *  Adding a new type to those tables automatically registers its name
+ *  here — the registry stays in sync by construction.
+ */
 #pragma once
 
 #include <xrpl/json/json_value.h>
 
+/** Centralized registry of every JSON key name used in the XRPL rippled
+ *  implementation.
+ *
+ *  Each identifier is a `constexpr json::StaticString` wrapping a
+ *  string literal from the binary's read-only data segment.  Indexing a
+ *  `json::Value` with a `StaticString` stores only the pointer — no heap
+ *  allocation — because the library knows the pointed-to string has static
+ *  lifetime.  This makes the efficient path the default for all named
+ *  fields.
+ *
+ *  @see jss.h for the full list of constants and their trailing comments.
+ */
 namespace xrpl::jss {
 
 // NOLINTBEGIN(readability-identifier-naming)
-// JSON static strings
 
+/** Declares a `constexpr json::StaticString` whose identifier and string
+ *  value are identical.
+ *
+ *  The `#x` stringification ensures the C++ name and the JSON key can never
+ *  silently diverge: renaming the identifier is a compile error at every
+ *  usage site.  The macro is `#undef`-ed at the end of the namespace block
+ *  so it does not leak into surrounding translation-unit scope.
+ *
+ *  @param x An unquoted C++ identifier that becomes both the variable name
+ *      and the underlying JSON key string.
+ */
 #define JSS(x) constexpr ::json::StaticString x(#x)
 
-/* These "StaticString" field names are used instead of string literals to
-   optimize the performance of accessing properties of json::Value objects.
-
-   Most strings have a trailing comment. Here is the legend:
-
-   in: Read by the given RPC handler from its `json::Value` parameter.
-   out: Assigned by the given RPC handler in the `json::Value` it returns.
-   field: A field of at least one type of transaction.
-   RPC: Common properties of RPC requests and responses.
-   error: Common properties of RPC error responses.
-*/
-
 JSS(AL_size);                     // out: GetCounts
 JSS(AL_hit_rate);                 // out: GetCounts
 JSS(AcceptedCredentials);         // out: AccountObjects
@@ -678,6 +732,12 @@ JSS(warnings);                    // out: server_info, server_state
 JSS(workers);                     //
 JSS(write_load);                  // out: GetCounts
 
+// --- X-macro expansion: transaction and ledger-entry type names ---
+// Redefines TRANSACTION and LEDGER_ENTRY momentarily to emit a JSS()
+// declaration for each type name registered in the canonical macro tables.
+// Adding a new entry to transactions.macro or ledger_entries.macro
+// automatically registers its name here — no manual update required.
+
 #pragma push_macro("TRANSACTION")
 #undef TRANSACTION
 
@@ -693,6 +753,10 @@ JSS(write_load);                  // out: GetCounts
 #pragma push_macro("LEDGER_ENTRY_DUPLICATE")
 #undef LEDGER_ENTRY_DUPLICATE
 
+// LEDGER_ENTRY emits both the internal name and the rpcName alias.
+// LEDGER_ENTRY_DUPLICATE emits only the rpcName to avoid re-declaring
+// the identifier when a single type has two registered names (e.g.,
+// DepositPreauth appears as both a transaction type and a ledger entry).
 #define LEDGER_ENTRY(tag, value, name, rpcName, ...) \
     JSS(name);                                       \
     JSS(rpcName);
diff --git a/include/xrpl/protocol/messages.h b/include/xrpl/protocol/messages.h
index e6654cc183..bb97c82548 100644
--- a/include/xrpl/protocol/messages.h
+++ b/include/xrpl/protocol/messages.h
@@ -1,12 +1,35 @@
 #pragma once
 
-// Some versions of protobuf generate code that will produce errors during
-// compilation. See https://github.com/google/protobuf/issues/549 for more
-// details. We work around this by undefining this macro.
-//
+/** @file
+ *  Safe include shim for the XRPL peer-to-peer protobuf definitions.
+ *
+ *  All code that needs access to the XRPL wire-protocol types (the
+ *  `protocol::MessageType` enum, `TMTransaction`, `TMProposeSet`,
+ *  `TMValidation`, `TMSquelch`, and the rest of the peer message
+ *  hierarchy) must include this header rather than
+ *  `<xrpl/proto/xrpl.pb.h>` directly.  The indirection exists to
+ *  resolve a macro conflict that would otherwise produce cryptic build
+ *  failures on affected platforms.
+ *
+ *  Some versions of `protoc` emit C++ that uses `TYPE_BOOL` as a plain
+ *  identifier.  Certain platform headers (notably parts of the Windows
+ *  SDK) define `TYPE_BOOL` as a preprocessor macro, so when
+ *  `xrpl.pb.h` is compiled in a translation unit where that macro is
+ *  live the preprocessor expands it mid-compilation and corrupts the
+ *  generated symbol names.  The `#ifdef` guard before the `#undef` is
+ *  deliberate: it keeps the file a no-op on platforms that never define
+ *  the macro, avoiding compilers that warn on `#undef` of an undefined
+ *  name.
+ *
+ *  @note The `TYPE_BOOL` workaround is technical debt.  It should be
+ *      removed once the project upgrades to a `protoc` version that no
+ *      longer generates code conflicting with that macro name.
+ *
+ *  @see https://github.com/google/protobuf/issues/549
+ */
+
 // TODO: Remove this after the protoc we use is upgraded to not generate
 //       code that conflicts with the TYPE_BOOL macro.
-
 #ifdef TYPE_BOOL
 #undef TYPE_BOOL
 #endif
diff --git a/include/xrpl/protocol/nft.h b/include/xrpl/protocol/nft.h
index ce73e244c1..bd820a924c 100644
--- a/include/xrpl/protocol/nft.h
+++ b/include/xrpl/protocol/nft.h
@@ -1,3 +1,16 @@
+/** @file
+ *  Binary layout and field accessors for XRPL NFToken identifiers.
+ *
+ *  Every `NFTokenID` on the ledger is a 256-bit big-endian structure that
+ *  packs six fields: flags (2 bytes), transfer fee (2 bytes), issuer
+ *  AccountID (20 bytes), ciphered taxon (4 bytes), and serial number
+ *  (4 bytes). This file is the single source of truth for that layout;
+ *  all other subsystems that need to inspect a token ID call the accessors
+ *  defined here rather than duplicating the byte-offset arithmetic.
+ *
+ *  @see nftPageMask.h for the `kPAGE_MASK` constant that isolates the low
+ *      96 bits used as the NFTokenPage sort key.
+ */
 #pragma once
 
 #include <xrpl/basics/base_uint.h>
@@ -11,30 +24,84 @@
 
 namespace xrpl::nft {
 
-// Separate taxons from regular integers.
+/** Phantom type tag that makes `Taxon` a distinct type from plain integers.
+ *
+ *  This empty struct exists solely to instantiate `TaggedInteger` so that
+ *  the compiler rejects accidental integer/taxon mixups at call sites where
+ *  taxon and serial number (both `uint32_t` underneath) appear side by side.
+ */
 struct TaxonTag
 {
 };
+
+/** Strongly-typed wrapper for an NFT taxon value.
+ *
+ *  A taxon is an issuer-assigned 32-bit category label embedded in every
+ *  NFTokenID. The compiler distinguishes `Taxon` from raw `uint32_t`, so a
+ *  serial number cannot be passed where a taxon is expected. Use `toTaxon()`
+ *  and `toUInt32()` to cross the type boundary explicitly.
+ */
 using Taxon = TaggedInteger<std::uint32_t, TaxonTag>;
 
+/** Convert a plain `uint32_t` to a `Taxon`.
+ *
+ *  @param i The raw taxon value obtained from a transaction field or other
+ *      integer source.
+ *  @return A `Taxon` wrapping `i`.
+ */
 inline Taxon
 toTaxon(std::uint32_t i)
 {
     return static_cast<Taxon>(i);
 }
 
+/** Convert a `Taxon` to a plain `uint32_t`.
+ *
+ *  @param t The taxon to unwrap.
+ *  @return The underlying integer value.
+ */
 inline std::uint32_t
 toUInt32(Taxon t)
 {
     return static_cast<std::uint32_t>(t);
 }
 
+/** The issuer may burn the token even when it is held by another account. */
 constexpr std::uint16_t const kFLAG_BURNABLE = 0x0001;
+
+/** The token may only be bought or sold for XRP, not IOUs. */
 constexpr std::uint16_t const kFLAG_ONLY_XRP = 0x0002;
+
+/** Accepting a transfer of this token may open trust lines on the recipient's
+ *  account to receive IOU royalty payments.
+ *
+ *  @note Under amendment `fixEnforceNFTokenTrustline`, transfers with a
+ *      non-zero transfer fee denominated in an IOU are rejected with
+ *      `tecNO_LINE` unless this flag is set or the NFT issuer is also the
+ *      IOU issuer.
+ */
 constexpr std::uint16_t const kFLAG_CREATE_TRUST_LINES = 0x0004;
+
+/** The token may be transferred to accounts other than the issuer. */
 constexpr std::uint16_t const kFLAG_TRANSFERABLE = 0x0008;
+
+/** The token's URI may be updated after minting via `NFTokenModify`.
+ *
+ *  Because flags are baked into bytes 0–1 of the token ID, this flag — like
+ *  all flags — is immutable after minting. `NFTokenModify` reads it directly
+ *  from the token ID via `getFlags()` and returns `tecNO_PERMISSION` if it
+ *  is absent.
+ */
 constexpr std::uint16_t const kFLAG_MUTABLE = 0x0010;
 
+/** Extract the flags field from an NFTokenID.
+ *
+ *  Reads bytes 0–1 (big-endian) of `id` and converts to host byte order.
+ *  Flags are immutable after minting because they are part of the token ID.
+ *
+ *  @param id A 256-bit NFTokenID as stored on the ledger.
+ *  @return The 16-bit flags bitmask; compare against the `kFLAG_*` constants.
+ */
 inline std::uint16_t
 getFlags(uint256 const& id)
 {
@@ -43,6 +110,16 @@ getFlags(uint256 const& id)
     return boost::endian::big_to_native(flags);
 }
 
+/** Extract the transfer fee from an NFTokenID.
+ *
+ *  Reads bytes 2–3 (big-endian) of `id` and converts to host byte order.
+ *  The fee is expressed in basis points; 50000 represents 50%. Use
+ *  `nft::transferFeeAsRate()` (in `Rate.h`) to convert to a `Rate` suitable
+ *  for `multiply()`.
+ *
+ *  @param id A 256-bit NFTokenID as stored on the ledger.
+ *  @return Transfer fee in basis points (0–50000).
+ */
 inline std::uint16_t
 getTransferFee(uint256 const& id)
 {
@@ -51,6 +128,15 @@ getTransferFee(uint256 const& id)
     return boost::endian::big_to_native(fee);
 }
 
+/** Extract the serial number from an NFTokenID.
+ *
+ *  Reads bytes 28–31 (big-endian) of `id` and converts to host byte order.
+ *  The serial is the issuer's mint sequence at the time the token was created
+ *  and is unique within a single issuer's token space.
+ *
+ *  @param id A 256-bit NFTokenID as stored on the ledger.
+ *  @return The 32-bit serial number.
+ */
 inline std::uint32_t
 getSerial(uint256 const& id)
 {
@@ -59,6 +145,38 @@ getSerial(uint256 const& id)
     return boost::endian::big_to_native(seq);
 }
 
+/** Compute the ciphered taxon stored in an NFTokenID for a given mint.
+ *
+ *  To prevent tokens minted under the same taxon from clustering in the same
+ *  `NFTokenPage` objects (a ledger-write hotspot), the stored taxon is XORed
+ *  with a scramble value derived from the mint sequence number via a Linear
+ *  Congruential Generator:
+ *
+ *  @code
+ *  ciphered = taxon ^ (384160001 * tokenSeq + 2459)
+ *  @endcode
+ *
+ *  The LCG multiplier (384160001 ≡ 1 mod 4) and addend (2459, odd) satisfy
+ *  the Hull-Dobell theorem, guaranteeing a full period over 2³² when
+ *  arithmetic wraps naturally on `uint32_t`. Because `tokenSeq` advances
+ *  monotonically and the issuer cannot choose it freely, successive mints
+ *  under the same taxon land in very different positions in the page sort
+ *  order, distributing load.
+ *
+ *  Since XOR is its own inverse, calling this function a second time with the
+ *  stored ciphered value recovers the original taxon — no separate decipher
+ *  function is needed. `getTaxon()` relies on this property.
+ *
+ *  @param tokenSeq The issuer's account sequence at the time of minting
+ *      (the serial number that will be embedded in the token ID).
+ *  @param taxon The issuer-supplied taxon to cipher.
+ *  @return The ciphered taxon value to embed in bytes 24–27 of the token ID.
+ *
+ *  @note **Protocol-stable constants.** The LCG parameters 384160001 and
+ *      2459 are embedded in every NFTokenID ever minted. Changing them is
+ *      a consensus-breaking change that requires an amendment and a way to
+ *      distinguish token IDs generated under the old scheme.
+ */
 inline Taxon
 cipheredTaxon(std::uint32_t tokenSeq, Taxon taxon)
 {
@@ -83,6 +201,16 @@ cipheredTaxon(std::uint32_t tokenSeq, Taxon taxon)
     return taxon ^ toTaxon(((384160001 * tokenSeq) + 2459));
 }
 
+/** Extract and decode the taxon from an NFTokenID.
+ *
+ *  Reads bytes 24–27 (big-endian) to obtain the stored ciphered taxon, then
+ *  deciphers it by calling `cipheredTaxon()` a second time with the serial
+ *  number from bytes 28–31. Because XOR is its own inverse, this cancels the
+ *  original scramble and returns the issuer-supplied taxon value.
+ *
+ *  @param id A 256-bit NFTokenID as stored on the ledger.
+ *  @return The original issuer-assigned taxon, not the ciphered value.
+ */
 inline Taxon
 getTaxon(uint256 const& id)
 {
@@ -95,6 +223,14 @@ getTaxon(uint256 const& id)
     return cipheredTaxon(getSerial(id), toTaxon(taxon));
 }
 
+/** Extract the issuer AccountID from an NFTokenID.
+ *
+ *  Reads bytes 4–23 of `id`, which hold the 20-byte issuer address in
+ *  big-endian order as packed by `NFTokenMint::createNFTokenID()`.
+ *
+ *  @param id A 256-bit NFTokenID as stored on the ledger.
+ *  @return The 20-byte AccountID of the token's issuer.
+ */
 inline AccountID
 getIssuer(uint256 const& id)
 {
diff --git a/include/xrpl/protocol/nftPageMask.h b/include/xrpl/protocol/nftPageMask.h
index d679c319fa..cf31f53390 100644
--- a/include/xrpl/protocol/nftPageMask.h
+++ b/include/xrpl/protocol/nftPageMask.h
@@ -6,8 +6,35 @@
 
 namespace xrpl::nft {
 
-// NFT directory pages order their contents based only on the low 96 bits of
-// the NFToken value.  This mask provides easy access to the necessary mask.
+/** Bitmask that separates the owner-identity region of an NFToken page key
+ *  from its token-ordering region.
+ *
+ *  Every `NFTokenID` encodes the issuing `AccountID` in its high 160 bits and
+ *  token-specific data (taxon + sequence) in its low 96 bits. Ledger page keys
+ *  for `ltNFTOKEN_PAGE` SLEs fuse those two regions into a single `uint256`.
+ *  `kPAGE_MASK` — 96 bits of `1` in the least-significant position, 160 bits
+ *  of `0` above — is the canonical tool for splitting them:
+ *
+ *  - `token & kPAGE_MASK`   → low 96 bits (token-ordering portion)
+ *  - `key   & ~kPAGE_MASK`  → high 160 bits (owner AccountID portion)
+ *
+ *  Typical uses:
+ *  - **Page key construction** (`Indexes.cpp`): `(k.key & ~kPAGE_MASK) + (token & kPAGE_MASK)`
+ *  - **Max-page sentinel** (`keylet::nftpage_max`): initialize the full `uint256`
+ *    to `kPAGE_MASK` (all-ones in the low 96 bits), then overwrite the high
+ *    bytes with the owner's `AccountID` to form the lexicographically largest
+ *    page key for that owner.
+ *  - **RPC pagination** (`AccountNFTs.cpp`, `AccountObjects.cpp`): validate
+ *    that a client-supplied marker or `entryIndex` belongs to the correct page.
+ *  - **Sort-order comparisons** (`NFTokenHelpers.cpp`): tokens with different
+ *    low-96-bit values belong to different pages.
+ *  - **Invariant checks** (`NFTInvariant.cpp`): verify that a page being deleted
+ *    carries the all-ones sentinel in its low 96 bits.
+ *
+ *  @note The value is `constexpr`, resolved entirely at compile time via
+ *      `base_uint`'s `std::string_view` constructor, so including this header
+ *      has no runtime cost and raises no ODR concerns.
+ */
 uint256 constexpr kPAGE_MASK(
     std::string_view("0000000000000000000000000000000000000000ffffffffffffffffffffffff"));
 
diff --git a/include/xrpl/protocol/serialize.h b/include/xrpl/protocol/serialize.h
index 5b84a28b5d..9884ec5025 100644
--- a/include/xrpl/protocol/serialize.h
+++ b/include/xrpl/protocol/serialize.h
@@ -6,7 +6,22 @@
 
 namespace xrpl {
 
-/** Serialize an object to a blob. */
+/** Serialize a protocol object to its canonical wire-format byte sequence.
+ *
+ *  Constructs a `Serializer` pre-reserved to 256 bytes, invokes
+ *  `o.add(s)` to write the object's canonical binary encoding, and returns
+ *  a copy of the accumulated buffer.  The returned `Blob` is independently
+ *  owned by the caller — no lifetime dependency on the transient `Serializer`
+ *  is created.
+ *
+ *  @tparam Object Any type that implements `void add(Serializer&) const` —
+ *      the canonical serialization interface defined by `STBase` and
+ *      honoured by every concrete protocol type (`STTx`, `STLedgerEntry`,
+ *      transaction-metadata objects, etc.).
+ *  @param o The object to serialize.
+ *  @return A `Blob` (`std::vector<uint8_t>`) containing the complete
+ *      wire-format encoding of `o`.
+ */
 template <class Object>
 Blob
 serializeBlob(Object const& o)
@@ -16,7 +31,19 @@ serializeBlob(Object const& o)
     return s.peekData();
 }
 
-/** Serialize an object to a hex string. */
+/** Serialize an `STObject` to an uppercase hex string of its wire encoding.
+ *
+ *  Convenience wrapper around `serializeBlob` + `strHex`, covering the
+ *  common RPC pattern of rendering a transaction, ledger entry, or metadata
+ *  object as a hex string for a JSON response (e.g. `tx_blob`, `meta_blob`,
+ *  `data` fields).  The concrete `STObject` parameter — rather than a
+ *  template — avoids unnecessary instantiation overhead for this
+ *  narrow but frequent use case.
+ *
+ *  @param o The `STObject` (or `STObject`-derived type) to serialize.
+ *  @return An uppercase hex string of the canonical wire encoding of `o`.
+ *  @see serializeBlob
+ */
 inline std::string
 serializeHex(STObject const& o)
 {
diff --git a/include/xrpl/protocol/st.h b/include/xrpl/protocol/st.h
index 61571196f2..dcff09a705 100644
--- a/include/xrpl/protocol/st.h
+++ b/include/xrpl/protocol/st.h
@@ -1,3 +1,36 @@
+/** @file
+ *  Umbrella header for the XRPL Serialized Type (ST) system.
+ *
+ *  Including this header makes the complete ST type vocabulary available in a
+ *  single line. Every type that can appear inside a transaction, ledger entry,
+ *  or consensus message is reachable transitively:
+ *
+ *  - **Field registry** — `SField`, `SOTemplate`, `SOEStyle`, and the full set
+ *    of named fields (`sfAmount`, `sfDestination`, …) via `SField.h`.
+ *  - **Polymorphic root** — `STBase` and the `detail::STVar` small-buffer
+ *    helper via `STBase.h`.
+ *  - **Scalar leaves** — `STInteger<T>` / `STUInt8` … `STUInt64` / `STInt32`
+ *    (`STInteger.h`); `STBitString<Bits>` / `STUInt128` … `STUInt256`
+ *    (`STBitString.h`); `STBlob` (`STBlob.h`); `STAccount` (`STAccount.h`).
+ *  - **Composite containers** — `STObject` with `SOTemplate` enforcement and
+ *    typed proxy accessors (`STObject.h`); `STArray` of inner `STObject`
+ *    values (`STArray.h`); `STVector256` for multi-hash fields (`STVector256.h`).
+ *  - **Domain-specific types** — `STAmount` (XRP drops or IOU amount),
+ *    `STNumber` (high-precision asset-contextual value), `STPathSet` (payment
+ *    path graphs), `STIssue`, `STCurrency`.
+ *  - **High-level protocol objects** — `STTx` (signed transaction with
+ *    cached ID and type), `STLedgerEntry` / `SLE` (keyed ledger state entry),
+ *    `STValidation` (consensus vote with lazy signature cache).
+ *  - **JSON boundary** — `STParsedJSON` for deserializing a `Json::Value` tree
+ *    into an `STObject` or `STArray`.
+ *
+ *  @note Code that works with only one or two ST primitives should prefer the
+ *      individual headers to keep compile-time dependencies minimal. Include
+ *      `st.h` when a translation unit genuinely needs the full protocol-object
+ *      vocabulary (transaction processing, serialization, RPC formatting, etc.).
+ *
+ *  @see STBase.h, STObject.h, STTx.h, STLedgerEntry.h, STValidation.h
+ */
 #pragma once
 
 #include <xrpl/protocol/SField.h>
diff --git a/include/xrpl/protocol/tokens.h b/include/xrpl/protocol/tokens.h
index 125cfe8583..14800d99c6 100644
--- a/include/xrpl/protocol/tokens.h
+++ b/include/xrpl/protocol/tokens.h
@@ -1,3 +1,27 @@
+/** @file
+ *  Public interface for Base58Check encoding and decoding of XRPL
+ *  cryptographic identifiers.
+ *
+ *  Raw byte sequences — account IDs, node keys, seeds — are converted to and
+ *  from the human-readable strings that appear in XRPL transactions and client
+ *  APIs (e.g., `rHb9CJAWyB4rj91VRWn96DkukG4bwdtyTh` for an account address).
+ *
+ *  Every encoded token follows the wire layout:
+ *  @code
+ *    [ type byte (1) ][ raw payload (N) ][ checksum (4) ]
+ *  @endcode
+ *  where the checksum is the first four bytes of SHA-256(SHA-256(type ‖ payload)).
+ *
+ *  Three namespaces expose encoding/decoding:
+ *  - `xrpl::` — public API; dispatches to `b58_fast` on GCC/Clang, `b58_ref`
+ *      on MSVC.
+ *  - `xrpl::b58_ref` — portable O(n²) reference implementation (all compilers).
+ *  - `xrpl::b58_fast` — 10–15× faster implementation using GCC's
+ *      `unsigned __int128`; guarded by `#ifndef _MSC_VER`.
+ *
+ *  @see https://xrpl.org/base58-encodings.html
+ */
+
 #pragma once
 
 #include <xrpl/basics/Expected.h>
@@ -12,91 +36,308 @@
 
 namespace xrpl {
 
+/** Result type for fallible Base58Check codec operations.
+ *
+ *  Holds either a value of type `T` on success, or a `std::error_code`
+ *  (wrapping a `TokenCodecErrc` enumerator) on failure.  Marked
+ *  `[[nodiscard]]` via `Expected` so callers cannot silently ignore errors.
+ *
+ *  @tparam T The success-path value type (e.g., `std::span<std::uint8_t>`).
+ *  @see TokenCodecErrc
+ */
 template <class T>
 using B58Result = Expected<T, std::error_code>;
 
+/** One-byte version prefixes for each XRPL identifier category.
+ *
+ *  The prefix byte is prepended to the raw payload before Base58Check
+ *  encoding.  It causes the resulting string to begin with a
+ *  category-specific letter in the XRPL alphabet — e.g., account addresses
+ *  start with `'r'` and family seeds start with `'s'` — providing a
+ *  recognisable visual cue without decoding.
+ *
+ *  `None` and `FamilyGenerator` are reserved and currently unused; their
+ *  numeric values must not be reassigned to new token categories.
+ *
+ *  @note These values are protocol-stable and must never be changed.  All
+ *      Base58Check-encoded XRPL identifiers in existence carry one of these
+ *      bytes as their first decoded byte.
+ */
 enum class TokenType : std::uint8_t {
-    None = 1,  // unused
-    NodePublic = 28,
-    NodePrivate = 32,
-    AccountID = 0,
-    AccountPublic = 35,
-    AccountSecret = 34,
-    FamilyGenerator = 41,  // unused
-    FamilySeed = 33
+    None = 1,            ///< Reserved; unused.
+    NodePublic = 28,     ///< Validator/peer public key.
+    NodePrivate = 32,    ///< Validator/peer private key.
+    AccountID = 0,       ///< Classic account address (20-byte hash).
+    AccountPublic = 35,  ///< Account public key.
+    AccountSecret = 34,  ///< Account private key.
+    FamilyGenerator = 41, ///< Reserved; unused.
+    FamilySeed = 33      ///< Key-generation seed (16 bytes).
 };
 
+/** Decode a Base58Check string into a typed XRPL value.
+ *
+ *  The overload with no explicit `TokenType` is used when the target type
+ *  `T` carries its own implicit token type (e.g., `parseBase58<AccountID>`).
+ *  The overload that accepts a `TokenType` is used when the type byte must
+ *  be supplied by the caller (e.g., `parseBase58<PublicKey>(TokenType::NodePublic, s)`).
+ *
+ *  No definition is provided in this header.  Explicit template
+ *  specialisations for each concrete XRPL type live alongside that type's
+ *  own implementation (e.g., `AccountID.cpp`, `PublicKey.cpp`).
+ *
+ *  @tparam T The target XRPL type to parse into.
+ *  @param s The Base58Check-encoded string to decode.
+ *  @return The decoded value, or `std::nullopt` if the string is invalid,
+ *      has the wrong token type, or fails its checksum.
+ */
 template <class T>
 [[nodiscard]] std::optional<T>
 parseBase58(std::string const& s);
 
+/** Decode a Base58Check string with an explicit token type into a typed XRPL value.
+ *
+ *  @tparam T The target XRPL type to parse into.
+ *  @param type The expected one-byte token-type prefix.  Decoding fails if
+ *      the decoded prefix does not match.
+ *  @param s The Base58Check-encoded string to decode.
+ *  @return The decoded value, or `std::nullopt` on any error.
+ */
 template <class T>
 [[nodiscard]] std::optional<T>
 parseBase58(TokenType type, std::string const& s);
 
-/** Encode data in Base58Check format using XRPL alphabet
-
-    For details on the format see
-    https://xrpl.org/base58-encodings.html#base58-encodings
-
-    @param type The type of token to encode.
-    @param token Pointer to the data to encode.
-    @param size The size of the data to encode.
-
-    @return the encoded token.
-*/
+/** Encode data in Base58Check format using the XRPL alphabet.
+ *
+ *  Prepends `type` as a one-byte version prefix, appends a 4-byte
+ *  SHA-256(SHA-256(type ‖ data)) checksum, then Base58-encodes the
+ *  concatenation.
+ *
+ *  On non-MSVC platforms this dispatches to `b58_fast::encodeBase58Token`;
+ *  on MSVC it falls back to `b58_ref::encodeBase58Token`.
+ *
+ *  @param type The token category prefix byte.
+ *  @param token Pointer to the raw payload bytes.
+ *  @param size Number of payload bytes.
+ *  @return The Base58Check-encoded string.
+ *
+ *  @see https://xrpl.org/base58-encodings.html
+ */
 [[nodiscard]] std::string
 encodeBase58Token(TokenType type, void const* token, std::size_t size);
 
+/** Decode a Base58Check string and validate its token type and checksum.
+ *
+ *  Returns the raw payload bytes (without the type prefix or checksum) as a
+ *  string, or an empty string if the input is malformed, the token type does
+ *  not match `type`, or the checksum fails.
+ *
+ *  On non-MSVC platforms this dispatches to `b58_fast::decodeBase58Token`;
+ *  on MSVC it falls back to `b58_ref::decodeBase58Token`.
+ *
+ *  @param s The Base58Check-encoded string to decode.
+ *  @param type The expected one-byte token-type prefix.
+ *  @return The raw decoded payload, or an empty string on any error.
+ *  @note Error detail is lost on failure; prefer the span-based
+ *      `b58_fast::decodeBase58Token` overload where typed errors matter.
+ */
 [[nodiscard]] std::string
 decodeBase58Token(std::string const& s, TokenType type);
 
+/** Portable O(n²) reference implementation of the XRPL Base58Check codec.
+ *
+ *  Adapted from Bitcoin Core.  Performs direct base-256 ↔ base-58 digit
+ *  conversion without any compiler extensions, making it available on all
+ *  platforms including MSVC.  For large payloads the O(n²) cost is
+ *  measurable; prefer `b58_fast` where available.
+ */
 namespace b58_ref {
-// The reference version does not use gcc extensions (int128 in particular)
+
+/** Encode data in Base58Check format using the XRPL alphabet.
+ *
+ *  Portable reference implementation; does not use `__int128` or other
+ *  compiler extensions.
+ *
+ *  @param type The token category prefix byte.
+ *  @param token Pointer to the raw payload bytes.
+ *  @param size Number of payload bytes.
+ *  @return The Base58Check-encoded string.
+ */
 [[nodiscard]] std::string
 encodeBase58Token(TokenType type, void const* token, std::size_t size);
 
+/** Decode a Base58Check string and validate its token type and checksum.
+ *
+ *  Portable reference implementation.
+ *
+ *  @param s The Base58Check-encoded string to decode.
+ *  @param type The expected one-byte token-type prefix.
+ *  @return The raw decoded payload, or an empty string on any error.
+ */
 [[nodiscard]] std::string
 decodeBase58Token(std::string const& s, TokenType type);
 
+/** Raw base-conversion primitives, exposed for unit testing only.
+ *
+ *  These functions operate on byte spans without any XRPL framing (no
+ *  token-type prefix and no checksum), allowing the numeric conversion to
+ *  be verified in isolation.
+ */
 namespace detail {
-// Expose detail functions for unit tests only
+
+/** Encode raw bytes into a Base58 string using the XRPL alphabet.
+ *
+ *  Performs the O(n²) base-256 → base-58 conversion.  No token-type prefix
+ *  or checksum is applied.
+ *
+ *  @param message Pointer to the input bytes.
+ *  @param size Number of input bytes.
+ *  @param temp Caller-supplied scratch buffer; must be at least `size` bytes.
+ *  @param tempSize Size of the scratch buffer in bytes.
+ *  @return The Base58-encoded string.
+ *  @note Exposed for unit testing only; production code should call
+ *      `b58_ref::encodeBase58Token`.
+ */
 std::string
 encodeBase58(void const* message, std::size_t size, void* temp, std::size_t tempSize);
 
+/** Decode a raw Base58 string into bytes using the XRPL alphabet.
+ *
+ *  Performs the base-58 → base-256 conversion without validating any token
+ *  prefix or checksum.
+ *
+ *  @param s The Base58-encoded string to decode.
+ *  @return The decoded bytes, or an empty string if any character is outside
+ *      the XRPL Base58 alphabet.
+ *  @note Exposed for unit testing only; production code should call
+ *      `b58_ref::decodeBase58Token`.
+ */
 std::string
 decodeBase58(std::string const& s);
+
 }  // namespace detail
 }  // namespace b58_ref
 
 #ifndef _MSC_VER
+/** 10–15× faster Base58Check codec using GCC/Clang's `unsigned __int128`.
+ *
+ *  The algorithm routes through an intermediate base-58^10 representation.
+ *  `58^10 = 430,804,206,899,405,824` fits in a 64-bit register, so groups of
+ *  ten base-58 digits can be processed as a single 64-bit word.  The
+ *  expensive multi-precision arithmetic is then performed on far fewer, larger
+ *  coefficients.  The three-stage pipeline is:
+ *  @code
+ *    base 58 → base 58^10 → base 2^64 → base 2^8
+ *  @endcode
+ *  Conversions between bases that are powers of one another are trivial
+ *  concatenations; only the middle hop requires multi-precision work.
+ *
+ *  The span-based overloads avoid heap allocation in the hot path.  The
+ *  `std::string`-returning overloads are provided for API compatibility but
+ *  each require one allocation.
+ *
+ *  @note Not available on MSVC, which lacks `unsigned __int128`.
+ */
 namespace b58_fast {
-// Use the fast version (10-15x faster) is using gcc extensions (int128 in
-// particular)
+
+/** Encode data in Base58Check format into a caller-supplied buffer.
+ *
+ *  Prepends `tokenType` as a one-byte version prefix, appends a 4-byte
+ *  checksum, and Base58-encodes the result into `out`.  No heap allocation.
+ *
+ *  @param tokenType The token category prefix byte.
+ *  @param input The raw payload bytes to encode.
+ *  @param out Buffer to receive the Base58Check-encoded bytes.  Must be
+ *      large enough to hold the encoded output.
+ *  @return On success, a sub-span of `out` covering the encoded bytes.
+ *      On failure, a `std::error_code` wrapping a `TokenCodecErrc` value
+ *      (e.g., `OutputTooSmall` if `out` is insufficient).
+ */
 [[nodiscard]] B58Result<std::span<std::uint8_t>>
 encodeBase58Token(
     TokenType tokenType,
     std::span<std::uint8_t const> input,
     std::span<std::uint8_t> out);
 
+/** Decode a Base58Check string into a caller-supplied buffer.
+ *
+ *  Validates the token-type prefix and 4-byte checksum before writing to
+ *  `outBuf`.  No heap allocation.
+ *
+ *  @param type The expected one-byte token-type prefix.
+ *  @param s The Base58Check-encoded string to decode.
+ *  @param outBuf Buffer to receive the raw decoded payload bytes.  Must be
+ *      large enough for the payload (payload size = decoded size − 5).
+ *  @return On success, a sub-span of `outBuf` covering the decoded bytes.
+ *      On failure, a `std::error_code` wrapping a `TokenCodecErrc`
+ *      (e.g., `MismatchedTokenType`, `MismatchedChecksum`, `OutputTooSmall`,
+ *      or `BadB58Character`).
+ */
 [[nodiscard]] B58Result<std::span<std::uint8_t>>
 decodeBase58Token(TokenType type, std::string_view s, std::span<std::uint8_t> outBuf);
 
-// This interface matches the old interface, but requires additional allocation
+/** Encode data in Base58Check format, returning a `std::string`.
+ *
+ *  Legacy-compatible overload matching the `b58_ref` API.  Requires one
+ *  heap allocation for the returned string.
+ *
+ *  @param type The token category prefix byte.
+ *  @param token Pointer to the raw payload bytes.
+ *  @param size Number of payload bytes.
+ *  @return The Base58Check-encoded string.
+ */
 [[nodiscard]] std::string
 encodeBase58Token(TokenType type, void const* token, std::size_t size);
 
-// This interface matches the old interface, but requires additional allocation
+/** Decode a Base58Check string, returning a `std::string`.
+ *
+ *  Legacy-compatible overload matching the `b58_ref` API.  Requires one
+ *  heap allocation for the returned string.  Error detail is lost on
+ *  failure; prefer the span-based overload where typed errors matter.
+ *
+ *  @param s The Base58Check-encoded string to decode.
+ *  @param type The expected one-byte token-type prefix.
+ *  @return The raw decoded payload, or an empty string on any error.
+ */
 [[nodiscard]] std::string
 decodeBase58Token(std::string const& s, TokenType type);
 
+/** Raw base-conversion primitives, exposed for unit testing only.
+ *
+ *  These functions perform the numeric base conversion without any XRPL
+ *  framing (no token-type prefix and no checksum), enabling isolated testing
+ *  of the fast-path arithmetic.
+ */
 namespace detail {
-// Expose detail functions for unit tests only
+
+/** Convert big-endian base-256 bytes to a big-endian Base58 byte sequence.
+ *
+ *  Uses the three-stage `b256 → b58^10 → b2^64 → b58` pipeline.  No token
+ *  prefix or checksum is applied.
+ *
+ *  @param input The big-endian base-256 bytes to convert.
+ *  @param out Buffer to receive the Base58-encoded bytes.
+ *  @return On success, a sub-span of `out` covering the result.
+ *      On failure, a `std::error_code` (e.g., `OutputTooSmall`).
+ *  @note Exposed for unit testing only.
+ */
 B58Result<std::span<std::uint8_t>>
 b256ToB58Be(std::span<std::uint8_t const> input, std::span<std::uint8_t> out);
 
+/** Convert a big-endian Base58 byte sequence to big-endian base-256 bytes.
+ *
+ *  Uses the three-stage `b58 → b58^10 → b2^64 → b256` pipeline.  No token
+ *  prefix or checksum validation is performed.
+ *
+ *  @param input The Base58-encoded string to decode.
+ *  @param out Buffer to receive the big-endian base-256 bytes.
+ *  @return On success, a sub-span of `out` covering the result.
+ *      On failure, a `std::error_code` (e.g., `BadB58Character`,
+ *      `OutputTooSmall`, or `OverflowAdd`).
+ *  @note Exposed for unit testing only.
+ */
 B58Result<std::span<std::uint8_t>>
 b58ToB256Be(std::string_view input, std::span<std::uint8_t> out);
+
 }  // namespace detail
 
 }  // namespace b58_fast
diff --git a/include/xrpl/tx/transactors/nft/NFTokenCreateOffer.h b/include/xrpl/tx/transactors/nft/NFTokenCreateOffer.h
index cedb680bb1..7841979179 100644
--- a/include/xrpl/tx/transactors/nft/NFTokenCreateOffer.h
+++ b/include/xrpl/tx/transactors/nft/NFTokenCreateOffer.h
@@ -4,6 +4,24 @@
 
 namespace xrpl {
 
+/**
+ * Transactor for `ttNFTOKEN_CREATE_OFFER` (type code 27).
+ *
+ * Places a buy or sell offer for an NFT into the ledger. When `tfSellNFToken`
+ * is set the submitter is offering to sell an NFT they own; when unset they
+ * are offering to buy an NFT currently held by the account named in
+ * `sfOwner`. The distinction drives which account's NFT directory is searched
+ * in `preclaim` and which reserve is charged in `doApply`.
+ *
+ * All three pipeline phases delegate almost entirely to free functions in
+ * `NFTokenHelpers` (`tokenOfferCreatePreflight`, `tokenOfferCreatePreclaim`,
+ * `tokenOfferCreateApply`) that are shared with `NFTokenMint`, which can
+ * create a sell offer atomically at mint time. This sharing ensures the two
+ * transactors cannot drift apart on offer-creation rules.
+ *
+ * @note `ConsequencesFactory{Normal}` means a fee is charged on failure; this
+ *     transaction does not block later transactions from the same account.
+ */
 class NFTokenCreateOffer : public Transactor
 {
 public:
@@ -13,24 +31,98 @@ public:
     {
     }
 
+    /**
+     * Returns the flag mask for this transaction type (`tfNFTokenCreateOfferMask`).
+     *
+     * The framework passes this mask to `preflight1`, which rejects any
+     * transaction whose flags include bits not defined for
+     * `ttNFTOKEN_CREATE_OFFER`. This guards against clients setting
+     * unrecognized bits that could acquire meaning under future amendments.
+     */
     static std::uint32_t
     getFlagsMask(PreflightContext const& ctx);
 
+    /**
+     * Stateless structural validation — no ledger access.
+     *
+     * Extracts NFT flags embedded in `sfNFTokenID` (e.g. `lsfBurnable`,
+     * `lsfOnlyXRP`, `lsfTransferable`) then delegates to
+     * `nft::tokenOfferCreatePreflight()`, which validates the offer amount,
+     * optional destination and expiration, ownership rules, and transaction
+     * flags.
+     *
+     * @return `tesSUCCESS` if the transaction is structurally valid; a
+     *     `tem*` code otherwise.
+     */
     static NotTEC
     preflight(PreflightContext const& ctx);
 
+    /**
+     * Read-only ledger checks after signature verification.
+     *
+     * Performs two checks before delegating to the shared helper:
+     *
+     * 1. **Expiration guard** — rejects with `tecEXPIRED` if the offer's
+     *    `sfExpiration` has already passed the current ledger close time.
+     *    This cannot be done in `preflight` because close time is ledger
+     *    state.
+     * 2. **Token ownership** — for sell offers, confirms `sfAccount` holds
+     *    the NFT; for buy offers, confirms `sfOwner` holds it. Returns
+     *    `tecNO_ENTRY` if the token is absent from the expected directory.
+     *
+     * After these two checks, delegates to
+     * `nft::tokenOfferCreatePreclaim()` for business-logic validation
+     * (transfer fee eligibility, destination account existence, etc.).
+     *
+     * @return `tesSUCCESS` on success; `tecEXPIRED`, `tecNO_ENTRY`, or
+     *     another `tec*`/`ter*` code on failure.
+     */
     static TER
     preclaim(PreclaimContext const& ctx);
 
+    /**
+     * Creates the `NFTokenOffer` ledger object and inserts it into the
+     * appropriate buy or sell directory.
+     *
+     * Delegates entirely to `nft::tokenOfferCreateApply()`, passing all
+     * transaction fields plus `preFeeBalance_` (the submitter's XRP balance
+     * before fee deduction) for reserve checking.
+     *
+     * @return `tesSUCCESS` on success; a `tec*` code if the offer object
+     *     cannot be created (e.g. `tecINSUFFICIENT_RESERVE`).
+     */
     TER
     doApply() override;
 
+    /**
+     * Per-entry invariant visitor hook.
+     *
+     * No transaction-specific invariants are currently enforced; this is a
+     * no-op placeholder for future work.
+     *
+     * @param isDelete `true` if the entry is being deleted.
+     * @param before    The SLE state before the transaction, or `nullptr`.
+     * @param after     The SLE state after the transaction, or `nullptr`.
+     */
     void
     visitInvariantEntry(
         bool isDelete,
         std::shared_ptr<SLE const> const& before,
         std::shared_ptr<SLE const> const& after) override;
 
+    /**
+     * Post-execution invariant finalizer.
+     *
+     * No transaction-specific invariants are currently enforced; always
+     * returns `true`. Placeholder for future work.
+     *
+     * @param tx     The transaction being applied.
+     * @param result The `TER` code produced by `doApply`.
+     * @param fee    The fee charged, in drops.
+     * @param view   The ledger view after the transaction.
+     * @param j      Journal for diagnostic logging.
+     * @return `true` — all invariants pass (none are currently defined).
+     */
     [[nodiscard]] bool
     finalizeInvariants(
         STTx const& tx,
diff --git a/include/xrpl/tx/transactors/nft/NFTokenMint.h b/include/xrpl/tx/transactors/nft/NFTokenMint.h
index 43beb47179..b71ba3cfcd 100644
--- a/include/xrpl/tx/transactors/nft/NFTokenMint.h
+++ b/include/xrpl/tx/transactors/nft/NFTokenMint.h
@@ -6,6 +6,24 @@
 
 namespace xrpl {
 
+/** Transactor for the `NFTokenMint` transaction type.
+ *
+ *  Creates a new non-fungible token on the XRP Ledger and records it in the
+ *  issuer's on-ledger NFToken page structure. Optionally, in the same atomic
+ *  step, it can create an initial sell offer for the newly minted token when
+ *  `featureNFTokenMintOffer` is active and the transaction includes offer
+ *  fields (`sfAmount`, optionally `sfDestination` and `sfExpiration`).
+ *
+ *  The offer-creation helpers (`nft::tokenOfferCreatePreflight`,
+ *  `nft::tokenOfferCreatePreclaim`, `nft::tokenOfferCreateApply`) are shared
+ *  with `NFTokenCreateOffer` to keep offer-validation logic consistent whether
+ *  an offer is created standalone or bundled into a mint. The embedded-offer
+ *  path always creates a sell offer — atomic mint-and-buy-offer is not
+ *  supported.
+ *
+ *  @note `kCONSEQUENCES_FACTORY` is `Normal`; minting imposes no extraordinary
+ *      sequencing constraints on other transactions from the same account.
+ */
 class NFTokenMint : public Transactor
 {
 public:
@@ -15,27 +33,137 @@ public:
     {
     }
 
+    /** Gate the embedded-offer sub-feature during preflight.
+     *
+     *  Returns `false` (blocking the transaction) if the transaction contains
+     *  any of `sfAmount`, `sfDestination`, or `sfExpiration` — the fields used
+     *  to bundle an initial sell offer — and `featureNFTokenMintOffer` is not
+     *  enabled on the current network. Without this guard a mint-and-offer
+     *  transaction could activate on a network that has not voted for the
+     *  combined flow.
+     *
+     *  @param ctx  Preflight context; no ledger access is performed.
+     *  @return `true` if the transaction is compatible with active amendments;
+     *      `false` if offer fields are present but `featureNFTokenMintOffer`
+     *      is not yet enabled.
+     */
     static bool
     checkExtraFeatures(PreflightContext const& ctx);
 
+    /** Return the valid transaction-flag bitmask for the current amendment set.
+     *
+     *  The set of legal flags is amendment-sensitive in two ways:
+     *  - `tfTrustLine` was permanently disabled by `fixRemoveNFTokenAutoTrustLine`
+     *    to close a denial-of-service vector: two cooperating accounts could trade
+     *    an NFT in a loop, each transfer creating a new trustline on the issuer
+     *    and growing the issuer's reserve without bound.
+     *  - `tfMutable` (mutable-URI NFTs) is added by `featureDynamicNFT`.
+     *
+     *  The returned mask is one of four combinations depending on which of these
+     *  two amendments are active.
+     *
+     *  @param ctx  Preflight context used to query active amendments.
+     *  @return A bitmask of `tf*` flags that are legal for this transaction.
+     */
     static std::uint32_t
     getFlagsMask(PreflightContext const& ctx);
 
+    /** Stateless validation of `NFTokenMint` transaction fields.
+     *
+     *  Checks mint-specific field constraints:
+     *  - `sfTransferFee` must not exceed `maxTransferFee`; if non-zero,
+     *    `tfTransferable` must also be set (a transfer fee on a non-transferable
+     *    token is contradictory).
+     *  - `sfIssuer`, when present, must not equal `sfAccount` — the
+     *    authorized-minter pattern requires distinct minter and issuer accounts.
+     *  - `sfURI`, when present, must be non-empty and within `maxTokenURILength`.
+     *  - If offer fields are present, `sfAmount` is mandatory; offer field
+     *    validity is then delegated to `nft::tokenOfferCreatePreflight()`.
+     *
+     *  @param ctx  Preflight context; no ledger access is performed.
+     *  @return `tesSUCCESS` if all fields are valid; a `tem*` code describing
+     *      the first constraint violated.
+     */
     static NotTEC
     preflight(PreflightContext const& ctx);
 
+    /** Read-only ledger validation for the `NFTokenMint` transaction.
+     *
+     *  When `sfIssuer` is present (authorized-minter path), reads the issuer's
+     *  `AccountRoot` and verifies that its `sfNFTokenMinter` field matches the
+     *  signing account. A missing issuer account returns `tecNO_ISSUER`; a
+     *  mismatch returns `tecNO_PERMISSION`.
+     *
+     *  If offer fields are present, also invokes `nft::tokenOfferCreatePreclaim()`
+     *  to check offer-specific ledger conditions (expiry, trustline authorisation,
+     *  deep-freeze status, etc.).
+     *
+     *  @param ctx  Preclaim context providing read-only ledger access.
+     *  @return `tesSUCCESS` if all checks pass; `tecNO_ISSUER` if the issuer
+     *      account does not exist; `tecNO_PERMISSION` if the signing account is
+     *      not the designated minter; or any error propagated from
+     *      `nft::tokenOfferCreatePreclaim()`.
+     */
     static TER
     preclaim(PreclaimContext const& ctx);
 
+    /** Apply the `NFTokenMint` transaction to the mutable ledger view.
+     *
+     *  Execution proceeds in up to four steps:
+     *  1. **Sequence bookkeeping**: On the issuer's `AccountRoot`,
+     *     `sfFirstNFTokenSequence` is seeded on the first mint (set to the
+     *     issuer's current account sequence, decremented by one when the issuer
+     *     submits the transaction directly with a sequence number because the
+     *     sequence has already been pre-incremented by this point).
+     *     `sfMintedNFTokens` is incremented; overflow returns
+     *     `tecMAX_SEQUENCE_REACHED`.
+     *  2. **Token insertion**: The NFToken `STObject` is assembled with the
+     *     computed ID and optional URI, then placed into the issuer's NFToken
+     *     page structure via `nft::insertToken()`.
+     *  3. **Optional sell offer**: If `sfAmount` is present,
+     *     `nft::tokenOfferCreateApply()` creates a sell offer atomically.
+     *  4. **Reserve check**: Performed only when the owner count increased
+     *     relative to its pre-mint value — packing NFTs into an existing page
+     *     does not raise the owner count and therefore does not require a
+     *     reserve top-up.
+     *
+     *  @return `tesSUCCESS` on success; `tecMAX_SEQUENCE_REACHED` if the
+     *      issuer's NFT sequence counter would overflow; `tecINSUFFICIENT_RESERVE`
+     *      if a new page or sell offer was created and the issuer cannot cover
+     *      the increased reserve; or any error from `nft::insertToken()` or
+     *      `nft::tokenOfferCreateApply()`.
+     */
     TER
     doApply() override;
 
+    /** Per-entry invariant visitor for `NFTokenMint`.
+     *
+     *  Tracks NFToken page and NFT issuance count changes to verify that
+     *  minting results in exactly the expected ledger mutations.
+     *
+     *  @param isDelete  True if the entry is being deleted.
+     *  @param before    SLE state before the transaction (null for insertions).
+     *  @param after     SLE state after the transaction (null for deletions).
+     */
     void
     visitInvariantEntry(
         bool isDelete,
         std::shared_ptr<SLE const> const& before,
         std::shared_ptr<SLE const> const& after) override;
 
+    /** Post-apply invariant finalizer for `NFTokenMint`.
+     *
+     *  Verifies that the net NFT count change across all visited entries is
+     *  consistent with a successful mint (+1 net token created).
+     *
+     *  @param tx      The transaction being applied.
+     *  @param result  The TER result from `doApply()`.
+     *  @param fee     The fee charged for this transaction.
+     *  @param view    Read-only view of the ledger after apply.
+     *  @param j       Journal for diagnostic logging.
+     *  @return `true` if the invariant holds; `false` if an unexpected NFT
+     *      count discrepancy is detected.
+     */
     [[nodiscard]] bool
     finalizeInvariants(
         STTx const& tx,
@@ -44,7 +172,36 @@ public:
         ReadView const& view,
         beast::Journal const& j) override;
 
-    // Public to support unit tests.
+    /** Construct the 32-byte big-endian NFToken ID from its component fields.
+     *
+     *  The layout is:
+     *
+     *  | Bytes | Content                          |
+     *  |-------|----------------------------------|
+     *  | 0–1   | Flags (2 bytes, big-endian)      |
+     *  | 2–3   | Transfer fee (2 bytes, big-endian)|
+     *  | 4–23  | Issuer `AccountID` (20 bytes)    |
+     *  | 24–27 | Ciphered taxon (4 bytes, big-endian) |
+     *  | 28–31 | Token sequence number (4 bytes, big-endian) |
+     *
+     *  The taxon is scrambled via `nft::cipheredTaxon()` before packing:
+     *  `taxon ^ ((384160001 * tokenSeq) + 2459)`. This linear congruential
+     *  transform — a permutation of the 32-bit integer space by the Hull-Dobell
+     *  theorem — distributes tokens with the same taxon across different NFToken
+     *  pages, avoiding page hot-spots that would degrade lookup and deletion
+     *  performance. The constants are **protocol-frozen**: changing them would
+     *  corrupt interpretation of existing token IDs and require a new amendment.
+     *
+     *  Exposed publicly to enable unit testing without a full transaction context.
+     *
+     *  @param flags     Two-byte flag field (e.g., `nft::kFLAG_TRANSFERABLE`).
+     *  @param fee       Transfer fee in units of 1/100,000 of a percent (0–50,000).
+     *  @param issuer    The issuer's 20-byte `AccountID`.
+     *  @param taxon     The unscrambled taxon value assigned by the issuer.
+     *  @param tokenSeq  The per-issuer mint sequence number used as the cipher key
+     *                   and stored in the final 4 bytes of the ID.
+     *  @return A `uint256` token ID encoding all five fields.
+     */
     static uint256
     createNFTokenID(
         std::uint16_t flags,
diff --git a/include/xrpl/tx/transactors/nft/NFTokenModify.h b/include/xrpl/tx/transactors/nft/NFTokenModify.h
index d7f5f031b1..e7183d8b86 100644
--- a/include/xrpl/tx/transactors/nft/NFTokenModify.h
+++ b/include/xrpl/tx/transactors/nft/NFTokenModify.h
@@ -4,6 +4,21 @@
 
 namespace xrpl {
 
+/** Transactor for the `NFTokenModify` transaction type.
+ *
+ *  Updates the URI metadata of an existing, mutable NFT on the XRP Ledger.
+ *  Mutability is a permanent, at-mint choice encoded directly in the 256-bit
+ *  token ID via `nft::kFLAG_MUTABLE`; tokens minted without that flag cannot
+ *  be modified under any circumstances.
+ *
+ *  Both the original issuer and a designated authorized minter (the account
+ *  recorded in the issuer's `sfNFTokenMinter` field) may submit this
+ *  transaction. Any other account receives `tecNO_PERMISSION`.
+ *
+ *  @note `kCONSEQUENCES_FACTORY` is `Normal`; URI modification imposes no
+ *      extraordinary sequencing constraints on other transactions from the
+ *      same account.
+ */
 class NFTokenModify : public Transactor
 {
 public:
@@ -13,21 +28,91 @@ public:
     {
     }
 
+    /** Stateless validation of `NFTokenModify` transaction fields.
+     *
+     *  Performs two pure-data checks without consulting ledger state:
+     *  - If `sfOwner` is present, it must not equal `sfAccount`. The field is
+     *    only meaningful when a designated minter is acting on behalf of the
+     *    actual owner; a self-referential value is malformed.
+     *  - If `sfURI` is present, it must be non-empty and no longer than
+     *    `kMAX_TOKEN_URI_LENGTH` (256 bytes). A present-but-empty URI is
+     *    rejected as ambiguous. Omitting `sfURI` entirely is valid and signals
+     *    that the URI should not be changed.
+     *
+     *  @param ctx  Preflight context; no ledger access is performed.
+     *  @return `tesSUCCESS` if all fields are valid; `temMALFORMED` if
+     *      `sfOwner` equals `sfAccount`, or if `sfURI` is present but empty
+     *      or exceeds the maximum length.
+     */
     static NotTEC
     preflight(PreflightContext const& ctx);
 
+    /** Read-only ledger validation for the `NFTokenModify` transaction.
+     *
+     *  Resolves the effective owner (`sfOwner` if present, otherwise
+     *  `sfAccount`) and then performs the following checks in order:
+     *  1. The NFT identified by `sfNFTokenID` must exist in the owner's token
+     *     directory; absent tokens return `tecNO_ENTRY`.
+     *  2. The NFT's `nft::kFLAG_MUTABLE` bit (encoded in the token ID) must be
+     *     set; immutable tokens return `tecNO_PERMISSION`.
+     *  3. If the signing account is not the original issuer (extracted from the
+     *     token ID via `nft::getIssuer`), the issuer's `AccountRoot` must have
+     *     `sfNFTokenMinter` pointing to the signing account; any other account
+     *     returns `tecNO_PERMISSION`.
+     *
+     *  @param ctx  Preclaim context providing read-only ledger access.
+     *  @return `tesSUCCESS` if all checks pass; `tecNO_ENTRY` if the NFT does
+     *      not exist; `tecNO_PERMISSION` if the token is immutable or the
+     *      caller is neither the issuer nor the designated minter;
+     *      `tecINTERNAL` if the issuer's `AccountRoot` cannot be read (ledger
+     *      corruption sentinel, excluded from coverage).
+     */
     static TER
     preclaim(PreclaimContext const& ctx);
 
+    /** Apply the `NFTokenModify` transaction to the mutable ledger view.
+     *
+     *  Resolves the effective owner (`sfOwner` if present, otherwise
+     *  `sfAccount`) and delegates all ledger writes to
+     *  `nft::changeTokenURI()`, which locates the correct `NFTokenPage` SLE
+     *  and updates the stored URI in place. Passing `ctx_.tx[~sfURI]` (an
+     *  optional) allows the helper to distinguish an explicit URI update from
+     *  an omitted field.
+     *
+     *  @return The `TER` result from `nft::changeTokenURI()`, which is
+     *      `tesSUCCESS` on a successful write or an error code if the page
+     *      cannot be located.
+     */
     TER
     doApply() override;
 
+    /** Per-entry invariant visitor for `NFTokenModify`.
+     *
+     *  No transaction-specific invariants are currently enforced; the override
+     *  is a placeholder for future work.
+     *
+     *  @param isDelete  True if the entry is being deleted.
+     *  @param before    SLE state before the transaction (null for insertions).
+     *  @param after     SLE state after the transaction (null for deletions).
+     */
     void
     visitInvariantEntry(
         bool isDelete,
         std::shared_ptr<SLE const> const& before,
         std::shared_ptr<SLE const> const& after) override;
 
+    /** Post-apply invariant finalizer for `NFTokenModify`.
+     *
+     *  No transaction-specific invariants are currently enforced; always
+     *  returns `true`. The override is a placeholder for future work.
+     *
+     *  @param tx      The transaction being applied.
+     *  @param result  The TER result from `doApply()`.
+     *  @param fee     The fee charged for this transaction.
+     *  @param view    Read-only view of the ledger after apply.
+     *  @param j       Journal for diagnostic logging.
+     *  @return Always `true`.
+     */
     [[nodiscard]] bool
     finalizeInvariants(
         STTx const& tx,
diff --git a/include/xrpl/tx/transactors/oracle/OracleDelete.h b/include/xrpl/tx/transactors/oracle/OracleDelete.h
index 5acc365fa5..582dc83551 100644
--- a/include/xrpl/tx/transactors/oracle/OracleDelete.h
+++ b/include/xrpl/tx/transactors/oracle/OracleDelete.h
@@ -4,15 +4,18 @@
 
 namespace xrpl {
 
-/**
-    Price Oracle is a system that acts as a bridge between
-    a blockchain network and the external world, providing off-chain price data
-    to decentralized applications (dApps) on the blockchain. This implementation
-    conforms to the requirements specified in the XLS-47d.
-
-    The OracleDelete transactor implements the deletion of Oracle objects.
-*/
-
+/** Transactor for the `OracleDelete` transaction type (XLS-47d).
+ *
+ *  Removes a Price Oracle object from the ledger. Price Oracles bridge the
+ *  blockchain and external world by publishing off-chain asset prices on-chain
+ *  for consumption by decentralised applications.
+ *
+ *  This transactor pairs with `OracleSet`, which handles creation and updates.
+ *  Deletion needs no field validation — all meaningful checks are deferred to
+ *  `preclaim`. The static `deleteOracle` helper exposes the core mutation logic
+ *  so that `AccountDelete` can clean up oracles during account removal without
+ *  constructing a full transactor instance.
+ */
 class OracleDelete : public Transactor
 {
 public:
@@ -22,21 +25,58 @@ public:
     {
     }
 
+    /** Stateless preflight validation.
+     *
+     *  A delete request carries only an `sfOracleDocumentID`; there is nothing
+     *  to validate without ledger state, so this always returns `tesSUCCESS`.
+     *  All substantive checks occur in `preclaim`.
+     *
+     *  @param ctx Preflight context (no ledger access).
+     *  @return `tesSUCCESS` unconditionally.
+     */
     static NotTEC
     preflight(PreflightContext const& ctx);
 
+    /** Read-only ledger validation.
+     *
+     *  Confirms that the oracle identified by `sfOracleDocumentID` exists at
+     *  `keylet::oracle(account, documentId)` and that its `sfOwner` field
+     *  matches the submitting account. Because the keylet embeds the account,
+     *  an ownership mismatch is structurally unreachable through normal flow
+     *  (the branch is `LCOV_EXCL`).
+     *
+     *  @param ctx Preclaim context (read-only ledger access).
+     *  @return `tesSUCCESS` if the oracle exists and is owned by the submitter;
+     *      `tecNO_ENTRY` if the oracle does not exist;
+     *      `terNO_ACCOUNT` if the submitting account is missing (unreachable
+     *          under normal conditions — account existence is enforced earlier).
+     */
     static TER
     preclaim(PreclaimContext const& ctx);
 
+    /** Apply the oracle deletion to the mutable ledger view.
+     *
+     *  Peeks the oracle SLE and delegates immediately to `deleteOracle`.
+     *  Returns `tecINTERNAL` if the SLE cannot be found (unreachable under
+     *  normal conditions — `preclaim` already confirmed existence).
+     *
+     *  @return `tesSUCCESS` on success; `tecINTERNAL` if the oracle SLE is
+     *      unexpectedly missing.
+     */
     TER
     doApply() override;
 
+    /** Per-entry invariant visitor (no-op; reserved for future use). */
     void
     visitInvariantEntry(
         bool isDelete,
         std::shared_ptr<SLE const> const& before,
         std::shared_ptr<SLE const> const& after) override;
 
+    /** Post-transaction invariant check (no-op; reserved for future use).
+     *
+     *  @return `true` unconditionally.
+     */
     [[nodiscard]] bool
     finalizeInvariants(
         STTx const& tx,
@@ -45,6 +85,32 @@ public:
         ReadView const& view,
         beast::Journal const& j) override;
 
+    /** Remove a Price Oracle SLE from the ledger and adjust owner reserves.
+     *
+     *  Exposed as a static helper so that `AccountDelete` (and any other
+     *  transactor that must sweep owned objects) can invoke oracle deletion
+     *  without constructing an `OracleDelete` transactor instance — the same
+     *  pattern as `Transactor::ticketDelete`.
+     *
+     *  Owner-reserve adjustment follows XLS-47d: oracles with more than five
+     *  `sfPriceDataSeries` entries occupy **two** reserve slots when created,
+     *  so `-2` is passed to `adjustOwnerCount` for those; all others use `-1`.
+     *  This threshold must stay in sync with the creation logic in `OracleSet`.
+     *
+     *  Deletion order: `dirRemove` from the owner directory → `adjustOwnerCount`
+     *  → `view.erase`. Erasing before `dirRemove` would lose the cached page
+     *  index stored in `sfOwnerNode`.
+     *
+     *  @param view   Mutable apply view.
+     *  @param sle    The oracle SLE to delete; must not be null.
+     *  @param account Account that owns the oracle.
+     *  @param j      Journal for diagnostic logging.
+     *  @return `tesSUCCESS` on success;
+     *      `tefBAD_LEDGER` if removal from the owner directory fails (signals
+     *          ledger corruption — `LCOV_EXCL`);
+     *      `tecINTERNAL` if `sle` is null or the owner `AccountRoot` is missing
+     *          (`LCOV_EXCL`).
+     */
     static TER
     deleteOracle(
         ApplyView& view,
diff --git a/include/xrpl/tx/transactors/oracle/OracleSet.h b/include/xrpl/tx/transactors/oracle/OracleSet.h
index 3cad859dce..5e3c0d0a59 100644
--- a/include/xrpl/tx/transactors/oracle/OracleSet.h
+++ b/include/xrpl/tx/transactors/oracle/OracleSet.h
@@ -4,15 +4,18 @@
 
 namespace xrpl {
 
-/**
-    Price Oracle is a system that acts as a bridge between
-    a blockchain network and the external world, providing off-chain price data
-    to decentralized applications (dApps) on the blockchain. This implementation
-    conforms to the requirements specified in the XLS-47d.
-
-    The OracleSet transactor implements creating or updating Oracle objects.
-*/
-
+/** Transactor for the `OracleSet` transaction type (XLS-47d).
+ *
+ *  Handles both creation and in-place update of Price Oracle ledger objects.
+ *  A Price Oracle bridges off-chain data sources (e.g., exchange price feeds)
+ *  and on-ledger consumers by publishing timestamped token-pair prices under
+ *  an `(account, sfOracleDocumentID)` key. The counterpart transactor,
+ *  `OracleDelete`, handles removal.
+ *
+ *  @note Owner-count reserve follows a tiered model: oracles with more than
+ *      five `sfPriceDataSeries` entries consume **two** reserve slots; all
+ *      others consume one. This threshold is shared with `OracleDelete`.
+ */
 class OracleSet : public Transactor
 {
 public:
@@ -22,21 +25,103 @@ public:
     {
     }
 
+    /** Stateless structural validation (no ledger access).
+     *
+     *  Checks that `sfPriceDataSeries` is non-empty and within
+     *  `kMAX_ORACLE_DATA_SERIES`, and that the optional string fields
+     *  `sfProvider`, `sfURI`, and `sfAssetClass` — when present — are
+     *  non-empty and within their respective maximum lengths.
+     *
+     *  Deeper token-pair consistency is deferred to `preclaim`, which can
+     *  compare against the existing oracle SLE.
+     *
+     *  @param ctx Preflight context (no ledger access).
+     *  @return `temARRAY_EMPTY` if `sfPriceDataSeries` is empty;
+     *      `temARRAY_TOO_LARGE` if it exceeds `kMAX_ORACLE_DATA_SERIES`;
+     *      `temMALFORMED` if any optional string field violates its length
+     *          bounds; `tesSUCCESS` otherwise.
+     */
     static NotTEC
     preflight(PreflightContext const& ctx);
 
+    /** Read-only ledger validation; distinguishes create from update.
+     *
+     *  **Timestamp freshness.** `sfLastUpdateTime` is stored in XRPL epoch
+     *  seconds (offset from Unix epoch by `kEPOCH_OFFSET`). The converted
+     *  Unix timestamp must lie within `±kMAX_LAST_UPDATE_TIME_DELTA` of the
+     *  ledger's `closeTime`. On update it must also be strictly greater than
+     *  the existing oracle's `sfLastUpdateTime`.
+     *
+     *  **Create.** If no oracle SLE exists for `(account, sfOracleDocumentID)`,
+     *  `sfProvider` and `sfAssetClass` are mandatory, and any entry in
+     *  `sfPriceDataSeries` that lacks `sfAssetPrice` is malformed (there is
+     *  nothing to delete from a non-existent object).
+     *
+     *  **Update.** If the oracle SLE exists, `sfProvider` and `sfAssetClass`
+     *  may be omitted; if supplied they must match the stored values (these
+     *  fields are immutable after creation). Entries without `sfAssetPrice`
+     *  signal deletion; a deletion request for a pair not in the current
+     *  oracle returns `tecTOKEN_PAIR_NOT_FOUND`. Duplicate pairs within a
+     *  single transaction are rejected.
+     *
+     *  **Reserve.** The account balance is checked against the reserve
+     *  required by the resulting pair count (using the tiered 1-or-2-slot
+     *  model) before the fee is deducted.
+     *
+     *  @param ctx Preclaim context (read-only ledger access).
+     *  @return `tesSUCCESS` on success;
+     *      `terNO_ACCOUNT` if the submitting account does not exist;
+     *      `tecINVALID_UPDATE_TIME` if the timestamp is out of the freshness
+     *          window or is not strictly newer than the existing oracle's
+     *          timestamp on update;
+     *      `tecTOKEN_PAIR_NOT_FOUND` if a deletion targets a pair absent from
+     *          the current oracle;
+     *      `tecARRAY_EMPTY` if the resolved pair set after merging is empty;
+     *      `tecARRAY_TOO_LARGE` if the resolved pair set exceeds
+     *          `kMAX_ORACLE_DATA_SERIES`;
+     *      `tecINSUFFICIENT_RESERVE` if the account cannot cover the reserve;
+     *      `temMALFORMED` for structural violations (duplicate pairs,
+     *          self-referential base/quote, mismatched immutable fields, or
+     *          a deletion entry in a creation context).
+     */
     static TER
     preclaim(PreclaimContext const& ctx);
 
+    /** Apply the oracle create or update to the mutable ledger view.
+     *
+     *  **Update path.** Loads all existing pairs into a
+     *  `std::map<pair<Currency,Currency>, STObject>` keyed by `tokenPairKey`,
+     *  applies the transaction's entries (delete / update-in-place / insert),
+     *  and serialises the result back as `sfPriceDataSeries`. Owner-count is
+     *  adjusted for any tier change. `sfURI` and `sfLastUpdateTime` are
+     *  updated unconditionally. Under `fixIncludeKeyletFields`, `sfOracleDocumentID`
+     *  is back-filled onto older objects that predate the amendment.
+     *
+     *  **Create path.** Constructs a new SLE, inserts it into the owner
+     *  directory, and increments the owner count by 1 or 2 per the tiered
+     *  model. Under `fixPriceOracleOrder`, the initial `sfPriceDataSeries`
+     *  is sorted via the same map approach as the update path; without the
+     *  amendment, raw transaction order is preserved (legacy behaviour).
+     *
+     *  @return `tesSUCCESS` on success;
+     *      `tecDIR_FULL` if the owner directory is full (create path only);
+     *      `tefINTERNAL` if the account SLE cannot be peeked for owner-count
+     *          adjustment (unreachable under normal conditions).
+     */
     TER
     doApply() override;
 
+    /** Per-entry invariant visitor (no-op; reserved for future work). */
     void
     visitInvariantEntry(
         bool isDelete,
         std::shared_ptr<SLE const> const& before,
         std::shared_ptr<SLE const> const& after) override;
 
+    /** Post-transaction invariant check (no-op; reserved for future work).
+     *
+     *  @return `true` unconditionally.
+     */
     [[nodiscard]] bool
     finalizeInvariants(
         STTx const& tx,
diff --git a/include/xrpl/tx/transactors/payment/DepositPreauth.h b/include/xrpl/tx/transactors/payment/DepositPreauth.h
index 9eaf94989a..bd7b63d437 100644
--- a/include/xrpl/tx/transactors/payment/DepositPreauth.h
+++ b/include/xrpl/tx/transactors/payment/DepositPreauth.h
@@ -4,6 +4,20 @@
 
 namespace xrpl {
 
+/** Transactor for the `DepositPreauth` transaction type.
+ *
+ *  Manages the whitelist of accounts and credential-bearing parties permitted
+ *  to send payments to an account that has enabled `lsfDepositAuth`. Without a
+ *  preauthorization entry, any inbound payment to such an account fails.
+ *
+ *  Supports four mutually exclusive operations, selected by which single field
+ *  is present in the transaction: `sfAuthorize`, `sfUnauthorize`,
+ *  `sfAuthorizeCredentials`, and `sfUnauthorizeCredentials`. The credential
+ *  variants are gated on the `featureCredentials` amendment.
+ *
+ *  @note The `ConsequencesFactory` is `Normal` — this transaction does not
+ *      block other transactions from the same account in the fee queue.
+ */
 class DepositPreauth : public Transactor
 {
 public:
@@ -13,24 +27,83 @@ public:
     {
     }
 
+    /** Gate credential-based operations on the `featureCredentials` amendment.
+     *
+     *  Returns `false` (causing `invokePreflight` to emit `temDISABLED`) when
+     *  `sfAuthorizeCredentials` or `sfUnauthorizeCredentials` is present but
+     *  the `featureCredentials` amendment is not yet active on the ledger.
+     *
+     *  @param ctx Preflight context carrying the transaction and active rules.
+     *  @return `true` if the transaction is permitted to proceed to `preflight`;
+     *      `false` if a required amendment is disabled.
+     */
     static bool
     checkExtraFeatures(PreflightContext const& ctx);
 
+    /** Stateless validation of field presence and basic semantic correctness.
+     *
+     *  Enforces that exactly one of `sfAuthorize`, `sfUnauthorize`,
+     *  `sfAuthorizeCredentials`, or `sfUnauthorizeCredentials` is present,
+     *  returning `temMALFORMED` otherwise. For account-based operations,
+     *  validates that the target `AccountID` is non-zero and that the
+     *  authorizing account is not attempting to preauthorize itself
+     *  (`temCANNOT_PREAUTH_SELF`). For credential-based operations, delegates
+     *  array validation to `credentials::checkArray`.
+     *
+     *  @param ctx Preflight context; no ledger view is available.
+     *  @return `tesSUCCESS` on valid input, or a `tem*` code describing the
+     *      specific malformation.
+     */
     static NotTEC
     preflight(PreflightContext const& ctx);
 
+    /** Read-only ledger checks for authorization and de-authorization.
+     *
+     *  For `sfAuthorize`: verifies the target account exists (`tecNO_TARGET`)
+     *  and that no duplicate `DepositPreauth` entry already exists for the pair
+     *  (`tecDUPLICATE`). For `sfUnauthorize`: verifies the entry being removed
+     *  is present (`tecNO_ENTRY`). Credential variants additionally verify that
+     *  every credential issuer is a live account (`tecNO_ISSUER`), and sort the
+     *  credential set canonically before computing the ledger key to ensure the
+     *  duplicate check is order-independent.
+     *
+     *  @param ctx Preclaim context providing a read-only ledger view.
+     *  @return `tesSUCCESS`, or a `tec*`/`tef*` code if a ledger-state
+     *      constraint is violated.
+     */
     static TER
     preclaim(PreclaimContext const& ctx);
 
+    /** Apply the preauthorization change to the ledger.
+     *
+     *  For authorization operations (`sfAuthorize` / `sfAuthorizeCredentials`),
+     *  checks the owner reserve against `preFeeBalance_` (the balance before
+     *  fee deduction), creates a `DepositPreauth` SLE, inserts it into the
+     *  ledger and the account's owner directory, and increments the owner count.
+     *  For de-authorization, delegates to `removeFromLedger`. Credentials are
+     *  re-sorted before being written to the SLE to preserve canonical order.
+     *
+     *  @return `tesSUCCESS` on success, `tecINSUFFICIENT_RESERVE` if the
+     *      account lacks sufficient reserve to own another entry, or a `tef*`
+     *      code on internal ledger inconsistency.
+     *  @note Reserve is checked against `preFeeBalance_` so that an account
+     *      may spend its base reserve on fees while still being rejected for
+     *      creating a new owned object it cannot afford.
+     */
     TER
     doApply() override;
 
+    /** No-op invariant visitor; transaction-specific invariants not yet defined. */
     void
     visitInvariantEntry(
         bool isDelete,
         std::shared_ptr<SLE const> const& before,
         std::shared_ptr<SLE const> const& after) override;
 
+    /** No-op invariant finalizer; transaction-specific invariants not yet defined.
+     *
+     *  @return Always `true`.
+     */
     [[nodiscard]] bool
     finalizeInvariants(
         STTx const& tx,
@@ -39,7 +112,21 @@ public:
         ReadView const& view,
         beast::Journal const& j) override;
 
-    // Interface used by AccountDelete
+    /** Remove a `DepositPreauth` SLE from the ledger by its index.
+     *
+     *  Locates the entry, removes it from the owner's directory using the
+     *  `sfOwnerNode` page cached in the SLE, decrements the owner count, and
+     *  erases the entry. Called both from `doApply` (for `sfUnauthorize` /
+     *  `sfUnauthorizeCredentials`) and from `AccountDelete` when cleaning up
+     *  all owned objects before deleting an account.
+     *
+     *  @param view  Mutable ledger view on which to operate.
+     *  @param delIndex Ledger key of the `DepositPreauth` entry to remove.
+     *  @param j     Journal for diagnostic logging.
+     *  @return `tesSUCCESS` on success; `tecNO_ENTRY` if the SLE is missing;
+     *      `tefBAD_LEDGER` if the owner-directory removal fails (indicates
+     *      ledger corruption — should be unreachable under normal operation).
+     */
     static TER
     removeFromLedger(ApplyView& view, uint256 const& delIndex, beast::Journal j);
 };
diff --git a/include/xrpl/tx/transactors/payment/Payment.h b/include/xrpl/tx/transactors/payment/Payment.h
index 23a46f0766..44794c384b 100644
--- a/include/xrpl/tx/transactors/payment/Payment.h
+++ b/include/xrpl/tx/transactors/payment/Payment.h
@@ -4,48 +4,211 @@
 
 namespace xrpl {
 
+/**
+ * Transactor for the `ttPAYMENT` transaction type.
+ *
+ * Handles three structurally distinct execution paths within a single protocol
+ * transaction type: direct XRP-to-XRP transfers, direct MPToken (MPT) transfers
+ * (pre-`featureMPTokensV2`), and cross-currency path-based payments routed
+ * through `path::RippleCalc`. The branching is an implementation detail hidden
+ * from the serialized transaction format.
+ *
+ * Pipeline stages follow the standard `Transactor` framework:
+ * `checkExtraFeatures` → `preflight` → `preflight2` → `preclaim` → `doApply`.
+ * All stages except `doApply` are static; compile-time dispatch via
+ * `invokePreflight<Payment>` rather than vtable.
+ *
+ * @note `ConsequencesFactory` is `Custom` because the maximum XRP spend depends
+ *     on `sfSendMax` vs. `sfAmount` — the framework invokes `makeTxConsequences`
+ *     to obtain a conservative upper bound for queue ordering.
+ */
 class Payment : public Transactor
 {
-    /* The largest number of paths we allow */
+    /** Maximum number of paths allowed in `sfPaths`. */
     static std::size_t const kMAX_PATH_SIZE = 6;
 
-    /* The longest path we allow */
+    /** Maximum number of steps permitted in a single path. */
     static std::size_t const kMAX_PATH_LENGTH = 8;
 
 public:
+    /**
+     * Signals to the framework that this transactor computes its own
+     * `TxConsequences` via `makeTxConsequences` rather than using the
+     * standard normal-fee or blocker logic.
+     */
     static constexpr auto kCONSEQUENCES_FACTORY = ConsequencesFactoryType::Custom;
 
     explicit Payment(ApplyContext& ctx) : Transactor(ctx)
     {
     }
 
+    /**
+     * Computes the maximum XRP that this transaction could consume.
+     *
+     * If `sfSendMax` is present and denominated in XRP, its value is the
+     * upper bound. Otherwise `sfAmount` is used if it is native. If neither
+     * field is XRP, the maximum is zero (no XRP is spent beyond the fee).
+     * The result is used by the transaction queue for consequence ordering.
+     *
+     * @param ctx Stateless preflight context providing the raw transaction.
+     * @return `TxConsequences` carrying the computed maximum XRP spend.
+     */
     static TxConsequences
     makeTxConsequences(PreflightContext const& ctx);
 
+    /**
+     * Gates optional transaction fields behind their required amendments.
+     *
+     * Returns `false` (suppressing the transaction) if:
+     * - `sfCredentialIDs` is present but `featureCredentials` is not enabled, or
+     * - `sfDomainID` is present but `featurePermissionedDEX` is not enabled.
+     *
+     * @param ctx Preflight context including the active rule set.
+     * @return `true` if all present optional fields are supported; `false` otherwise.
+     */
     static bool
     checkExtraFeatures(PreflightContext const& ctx);
 
+    /**
+     * Returns the set of transaction flags that are valid for this payment.
+     *
+     * For MPT-denominated payments when `featureMPTokensV2` is not active,
+     * only `tfPartialPayment` is permitted beyond the universal flags. Once
+     * `MPTokensV2` is active, the full `tfPaymentMask` (which includes
+     * `tfLimitQuality`, `tfNoRippleDirect`, etc.) becomes valid because MPT
+     * payments can then participate in path-finding.
+     *
+     * @param ctx Preflight context providing the transaction and active rules.
+     * @return Bitmask of flags that must be zero for a well-formed transaction.
+     */
     static std::uint32_t
     getFlagsMask(PreflightContext const& ctx);
 
+    /**
+     * Performs stateless structural validation of the payment fields.
+     *
+     * Checks performed (no ledger access):
+     * - MPT-denominated `sfAmount` requires `featureMPTokensV1`.
+     * - XRP direct payments must not carry `sfSendMax`, `sfPaths`,
+     *   `tfPartialPayment`, `tfLimitQuality`, or `tfNoRippleDirect` — each
+     *   produces a distinct `temBAD_SEND_XRP_*` error for client diagnostics.
+     * - Pre-`MPTokensV2` MPT payments must not carry `sfPaths`.
+     * - Self-payments without `sfPaths` are rejected as `temREDUNDANT`;
+     *   self-payments with paths are allowed (arbitrage cycle).
+     * - When `sfDeliverMin` is set, `tfPartialPayment` must be set, the amount
+     *   must be positive, its asset must match `sfAmount`, and it must not
+     *   exceed `sfAmount`.
+     * - Credential fields are structurally validated via `credentials::checkFields`.
+     *
+     * @param ctx Preflight context; no ledger view is available.
+     * @return `tesSUCCESS` if structurally valid, or a `tem*` error code.
+     */
     static NotTEC
     preflight(PreflightContext const& ctx);
 
+    /**
+     * Validates delegation permission for the payment when `sfDelegate` is set.
+     *
+     * Two-tier check:
+     * 1. Full permission: if the `DelegateObject` SLE grants blanket `ttPAYMENT`
+     *    permission, the payment is allowed unconditionally.
+     * 2. Granular permissions: `PaymentMint` permits a delegate to issue tokens
+     *    where the delegating account is the asset issuer; `PaymentBurn` permits
+     *    sending tokens back to their issuer. Both grants apply only to *direct*
+     *    payments — any payment with `sfPaths` set, or where `sfSendMax` refers
+     *    to a different asset than `sfAmount`, is denied. This prevents granular
+     *    delegation from being used to manipulate multi-hop paths.
+     *
+     * If `sfDelegate` is absent, returns `tesSUCCESS` immediately.
+     *
+     * @param view Read-only ledger view used to look up the delegate SLE.
+     * @param tx   The transaction being validated.
+     * @return `tesSUCCESS` if permitted, `terNO_DELEGATE_PERMISSION` otherwise.
+     */
     static NotTEC
     checkPermission(ReadView const& view, STTx const& tx);
 
+    /**
+     * Validates ledger-state preconditions for the payment.
+     *
+     * Checks performed (read-only ledger access):
+     * - Non-native payments to a non-existent destination fail `tecNO_DST`;
+     *   only XRP can fund a new account.
+     * - Partial payments cannot create accounts (`telNO_DST_PARTIAL`).
+     * - XRP amount below base reserve cannot create an account (`tecNO_DST_INSUF_XRP`).
+     * - Destination with `lsfRequireDestTag` requires `sfDestinationTag`
+     *   (`tecDST_TAG_NEEDED`).
+     * - Path complexity: more than `kMAX_PATH_SIZE` (6) paths, or any path
+     *   exceeding `kMAX_PATH_LENGTH` (8) steps, is rejected `telBAD_PATH_COUNT`.
+     * - Credential validity is checked via `credentials::valid`.
+     * - If `sfDomainID` is present, both sender and destination must be members
+     *   of the specified permissioned domain (`tecNO_PERMISSION`).
+     *
+     * @param ctx Preclaim context providing a read-only ledger view.
+     * @return `tesSUCCESS`, or a `tec*`/`tel*`/`ter*` error code.
+     */
     static TER
     preclaim(PreclaimContext const& ctx);
 
+    /**
+     * Executes the payment and mutates ledger state.
+     *
+     * Branches into one of three execution paths based on asset type and flags:
+     *
+     * **RippleCalc (path-based):** Any payment with `sfPaths`, `sfSendMax`, or
+     * a non-native destination amount (except direct MPT pre-`MPTokensV2`)
+     * routes through `path::RippleCalc::rippleCalculate` inside a
+     * `PaymentSandbox`. The sandbox is applied atomically only if the
+     * calculation succeeds. `ter*` retry codes from `RippleCalc` are promoted
+     * to `tecPATH_DRY` to ensure fee collection and deter path-spam.
+     * `ctx_.deliver()` records the actual delivered amount when it differs from
+     * the requested amount (enabling the `DeliveredAmount` metadata field).
+     *
+     * **Direct MPT (pre-`featureMPTokensV2`):** Bypasses `RippleCalc`. Checks
+     * `requireAuth`, `canTransfer`, and frozen state, then applies the transfer
+     * rate. If `tfPartialPayment` is set and the sender cannot cover the full
+     * transfer-rate-adjusted cost, the delivered amount is scaled down and
+     * checked against `sfDeliverMin`. `fixMPTDeliveredAmount` gates whether
+     * `ctx_.deliver()` is called for partial or rate-adjusted deliveries.
+     *
+     * **Direct XRP:** Validates that `preFeeBalance_` covers the destination
+     * amount plus the reserve (adjusted for whether the source account or a
+     * delegate pays the fee). Rejects pseudo-account recipients. Enforces
+     * deposit pre-authorization with a small-balance bypass to prevent accounts
+     * from becoming permanently wedged. Updates both `sfBalance` fields directly.
+     *
+     * @return `tesSUCCESS` on success, or a `tec*` error code on failure.
+     */
     TER
     doApply() override;
 
+    /**
+     * Invariant visitor called once per modified SLE.
+     *
+     * Currently a no-op placeholder for future transaction-specific invariants.
+     *
+     * @param isDelete `true` if the SLE is being erased.
+     * @param before   SLE state before the transaction, or `nullptr` if new.
+     * @param after    SLE state after the transaction, or `nullptr` if deleted.
+     */
     void
     visitInvariantEntry(
         bool isDelete,
         std::shared_ptr<SLE const> const& before,
         std::shared_ptr<SLE const> const& after) override;
 
+    /**
+     * Finalizes transaction-specific invariant checks after all SLEs are visited.
+     *
+     * Currently a no-op placeholder; always returns `true`.
+     *
+     * @param tx     The transaction that was applied.
+     * @param result The TER code returned by `doApply`.
+     * @param fee    The fee charged in drops.
+     * @param view   Read-only view of the ledger after the transaction.
+     * @param j      Journal for diagnostic logging.
+     * @return `true` if all invariants pass; `false` to veto the transaction.
+     */
     [[nodiscard]] bool
     finalizeInvariants(
         STTx const& tx,
diff --git a/include/xrpl/tx/transactors/payment_channel/PaymentChannelClaim.h b/include/xrpl/tx/transactors/payment_channel/PaymentChannelClaim.h
index 444832b1dc..8b2d049ec1 100644
--- a/include/xrpl/tx/transactors/payment_channel/PaymentChannelClaim.h
+++ b/include/xrpl/tx/transactors/payment_channel/PaymentChannelClaim.h
@@ -4,6 +4,25 @@
 
 namespace xrpl {
 
+/** Transactor for the PaymentChannelClaim transaction type.
+ *
+ *  Payment channels are off-ledger scaling constructs: a sender locks XRP
+ *  into an on-ledger `ltPAYCHAN` object via `PaymentChannelCreate`, then
+ *  issues incrementally larger signed authorization vouchers off-ledger.
+ *  Each voucher encodes a new *cumulative* `sfBalance` — "the receiver may
+ *  now claim up to N drops total from this channel." When either party
+ *  wants to settle, they submit a `PaymentChannelClaim` transaction. This
+ *  transactor handles all settlement scenarios: balance claims, voluntary
+ *  close, expiry-triggered close, and expiry removal (`tfRenew`).
+ *
+ *  @note `kCONSEQUENCES_FACTORY` is `Normal` (not `Custom` as in
+ *      `PaymentChannelCreate` / `PaymentChannelFund`) because a Claim only
+ *      redistributes already-locked XRP and cannot introduce new XRP
+ *      obligations for the submitting account.
+ *
+ *  @see PaymentChannelCreate — opens the channel and locks capacity.
+ *  @see PaymentChannelFund — adds XRP to an existing channel.
+ */
 class PaymentChannelClaim : public Transactor
 {
 public:
@@ -13,27 +32,145 @@ public:
     {
     }
 
+    /** Gate optional fields on their governing amendments.
+     *
+     *  Rejects the transaction with `temDISABLED` if `sfCredentialIDs` is
+     *  present but the `featureCredentials` amendment is not yet active.
+     *  Called by the framework before `preflight`.
+     *
+     *  @param ctx Preflight context providing the transaction and active rules.
+     *  @return `true` if all optional fields are permitted under current rules;
+     *      `false` to abort with `temDISABLED`.
+     */
     static bool
     checkExtraFeatures(PreflightContext const& ctx);
 
+    /** Return the set of legal flag bits for this transaction type.
+     *
+     *  The base-class `preflight1` enforces this mask before invoking the
+     *  transactor-specific `preflight`, so unknown flags are rejected early.
+     *
+     *  @param ctx Preflight context (unused; present for framework
+     *      compatibility).
+     *  @return `tfPaymentChannelClaimMask`.
+     */
     static std::uint32_t
     getFlagsMask(PreflightContext const& ctx);
 
+    /** Stateless validation of the transaction fields.
+     *
+     *  Checks that can be performed without ledger access, in order:
+     *  - `sfBalance` and `sfAmount`, when present, must be positive XRP;
+     *    `sfBalance` must not exceed `sfAmount`.
+     *  - `tfClose` and `tfRenew` are mutually exclusive.
+     *  - If `sfSignature` is present, both `sfPublicKey` and `sfBalance`
+     *    must also be present (a bare signature is malformed).
+     *  - The off-channel payment voucher signature is verified here against
+     *    the transaction-supplied public key via
+     *    `serializePayChanAuthorization`. This is distinct from the
+     *    transaction's own signature (verified by the framework in
+     *    `preflight2`); the voucher authorizes the receiver to claim funds,
+     *    not the transaction itself.
+     *  - Credential field structure is validated via
+     *    `credentials::checkFields`.
+     *
+     *  @note The public key is not yet matched against the channel's stored
+     *      key here because `preflight` has no ledger access; that check
+     *      occurs in `doApply`.
+     *
+     *  @param ctx Preflight context.
+     *  @return `tesSUCCESS` on success, or a `tem*` code describing the
+     *      specific malformation.
+     */
     static NotTEC
     preflight(PreflightContext const& ctx);
 
+    /** Validate credentials against live ledger state.
+     *
+     *  Called only when `featureCredentials` is enabled. Delegates to the
+     *  base-class no-op otherwise. Uses `credentials::valid()` to check
+     *  that any `sfCredentialIDs` entries exist in the ledger and are not
+     *  expired. Credential *cleanup* (removing expired objects) is deferred
+     *  to `verifyDepositPreauth` in `doApply`.
+     *
+     *  @param ctx Preclaim context providing read-only ledger access.
+     *  @return `tesSUCCESS`, or a `ter*`/`tec*` code if credentials are
+     *      invalid or expired.
+     */
     static TER
     preclaim(PreclaimContext const& ctx);
 
+    /** Settle the payment channel on the ledger.
+     *
+     *  Executes up to four independent behaviors, evaluated in order:
+     *
+     *  1. **Expiry check (highest priority).** If the ledger's
+     *     `parentCloseTime` has passed either `sfCancelAfter` or
+     *     `sfExpiration`, `closeChannel()` is called immediately regardless
+     *     of other fields or flags. A claim transaction can thus serve as
+     *     the trigger that closes an expired channel even when no XRP
+     *     transfer is requested.
+     *
+     *  2. **Permission check.** Only the channel source (`sfAccount`) or
+     *     destination (`sfDestination`) may interact with the channel.
+     *
+     *  3. **Balance claim** (when `sfBalance` is present). Transfers the
+     *     incremental difference `reqBalance - chanBalance` to the
+     *     destination. `sfBalance` is cumulative: the actual XRP moved is
+     *     only the new portion beyond what was already claimed. The
+     *     destination must supply `sfSignature`; the source does not need
+     *     one. The supplied public key is matched against the channel's
+     *     stored `sfPublicKey`. `verifyDepositPreauth` is called before
+     *     the transfer to honor any DepositPreauth restrictions.
+     *
+     *  4. **Renew** (`tfRenew`). Clears `sfExpiration`, retracting a
+     *     previously issued close request. Only the source may renew.
+     *
+     *  5. **Close** (`tfClose`). If the destination is closing, or the
+     *     channel is fully drained (`sfBalance == sfAmount`), the channel
+     *     closes immediately via `closeChannel()`. If the source is
+     *     closing a partially-funded channel, `sfExpiration` is set to
+     *     `parentCloseTime + sfSettleDelay`, giving the destination a
+     *     guaranteed settlement window; a sooner existing expiration is
+     *     never overwritten.
+     *
+     *  @return `tesSUCCESS` on success, or a `tec*`/`tem*` code:
+     *      - `tecNO_TARGET` — channel object not found.
+     *      - `tecNO_PERMISSION` — submitter is neither source nor
+     *          destination.
+     *      - `tecUNFUNDED_PAYMENT` — requested balance does not exceed the
+     *          already-settled balance (nothing new to transfer), or exceeds
+     *          the channel's total funded capacity.
+     *      - `temBAD_SIGNATURE` — destination attempted a claim without
+     *          supplying a signature.
+     *      - `temBAD_SIGNER` — supplied public key does not match the
+     *          channel's stored key.
+     *      - `tecNO_DST` — destination account not found.
+     */
     TER
     doApply() override;
 
+    /** Per-entry invariant hook (no-op; reserved for future use).
+     *
+     *  @param isDelete Whether the entry is being deleted.
+     *  @param before   SLE state before the transaction.
+     *  @param after    SLE state after the transaction.
+     */
     void
     visitInvariantEntry(
         bool isDelete,
         std::shared_ptr<SLE const> const& before,
         std::shared_ptr<SLE const> const& after) override;
 
+    /** Post-transaction invariant check (no-op; reserved for future use).
+     *
+     *  @param tx     The applied transaction.
+     *  @param result The TER returned by `doApply`.
+     *  @param fee    The fee deducted.
+     *  @param view   Read-only view of the resulting ledger state.
+     *  @param j      Journal for diagnostic logging.
+     *  @return Always `true` (no invariants enforced yet).
+     */
     [[nodiscard]] bool
     finalizeInvariants(
         STTx const& tx,
diff --git a/include/xrpl/tx/transactors/payment_channel/PaymentChannelCreate.h b/include/xrpl/tx/transactors/payment_channel/PaymentChannelCreate.h
index 800cfcdb91..8a59383238 100644
--- a/include/xrpl/tx/transactors/payment_channel/PaymentChannelCreate.h
+++ b/include/xrpl/tx/transactors/payment_channel/PaymentChannelCreate.h
@@ -4,6 +4,27 @@
 
 namespace xrpl {
 
+/**
+ * Transactor for opening a unidirectional XRP payment channel (`ttPAYCHAN_CREATE`).
+ *
+ * Payment channels let two parties exchange a stream of XRP micropayments
+ * off-ledger via signed claim messages, while committing only the open and
+ * close operations to the global ledger. This transactor handles the first
+ * on-ledger step: locking the sender's XRP into a new `PayChannel` SLE and
+ * registering it in both parties' owner directories.
+ *
+ * Pipeline contract:
+ * - `makeTxConsequences` — reports the full `sfAmount` as consumed XRP so the
+ *   transaction queue accurately prices the account's locked funds.
+ * - `preflight` — field-level validation only; no ledger access.
+ * - `preclaim` — read-only ledger checks (reserve, destination existence,
+ *   permission flags, pseudo-account guard).
+ * - `doApply` — constructs the `PayChannel` SLE, inserts dual directory
+ *   entries, and debits the sender's balance.
+ *
+ * `ConsequencesFactory` is `Custom` because the channel locks the full
+ * `sfAmount` of XRP beyond just the fee, unlike a `Normal` transactor.
+ */
 class PaymentChannelCreate : public Transactor
 {
 public:
@@ -13,24 +34,118 @@ public:
     {
     }
 
+    /**
+     * Report the worst-case XRP consumed so the transaction queue can reserve
+     * the right amount.
+     *
+     * Returns a `TxConsequences` whose consumed XRP is `ctx.tx[sfAmount].xrp()`
+     * — the full channel funding, not merely the fee. This distinction matters
+     * for pending-transaction accounting: the account cannot spend the escrowed
+     * XRP while this transaction awaits inclusion.
+     *
+     * @param ctx  Preflight context providing access to the transaction fields.
+     * @return     `TxConsequences` reflecting fee + full channel amount.
+     */
     static TxConsequences
     makeTxConsequences(PreflightContext const& ctx);
 
+    /**
+     * Validate transaction fields before any ledger access.
+     *
+     * Enforces three structural invariants:
+     * 1. `sfAmount` must be a positive XRP value; IOUs are not permitted in
+     *    payment channels.
+     * 2. `sfAccount` must differ from `sfDestination`; self-funded channels
+     *    are rejected with `temDST_IS_SRC`.
+     * 3. `sfPublicKey` must parse as a known key type (secp256k1 or Ed25519);
+     *    this key signs off-ledger claims and cannot be changed after creation.
+     *
+     * @param ctx  Preflight context providing the transaction and current rules.
+     * @return     `tesSUCCESS`, or a `tem*` error code.
+     */
     static NotTEC
     preflight(PreflightContext const& ctx);
 
+    /**
+     * Validate ledger state before mutating it.
+     *
+     * Checks (in order):
+     * - Sender account exists.
+     * - Sender balance covers the new owner reserve (`tecINSUFFICIENT_RESERVE`)
+     *   and the full channel amount on top of that (`tecUNFUNDED`). The two
+     *   codes are intentionally distinct: `tecINSUFFICIENT_RESERVE` means the
+     *   account cannot hold another ledger object at all; `tecUNFUNDED` means
+     *   it can hold the object but cannot fund it at the requested level.
+     * - Destination account exists (`tecNO_DST`).
+     * - Destination has not set `lsfDisallowIncomingPayChan` (`tecNO_PERMISSION`).
+     * - Destination tag is present when required by `lsfRequireDestTag`
+     *   (`tecDST_TAG_NEEDED`).
+     * - Destination is not a pseudo-account (`tecNO_PERMISSION`). This check
+     *   is not amendment-gated because pseudo-account discriminator fields are
+     *   themselves only written under amendment guards, so the check's
+     *   behaviour automatically tracks the active amendments.
+     *
+     * @param ctx  Preclaim context providing read-only ledger access.
+     * @return     `tesSUCCESS`, or a `tec*`/`ter*` error code.
+     */
     static TER
     preclaim(PreclaimContext const& ctx);
 
+    /**
+     * Construct the `PayChannel` SLE and commit all ledger mutations.
+     *
+     * Performs the following steps in order:
+     * 1. **Expiry check** (under `fixPayChanCancelAfter`): if `sfCancelAfter`
+     *    is present and already past the ledger's `parentCloseTime`, returns
+     *    `tecEXPIRED`. This runs in `doApply`, not `preclaim`, because the
+     *    canonical close time is only fully settled at apply time.
+     * 2. **Channel SLE construction**: creates a `PayChannel` object at
+     *    `keylet::payChan(account, dst, tx.getSeqValue())`. Using the
+     *    sequence-or-ticket value as part of the key makes the channel ID
+     *    deterministic before the transaction lands — off-ledger parties can
+     *    reference the channel in signed claims before confirmation. The SLE
+     *    captures total escrowed funds (`sfAmount`), running paid balance
+     *    initialised to zero (`sfBalance`), both account IDs, settle delay,
+     *    signing public key, and optional cancel-after/tag fields. Under
+     *    `fixIncludeKeyletFields`, `sfSequence` is also stored so the keylet
+     *    can be reconstructed from the SLE alone.
+     * 3. **Dual directory registration**: inserts the channel into the sender's
+     *    owner directory (`sfOwnerNode`) and the recipient's owner directory
+     *    (`sfDestinationNode`), enabling efficient removal on closure.
+     * 4. **Balance and owner count update**: decrements sender `sfBalance` by
+     *    the channel amount and calls `adjustOwnerCount(..., +1, ...)` to
+     *    raise the sender's minimum reserve.
+     *
+     * @return `tesSUCCESS` on success, or a `tef*`/`tec*` code on failure.
+     */
     TER
     doApply() override;
 
+    /**
+     * Per-entry invariant visitor (reserved for future transaction-specific
+     * invariant checks; currently a no-op).
+     *
+     * @param isDelete  True if the entry is being deleted.
+     * @param before    SLE state before the transaction, or null if new.
+     * @param after     SLE state after the transaction, or null if deleted.
+     */
     void
     visitInvariantEntry(
         bool isDelete,
         std::shared_ptr<SLE const> const& before,
         std::shared_ptr<SLE const> const& after) override;
 
+    /**
+     * Post-apply invariant finalizer (reserved for future transaction-specific
+     * invariant checks; currently always returns `true`).
+     *
+     * @param tx     The applied transaction.
+     * @param result The TER returned by `doApply`.
+     * @param fee    The fee charged for this transaction.
+     * @param view   Read-only view of the ledger after application.
+     * @param j      Journal for diagnostic logging.
+     * @return       `true` if all invariants pass; `false` to veto the result.
+     */
     [[nodiscard]] bool
     finalizeInvariants(
         STTx const& tx,
diff --git a/include/xrpl/tx/transactors/payment_channel/PaymentChannelFund.h b/include/xrpl/tx/transactors/payment_channel/PaymentChannelFund.h
index ee26d34dce..7114879e29 100644
--- a/include/xrpl/tx/transactors/payment_channel/PaymentChannelFund.h
+++ b/include/xrpl/tx/transactors/payment_channel/PaymentChannelFund.h
@@ -4,6 +4,20 @@
 
 namespace xrpl {
 
+/** Adds XRP to an existing payment channel and optionally extends its expiration.
+ *
+ *  One of three transactors in the payment channel lifecycle (alongside
+ *  `PaymentChannelCreate` and `PaymentChannelClaim`). The channel owner may
+ *  top up the escrowed XRP balance without closing and reopening the channel,
+ *  and may independently extend the voluntary `sfExpiration` deadline.
+ *
+ *  `ConsequencesFactory` is `Custom` because the consumed XRP is the full
+ *  `sfAmount` being deposited — not merely the fee — and the transaction queue
+ *  must price it accordingly.
+ *
+ *  No `preclaim` override is defined; all meaningful ledger preconditions are
+ *  checked efficiently inside `doApply` once the channel SLE is in hand.
+ */
 class PaymentChannelFund : public Transactor
 {
 public:
@@ -13,21 +27,86 @@ public:
     {
     }
 
+    /** Report the worst-case XRP consumed so the transaction queue can reserve
+     *  the right amount.
+     *
+     *  Returns a `TxConsequences` whose consumed XRP equals `ctx.tx[sfAmount].xrp()`
+     *  — the full deposit, not merely the fee. Pending-transaction accounting
+     *  treats this XRP as unavailable until the transaction is included or dropped.
+     *
+     *  @param ctx  Preflight context providing access to the transaction fields.
+     *  @return     `TxConsequences` reflecting fee + full deposit amount.
+     */
     static TxConsequences
     makeTxConsequences(PreflightContext const& ctx);
 
+    /** Validate transaction fields before any ledger access.
+     *
+     *  Enforces two structural rules:
+     *  1. `sfAmount` must be XRP; IOU amounts are not permitted in payment channels.
+     *  2. `sfAmount` must be strictly positive.
+     *
+     *  Everything else is deferred to `doApply`.
+     *
+     *  @param ctx  Preflight context providing the transaction and current rules.
+     *  @return     `tesSUCCESS`, or `temBAD_AMOUNT` if the amount is invalid.
+     */
     static NotTEC
     preflight(PreflightContext const& ctx);
 
+    /** Mutate ledger state to fund the channel and/or extend its expiration.
+     *
+     *  Executes the following guard sequence:
+     *  1. **Channel existence** — looks up the `ltPAYCHAN` SLE by `sfChannel`;
+     *     returns `tecNO_ENTRY` if absent.
+     *  2. **Expiry short-circuit** — if `parentCloseTime` has passed either
+     *     `sfCancelAfter` or `sfExpiration`, calls `closeChannel` and returns its
+     *     result. This ensures a stale funding attempt performs useful cleanup
+     *     rather than silently failing.
+     *  3. **Ownership enforcement** — only the account that originally opened the
+     *     channel may fund it; any other submitter receives `tecNO_PERMISSION`.
+     *  4. **Expiration extension** — if `sfExpiration` is present in the
+     *     transaction, the new value must be at least `parentCloseTime +
+     *     sfSettleDelay` (floored by the existing expiration if that is earlier),
+     *     ensuring the destination retains time to claim; violates return
+     *     `temBAD_EXPIRATION`.
+     *  5. **Reserve check** — owner balance must cover `accountReserve(ownerCount)`;
+     *     falls short returns `tecINSUFFICIENT_RESERVE`.
+     *  6. **Balance check** — owner balance must also cover the deposit on top of
+     *     the reserve; falls short returns `tecUNFUNDED`.
+     *  7. **Destination existence** — the channel's destination account must still
+     *     exist; if deleted, returns `tecNO_DST` to prevent locking XRP into an
+     *     unclaimable channel.
+     *
+     *  On success, `sfAmount` on the channel SLE is incremented and the owner's
+     *  `sfBalance` is decremented by the same amount.
+     *
+     *  @return `tesSUCCESS` on success, or a `tec*`/`tem*`/`tef*` error code.
+     */
     TER
     doApply() override;
 
+    /** Per-entry invariant visitor (no-op; reserved for future invariant checks).
+     *
+     *  @param isDelete  True if the entry is being deleted.
+     *  @param before    SLE state before the transaction, or null if new.
+     *  @param after     SLE state after the transaction, or null if deleted.
+     */
     void
     visitInvariantEntry(
         bool isDelete,
         std::shared_ptr<SLE const> const& before,
         std::shared_ptr<SLE const> const& after) override;
 
+    /** Post-apply invariant finalizer (no-op; reserved for future invariant checks).
+     *
+     *  @param tx     The applied transaction.
+     *  @param result The TER returned by `doApply`.
+     *  @param fee    The fee charged for this transaction.
+     *  @param view   Read-only view of the ledger after application.
+     *  @param j      Journal for diagnostic logging.
+     *  @return       Always `true`; no transaction-specific invariants are checked yet.
+     */
     [[nodiscard]] bool
     finalizeInvariants(
         STTx const& tx,
diff --git a/include/xrpl/tx/transactors/permissioned_domain/PermissionedDomainDelete.h b/include/xrpl/tx/transactors/permissioned_domain/PermissionedDomainDelete.h
index 1ac96be2eb..9e6204569f 100644
--- a/include/xrpl/tx/transactors/permissioned_domain/PermissionedDomainDelete.h
+++ b/include/xrpl/tx/transactors/permissioned_domain/PermissionedDomainDelete.h
@@ -4,31 +4,122 @@
 
 namespace xrpl {
 
+/**
+ * Transactor that removes a permissioned domain from the ledger.
+ *
+ * A permissioned domain constrains access to certain ledger operations (AMM,
+ * DEX) to accounts that satisfy a configured set of credentials. This
+ * transactor is the controlled teardown path: the domain owner deletes the
+ * domain SLE, removes it from the owner directory, and recovers the base
+ * reserve that was locked at creation time.
+ *
+ * Unlike `PermissionedDomainSet`, this class intentionally omits a
+ * `checkExtraFeatures` override. The base-class implementation returns `true`
+ * unconditionally, so deletion is always permitted once the domain object
+ * exists — objects must never be stranded by an amendment state change.
+ *
+ * Pipeline: `preflight` (structural check) → `preclaim` (existence + ownership)
+ * → `doApply` (directory removal, owner-count decrement, SLE erasure).
+ */
 class PermissionedDomainDelete : public Transactor
 {
 public:
+    /**
+     * Consequences factory type for this transactor.
+     *
+     * `Normal` indicates that the worst-case impact on the submitting account's
+     * spendable balance is the transaction fee alone. Deleting a domain returns
+     * a reserve increment but does not transfer XRP between parties in an
+     * unbounded way, so no special queuing treatment is required.
+     */
     static constexpr auto kCONSEQUENCES_FACTORY = ConsequencesFactoryType::Normal;
 
     explicit PermissionedDomainDelete(ApplyContext& ctx) : Transactor(ctx)
     {
     }
 
+    /**
+     * Stateless preflight validation — no ledger access.
+     *
+     * Confirms that `sfDomainID` is non-zero. A zero value is structurally
+     * malformed; all ledger-state checks (existence, ownership) are deferred
+     * to `preclaim` so they can influence fee-claiming behaviour.
+     *
+     * @param ctx  The preflight context containing the transaction.
+     * @return `temMALFORMED` if `sfDomainID` is zero; `tesSUCCESS` otherwise.
+     */
     static NotTEC
     preflight(PreflightContext const& ctx);
 
+    /**
+     * Read-only ledger validation — existence and ownership checks.
+     *
+     * Resolves `sfDomainID` to a `PermissionedDomain` SLE via
+     * `keylet::permissionedDomain` and verifies two conditions:
+     * - The domain exists in the current ledger view.
+     * - The submitting account (`sfAccount`) is the domain's `sfOwner`.
+     *
+     * Placing these checks here rather than in `doApply` ensures that an
+     * unauthorized or nonexistent-domain delete still results in a fee claim.
+     *
+     * @param ctx  The preclaim context with read-only ledger view.
+     * @return `tecNO_ENTRY` if the domain does not exist;
+     *         `tecNO_PERMISSION` if the submitter is not the domain owner;
+     *         `tesSUCCESS` otherwise.
+     */
     static TER
     preclaim(PreclaimContext const& ctx);
 
-    /** Attempt to delete the Permissioned Domain. */
+    /**
+     * Apply the domain deletion to the mutable ledger view.
+     *
+     * Performs three mutations in order:
+     * 1. `view().dirRemove()` — removes the SLE from the owner's directory,
+     *    which is required for correct reserve accounting. Failure here
+     *    indicates ledger corruption and returns `tefBAD_LEDGER`.
+     * 2. `adjustOwnerCount(view(), ownerSle, -1, j)` — decrements the owner's
+     *    `sfOwnerCount`, releasing the base reserve locked at creation.
+     * 3. `view().erase(slePd)` — removes the `PermissionedDomain` SLE.
+     *
+     * @return `tefBAD_LEDGER` if the owner-directory entry cannot be removed
+     *         (ledger corruption; marked `LCOV_EXCL` as unreachable in
+     *         production); `tesSUCCESS` otherwise.
+     */
     TER
     doApply() override;
 
+    /**
+     * Per-entry invariant visitor — currently a no-op placeholder.
+     *
+     * Called once for each SLE modified by this transaction. No
+     * domain-deletion-specific invariants are enforced at the entry level yet.
+     *
+     * @param isDelete  `true` if the entry is being deleted.
+     * @param before    SLE state before the transaction (may be null for new
+     *                  entries).
+     * @param after     SLE state after the transaction (may be null for
+     *                  deletions).
+     */
     void
     visitInvariantEntry(
         bool isDelete,
         std::shared_ptr<SLE const> const& before,
         std::shared_ptr<SLE const> const& after) override;
 
+    /**
+     * Post-transaction invariant check — currently a no-op placeholder.
+     *
+     * Called once after all `visitInvariantEntry` calls for this transaction.
+     * No domain-deletion-specific invariants are enforced yet; always returns
+     * `true`.
+     *
+     * @param tx     The transaction being applied.
+     * @param result The TER result from `doApply`.
+     * @param fee    The fee charged for this transaction.
+     * @param view   Read-only view of the post-transaction ledger state.
+     * @param j      Journal for diagnostic logging.
+     * @return `true` unconditionally (no invariant violations possible yet).
+     */
     [[nodiscard]] bool
     finalizeInvariants(
         STTx const& tx,
diff --git a/include/xrpl/tx/transactors/permissioned_domain/PermissionedDomainSet.h b/include/xrpl/tx/transactors/permissioned_domain/PermissionedDomainSet.h
index f5725e7660..f4d0be8b46 100644
--- a/include/xrpl/tx/transactors/permissioned_domain/PermissionedDomainSet.h
+++ b/include/xrpl/tx/transactors/permissioned_domain/PermissionedDomainSet.h
@@ -4,6 +4,18 @@
 
 namespace xrpl {
 
+/** Transactor for the `ttPERMISSIONED_DOMAIN_SET` transaction.
+ *
+ *  Handles both creation of a new `PermissionedDomain` ledger object and
+ *  in-place modification of an existing one. The presence of `sfDomainID` in
+ *  the transaction selects the update path; its absence triggers creation.
+ *
+ *  Permissioned Domains define a named set of accepted credential types
+ *  (issuer + credential-type pairs). Other protocol features can scope access
+ *  to holders of those credentials without enumerating individual accounts.
+ *
+ *  Gated on the `featureCredentials` amendment via `checkExtraFeatures`.
+ */
 class PermissionedDomainSet : public Transactor
 {
 public:
@@ -13,25 +25,103 @@ public:
     {
     }
 
+    /** Gate this transaction type on the `featureCredentials` amendment.
+     *
+     *  Called by `invokePreflight` before `preflight`. Returns `false` (and
+     *  causes `temDISABLED`) when the amendment is not yet active, preventing
+     *  domain creation or modification on pre-amendment ledgers.
+     *
+     *  @param ctx  The preflight context carrying the current rule set.
+     *  @return `true` if `featureCredentials` is enabled; `false` otherwise.
+     */
     static bool
     checkExtraFeatures(PreflightContext const& ctx);
 
+    /** Stateless validation of transaction fields.
+     *
+     *  Delegates to `credentials::checkArray` to enforce that
+     *  `sfAcceptedCredentials` is non-empty, within
+     *  `kMAX_PERMISSIONED_DOMAIN_CREDENTIALS_ARRAY_SIZE` (10), and
+     *  structurally well-formed. Also rejects a zero-valued `sfDomainID` —
+     *  a zero hash is not a valid domain identifier.
+     *
+     *  No ledger state is accessed here; all checks are purely against the
+     *  transaction's own fields.
+     *
+     *  @param ctx  The preflight context.
+     *  @return `tesSUCCESS` on success; `temMALFORMED` for a zero
+     *      `sfDomainID`; a `tem` code from `checkArray` for invalid
+     *      credential structure.
+     */
     static NotTEC
     preflight(PreflightContext const& ctx);
 
+    /** Read-only ledger state checks.
+     *
+     *  Verifies:
+     *  - The submitting account exists on ledger (guard against internal
+     *    inconsistency; returns `tefINTERNAL` if missing).
+     *  - Every `sfIssuer` in `sfAcceptedCredentials` has a live `AccountRoot`
+     *    on ledger; a domain referencing a non-existent issuer would be
+     *    permanently unresolvable (`tecNO_ISSUER`).
+     *  - For update operations (`sfDomainID` present): the domain SLE exists
+     *    (`tecNO_ENTRY`) and is owned by the submitting account
+     *    (`tecNO_PERMISSION`).
+     *
+     *  @param ctx  The preclaim context carrying the read-only ledger view.
+     *  @return `tesSUCCESS`, `tefINTERNAL`, `tecNO_ISSUER`, `tecNO_ENTRY`,
+     *      or `tecNO_PERMISSION`.
+     */
     static TER
     preclaim(PreclaimContext const& ctx);
 
-    /** Attempt to create the Permissioned Domain. */
+    /** Apply the transaction, creating or updating a PermissionedDomain SLE.
+     *
+     *  Canonicalises `sfAcceptedCredentials` via `credentials::makeSorted`
+     *  before writing, ensuring deterministic storage order regardless of
+     *  submission order.
+     *
+     *  **Update path** (`sfDomainID` present): replaces the existing domain
+     *  SLE's credential array in-place; no reserve change occurs.
+     *
+     *  **Create path** (`sfDomainID` absent): checks that the account's XRP
+     *  balance covers `accountReserve(ownerCount + 1)`, allocates a new SLE
+     *  keyed by `keylet::permissionedDomain(account_, sfSequence)`, inserts it
+     *  into the owner directory, and increments the owner count by one.
+     *
+     *  The transaction sequence number is used as the domain's key
+     *  differentiator, making each domain globally unique without a separate
+     *  ID-generation step.
+     *
+     *  @return `tesSUCCESS`; `tecINSUFFICIENT_RESERVE` if the account cannot
+     *      cover the new reserve; `tecDIR_FULL` if the owner directory has no
+     *      space; `tefINTERNAL` (unreachable in normal operation) if the owner
+     *      or domain SLE is unexpectedly absent.
+     */
     TER
     doApply() override;
 
+    /** Per-entry invariant visitor — currently a no-op (future work).
+     *
+     *  @param isDelete  True when the entry is being deleted.
+     *  @param before    The SLE state before the transaction.
+     *  @param after     The SLE state after the transaction.
+     */
     void
     visitInvariantEntry(
         bool isDelete,
         std::shared_ptr<SLE const> const& before,
         std::shared_ptr<SLE const> const& after) override;
 
+    /** Post-transaction invariant finalization — currently a no-op (future work).
+     *
+     *  @param tx     The applied transaction.
+     *  @param result The TER code returned by `doApply`.
+     *  @param fee    The fee charged.
+     *  @param view   The post-transaction read view.
+     *  @param j      Journal for diagnostic logging.
+     *  @return Always `true`; no transaction-specific invariants are checked yet.
+     */
     [[nodiscard]] bool
     finalizeInvariants(
         STTx const& tx,
diff --git a/include/xrpl/tx/transactors/system/Batch.h b/include/xrpl/tx/transactors/system/Batch.h
index 82e5bf8f78..b744dfc819 100644
--- a/include/xrpl/tx/transactors/system/Batch.h
+++ b/include/xrpl/tx/transactors/system/Batch.h
@@ -6,39 +6,192 @@
 
 namespace xrpl {
 
+/** Transactor for the `ttBATCH` transaction type.
+ *
+ *  Bundles two to eight inner XRPL transactions into a single outer
+ *  transaction with one of four configurable execution policies
+ *  (`tfAllOrNothing`, `tfOnlyOne`, `tfUntilFailure`, `tfIndependent`).
+ *  This lets operations that belong together — such as a DEX offer paired
+ *  with a trust-line establishment — be submitted composably without the
+ *  race conditions and ordering problems of independent submissions.
+ *
+ *  The outer transaction handles fee deduction and sequence/ticket
+ *  consumption via the base-class `apply()` machinery. Inner transaction
+ *  execution is delegated to `applyBatchTransactions()` in `apply.cpp`,
+ *  which is called by `applyTransaction()` only after the outer apply
+ *  succeeds. Each inner transaction runs in its own `perTxBatchView`
+ *  sandbox layered over a shared `wholeBatchView`; `wholeBatchView` is
+ *  merged into the authoritative ledger view only if at least one inner
+ *  transaction was applied.
+ *
+ *  @note Vault (`ttVAULT_*`), Loan Broker (`ttLOAN_BROKER_*`), and Loan
+ *      (`ttLOAN_*`) transaction types are forbidden as inner transactions
+ *      and are enumerated in `kDISABLED_TX_TYPES`.
+ */
 class Batch : public Transactor
 {
 public:
+    /** Uses standard consequence analysis; does not unconditionally block
+     *  the transaction queue the way a `Blocker`-factory transactor does.
+     */
     static constexpr auto kCONSEQUENCES_FACTORY = ConsequencesFactoryType::Normal;
 
     explicit Batch(ApplyContext& ctx) : Transactor(ctx)
     {
     }
 
+    /** Compute the total base fee for a Batch transaction.
+     *
+     *  The fee is additive:
+     *  - One base fee for the outer Batch transaction itself.
+     *  - One base fee per inner transaction (preventing Batch from being a
+     *    cost-avoidance mechanism relative to submitting transactions
+     *    individually).
+     *  - One base fee per entry in `sfBatchSigners` (mirrors the multi-sign
+     *    fee structure used elsewhere in the protocol).
+     *
+     *  Overflow is checked at every accumulation step. If any addition would
+     *  overflow, `INITIAL_XRP` is returned as a sentinel — consistent with
+     *  the defensive pattern used across the XRPL fee pipeline.
+     *
+     *  @param view The current ledger view, used to obtain the base fee.
+     *  @param tx   The Batch transaction being evaluated.
+     *  @return The total base fee in drops, or `INITIAL_XRP` on overflow.
+     */
     static XRPAmount
     calculateBaseFee(ReadView const& view, STTx const& tx);
 
+    /** Return the set of flags valid on the outer Batch transaction.
+     *
+     *  Returns `tfBatchMask`, which admits exactly the four mutually
+     *  exclusive execution-policy flags and rejects `tfInnerBatchTxn` on
+     *  the outer transaction (only inner transactions carry that flag).
+     *
+     *  @param ctx Preflight context (unused beyond satisfying the static
+     *      interface; the mask is unconditional).
+     *  @return The bitmask of valid outer-Batch flags.
+     */
     static std::uint32_t
     getFlagsMask(PreflightContext const& ctx);
 
+    /** Validate the structural integrity of a Batch transaction.
+     *
+     *  Runs before signature verification and has no ledger access.
+     *  Checks (in order):
+     *  1. Exactly one execution-policy flag is set (enforced via
+     *     `std::popcount`).
+     *  2. `sfRawTransactions` contains at least 2 and at most
+     *     `maxBatchTxCount` (8) entries.
+     *  3. Each inner transaction: is not a `ttBATCH` (no nesting), is not
+     *     a disabled type (`kDISABLED_TX_TYPES`), carries `tfInnerBatchTxn`,
+     *     has an empty `sfSigningPubKey` and no `sfTxnSignature`/`sfSigners`,
+     *     has a zero XRP fee, and passes its own `xrpl::preflight()` call
+     *     with the `tapBATCH` flag and the outer batch's ID as
+     *     `parentBatchId`.
+     *  4. Each inner transaction has either a non-zero `sfSequence` or an
+     *     `sfTicketSequence`, but not both.
+     *  5. For `tfAllOrNothing` and `tfUntilFailure` modes, duplicate
+     *     sequence or ticket values across inner transactions from the same
+     *     account are rejected (these modes commit or abort as a unit, so
+     *     consuming the same account slot twice would be incoherent).
+     *
+     *  @param ctx The preflight context for the outer Batch transaction.
+     *  @return `tesSUCCESS` if the batch is structurally valid; a `tem*`
+     *      code otherwise (e.g., `temINVALID_INNER_BATCH` for disabled
+     *      types, `temINVALID_FLAG` for multiple policy flags).
+     */
     static NotTEC
     preflight(PreflightContext const& ctx);
 
+    /** Validate batch-signer authorization after the outer signature is
+     *  verified.
+     *
+     *  Called by the framework only after the outer transaction's own
+     *  cryptographic signature has been accepted, granting confidence that
+     *  the submitter is who they claim to be. This hook:
+     *  1. Builds `requiredSigners` — every inner-transaction account that
+     *     differs from the outer account, plus any `sfCounterparty` fields
+     *     that differ from the outer account.
+     *  2. Validates `sfBatchSigners` against that set with a bidirectional
+     *     pass: extraneous signers (not in `requiredSigners`) and missing
+     *     signers (in `requiredSigners` but absent from `sfBatchSigners`)
+     *     both fail, as do duplicates. The outer account may not appear in
+     *     `sfBatchSigners`.
+     *  3. Calls `ctx.tx.checkBatchSign()` to verify the cryptographic
+     *     signatures of all batch signers.
+     *
+     *  @param ctx The preflight context, guaranteed to be post-outer-sig.
+     *  @return `tesSUCCESS` if all batch signers are valid and sufficient;
+     *      a `tem*` code otherwise.
+     */
     static NotTEC
     preflightSigValidated(PreflightContext const& ctx);
 
+    /** Verify signatures at the preclaim stage, where ledger state is
+     *  available.
+     *
+     *  Runs two checks in sequence:
+     *  1. `Transactor::checkSign` — validates the outer account's
+     *     signature (regular key, master key, or signer list).
+     *  2. `Transactor::checkBatchSign` — re-validates batch-signer
+     *     credentials against on-ledger `RegularKey`/`SignerList` objects,
+     *     which are only accessible in preclaim.
+     *
+     *  The split from `preflightSigValidated` is intentional: preflight
+     *  can only check cryptographic correctness; preclaim can additionally
+     *  confirm on-ledger authorization state.
+     *
+     *  @param ctx The preclaim context, providing a read-only ledger view.
+     *  @return `tesSUCCESS` if both checks pass; a `tef*` code otherwise.
+     */
     static NotTEC
     checkSign(PreclaimContext const& ctx);
 
+    /** Apply the outer Batch transaction.
+     *
+     *  Returns `tesSUCCESS` immediately. The outer Batch itself writes
+     *  nothing to the ledger beyond the fee deduction and sequence/ticket
+     *  consumption handled by the base-class `apply()` method. Inner
+     *  transaction execution is performed by `applyBatchTransactions()` in
+     *  `apply.cpp`, invoked by `applyTransaction()` after this method
+     *  returns.
+     *
+     *  @return Always `tesSUCCESS`.
+     */
     TER
     doApply() override;
 
+    /** Invariant visitor for Batch — currently a no-op.
+     *
+     *  Inner-transaction invariant checking is handled by the individual
+     *  inner transactors in their own apply contexts. The outer Batch
+     *  transaction does not directly mutate ledger objects beyond the
+     *  base-class fee/sequence handling.
+     *
+     *  @param isDelete `true` if the entry is being deleted.
+     *  @param before   The SLE state before the transaction; may be null
+     *      for newly created entries.
+     *  @param after    The SLE state after the transaction; may be null for
+     *      deleted entries.
+     */
     void
     visitInvariantEntry(
         bool isDelete,
         std::shared_ptr<SLE const> const& before,
         std::shared_ptr<SLE const> const& after) override;
 
+    /** Finalize invariant checks for Batch — currently a no-op.
+     *
+     *  Returns `true` unconditionally. Inner-transaction invariants are
+     *  finalized within each inner transactor's own apply context.
+     *
+     *  @param tx     The Batch transaction.
+     *  @param result The TER code produced by `doApply`.
+     *  @param fee    The fee deducted from the submitting account.
+     *  @param view   A read-only view of the ledger after application.
+     *  @param j      Journal for diagnostic logging.
+     *  @return Always `true` (no outer-Batch invariant violations possible).
+     */
     [[nodiscard]] bool
     finalizeInvariants(
         STTx const& tx,
@@ -47,6 +200,15 @@ public:
         ReadView const& view,
         beast::Journal const& j) override;
 
+    /** Transaction types that may not appear as inner transactions in a
+     *  Batch.
+     *
+     *  Vault (`ttVAULT_*`), Loan Broker (`ttLOAN_BROKER_*`), and Loan
+     *  (`ttLOAN_*`) families are blocked because their multi-ledger-object
+     *  state machines are difficult to reason about under batch atomicity
+     *  semantics. `preflight` rejects any inner transaction whose type
+     *  appears here with `temINVALID_INNER_BATCH`.
+     */
     static constexpr auto kDISABLED_TX_TYPES = std::to_array<TxType>({
         ttVAULT_CREATE,
         ttVAULT_SET,
diff --git a/include/xrpl/tx/transactors/system/Change.h b/include/xrpl/tx/transactors/system/Change.h
index c3a3ff81ff..f23f3f7927 100644
--- a/include/xrpl/tx/transactors/system/Change.h
+++ b/include/xrpl/tx/transactors/system/Change.h
@@ -4,6 +4,23 @@
 
 namespace xrpl {
 
+/** Applies consensus-driven, system-level protocol mutations to a closed ledger.
+ *
+ *  `Change` handles three distinct pseudo-transaction types — `ttAMENDMENT`,
+ *  `ttFEE`, and `ttUNL_MODIFY` — under one class, dispatching in `doApply()`
+ *  to `applyAmendment()`, `applyFee()`, or `applyUNLModify()` based on the
+ *  transaction type.
+ *
+ *  These transactions are synthesized internally during ledger close and are
+ *  never submitted by real accounts. Accordingly, `Transactor::invokePreflight<Change>`
+ *  is fully specialized (in `Change.cpp`) to bypass the normal amendment-gating,
+ *  flag-mask, and signature-validation sequence, performing only `preflight0`
+ *  plus zero-account/zero-fee/zero-sequence checks.
+ *
+ *  @note `calculateBaseFee()` unconditionally returns zero — pseudo-transactions
+ *      are not subject to fee markets or reserve checks.
+ *  @see EnableAmendment, SetFee, UNLModify
+ */
 class Change : public Transactor
 {
 public:
@@ -13,17 +30,33 @@ public:
     {
     }
 
+    /** Dispatch to `applyAmendment()`, `applyFee()`, or `applyUNLModify()`.
+     *
+     *  The `default` branch is `UNREACHABLE`; `preclaim()` rejects unknown
+     *  transaction types before `doApply()` is ever called.
+     *
+     *  @return `tesSUCCESS` on success, a `tef*` code on protocol-level
+     *      constraint violations, or `temINVALID_FLAG` for conflicting amendment
+     *      flags.
+     */
     TER
     doApply() override;
+
+    /** Assert that the synthesized account field is the zero account. */
     void
     preCompute() override;
 
+    /** No-op; `Change` has no transaction-specific invariant entries yet. */
     void
     visitInvariantEntry(
         bool isDelete,
         std::shared_ptr<SLE const> const& before,
         std::shared_ptr<SLE const> const& after) override;
 
+    /** No-op; `Change` has no transaction-specific invariant finalization yet.
+     *
+     *  @return Always `true`.
+     */
     [[nodiscard]] bool
     finalizeInvariants(
         STTx const& tx,
@@ -32,28 +65,90 @@ public:
         ReadView const& view,
         beast::Journal const& j) override;
 
+    /** Return zero; pseudo-transactions carry no fee.
+     *
+     *  @return `XRPAmount{0}` unconditionally.
+     */
     static XRPAmount
     calculateBaseFee(ReadView const& view, STTx const& tx)
     {
         return XRPAmount{0};
     }
 
+    /** Validate that this transaction is being applied to a closed ledger and
+     *  enforce format compatibility for `ttFEE` transactions.
+     *
+     *  Returns `temINVALID` when the view is open, because the open/closed
+     *  distinction is not available during preflight. For `ttFEE`, the set of
+     *  required and forbidden fields differs depending on whether `featureXRPFees`
+     *  is active: the legacy format uses fee-unit integers (`sfBaseFee`,
+     *  `sfReferenceFeeUnits`, `sfReserveBase`, `sfReserveIncrement`), while the
+     *  new format uses drop amounts (`sfBaseFeeDrops`, `sfReserveBaseDrops`,
+     *  `sfReserveIncrementDrops`). Mixing field sets returns `temMALFORMED` or
+     *  `temDISABLED`. `ttAMENDMENT` and `ttUNL_MODIFY` require no extra checks
+     *  here; unknown types return `temUNKNOWN`.
+     *
+     *  @param ctx Read-only context including the ledger view and transaction.
+     *  @return `tesSUCCESS`, `temINVALID`, `temMALFORMED`, `temDISABLED`, or
+     *      `temUNKNOWN`.
+     */
     static TER
     preclaim(PreclaimContext const& ctx);
 
 private:
+    /** Record a `tfGotMajority` / `tfLostMajority` event, or activate an
+     *  amendment on the ledger.
+     *
+     *  Writes to the `keylet::amendments()` SLE. On activation, calls
+     *  `AmendmentTable::enable()` and, if the amendment is unsupported by this
+     *  node, invokes `NetworkOPs::setAmendmentBlocked()` to halt consensus
+     *  participation.
+     *
+     *  @return `tesSUCCESS`, `tefALREADY` (duplicate majority record or removal
+     *      of a non-existent majority), or `temINVALID_FLAG` (both majority flags
+     *      set simultaneously).
+     */
     TER
     applyAmendment();
 
+    /** Write the new fee schedule into the `keylet::fees()` SLE.
+     *
+     *  Under `featureXRPFees`, sets the drop-denominated fields and explicitly
+     *  removes the legacy fee-unit fields via `makeFieldAbsent` to prevent stale
+     *  data from persisting. Without the feature, the legacy fields are written
+     *  and the drop fields remain absent.
+     *
+     *  @return `tesSUCCESS` always.
+     */
     TER
     applyFee();
 
+    /** Nominate a validator for disabling or re-enabling in the Negative UNL.
+     *
+     *  Only valid on flag ledgers (`isFlagLedger(view().seq())`); returns
+     *  `tefFAILURE` on any other ledger sequence. Enforces these consistency
+     *  invariants on `keylet::negativeUNL()`:
+     *  - At most one pending `sfValidatorToDisable` and one `sfValidatorToReEnable`.
+     *  - A validator cannot be nominated for disabling if it is already in the
+     *    Negative UNL.
+     *  - A validator cannot be nominated for re-enabling if it is not in the
+     *    Negative UNL.
+     *  - The same validator cannot simultaneously occupy both pending slots.
+     *
+     *  @return `tesSUCCESS` on success, `tefFAILURE` for any format error or
+     *      invariant violation.
+     */
     TER
     applyUNLModify();
 };
 
+/** Semantic alias for `Change` when dispatching amendment activation pseudo-transactions. */
 using EnableAmendment = Change;
+
+/** Semantic alias for `Change` when dispatching fee-schedule update pseudo-transactions. */
 using SetFee = Change;
+
+/** Semantic alias for `Change` when dispatching Negative UNL modification pseudo-transactions. */
 using UNLModify = Change;
 
 }  // namespace xrpl
diff --git a/include/xrpl/tx/transactors/system/LedgerStateFix.h b/include/xrpl/tx/transactors/system/LedgerStateFix.h
index 7e6a89ea0b..8caa694dcf 100644
--- a/include/xrpl/tx/transactors/system/LedgerStateFix.h
+++ b/include/xrpl/tx/transactors/system/LedgerStateFix.h
@@ -1,40 +1,141 @@
+/** @file
+ *  Declares the LedgerStateFix transactor for the `ttLEDGER_STATE_FIX`
+ *  transaction type, a protocol-level maintenance mechanism that corrects
+ *  corrupted or inconsistent ledger state.
+ *
+ *  Gated on the `fixNFTokenPageLinks` amendment. New repair operations may
+ *  be introduced in future amendments by extending the `FixType` enum.
+ */
+
 #pragma once
 
 #include <xrpl/tx/Transactor.h>
 
 namespace xrpl {
 
+/** Repairs corrupted ledger state via a protocol-level maintenance transaction.
+ *
+ *  `LedgerStateFix` implements `ttLEDGER_STATE_FIX`, which allows network
+ *  participants to correct inconsistent ledger entries. The specific repair
+ *  operation is selected by the `sfLedgerFixType` field; currently the only
+ *  supported type is `NfTokenPageLink`, which heals broken forward/backward
+ *  links in an account's NFToken page chain.
+ *
+ *  The fee is one owner reserve (same as `AccountDelete`) to deter frivolous
+ *  submissions. The fee is non-refundable even when no repair is needed.
+ *
+ *  @note Amendment gating is handled by the framework before `preflight` is
+ *      called; no manual amendment check is required inside the lifecycle
+ *      methods.
+ */
 class LedgerStateFix : public Transactor
 {
 public:
+    /** Identifies which ledger-repair operation the transaction performs.
+     *
+     *  The `sfLedgerFixType` field in the transaction carries one of these
+     *  values as a `uint16_t`. All three lifecycle methods dispatch on this
+     *  enum; unknown values are rejected at `preflight` with
+     *  `tefINVALID_LEDGER_FIX_TYPE`.
+     */
     enum class FixType : std::uint16_t {
+        /** Repair broken forward/backward links between NFToken page SLEs
+         *  in an account's NFToken directory.
+         *
+         *  Requires `sfOwner` to be present in the transaction.
+         */
         NfTokenPageLink = 1,
     };
 
+    /** Not a queue blocker; later transactions from the same account may
+     *  proceed without waiting for this one to be applied.
+     */
     static constexpr auto kCONSEQUENCES_FACTORY = ConsequencesFactoryType::Normal;
 
     explicit LedgerStateFix(ApplyContext& ctx) : Transactor(ctx)
     {
     }
 
+    /** Validate the transaction's static fields.
+     *
+     *  Checks that `sfLedgerFixType` maps to a known `FixType`. For
+     *  `NfTokenPageLink`, also verifies that `sfOwner` is present.
+     *
+     *  @param ctx  The preflight context; no ledger access is available here.
+     *  @return `tesSUCCESS` on success; `tefINVALID_LEDGER_FIX_TYPE` if the
+     *      fix type is unrecognised; `temINVALID` if a required field is
+     *      absent for the selected fix type.
+     */
     static NotTEC
     preflight(PreflightContext const& ctx);
 
+    /** Compute the fee for this transaction.
+     *
+     *  Returns one owner reserve, matching the pricing strategy used by
+     *  `AccountDelete`. The elevated fee serves as an economic deterrent
+     *  against frivolous repair submissions.
+     *
+     *  @param view  The current read-only ledger view.
+     *  @param tx    The transaction being evaluated.
+     *  @return The fee in drops (one owner reserve).
+     */
     static XRPAmount
     calculateBaseFee(ReadView const& view, STTx const& tx);
 
+    /** Verify ledger preconditions before applying the repair.
+     *
+     *  For `NfTokenPageLink`, confirms that the account identified by
+     *  `sfOwner` exists in the ledger. This check is deferred to preclaim
+     *  (rather than preflight) because ledger state may change between
+     *  submission and application.
+     *
+     *  @param ctx  The preclaim context, providing read-only ledger access.
+     *  @return `tesSUCCESS` if preconditions are satisfied;
+     *      `tecOBJECT_NOT_FOUND` if the owner account does not exist;
+     *      `tecINTERNAL` (unreachable in practice) if an unknown fix type
+     *      reaches this stage despite passing preflight.
+     */
     static TER
     preclaim(PreclaimContext const& ctx);
 
+    /** Execute the ledger repair operation.
+     *
+     *  For `NfTokenPageLink`, calls `nft::repairNFTokenDirectoryLinks` to
+     *  walk the owner's NFToken page chain and correct any broken links.
+     *
+     *  @return `tesSUCCESS` if the repair completed; `tecFAILED_PROCESSING`
+     *      if the repair helper could not make progress; `tecINTERNAL`
+     *      (unreachable in practice) if an unknown fix type reaches this
+     *      stage despite passing preflight.
+     */
     TER
     doApply() override;
 
+    /** No-op: no transaction-specific invariants are currently defined.
+     *
+     *  Reserved for future use. Accumulates nothing.
+     *
+     *  @param isDelete  True if the entry was erased.
+     *  @param before    The SLE state before the transaction.
+     *  @param after     The SLE state after the transaction.
+     */
     void
     visitInvariantEntry(
         bool isDelete,
         std::shared_ptr<SLE const> const& before,
         std::shared_ptr<SLE const> const& after) override;
 
+    /** No-op: no transaction-specific invariants are currently defined.
+     *
+     *  Reserved for future use. Always returns `true`.
+     *
+     *  @param tx      The transaction that was applied.
+     *  @param result  The tentative TER from `doApply`.
+     *  @param fee     The fee consumed.
+     *  @param view    The post-apply ledger view.
+     *  @param j       Journal for diagnostics.
+     *  @return Always `true` (no invariants to check yet).
+     */
     [[nodiscard]] bool
     finalizeInvariants(
         STTx const& tx,
diff --git a/include/xrpl/tx/transactors/system/TicketCreate.h b/include/xrpl/tx/transactors/system/TicketCreate.h
index 9c9289e1b5..e3050ee3dd 100644
--- a/include/xrpl/tx/transactors/system/TicketCreate.h
+++ b/include/xrpl/tx/transactors/system/TicketCreate.h
@@ -4,68 +4,153 @@
 
 namespace xrpl {
 
+/** Transactor for the `TicketCreate` transaction type.
+ *
+ *  Mints one or more `Ticket` ledger objects in a single transaction.
+ *  Tickets reserve a contiguous block of future account sequence numbers,
+ *  allowing the owner to submit transactions out-of-order or in parallel
+ *  without violating the normal strict sequence increment requirement.
+ *
+ *  Uses `ConsequencesFactoryType::Custom` so that `makeTxConsequences` can
+ *  report the exact number of sequence numbers consumed (equal to
+ *  `sfTicketCount`), enabling the transaction queue to correctly order
+ *  transactions that reference the newly minted ticket sequences.
+ *
+ *  @note `TicketCreate` is the only transactor that advances an account's
+ *      `sfSequence` by more than one in a single application.
+ */
 class TicketCreate : public Transactor
 {
 public:
     static constexpr auto kCONSEQUENCES_FACTORY = ConsequencesFactoryType::Custom;
 
+    /** Minimum number of tickets that may be created in one transaction.
+     *
+     *  A count of zero is nonsensical and is rejected by `preflight` with
+     *  `temINVALID_COUNT`.
+     */
     constexpr static std::uint32_t kMIN_VALID_COUNT = 1;
 
-    // A note on how the maxValidCount was determined.  The goal is for
-    // a single TicketCreate transaction to not use more compute power than
-    // a single compute-intensive Payment.
-    //
-    // Timing was performed using a MacBook Pro laptop and a release build
-    // with asserts off.  20 measurements were taken of each of the Payment
-    // and TicketCreate transactions and averaged to get timings.
-    //
-    // For the example compute-intensive Payment a Discrepancy unit test
-    // unit test Payment with 3 paths was chosen.  With all the latest
-    // amendments enabled, that Payment::doApply() operation took, on
-    // average, 1.25 ms.
-    //
-    // Using that same test set up creating 250 Tickets in a single
-    // TicketCreate::doApply() in a unit test took, on average, 1.21 ms.
-    //
-    // So, for the moment, a single transaction creating 250 Tickets takes
-    // about the same compute time as a single compute-intensive payment.
-    //
-    // October 2018.
+    /** Maximum number of tickets that may be created in one transaction.
+     *
+     *  Calibrated so that a single `TicketCreate` consuming this many tickets
+     *  takes roughly the same validator CPU as a compute-intensive three-path
+     *  `Payment`. Benchmarked on a MacBook Pro release build (asserts off):
+     *  250 tickets averaged 1.21 ms vs. 1.25 ms for the reference Payment.
+     *  Exceeding this value is rejected by `preflight` with `temINVALID_COUNT`.
+     *
+     *  @note Benchmark performed October 2018.
+     */
     constexpr static std::uint32_t kMAX_VALID_COUNT = 250;
 
-    // The maximum number of Tickets an account may hold.  If a
-    // TicketCreate would cause an account to own more than this many
-    // tickets, then the TicketCreate will fail.
-    //
-    // The number was chosen arbitrarily and is an effort toward avoiding
-    // ledger-stuffing with Tickets.
+    /** Maximum number of tickets an account may hold at one time.
+     *
+     *  If a `TicketCreate` would push the account's net ticket inventory
+     *  (existing + added − consumed) above this threshold, `preclaim` rejects
+     *  the transaction with `tecDIR_FULL`. The limit is an anti-ledger-stuffing
+     *  measure and was chosen to match `kMAX_VALID_COUNT`.
+     */
     constexpr static std::uint32_t kMAX_TICKET_THRESHOLD = 250;
 
     explicit TicketCreate(ApplyContext& ctx) : Transactor(ctx)
     {
     }
 
+    /** Build the `TxConsequences` for a `TicketCreate` transaction.
+     *
+     *  Reports `sfTicketCount` as the number of sequence numbers consumed so
+     *  the transaction queue can correctly evaluate ordering constraints for
+     *  any later transaction that references one of the newly reserved ticket
+     *  sequences.
+     *
+     *  @param ctx Preflight context providing access to the transaction fields.
+     *  @return A `TxConsequences` object encoding the multi-sequence claim.
+     */
     static TxConsequences
     makeTxConsequences(PreflightContext const& ctx);
 
-    /** Enforce constraints beyond those of the Transactor base class. */
+    /** Stateless validation of `sfTicketCount`.
+     *
+     *  Reads `sfTicketCount` from the transaction and rejects values outside
+     *  `[kMIN_VALID_COUNT, kMAX_VALID_COUNT]`. No ledger state is accessed.
+     *
+     *  @param ctx Preflight context providing access to the transaction fields.
+     *  @return `tesSUCCESS` if the count is in range; `temINVALID_COUNT`
+     *      otherwise.
+     */
     static NotTEC
     preflight(PreflightContext const& ctx);
 
-    /** Enforce constraints beyond those of the Transactor base class. */
+    /** State-aware validation of the account's ticket inventory.
+     *
+     *  Computes the net ticket delta after applying this transaction:
+     *  `curTicketCount + addedTickets − consumedTickets`. The `consumedTickets`
+     *  term is 1 when the transaction itself was submitted using a ticket
+     *  (i.e. `getSeqProxy().isTicket()` is true), otherwise 0.
+     *
+     *  @param ctx Preclaim context providing read-only ledger access.
+     *  @return `tesSUCCESS` if the net delta stays within
+     *      `kMAX_TICKET_THRESHOLD`; `tecDIR_FULL` if the threshold would be
+     *      exceeded; `terNO_ACCOUNT` if the submitting account does not exist.
+     */
     static TER
     preclaim(PreclaimContext const& ctx);
 
-    /** Precondition: fee collection is likely.  Attempt to create ticket(s). */
+    /** Create the requested tickets and update account state.
+     *
+     *  Execution steps:
+     *  1. Checks the account's pre-fee balance against the reserve required
+     *     for `ticketCount` additional owned objects, using `preFeeBalance_`
+     *     so the account may dip into its reserve to pay the fee.
+     *  2. Reads `sfSequence` from the account root (already incremented by the
+     *     transaction machinery) as the first ticket sequence number, then
+     *     sanity-checks that `txSeq == firstTicketSeq − 1` (or `txSeq == 0`
+     *     for ticket-submitted transactions).
+     *  3. Creates one `Ticket` SLE per requested ticket, inserts each into the
+     *     ledger, and links it into the account's owner directory, storing the
+     *     directory page in `sfOwnerNode`.
+     *  4. Advances `sfSequence` by `ticketCount` — the only transactor in XRPL
+     *     that increments the account sequence by more than one.
+     *  5. Increments `sfTicketCount` on the account root and calls
+     *     `adjustOwnerCount` with `+ticketCount` to update the reserve
+     *     obligation.
+     *
+     *  @return `tesSUCCESS` on success; `tecINSUFFICIENT_RESERVE` if the
+     *      account cannot cover the reserve for the new tickets; `tecDIR_FULL`
+     *      if the owner directory is full; `tefINTERNAL` for ledger
+     *      corruption (should not occur in practice).
+     */
     TER
     doApply() override;
 
+    /** Per-entry invariant visitor (reserved for future use).
+     *
+     *  No transaction-specific invariants are currently enforced. The override
+     *  exists as a placeholder for future checks on `Ticket` SLE mutations.
+     *
+     *  @param isDelete True if the entry is being deleted.
+     *  @param before SLE state before the transaction, or nullptr if new.
+     *  @param after SLE state after the transaction, or nullptr if deleted.
+     */
     void
     visitInvariantEntry(
         bool isDelete,
         std::shared_ptr<SLE const> const& before,
         std::shared_ptr<SLE const> const& after) override;
 
+    /** Post-transaction invariant check (reserved for future use).
+     *
+     *  No transaction-specific invariants are currently enforced. Always
+     *  returns `true`.
+     *
+     *  @param tx The applied transaction.
+     *  @param result The TER produced by `doApply`.
+     *  @param fee The fee charged.
+     *  @param view Read-only view of the resulting ledger state.
+     *  @param j Journal for diagnostic logging.
+     *  @return `true` unconditionally; future implementations may return
+     *      `false` to signal invariant violations.
+     */
     [[nodiscard]] bool
     finalizeInvariants(
         STTx const& tx,
diff --git a/include/xrpl/tx/transactors/token/Clawback.h b/include/xrpl/tx/transactors/token/Clawback.h
index 6a5927fb02..6ccfefc7d5 100644
--- a/include/xrpl/tx/transactors/token/Clawback.h
+++ b/include/xrpl/tx/transactors/token/Clawback.h
@@ -4,6 +4,21 @@
 
 namespace xrpl {
 
+/** Executes a ttCLAWBACK transaction on the XRP Ledger.
+ *
+ *  Allows an issuer to reclaim tokens from a holder's account, supporting
+ *  both IOU trust-line tokens and Multi-Purpose Tokens (MPT). The amount
+ *  recovered is capped at the holder's spendable balance; any freeze state
+ *  the issuer may have applied to the account is bypassed for this purpose.
+ *
+ *  Clawback is rejected against AMM liquidity-pool accounts (use
+ *  `AMMClawback` instead) and, when `featureSingleAssetVault` is active,
+ *  against pseudo-accounts.
+ *
+ *  @note For IOU tokens the holder identity is encoded inside `sfAmount`'s
+ *      issuer field; `sfHolder` must be absent. For MPT tokens `sfHolder`
+ *      carries the holder account and must be present.
+ */
 class Clawback : public Transactor
 {
 public:
@@ -13,21 +28,84 @@ public:
     {
     }
 
+    /** Validate the structural correctness of the clawback transaction fields.
+     *
+     *  Dispatches to a template specialisation based on the asset type carried
+     *  in `sfAmount` (IOU `Issue` or `MPTIssue`). For IOUs, rejects if
+     *  `sfHolder` is present, if the amount is XRP or non-positive, or if the
+     *  issuer and holder are the same account. For MPTs, additionally gates on
+     *  the `featureMPTokensV1` amendment and requires `sfHolder` to be present
+     *  and the amount to be within `maxMPTokenAmount`.
+     *
+     *  @param ctx Stateless preflight context carrying the transaction and rules.
+     *  @return `tesSUCCESS` if the transaction is structurally valid; a `tem*`
+     *      error code otherwise.
+     */
     static NotTEC
     preflight(PreflightContext const& ctx);
 
+    /** Verify ledger preconditions required for clawback to succeed.
+     *
+     *  Confirms that both the issuer and holder accounts exist, that the holder
+     *  is neither an AMM account nor (when `featureSingleAssetVault` is active)
+     *  a pseudo-account, and then dispatches to the asset-type-specific helper.
+     *
+     *  For IOU tokens the helper checks that `lsfAllowTrustLineClawback` is set
+     *  on the issuer and that `lsfNoFreeze` is not set, that the trust line
+     *  exists with the correct balance orientation, and that the holder's
+     *  spendable balance is non-zero. For MPT tokens it checks `lsfMPTCanClawback`
+     *  on the issuance object, that the caller is the issuance's issuer, that the
+     *  holder's `MPToken` object exists, and that the spendable balance is
+     *  non-zero.
+     *
+     *  @param ctx Read-only preclaim context providing the current ledger view.
+     *  @return `tesSUCCESS` on success; `tecNO_PERMISSION`, `tecNO_LINE`,
+     *      `tecAMM_ACCOUNT`, `tecPSEUDO_ACCOUNT`, `tecOBJECT_NOT_FOUND`,
+     *      `tecINSUFFICIENT_FUNDS`, or `terNO_ACCOUNT` on failure.
+     */
     static TER
     preclaim(PreclaimContext const& ctx);
 
+    /** Apply the clawback, moving tokens from the holder back to the issuer.
+     *
+     *  Calls `directSendNoFee` to transfer `min(spendableBalance, sfAmount)`
+     *  tokens without applying any transfer fee. The spendable balance is
+     *  computed via `accountHolds` with `fhIGNORE_FREEZE`, so clawback
+     *  succeeds up to the available balance even when the account is frozen.
+     *
+     *  @return `tesSUCCESS` on success; `tecINTERNAL` if an internal
+     *      consistency check fails (should not occur in practice).
+     */
     TER
     doApply() override;
 
+    /** Per-entry invariant visitor hook for the clawback transactor.
+     *
+     *  Currently a no-op; reserved for future transaction-specific invariant
+     *  checks.
+     *
+     *  @param isDelete True if the entry is being deleted.
+     *  @param before The SLE state before the transaction.
+     *  @param after The SLE state after the transaction.
+     */
     void
     visitInvariantEntry(
         bool isDelete,
         std::shared_ptr<SLE const> const& before,
         std::shared_ptr<SLE const> const& after) override;
 
+    /** Invariant finalisation hook for the clawback transactor.
+     *
+     *  Currently a no-op that always returns `true`; reserved for future
+     *  transaction-specific invariant checks.
+     *
+     *  @param tx The transaction being applied.
+     *  @param result The TER result code from `doApply`.
+     *  @param fee The fee charged for the transaction.
+     *  @param view The ledger view after the transaction.
+     *  @param j Journal for diagnostic logging.
+     *  @return Always `true`; no violations are currently checked.
+     */
     [[nodiscard]] bool
     finalizeInvariants(
         STTx const& tx,
diff --git a/include/xrpl/tx/transactors/token/MPTokenAuthorize.h b/include/xrpl/tx/transactors/token/MPTokenAuthorize.h
index 29d80c5d9d..717279a810 100644
--- a/include/xrpl/tx/transactors/token/MPTokenAuthorize.h
+++ b/include/xrpl/tx/transactors/token/MPTokenAuthorize.h
@@ -4,15 +4,57 @@
 
 namespace xrpl {
 
+/** Arguments for the core MPToken authorization helper.
+ *
+ *  Bundles the inputs required by `authorizeMPToken()` (declared in
+ *  `MPTokenHelpers.h`) so that the helper can be called from contexts outside
+ *  the `MPTokenAuthorize` transactor — for example, `VaultCreate` and
+ *  `VaultDeposit` reuse it to implicitly authorize vault pseudo-accounts
+ *  without executing a full transaction.
+ *
+ *  @see authorizeMPToken
+ */
 struct MPTAuthorizeArgs
 {
+    /** Submitting account's XRP balance before fee deduction; used for the
+     *  reserve check when creating a new `MPToken` object. */
     XRPAmount const& priorBalance;
+
+    /** 192-bit identifier of the target MPT issuance. */
     MPTID const& mptIssuanceID;
+
+    /** Account that submitted the transaction (holder when `holderID` is
+     *  absent; issuer when `holderID` is present). */
     AccountID const& account;
+
+    /** Transaction flags; `tfMPTUnauthorize` selects the
+     *  delete/deauthorize path. */
     std::uint32_t flags{};
+
+    /** When set, `account` is the issuer acting on behalf of this holder;
+     *  when absent, `account` itself is the holder. */
     std::optional<AccountID> holderID;
 };
 
+/** Transactor for the `MPTokenAuthorize` transaction (ttMPTOKEN_AUTHORIZE, opcode 57).
+ *
+ *  Manages the bidirectional authorization handshake that governs who may hold a
+ *  given Multi-Purpose Token (MPT) issuance. A single transaction type, differentiated
+ *  by the presence of the optional `sfHolder` field, handles two distinct roles:
+ *
+ *  - **Holder path** (`sfHolder` absent): the submitting account opts in to hold the
+ *    issuance (creates an `MPToken` SLE), or opts out (deletes it via `tfMPTUnauthorize`).
+ *  - **Issuer path** (`sfHolder` present): the issuer grants or revokes the
+ *    `lsfMPTAuthorized` flag on the named holder's existing `MPToken` SLE. Only
+ *    meaningful when the issuance carries `lsfMPTRequireAuth`.
+ *
+ *  The protocol enforces a holder-first, issuer-second handshake: a holder must opt in
+ *  before the issuer can authorize them. Gated behind the `featureMPTokensV1` amendment.
+ *  Delegable to a credentialed delegate via the `mustAuthorizeMPT` privilege.
+ *
+ *  @note `ConsequencesFactory` is `Normal` — a well-formed transaction that fails
+ *      in preclaim still consumes its sequence number and fee.
+ */
 class MPTokenAuthorize : public Transactor
 {
 public:
@@ -22,24 +64,102 @@ public:
     {
     }
 
+    /** Return the bitmask of valid transaction flags for this type.
+     *
+     *  Reports `tfMPTokenAuthorizeMask` to the `preflight1()` framework so that
+     *  unexpected flag bits are rejected before field validation begins.
+     *
+     *  @param ctx Preflight context (unused; present for interface uniformity).
+     *  @return The set of flag bits valid for `MPTokenAuthorize` transactions.
+     */
     static std::uint32_t
     getFlagsMask(PreflightContext const& ctx);
 
+    /** Stateless field validation — rejects degenerate self-authorization.
+     *
+     *  The only check performed here is that `sfAccount != sfHolder`; an account
+     *  authorizing itself is a client bug with no valid interpretation. All
+     *  amendment gating is handled upstream by `invokePreflight<T>()` via the
+     *  `Permission` registry, so this method does not touch ledger or amendment state.
+     *
+     *  @param ctx Preflight context providing the transaction and rules.
+     *  @return `tesSUCCESS` or `temMALFORMED` if `sfAccount == sfHolder`.
+     */
     static NotTEC
     preflight(PreflightContext const& ctx);
 
+    /** Ledger-state validation against a read-only view.
+     *
+     *  Branches on the presence of `sfHolder`:
+     *
+     *  **Holder path** (`sfHolder` absent — submitter is the holder):
+     *  - With `tfMPTUnauthorize`: confirms the `MPToken` SLE exists, that both
+     *    `sfMPTAmount` and `sfLockedAmount` are zero (`tecHAS_OBLIGATIONS` if not),
+     *    and (when `featureSingleAssetVault` is active) that `lsfMPTLocked` is not
+     *    set on the token (`tecNO_PERMISSION`).
+     *  - Without `tfMPTUnauthorize`: confirms the issuance exists, that the submitter
+     *    is not the issuer (`tecNO_PERMISSION`), and that no `MPToken` SLE already
+     *    exists (`tecDUPLICATE`).
+     *
+     *  **Issuer path** (`sfHolder` present — submitter is the issuer):
+     *  - Confirms the holder account exists (`tecNO_DST`).
+     *  - Confirms the issuance exists (`tecOBJECT_NOT_FOUND`).
+     *  - Confirms the submitter is the issuance's issuer (`tecNO_PERMISSION`).
+     *  - Confirms `lsfMPTRequireAuth` is set on the issuance (`tecNO_AUTH`);
+     *    granting auth on a non-auth issuance is meaningless.
+     *  - Confirms the holder has already created their `MPToken` entry (`tecOBJECT_NOT_FOUND`),
+     *    enforcing the holder-first handshake.
+     *  - Rejects pseudo-accounts (vault and loan broker) as holders (`tecNO_PERMISSION`),
+     *    because pseudo-accounts are implicitly always authorized by the protocol.
+     *
+     *  @param ctx Preclaim context providing the read-only ledger view and transaction.
+     *  @return `tesSUCCESS`, or one of the `tec`/`tef` codes described above.
+     */
     static TER
     preclaim(PreclaimContext const& ctx);
 
+    /** Apply the authorization change to the ledger.
+     *
+     *  Delegates entirely to `authorizeMPToken()` from `MPTokenHelpers.h`, passing
+     *  `preFeeBalance_` (the XRP balance snapshot taken by the base class before fee
+     *  deduction) along with the transaction fields. All ledger mutations — creating
+     *  or deleting the `MPToken` SLE, adjusting owner directory entries, and toggling
+     *  `lsfMPTAuthorized` — are performed inside that helper.
+     *
+     *  @return `tesSUCCESS`, `tecINSUFFICIENT_RESERVE`, or a `tef` code on
+     *      invariant violations inside `authorizeMPToken`.
+     */
     TER
     doApply() override;
 
+    /** Accumulate per-entry data for transaction-specific invariant checks.
+     *
+     *  Currently a no-op stub; no transaction-specific invariants are defined yet.
+     *  The method exists to satisfy the pure-virtual interface on `Transactor` and
+     *  serves as the extension point for future post-apply checks.
+     *
+     *  @param isDelete True if the entry was erased.
+     *  @param before   Entry state before the transaction (nullptr for new entries).
+     *  @param after    Entry state after the transaction.
+     */
     void
     visitInvariantEntry(
         bool isDelete,
         std::shared_ptr<SLE const> const& before,
         std::shared_ptr<SLE const> const& after) override;
 
+    /** Finalize transaction-specific invariant checks.
+     *
+     *  Currently a no-op stub that always returns `true`; no transaction-specific
+     *  invariants are defined yet. Satisfies the pure-virtual interface on `Transactor`.
+     *
+     *  @param tx     The transaction being applied.
+     *  @param result The tentative TER result.
+     *  @param fee    The fee consumed.
+     *  @param view   Read-only ledger view after the transaction.
+     *  @param j      Logging sink.
+     *  @return Always `true` (no invariants to fail).
+     */
     [[nodiscard]] bool
     finalizeInvariants(
         STTx const& tx,
diff --git a/include/xrpl/tx/transactors/token/MPTokenIssuanceCreate.h b/include/xrpl/tx/transactors/token/MPTokenIssuanceCreate.h
index 2cb871550a..93ab00b0cc 100644
--- a/include/xrpl/tx/transactors/token/MPTokenIssuanceCreate.h
+++ b/include/xrpl/tx/transactors/token/MPTokenIssuanceCreate.h
@@ -6,24 +6,84 @@
 
 namespace xrpl {
 
+/** Input parameters for creating a new MPTokenIssuance ledger object.
+ *
+ *  This aggregate decouples the creation logic from the transaction context so
+ *  that `MPTokenIssuanceCreate::create()` can be called as a side effect by
+ *  other transactors — most notably `VaultCreate`, which mints a share-token
+ *  issuance when creating a single-asset vault — without constructing a full
+ *  `ApplyContext`.
+ *
+ *  @note When `priorBalance` is present, `create()` enforces the owner-reserve
+ *      requirement.  Callers that manage the reserve externally (e.g. vault
+ *      pseudo-account creation) should pass `std::nullopt` to skip the check.
+ */
 struct MPTCreateArgs
 {
+    /** Account balance before fee deduction.  When set, `create()` returns
+     *  `tecINSUFFICIENT_RESERVE` if the balance cannot cover the new reserve
+     *  increment.  Pass `std::nullopt` to skip the reserve check. */
     std::optional<XRPAmount> priorBalance;
+
+    /** Issuing account; combined with `sequence` to derive the deterministic
+     *  `MPTID` via `makeMptID()`. */
     AccountID const& account;
+
+    /** Transaction sequence value used with `account` to compute the `MPTID`.
+     *  Stored in the issuance SLE as `sfSequence`. */
     std::uint32_t sequence = 0;
+
+    /** Transaction flags, stripped of universal bits (`~tfUniversal`) before
+     *  being written to `sfFlags` on the issuance SLE. */
     std::uint32_t flags = 0;
+
+    /** Optional supply cap for the issuance.  Must be positive and at most
+     *  `maxMPTokenAmount` (0x7FFF_FFFF_FFFF_FFFF).  Absent means no cap. */
     std::optional<std::uint64_t> maxAmount =
         std::nullopt;  // NOLINT(readability-redundant-member-init)
+
+    /** Optional decimal-scale exponent stored in `sfAssetScale` on the SLE. */
     std::optional<std::uint8_t> assetScale =
         std::nullopt;  // NOLINT(readability-redundant-member-init)
+
+    /** Per-transfer fee in basis points.  Must be ≤ `maxTransferFee`
+     *  (50,000).  A non-zero value requires `tfMPTCanTransfer` to be set in
+     *  `flags`. */
     std::optional<std::uint16_t> transferFee =
         std::nullopt;  // NOLINT(readability-redundant-member-init)
+
+    /** Arbitrary binary metadata stored in `sfMPTokenMetadata`.  When
+     *  present must be non-empty and at most `maxMPTokenMetadataLength`
+     *  (1,024) bytes. */
     std::optional<Slice> const& metadata{};
+
+    /** Optional permissioned-domain ID.  When set the issuance is private
+     *  and `tfMPTRequireAuth` must be set in `flags`.  Requires both
+     *  `featurePermissionedDomains` and `featureSingleAssetVault`. */
     std::optional<uint256> domainId = std::nullopt;  // NOLINT(readability-redundant-member-init)
+
+    /** Optional bitmask of flags that may be changed after issuance.  When
+     *  present must be non-zero and contain only bits within
+     *  `tmfMPTokenIssuanceCreateMutableMask`.  Requires `featureDynamicMPT`. */
     std::optional<std::uint32_t> mutableFlags =
         std::nullopt;  // NOLINT(readability-redundant-member-init)
 };
 
+/** Transactor for the `ttMPTOKEN_ISSUANCE_CREATE` transaction type.
+ *
+ *  Creates a new `MPTokenIssuance` ledger object that anchors all subsequent
+ *  holder balances for a Multi-Party Token (MPT).  MPTs carry richer metadata
+ *  than classic trust-line IOUs: optional supply caps, decimal scaling,
+ *  configurable transfer fees, arbitrary binary metadata, and
+ *  permissioned-domain constraints.
+ *
+ *  The core creation logic lives in the static `create()` method rather than
+ *  directly in `doApply()`, allowing `VaultCreate` (and future transactors)
+ *  to mint an MPT issuance as a side effect by constructing `MPTCreateArgs`
+ *  directly, without a full transaction context.
+ *
+ *  @see MPTCreateArgs
+ */
 class MPTokenIssuanceCreate : public Transactor
 {
 public:
@@ -33,24 +93,93 @@ public:
     {
     }
 
+    /** Gate optional field categories on the amendments that enable them.
+     *
+     *  Returns `false` (causing `invokePreflight` to return `temDISABLED`) if:
+     *  - `sfDomainID` is present but neither `featurePermissionedDomains` nor
+     *    `featureSingleAssetVault` is enabled, or
+     *  - `sfMutableFlags` is present but `featureDynamicMPT` is not enabled.
+     *
+     *  @param ctx  The preflight context.
+     *  @return `true` if all present optional fields are covered by active
+     *      amendments; `false` otherwise.
+     */
     static bool
     checkExtraFeatures(PreflightContext const& ctx);
 
+    /** Returns the flag mask for this transaction type.
+     *
+     *  `invokePreflight` passes this mask to `preflight1`, which rejects any
+     *  transaction whose `sfFlags` field contains bits outside the mask.
+     *
+     *  @param ctx  The preflight context (unused; present for interface
+     *      uniformity).
+     *  @return `tfMPTokenIssuanceCreateMask`.
+     */
     static std::uint32_t
     getFlagsMask(PreflightContext const& ctx);
 
+    /** Validate semantic constraints on the transaction fields.
+     *
+     *  Enforces four rules:
+     *  1. If `sfMutableFlags` is present it must be non-zero and must not
+     *     contain bits outside `tmfMPTokenIssuanceCreateMutableMask`
+     *     (returns `temINVALID_FLAG`).
+     *  2. A non-zero `sfTransferFee` (max 50,000 basis points) requires
+     *     `tfMPTCanTransfer` to also be set (returns `temMALFORMED` or
+     *     `temBAD_TRANSFER_FEE`).
+     *  3. A zero `sfDomainID` is malformed; a non-zero domain ID requires
+     *     `tfMPTRequireAuth` (returns `temMALFORMED`).
+     *  4. `sfMPTokenMetadata` must be non-empty and ≤ 1,024 bytes;
+     *     `sfMaximumAmount`, if present, must be positive and ≤
+     *     `maxMPTokenAmount` (returns `temMALFORMED`).
+     *
+     *  @param ctx  The preflight context.
+     *  @return `tesSUCCESS` if all checks pass; a `tem*` error code otherwise.
+     */
     static NotTEC
     preflight(PreflightContext const& ctx);
 
+    /** Apply the transaction: package fields into `MPTCreateArgs` and delegate
+     *  to `create()`.
+     *
+     *  Passes `preFeeBalance_` as `priorBalance` so that `create()` enforces
+     *  the reserve requirement against the pre-fee snapshot.
+     *
+     *  @return `tesSUCCESS` on success, or the `TER` embedded in the
+     *      `Unexpected` result from `create()`.
+     */
     TER
     doApply() override;
 
+    /** Accumulate per-entry data for transaction-specific invariant checks.
+     *
+     *  Currently a no-op stub; no transaction-specific invariants are defined
+     *  yet.  The method satisfies the `Transactor` interface and serves as the
+     *  extension point for future checks.
+     *
+     *  @param isDelete True if the entry was erased.
+     *  @param before   Entry state before the transaction (nullptr for new entries).
+     *  @param after    Entry state after the transaction.
+     */
     void
     visitInvariantEntry(
         bool isDelete,
         std::shared_ptr<SLE const> const& before,
         std::shared_ptr<SLE const> const& after) override;
 
+    /** Finalize transaction-specific invariant checks.
+     *
+     *  Currently a no-op stub that always returns `true`.  Satisfies the
+     *  `Transactor` interface; reserved for future per-transaction invariants.
+     *
+     *  @param tx     The transaction being applied.
+     *  @param result The tentative TER result.
+     *  @param fee    The fee consumed.
+     *  @param view   Read-only ledger view after the transaction.
+     *  @param j      Logging sink.
+     *  @return Always `true` (no invariants to fail).
+     */
     [[nodiscard]] bool
     finalizeInvariants(
         STTx const& tx,
@@ -59,6 +188,34 @@ public:
         ReadView const& view,
         beast::Journal const& j) override;
 
+    /** Create an `MPTokenIssuance` SLE from the supplied parameters.
+     *
+     *  This is the single authoritative path for inserting a new MPT issuance
+     *  into the ledger.  It is called directly by `doApply()` and may also be
+     *  called by other transactors (e.g. `VaultCreate`) that need to mint a
+     *  share-token issuance as a side effect.
+     *
+     *  Sequence of operations:
+     *  1. If `args.priorBalance` is set, verifies the account can cover the
+     *     new owner-reserve increment.
+     *  2. Inserts an entry in the issuer's owner directory via
+     *     `view.dirInsert()`.
+     *  3. Constructs the `MPTokenIssuance` SLE with mandatory fields
+     *     (`sfFlags`, `sfIssuer`, `sfOutstandingAmount = 0`, `sfOwnerNode`,
+     *     `sfSequence`) and populates all optional fields present in `args`.
+     *  4. Calls `adjustOwnerCount()` to increment the account's reserve
+     *     obligation.
+     *
+     *  @param view    Mutable ledger view to write the new SLE into.
+     *  @param journal Logging sink.
+     *  @param args    Creation parameters; see `MPTCreateArgs`.
+     *  @return On success, the new `MPTID` (deterministically derived from
+     *      `args.sequence` and `args.account` via `makeMptID()`).  On failure,
+     *      an `Unexpected` wrapping one of:
+     *      - `tecINTERNAL` — issuer account SLE not found (ledger corruption).
+     *      - `tecINSUFFICIENT_RESERVE` — `priorBalance` too low.
+     *      - `tecDIR_FULL` — owner directory page exhausted.
+     */
     static Expected<MPTID, TER>
     create(ApplyView& view, beast::Journal journal, MPTCreateArgs const& args);
 };
diff --git a/include/xrpl/tx/transactors/token/MPTokenIssuanceDestroy.h b/include/xrpl/tx/transactors/token/MPTokenIssuanceDestroy.h
index 2f18a501e9..3a94f8bb3f 100644
--- a/include/xrpl/tx/transactors/token/MPTokenIssuanceDestroy.h
+++ b/include/xrpl/tx/transactors/token/MPTokenIssuanceDestroy.h
@@ -1,9 +1,30 @@
+/** @file
+ *  Declares the `MPTokenIssuanceDestroy` transactor (`ttMPTOKEN_ISSUANCE_DESTROY`).
+ *
+ *  Handles permanent deletion of an MPToken issuance object from the ledger,
+ *  reclaiming the issuer's owner-count slot and removing the entry from the
+ *  owner directory.  Gated behind `featureMPTokensV1`; delegable via the
+ *  `destroyMPTIssuance` privilege.
+ */
+
 #pragma once
 
 #include <xrpl/tx/Transactor.h>
 
 namespace xrpl {
 
+/** Transactor for the `ttMPTOKEN_ISSUANCE_DESTROY` transaction type (opcode 55).
+ *
+ *  Permanently removes an `MPTokenIssuance` ledger object when no tokens remain
+ *  in circulation (`sfOutstandingAmount == 0`) and none are locked
+ *  (`sfLockedAmount == 0`), protecting any holders from having live balances
+ *  orphaned.  On success the issuer's owner count is decremented by one.
+ *
+ *  All substantive validation lives in `preclaim`; `preflight` is intentionally
+ *  trivial because every guard requires reading current ledger state.
+ *
+ *  @see MPTokenIssuanceCreate
+ */
 class MPTokenIssuanceDestroy : public Transactor
 {
 public:
@@ -13,21 +34,81 @@ public:
     {
     }
 
+    /** Static validation phase — unconditionally returns `tesSUCCESS`.
+     *
+     *  Every meaningful precondition for this transaction requires ledger
+     *  state that is unavailable at preflight time.  Field-level checks
+     *  (valid fee, sequence, well-formed signature) are handled by the
+     *  framework's `preflight0`/`preflight1` layers before this method runs.
+     *
+     *  @param ctx  The preflight context (unused).
+     *  @return `tesSUCCESS` always.
+     */
     static NotTEC
     preflight(PreflightContext const& ctx);
 
+    /** Read-only ledger validation — enforces all destruction preconditions.
+     *
+     *  Reads the `MPTokenIssuance` SLE identified by `sfMPTokenIssuanceID` and
+     *  enforces three invariants in order:
+     *  1. The issuance object must exist (`tecOBJECT_NOT_FOUND` if absent).
+     *  2. `sfIssuer` must match the transaction submitter (`tecNO_PERMISSION`
+     *     if it does not) — only the issuer may destroy their own issuance.
+     *  3. `sfOutstandingAmount` must be zero, and `sfLockedAmount` (if present)
+     *     must also be zero (`tecHAS_OBLIGATIONS` if either is non-zero).
+     *
+     *  @param ctx  The preclaim context providing a read-only ledger view.
+     *  @return `tesSUCCESS` if all guards pass; `tecOBJECT_NOT_FOUND`,
+     *      `tecNO_PERMISSION`, or `tecHAS_OBLIGATIONS` otherwise.
+     *  @note A non-zero `sfLockedAmount` when `sfOutstandingAmount` is already
+     *      zero would indicate corrupted ledger state unreachable through normal
+     *      transaction flow; the check is present as a defensive backstop.
+     */
     static TER
     preclaim(PreclaimContext const& ctx);
 
+    /** Execute the ledger mutation: erase the issuance SLE and update accounting.
+     *
+     *  Sequence of operations:
+     *  1. Peeks the `MPTokenIssuance` SLE via `view().peek(keylet::mptIssuance(...))`.
+     *  2. Removes the entry from the issuer's owner directory via `view().dirRemove()`.
+     *  3. Erases the SLE with `view().erase()`.
+     *  4. Decrements the issuer's owner count by one via `adjustOwnerCount()`.
+     *
+     *  @return `tesSUCCESS` on success; `tefBAD_LEDGER` if the owner-directory
+     *      removal fails (indicates ledger corruption, not user error).
+     */
     TER
     doApply() override;
 
+    /** Accumulate per-entry data for transaction-specific invariant checks.
+     *
+     *  Currently a no-op stub; no transaction-specific invariants are defined
+     *  yet.  Satisfies the `Transactor` interface and serves as the extension
+     *  point for future checks.
+     *
+     *  @param isDelete  True if the entry was erased.
+     *  @param before    Entry state before the transaction (nullptr for new entries).
+     *  @param after     Entry state after the transaction (nullptr for deleted entries).
+     */
     void
     visitInvariantEntry(
         bool isDelete,
         std::shared_ptr<SLE const> const& before,
         std::shared_ptr<SLE const> const& after) override;
 
+    /** Finalize transaction-specific invariant checks.
+     *
+     *  Currently a no-op stub that always returns `true`.  Satisfies the
+     *  `Transactor` interface; reserved for future per-transaction invariants.
+     *
+     *  @param tx     The transaction being applied.
+     *  @param result The tentative TER result.
+     *  @param fee    The fee consumed.
+     *  @param view   Read-only ledger view after the transaction.
+     *  @param j      Logging sink.
+     *  @return Always `true` (no invariants to fail).
+     */
     [[nodiscard]] bool
     finalizeInvariants(
         STTx const& tx,
diff --git a/include/xrpl/tx/transactors/token/MPTokenIssuanceSet.h b/include/xrpl/tx/transactors/token/MPTokenIssuanceSet.h
index 2e8c8a7a41..874372d62a 100644
--- a/include/xrpl/tx/transactors/token/MPTokenIssuanceSet.h
+++ b/include/xrpl/tx/transactors/token/MPTokenIssuanceSet.h
@@ -4,6 +4,22 @@
 
 namespace xrpl {
 
+/** Transactor for `ttMPTOKEN_ISSUANCE_SET` transactions.
+ *
+ *  Handles two distinct operations on MPTokenIssuance ledger objects:
+ *  1. Toggling the locked state of the whole issuance or an individual
+ *     holder's `MPToken` slot (via `tfMPTLock` / `tfMPTUnlock`).
+ *  2. Mutating post-creation properties of the issuance — `sfMutableFlags`,
+ *     `sfTransferFee`, `sfMPTokenMetadata`, and `sfDomainID` — when the
+ *     `featureDynamicMPT` amendment is active.
+ *
+ *  Uses compile-time (static) polymorphism: the three pipeline entry points
+ *  (`checkExtraFeatures`, `preflight`, `preclaim`) are static methods driven
+ *  by `Transactor::invokePreflight<T>` rather than virtual dispatch.
+ *  `ConsequencesFactory{Normal}` applies standard fee consequences; this
+ *  transaction does not unconditionally block later transactions from the
+ *  same account.
+ */
 class MPTokenIssuanceSet : public Transactor
 {
 public:
@@ -13,30 +29,163 @@ public:
     {
     }
 
+    /** Gate on amendment requirements not captured by the global tx-to-feature
+     *  map.
+     *
+     *  Returns `false` (causing `invokePreflight` to return `temDISABLED`)
+     *  if `sfDomainID` is present in the transaction but either
+     *  `featurePermissionedDomains` or `featureSingleAssetVault` is not yet
+     *  enabled. All other transactions pass unconditionally.
+     *
+     *  @param ctx Preflight context providing access to transaction fields
+     *      and active amendment rules.
+     *  @return `true` if the transaction may proceed, `false` to abort with
+     *      `temDISABLED`.
+     */
     static bool
     checkExtraFeatures(PreflightContext const& ctx);
 
+    /** Return the valid flag-bit mask for this transaction type.
+     *
+     *  Delegates to `tfMPTokenIssuanceSetMask`, which covers `tfMPTLock` and
+     *  `tfMPTUnlock`. `preflight1` uses this mask to reject transactions that
+     *  set any undefined flag bits.
+     *
+     *  @param ctx Preflight context (unused; present for framework uniformity).
+     *  @return Bitmask of all flag bits this transaction legitimately owns.
+     */
     static std::uint32_t
     getFlagsMask(PreflightContext const& ctx);
 
+    /** Stateless semantic validation (no ledger access).
+     *
+     *  Enforces the following invariants:
+     *  - `sfDomainID` and `sfHolder` are mutually exclusive.
+     *  - `tfMPTLock` and `tfMPTUnlock` cannot both be set.
+     *  - The submitting account cannot equal `sfHolder`.
+     *
+     *  When `featureDynamicMPT` is active, additionally:
+     *  - Mutation fields (`sfMutableFlags`, `sfMPTokenMetadata`,
+     *    `sfTransferFee`) cannot coexist with `sfHolder` or non-universal
+     *    tx flags.
+     *  - Setting a non-zero `sfTransferFee` while clearing `tmfMPTClearCanTransfer`
+     *    is rejected.
+     *  - `sfMutableFlags` must be non-zero and must not include unknown bits
+     *    (validated against `tmfMPTokenIssuanceSetMutableMask`).
+     *
+     *  When either `featureSingleAssetVault` or `featureDynamicMPT` is
+     *  enabled, a transaction that changes nothing (zero flags, no domain,
+     *  no mutation fields) is rejected as `temMALFORMED`.
+     *
+     *  @param ctx Preflight context with the transaction and active rules.
+     *  @return `tesSUCCESS` on valid input; a `tem*` code on any violation.
+     */
     static NotTEC
     preflight(PreflightContext const& ctx);
 
+    /** Validate delegate authorization for lock/unlock operations.
+     *
+     *  If `sfDelegate` is absent the call is a no-op and returns
+     *  `tesSUCCESS`. Otherwise the delegate SLE is loaded and permissions
+     *  are checked in two tiers:
+     *  1. Broad transaction-level permission via `checkTxPermission()`.
+     *  2. Granular fall-back: `MPTokenIssuanceLock` required for `tfMPTLock`,
+     *     `MPTokenIssuanceUnlock` required for `tfMPTUnlock`.
+     *
+     *  @param view Read-only ledger view used to load the delegate SLE.
+     *  @param tx   The transaction being validated.
+     *  @return `tesSUCCESS` if authorized; `terNO_DELEGATE_PERMISSION` if the
+     *      delegate lacks the required permission.
+     */
     static NotTEC
     checkPermission(ReadView const& view, STTx const& tx);
 
+    /** Read-only ledger-state validation (runs after signature verification).
+     *
+     *  Checks that:
+     *  - The target `MPTokenIssuance` object exists and the submitter is its
+     *    issuer.
+     *  - If `sfHolder` is present: the holder account exists and their
+     *    `MPToken` slot for this issuance exists.
+     *  - If `sfDomainID` is present: the issuance has `lsfMPTRequireAuth` set,
+     *    and the referenced `PermissionedDomain` object exists (unless the
+     *    zero sentinel is supplied to clear the domain link).
+     *  - Lock/unlock operations respect the `lsfMPTCanLock` flag: under older
+     *    rules the flag must be present; under `featureSingleAssetVault` or
+     *    `featureDynamicMPT` the flag is only required when the tx actually
+     *    requests a lock or unlock.
+     *  - For `featureDynamicMPT` mutations: each flag the transaction tries to
+     *    set or clear must be listed in `sfMutableFlags` on the ledger object
+     *    (table-driven via `kMPT_MUTABILITY_FLAGS`); similarly,
+     *    `sfMPTokenMetadata` and `sfTransferFee` mutations require
+     *    `lsmfMPTCanMutateMetadata` and `lsmfMPTCanMutateTransferFee`
+     *    respectively. Setting a non-zero `sfTransferFee` additionally
+     *    requires `lsfMPTCanTransfer` to already be set on the object.
+     *
+     *  @param ctx Preclaim context providing read-only access to the ledger.
+     *  @return `tesSUCCESS` on success; `tecOBJECT_NOT_FOUND`,
+     *      `tecNO_PERMISSION`, `tecNO_AUTH`, `tecNO_ENTRY`, or another
+     *      `tec*` / `ter*` code on failure.
+     */
     static TER
     preclaim(PreclaimContext const& ctx);
 
+    /** Apply the transaction's mutations to the ledger.
+     *
+     *  Peeks at the `MPTokenIssuance` SLE (or the holder's `MPToken` SLE
+     *  when `sfHolder` is present) and applies the following changes as
+     *  directed by the transaction flags and fields:
+     *  - `tfMPTLock` / `tfMPTUnlock`: sets or clears `lsfMPTLocked`.
+     *  - `sfMutableFlags`: iterates `kMPT_MUTABILITY_FLAGS` and sets/clears
+     *    each `canMutateFlag` on the issuance as directed.
+     *  - When `tmfMPTClearCanTransfer` is applied, `sfTransferFee` is
+     *    explicitly removed to keep the ledger internally consistent.
+     *  - `sfTransferFee`: stored absent when zero (field uses `soeDEFAULT`
+     *    semantics), present otherwise.
+     *  - `sfMPTokenMetadata`: an empty blob removes the field entirely.
+     *  - `sfDomainID`: zero sentinel removes the field; any other value sets
+     *    it.
+     *
+     *  All failure paths should have been caught in preflight/preclaim; if
+     *  `doApply` reaches an unexpected state it returns `tecINTERNAL`.
+     *
+     *  @return `tesSUCCESS` on success; `tecINTERNAL` on an unexpected error.
+     */
     TER
     doApply() override;
 
+    /** Per-entry invariant hook (currently a no-op).
+     *
+     *  Called by the invariant-checker framework for each SLE modified by
+     *  this transaction. No transaction-specific invariants are registered
+     *  yet; this override exists as a placeholder for future work.
+     *
+     *  @param isDelete `true` if the entry was deleted.
+     *  @param before   SLE state before the transaction (may be null for new
+     *      entries).
+     *  @param after    SLE state after the transaction (may be null for
+     *      deletions).
+     */
     void
     visitInvariantEntry(
         bool isDelete,
         std::shared_ptr<SLE const> const& before,
         std::shared_ptr<SLE const> const& after) override;
 
+    /** Post-apply invariant finalizer (currently a no-op).
+     *
+     *  Called once after all `visitInvariantEntry` calls for this
+     *  transaction. No transaction-specific invariants are registered yet;
+     *  always returns `true`. This override exists as a placeholder for
+     *  future work.
+     *
+     *  @param tx     The applied transaction.
+     *  @param result The `TER` result of `doApply`.
+     *  @param fee    Fee charged for this transaction.
+     *  @param view   Read-only view of the ledger after application.
+     *  @param j      Journal for diagnostic logging.
+     *  @return `true` (invariant trivially satisfied).
+     */
     [[nodiscard]] bool
     finalizeInvariants(
         STTx const& tx,
diff --git a/include/xrpl/tx/transactors/token/TrustSet.h b/include/xrpl/tx/transactors/token/TrustSet.h
index 5eee05889a..4ed092b4e2 100644
--- a/include/xrpl/tx/transactors/token/TrustSet.h
+++ b/include/xrpl/tx/transactors/token/TrustSet.h
@@ -5,6 +5,27 @@
 
 namespace xrpl {
 
+/** Transactor for `TrustSet` transactions.
+ *
+ *  A `TrustSet` transaction creates, modifies, or implicitly deletes a
+ *  *trust line* — the bilateral `RippleState` ledger entry that permits two
+ *  accounts to carry a non-XRP IOU balance in a specific currency. Without a
+ *  trust line, no IOU balance can exist between the two parties.
+ *
+ *  The class participates in the standard three-phase pipeline declared by
+ *  `Transactor`:
+ *  - `getFlagsMask` / `preflight` — stateless validation (no ledger access).
+ *  - `checkPermission`            — delegate-authority check against a
+ *                                   read-only view.
+ *  - `preclaim`                   — read-only ledger checks.
+ *  - `doApply`                    — mutable ledger writes.
+ *
+ *  Static methods use compile-time name hiding rather than virtual dispatch;
+ *  `Transactor::invokePreflight<TrustSet>` resolves them at compile time.
+ *  `ConsequencesFactoryType::Normal` is used — the transaction does not block
+ *  subsequent transactions from the same account and needs no custom
+ *  consequence computation.
+ */
 class TrustSet : public Transactor
 {
 public:
@@ -14,27 +35,179 @@ public:
     {
     }
 
+    /** Return the set of flags valid for a `TrustSet` transaction.
+     *
+     *  Returns `tfTrustSetMask`, which is the union of `tfSetfAuth`,
+     *  `tfSetNoRipple`, `tfClearNoRipple`, `tfSetFreeze`, `tfClearFreeze`,
+     *  `tfSetDeepFreeze`, and `tfClearDeepFreeze`. `preflight1` uses this mask
+     *  to reject transactions that set any flag outside the union before any
+     *  ledger state is touched. The deep-freeze bits are included in the mask
+     *  unconditionally; `preflight` enforces the `featureDeepFreeze` amendment
+     *  guard separately at runtime.
+     *
+     *  @param ctx  Preflight context (unused; present for interface uniformity).
+     *  @return     Bitmask of all flags permitted on a `TrustSet` transaction.
+     */
     static std::uint32_t
     getFlagsMask(PreflightContext const& ctx);
 
+    /** Validate a `TrustSet` transaction without accessing ledger state.
+     *
+     *  Checks performed (all return `tem` codes, so no fee is charged on
+     *  failure):
+     *  - If `featureDeepFreeze` is not enabled, `tfSetDeepFreeze` and
+     *    `tfClearDeepFreeze` are rejected with `temINVALID_FLAG`.
+     *  - `sfLimitAmount` must be a legal non-native amount (`temBAD_AMOUNT`).
+     *  - `sfLimitAmount` must not be denominated in XRP (`temBAD_LIMIT`).
+     *  - The currency must not be the XRP pseudo-currency sentinel
+     *    (`temBAD_CURRENCY`).
+     *  - The limit must be non-negative (`temBAD_LIMIT`).
+     *  - The issuer field must be a real, non-zero account ID
+     *    (`temDST_NEEDED`).
+     *
+     *  @param ctx  Immutable preflight context carrying the transaction and
+     *              active ledger rules.
+     *  @return     `tesSUCCESS` on success, or a `tem` error code.
+     */
     static NotTEC
     preflight(PreflightContext const& ctx);
 
+    /** Validate delegate authority for a `TrustSet` transaction.
+     *
+     *  Called only when `sfDelegate` is present on the transaction. Locates
+     *  the `Delegate` ledger object for `(sfAccount, sfDelegate)` and first
+     *  checks full transaction-type permission via `checkTxPermission`. If
+     *  that passes, the entire transaction is allowed. Otherwise, the method
+     *  falls through to the following **granular permission** checks:
+     *
+     *  - Any flag in `tfTrustSetPermissionMask` (everything except
+     *    `tfSetfAuth`, `tfSetFreeze`, and `tfClearFreeze`) → denied.
+     *  - `sfQualityIn` or `sfQualityOut` present → denied (delegates cannot
+     *    adjust quality settings under granular grants).
+     *  - Trust line does not yet exist → denied (granular grants cannot
+     *    create new trust lines).
+     *  - `tfSetfAuth` set without `TrustlineAuthorize` permission → denied.
+     *  - `tfSetFreeze` set without `TrustlineFreeze` permission → denied.
+     *  - `tfClearFreeze` set without `TrustlineUnfreeze` permission → denied.
+     *  - `sfLimitAmount` differs from the stored limit → denied (granular
+     *    delegates cannot modify credit limits).
+     *
+     *  @param view  Read-only ledger view for looking up delegate objects and
+     *               the existing trust line.
+     *  @param tx    The transaction being evaluated.
+     *  @return      `tesSUCCESS` if the delegate is authorised, or
+     *               `terNO_DELEGATE_PERMISSION` otherwise.
+     */
     static NotTEC
     checkPermission(ReadView const& view, STTx const& tx);
 
+    /** Read-only ledger checks before state mutation.
+     *
+     *  Checks (in order):
+     *  1. **Auth flag guard**: `tfSetfAuth` is only valid when the issuing
+     *     account has `lsfRequireAuth` set (`tefNO_AUTH_REQUIRED`).
+     *  2. **Self-trust**: sender and destination (issuer) must differ
+     *     (`temDST_IS_SRC`).
+     *  3. **Destination existence**: when AMM or `featureSingleAssetVault` is
+     *     enabled the destination account must exist (`tecNO_DST`).
+     *  4. **`lsfDisallowIncomingTrustline`**: if the destination has opted out
+     *     of incoming trust lines, the transaction is blocked (`tecNO_PERMISSION`)
+     *     unless `fixDisallowIncomingV1` is enabled *and* a trust line between
+     *     the parties already exists (modification of an existing relationship
+     *     is always permitted regardless of the opt-out).
+     *  5. **Pseudo-account restrictions**:
+     *     - AMM pseudo-accounts: new trust lines are only permitted when the
+     *       currency matches the pool's LP token and the pool has non-zero
+     *       liquidity; existing lines may always be modified.
+     *     - Vault and loan-broker pseudo-accounts: modification of an existing
+     *       line is permitted; creation of a new line is not.
+     *     - Any other pseudo-account type → `tecPSEUDO_ACCOUNT`.
+     *  6. **Deep-freeze invariants** (when `featureDeepFreeze` is active):
+     *     - `lsfNoFreeze` on the sender's account blocks any freeze action.
+     *     - Setting and clearing any freeze flag in the same transaction is
+     *       rejected.
+     *     - A post-transaction simulation via `computeFreezeFlags` ensures
+     *       deep-freeze cannot be set without a co-occurring normal freeze.
+     *
+     *  @param ctx  Read-only preclaim context with ledger view and transaction.
+     *  @return     `tesSUCCESS`, or an appropriate `tec`/`tef`/`tem` error.
+     */
     static TER
     preclaim(PreclaimContext const& ctx);
 
+    /** Apply the `TrustSet` transaction to the mutable ledger view.
+     *
+     *  **Reserve policy**: accounts with fewer than two owned objects are
+     *  exempt from the incremental reserve requirement when creating a new
+     *  trust line. This allows gateways to fund new users with exactly the
+     *  base reserve — without having to pad for the trust-line reserve — so
+     *  the user cannot pocket the surplus.
+     *
+     *  **Existing trust line** (`RippleState` SLE found):
+     *  - Account IDs are compared numerically to assign the "low" and "high"
+     *    side; all field accesses (`sfLowLimit`/`sfHighLimit`,
+     *    `sfLowQualityIn`/`sfHighQualityIn`, etc.) use the appropriate side.
+     *  - Quality values equal to `QUALITY_ONE` are stored as zero to maintain
+     *    canonical representation.
+     *  - The owner-reserve flags (`lsfLowReserve`/`lsfHighReserve`) are
+     *    recomputed from scratch after every change; `adjustOwnerCount` is
+     *    called with ±1 whenever either flag transitions.
+     *  - If both sides of the trust line reach fully default state (zero limit,
+     *    zero quality, no special flags, no outstanding balance), `trustDelete`
+     *    is called to remove the SLE and decrement both owner counts (automatic
+     *    garbage collection).
+     *  - If a reserve increase would be required but `preFeeBalance_` falls
+     *    short of the post-creation reserve threshold, the transaction fails
+     *    with `tecINSUF_RESERVE_LINE`.
+     *
+     *  **No existing trust line**:
+     *  - Submitting all-default parameters on a non-existent line returns
+     *    `tecNO_LINE_REDUNDANT` immediately.
+     *  - If the sender's XRP balance is below the reserve needed to hold one
+     *    more object, the transaction fails with `tecNO_LINE_INSUF_RESERVE`.
+     *  - Otherwise, `trustCreate` initialises a new `RippleState` SLE with
+     *    the supplied limit, quality, and flag values.
+     *
+     *  @return  `tesSUCCESS`, `tecINSUF_RESERVE_LINE`, `tecNO_LINE_REDUNDANT`,
+     *           `tecNO_LINE_INSUF_RESERVE`, `tecNO_DST`, `tecNO_PERMISSION`,
+     *           or `tefINTERNAL` on unexpected ledger corruption.
+     */
     TER
     doApply() override;
 
+    /** Accumulate per-SLE state for transaction-specific invariant checks.
+     *
+     *  Called once per modified ledger entry before `finalizeInvariants`.
+     *  The current implementation is a no-op placeholder; `TrustSet` does
+     *  not yet define transaction-specific post-conditions beyond those
+     *  enforced by the protocol-level invariant checkers.
+     *
+     *  @param isDelete  `true` if the entry was erased.
+     *  @param before    Entry state before the transaction (`nullptr` if
+     *                   the entry was newly created).
+     *  @param after     Entry state after the transaction (not guaranteed to
+     *                   be `nullptr` on deletion; use `isDelete` instead).
+     */
     void
     visitInvariantEntry(
         bool isDelete,
         std::shared_ptr<SLE const> const& before,
         std::shared_ptr<SLE const> const& after) override;
 
+    /** Verify transaction-specific post-conditions after all entries are visited.
+     *
+     *  Called once after every modified ledger entry has been passed to
+     *  `visitInvariantEntry`. Returns `false` to fail the transaction with
+     *  `tecINVARIANT_FAILED`. The current implementation always returns
+     *  `true` (placeholder for future transaction-specific invariants).
+     *
+     *  @param tx      The applied transaction.
+     *  @param result  Tentative `TER` result prior to invariant checking.
+     *  @param fee     Fee consumed by the transaction.
+     *  @param view    Read-only view of the final ledger state.
+     *  @param j       Journal for logging invariant failures.
+     *  @return        `true` if all transaction-specific invariants pass.
+     */
     [[nodiscard]] bool
     finalizeInvariants(
         STTx const& tx,
diff --git a/include/xrpl/tx/transactors/vault/VaultClawback.h b/include/xrpl/tx/transactors/vault/VaultClawback.h
index bd9fb2abec..83c255c8cd 100644
--- a/include/xrpl/tx/transactors/vault/VaultClawback.h
+++ b/include/xrpl/tx/transactors/vault/VaultClawback.h
@@ -4,6 +4,32 @@
 
 namespace xrpl {
 
+/** Implements the VaultClawback transaction for forcibly recovering assets or
+ *  shares held inside a Vault ledger object.
+ *
+ *  The transaction operates in one of two mutually exclusive modes, determined
+ *  at runtime by comparing the submitting account against vault roles:
+ *
+ *  - **Share-burn mode** (vault owner, share MPT targeted): burns all of a
+ *    holder's vault shares when the vault holds zero assets. This is the
+ *    recovery mechanism for stuck vaults where a lending protocol has absorbed
+ *    all assets and suffered a total loss, leaving outstanding shares with no
+ *    underlying value. Partial burns are not permitted.
+ *
+ *  - **Asset-clawback mode** (asset issuer, vault asset targeted): recovers
+ *    the vault's underlying IOU or MPT assets from the vault pseudo-account
+ *    and proportionally destroys the corresponding holder shares. XRP vaults
+ *    are excluded; IOU vaults require `lsfAllowTrustLineClawback` (and not
+ *    `lsfNoFreeze`) on the issuer's account root; MPT vaults require
+ *    `lsfMPTCanClawback` on the issuance.
+ *
+ *  @note When the asset issuer and vault owner are the same account, the
+ *      transaction is ambiguous and `sfAmount` must be supplied explicitly;
+ *      omitting it returns `tecWRONG_ASSET`.
+ *
+ *  @see VaultWithdraw (holder-initiated counterpart that also converts shares
+ *      to assets, but requires no external authority)
+ */
 class VaultClawback : public Transactor
 {
 public:
@@ -13,21 +39,83 @@ public:
     {
     }
 
+    /** Validate transaction fields before accessing ledger state.
+     *
+     *  Rejects a zero/empty `sfVaultID`. If `sfAmount` is present it must be
+     *  non-negative and must not be XRP, since XRP clawback is categorically
+     *  forbidden. A zero `sfAmount` is valid and means "all".
+     *
+     *  @param ctx Preflight context carrying the transaction and rules.
+     *  @return `tesSUCCESS` on success, `temMALFORMED` for an empty vault ID
+     *      or an XRP amount, `temBAD_AMOUNT` for a negative amount.
+     */
     static NotTEC
     preflight(PreflightContext const& ctx);
 
+    /** Verify authorization and resolve the operating mode against ledger state.
+     *
+     *  Loads the vault SLE and share MPT issuance, then resolves the effective
+     *  clawback amount via the file-local `clawbackAmount()` helper (an absent
+     *  `sfAmount` becomes "all shares" for the vault owner, or "vault asset"
+     *  for the issuer).
+     *
+     *  For **share-burn mode**: enforces that the vault has shares outstanding
+     *  but both `sfAssetsTotal` and `sfAssetsAvailable` are zero, and that a
+     *  non-zero explicit amount equals the holder's entire share balance.
+     *
+     *  For **asset-clawback mode**: confirms the submitter is the vault's
+     *  asset issuer (not the holder), the asset is not XRP, and the appropriate
+     *  clawback flags are set (`lsfAllowTrustLineClawback` without `lsfNoFreeze`
+     *  for IOU; `lsfMPTCanClawback` for MPT).
+     *
+     *  @param ctx Preclaim context providing read-only ledger access.
+     *  @return `tesSUCCESS` on success, `tecNO_ENTRY` if the vault is missing,
+     *      `tecWRONG_ASSET` if the amount is ambiguous or targets an unrelated
+     *      asset, `tecNO_PERMISSION` for authorization failures,
+     *      `tecLIMIT_EXCEEDED` if the vault owner attempts a partial share burn,
+     *      `tefINTERNAL` if the share MPT issuance is unexpectedly absent.
+     */
     static TER
     preclaim(PreclaimContext const& ctx);
 
+    /** Execute the clawback, mutating vault and holder balances.
+     *
+     *  In **share-burn mode**, sets `sharesDestroyed` to the holder's full
+     *  share balance; no assets move. In **asset-clawback mode**, delegates
+     *  to `assetsToClawback()` to compute the (shares, assets) pair.
+     *
+     *  Mutation sequence:
+     *  1. Decrements vault `sfAssetsTotal` and `sfAssetsAvailable`.
+     *  2. Transfers `sharesDestroyed` shares from holder to vault pseudo-account
+     *     (transfer fee waived).
+     *  3. Attempts to remove the holder's now-empty MPToken entry via
+     *     `removeEmptyHolding()`; tolerates `tecHAS_OBLIGATIONS` silently.
+     *  4. If `assetsRecovered > 0`, transfers assets from the vault
+     *     pseudo-account to the submitting issuer (transfer fee waived) and
+     *     confirms the vault's asset balance has not gone negative.
+     *  5. Calls `associateAsset` to re-round stored numeric fields to the
+     *     vault asset's precision.
+     *
+     *  @return `tesSUCCESS` on success, `tecPRECISION_LOSS` if rounding
+     *      produced zero shares to destroy, `tecPATH_DRY` on arithmetic
+     *      overflow in the share/asset conversion, `tefINTERNAL` on
+     *      unexpected ledger-corruption conditions.
+     */
     TER
     doApply() override;
 
+    /** Per-entry invariant hook; no transaction-specific checks are registered yet. */
     void
     visitInvariantEntry(
         bool isDelete,
         std::shared_ptr<SLE const> const& before,
         std::shared_ptr<SLE const> const& after) override;
 
+    /** Post-transaction invariant finalization; no transaction-specific checks
+     *  are registered yet.
+     *
+     *  @return Always `true`.
+     */
     [[nodiscard]] bool
     finalizeInvariants(
         STTx const& tx,
@@ -37,6 +125,31 @@ public:
         beast::Journal const& j) override;
 
 private:
+    /** Compute the (assetsRecovered, sharesDestroyed) pair for asset-clawback mode.
+     *
+     *  When `clawbackAmount` is zero ("all"), converts the holder's entire
+     *  share balance to assets via `sharesToAssetsWithdraw`. When non-zero,
+     *  performs a double-pass: assets → shares (via `assetsToSharesWithdraw`),
+     *  then shares → assets, to account correctly for integer truncation in
+     *  the MPT share representation.
+     *
+     *  If the resulting `assetsRecovered` would exceed `sfAssetsAvailable`
+     *  (possible when assets are partially deployed to a lending protocol),
+     *  the method clamps to `assetsAvailable` and recomputes shares with
+     *  `TruncateShares::Yes` so the re-conversion cannot overshoot the cap.
+     *
+     *  A legacy pre-`fixSecurity3_1_3` code path is preserved for ledger
+     *  replay: zero-amount clawback on old rules skips the `assetsAvailable`
+     *  clamp, reproducing the original (incorrect) outcome.
+     *
+     *  @param vault Mutable vault SLE used for exchange-rate and cap reads.
+     *  @param sleShareIssuance Read-only share MPT issuance SLE.
+     *  @param holder Account whose shares are being destroyed.
+     *  @param clawbackAmount Resolved asset amount to recover; zero means all.
+     *  @return `(assetsRecovered, sharesDestroyed)` on success, or an
+     *      `Unexpected` `TER`: `tecPATH_DRY` on arithmetic overflow,
+     *      `tecINTERNAL` on asset-mismatch or conversion helper failure.
+     */
     Expected<std::pair<STAmount, STAmount>, TER>
     assetsToClawback(
         std::shared_ptr<SLE> const& vault,
diff --git a/include/xrpl/tx/transactors/vault/VaultCreate.h b/include/xrpl/tx/transactors/vault/VaultCreate.h
index 1b05f80c06..52e662f056 100644
--- a/include/xrpl/tx/transactors/vault/VaultCreate.h
+++ b/include/xrpl/tx/transactors/vault/VaultCreate.h
@@ -4,36 +4,160 @@
 
 namespace xrpl {
 
+/** Transactor for the `ttVAULT_CREATE` transaction type.
+ *
+ *  Instantiates a new Vault on the ledger: a pooled-asset construct that holds
+ *  a designated asset inside a synthetic pseudo-account and issues share tokens
+ *  (via `MPTokenIssuance`) to depositors in proportion to their contribution.
+ *
+ *  The three-phase pipeline is:
+ *  - `checkExtraFeatures` / `preflight` — amendment gating and field validation
+ *    (no ledger access)
+ *  - `preclaim` — read-only checks on asset validity, freeze state, and domain
+ *  - `doApply` — creates the Vault SLE, its pseudo-account, the asset holding,
+ *    and the share `MPTokenIssuance`; increments owner count by 2
+ *
+ *  @note `sfScale` is only meaningful for IOU assets; it is rejected for XRP
+ *      and MPT assets in `preflight`.
+ *  @note `sfDomainID` is only valid when `tfVaultPrivate` is set; it also
+ *      requires the `PermissionedDomains` amendment.
+ *  @see VaultDeposit, VaultWithdraw, VaultSet, VaultClawback, VaultDelete
+ */
 class VaultCreate : public Transactor
 {
 public:
+    /** Standard fee and sequence consequences; does not block queued transactions. */
     static constexpr auto kCONSEQUENCES_FACTORY = ConsequencesFactoryType::Normal;
 
     explicit VaultCreate(ApplyContext& ctx) : Transactor(ctx)
     {
     }
 
+    /** Gate the transaction on required amendments.
+     *
+     *  Returns `false` (producing `temDISABLED`) if `featureMPTokensV1` is not
+     *  active, or if `sfDomainID` is present and `featurePermissionedDomains`
+     *  is not active.  Called by `invokePreflight<VaultCreate>` before
+     *  `preflight1`, so disabled transactions are rejected before any field
+     *  parsing.
+     *
+     *  @param ctx  Preflight context.
+     *  @return `true` if the required amendments are active; `false` otherwise.
+     */
     static bool
     checkExtraFeatures(PreflightContext const& ctx);
 
+    /** Return the bitmask of valid flag bits for this transaction type.
+     *
+     *  Returns `tfVaultCreateMask`, which permits `tfVaultPrivate` and
+     *  `tfVaultShareNonTransferable`.  Any flag bits outside this mask
+     *  cause `preflight0` to return `temINVALID_FLAG`.
+     *
+     *  @param ctx  Preflight context (unused).
+     *  @return Bitmask of permitted flag bits.
+     */
     static std::uint32_t
     getFlagsMask(PreflightContext const& ctx);
 
+    /** Perform stateless, ledger-free field validation.
+     *
+     *  Validates the following constraints (returning `temMALFORMED` on
+     *  violation):
+     *  - `sfData`, if present, must not exceed `kMAX_DATA_PAYLOAD_LENGTH`.
+     *  - `sfWithdrawalPolicy`, if present, must equal
+     *    `kVAULT_STRATEGY_FIRST_COME_FIRST_SERVE` (the only supported strategy).
+     *  - `sfDomainID`, if present, must be non-zero and `tfVaultPrivate` must
+     *    be set (domain-scoped access applies only to private vaults).
+     *  - `sfAssetsMaximum`, if present, must not be negative.
+     *  - `sfMPTokenMetadata`, if present, must be non-empty and within
+     *    `kMAX_MP_TOKEN_METADATA_LENGTH`.
+     *  - `sfScale`, if present, is only valid for IOU assets (rejected for XRP
+     *    and MPT) and must not exceed `kVAULT_MAXIMUM_IOU_SCALE`.
+     *
+     *  @param ctx  Preflight context carrying the transaction and active rules.
+     *  @return `tesSUCCESS` or `temMALFORMED`.
+     */
     static NotTEC
     preflight(PreflightContext const& ctx);
 
+    /** Perform read-only ledger checks after signature verification.
+     *
+     *  Checks, in order (returning the first failing code):
+     *  - `canAddHolding`: the asset can be held (e.g., MPT issuance exists).
+     *  - Pseudo-account issuer rejection: if the asset's issuer is a
+     *    pseudo-account (e.g., an AMM LP token or another vault's share MPT),
+     *    returns `tecWRONG_ASSET`.  Such assets cannot be clawed back if needed.
+     *  - Freeze check: returns `tecFROZEN` (IOU) or `tecLOCKED` (MPT) if the
+     *    asset is frozen for the vault owner.
+     *  - Domain existence: if `sfDomainID` is present, the referenced
+     *    `PermissionedDomain` object must exist; returns `tecOBJECT_NOT_FOUND`
+     *    otherwise.
+     *  - Address collision: derives the pseudo-account address from the vault
+     *    keylet; returns `terADDRESS_COLLISION` if the derivation yields zero.
+     *
+     *  @param ctx  Preclaim context carrying a read-only ledger view.
+     *  @return `tesSUCCESS`, `tecWRONG_ASSET`, `tecFROZEN`, `tecLOCKED`,
+     *      `tecOBJECT_NOT_FOUND`, `terADDRESS_COLLISION`, or a code from
+     *      `canAddHolding`.
+     */
     static TER
     preclaim(PreclaimContext const& ctx);
 
+    /** Apply the vault creation to the mutable ledger view.
+     *
+     *  Executes the following steps atomically:
+     *  1. Links a new Vault SLE into the owner's directory via `dirLink`.
+     *  2. Increments the owner count by 2 (vault + pseudo-account), then checks
+     *     `preFeeBalance_` against the new reserve requirement; returns
+     *     `tecINSUFFICIENT_RESERVE` if insufficient.  The increment-before-check
+     *     order is intentional: the account must be able to afford both objects.
+     *  3. Creates the pseudo-account via `createPseudoAccount` keyed from the
+     *     vault's object ID with `sfVaultID` as the discriminator field.
+     *  4. Adds an empty asset holding on the pseudo-account via `addEmptyHolding`
+     *     (either an `MPToken` or a `TrustLine`/`RippleState`).
+     *  5. Creates the share `MPTokenIssuance` on the pseudo-account at sequence 1
+     *     via `MPTokenIssuanceCreate::create`.  The `tfVaultShareNonTransferable`
+     *     flag suppresses `lsfMPTCanEscrow | lsfMPTCanTrade | lsfMPTCanTransfer`;
+     *     `tfVaultPrivate` sets `lsfMPTRequireAuth`.
+     *  6. Populates and inserts the Vault SLE with all fields.
+     *  7. Explicitly authorizes the vault creator's `MPToken` via
+     *     `authorizeMPToken`.  For private vaults, also authorizes the
+     *     pseudo-account itself (so it can hold its own share tokens internally).
+     *  8. Calls `associateAsset` on the vault SLE — this must be the final
+     *     write to round stored numeric values to the asset's precision.
+     *
+     *  @return `tesSUCCESS` or a `tec*` / `ter*` error.
+     */
     TER
     doApply() override;
 
+    /** Accumulate per-entry data for transaction-specific invariant checks.
+     *
+     *  Currently a no-op placeholder; no transaction-specific invariants are
+     *  defined for `VaultCreate` yet.
+     *
+     *  @param isDelete  `true` if the entry was erased.
+     *  @param before    Entry state before the transaction (nullptr if new).
+     *  @param after     Entry state after the transaction.
+     */
     void
     visitInvariantEntry(
         bool isDelete,
         std::shared_ptr<SLE const> const& before,
         std::shared_ptr<SLE const> const& after) override;
 
+    /** Evaluate transaction-specific post-conditions after all entries are visited.
+     *
+     *  Currently a no-op placeholder that always returns `true`; no
+     *  transaction-specific invariants are defined for `VaultCreate` yet.
+     *
+     *  @param tx     The transaction being applied.
+     *  @param result Tentative TER result.
+     *  @param fee    Fee consumed by the transaction.
+     *  @param view   Read-only ledger view after the transaction.
+     *  @param j      Journal for logging invariant failures.
+     *  @return `true` (all invariants pass).
+     */
     [[nodiscard]] bool
     finalizeInvariants(
         STTx const& tx,
diff --git a/include/xrpl/tx/transactors/vault/VaultDelete.h b/include/xrpl/tx/transactors/vault/VaultDelete.h
index dc610cc089..31c3c15e24 100644
--- a/include/xrpl/tx/transactors/vault/VaultDelete.h
+++ b/include/xrpl/tx/transactors/vault/VaultDelete.h
@@ -1,9 +1,34 @@
+/** @file
+ *  Declares the `VaultDelete` transactor, which tears down a Single-Sided AMM
+ *  vault and all of its associated ledger objects.
+ */
+
 #pragma once
 
 #include <xrpl/tx/Transactor.h>
 
 namespace xrpl {
 
+/** Transactor for the `ttVAULT_DELETE` transaction type.
+ *
+ *  Performs a full multi-object teardown of a vault that has been fully
+ *  drained by its depositors.  The teardown sequence is:
+ *  1. Remove the pseudo-account's zero-balance asset holding.
+ *  2. Remove the vault owner's MPToken for share issuance (if any).
+ *  3. Erase the share MPTokenIssuance and its directory entry.
+ *  4. Erase the vault pseudo-account.
+ *  5. Remove the vault SLE from the owner's directory and decrement the
+ *     owner count by 2 (one for the vault object, one for the pseudo-account).
+ *
+ *  Deletion is only possible once every depositor has withdrawn: `preclaim`
+ *  enforces that `sfAssetsAvailable`, `sfAssetsTotal`, and the share
+ *  issuance's `sfOutstandingAmount` are all zero before allowing `doApply`
+ *  to run.  This makes `VaultDelete` the terminal state of the vault lifecycle
+ *  and the strict inverse of `VaultCreate`.
+ *
+ *  @note This transactor is gated on the `featureSingleAssetVault` amendment
+ *      and is not delegable (`Delegation::NotDelegable`).
+ */
 class VaultDelete : public Transactor
 {
 public:
@@ -13,21 +38,89 @@ public:
     {
     }
 
+    /** Stateless preflight validation.
+     *
+     *  Confirms that `sfVaultID` is non-zero.  A zero vault ID cannot
+     *  correspond to any ledger object and is rejected immediately.
+     *
+     *  @return `temMALFORMED` if `sfVaultID` is zero; `tesSUCCESS` otherwise.
+     */
     static NotTEC
     preflight(PreflightContext const& ctx);
 
+    /** Read-only ledger checks before state mutation.
+     *
+     *  Enforces the three-invariant guard that makes safe deletion possible:
+     *  - The submitting account must be the vault `sfOwner`.
+     *  - `sfAssetsAvailable` on the vault must be zero.
+     *  - `sfAssetsTotal` on the vault must be zero.
+     *  - `sfOutstandingAmount` on the share MPTokenIssuance must be zero.
+     *
+     *  Any outstanding assets or shares indicate depositors have not yet
+     *  withdrawn; the vault cannot be deleted while it holds funds.
+     *
+     *  @return `tecNO_ENTRY` if the vault does not exist; `tecNO_PERMISSION`
+     *      if the submitter is not the vault owner or the share issuance owner
+     *      is mismatched; `tecHAS_OBLIGATIONS` if any asset or share balance
+     *      is non-zero; `tecOBJECT_NOT_FOUND` if the share issuance SLE is
+     *      missing; `tesSUCCESS` otherwise.
+     */
     static TER
     preclaim(PreclaimContext const& ctx);
 
+    /** Execute the vault teardown, mutating ledger state.
+     *
+     *  Removes five categories of ledger objects in dependency order.
+     *  Defensive `tecHAS_OBLIGATIONS` guards (marked `LCOV_EXCL`) verify the
+     *  pseudo-account reaches a clean state (zero balance, zero owner count,
+     *  no directory) before it is erased; these guards protect against bugs
+     *  in earlier cleanup steps and are not reachable through valid
+     *  transaction sequences.  Conditions that indicate ledger corruption
+     *  (missing pseudo-account, mismatched issuance owner) return
+     *  `tefBAD_LEDGER` or `tefINTERNAL` rather than a fee-claiming `tec`
+     *  code.
+     *
+     *  @return `tesSUCCESS` on complete teardown; a `tef` code if ledger
+     *      corruption is detected; a `tec` code from `removeEmptyHolding` if
+     *      a holding cannot be removed.
+     */
     TER
     doApply() override;
 
+    /** Per-SLE visitor called by the invariant checker framework.
+     *
+     *  Accumulates per-entry accounting needed by `finalizeInvariants`.
+     *  Called once for each SLE that was modified, inserted, or deleted
+     *  during `doApply`.
+     *
+     *  @param isDelete  `true` if the SLE was erased.
+     *  @param before    SLE state before the transaction; `nullptr` for
+     *      newly inserted entries.
+     *  @param after     SLE state after the transaction; `nullptr` for
+     *      deleted entries.
+     */
     void
     visitInvariantEntry(
         bool isDelete,
         std::shared_ptr<SLE const> const& before,
         std::shared_ptr<SLE const> const& after) override;
 
+    /** Terminal invariant check called after all entries have been visited.
+     *
+     *  Validates that the net effect of the transaction satisfies the
+     *  `ValidVault` invariant (asset/share conservation, immutable field
+     *  constraints).  Returns `false` and logs diagnostics if any violation
+     *  is detected, causing the framework to escalate to
+     *  `tecINVARIANT_FAILED`.
+     *
+     *  @param tx      The transaction being applied.
+     *  @param result  The TER returned by `doApply`.
+     *  @param fee     The fee charged for the transaction.
+     *  @param view    Read-only view of the post-apply ledger state.
+     *  @param j       Journal for diagnostic logging.
+     *  @return `true` if all invariants pass; `false` if any violation is
+     *      detected.
+     */
     [[nodiscard]] bool
     finalizeInvariants(
         STTx const& tx,
diff --git a/include/xrpl/tx/transactors/vault/VaultDeposit.h b/include/xrpl/tx/transactors/vault/VaultDeposit.h
index fbaf987082..5594a5b6f9 100644
--- a/include/xrpl/tx/transactors/vault/VaultDeposit.h
+++ b/include/xrpl/tx/transactors/vault/VaultDeposit.h
@@ -4,30 +4,144 @@
 
 namespace xrpl {
 
+/** Transactor for the `ttVAULT_DEPOSIT` transaction type.
+ *
+ *  Deposits assets into a Vault ledger object and mints vault-share MPTokens
+ *  for the depositor in exchange — the primary liquidity-provision operation
+ *  for on-ledger asset pools.
+ *
+ *  The three-phase pipeline is:
+ *  - `preflight` — rejects a zero `sfVaultID` and any non-positive `sfAmount`
+ *    without accessing the ledger
+ *  - `preclaim` — read-only checks: vault existence, asset type match, freeze
+ *    state, and — for private vaults — domain-credential authorization
+ *  - `doApply` — mints shares via a two-step exchange calculation, updates
+ *    `sfAssetsTotal`/`sfAssetsAvailable`, enforces the vault asset cap, and
+ *    issues two `accountSend` calls (assets in, shares out), both with
+ *    `WaiveTransferFee::Yes` to preserve exchange-rate accuracy
+ *
+ *  @note Transfer fees are intentionally waived on both legs. Allowing them
+ *      would corrupt the `sfAssetsTotal` accounting and break the share
+ *      exchange rate for all depositors.
+ *  @note Private vault access is governed by `DomainID` credentials on the
+ *      share MPT issuance, not by standard MPT issuer authorization, because
+ *      the share issuer is a pseudo-account that cannot proactively authorize
+ *      holders.
+ *  @see VaultWithdraw, VaultCreate, VaultHelpers.h
+ */
 class VaultDeposit : public Transactor
 {
 public:
+    /** Standard fee and sequence consequences; does not block queued transactions. */
     static constexpr auto kCONSEQUENCES_FACTORY = ConsequencesFactoryType::Normal;
 
     explicit VaultDeposit(ApplyContext& ctx) : Transactor(ctx)
     {
     }
 
+    /** Perform stateless, ledger-free field validation.
+     *
+     *  Checks:
+     *  - `sfVaultID` must be non-zero; returns `temMALFORMED` otherwise.
+     *  - `sfAmount` must be positive; returns `temBAD_AMOUNT` otherwise.
+     *
+     *  @param ctx  Preflight context carrying the transaction and active rules.
+     *  @return `tesSUCCESS`, `temMALFORMED`, or `temBAD_AMOUNT`.
+     */
     static NotTEC
     preflight(PreflightContext const& ctx);
 
+    /** Perform read-only ledger checks after signature verification.
+     *
+     *  Validates the following constraints in order, returning the first
+     *  failing code:
+     *  - Vault existence: the object identified by `sfVaultID` must exist;
+     *    returns `tecNO_ENTRY` otherwise.
+     *  - Asset match: `sfAmount` must carry the same asset type as the vault's
+     *    `sfAsset` field; returns `tecWRONG_ASSET` otherwise.
+     *  - Transferability: the vault asset must be transferable from the
+     *    depositor to the vault pseudo-account; returns the result of
+     *    `canTransfer` otherwise.
+     *  - Freeze / lock: returns `tecFROZEN` (IOU) or `tecLOCKED` (MPT) if the
+     *    deposited asset is frozen for the depositor, and `tecLOCKED` if the
+     *    vault's share MPT is locked for the depositor.
+     *  - Private vault authorization: if `lsfVaultPrivate` is set and the
+     *    depositor is not the vault owner, the vault's share MPT issuance must
+     *    carry a `sfDomainID`; `credentials::validDomain` must succeed (or
+     *    return only `tecEXPIRED`, which is suppressed here so that `doApply`
+     *    can delete the expired credentials as a side effect); returns
+     *    `tecNO_AUTH` if no `sfDomainID` is present.
+     *  - Sufficient balance: the depositor must hold at least `sfAmount` of the
+     *    vault asset; returns `tecINSUFFICIENT_FUNDS` otherwise.
+     *
+     *  @param ctx  Preclaim context carrying a read-only ledger view.
+     *  @return `tesSUCCESS`, `tecNO_ENTRY`, `tecWRONG_ASSET`, `tecFROZEN`,
+     *      `tecLOCKED`, `tecNO_AUTH`, `tecINSUFFICIENT_FUNDS`, or a code from
+     *      `canTransfer` / `requireAuth`.
+     */
     static TER
     preclaim(PreclaimContext const& ctx);
 
+    /** Apply the vault deposit to the mutable ledger view.
+     *
+     *  Executes the following steps atomically:
+     *  1. Ensures the depositor holds (or creates) an MPToken for vault shares
+     *     via `enforceMPTokenAuthorization` (private vault, non-owner) or
+     *     `authorizeMPToken` (public vault or vault owner). For the vault owner
+     *     of a private vault, also authorizes the pseudo-account itself.
+     *  2. Computes `sharesCreated` via `assetsToSharesDeposit()` (truncated to
+     *     integral MPT units); returns `tecPRECISION_LOSS` if the result rounds
+     *     to zero, preventing dust deposits.
+     *  3. Back-computes the exact asset cost via `sharesToAssetsDeposit()` to
+     *     guarantee `assetsDeposited <= sfAmount`; any sub-share-unit remainder
+     *     is effectively returned to the depositor.
+     *  4. Updates `sfAssetsTotal` and `sfAssetsAvailable` on the vault SLE,
+     *     then enforces the vault's `sfAssetsMaximum` cap; returns
+     *     `tecLIMIT_EXCEEDED` if the cap would be breached.
+     *  5. Transfers `assetsDeposited` from the depositor to the vault
+     *     pseudo-account via `accountSend` with `WaiveTransferFee::Yes`.
+     *  6. Transfers `sharesCreated` from the vault pseudo-account to the
+     *     depositor via `accountSend` with `WaiveTransferFee::Yes`.
+     *  7. Calls `associateAsset` on the vault SLE — this must be the final
+     *     write to round stored numeric values to the asset's precision.
+     *
+     *  If `assetsToSharesDeposit` or `sharesToAssetsDeposit` throws
+     *  `std::overflow_error` (e.g., due to a large scale factor combined with
+     *  large balances), the exception is caught and `tecPATH_DRY` is returned.
+     *
+     *  @return `tesSUCCESS`, `tecPRECISION_LOSS`, `tecLIMIT_EXCEEDED`,
+     *      `tecPATH_DRY`, or a `tec*` / `ter*` code from the underlying helpers.
+     */
     TER
     doApply() override;
 
+    /** Accumulate per-entry data for transaction-specific invariant checks.
+     *
+     *  Currently a no-op placeholder; no transaction-specific invariants are
+     *  defined for `VaultDeposit` yet.
+     *
+     *  @param isDelete  `true` if the entry was erased.
+     *  @param before    Entry state before the transaction (nullptr if new).
+     *  @param after     Entry state after the transaction.
+     */
     void
     visitInvariantEntry(
         bool isDelete,
         std::shared_ptr<SLE const> const& before,
         std::shared_ptr<SLE const> const& after) override;
 
+    /** Evaluate transaction-specific post-conditions after all entries are visited.
+     *
+     *  Currently a no-op placeholder that always returns `true`; no
+     *  transaction-specific invariants are defined for `VaultDeposit` yet.
+     *
+     *  @param tx     The transaction being applied.
+     *  @param result Tentative TER result.
+     *  @param fee    Fee consumed by the transaction.
+     *  @param view   Read-only ledger view after the transaction.
+     *  @param j      Journal for logging invariant failures.
+     *  @return `true` (all invariants pass).
+     */
     [[nodiscard]] bool
     finalizeInvariants(
         STTx const& tx,
diff --git a/include/xrpl/tx/transactors/vault/VaultSet.h b/include/xrpl/tx/transactors/vault/VaultSet.h
index 719b828766..87b9196100 100644
--- a/include/xrpl/tx/transactors/vault/VaultSet.h
+++ b/include/xrpl/tx/transactors/vault/VaultSet.h
@@ -4,33 +4,142 @@
 
 namespace xrpl {
 
+/** Transactor for the `ttVAULT_SET` transaction type.
+ *
+ *  Allows the vault owner to modify the mutable properties of an existing
+ *  vault after creation.  The three writable fields are: `sfData` (arbitrary
+ *  off-chain metadata), `sfAssetsMaximum` (deposit cap), and `sfDomainID`
+ *  (permissioned-domain gate for private vaults).  All other vault properties
+ *  are fixed at `VaultCreate` time and cannot be changed.
+ *
+ *  The three-phase pipeline is:
+ *  - `checkExtraFeatures` / `preflight` — amendment gating and field
+ *    validation (no ledger access)
+ *  - `preclaim` — read-only ownership and domain checks
+ *  - `doApply` — updates the Vault SLE and, for domain changes, the
+ *    associated `MPTokenIssuance` SLE
+ *
+ *  @note `sfDomainID` can only be set on vaults that were created with
+ *      `lsfVaultPrivate`.  A zero value clears an existing domain restriction;
+ *      it is not possible to retroactively restrict a public vault.
+ *  @note The vault SLE is always marked dirty via `view().update(vault)` even
+ *      when only the issuance SLE changes — this gives the `ValidVault`
+ *      invariant checker a signal that a `VaultSet` occurred.
+ *  @see VaultCreate, VaultDeposit, VaultWithdraw, VaultClawback, VaultDelete
+ */
 class VaultSet : public Transactor
 {
 public:
+    /** Standard fee and sequence consequences; does not block queued transactions. */
     static constexpr auto kCONSEQUENCES_FACTORY = ConsequencesFactoryType::Normal;
 
     explicit VaultSet(ApplyContext& ctx) : Transactor(ctx)
     {
     }
 
+    /** Gate the transaction on required amendments.
+     *
+     *  Returns `false` (producing `temDISABLED`) if `sfDomainID` is present
+     *  in the transaction but `featurePermissionedDomains` is not yet active.
+     *  Called by `invokePreflight<VaultSet>` before `preflight1`, keeping the
+     *  domain-feature availability check separate from per-field branching in
+     *  `preflight`.
+     *
+     *  @param ctx  Preflight context.
+     *  @return `true` if all required amendments are active; `false` otherwise.
+     */
     static bool
     checkExtraFeatures(PreflightContext const& ctx);
 
+    /** Perform stateless, ledger-free field validation.
+     *
+     *  Validates the following constraints (returning `temMALFORMED` on any
+     *  violation):
+     *  - `sfVaultID` must be non-zero.
+     *  - `sfData`, if present, must be non-empty and at most
+     *    `kMAX_DATA_PAYLOAD_LENGTH` bytes.
+     *  - `sfAssetsMaximum`, if present, must be non-negative.
+     *  - At least one of `sfData`, `sfAssetsMaximum`, or `sfDomainID` must be
+     *    present; a transaction that sets none of these fields is rejected as a
+     *    no-op to prevent fee-burning with no effect.
+     *
+     *  @param ctx  Preflight context carrying the transaction and active rules.
+     *  @return `tesSUCCESS` or `temMALFORMED`.
+     */
     static NotTEC
     preflight(PreflightContext const& ctx);
 
+    /** Perform read-only ledger checks after signature verification.
+     *
+     *  Checks, in order (returning the first failing code):
+     *  - The vault ledger object for `sfVaultID` must exist; returns
+     *    `tecNO_ENTRY` if absent.
+     *  - The submitting account must be the vault's `sfOwner`; returns
+     *    `tecNO_PERMISSION` otherwise.
+     *  - The vault's `MPTokenIssuance` SLE must exist; returns `tefINTERNAL`
+     *    if missing (a defensive guard marked `LCOV_EXCL_*` because
+     *    `VaultCreate` and the invariant checker prevent this state).
+     *  - If `sfDomainID` is being set, `lsfVaultPrivate` must be active on the
+     *    vault; returns `tecNO_PERMISSION` for public vaults.
+     *  - A non-zero `sfDomainID` must resolve to an existing
+     *    `PermissionedDomain` object; returns `tecOBJECT_NOT_FOUND` if not.
+     *
+     *  @param ctx  Preclaim context carrying a read-only ledger view.
+     *  @return `tesSUCCESS`, `tecNO_ENTRY`, `tecNO_PERMISSION`,
+     *      `tecOBJECT_NOT_FOUND`, or `tefINTERNAL`.
+     */
     static TER
     preclaim(PreclaimContext const& ctx);
 
+    /** Apply vault configuration changes to the mutable ledger view.
+     *
+     *  Applies updates in order:
+     *  - `sfData`: written directly to the Vault SLE if present.
+     *  - `sfAssetsMaximum`: written to the Vault SLE if present; returns
+     *    `tecLIMIT_EXCEEDED` if a non-zero cap would be lower than the
+     *    vault's current `sfAssetsTotal`.
+     *  - `sfDomainID`: written to or removed from the `MPTokenIssuance` SLE
+     *    (not the Vault SLE) because domain enforcement for MPT-based vaults
+     *    lives at the issuance level.  A zero value calls `makeFieldAbsent` to
+     *    clear the restriction.
+     *
+     *  The Vault SLE is always marked dirty via `view().update(vault)` even
+     *  when only the issuance changed, so the `ValidVault` invariant checker
+     *  can observe the operation.  `associateAsset` is called last to re-round
+     *  stored numeric values to the asset's precision.
+     *
+     *  @return `tesSUCCESS`, `tecLIMIT_EXCEEDED`, or `tefINTERNAL`.
+     */
     TER
     doApply() override;
 
+    /** Accumulate per-entry data for transaction-specific invariant checks.
+     *
+     *  Currently a no-op placeholder; no transaction-specific invariants are
+     *  defined for `VaultSet` yet.
+     *
+     *  @param isDelete  `true` if the entry was erased.
+     *  @param before    Entry state before the transaction (nullptr if new).
+     *  @param after     Entry state after the transaction.
+     */
     void
     visitInvariantEntry(
         bool isDelete,
         std::shared_ptr<SLE const> const& before,
         std::shared_ptr<SLE const> const& after) override;
 
+    /** Evaluate transaction-specific post-conditions after all entries are visited.
+     *
+     *  Currently a no-op placeholder that always returns `true`; no
+     *  transaction-specific invariants are defined for `VaultSet` yet.
+     *
+     *  @param tx     The transaction being applied.
+     *  @param result Tentative TER result.
+     *  @param fee    Fee consumed by the transaction.
+     *  @param view   Read-only ledger view after the transaction.
+     *  @param j      Journal for logging invariant failures.
+     *  @return `true` (all invariants pass).
+     */
     [[nodiscard]] bool
     finalizeInvariants(
         STTx const& tx,
diff --git a/include/xrpl/tx/transactors/vault/VaultWithdraw.h b/include/xrpl/tx/transactors/vault/VaultWithdraw.h
index fd3739bc2f..7c625c46a9 100644
--- a/include/xrpl/tx/transactors/vault/VaultWithdraw.h
+++ b/include/xrpl/tx/transactors/vault/VaultWithdraw.h
@@ -4,30 +4,150 @@
 
 namespace xrpl {
 
+/** Transactor for the `ttVAULT_WITHDRAW` transaction type.
+ *
+ *  Redeems vault-share MPTokens for the underlying pooled asset — the inverse
+ *  of `VaultDeposit`. The submitter specifies `sfAmount` in either the vault's
+ *  underlying asset or its share MPT; the complementary quantity is computed
+ *  via the vault's current share-to-asset exchange rate.
+ *
+ *  The three-phase pipeline is:
+ *  - `preflight` — rejects a zero `sfVaultID`, a non-positive `sfAmount`, and
+ *    a zero explicit `sfDestination` without accessing the ledger.
+ *  - `preclaim` — read-only checks: vault existence, asset denomination,
+ *    transferability, withdrawal limits (with share-to-asset conversion when
+ *    `fixSecurity3_1_3` is active), destination authorization, and freeze state.
+ *  - `doApply` — burns shares, decrements `sfAssetsTotal`/`sfAssetsAvailable`,
+ *    and credits the underlying asset to the destination account.
+ *
+ *  @note Possession of vault shares is treated as standing authorization to
+ *      withdraw. The `lsfVaultPrivate` flag is intentionally not re-checked
+ *      in `doApply`; holding a share proves prior authorized deposit.
+ *  @note Transfer fees are waived when returning shares to the vault
+ *      pseudo-account (`WaiveTransferFee::Yes`) because shares are internal
+ *      bookkeeping tokens, not economic transfers.
+ *  @see VaultDeposit, VaultCreate, VaultHelpers.h
+ */
 class VaultWithdraw : public Transactor
 {
 public:
+    /** Standard fee and sequence consequences; does not block queued transactions. */
     static constexpr auto kCONSEQUENCES_FACTORY = ConsequencesFactoryType::Normal;
 
     explicit VaultWithdraw(ApplyContext& ctx) : Transactor(ctx)
     {
     }
 
+    /** Perform stateless, ledger-free field validation.
+     *
+     *  Checks:
+     *  - `sfVaultID` must be non-zero; returns `temMALFORMED` otherwise.
+     *  - `sfAmount` must be positive; returns `temBAD_AMOUNT` otherwise.
+     *  - If `sfDestination` is present, it must be non-zero; returns
+     *    `temMALFORMED` otherwise.
+     *
+     *  @param ctx  Preflight context carrying the transaction and active rules.
+     *  @return `tesSUCCESS`, `temMALFORMED`, or `temBAD_AMOUNT`.
+     */
     static NotTEC
     preflight(PreflightContext const& ctx);
 
+    /** Perform read-only ledger checks after signature verification.
+     *
+     *  Validates the following constraints in order, returning the first
+     *  failing code:
+     *  - Vault existence: the object identified by `sfVaultID` must exist;
+     *    returns `tecNO_ENTRY` otherwise.
+     *  - Asset denomination: `sfAmount` must be denominated in either the
+     *    vault's `sfAsset` or its share MPT; returns `tecWRONG_ASSET` otherwise.
+     *  - Transferability: the vault asset must be transferable from the vault
+     *    pseudo-account to the destination; returns the result of `canTransfer`
+     *    otherwise.
+     *  - Withdrawal policy: only `vaultStrategyFirstComeFirstServe` is
+     *    supported; any other value returns `tefINTERNAL` (invariant violation).
+     *  - Withdrawal limits: when `fixSecurity3_1_3` is active and the amount is
+     *    share-denominated, shares are first converted to an equivalent asset
+     *    amount before calling `canWithdraw`. Pre-amendment, share-denominated
+     *    requests bypassed this check entirely. Overflow during conversion
+     *    returns `tecPATH_DRY`.
+     *  - Destination authorization: `WeakAuth` (trust line or MPToken may be
+     *    created in `doApply`) when withdrawing to `sfAccount`; `StrongAuth`
+     *    (trust line or MPToken must already exist) when withdrawing to a third
+     *    party.
+     *  - Freeze / lock: returns a freeze error if the vault asset is frozen for
+     *    the destination, or if the vault's share MPT is frozen for the
+     *    submitting account.
+     *
+     *  @param ctx  Preclaim context carrying a read-only ledger view.
+     *  @return `tesSUCCESS`, `tecNO_ENTRY`, `tecWRONG_ASSET`, `tecPATH_DRY`,
+     *      `tefINTERNAL`, `tecFROZEN`, `tecLOCKED`, or a code from
+     *      `canTransfer` / `canWithdraw` / `requireAuth` / `checkFrozen`.
+     */
     static TER
     preclaim(PreclaimContext const& ctx);
 
+    /** Apply the vault withdrawal to the mutable ledger view.
+     *
+     *  Executes the following steps atomically:
+     *  1. Resolves the vault and share issuance SLEs with write access.
+     *  2. If `sfAmount` is asset-denominated: calls `assetsToSharesWithdraw` to
+     *     find `sharesRedeemed`, returns `tecPRECISION_LOSS` if the result is
+     *     zero (dust prevention), then back-computes `assetsWithdrawn` via
+     *     `sharesToAssetsWithdraw`. If `sfAmount` is share-denominated: uses the
+     *     amount directly as `sharesRedeemed` and derives `assetsWithdrawn`.
+     *  3. Returns `tecPATH_DRY` if conversion throws `std::overflow_error`.
+     *  4. Verifies the submitter holds at least `sharesRedeemed` via
+     *     `accountHolds`; returns `tecINSUFFICIENT_FUNDS` if not.
+     *  5. Checks `sfAssetsAvailable` (not the raw pseudo-account balance)
+     *     against `assetsWithdrawn`; returns `tecINSUFFICIENT_FUNDS` if
+     *     insufficient. Using `sfAssetsAvailable` correctly excludes assets
+     *     pledged to external lending positions.
+     *  6. Decrements both `sfAssetsTotal` and `sfAssetsAvailable` on the vault
+     *     by `assetsWithdrawn`.
+     *  7. Transfers `sharesRedeemed` from the submitter back to the vault
+     *     pseudo-account via `accountSend` with `WaiveTransferFee::Yes`.
+     *  8. Attempts to remove the submitter's now-empty share MPToken via
+     *     `removeEmptyHolding`; `tecHAS_OBLIGATIONS` (balance non-zero) is
+     *     silently tolerated. Skipped when the submitter is the vault owner.
+     *  9. Calls `doWithdraw` to credit `assetsWithdrawn` from the vault
+     *     pseudo-account to the destination account.
+     *  10. Calls `associateAsset` on the vault SLE — must be the final write to
+     *      round stored numeric values to the asset's precision.
+     *
+     *  @return `tesSUCCESS`, `tecPRECISION_LOSS`, `tecPATH_DRY`,
+     *      `tecINSUFFICIENT_FUNDS`, or a `tec*` / `ter*` code from the
+     *      underlying helpers.
+     */
     TER
     doApply() override;
 
+    /** Accumulate per-entry data for transaction-specific invariant checks.
+     *
+     *  Currently a no-op placeholder; no transaction-specific invariants are
+     *  defined for `VaultWithdraw` yet.
+     *
+     *  @param isDelete  `true` if the entry was erased.
+     *  @param before    Entry state before the transaction (nullptr if new).
+     *  @param after     Entry state after the transaction.
+     */
     void
     visitInvariantEntry(
         bool isDelete,
         std::shared_ptr<SLE const> const& before,
         std::shared_ptr<SLE const> const& after) override;
 
+    /** Evaluate transaction-specific post-conditions after all entries are visited.
+     *
+     *  Currently a no-op placeholder that always returns `true`; no
+     *  transaction-specific invariants are defined for `VaultWithdraw` yet.
+     *
+     *  @param tx     The transaction being applied.
+     *  @param result Tentative TER result.
+     *  @param fee    Fee consumed by the transaction.
+     *  @param view   Read-only ledger view after the transaction.
+     *  @param j      Journal for logging invariant failures.
+     *  @return `true` (all invariants pass).
+     */
     [[nodiscard]] bool
     finalizeInvariants(
         STTx const& tx,
diff --git a/src/libxrpl/protocol/digest.cpp b/src/libxrpl/protocol/digest.cpp
index 2e1b2b25cf..b7a6239afe 100644
--- a/src/libxrpl/protocol/digest.cpp
+++ b/src/libxrpl/protocol/digest.cpp
@@ -1,3 +1,16 @@
+/** @file
+ *  Concrete implementations of the RIPEMD-160, SHA-256, and SHA-512 hashers.
+ *
+ *  Each hasher stores its OpenSSL context in an opaque `char ctx_[]` buffer
+ *  declared in the header so that `digest.h` does not need to expose any
+ *  OpenSSL headers to its consumers.  The constructors here recover the real
+ *  OpenSSL type via `reinterpret_cast`, which is only safe when the buffer
+ *  size exactly matches `sizeof` the target struct.  A `static_assert` in
+ *  each constructor enforces that invariant at compile time: if an OpenSSL
+ *  upgrade ever changes a context struct's size, the build breaks here rather
+ *  than silently corrupting memory at runtime.
+ */
+
 #include <xrpl/protocol/digest.h>
 
 #include <openssl/ripemd.h>
@@ -9,6 +22,10 @@ namespace xrpl {
 
 OpensslRipemd160Hasher::OpensslRipemd160Hasher()
 {
+    // Compile-time firewall: ctx_ must be exactly sizeof(RIPEMD160_CTX) bytes
+    // for the reinterpret_cast below to be safe.  If an OpenSSL upgrade ever
+    // changes the size of RIPEMD160_CTX, this assert fires and the hardcoded
+    // buffer size in digest.h must be updated to match.
     static_assert(sizeof(decltype(OpensslRipemd160Hasher::ctx_)) == sizeof(RIPEMD160_CTX), "");
     auto const ctx = reinterpret_cast<RIPEMD160_CTX*>(ctx_);
     RIPEMD160_Init(ctx);
@@ -34,6 +51,9 @@ operator result_type() noexcept
 
 OpensslSha512Hasher::OpensslSha512Hasher()
 {
+    // Same opaque-buffer safety check as OpensslRipemd160Hasher: ctx_ must
+    // match sizeof(SHA512_CTX).  Update the buffer size in digest.h if this
+    // assert fires after an OpenSSL upgrade.
     static_assert(sizeof(decltype(OpensslSha512Hasher::ctx_)) == sizeof(SHA512_CTX), "");
     auto const ctx = reinterpret_cast<SHA512_CTX*>(ctx_);
     SHA512_Init(ctx);
@@ -59,6 +79,9 @@ operator result_type() noexcept
 
 OpensslSha256Hasher::OpensslSha256Hasher()
 {
+    // Same opaque-buffer safety check as OpensslRipemd160Hasher: ctx_ must
+    // match sizeof(SHA256_CTX).  Update the buffer size in digest.h if this
+    // assert fires after an OpenSSL upgrade.
     static_assert(sizeof(decltype(OpensslSha256Hasher::ctx_)) == sizeof(SHA256_CTX), "");
     auto const ctx = reinterpret_cast<SHA256_CTX*>(ctx_);
     SHA256_Init(ctx);
diff --git a/src/libxrpl/protocol/tokens.cpp b/src/libxrpl/protocol/tokens.cpp
index 91063d3fa6..41f6590884 100644
--- a/src/libxrpl/protocol/tokens.cpp
+++ b/src/libxrpl/protocol/tokens.cpp
@@ -1,5 +1,34 @@
-//
-/* The base58 encoding & decoding routines in the b58_ref namespace are taken
+/**
+ * @file tokens.cpp
+ * @brief Base58Check encoding and decoding for XRPL identifiers.
+ *
+ * This file is the single source of truth for XRPL's Base58Check scheme —
+ * the algorithm that converts raw binary account IDs, key pairs, and seeds
+ * into the human-readable strings users interact with every day
+ * (e.g., `rHb9CJAWyB4rj91VRWn96DkukG4bwdtyTh`).
+ *
+ * Every encoded XRPL identifier follows the wire layout:
+ * @code
+ *   [ type byte (1) ][ raw payload (N) ][ checksum (4) ]
+ * @endcode
+ * The checksum is the first four bytes of SHA-256(SHA-256(type || payload)),
+ * identical to Bitcoin's checksum design.
+ *
+ * Two internal implementations are provided and selected at compile time:
+ * - `b58_ref` — portable O(n²) algorithm adapted from Bitcoin Core.
+ * - `b58_fast` — 10-15× faster path using GCC's `unsigned __int128` extension;
+ *   unavailable on MSVC, which falls back to `b58_ref`.
+ *
+ * The fast algorithm stages the conversion as:
+ * @code
+ *   base 58 → base 58^10 → base 2^64 → base 2^8
+ * @endcode
+ * `58^10 = 430804206899405824` is the largest power of 58 that fits in a
+ * 64-bit register, enabling the first hop to use simple 64-bit arithmetic.
+ * The multi-precision second hop then operates on far fewer, larger
+ * coefficients, dramatically reducing total work.
+ *
+ * The base58 encoding & decoding routines in the b58_ref namespace are taken
  * from Bitcoin but have been modified from the original.
  *
  * Copyright (c) 2014 The Bitcoin Core developers
@@ -122,9 +151,22 @@ coefficients sizes greatly speeds up the multi-precision computations.
 
 namespace xrpl {
 
+/** The 58-character XRPL Base58 alphabet.
+ *
+ *  Deliberately chosen so that an `AccountID` of all-zero bytes encodes to a
+ *  string beginning with `'r'`, letting users and validators visually
+ *  recognize a classic XRPL account address without decoding.
+ */
 static constexpr char const* kALPHABET_FORWARD =
     "rpshnaf39wBUDNEGHJKLM4PQRST7VWXYZ2bcdeCg65jkm8oFqi1tuvAxyz";
 
+/** Compile-time reverse lookup table for the XRPL Base58 alphabet.
+ *
+ *  Maps each ASCII byte value to its 0-based index in `kALPHABET_FORWARD`,
+ *  or `-1` if the character is not a valid Base58 digit.  Used by the
+ *  decoder to convert encoded characters back to numeric coefficients
+ *  without a linear search.
+ */
 static constexpr std::array<int, 256> const kALPHABET_REVERSE = []() {
     std::array<int, 256> map{};
     for (auto& m : map)
@@ -134,6 +176,14 @@ static constexpr std::array<int, 256> const kALPHABET_REVERSE = []() {
     return map;
 }();
 
+/** Hash a raw buffer with the given Hasher.
+ *
+ *  @tparam Hasher A type satisfying the XRP hasher concept — default-constructible,
+ *      callable with `(void const*, size_t)`, and convertible to its `result_type`.
+ *  @param data Pointer to the bytes to hash.
+ *  @param size Number of bytes to hash.
+ *  @return The hash digest.
+ */
 template <class Hasher>
 static typename Hasher::result_type
 digest(void const* data, std::size_t size) noexcept
@@ -143,6 +193,16 @@ digest(void const* data, std::size_t size) noexcept
     return static_cast<typename Hasher::result_type>(h);
 }
 
+/** Hash a fixed-size byte array with the given Hasher.
+ *
+ *  Convenience overload for `std::array<T, N>` where `sizeof(T) == 1`.
+ *
+ *  @tparam Hasher A type satisfying the XRP hasher concept.
+ *  @tparam T Byte-sized element type.
+ *  @tparam N Array length.
+ *  @param v The byte array to hash.
+ *  @return The hash digest.
+ */
 template <class Hasher, class T, std::size_t N, class = std::enable_if_t<sizeof(T) == 1>>
 static typename Hasher::result_type
 digest(std::array<T, N> const& v)
@@ -150,7 +210,17 @@ digest(std::array<T, N> const& v)
     return digest<Hasher>(v.data(), v.size());
 }
 
-// Computes a double digest (e.g. digest of the digest)
+/** Compute the hash of a hash (double-digest).
+ *
+ *  Applies the Hasher twice: first to produce an intermediate digest from
+ *  `args`, then hashes that digest again.  The result is the same as
+ *  `digest<Hasher>(digest<Hasher>(args...))`.
+ *
+ *  @tparam Hasher A type satisfying the XRP hasher concept.
+ *  @tparam Args  Arguments forwarded to the inner `digest` overload.
+ *  @param args   Data arguments passed to the inner digest computation.
+ *  @return The double-digest result.
+ */
 template <class Hasher, class... Args>
 static typename Hasher::result_type
 digest2(Args const&... args)
@@ -174,6 +244,19 @@ checksum(void* out, void const* message, std::size_t size)
     std::memcpy(out, h.data(), 4);
 }
 
+/** Encode a raw payload as a Base58Check XRPL token string.
+ *
+ *  Prepends the `type` byte, appends a 4-byte double-SHA256 checksum, then
+ *  Base58-encodes the result using the XRPL alphabet.  Dispatches to the
+ *  fast (`b58_fast`) implementation on non-MSVC compilers, and to the
+ *  portable reference implementation (`b58_ref`) on MSVC.
+ *
+ *  @param type  The `TokenType` version byte that prefixes the encoded form
+ *      (e.g., `TokenType::AccountID = 0` → addresses start with `'r'`).
+ *  @param token Pointer to the raw payload bytes to encode.
+ *  @param size  Number of payload bytes.
+ *  @return The Base58Check-encoded string, or an empty string on error.
+ */
 [[nodiscard]] std::string
 encodeBase58Token(TokenType type, void const* token, std::size_t size)
 {
@@ -184,6 +267,22 @@ encodeBase58Token(TokenType type, void const* token, std::size_t size)
 #endif
 }
 
+/** Decode a Base58Check XRPL token string and return the raw payload.
+ *
+ *  Decodes the Base58 string, then validates:
+ *  1. The decoded length is at least 6 bytes (1 type + 1 payload min + 4 checksum).
+ *  2. The leading type byte matches `type`.
+ *  3. The trailing 4-byte checksum is correct.
+ *
+ *  Dispatches to the fast (`b58_fast`) implementation on non-MSVC compilers,
+ *  and to the portable reference implementation (`b58_ref`) on MSVC.
+ *
+ *  @param s    The Base58Check-encoded string to decode.
+ *  @param type The expected `TokenType` version byte.
+ *  @return The raw payload (type byte and checksum stripped), or an empty
+ *      string if the input is invalid, the type does not match, or the
+ *      checksum fails.
+ */
 [[nodiscard]] std::string
 decodeBase58Token(std::string const& s, TokenType type)
 {
@@ -198,6 +297,21 @@ namespace b58_ref {
 
 namespace detail {
 
+/** Encode a raw byte buffer as a Base58 string (reference O(n²) algorithm).
+ *
+ *  Uses the Bitcoin-derived algorithm: for each input byte the working
+ *  base-58 buffer is multiplied by 256 and the byte added as carry.
+ *  Leading zero bytes map to the first alphabet character (`'r'`) to
+ *  preserve bijectivity.
+ *
+ *  @param message  Pointer to the data to encode.
+ *  @param size     Number of bytes in `message`.
+ *  @param temp     Caller-supplied scratch buffer; must be at least
+ *      `size * 138 / 100 + 1` bytes (derived from log(256)/log(58) ≈ 1.38).
+ *  @param tempSize Size of `temp` in bytes.
+ *  @return The Base58-encoded string.
+ *  @note Exposed in the header for unit-testing comparison against the fast path.
+ */
 std::string
 encodeBase58(void const* message, std::size_t size, void* temp, std::size_t tempSize)
 {
@@ -245,6 +359,18 @@ encodeBase58(void const* message, std::size_t size, void* temp, std::size_t temp
     return str;
 }
 
+/** Decode a Base58 string to raw bytes (reference O(n²) algorithm).
+ *
+ *  Reverses `encodeBase58`: for each input character the working base-256
+ *  buffer is multiplied by 58 and the digit value added as carry.
+ *  Leading `'r'` characters (index 0 in the alphabet) map back to leading
+ *  zero bytes.
+ *
+ *  @param s The Base58-encoded string to decode.
+ *  @return The decoded byte string, or an empty string if any character is
+ *      not in the XRPL alphabet or if the input exceeds 64 characters.
+ *  @note Exposed in the header for unit-testing comparison against the fast path.
+ */
 std::string
 decodeBase58(std::string const& s)
 {
@@ -293,6 +419,18 @@ decodeBase58(std::string const& s)
 
 }  // namespace detail
 
+/** Encode a raw payload as a Base58Check XRPL token string (reference implementation).
+ *
+ *  Constructs the wire layout `[type][payload][checksum]` in a stack-allocated
+ *  buffer, then delegates to `detail::encodeBase58`.  The scratch buffer is
+ *  sized at `expanded * 3` bytes, which is a safe upper bound derived from
+ *  `log(256) / log(58) ≈ 1.38` plus one character of slack.
+ *
+ *  @param type  The `TokenType` version byte to prepend.
+ *  @param token Pointer to the payload bytes.
+ *  @param size  Number of payload bytes.
+ *  @return The Base58Check-encoded string.
+ */
 std::string
 encodeBase58Token(TokenType type, void const* token, std::size_t size)
 {
@@ -306,8 +444,6 @@ encodeBase58Token(TokenType type, void const* token, std::size_t size)
 
     boost::container::small_vector<std::uint8_t, 1024> buf(bufsize);
 
-    // Lay the data out as
-    //      <type><token><checksum>
     buf[0] = safeCast<std::underlying_type_t<TokenType>>(type);
     if (size != 0u)
         std::memcpy(buf.data() + 1, token, size);
@@ -316,6 +452,16 @@ encodeBase58Token(TokenType type, void const* token, std::size_t size)
     return detail::encodeBase58(buf.data(), expanded, buf.data() + expanded, bufsize - expanded);
 }
 
+/** Decode a Base58Check XRPL token string and return the raw payload (reference implementation).
+ *
+ *  Validates decoded length (≥ 6 bytes), the leading type byte, and the
+ *  trailing 4-byte checksum.  Returns an empty string on any mismatch.
+ *
+ *  @param s    The Base58Check-encoded string to decode.
+ *  @param type The expected `TokenType` version byte.
+ *  @return The raw payload with the type byte and checksum stripped, or an
+ *      empty string if validation fails.
+ */
 std::string
 decodeBase58Token(std::string const& s, TokenType type)
 {
@@ -345,7 +491,33 @@ decodeBase58Token(std::string const& s, TokenType type)
 // meantime MS falls back to the slower reference implementation)
 namespace b58_fast {
 namespace detail {
-// Note: both the input and output will be BIG ENDIAN
+
+/** Encode big-endian binary data as a big-endian Base58 byte sequence (fast path).
+ *
+ *  Implements the three-hop conversion `base 256 → base 2^64 → base 58^10 → base 58`
+ *  using GCC's `unsigned __int128` for carry-free multi-precision arithmetic:
+ *
+ *  1. The input bytes are loaded into at most 5 `uint64_t` limbs (little-endian
+ *     coefficient order), representing the value in base 2^64.
+ *  2. The 2^64 limb array is repeatedly divided by `58^10 = 430804206899405824`
+ *     via `inplaceBigintDivRem` to extract base-58^10 coefficients.
+ *  3. Each base-58^10 coefficient is expanded into 10 base-58 digits via
+ *     `b5810ToB58Be` and mapped through `kALPHABET_FORWARD`.
+ *
+ *  Leading zero bytes in `input` each emit the alphabet's first character
+ *  (`'r'`) to preserve the bijective encoding property.
+ *
+ *  @note Both `input` and `out` are in big-endian byte order.
+ *  @note Maximum valid `input` is 38 bytes (33-byte public key + 1 type + 4 checksum).
+ *      Larger inputs return `TokenCodecErrc::InputTooLarge`.
+ *
+ *  @param input The big-endian binary data to encode.
+ *  @param out   Caller-supplied output buffer; must be large enough for the
+ *      encoded result (≈ ceil(len×log(256)/log(58)) + leading-zero count).
+ *      Returns `TokenCodecErrc::OutputTooSmall` if insufficient.
+ *  @return On success, a subspan of `out` containing the encoded Base58 bytes.
+ *      On failure, an unexpected `TokenCodecErrc` error code.
+ */
 B58Result<std::span<std::uint8_t>>
 b256ToB58Be(std::span<std::uint8_t const> input, std::span<std::uint8_t> out)
 {
@@ -466,7 +638,35 @@ b256ToB58Be(std::span<std::uint8_t const> input, std::span<std::uint8_t> out)
     return out.subspan(0, outIndex);
 }
 
-// Note the input is BIG ENDIAN (some fn in this module use little endian)
+/** Decode a big-endian Base58 string to big-endian binary data (fast path).
+ *
+ *  Reverses `b256ToB58Be` using the same three-hop strategy in reverse:
+ *  `base 58 → base 58^10 → base 2^64 → base 2^8`:
+ *
+ *  1. The input string is partitioned into chunks of 10 characters
+ *     (with a possible shorter partial chunk at the start).  Each chunk is
+ *     accumulated into a `uint64_t` base-58^10 coefficient using simple
+ *     64-bit arithmetic.
+ *  2. The base-58^10 coefficients synthesize a multi-precision value stored
+ *     as `uint64_t` limbs via `inplaceBigintMul` (×58^10) and
+ *     `inplaceBigintAdd` (+coefficient) for each chunk.
+ *  3. The `uint64_t` limbs are written out as big-endian bytes, suppressing
+ *     leading zeros from the most-significant limb.
+ *
+ *  Leading `'r'` characters (alphabet index 0) map back to leading zero bytes.
+ *
+ *  @note The input string is big-endian (most significant Base58 digit first).
+ *  @note Maximum input length is 52 characters (encoding up to 38 bytes);
+ *      larger inputs return `TokenCodecErrc::InputTooLarge`.
+ *  @note `out` must be at least 8 bytes; returns `TokenCodecErrc::OutputTooSmall`
+ *      if the buffer is too small to hold the decoded result.
+ *
+ *  @param input The Base58-encoded string to decode (big-endian digit order).
+ *  @param out   Caller-supplied output buffer for the decoded bytes.
+ *  @return On success, a subspan of `out` containing the decoded big-endian bytes.
+ *      On failure, an unexpected `TokenCodecErrc` error code (e.g.,
+ *      `InvalidEncodingChar` for characters not in the XRPL alphabet).
+ */
 B58Result<std::span<std::uint8_t>>
 b58ToB256Be(std::string_view input, std::span<std::uint8_t> out)
 {
@@ -604,6 +804,21 @@ b58ToB256Be(std::string_view input, std::span<std::uint8_t> out)
 }
 }  // namespace detail
 
+/** Encode a raw payload as a Base58Check XRPL token (fast, span-based overload).
+ *
+ *  Builds the wire layout `[tokenType][input][checksum(4)]` in a 128-byte
+ *  stack buffer, then delegates to `detail::b256ToB58Be` to perform the
+ *  base conversion.  The output is written directly into the caller-supplied
+ *  `out` span, avoiding heap allocation.
+ *
+ *  @param tokenType The `TokenType` version byte to prepend.
+ *  @param input     The raw payload bytes to encode.  Must be non-empty and
+ *      at most 123 bytes (128 buffer − 5 bytes for type + checksum).
+ *  @param out       Caller-supplied output buffer for the encoded Base58 bytes.
+ *  @return On success, a subspan of `out` containing the encoded result.
+ *      On failure, an unexpected `TokenCodecErrc` (`InputTooLarge`,
+ *      `InputTooSmall`, or `OutputTooSmall`).
+ */
 B58Result<std::span<std::uint8_t>>
 encodeBase58Token(
     TokenType tokenType,
@@ -620,21 +835,33 @@ encodeBase58Token(
     {
         return Unexpected(TokenCodecErrc::InputTooSmall);
     }
-    // <type (1 byte)><token (input len)><checksum (4 bytes)>
     buf[0] = static_cast<std::uint8_t>(tokenType);
-    // buf[1..=input.len()] = input;
     memcpy(&buf[1], input.data(), input.size());
     size_t const checksumI = input.size() + 1;
-    // buf[checksum_i..checksum_i + 4] = checksum
     checksum(buf.data() + checksumI, buf.data(), checksumI);
     std::span<std::uint8_t const> const b58Span(buf.data(), input.size() + 5);
     return detail::b256ToB58Be(b58Span, out);
 }
-// Convert from base 58 to base 256, largest coefficients first
-// The input is encoded in XRPL format, with the token in the first
-// byte and the checksum in the last four bytes.
-// The decoded base 256 value does not include the token type or checksum.
-// It is an error if the token type or checksum does not match.
+
+/** Decode a Base58Check XRPL token and return the raw payload (fast, span-based overload).
+ *
+ *  Converts the Base58 string to binary via `detail::b58ToB256Be`, then
+ *  applies three-layer validation:
+ *  1. Decoded length ≥ 6 bytes (1 type + at least 1 payload byte + 4 checksum).
+ *  2. Leading type byte matches `type`.
+ *  3. Trailing 4-byte double-SHA256 checksum is correct.
+ *
+ *  Only the interior payload (type byte and checksum stripped) is copied into
+ *  `outBuf` on success.
+ *
+ *  @param type   The expected `TokenType` version byte.
+ *  @param s      The Base58Check-encoded string to decode (largest digit first).
+ *  @param outBuf Caller-supplied buffer for the decoded payload bytes.
+ *  @return On success, a subspan of `outBuf` containing the decoded payload.
+ *      On failure, an unexpected `TokenCodecErrc` (`InputTooSmall`,
+ *      `MismatchedTokenType`, `MismatchedChecksum`, `OutputTooSmall`,
+ *      `InvalidEncodingChar`, or `InputTooLarge`).
+ */
 B58Result<std::span<std::uint8_t>>
 decodeBase58Token(TokenType type, std::string_view s, std::span<std::uint8_t> outBuf)
 {
@@ -670,16 +897,22 @@ decodeBase58Token(TokenType type, std::string_view s, std::span<std::uint8_t> ou
     return outBuf.subspan(0, outSize);
 }
 
+/** Encode a raw payload as a Base58Check XRPL token string (fast, legacy string overload).
+ *
+ *  Bridges the zero-allocation span-based API to the legacy `std::string`
+ *  interface expected by callers that pre-date the span overload.  Pre-allocates
+ *  128 bytes — well above the theoretical maximum of ≈46 Base58 characters for
+ *  a 33-byte public key — to avoid reallocation.
+ *
+ *  @param type  The `TokenType` version byte to prepend.
+ *  @param token Pointer to the raw payload bytes.
+ *  @param size  Number of payload bytes.
+ *  @return The Base58Check-encoded string, or an empty string on any error.
+ */
 [[nodiscard]] std::string
 encodeBase58Token(TokenType type, void const* token, std::size_t size)
 {
     std::string sr;
-    // The largest object encoded as base58 is 33 bytes; This will be encoded in
-    // at most ceil(log(2^256,58)) bytes, or 46 bytes. 128 is plenty (and
-    // there's not real benefit making it smaller). Note that 46 bytes may be
-    // encoded in more than 46 base58 chars. Since decode uses 64 as the
-    // over-allocation, this function uses 128 (again, over-allocation assuming
-    // 2 base 58 char per byte)
     sr.resize(128);
     std::span<std::uint8_t> const outSp(reinterpret_cast<std::uint8_t*>(sr.data()), sr.size());
     std::span<std::uint8_t const> const inSp(reinterpret_cast<std::uint8_t const*>(token), size);
@@ -690,12 +923,21 @@ encodeBase58Token(TokenType type, void const* token, std::size_t size)
     return sr;
 }
 
+/** Decode a Base58Check XRPL token string and return the raw payload (fast, legacy string overload).
+ *
+ *  Bridges the zero-allocation span-based API to the legacy `std::string`
+ *  interface.  Pre-allocates 64 bytes — sufficient for any valid XRPL token
+ *  payload — to avoid reallocation.
+ *
+ *  @param s    The Base58Check-encoded string to decode.
+ *  @param type The expected `TokenType` version byte.
+ *  @return The raw payload with type byte and checksum stripped, or an empty
+ *      string on any error (invalid character, type mismatch, checksum failure, etc.).
+ */
 [[nodiscard]] std::string
 decodeBase58Token(std::string const& s, TokenType type)
 {
     std::string sr;
-    // The largest object encoded as base58 is 33 bytes; 64 is plenty (and
-    // there's no benefit making it smaller)
     sr.resize(64);
     std::span<std::uint8_t> const outSp(reinterpret_cast<std::uint8_t*>(sr.data()), sr.size());
     auto r = b58_fast::decodeBase58Token(type, s, outSp);
diff --git a/src/libxrpl/tx/transactors/dex/OfferCreate.cpp b/src/libxrpl/tx/transactors/dex/OfferCreate.cpp
index 83d531ec2b..6c32a6a4c3 100644
--- a/src/libxrpl/tx/transactors/dex/OfferCreate.cpp
+++ b/src/libxrpl/tx/transactors/dex/OfferCreate.cpp
@@ -157,7 +157,6 @@ OfferCreate::preflight(PreflightContext const& ctx)
         JLOG(j.debug()) << "Malformed offer: redundant (IOU for IOU)";
         return temREDUNDANT;
     }
-    // We don't allow a non-native currency to use the currency code XRP.
     if (badAsset() == uPaysAsset || badAsset() == uGetsAsset)
     {
         JLOG(j.debug()) << "Malformed offer: bad currency";
@@ -200,7 +199,8 @@ OfferCreate::preclaim(PreclaimContext const& ctx)
         return tecFROZEN;
     }
 
-    // Allow unfunded MPT for issuer (OutstandingAmount >= MaximumAmount)
+    // MPT issuers may place offers even when OutstandingAmount >= MaximumAmount
+    // (they have no "balance" to be funded from).
     if ((!saTakerGets.holds<MPTIssue>() || saTakerGets.getIssuer() != id) &&
         accountFunds(
             ctx.view,
@@ -214,8 +214,6 @@ OfferCreate::preclaim(PreclaimContext const& ctx)
         return tecUNFUNDED_OFFER;
     }
 
-    // This can probably be simplified to make sure that you cancel sequences
-    // before the transaction sequence number.
     if (cancelSequence && (uAccountSequence <= *cancelSequence))
     {
         JLOG(ctx.j.debug()) << "uAccountSequenceNext=" << uAccountSequence
@@ -230,7 +228,6 @@ OfferCreate::preclaim(PreclaimContext const& ctx)
         return tecEXPIRED;
     }
 
-    // Make sure that we are authorized to hold what the taker will pay us.
     if (!saTakerPays.native())
     {
         auto result = checkAcceptAsset(ctx.view, ctx.flags, id, ctx.j, uPaysAsset);
@@ -238,8 +235,6 @@ OfferCreate::preclaim(PreclaimContext const& ctx)
             return result;
     }
 
-    // if domain is specified, make sure that domain exists and the offer create
-    // is part of the domain
     if (ctx.tx.isFieldPresent(sfDomainID))
     {
         if (!permissioned_dex::accountInDomain(ctx.view, id, ctx.tx[sfDomainID]))
@@ -262,7 +257,6 @@ OfferCreate::checkAcceptAsset(
     beast::Journal const j,
     Asset const& asset)
 {
-    // Only valid for custom currencies
     XRPL_ASSERT(!isXRP(asset), "xrpl::OfferCreate::checkAcceptAsset : input is not XRP");
 
     auto const issuerAccount = view.read(keylet::account(asset.getIssuer()));
@@ -275,9 +269,8 @@ OfferCreate::checkAcceptAsset(
         return ((flags & TapRetry) != 0u) ? TER{terNO_ACCOUNT} : TER{tecNO_ISSUER};
     }
 
-    // An account cannot create a trustline to itself, so no line can exist
-    // to be frozen. Additionally, an issuer can always accept its own
-    // issuance.
+    // An issuer always accepts its own issuance; no trust line can exist
+    // between an account and itself, so no freeze check is needed either.
     if (asset.getIssuer() == id)
         return tesSUCCESS;
 
@@ -293,10 +286,8 @@ OfferCreate::checkAcceptAsset(
                     return ((flags & TapRetry) != 0u) ? TER{terNO_LINE} : TER{tecNO_LINE};
                 }
 
-                // Entries have a canonical representation, determined by a
-                // lexicographical "greater than" comparison employing
-                // strict weak ordering. Determine which entry we need to
-                // access.
+                // Trust-line entries use canonical account ordering (id > issuer
+                // selects the "low" side fields).
                 bool const canonicalGt(id > issuer);
 
                 bool const isAuthorized(
@@ -318,8 +309,8 @@ OfferCreate::checkAcceptAsset(
                 return tesSUCCESS;
             }
 
-            // There's no difference which side enacted deep freeze, accepting
-            // tokens shouldn't be possible.
+            // Either side can enact deep freeze; once set, token movement is
+            // prohibited regardless of which side initiated it.
             bool const deepFrozen =
                 ((*trustLine)[sfFlags] & (lsfLowDeepFreeze | lsfHighDeepFreeze)) != 0u;
 
@@ -331,8 +322,8 @@ OfferCreate::checkAcceptAsset(
             return tesSUCCESS;
         },
         [&](MPTIssue const& issue) -> TER {
-            // WeakAuth - don't check if MPToken exists since it's created
-            // if needed.
+            // WeakAuth: an MPToken holder entry need not pre-exist — it will
+            // be created lazily if the account has the right authorization.
             return requireAuth(view, issue, id, AuthType::WeakAuth);
         });
 }
@@ -539,10 +530,8 @@ OfferCreate::applyHybrid(
     if (!sleOffer->isFieldPresent(sfDomainID))
         return tecINTERNAL;  // LCOV_EXCL_LINE
 
-    // set hybrid flag
     sleOffer->setFlag(lsfHybrid);
 
-    // if offer is hybrid, need to also place into open offer dir
     Book const book{saTakerPays.asset(), saTakerGets.asset(), std::nullopt};
 
     auto dir = keylet::quality(keylet::kBOOK(book), getRate(saTakerGets, saTakerPays));
@@ -722,8 +711,6 @@ OfferCreate::applyGuts(Sandbox& sb, Sandbox& sbCancel)
         if (takerAmount != placeOffer)
             crossed = true;
 
-        // The offer that we need to place after offer crossing should
-        // never be negative. If it is, something went very very wrong.
         if (placeOffer.in < kZERO || placeOffer.out < kZERO)
         {
             JLOG(j_.fatal()) << "Cross left offer negative!"
diff --git a/src/libxrpl/tx/transactors/did/DIDDelete.cpp b/src/libxrpl/tx/transactors/did/DIDDelete.cpp
index 9f9f54e6f6..fb6787aa66 100644
--- a/src/libxrpl/tx/transactors/did/DIDDelete.cpp
+++ b/src/libxrpl/tx/transactors/did/DIDDelete.cpp
@@ -1,3 +1,12 @@
+/** @file
+ *  Implementation of the `DIDDelete` transactor, which removes a
+ *  Decentralized Identifier (`ltDID`) ledger entry owned by the submitting
+ *  account. See `DIDDelete.h` for the full interface contract.
+ *
+ *  The `deleteSLE(ApplyView&, ...)` overload is intentionally reachable
+ *  from other transactors (notably `AccountDelete`) that need to clean up
+ *  an owned DID without constructing a full transactor context.
+ */
 #include <xrpl/tx/transactors/did/DIDDelete.h>
 
 #include <xrpl/basics/Log.h>
@@ -43,7 +52,6 @@ DIDDelete::deleteSLE(
     AccountID const owner,
     beast::Journal j)
 {
-    // Remove object from owner directory
     if (!view.dirRemove(keylet::ownerDir(owner), (*sle)[sfOwnerNode], sle->key(), true))
     {
         // LCOV_EXCL_START
@@ -59,7 +67,6 @@ DIDDelete::deleteSLE(
     adjustOwnerCount(view, sleOwner, -1, j);
     view.update(sleOwner);
 
-    // Remove object from ledger
     view.erase(sle);
     return tesSUCCESS;
 }
diff --git a/src/libxrpl/tx/transactors/did/DIDSet.cpp b/src/libxrpl/tx/transactors/did/DIDSet.cpp
index fbed821280..fe04eecd5f 100644
--- a/src/libxrpl/tx/transactors/did/DIDSet.cpp
+++ b/src/libxrpl/tx/transactors/did/DIDSet.cpp
@@ -1,3 +1,15 @@
+/** @file
+ *  Implementation of the `DIDSet` transactor, which creates or updates a
+ *  Decentralized Identifier (DID) ledger object (`ltDID`) owned by the
+ *  submitting account. The DID object stores up to three independently-optional
+ *  blob fields — `sfURI`, `sfDIDDocument`, and `sfData` — each capped at 256
+ *  bytes. The implementation conforms to the W3C DID v1.0 specification
+ *  (https://www.w3.org/TR/did-core/).
+ *
+ *  @note The symmetric removal path lives in `DIDDelete.cpp`. The file-local
+ *      `addSLE` helper mirrors `DIDDelete::deleteSLE` in reverse: reserve
+ *      check → insert → dirInsert → adjustOwnerCount(+1).
+ */
 #include <xrpl/tx/transactors/did/DIDSet.h>
 
 #include <xrpl/core/ServiceRegistry.h>
@@ -23,20 +35,25 @@
 
 namespace xrpl {
 
-/*
-    DID
-    ======
-
-    Decentralized Identifiers (DIDs) are a new type of identifier that enable
-    verifiable, self-sovereign digital identity and are designed to be
-    compatible with any distributed ledger or network. This implementation
-    conforms to the requirements specified in the DID v1.0 specification
-    currently recommended by the W3C Credentials Community Group
-    (https://www.w3.org/TR/did-core/).
-*/
-
-//------------------------------------------------------------------------------
-
+/** Validate DID transaction fields before any ledger state is read.
+ *
+ *  Enforces two emptiness invariants:
+ *  1. At least one of `sfURI`, `sfDIDDocument`, or `sfData` must be present in
+ *     the transaction. A transaction with none of them is meaningless.
+ *  2. All three fields may not be simultaneously present but empty. A client
+ *     sending `URI=""`, `DIDDocument=""`, `Data=""` is attempting to wipe an
+ *     existing DID via `DIDSet` rather than `DIDDelete`; the protocol blocks
+ *     this by treating "all-present, all-empty" as equivalent to no payload.
+ *
+ *  Also enforces per-field byte-length limits via the `isTooLong` lambda, which
+ *  uses the `~sField` (optional) accessor so absent fields are silently skipped.
+ *
+ *  @param ctx  Preflight context containing the raw transaction fields.
+ *  @return `temEMPTY_DID` if no non-empty field payload is provided;
+ *      `temMALFORMED` if any present field exceeds its maximum byte length
+ *      (`kMAX_DIDURI_LENGTH`, `kMAX_DID_DOCUMENT_LENGTH`, or
+ *      `kMAX_DID_DATA_LENGTH`); `tesSUCCESS` otherwise.
+ */
 NotTEC
 DIDSet::preflight(PreflightContext const& ctx)
 {
@@ -63,6 +80,31 @@ DIDSet::preflight(PreflightContext const& ctx)
     return tesSUCCESS;
 }
 
+/** Insert a new owner-tracked SLE into the ledger with all required bookkeeping.
+ *
+ *  Performs the standard three-step sequence for creating any owned ledger
+ *  object: reserve check, object insertion, and directory linkage.
+ *
+ *  1. **Reserve check**: verifies `sfBalance ≥ accountReserve(ownerCount + 1)`
+ *     before touching anything. The check uses the pre-insertion owner count so
+ *     that `tecINSUFFICIENT_RESERVE` is returned cleanly with no partial state.
+ *  2. **Insertion**: calls `ctx.view().insert(sle)` to add the object to the
+ *     ledger view.
+ *  3. **Directory linkage**: calls `dirInsert` to register the object's key in
+ *     the account's owner directory and stores the returned page index in
+ *     `sfOwnerNode` on the SLE. That cached index enables O(1) removal by
+ *     `DIDDelete::deleteSLE` via `dirRemove`. Increments `sfOwnerCount` on the
+ *     account root and writes the updated account SLE back.
+ *
+ *  @param ctx    Apply context providing the mutable ledger view and journal.
+ *  @param sle    The freshly constructed SLE to insert; must not yet be present
+ *      in the view.
+ *  @param owner  Account that will own the new object.
+ *  @return `tecINSUFFICIENT_RESERVE` if the account balance is below the new
+ *      reserve threshold; `tecDIR_FULL` if the owner directory has no room
+ *      (unreachable in practice — marked `LCOV_EXCL_LINE`); `tesSUCCESS` on
+ *      success.
+ */
 static TER
 addSLE(ApplyContext& ctx, std::shared_ptr<SLE> const& sle, AccountID const& owner)
 {
@@ -70,7 +112,6 @@ addSLE(ApplyContext& ctx, std::shared_ptr<SLE> const& sle, AccountID const& owne
     if (!sleAccount)
         return tefINTERNAL;  // LCOV_EXCL_LINE
 
-    // Check reserve availability for new object creation
     {
         auto const balance = STAmount((*sleAccount)[sfBalance]).xrp();
         auto const reserve = ctx.view().fees().accountReserve((*sleAccount)[sfOwnerCount] + 1);
@@ -79,10 +120,8 @@ addSLE(ApplyContext& ctx, std::shared_ptr<SLE> const& sle, AccountID const& owne
             return tecINSUFFICIENT_RESERVE;
     }
 
-    // Add ledger object to ledger
     ctx.view().insert(sle);
 
-    // Add ledger object to owner's page
     {
         auto page =
             ctx.view().dirInsert(keylet::ownerDir(owner), sle->key(), describeOwnerDir(owner));
@@ -96,13 +135,45 @@ addSLE(ApplyContext& ctx, std::shared_ptr<SLE> const& sle, AccountID const& owne
     return tesSUCCESS;
 }
 
+/** Apply the DID create-or-update to the ledger.
+ *
+ *  Dispatches to one of two paths based on whether a DID SLE already exists
+ *  for the submitting account (keyed by `keylet::did(account_)`).
+ *
+ *  **Update path** (SLE exists): applies a local `update` lambda to each of
+ *  `sfURI`, `sfDIDDocument`, and `sfData`. The lambda is intentionally
+ *  asymmetric: an absent transaction field is a no-op (leaves the stored value
+ *  unchanged), an empty field actively removes the attribute from the SLE via
+ *  `makeFieldAbsent` (surgical clear), and a non-empty field overwrites the
+ *  stored value. After all three updates, the code re-checks whether all fields
+ *  are now absent — an update that clears the last remaining attribute produces
+ *  an empty DID, which is rejected with `tecEMPTY_DID`. Note the `tec` code
+ *  rather than `tem`: the fee is still charged because preflight already passed.
+ *
+ *  **Create path** (no SLE exists): constructs a fresh `ltDID` SLE, sets
+ *  `sfAccount`, and copies non-empty transaction fields via a `set` lambda
+ *  (absent or empty fields are skipped). Under `fixEmptyDID`, if all three
+ *  fields end up absent in the new SLE the function returns `tecEMPTY_DID`
+ *  before inserting. Without that amendment, the create path allowed an SLE
+ *  where every payload field was absent (because `preflight` only caught the
+ *  "all-present and all-empty" case, not the "all-present but some non-empty
+ *  strings that happen to be zero-length" edge). Finally, `addSLE` is called
+ *  to validate the owner reserve, insert the SLE, link it into the owner
+ *  directory, and increment `sfOwnerCount`.
+ *
+ *  @return `tesSUCCESS` on success; `tecEMPTY_DID` if the resulting DID would
+ *      carry no attributes; `tecINSUFFICIENT_RESERVE` if the account cannot
+ *      cover the incremental owner reserve (create path only); `tecDIR_FULL`
+ *      if the owner directory cannot accommodate the new entry (create path
+ *      only, unreachable in practice).
+ */
 TER
 DIDSet::doApply()
 {
-    // Edit ledger object if it already exists
     Keylet const didKeylet = keylet::did(account_);
     if (auto const sleDID = ctx_.view().peek(didKeylet))
     {
+        // Update path: absent field = no-op, empty = remove, non-empty = replace.
         auto update = [&](auto const& sField) {
             if (auto const field = ctx_.tx[~sField])
             {
@@ -129,7 +200,7 @@ DIDSet::doApply()
         return tesSUCCESS;
     }
 
-    // Create new ledger object otherwise
+    // Create path: build a fresh SLE and populate non-empty fields only.
     auto const sleDID = std::make_shared<SLE>(didKeylet);
     (*sleDID)[sfAccount] = account_;
 
@@ -141,6 +212,10 @@ DIDSet::doApply()
     set(sfURI);
     set(sfDIDDocument);
     set(sfData);
+
+    // fixEmptyDID closes the preflight gap: reject creation of an SLE where
+    // every payload field ended up absent (e.g. all values were empty strings
+    // that passed the "not all three present-and-empty" preflight check).
     if (ctx_.view().rules().enabled(fixEmptyDID) && !sleDID->isFieldPresent(sfURI) &&
         !sleDID->isFieldPresent(sfDIDDocument) && !sleDID->isFieldPresent(sfData))
     {
@@ -150,19 +225,28 @@ DIDSet::doApply()
     return addSLE(ctx_, sleDID, account_);
 }
 
+/** Invariant visitor stub — no DID-specific per-entry invariants are enforced.
+ *
+ *  The global invariant framework (`ValidAMM`, `XRPNotCreated`, etc.) already
+ *  covers the properties that matter for DID objects. This override exists only
+ *  to satisfy the `Transactor` interface contract.
+ */
 void
 DIDSet::visitInvariantEntry(
     bool,
     std::shared_ptr<SLE const> const&,
     std::shared_ptr<SLE const> const&)
 {
-    // No transaction-specific invariants yet (future work).
 }
 
+/** Invariant finalizer stub — no DID-specific post-transaction invariants are
+ *  enforced.
+ *
+ *  @return `true` always.
+ */
 bool
 DIDSet::finalizeInvariants(STTx const&, TER, XRPAmount, ReadView const&, beast::Journal const&)
 {
-    // No transaction-specific invariants yet (future work).
     return true;
 }
 
diff --git a/src/libxrpl/tx/transactors/escrow/Escrow.cpp b/src/libxrpl/tx/transactors/escrow/Escrow.cpp
index e69de29bb2..60a2c67175 100644
--- a/src/libxrpl/tx/transactors/escrow/Escrow.cpp
+++ b/src/libxrpl/tx/transactors/escrow/Escrow.cpp
@@ -0,0 +1,23 @@
+/** @file
+ *  Build-system anchor for the escrow transactor module.
+ *
+ *  This file is intentionally empty. All escrow logic is distributed across
+ *  three sibling translation units:
+ *
+ *  - `EscrowCreate.cpp`  — locks XRP or tokens into a new escrow SLE, with
+ *    optional time-based release and/or a crypto-condition fulfillment
+ *    requirement. Contains the canonical module-level comment for the entire
+ *    escrow subsystem.
+ *  - `EscrowFinish.cpp`  — releases escrowed funds to the destination after
+ *    time and/or fulfillment conditions are met; validates and caches
+ *    crypto-conditions via the hash router.
+ *  - `EscrowCancel.cpp`  — returns escrowed funds to the originator after the
+ *    cancel-after deadline has passed; no fee is applied on return.
+ *
+ *  The file exists as a structural artifact of the build system: either
+ *  CMake required a translation unit when escrow logic was first introduced,
+ *  or a refactor that split a monolithic `Escrow.cpp` into three specialized
+ *  transactors left this source behind.
+ *
+ *  @see EscrowCreate.h, EscrowFinish.h, EscrowCancel.h
+ */
diff --git a/src/libxrpl/tx/transactors/escrow/EscrowCancel.cpp b/src/libxrpl/tx/transactors/escrow/EscrowCancel.cpp
index 05d6a29454..200a882483 100644
--- a/src/libxrpl/tx/transactors/escrow/EscrowCancel.cpp
+++ b/src/libxrpl/tx/transactors/escrow/EscrowCancel.cpp
@@ -1,3 +1,12 @@
+/** @file
+ *  Implementation of the `EscrowCancel` transactor.
+ *
+ *  Handles the expiry-refund path of the escrow lifecycle: once the ledger's
+ *  parent close time has advanced past `sfCancelAfter`, any party may submit
+ *  an `EscrowCancel` to return the locked funds to the original escrow creator.
+ *  Supports XRP escrows (original design) and token escrows (IOU / MPT) gated
+ *  behind `featureTokenEscrow`.
+ */
 #include <xrpl/tx/transactors/escrow/EscrowCancel.h>
 
 #include <xrpl/basics/Log.h>
@@ -34,6 +43,18 @@ EscrowCancel::preflight(PreflightContext const& ctx)
     return tesSUCCESS;
 }
 
+/** Read-only authorization check for non-XRP escrow cancellations.
+ *
+ *  Primary template — no body; only the `Issue` and `MPTIssue` full
+ *  specializations are defined. Called via `std::visit` on the `Asset` variant
+ *  held by the escrow's `sfAmount`.
+ *
+ *  @tparam T Asset type; must be `Issue` (IOU) or `MPTIssue` (MPT).
+ *  @param ctx     Read-only preclaim context providing ledger access.
+ *  @param account Escrow creator (`sfAccount` on the escrow SLE).
+ *  @param amount  Escrowed token amount; its asset identifies the issuer.
+ *  @return `tesSUCCESS` if cancellation may proceed; a `tec` error otherwise.
+ */
 template <ValidIssueType T>
 static TER
 escrowCancelPreclaimHelper(
@@ -41,6 +62,18 @@ escrowCancelPreclaimHelper(
     AccountID const& account,
     STAmount const& amount);
 
+/** IOU specialization: verifies the escrow owner is still authorized by the issuer.
+ *
+ *  Authorization must remain valid at cancel time, not just at creation time.
+ *  The `issuer == account` case is impossible by construction but is guarded
+ *  defensively and marked unreachable for coverage purposes.
+ *
+ *  @param ctx     Read-only preclaim context.
+ *  @param account Escrow creator (`sfAccount` on the escrow SLE).
+ *  @param amount  Escrowed IOU amount.
+ *  @return `tesSUCCESS` if authorized; `tecINTERNAL` if issuer equals account
+ *          (unreachable); a `requireAuth` error if authorization was revoked.
+ */
 template <>
 TER
 escrowCancelPreclaimHelper<Issue>(
@@ -49,17 +82,31 @@ escrowCancelPreclaimHelper<Issue>(
     STAmount const& amount)
 {
     AccountID const& issuer = amount.getIssuer();
-    // If the issuer is the same as the account, return tecINTERNAL
     if (issuer == account)
         return tecINTERNAL;  // LCOV_EXCL_LINE
 
-    // If the issuer has requireAuth set, check if the account is authorized
     if (auto const ter = requireAuth(ctx.view, amount.get<Issue>(), account); !isTesSuccess(ter))
         return ter;
 
     return tesSUCCESS;
 }
 
+/** MPT specialization: verifies the MPT issuance still exists and the escrow
+ *  owner remains authorized to hold it.
+ *
+ *  Unlike the IOU path, an MPT issuance can be deleted while an escrow
+ *  referencing it is still open; this check surfaces that condition early.
+ *  Authorization uses `AuthType::WeakAuth` because MPTs operate under a less
+ *  strict per-transaction approval model than IOU trust lines.
+ *
+ *  @param ctx     Read-only preclaim context.
+ *  @param account Escrow creator (`sfAccount` on the escrow SLE).
+ *  @param amount  Escrowed MPT amount.
+ *  @return `tesSUCCESS` if authorized; `tecINTERNAL` if issuer equals account
+ *          (unreachable); `tecOBJECT_NOT_FOUND` if the MPT issuance was
+ *          deleted after the escrow was created; a `requireAuth` error if
+ *          weak authorization is denied.
+ */
 template <>
 TER
 escrowCancelPreclaimHelper<MPTIssue>(
@@ -68,18 +115,14 @@ escrowCancelPreclaimHelper<MPTIssue>(
     STAmount const& amount)
 {
     AccountID const issuer = amount.getIssuer();
-    // If the issuer is the same as the account, return tecINTERNAL
     if (issuer == account)
         return tecINTERNAL;  // LCOV_EXCL_LINE
 
-    // If the mpt does not exist, return tecOBJECT_NOT_FOUND
     auto const issuanceKey = keylet::mptIssuance(amount.get<MPTIssue>().getMptID());
     auto const sleIssuance = ctx.view.read(issuanceKey);
     if (!sleIssuance)
         return tecOBJECT_NOT_FOUND;
 
-    // If the issuer has requireAuth set, check if the account is
-    // authorized
     auto const& mptIssue = amount.get<MPTIssue>();
     if (auto const ter = requireAuth(ctx.view, mptIssue, account, AuthType::WeakAuth);
         !isTesSuccess(ter))
@@ -130,17 +173,15 @@ EscrowCancel::doApply()
 
     auto const now = ctx_.view().header().parentCloseTime;
 
-    // No cancel time specified: can't execute at all.
+    // Escrows with no sfCancelAfter can never be cancelled.
     if (!(*slep)[~sfCancelAfter])
         return tecNO_PERMISSION;
 
-    // Too soon: can't execute before the cancel time.
     if (!after(now, (*slep)[sfCancelAfter]))
         return tecNO_PERMISSION;
 
     AccountID const account = (*slep)[sfAccount];
 
-    // Remove escrow from owner directory
     {
         auto const page = (*slep)[sfOwnerNode];
         if (!ctx_.view().dirRemove(keylet::ownerDir(account), page, k.key, true))
@@ -152,7 +193,6 @@ EscrowCancel::doApply()
         }
     }
 
-    // Remove escrow from recipient's owner directory, if present.
     if (auto const optPage = (*slep)[~sfDestinationNode]; optPage)
     {
         if (!ctx_.view().dirRemove(keylet::ownerDir((*slep)[sfDestination]), *optPage, k.key, true))
@@ -167,7 +207,6 @@ EscrowCancel::doApply()
     auto const sle = ctx_.view().peek(keylet::account(account));
     STAmount const amount = slep->getFieldAmount(sfAmount);
 
-    // Transfer amount back to the owner
     if (isXRP(amount))
     {
         (*sle)[sfBalance] = (*sle)[sfBalance] + amount;
@@ -197,7 +236,7 @@ EscrowCancel::doApply()
             !isTesSuccess(ret))
             return ret;  // LCOV_EXCL_LINE
 
-        // Remove escrow from issuers owner directory, if present.
+        // Non-XRP escrows also carry an sfIssuerNode directory entry.
         if (auto const optPage = (*slep)[~sfIssuerNode]; optPage)
         {
             if (!ctx_.view().dirRemove(keylet::ownerDir(issuer), *optPage, k.key, true))
@@ -213,7 +252,6 @@ EscrowCancel::doApply()
     adjustOwnerCount(ctx_.view(), sle, -1, ctx_.journal);
     ctx_.view().update(sle);
 
-    // Remove escrow from ledger
     ctx_.view().erase(slep);
 
     return tesSUCCESS;
diff --git a/src/libxrpl/tx/transactors/escrow/EscrowCreate.cpp b/src/libxrpl/tx/transactors/escrow/EscrowCreate.cpp
index dd9c1b84b4..466a279a33 100644
--- a/src/libxrpl/tx/transactors/escrow/EscrowCreate.cpp
+++ b/src/libxrpl/tx/transactors/escrow/EscrowCreate.cpp
@@ -1,3 +1,22 @@
+/** @file
+ *  Implements the EscrowCreate transactor, which locks XRP or token (IOU/MPT)
+ *  funds in a conditional escrow ledger object.  The escrow can later be
+ *  released by `EscrowFinish` or reclaimed by `EscrowCancel`.
+ *
+ *  Locked funds are completely unavailable to either party until one of those
+ *  outcomes occurs.  Time-based unlocks and crypto-conditions are both
+ *  supported unlock mechanisms.  Escrows may also carry an expiry after which
+ *  only `EscrowCancel` is permitted.
+ *
+ *  Token escrow (`Issue`/`MPTIssue`) is gated on `featureTokenEscrow`.
+ *
+ *  @see https://xrpl.org/escrowcreate.html
+ *  @see https://xrpl.org/escrowfinish.html
+ *  @see https://xrpl.org/escrowcancel.html
+ *  @see EscrowFinish
+ *  @see EscrowCancel
+ */
+
 #include <xrpl/tx/transactors/escrow/EscrowCreate.h>
 
 #include <xrpl/basics/Log.h>
@@ -38,40 +57,6 @@
 
 namespace xrpl {
 
-/*
-    Escrow
-    ======
-
-    Escrow is a feature of the XRP Ledger that allows you to send conditional
-    XRP payments. These conditional payments, called escrows, set aside XRP and
-    deliver it later when certain conditions are met. Conditions to successfully
-    finish an escrow include time-based unlocks and crypto-conditions. Escrows
-    can also be set to expire if not finished in time.
-
-    The XRP set aside in an escrow is locked up. No one can use or destroy the
-    XRP until the escrow has been successfully finished or canceled. Before the
-    expiration time, only the intended receiver can get the XRP. After the
-    expiration time, the XRP can only be returned to the sender.
-
-    For more details on escrow, including examples, diagrams and more please
-    visit https://xrpl.org/escrow.html
-
-    For details on specific transactions, including fields and validation rules
-    please see:
-
-    `EscrowCreate`
-    --------------
-        See: https://xrpl.org/escrowcreate.html
-
-    `EscrowFinish`
-    --------------
-        See: https://xrpl.org/escrowfinish.html
-
-    `EscrowCancel`
-    --------------
-        See: https://xrpl.org/escrowcancel.html
-*/
-
 //------------------------------------------------------------------------------
 
 TxConsequences
@@ -81,10 +66,30 @@ EscrowCreate::makeTxConsequences(PreflightContext const& ctx)
     return TxConsequences{ctx.tx, isXRP(amount) ? amount.xrp() : beast::kZERO};
 }
 
+/** Stateless preflight checks specific to each non-XRP asset type.
+ *
+ *  Specialised for `Issue` (IOU) and `MPTIssue` (MPT).  Called from
+ *  `EscrowCreate::preflight` after `featureTokenEscrow` has been confirmed
+ *  active.  Validates amount polarity, magnitude, and asset-type constraints
+ *  without touching the ledger.
+ *
+ *  @tparam T  `Issue` or `MPTIssue`.
+ *  @param ctx stateless preflight context.
+ *  @return    `tesSUCCESS`, or a `tem*` error code.
+ */
 template <ValidIssueType T>
 static NotTEC
 escrowCreatePreflightHelper(PreflightContext const& ctx);
 
+/** IOU-specific preflight helper.
+ *
+ *  Rejects native (XRP) amounts, non-positive values, and the bad-currency
+ *  sentinel.  The native guard prevents XRP amounts from reaching this path
+ *  via an `Issue`-typed specialisation.
+ *
+ *  @param ctx stateless preflight context.
+ *  @return    `temBAD_AMOUNT` for invalid amounts; `tesSUCCESS` otherwise.
+ */
 template <>
 NotTEC
 escrowCreatePreflightHelper<Issue>(PreflightContext const& ctx)
@@ -99,6 +104,17 @@ escrowCreatePreflightHelper<Issue>(PreflightContext const& ctx)
     return tesSUCCESS;
 }
 
+/** MPT-specific preflight helper.
+ *
+ *  In addition to the checks common to all non-XRP assets (non-native, positive
+ *  value), also requires `featureMPTokensV1` to be active and enforces the
+ *  `kMAX_MP_TOKEN_AMOUNT` ceiling on the raw MPT balance.
+ *
+ *  @param ctx stateless preflight context.
+ *  @return    `temDISABLED` if `featureMPTokensV1` is inactive;
+ *             `temBAD_AMOUNT` for out-of-range or non-positive amounts;
+ *             `tesSUCCESS` otherwise.
+ */
 template <>
 NotTEC
 escrowCreatePreflightHelper<MPTIssue>(PreflightContext const& ctx)
@@ -113,6 +129,7 @@ escrowCreatePreflightHelper<MPTIssue>(PreflightContext const& ctx)
     return tesSUCCESS;
 }
 
+/** @copydoc EscrowCreate::preflight */
 NotTEC
 EscrowCreate::preflight(PreflightContext const& ctx)
 {
@@ -134,20 +151,18 @@ EscrowCreate::preflight(PreflightContext const& ctx)
             return temBAD_AMOUNT;
     }
 
-    // We must specify at least one timeout value
+    // At least one of sfCancelAfter or sfFinishAfter must be present;
+    // an escrow with neither has no defined lifecycle.
     if (!ctx.tx[~sfCancelAfter] && !ctx.tx[~sfFinishAfter])
         return temBAD_EXPIRATION;
 
-    // If both finish and cancel times are specified then the cancel time must
-    // be strictly after the finish time.
     if (ctx.tx[~sfCancelAfter] && ctx.tx[~sfFinishAfter] &&
         ctx.tx[sfCancelAfter] <= ctx.tx[sfFinishAfter])
         return temBAD_EXPIRATION;
 
-    // In the absence of a FinishAfter, the escrow can be finished
-    // immediately, which can be confusing. When creating an escrow,
-    // we want to ensure that either a FinishAfter time is explicitly
-    // specified or a completion condition is attached.
+    // Without sfFinishAfter the escrow could be completed immediately on
+    // creation, which is almost certainly a mistake. Require sfCondition
+    // as an explicit unlock mechanism when no finish time is given.
     if (!ctx.tx[~sfFinishAfter] && !ctx.tx[~sfCondition])
         return temMALFORMED;
 
@@ -168,6 +183,20 @@ EscrowCreate::preflight(PreflightContext const& ctx)
     return tesSUCCESS;
 }
 
+/** Read-only ledger checks specific to each non-XRP asset type during preclaim.
+ *
+ *  Specialised for `Issue` (IOU) and `MPTIssue` (MPT).  Called from
+ *  `EscrowCreate::preclaim` after confirming `featureTokenEscrow` is active.
+ *  Validates issuer permissions, sender/destination authorisation, freeze
+ *  status, and spendable balance against the live ledger state.
+ *
+ *  @tparam T       `Issue` or `MPTIssue`.
+ *  @param ctx      read-only preclaim context.
+ *  @param account  sender's `AccountID`.
+ *  @param dest     destination's `AccountID`.
+ *  @param amount   escrowed amount.
+ *  @return         `tesSUCCESS`, or a `tec*` error code.
+ */
 template <ValidIssueType T>
 static TER
 escrowCreatePreclaimHelper(
@@ -176,6 +205,35 @@ escrowCreatePreclaimHelper(
     AccountID const& dest,
     STAmount const& amount);
 
+/** IOU-specific preclaim helper.
+ *
+ *  Enforces the following in order:
+ *  - Issuer and sender must differ (no self-escrow of issued credit).
+ *  - Issuer must have `lsfAllowTrustLineLocking` set — token escrow is
+ *    opt-in for issuers.
+ *  - A trust line between sender and issuer must exist.
+ *  - Trust line balance polarity must match the XRP Ledger address-ordering
+ *    convention (positive balance → issuer > account; negative → issuer <
+ *    account).
+ *  - Both sender and destination must satisfy `requireAuth` when the issuer
+ *    mandates authorisation.
+ *  - Neither the sender's nor the destination's trust line may be frozen.
+ *  - Sender's spendable balance (checked with `fhIGNORE_FREEZE` to obtain the
+ *    raw balance) must be positive and cover `amount`.
+ *  - `canAdd` precision guard: the amount must be addable back to the balance
+ *    without precision loss when the escrow later finishes.
+ *
+ *  @param ctx     read-only preclaim context.
+ *  @param account sender's `AccountID`.
+ *  @param dest    destination's `AccountID`.
+ *  @param amount  escrowed IOU amount.
+ *  @return        `tecNO_PERMISSION` if issuer == account or flags/auth fail;
+ *                 `tecNO_ISSUER` if the issuer account does not exist;
+ *                 `tecNO_LINE` if no trust line exists; `tecFROZEN` if either
+ *                 party is frozen; `tecINSUFFICIENT_FUNDS` if balance is
+ *                 insufficient; `tecPRECISION_LOSS` on arithmetic edge cases;
+ *                 `tesSUCCESS` otherwise.
+ */
 template <>
 TER
 escrowCreatePreclaimHelper<Issue>(
@@ -186,67 +244,85 @@ escrowCreatePreclaimHelper<Issue>(
 {
     Issue const& issue = amount.get<Issue>();
     AccountID const& issuer = amount.getIssuer();
-    // If the issuer is the same as the account, return tecNO_PERMISSION
     if (issuer == account)
         return tecNO_PERMISSION;
 
-    // If the lsfAllowTrustLineLocking is not enabled, return tecNO_PERMISSION
     auto const sleIssuer = ctx.view.read(keylet::account(issuer));
     if (!sleIssuer)
         return tecNO_ISSUER;
     if (!sleIssuer->isFlag(lsfAllowTrustLineLocking))
         return tecNO_PERMISSION;
 
-    // If the account does not have a trustline to the issuer, return tecNO_LINE
     auto const sleRippleState = ctx.view.read(keylet::line(account, issuer, issue.currency));
     if (!sleRippleState)
         return tecNO_LINE;
 
     STAmount const balance = (*sleRippleState)[sfBalance];
 
-    // If balance is positive, issuer must have higher address than account
+    // Trust line balance polarity encodes address ordering: positive balance
+    // means issuer has the higher address; negative means issuer has the lower.
     if (balance > beast::kZERO && issuer < account)
         return tecNO_PERMISSION;  // LCOV_EXCL_LINE
 
-    // If balance is negative, issuer must have lower address than account
     if (balance < beast::kZERO && issuer > account)
         return tecNO_PERMISSION;  // LCOV_EXCL_LINE
 
-    // If the issuer has requireAuth set, check if the account is authorized
     if (auto const ter = requireAuth(ctx.view, issue, account); !isTesSuccess(ter))
         return ter;
 
-    // If the issuer has requireAuth set, check if the destination is authorized
     if (auto const ter = requireAuth(ctx.view, issue, dest); !isTesSuccess(ter))
         return ter;
 
-    // If the issuer has frozen the account, return tecFROZEN
     if (isFrozen(ctx.view, account, issue))
         return tecFROZEN;
 
-    // If the issuer has frozen the destination, return tecFROZEN
     if (isFrozen(ctx.view, dest, issue))
         return tecFROZEN;
 
     STAmount const spendableAmount = accountHolds(
         ctx.view, account, issue.currency, issuer, FreezeHandling::IgnoreFreeze, ctx.j);
 
-    // If the balance is less than or equal to 0, return tecINSUFFICIENT_FUNDS
     if (spendableAmount <= beast::kZERO)
         return tecINSUFFICIENT_FUNDS;
 
-    // If the spendable amount is less than the amount, return
-    // tecINSUFFICIENT_FUNDS
     if (spendableAmount < amount)
         return tecINSUFFICIENT_FUNDS;
 
-    // If the amount is not addable to the balance, return tecPRECISION_LOSS
+    // Guard against precision loss that would occur when the locked amount is
+    // returned to the sender's trust line balance on finish.
     if (!canAdd(spendableAmount, amount))
         return tecPRECISION_LOSS;
 
     return tesSUCCESS;
 }
 
+/** MPT-specific preclaim helper.
+ *
+ *  Mirrors the IOU helper in structure but applies MPT-specific rules:
+ *  - Issuer and sender must differ.
+ *  - The `MPTokenIssuance` object must exist and carry `lsfMPTCanEscrow`.
+ *  - The sender must hold an `MPToken` object for this issuance.
+ *  - Both sender and destination must pass `requireAuth` (WeakAuth) when the
+ *    issuance mandates authorisation.
+ *  - Lock/freeze status is checked with `isFrozen`; violations return
+ *    `tecLOCKED` (not `tecFROZEN`) — the deliberate distinction reflects the
+ *    different freeze semantics for MPTs vs. IOU trust lines.
+ *  - Transfer eligibility is confirmed via `canTransfer`.
+ *  - Sender's spendable MPT balance must be positive and cover `amount`.
+ *
+ *  @note Unlike the IOU path there is no `canAdd` precision check here because
+ *      MPT arithmetic uses integer semantics without IOU rounding concerns.
+ *
+ *  @param ctx     read-only preclaim context.
+ *  @param account sender's `AccountID`.
+ *  @param dest    destination's `AccountID`.
+ *  @param amount  escrowed MPT amount.
+ *  @return        `tecNO_PERMISSION` if issuer == account or flags/auth fail;
+ *                 `tecOBJECT_NOT_FOUND` if the issuance or sender's `MPToken`
+ *                 is absent; `tecLOCKED` if either party is frozen/locked;
+ *                 `tecINSUFFICIENT_FUNDS` if balance is insufficient;
+ *                 `tesSUCCESS` otherwise.
+ */
 template <>
 TER
 escrowCreatePreclaimHelper<MPTIssue>(
@@ -256,51 +332,40 @@ escrowCreatePreclaimHelper<MPTIssue>(
     STAmount const& amount)
 {
     AccountID const issuer = amount.getIssuer();
-    // If the issuer is the same as the account, return tecNO_PERMISSION
     if (issuer == account)
         return tecNO_PERMISSION;
 
-    // If the mpt does not exist, return tecOBJECT_NOT_FOUND
     auto const issuanceKey = keylet::mptIssuance(amount.get<MPTIssue>().getMptID());
     auto const sleIssuance = ctx.view.read(issuanceKey);
     if (!sleIssuance)
         return tecOBJECT_NOT_FOUND;
 
-    // If the lsfMPTCanEscrow is not enabled, return tecNO_PERMISSION
     if (!sleIssuance->isFlag(lsfMPTCanEscrow))
         return tecNO_PERMISSION;
 
-    // If the issuer is not the same as the issuer of the mpt, return
-    // tecNO_PERMISSION
     if (sleIssuance->getAccountID(sfIssuer) != issuer)
         return tecNO_PERMISSION;  // LCOV_EXCL_LINE
 
-    // If the account does not have the mpt, return tecOBJECT_NOT_FOUND
     if (!ctx.view.exists(keylet::mptoken(issuanceKey.key, account)))
         return tecOBJECT_NOT_FOUND;
 
-    // If the issuer has requireAuth set, check if the account is
-    // authorized
     auto const& mptIssue = amount.get<MPTIssue>();
     if (auto const ter = requireAuth(ctx.view, mptIssue, account, AuthType::WeakAuth);
         !isTesSuccess(ter))
         return ter;
 
-    // If the issuer has requireAuth set, check if the destination is
-    // authorized
     if (auto const ter = requireAuth(ctx.view, mptIssue, dest, AuthType::WeakAuth);
         !isTesSuccess(ter))
         return ter;
 
-    // If the issuer has frozen the account, return tecLOCKED
+    // MPT freeze violations use tecLOCKED rather than tecFROZEN to distinguish
+    // MPT lock semantics from IOU global/per-line freeze semantics.
     if (isFrozen(ctx.view, account, mptIssue))
         return tecLOCKED;
 
-    // If the issuer has frozen the destination, return tecLOCKED
     if (isFrozen(ctx.view, dest, mptIssue))
         return tecLOCKED;
 
-    // If the mpt cannot be transferred, return tecNO_AUTH
     if (auto const ter = canTransfer(ctx.view, mptIssue, account, dest); !isTesSuccess(ter))
         return ter;
 
@@ -312,18 +377,16 @@ escrowCreatePreclaimHelper<MPTIssue>(
         AuthHandling::IgnoreAuth,
         ctx.j);
 
-    // If the balance is less than or equal to 0, return tecINSUFFICIENT_FUNDS
     if (spendableAmount <= beast::kZERO)
         return tecINSUFFICIENT_FUNDS;
 
-    // If the spendable amount is less than the amount, return
-    // tecINSUFFICIENT_FUNDS
     if (spendableAmount < amount)
         return tecINSUFFICIENT_FUNDS;
 
     return tesSUCCESS;
 }
 
+/** @copydoc EscrowCreate::preclaim */
 TER
 EscrowCreate::preclaim(PreclaimContext const& ctx)
 {
@@ -358,6 +421,21 @@ EscrowCreate::preclaim(PreclaimContext const& ctx)
     return tesSUCCESS;
 }
 
+/** Debit the sender's token balance when creating a non-XRP escrow.
+ *
+ *  Specialised for `Issue` (IOU) and `MPTIssue` (MPT).  Performs the
+ *  asset-type-specific ledger mutation that removes funds from the sender's
+ *  spendable balance and places them under escrow control.
+ *
+ *  @tparam T        `Issue` or `MPTIssue`.
+ *  @param view      mutable apply view.
+ *  @param issuer    token issuer's `AccountID`.
+ *  @param sender    sender's `AccountID`.
+ *  @param amount    escrowed amount.
+ *  @param journal   logging journal.
+ *  @return          `tesSUCCESS`, `tecINTERNAL` (defensive; should never fire),
+ *                   or any error propagated from the underlying transfer helper.
+ */
 template <ValidIssueType T>
 static TER
 escrowLockApplyHelper(
@@ -367,6 +445,22 @@ escrowLockApplyHelper(
     STAmount const& amount,
     beast::Journal journal);
 
+/** IOU locking: transfer tokens fee-free from sender back to issuer.
+ *
+ *  Conceptually retires the tokens from circulation; they will be re-issued
+ *  to the destination by `EscrowFinish`.  `directSendNoFee` is used so no
+ *  transfer fee is charged at lock time (the fee, if any, is charged on
+ *  finish using the rate snapshotted in `sfTransferRate`).
+ *
+ *  @param view    mutable apply view.
+ *  @param issuer  token issuer's `AccountID`.
+ *  @param sender  sender's `AccountID`.
+ *  @param amount  escrowed IOU amount.
+ *  @param journal logging journal.
+ *  @return        `tecINTERNAL` if issuer == sender (defensive, should never
+ *                 fire in production); otherwise the result of
+ *                 `directSendNoFee`.
+ */
 template <>
 TER
 escrowLockApplyHelper<Issue>(
@@ -376,7 +470,8 @@ escrowLockApplyHelper<Issue>(
     STAmount const& amount,
     beast::Journal journal)
 {
-    // Defensive: Issuer cannot create an escrow
+    // Defensive: preclaim already rejected issuer == sender; tecINTERNAL
+    // here indicates an internal inconsistency rather than a user error.
     if (issuer == sender)
         return tecINTERNAL;  // LCOV_EXCL_LINE
 
@@ -387,6 +482,22 @@ escrowLockApplyHelper<Issue>(
     return tesSUCCESS;
 }
 
+/** MPT locking: atomically move tokens into the sender's locked-amount field.
+ *
+ *  `lockEscrowMPT` decrements `sfMPTAmount` and increments `sfLockedAmount`
+ *  on the sender's `MPToken` SLE, and increments `sfLockedAmount` on the
+ *  `MPTokenIssuance` SLE.  Ownership of the tokens does not change — no
+ *  issuer directory entry is needed because the issuance object tracks the
+ *  total locked supply directly.
+ *
+ *  @param view    mutable apply view.
+ *  @param issuer  token issuer's `AccountID`.
+ *  @param sender  sender's `AccountID`.
+ *  @param amount  escrowed MPT amount.
+ *  @param journal logging journal.
+ *  @return        `tecINTERNAL` if issuer == sender (defensive); otherwise
+ *                 the result of `lockEscrowMPT`.
+ */
 template <>
 TER
 escrowLockApplyHelper<MPTIssue>(
@@ -396,7 +507,7 @@ escrowLockApplyHelper<MPTIssue>(
     STAmount const& amount,
     beast::Journal journal)
 {
-    // Defensive: Issuer cannot create an escrow
+    // Defensive: see escrowLockApplyHelper<Issue> comment above.
     if (issuer == sender)
         return tecINTERNAL;  // LCOV_EXCL_LINE
 
@@ -406,11 +517,16 @@ escrowLockApplyHelper<MPTIssue>(
     return tesSUCCESS;
 }
 
+/** @copydoc EscrowCreate::doApply */
 TER
 EscrowCreate::doApply()
 {
     auto const closeTime = ctx_.view().header().parentCloseTime;
 
+    // Re-check time bounds against the current ledger's parentCloseTime.
+    // A transaction that was valid at preflight may arrive in a ledger where
+    // the expiry has already passed; creating an already-expired escrow must
+    // be rejected here rather than persisted.
     if (ctx_.tx[~sfCancelAfter] && after(closeTime, ctx_.tx[sfCancelAfter]))
         return tecNO_PERMISSION;
 
@@ -421,23 +537,22 @@ EscrowCreate::doApply()
     if (!sle)
         return tefINTERNAL;  // LCOV_EXCL_LINE
 
-    // Check reserve and funds availability
     STAmount const amount{ctx_.tx[sfAmount]};
 
+    // Reserve check: the new escrow SLE adds one to the owner count.
     auto const reserve = ctx_.view().fees().accountReserve((*sle)[sfOwnerCount] + 1);
 
     auto const balance = sle->getFieldAmount(sfBalance).xrp();
     if (balance < reserve)
         return tecINSUFFICIENT_RESERVE;
 
-    // Check reserve and funds availability
+    // For XRP escrows the sender's balance must also cover the locked principal.
     if (isXRP(amount))
     {
         if (balance < reserve + STAmount(amount).xrp())
             return tecUNFUNDED;
     }
 
-    // Check destination account
     {
         auto const sled = ctx_.view().read(keylet::account(ctx_.tx[sfDestination]));
         if (!sled)
@@ -446,8 +561,8 @@ EscrowCreate::doApply()
             return tecDST_TAG_NEEDED;
     }
 
-    // Create escrow in ledger.  Note that we use the value from the
-    // sequence or ticket.  For more explanation see comments in SeqProxy.h.
+    // The escrow keylet is derived from the sender's account and the sequence
+    // (or ticket) value; see SeqProxy.h for the rationale.
     Keylet const escrowKeylet = keylet::escrow(account_, ctx_.tx.getSeqValue());
     auto const slep = std::make_shared<SLE>(escrowKeylet);
     (*slep)[sfAmount] = amount;
@@ -459,11 +574,17 @@ EscrowCreate::doApply()
     (*slep)[~sfFinishAfter] = ctx_.tx[~sfFinishAfter];
     (*slep)[~sfDestinationTag] = ctx_.tx[~sfDestinationTag];
 
+    // fixIncludeKeyletFields: store sfSequence in the SLE so that
+    // EscrowFinish/EscrowCancel can reconstruct the keylet without external
+    // input, enabling more robust cross-ledger object navigation.
     if (ctx_.view().rules().enabled(fixIncludeKeyletFields))
     {
         (*slep)[sfSequence] = ctx_.tx.getSeqValue();
     }
 
+    // Snapshot the issuer's transfer rate at creation time. EscrowFinish reads
+    // this stored rate to compute the correct delivery amount; the issuer cannot
+    // retroactively change the rate that applies to the locked funds.
     if (ctx_.view().rules().enabled(featureTokenEscrow) && !isXRP(amount))
     {
         auto const xferRate = transferRate(ctx_.view(), amount);
@@ -473,7 +594,7 @@ EscrowCreate::doApply()
 
     ctx_.view().insert(slep);
 
-    // Add escrow to sender's owner directory
+    // Register the escrow in the sender's owner directory unconditionally.
     {
         auto page = ctx_.view().dirInsert(
             keylet::ownerDir(account_), escrowKeylet, describeOwnerDir(account_));
@@ -482,7 +603,7 @@ EscrowCreate::doApply()
         (*slep)[sfOwnerNode] = *page;
     }
 
-    // If it's not a self-send, add escrow to recipient's owner directory.
+    // Register in the destination's owner directory for non-self-escrows.
     AccountID const dest = ctx_.tx[sfDestination];
     if (dest != account_)
     {
@@ -506,7 +627,8 @@ EscrowCreate::doApply()
         (*slep)[sfIssuerNode] = *page;
     }
 
-    // Deduct owner's balance
+    // Debit the sender. XRP is deducted directly from sfBalance; token amounts
+    // are handled by asset-type-specific helpers via std::visit.
     if (isXRP(amount))
     {
         (*sle)[sfBalance] = (*sle)[sfBalance] - amount;
@@ -524,7 +646,6 @@ EscrowCreate::doApply()
         }
     }
 
-    // increment owner count
     adjustOwnerCount(ctx_.view(), sle, 1, ctx_.journal);
     ctx_.view().update(sle);
     return tesSUCCESS;
diff --git a/src/libxrpl/tx/transactors/escrow/EscrowFinish.cpp b/src/libxrpl/tx/transactors/escrow/EscrowFinish.cpp
index fb6c77c61a..48db49d931 100644
--- a/src/libxrpl/tx/transactors/escrow/EscrowFinish.cpp
+++ b/src/libxrpl/tx/transactors/escrow/EscrowFinish.cpp
@@ -36,14 +36,40 @@
 
 namespace xrpl {
 
-// During an EscrowFinish, the transaction must specify both
-// a condition and a fulfillment. We track whether that
-// fulfillment matches and validates the condition.
+/** HashRouter flag indicating the crypto-condition fulfillment is invalid.
+ *
+ *  Set in `preflightSigValidated` (and re-set in `doApply` if the cache has
+ *  expired) when `checkCondition` returns false.  When this bit is present on
+ *  a transaction's flags, `doApply` immediately returns
+ *  `tecCRYPTOCONDITION_ERROR` without repeating the cryptographic work.
+ */
 constexpr HashRouterFlags kSF_CF_INVALID = HashRouterFlags::PRIVATE5;
+
+/** HashRouter flag indicating the crypto-condition fulfillment is valid.
+ *
+ *  Set in `preflightSigValidated` (and re-set in `doApply` if the cache has
+ *  expired) when `checkCondition` returns true.  `doApply` reads this bit to
+ *  confirm that the fulfillment was already verified before proceeding with
+ *  the remaining condition checks against the escrow SLE.
+ */
 constexpr HashRouterFlags kSF_CF_VALID = HashRouterFlags::PRIVATE6;
 
 //------------------------------------------------------------------------------
 
+/** Verify that a crypto-condition fulfillment satisfies a condition.
+ *
+ *  Deserializes both the condition (`c`) and the fulfillment (`f`) using the
+ *  `cryptoconditions` library and calls `validate`.  Returns `false` if
+ *  either field fails to deserialize.  This is the single call site for all
+ *  crypto-condition verification in the escrow finish pipeline; its result is
+ *  cached in the `HashRouter` under `kSF_CF_VALID`/`kSF_CF_INVALID` to avoid
+ *  repeating the work across multiple passes of the same transaction.
+ *
+ *  @param f  raw bytes of the PREIMAGE-SHA-256 fulfillment.
+ *  @param c  raw bytes of the condition originally stored in the escrow SLE.
+ *  @return   `true` if the fulfillment validates the condition; `false` if
+ *            either field fails to deserialize or validation fails.
+ */
 static bool
 checkCondition(Slice f, Slice c)
 {
@@ -137,6 +163,23 @@ escrowFinishPreclaimHelper(
     AccountID const& dest,
     STAmount const& amount);
 
+/** IOU specialization: read-only eligibility check for an escrow destination.
+ *
+ *  Verifies that `dest` is permitted to receive the IOU held in escrow:
+ *  - If the issuer equals the destination the check trivially passes (the
+ *    issuer cannot be unauthorized or frozen against itself).
+ *  - Otherwise `requireAuth` is called; if the issuer has `lsfRequireAuth`
+ *    set and `dest` is not authorized on the trust line, the check fails.
+ *  - Then `isDeepFrozen` is consulted; deep-freeze on the trust line blocks
+ *    the finish regardless of authorization.
+ *
+ *  @param ctx     read-only preclaim context.
+ *  @param dest    the escrow destination account.
+ *  @param amount  the escrowed IOU amount (carries the issuer and currency).
+ *  @return        `tesSUCCESS` if the destination may receive the asset;
+ *                 `tecNO_AUTH` if `requireAuth` is set and the trust line is
+ *                 unauthorized; `tecFROZEN` if the trust line is deep-frozen.
+ */
 template <>
 TER
 escrowFinishPreclaimHelper<Issue>(
@@ -145,21 +188,37 @@ escrowFinishPreclaimHelper<Issue>(
     STAmount const& amount)
 {
     AccountID const& issuer = amount.getIssuer();
-    // If the issuer is the same as the account, return tesSUCCESS
     if (issuer == dest)
         return tesSUCCESS;
 
-    // If the issuer has requireAuth set, check if the destination is authorized
     if (auto const ter = requireAuth(ctx.view, amount.get<Issue>(), dest); !isTesSuccess(ter))
         return ter;
 
-    // If the issuer has deep frozen the destination, return tecFROZEN
     if (isDeepFrozen(ctx.view, dest, amount.get<Issue>().currency, amount.getIssuer()))
         return tecFROZEN;
 
     return tesSUCCESS;
 }
 
+/** MPT specialization: read-only eligibility check for an escrow destination.
+ *
+ *  Verifies that `dest` is permitted to receive the MPToken held in escrow:
+ *  - If the issuer equals the destination the check trivially passes.
+ *  - The MPT issuance object must exist on the ledger; a missing issuance
+ *    means the asset was destroyed after the escrow was created.
+ *  - `requireAuth` is called with `AuthType::WeakAuth`, which requires an
+ *    `MPToken` holder entry to exist but does not require the issuer to have
+ *    explicitly authorized it (less strict than IOU `requireAuth`).
+ *  - `isFrozen` checks for an MPT-level lock on the destination's holding.
+ *
+ *  @param ctx     read-only preclaim context.
+ *  @param dest    the escrow destination account.
+ *  @param amount  the escrowed MPT amount (carries the MPT issuance ID).
+ *  @return        `tesSUCCESS` if the destination may receive the asset;
+ *                 `tecOBJECT_NOT_FOUND` if the MPT issuance no longer exists;
+ *                 a `requireAuth` error code if `WeakAuth` fails;
+ *                 `tecLOCKED` if the destination's MPToken holding is frozen.
+ */
 template <>
 TER
 escrowFinishPreclaimHelper<MPTIssue>(
@@ -168,24 +227,19 @@ escrowFinishPreclaimHelper<MPTIssue>(
     STAmount const& amount)
 {
     AccountID const& issuer = amount.getIssuer();
-    // If the issuer is the same as the dest, return tesSUCCESS
     if (issuer == dest)
         return tesSUCCESS;
 
-    // If the mpt does not exist, return tecOBJECT_NOT_FOUND
     auto const issuanceKey = keylet::mptIssuance(amount.get<MPTIssue>().getMptID());
     auto const sleIssuance = ctx.view.read(issuanceKey);
     if (!sleIssuance)
         return tecOBJECT_NOT_FOUND;
 
-    // If the issuer has requireAuth set, check if the destination is
-    // authorized
     auto const& mptIssue = amount.get<MPTIssue>();
     if (auto const ter = requireAuth(ctx.view, mptIssue, dest, AuthType::WeakAuth);
         !isTesSuccess(ter))
         return ter;
 
-    // If the issuer has frozen the destination, return tecLOCKED
     if (isFrozen(ctx.view, dest, mptIssue))
         return tecLOCKED;
 
@@ -239,8 +293,6 @@ EscrowFinish::doApply()
         return tecNO_TARGET;
     }
 
-    // If a cancel time is present, a finish operation should only succeed prior
-    // to that time.
     auto const now = ctx_.view().header().parentCloseTime;
 
     // Too soon: can't execute before the finish time
@@ -251,7 +303,6 @@ EscrowFinish::doApply()
     if ((*slep)[~sfCancelAfter] && after(now, (*slep)[sfCancelAfter]))
         return tecNO_PERMISSION;
 
-    // Check cryptocondition fulfillment
     {
         auto const id = ctx_.tx.getTransactionID();
         auto flags = ctx_.registry.get().getHashRouter().getFlags(id);
@@ -282,12 +333,9 @@ EscrowFinish::doApply()
             // LCOV_EXCL_STOP
         }
 
-        // If the check failed, then simply return an error
-        // and don't look at anything else.
         if (any(flags & kSF_CF_INVALID))
             return tecCRYPTOCONDITION_ERROR;
 
-        // Check against condition in the ledger entry:
         auto const cond = (*slep)[~sfCondition];
 
         // If a condition wasn't specified during creation,
@@ -316,7 +364,6 @@ EscrowFinish::doApply()
 
     AccountID const account = (*slep)[sfAccount];
 
-    // Remove escrow from owner directory
     {
         auto const page = (*slep)[sfOwnerNode];
         if (!ctx_.view().dirRemove(keylet::ownerDir(account), page, k.key, true))
@@ -341,7 +388,6 @@ EscrowFinish::doApply()
     }
 
     STAmount const amount = slep->getFieldAmount(sfAmount);
-    // Transfer amount to destination
     if (isXRP(amount))
     {
         (*sled)[sfBalance] = (*sled)[sfBalance] + amount;
@@ -389,12 +435,10 @@ EscrowFinish::doApply()
 
     ctx_.view().update(sled);
 
-    // Adjust source owner count
     auto const sle = ctx_.view().peek(keylet::account(account));
     adjustOwnerCount(ctx_.view(), sle, -1, ctx_.journal);
     ctx_.view().update(sle);
 
-    // Remove escrow from ledger
     ctx_.view().erase(slep);
     return tesSUCCESS;
 }
diff --git a/src/libxrpl/tx/transactors/lending/LoanBrokerCoverClawback.cpp b/src/libxrpl/tx/transactors/lending/LoanBrokerCoverClawback.cpp
index c59a02d4c2..fecb250bc7 100644
--- a/src/libxrpl/tx/transactors/lending/LoanBrokerCoverClawback.cpp
+++ b/src/libxrpl/tx/transactors/lending/LoanBrokerCoverClawback.cpp
@@ -1,3 +1,17 @@
+/** @file
+ *  Implements `LoanBrokerCoverClawback`: the transaction that lets the
+ *  original asset issuer forcibly reclaim cover funds from a loan broker's
+ *  pseudo-account, subject to a minimum cover-to-debt ratio enforced via
+ *  asymmetric rounding.
+ *
+ *  The broker may be identified either explicitly via `sfLoanBrokerID` or
+ *  implicitly by encoding the pseudo-account as the IOU issuer in `sfAmount`.
+ *  XRP assets and MPTs cannot use the implicit path.
+ *
+ *  @see LoanBrokerCoverDeposit   structural inverse — adds cover, same
+ *      `WaiveTransferFee::Yes` convention
+ *  @see LoanBrokerCoverWithdraw  voluntary cover removal by broker owner
+ */
 #include <xrpl/tx/transactors/lending/LoanBrokerCoverClawback.h>
 
 #include <xrpl/basics/Expected.h>
@@ -83,6 +97,28 @@ LoanBrokerCoverClawback::preflight(PreflightContext const& ctx)
     return tesSUCCESS;
 }
 
+/** Resolve the target broker's ledger ID from the transaction.
+ *
+ *  Supports two identification modes:
+ *  - **Explicit**: `sfLoanBrokerID` is present in the transaction.
+ *  - **Implicit**: `sfAmount` is an IOU whose `issuer` field is the broker's
+ *    pseudo-account; the function reads that account's SLE and extracts its
+ *    `sfLoanBrokerID` field.
+ *
+ *  The implicit path exists because callers may naturally express the target
+ *  using the trust-line issuer convention (pseudo-account as issuer) without
+ *  knowing the broker's object ID up front.  `preflight` ensures the implicit
+ *  path is only reached when `sfAmount` holds an IOU.
+ *
+ *  @param view  Read-only ledger view used to look up the pseudo-account SLE.
+ *  @param tx    The transaction being applied.
+ *  @return The broker's `uint256` object ID on success, or:
+ *      - `tecINTERNAL` if the transaction state is inconsistent with what
+ *        `preflight` should have rejected (unreachable in practice).
+ *      - `tecNO_ENTRY` if the IOU issuer account does not exist.
+ *      - `tecOBJECT_NOT_FOUND` if the IOU issuer account exists but is not
+ *        a loan-broker pseudo-account.
+ */
 Expected<uint256, TER>
 determineBrokerID(ReadView const& view, STTx const& tx)
 {
@@ -126,6 +162,29 @@ determineBrokerID(ReadView const& view, STTx const& tx)
     // Or tecWRONG_ASSET?
 }
 
+/** Normalize the clawback asset to use the submitting account as issuer.
+ *
+ *  IOU trust lines are bidirectional: the same line can be expressed with
+ *  either endpoint as the `issuer` field.  This function canonicalises the
+ *  asset so that comparisons against the vault's `sfAsset` (which always
+ *  uses the actual issuer account) work correctly regardless of which
+ *  perspective the submitter used when constructing `sfAmount`.
+ *
+ *  MPT assets are returned as-is because MPTs have no trust-line issuer
+ *  ambiguity.
+ *
+ *  @param view                  Read-only ledger view (currently unused;
+ *      reserved for future validation).
+ *  @param account               The submitting account (the asset issuer).
+ *  @param brokerPseudoAccountID The broker pseudo-account ID resolved by
+ *      `determineBrokerID`.
+ *  @param amount                The `sfAmount` from the transaction, which may
+ *      encode the asset from either the issuer's or pseudo-account's
+ *      perspective.
+ *  @return The canonical `Asset` with `account` as issuer on success, or
+ *      `tecWRONG_ASSET` if the IOU issuer matches neither `account` nor
+ *      `brokerPseudoAccountID`.
+ */
 Expected<Asset, TER>
 determineAsset(
     ReadView const& view,
@@ -156,6 +215,29 @@ determineAsset(
     return Unexpected(tecWRONG_ASSET);
 }
 
+/** Compute the maximum amount the issuer may claw back while respecting the
+ *  broker's minimum cover floor.
+ *
+ *  The floor is `sfDebtTotal × sfCoverRateMinimum` (in tenth-basis-points),
+ *  computed with ceiling rounding so the ledger never permits cover to drop
+ *  below the contractual minimum.  The remaining surplus
+ *  (`sfCoverAvailable − minRequiredCover`) is then rounded down.  Asymmetric
+ *  rounding is deliberate: ceiling on the required minimum, floor on the
+ *  available surplus.
+ *
+ *  When `amount` is absent or zero the function returns the full surplus
+ *  (`maxClawAmount`).  When `amount` is provided but exceeds the surplus it
+ *  is silently capped — the submitter always receives at most what the floor
+ *  allows, without needing to know the exact number in advance.
+ *
+ *  @param sleBroker   The broker SLE supplying `sfDebtTotal`,
+ *      `sfCoverRateMinimum`, and `sfCoverAvailable`.
+ *  @param vaultAsset  Canonical vault asset used to type the returned
+ *      `STAmount` (avoids pseudo-account issuer ambiguity).
+ *  @param amount      Requested claw amount, or absent/zero for "take all".
+ *  @return The effective claw amount capped to `maxClawAmount`, or
+ *      `tecINSUFFICIENT_FUNDS` if cover is already at or below the floor.
+ */
 Expected<STAmount, TER>
 determineClawAmount(
     SLE const& sleBroker,
@@ -163,11 +245,9 @@ determineClawAmount(
     std::optional<STAmount> const& amount)
 {
     auto const maxClawAmount = [&]() {
-        // Always round the minimum required up
         NumberRoundModeGuard const mg1(Number::RoundingMode::Upward);
         auto const minRequiredCover =
             tenthBipsOfValue(sleBroker[sfDebtTotal], TenthBips32(sleBroker[sfCoverRateMinimum]));
-        // The subtraction probably won't round, but round down if it does.
         NumberRoundModeGuard const mg2(Number::RoundingMode::Downward);
         return sleBroker[sfCoverAvailable] - minRequiredCover;
     }();
@@ -185,22 +265,44 @@ determineClawAmount(
     return STAmount{vaultAsset, magnitude};
 }
 
+/** Asset-type-specific permission check for the vault asset issuer.
+ *
+ *  Dispatched from `preclaim` via `std::visit` on the vault asset variant.
+ *  Each specialisation enforces the clawback-permission model appropriate to
+ *  its asset type: `Issue` checks IOU account flags; `MPTIssue` checks the
+ *  `MPTIssuance` SLE flags.
+ *
+ *  @tparam T         Asset type: `Issue` or `MPTIssue`.
+ *  @param ctx        Preclaim context with read-only ledger view.
+ *  @param sleIssuer  The issuer's `AccountRoot` SLE.
+ *  @param clawAmount The effective claw amount (used by the MPT path to derive
+ *      the issuance keylet).
+ *  @return `tesSUCCESS` if the issuer holds the required permission flag, or
+ *      `tecNO_PERMISSION` / `tecOBJECT_NOT_FOUND` / `tecINTERNAL` otherwise.
+ */
 template <ValidIssueType T>
 static TER
 preclaimHelper(PreclaimContext const& ctx, SLE const& sleIssuer, STAmount const& clawAmount);
 
+/** IOU specialisation: enforces `lsfAllowTrustLineClawback` and absence of
+ *  `lsfNoFreeze` on the issuer account, mirroring the standard XRPL IOU
+ *  clawback permission model.
+ */
 template <>
 TER
 preclaimHelper<Issue>(PreclaimContext const& ctx, SLE const& sleIssuer, STAmount const& clawAmount)
 {
-    // If AllowTrustLineClawback is not set or NoFreeze is set, return no
-    // permission
     if (!(sleIssuer.isFlag(lsfAllowTrustLineClawback)) || (sleIssuer.isFlag(lsfNoFreeze)))
         return tecNO_PERMISSION;
 
     return tesSUCCESS;
 }
 
+/** MPT specialisation: looks up the `MPTIssuance` SLE and checks
+ *  `lsfMPTCanClawback`.  Also asserts (redundantly) that the issuance's
+ *  `sfIssuer` matches the submitting account — a consistency guard that
+ *  should be unreachable given upstream checks.
+ */
 template <>
 TER
 preclaimHelper<MPTIssue>(
@@ -261,8 +363,6 @@ LoanBrokerCoverClawback::preclaim(PreclaimContext const& ctx)
         return tecNO_PERMISSION;
     }
 
-    // Only the issuer of the vault asset can claw it back from the broker's
-    // cover funds.
     if (vaultAsset.getIssuer() != account)
     {
         JLOG(ctx.j.warn()) << "Account is not the issuer of the vault asset.";
@@ -291,9 +391,6 @@ LoanBrokerCoverClawback::preclaim(PreclaimContext const& ctx)
     }
     STAmount const& clawAmount = *findClawAmount;
 
-    // Explicitly check the balance of the trust line / MPT to make sure the
-    // balance is actually there. It should always match `sfCoverAvailable`, so
-    // if there isn't, this is an internal error.
     if (accountHolds(
             ctx.view,
             brokerPseudoAccountID,
@@ -303,7 +400,6 @@ LoanBrokerCoverClawback::preclaim(PreclaimContext const& ctx)
             ctx.j) < clawAmount)
         return tecINTERNAL;  // tecINSUFFICIENT_FUNDS; LCOV_EXCL_LINE
 
-    // Check if the vault asset issuer has the correct flags
     auto const sleIssuer = ctx.view.read(keylet::account(vaultAsset.getIssuer()));
     if (!sleIssuer)
     {
@@ -349,13 +445,11 @@ LoanBrokerCoverClawback::doApply()
     if (clawAmount.native())
         return tecINTERNAL;  // LCOV_EXCL_LINE
 
-    // Decrease the LoanBroker's CoverAvailable by Amount
     sleBroker->at(sfCoverAvailable) -= clawAmount;
     view().update(sleBroker);
 
     associateAsset(*sleBroker, vaultAsset);
 
-    // Transfer assets from pseudo-account to depositor.
     return accountSend(view(), brokerPseudoID, account, clawAmount, j_, WaiveTransferFee::Yes);
 }
 
diff --git a/src/libxrpl/tx/transactors/lending/LoanBrokerCoverDeposit.cpp b/src/libxrpl/tx/transactors/lending/LoanBrokerCoverDeposit.cpp
index a35878f5c6..c36d0c5d98 100644
--- a/src/libxrpl/tx/transactors/lending/LoanBrokerCoverDeposit.cpp
+++ b/src/libxrpl/tx/transactors/lending/LoanBrokerCoverDeposit.cpp
@@ -1,3 +1,17 @@
+/** @file
+ *  Implementation of `LoanBrokerCoverDeposit`, the transactor that lets a
+ *  `LoanBroker` owner inject collateral into the broker's pseudo-account.
+ *
+ *  Cover is the loss-absorption buffer the lending protocol (XLS-66) requires
+ *  each broker to maintain relative to its outstanding loan debt
+ *  (`sfDebtTotal`). Depositing cover increases `sfCoverAvailable` and the
+ *  pseudo-account's on-ledger asset balance atomically.
+ *
+ *  The three symmetrical cover-management transactors are:
+ *  - `LoanBrokerCoverDeposit`  — increases cover (this file)
+ *  - `LoanBrokerCoverWithdraw` — decreases cover (enforces minimum ratio)
+ *  - `LoanBrokerCoverClawback` — issuer reclaims frozen cover assets
+ */
 #include <xrpl/tx/transactors/lending/LoanBrokerCoverDeposit.h>
 
 #include <xrpl/basics/Log.h>
@@ -74,16 +88,12 @@ LoanBrokerCoverDeposit::preclaim(PreclaimContext const& ctx)
         return tecWRONG_ASSET;
 
     auto const pseudoAccountID = sleBroker->at(sfAccount);
-    // Cannot transfer a non-transferable Asset
     if (auto const ret = canTransfer(ctx.view, vaultAsset, account, pseudoAccountID))
         return ret;
-    // Cannot transfer a frozen Asset
     if (auto const ret = checkFrozen(ctx.view, account, vaultAsset))
         return ret;
-    // Pseudo-account cannot receive if asset is deep frozen
     if (auto const ret = checkDeepFrozen(ctx.view, pseudoAccountID, vaultAsset))
         return ret;
-    // Cannot transfer unauthorized asset
     if (auto const ret = requireAuth(ctx.view, vaultAsset, account, AuthType::StrongAuth))
         return ret;
 
@@ -120,11 +130,9 @@ LoanBrokerCoverDeposit::doApply()
 
     auto const brokerPseudoID = broker->at(sfAccount);
 
-    // Transfer assets from depositor to pseudo-account.
     if (auto ter = accountSend(view(), account_, brokerPseudoID, amount, j_, WaiveTransferFee::Yes))
         return ter;
 
-    // Increase the LoanBroker's CoverAvailable by Amount
     broker->at(sfCoverAvailable) += amount;
     view().update(broker);
 
diff --git a/src/libxrpl/tx/transactors/lending/LoanBrokerCoverWithdraw.cpp b/src/libxrpl/tx/transactors/lending/LoanBrokerCoverWithdraw.cpp
index 127d23a270..288c30d3ac 100644
--- a/src/libxrpl/tx/transactors/lending/LoanBrokerCoverWithdraw.cpp
+++ b/src/libxrpl/tx/transactors/lending/LoanBrokerCoverWithdraw.cpp
@@ -1,3 +1,17 @@
+/** @file
+ *  Implementation of the `LoanBrokerCoverWithdraw` transactor (XLS-66).
+ *
+ *  This transactor is the only sanctioned path by which a broker owner can
+ *  reclaim idle cover capital from the broker's pseudo-account. It enforces
+ *  the minimum cover ratio — `roundUp(tenthBipsOfValue(sfDebtTotal,
+ *  sfCoverRateMinimum))` — before permitting any withdrawal, ensuring
+ *  outstanding loans remain adequately backed. Asset movement is delegated
+ *  to `doWithdraw` in `View.h`, which handles pseudo-account settlement
+ *  logic common across vault-adjacent withdrawal operations.
+ *
+ *  @see LoanBrokerCoverDeposit   symmetric deposit path (increments cover)
+ *  @see LoanBrokerCoverClawback  forced cover reclaim by the vault asset issuer
+ */
 #include <xrpl/tx/transactors/lending/LoanBrokerCoverWithdraw.h>
 
 #include <xrpl/basics/Log.h>
@@ -23,12 +37,25 @@
 
 namespace xrpl {
 
+/** Delegates amendment gating to `checkLendingProtocolDependencies`.
+ *
+ *  Returns `false` (causing `invokePreflight` to return `temDISABLED`) if
+ *  the lending protocol amendment or any of its dependencies is not yet
+ *  active on the ledger.
+ */
 bool
 LoanBrokerCoverWithdraw::checkExtraFeatures(PreflightContext const& ctx)
 {
     return checkLendingProtocolDependencies(ctx.rules, ctx.tx);
 }
 
+/** Stateless field validation — no ledger access.
+ *
+ *  Rejects structural nonsense before any state is consulted: a zero broker
+ *  ID cannot map to a valid SLE, a non-positive amount is never a meaningful
+ *  withdrawal, and a present-but-zero `sfDestination` would silently route
+ *  funds to a black-hole address.
+ */
 NotTEC
 LoanBrokerCoverWithdraw::preflight(PreflightContext const& ctx)
 {
@@ -53,6 +80,30 @@ LoanBrokerCoverWithdraw::preflight(PreflightContext const& ctx)
     return tesSUCCESS;
 }
 
+/** Read-only ledger checks for a cover withdrawal.
+ *
+ *  Layers of enforcement (in order):
+ *  - Destination must not be a pseudo-account.
+ *  - `LoanBroker` SLE must exist and be owned by the submitter.
+ *  - The broker's vault must exist (missing vault → `tefBAD_LEDGER`; excluded
+ *    from coverage because the broker cannot outlive its vault in a well-formed
+ *    ledger).
+ *  - `sfAmount` asset must match the vault's `sfAsset`.
+ *  - Asset transferability: `canTransfer` from the broker pseudo-account to
+ *    the destination.
+ *  - Third-party destination: upgrades to `StrongAuth` and calls `canWithdraw`
+ *    (checks account existence, deposit-auth, tag requirements, trust limits).
+ *    Withdrawing to self requires only `WeakAuth`, so the owner need not
+ *    pre-establish a trust relationship with their own account.
+ *  - Freeze checks against the pseudo-account (source) and destination, unless
+ *    the destination is the asset issuer.
+ *  - Minimum cover: `roundUp(tenthBipsOfValue(sfDebtTotal,
+ *    sfCoverRateMinimum))` must remain after the withdrawal. Upward rounding
+ *    is enforced via `NumberRoundModeGuard` to prevent rounding dust from
+ *    under-collateralizing outstanding loans.
+ *  - `accountHolds` confirms the pseudo-account's actual balance covers the
+ *    requested amount, guarding against any divergence from `sfCoverAvailable`.
+ */
 TER
 LoanBrokerCoverWithdraw::preclaim(PreclaimContext const& ctx)
 {
@@ -93,46 +144,41 @@ LoanBrokerCoverWithdraw::preclaim(PreclaimContext const& ctx)
     if (amount.asset() != vaultAsset)
         return tecWRONG_ASSET;
 
-    // The broker's pseudo-account is the source of funds.
+    // The broker's pseudo-account is the source of funds, not the submitter.
     auto const pseudoAccountID = sleBroker->at(sfAccount);
-    // Cannot transfer a non-transferable Asset
     if (auto const ret = canTransfer(ctx.view, vaultAsset, pseudoAccountID, dstAcct))
         return ret;
 
-    // Withdrawal to a 3rd party destination account is essentially a transfer.
-    // Enforce all the usual asset transfer checks.
+    // Withdrawal to a 3rd party destination is functionally a transfer:
+    // enforce full consent checks and require StrongAuth (existing trust line
+    // or MPToken).
     AuthType authType = AuthType::WeakAuth;
     if (account != dstAcct)
     {
         if (auto const ret = canWithdraw(ctx.view, tx))
             return ret;
 
-        // The destination account must have consented to receive the asset by
-        // creating a RippleState or MPToken
         authType = AuthType::StrongAuth;
     }
 
-    // Destination MPToken must exist (if asset is an MPT)
     if (auto const ter = requireAuth(ctx.view, vaultAsset, dstAcct, authType))
         return ter;
 
-    // Check for freezes, unless sending directly to the issuer
+    // Freeze checks are skipped when sending directly to the asset issuer.
     if (dstAcct != vaultAsset.getIssuer())
     {
-        // Cannot send a frozen Asset
         if (auto const ret = checkFrozen(ctx.view, pseudoAccountID, vaultAsset))
             return ret;
-        // Destination account cannot receive if asset is deep frozen
         if (auto const ret = checkDeepFrozen(ctx.view, dstAcct, vaultAsset))
             return ret;
     }
 
     auto const coverAvail = sleBroker->at(sfCoverAvailable);
-    // Cover Rate is in 1/10 bips units
     auto const currentDebtTotal = sleBroker->at(sfDebtTotal);
     auto const minimumCover = [&]() {
-        // Always round the minimum required up.
-        // Applies to `tenthBipsOfValue` as well as `roundToAsset`.
+        // Always round the minimum required up — applies to both
+        // `tenthBipsOfValue` and `roundToAsset` — so fractional dust cannot
+        // be used to erode the collateral buffer below the required ratio.
         NumberRoundModeGuard const mg(Number::RoundingMode::Upward);
         return roundToAsset(
             vaultAsset,
@@ -156,6 +202,19 @@ LoanBrokerCoverWithdraw::preclaim(PreclaimContext const& ctx)
     return tesSUCCESS;
 }
 
+/** Executes the cover withdrawal against the mutable ledger view.
+ *
+ *  Decrements `sfCoverAvailable` on the `LoanBroker` SLE, then calls
+ *  `associateAsset` to re-round all `STNumber` fields to asset precision
+ *  (required after any numeric mutation on an SLE that holds asset-denominated
+ *  values). The actual token movement from the broker pseudo-account to the
+ *  destination is performed by `doWithdraw`.
+ *
+ *  @note `associateAsset` must be the last call before `doWithdraw`; failing
+ *      to call it produces silent precision corruption in the serialized SLE.
+ *  @note The broker and vault peek/read failures return `tecINTERNAL` and are
+ *      excluded from coverage — preclaim guarantees both objects exist.
+ */
 TER
 LoanBrokerCoverWithdraw::doApply()
 {
@@ -177,7 +236,6 @@ LoanBrokerCoverWithdraw::doApply()
 
     auto const brokerPseudoID = *broker->at(sfAccount);
 
-    // Decrease the LoanBroker's CoverAvailable by Amount
     broker->at(sfCoverAvailable) -= amount;
     view().update(broker);
 
@@ -186,6 +244,7 @@ LoanBrokerCoverWithdraw::doApply()
     return doWithdraw(view(), tx, account_, dstAcct, brokerPseudoID, preFeeBalance_, amount, j_);
 }
 
+/** No-op: no per-entry invariants are defined for this transaction type yet. */
 void
 LoanBrokerCoverWithdraw::visitInvariantEntry(
     bool,
@@ -195,6 +254,10 @@ LoanBrokerCoverWithdraw::visitInvariantEntry(
     // No transaction-specific invariants yet (future work).
 }
 
+/** No-op: no post-conditions are defined for this transaction type yet.
+ *
+ *  @return `true` unconditionally.
+ */
 bool
 LoanBrokerCoverWithdraw::finalizeInvariants(
     STTx const&,
diff --git a/src/libxrpl/tx/transactors/lending/LoanBrokerDelete.cpp b/src/libxrpl/tx/transactors/lending/LoanBrokerDelete.cpp
index 2c5767f9cc..54841599d1 100644
--- a/src/libxrpl/tx/transactors/lending/LoanBrokerDelete.cpp
+++ b/src/libxrpl/tx/transactors/lending/LoanBrokerDelete.cpp
@@ -1,3 +1,14 @@
+/** @file
+ *  Implements `LoanBrokerDelete`, the teardown transactor for a `LoanBroker`
+ *  and its associated pseudo-account.
+ *
+ *  Deletion is a strict multi-phase process: preclaim verifies that all loans
+ *  are closed and any residual debt rounds to zero, then doApply removes both
+ *  directory entries, refunds cover capital, clears the holding, and erases
+ *  both the pseudo-account SLE and the broker SLE — decrementing the human
+ *  owner's `sfOwnerCount` by exactly two to balance the two-unit increment
+ *  performed by `LoanBrokerSet`.
+ */
 #include <xrpl/tx/transactors/lending/LoanBrokerDelete.h>
 
 #include <xrpl/basics/Log.h>
@@ -95,8 +106,6 @@ LoanBrokerDelete::preclaim(PreclaimContext const& ctx)
     }
 
     auto const coverAvailable = STAmount{asset, sleBroker->at(sfCoverAvailable)};
-    // If there are assets in the cover, broker will receive them on deletion.
-    // So we need to check if the broker owner is deep frozen for that asset.
     if (coverAvailable > beast::kZERO)
     {
         if (auto const ret = checkDeepFrozen(ctx.view, brokerOwner, asset))
@@ -116,7 +125,6 @@ LoanBrokerDelete::doApply()
 
     auto const brokerID = tx[sfLoanBrokerID];
 
-    // Delete the loan broker
     auto broker = view().peek(keylet::loanbroker(brokerID));
     if (!broker)
         return tefBAD_LEDGER;  // LCOV_EXCL_LINE
diff --git a/src/libxrpl/tx/transactors/lending/LoanBrokerSet.cpp b/src/libxrpl/tx/transactors/lending/LoanBrokerSet.cpp
index 97ef73515a..91363fe246 100644
--- a/src/libxrpl/tx/transactors/lending/LoanBrokerSet.cpp
+++ b/src/libxrpl/tx/transactors/lending/LoanBrokerSet.cpp
@@ -1,3 +1,9 @@
+/** @file
+ *  Implements `LoanBrokerSet`, the upsert transactor for `LoanBroker` ledger
+ *  objects (XLS-66). A single transaction type handles both creation (when
+ *  `sfLoanBrokerID` is absent) and configuration updates (when present).
+ *  See `LoanBrokerSet.h` for the full interface and behavioral contract.
+ */
 #include <xrpl/tx/transactors/lending/LoanBrokerSet.h>
 
 #include <xrpl/basics/Log.h>
@@ -51,8 +57,6 @@ LoanBrokerSet::preflight(PreflightContext const& ctx)
 
     if (tx.isFieldPresent(sfLoanBrokerID))
     {
-        // Fixed fields can not be specified if we're modifying an existing
-        // LoanBroker Object
         if (tx.isFieldPresent(sfManagementFeeRate) || tx.isFieldPresent(sfCoverRateMinimum) ||
             tx.isFieldPresent(sfCoverRateLiquidation))
             return temINVALID;
@@ -70,7 +74,6 @@ LoanBrokerSet::preflight(PreflightContext const& ctx)
     {
         auto const minimumZero = tx[~sfCoverRateMinimum].value_or(0) == 0;
         auto const liquidationZero = tx[~sfCoverRateLiquidation].value_or(0) == 0;
-        // Both must be zero or non-zero.
         if (minimumZero != liquidationZero)
         {
             return temINVALID;
@@ -112,8 +115,6 @@ LoanBrokerSet::preclaim(PreclaimContext const& ctx)
 
     if (auto const brokerID = tx[~sfLoanBrokerID])
     {
-        // Updating an existing Broker
-
         auto const sleBroker = ctx.view.read(keylet::loanbroker(*brokerID));
         if (!sleBroker)
         {
@@ -133,7 +134,6 @@ LoanBrokerSet::preclaim(PreclaimContext const& ctx)
 
         if (auto const debtMax = tx[~sfDebtMaximum])
         {
-            // Can't reduce the debt maximum below the current total debt
             auto const currentDebtTotal = sleBroker->at(sfDebtTotal);
             if (*debtMax != 0 && *debtMax < currentDebtTotal)
             {
@@ -177,7 +177,6 @@ LoanBrokerSet::doApply()
 
     if (auto const brokerID = tx[~sfLoanBrokerID])
     {
-        // Modify an existing LoanBroker
         auto broker = view.peek(keylet::loanbroker(*brokerID));
         if (!broker)
         {
@@ -205,7 +204,6 @@ LoanBrokerSet::doApply()
     }
     else
     {
-        // Create a new LoanBroker pointing back to the given Vault
         auto const vaultID = tx[sfVaultID];
         auto const sleVault = view.read(keylet::vault(vaultID));
         if (!sleVault)
@@ -252,7 +250,6 @@ LoanBrokerSet::doApply()
         if (auto ter = addEmptyHolding(view, pseudoId, preFeeBalance_, sleVault->at(sfAsset), j_))
             return ter;
 
-        // Initialize data fields:
         broker->at(sfSequence) = sequence;
         broker->at(sfVaultID) = vaultID;
         broker->at(sfOwner) = account_;
diff --git a/src/libxrpl/tx/transactors/lending/LoanDelete.cpp b/src/libxrpl/tx/transactors/lending/LoanDelete.cpp
index 928ba67db4..3ce402c8ab 100644
--- a/src/libxrpl/tx/transactors/lending/LoanDelete.cpp
+++ b/src/libxrpl/tx/transactors/lending/LoanDelete.cpp
@@ -1,3 +1,20 @@
+/** @file LoanDelete.cpp
+ *  Implements the `LoanDelete` transactor for the XRP Ledger lending protocol
+ *  (XLS-66).
+ *
+ *  The teardown sequence requires two ordered steps:
+ *  1. All `Loan` objects for a broker are deleted via `LoanDelete` — each call
+ *     decrements `sfOwnerCount` on the `LoanBroker` SLE.
+ *  2. Once `sfOwnerCount` reaches zero the `LoanBroker` itself may be removed
+ *     via `LoanBrokerDelete`.
+ *
+ *  A critical edge case handled here: accumulated sub-precision rounding dust
+ *  in `sfDebtTotal` is forgiven when the last loan is deleted. No future
+ *  payment path can reduce it further, and leaving a non-zero `sfDebtTotal`
+ *  would permanently block `LoanBrokerDelete` (which requires that the debt
+ *  round to zero). The `XRPL_ASSERT_PARTS` guard confirms the residual is
+ *  already representationally zero before the assignment.
+ */
 #include <xrpl/tx/transactors/lending/LoanDelete.h>
 
 #include <xrpl/basics/Log.h>
@@ -97,23 +114,23 @@ LoanDelete::doApply()
         return tefBAD_LEDGER;  // LCOV_EXCL_LINE
     auto const vaultAsset = vaultSle->at(sfAsset);
 
-    // Remove LoanID from Directory of the LoanBroker pseudo-account.
     if (!view.dirRemove(
             keylet::ownerDir(brokerPseudoAccount), loanSle->at(sfLoanBrokerNode), loanID, false))
         return tefBAD_LEDGER;  // LCOV_EXCL_LINE
-    // Remove LoanID from Directory of the Borrower.
     if (!view.dirRemove(keylet::ownerDir(borrower), loanSle->at(sfOwnerNode), loanID, false))
         return tefBAD_LEDGER;  // LCOV_EXCL_LINE
 
-    // Delete the Loan object
     view.erase(loanSle);
 
-    // Decrement the LoanBroker's owner count.
-    // The broker's owner count is solely for the number of outstanding loans,
-    // and is distinct from the broker's pseudo-account's owner count
+    // The broker's sfOwnerCount tracks outstanding loans only — it is distinct
+    // from the broker's pseudo-account owner count, which governs XRP reserves.
+    // LoanBrokerDelete decrements the pseudo-account count by two; LoanDelete
+    // only touches this broker-level count.
     adjustOwnerCount(view, brokerSle, -1, j_);
-    // If there are no loans left, then any remaining debt must be forgiven,
-    // because there is no other way to pay it back.
+    // If no loans remain, forgive any residual sfDebtTotal. Rounding dust
+    // accumulates over many payment cycles and cannot be recovered once there
+    // are no more loans to repay against. Leaving a non-zero value would
+    // permanently block LoanBrokerDelete, which requires debt to round to zero.
     if (brokerSle->at(sfOwnerCount) == 0)
     {
         auto debtTotalProxy = brokerSle->at(sfDebtTotal);
@@ -130,10 +147,12 @@ LoanDelete::doApply()
             debtTotalProxy = 0;
         }
     }
-    // Decrement the borrower's owner count
     adjustOwnerCount(view, borrowerSle, -1, j_);
 
-    // These associations shouldn't do anything, but do them just to be safe
+    // associateAsset is a lending-transactor convention: STNumber / STTakesAsset
+    // fields carry asset-precision metadata that must remain consistent. Even on
+    // deletion paths where no write-back of these fields is expected, the
+    // defensive call ensures correctness if the convention ever changes.
     associateAsset(*loanSle, vaultAsset);
     associateAsset(*brokerSle, vaultAsset);
     associateAsset(*vaultSle, vaultAsset);
diff --git a/src/libxrpl/tx/transactors/lending/LoanManage.cpp b/src/libxrpl/tx/transactors/lending/LoanManage.cpp
index 648f33b980..dbcb0d4e87 100644
--- a/src/libxrpl/tx/transactors/lending/LoanManage.cpp
+++ b/src/libxrpl/tx/transactors/lending/LoanManage.cpp
@@ -1,3 +1,12 @@
+/** @file LoanManage.cpp
+ *  Implements the `LoanManage` transactor (ttLOAN_MANAGE, XLS-66).
+ *
+ *  Manages the credit-quality lifecycle of a loan — impairment, impairment
+ *  reversal, and formal default — on behalf of the `LoanBroker` that issued
+ *  the loan.  Multi-object accounting across the `Loan`, `LoanBroker`, and
+ *  `Vault` ledger entries is the core concern.  Payment processing lives in
+ *  `LoanPay`; loan creation lives in `LoanSet`.
+ */
 #include <xrpl/tx/transactors/lending/LoanManage.h>
 
 #include <xrpl/basics/Log.h>
@@ -77,12 +86,9 @@ LoanManage::preclaim(PreclaimContext const& ctx)
         JLOG(ctx.j.warn()) << "Loan does not exist.";
         return tecNO_ENTRY;
     }
-    // Impairment only allows certain transitions.
-    // 1. Once it's in default, it can't be changed.
-    // 2. It can get worse: unimpaired -> impaired -> default
-    //      or unimpaired -> default
-    // 3. It can get better: impaired -> unimpaired
-    // 4. If it's in a state, it can't be put in that state again.
+    // State-machine transitions: normal→impaired, normal→default,
+    // impaired→normal, impaired→default. Default is terminal; re-impair and
+    // un-impair-of-normal are blocked.
     if (loanSle->isFlag(lsfLoanDefault))
     {
         JLOG(ctx.j.warn()) << "Loan is in default. A defaulted loan can not be modified.";
@@ -129,20 +135,30 @@ LoanManage::preclaim(PreclaimContext const& ctx)
     return tesSUCCESS;
 }
 
+/** Compute the amount the vault is owed by a loan (XLS-66 §3.2.3.2).
+ *
+ *  The vault is owed principal plus its share of interest; management fees
+ *  accrue entirely to the broker.  `sfInterestOutstanding` is not stored
+ *  directly, so it is derived:
+ *
+ *  ```
+ *  InterestOutstanding = TotalValueOutstanding
+ *                        - PrincipalOutstanding
+ *                        - ManagementFeeOutstanding
+ *
+ *  owedToVault = PrincipalOutstanding + InterestOutstanding
+ *              = TotalValueOutstanding - ManagementFeeOutstanding
+ *  ```
+ *
+ *  This identity drives both the impairment paper-loss and the default
+ *  settlement amount.
+ *
+ *  @param loanSle  Read-only SLE for the Loan object.
+ *  @return         The amount the vault is owed, expressed as a `Number`.
+ */
 static Number
 owedToVault(SLE::ref loanSle)
 {
-    // Spec section 3.2.3.2, defines the default amount as
-    //
-    // DefaultAmount = (Loan.PrincipalOutstanding + Loan.InterestOutstanding)
-    //
-    // Loan.InterestOutstanding is not stored directly on ledger.
-    // It is computed as
-    //
-    // Loan.TotalValueOutstanding - Loan.PrincipalOutstanding -
-    //      Loan.ManagementFeeOutstanding
-    //
-    // Add that to the original formula, and you get this:
     return loanSle->at(sfTotalValueOutstanding) - loanSle->at(sfManagementFeeOutstanding);
 }
 
@@ -155,18 +171,15 @@ LoanManage::defaultLoan(
     Asset const& vaultAsset,
     beast::Journal j)
 {
-    // Calculate the amount of the Default that First-Loss Capital covers:
-
     std::int32_t const loanScale = loanSle->at(sfLoanScale);
     auto brokerDebtTotalProxy = brokerSle->at(sfDebtTotal);
 
     Number const totalDefaultAmount = owedToVault(loanSle);
 
-    // Apply the First-Loss Capital to the Default Amount
     TenthBips32 const coverRateMinimum{brokerSle->at(sfCoverRateMinimum)};
     TenthBips32 const coverRateLiquidation{brokerSle->at(sfCoverRateLiquidation)};
     auto const defaultCovered = [&]() {
-        // Always round the minimum required up.
+        // Always round upward — the broker must not under-cover the vault.
         NumberRoundModeGuard const mg(Number::RoundingMode::Upward);
         auto const minimumCover = tenthBipsOfValue(brokerDebtTotalProxy.value(), coverRateMinimum);
         // Round the liquidation amount up, too
@@ -186,8 +199,6 @@ LoanManage::defaultLoan(
 
     auto const vaultDefaultAmount = totalDefaultAmount - defaultCovered;
 
-    // Update the Vault object:
-
     // The vault may be at a different scale than the loan. Reduce rounding
     // errors during the accounting by rounding some of the values to that
     // scale.
@@ -209,8 +220,7 @@ LoanManage::defaultLoan(
         auto const vaultDefaultRounded = roundToAsset(
             vaultAsset, vaultDefaultAmount, vaultScale, Number::RoundingMode::Downward);
         vaultTotalProxy -= vaultDefaultRounded;
-        // Increase the Asset Available of the Vault by liquidated First-Loss
-        // Capital and any unclaimed funds amount:
+        // Add back the first-loss capital recovered from the broker.
         vaultAvailableProxy += defaultCovered;
         if (*vaultAvailableProxy > *vaultTotalProxy && !vaultAsset.integral())
         {
@@ -239,7 +249,7 @@ LoanManage::defaultLoan(
             // LCOV_EXCL_STOP
         }
 
-        // The loss has been realized
+        // If previously impaired, convert the recorded paper loss to realized.
         if (loanSle->isFlag(lsfLoanImpaired))
         {
             auto vaultLossUnrealizedProxy = vaultSle->at(sfLossUnrealized);
@@ -256,12 +266,8 @@ LoanManage::defaultLoan(
         view.update(vaultSle);
     }
 
-    // Update the LoanBroker object:
-
     {
-        // Decrease the Debt of the LoanBroker:
         adjustImpreciseNumber(brokerDebtTotalProxy, -totalDefaultAmount, vaultAsset, vaultScale);
-        // Decrease the First-Loss Capital Cover Available:
         auto coverAvailableProxy = brokerSle->at(sfCoverAvailable);
         if (coverAvailableProxy < defaultCovered)
         {
@@ -274,20 +280,20 @@ LoanManage::defaultLoan(
         view.update(brokerSle);
     }
 
-    // Update the Loan object:
     loanSle->setFlag(lsfLoanDefault);
 
     loanSle->at(sfTotalValueOutstanding) = 0;
     loanSle->at(sfPaymentRemaining) = 0;
     loanSle->at(sfPrincipalOutstanding) = 0;
     loanSle->at(sfManagementFeeOutstanding) = 0;
-    // Zero out the next due date. Since it's default, it'll be removed from
-    // the object.
+    // Zero the due date — a defaulted loan has no future payment schedule;
+    // a zero value causes the field to be removed from the serialised object.
     loanSle->at(sfNextPaymentDueDate) = 0;
     view.update(loanSle);
 
-    // Return funds from the LoanBroker pseudo-account to the
-    // Vault pseudo-account:
+    // Transfer the covered amount from the broker pseudo-account to the
+    // vault pseudo-account. WaiveTransferFee::Yes is required because neither
+    // account is a regular user account.
     return accountSend(
         view,
         brokerSle->at(sfAccount),
@@ -308,11 +314,9 @@ LoanManage::impairLoan(
     Number const lossUnrealized = owedToVault(loanSle);
 
     // The vault may be at a different scale than the loan. Reduce rounding
-    // errors during the accounting by rounding some of the values to that
-    // scale.
+    // errors during the accounting by rounding values to the vault's scale.
     auto const vaultScale = getAssetsTotalScale(vaultSle);
 
-    // Update the Vault object(set "paper loss")
     auto vaultLossUnrealizedProxy = vaultSle->at(sfLossUnrealized);
     adjustImpreciseNumber(vaultLossUnrealizedProxy, lossUnrealized, vaultAsset, vaultScale);
     if (vaultLossUnrealizedProxy > vaultSle->at(sfAssetsTotal) - vaultSle->at(sfAssetsAvailable))
@@ -325,13 +329,13 @@ LoanManage::impairLoan(
     }
     view.update(vaultSle);
 
-    // Update the Loan object
     loanSle->setFlag(lsfLoanImpaired);
     auto loanNextDueProxy = loanSle->at(sfNextPaymentDueDate);
     if (!hasExpired(view, loanNextDueProxy))
     {
-        // loan payment is not yet late -
-        // move the next payment due date to now
+        // Payment is not yet overdue — accelerate the due date to now so the
+        // grace period clock starts immediately rather than from the original
+        // scheduled date.
         loanNextDueProxy = view.parentCloseTime().time_since_epoch().count();
     }
     view.update(loanSle);
@@ -348,11 +352,9 @@ LoanManage::unimpairLoan(
     beast::Journal j)
 {
     // The vault may be at a different scale than the loan. Reduce rounding
-    // errors during the accounting by rounding some of the values to that
-    // scale.
+    // errors during the accounting by rounding values to the vault's scale.
     auto const vaultScale = getAssetsTotalScale(vaultSle);
 
-    // Update the Vault object(clear "paper loss")
     auto vaultLossUnrealizedProxy = vaultSle->at(sfLossUnrealized);
     Number const lossReversed = owedToVault(loanSle);
     if (vaultLossUnrealizedProxy < lossReversed)
@@ -362,24 +364,24 @@ LoanManage::unimpairLoan(
         return tefBAD_LEDGER;
         // LCOV_EXCL_STOP
     }
-    // Reverse the "paper loss"
     adjustImpreciseNumber(vaultLossUnrealizedProxy, -lossReversed, vaultAsset, vaultScale);
 
     view.update(vaultSle);
 
-    // Update the Loan object
     loanSle->clearFlag(lsfLoanImpaired);
     auto const paymentInterval = loanSle->at(sfPaymentInterval);
     auto const normalPaymentDueDate =
         std::max(loanSle->at(sfPreviousPaymentDueDate), loanSle->at(sfStartDate)) + paymentInterval;
     if (!hasExpired(view, normalPaymentDueDate))
     {
-        // loan was unimpaired within the payment interval
+        // Original due date is still in the future — restore the amortization
+        // schedule unchanged so the borrower loses no payment window.
         loanSle->at(sfNextPaymentDueDate) = normalPaymentDueDate;
     }
     else
     {
-        // loan was unimpaired after the original payment due date
+        // Original due date has passed — give the borrower a fresh interval
+        // from now rather than leaving the loan immediately overdue.
         loanSle->at(sfNextPaymentDueDate) =
             view.parentCloseTime().time_since_epoch().count() + paymentInterval;
     }
@@ -410,15 +412,14 @@ LoanManage::doApply()
     auto const vaultAsset = vaultSle->at(sfAsset);
 
     auto const result = [&]() -> TER {
-        // Valid flag combinations are checked in preflight. No flags is valid -
-        // just a noop.
+        // Mutual exclusivity of flags is enforced in preflight. No flags is a
+        // valid no-op form (e.g., used to trigger associateAsset post-amendment).
         if (tx.isFlag(tfLoanDefault))
             return defaultLoan(view, loanSle, brokerSle, vaultSle, vaultAsset, j_);
         if (tx.isFlag(tfLoanImpair))
             return impairLoan(view, loanSle, vaultSle, vaultAsset, j_);
         if (tx.isFlag(tfLoanUnimpair))
             return unimpairLoan(view, loanSle, vaultSle, vaultAsset, j_);
-        // NoOp, as described above.
         return tesSUCCESS;
     }();
 
diff --git a/src/libxrpl/tx/transactors/lending/LoanPay.cpp b/src/libxrpl/tx/transactors/lending/LoanPay.cpp
index ef93f0dc1b..eaabb4bddb 100644
--- a/src/libxrpl/tx/transactors/lending/LoanPay.cpp
+++ b/src/libxrpl/tx/transactors/lending/LoanPay.cpp
@@ -1,3 +1,17 @@
+/** @file
+ *  Implementation of the `LoanPay` transactor for the XRPL Lending Protocol
+ *  (XLS-66).
+ *
+ *  Covers the full transaction pipeline — `checkExtraFeatures`, `getFlagsMask`,
+ *  `preflight`, `calculateBaseFee`, `preclaim`, and `doApply` — for the
+ *  `ttLOAN_PAY` transaction type.  `doApply` is the algorithmic core: it
+ *  unwinds any prior impairment, runs the amortization arithmetic via
+ *  `loanMakePayment`, routes the broker service fee to either the broker
+ *  owner or the first-loss cover pool, and atomically transfers funds from
+ *  the borrower to the vault pseudo-account and the broker payee.
+ *
+ *  See `LoanPay.h` for the class contract and per-method behavioral docs.
+ */
 #include <xrpl/tx/transactors/lending/LoanPay.h>
 
 #include <xrpl/basics/Expected.h>
@@ -70,6 +84,26 @@ LoanPay::preflight(PreflightContext const& ctx)
     return tesSUCCESS;
 }
 
+/** Fee scaling for multi-installment loan payments.
+ *
+ *  Late and full payments always return a single base fee — they perform a
+ *  bounded, fixed amount of work regardless of `sfAmount`.
+ *
+ *  For regular and overpayment types the method reads the loan → loanbroker →
+ *  vault hierarchy to derive `regularPayment = roundedPeriodicPayment +
+ *  serviceFee`, then estimates `numPayments = amount / regularPayment`.  One
+ *  base-fee unit is charged per `kLOAN_PAYMENTS_PER_FEE_INCREMENT` estimated
+ *  payments (minimum 1, rounded up).  When `fixSecurity3_1_3` is active the
+ *  result is capped at `kLOAN_MAXIMUM_PAYMENTS_PER_TRANSACTION /
+ *  kLOAN_PAYMENTS_PER_FEE_INCREMENT` fee increments — matching the hard
+ *  processing cap that `loanMakePayment` enforces at apply time, so the fee
+ *  is never charged for work that cannot happen.
+ *
+ *  Overpayments use upward rounding for the payment estimate (conservative
+ *  billing); regular payments use downward rounding.  If any ledger object
+ *  in the chain is missing or the asset does not match, the method falls back
+ *  to `normalCost` and defers the error to `preclaim`.
+ */
 XRPAmount
 LoanPay::calculateBaseFee(ReadView const& view, STTx const& tx)
 {
@@ -277,6 +311,59 @@ LoanPay::preclaim(PreclaimContext const& ctx)
     return tesSUCCESS;
 }
 
+/** Atomic loan repayment: state mutation, accounting, and fund transfer.
+ *
+ *  Execution proceeds in five sequential phases:
+ *
+ *  **1. Impairment reversal.**  If `lsfLoanImpaired` is set,
+ *  `LoanManage::unimpairLoan` is called first.  It reverses the paper loss
+ *  recorded in the vault's `sfLossUnrealized` and recalculates
+ *  `sfNextPaymentDueDate`.  This must precede `loanMakePayment` because the
+ *  payment classification (late vs. on-time) depends on the corrected due date.
+ *
+ *  **2. Payment computation.**  `loanMakePayment` runs the XLS-66 amortization
+ *  arithmetic and modifies `loanSle` in-place, returning a `LoanPaymentParts`
+ *  breakdown: `principalPaid`, `interestPaid`, `feePaid`, and `valueChange`.
+ *  `valueChange` is negative for overpayments (extra principal reduction) and
+ *  positive for late/full payments (penalty interest accrued).
+ *
+ *  **3. Broker fee routing.**  The service fee is sent to the broker owner's
+ *  account when cover available ≥ `tenthBipsOfValue(debtTotal, coverRateMinimum)`
+ *  (rounded up) AND the owner is neither deep-frozen nor unauthorized.  The
+ *  upward rounding is conservative: it ensures `sfCoverAvailable` never dips
+ *  below the theoretical minimum, protecting the broker's solvency.  If the
+ *  owner cannot receive funds, the fee accumulates in the broker pseudo-account
+ *  (first-loss cover pool).  Only when both the owner and the pseudo-account are
+ *  deep-frozen does the transaction fail.
+ *
+ *  **4. Scale-reconciled accounting.**  The vault and loan may operate at
+ *  different numeric scales.  `totalPaidToVaultRounded` is rounded down to the
+ *  vault scale (preventing over-crediting).  The broker's `sfDebtTotal` is
+ *  adjusted via `adjustImpreciseNumber`, which re-rounds to vault scale and
+ *  floors at zero so accumulated rounding drift across multiple loans never
+ *  produces a negative debt balance.  `sfAssetsTotal` is adjusted by
+ *  `valueChange`, while `sfAssetsAvailable` is adjusted by
+ *  `totalPaidToVaultRounded`; the invariant `available ≤ total` is asserted
+ *  (and guarded with `tecINTERNAL` as a last-resort failsafe).
+ *
+ *  **5. Atomic fund transfer.**  A single `accountSendMulti` call moves funds:
+ *  borrower → vault pseudo-account (`totalPaidToVaultRounded`) and borrower →
+ *  broker payee (`totalPaidToBroker`).  Transfer fees are waived
+ *  (`WaiveTransferFee::Yes`) because the amortization schedule dictates exact
+ *  amounts.  If the broker is also the transaction submitter, `addEmptyHolding`
+ *  recreates a token holding the broker may have previously deleted.
+ *
+ *  @note In debug builds two `#if !NDEBUG` blocks verify fund conservation and
+ *      that `sfAssetsAvailable` tracks the vault pseudo-account's actual balance
+ *      before and after the transfer.  These are too expensive for release builds;
+ *      `XRPL_ASSERT_PARTS` macros serve as lightweight release-build postcondition
+ *      guards.
+ *
+ *  @return `tesSUCCESS` on success; `tefBAD_LEDGER` if any required SLE is
+ *      missing (implies ledger corruption); a `tec` code from `loanMakePayment`
+ *      or `LoanManage::unimpairLoan` on computation failure; `tecINTERNAL` if
+ *      the `assetsAvailable ≤ assetsTotal` invariant is violated post-accounting.
+ */
 TER
 LoanPay::doApply()
 {
diff --git a/src/libxrpl/tx/transactors/lending/LoanSet.cpp b/src/libxrpl/tx/transactors/lending/LoanSet.cpp
index 3f5bbfb1a3..26bd2113f2 100644
--- a/src/libxrpl/tx/transactors/lending/LoanSet.cpp
+++ b/src/libxrpl/tx/transactors/lending/LoanSet.cpp
@@ -1,3 +1,12 @@
+/** @file
+ *  Implements the `LoanSet` transactor for the XLS-66 on-ledger lending protocol.
+ *
+ *  `LoanSet` is the entry point for creating a new loan: it disburses principal
+ *  from a vault's pool of assets to a borrower, records the full amortization
+ *  schedule as a `Loan` ledger entry, and updates the `LoanBroker` and `Vault`
+ *  SLEs accordingly.  Subsequent payments are handled by `LoanPay`; teardown by
+ *  `LoanDelete`.  All financial math is delegated to `LendingHelpers.cpp`.
+ */
 #include <xrpl/tx/transactors/lending/LoanSet.h>
 
 #include <xrpl/basics/Log.h>
@@ -92,7 +101,6 @@ LoanSet::preflight(PreflightContext const& ctx)
         if (!validNumericMinimum(tx[~*field]))
             return temINVALID;
     }
-    // Principal Requested is required
     auto const p = tx[sfPrincipalRequested];
     if (p <= 0)
         return temINVALID;
@@ -207,6 +215,16 @@ LoanSet::getValueFields()
     return kVALUE_FIELDS;
 }
 
+/** Return the current ledger close time as a raw 32-bit second count.
+ *
+ *  Used both as `sfStartDate` on the newly-created `Loan` SLE and as the base
+ *  value for the schedule-overflow arithmetic in `preclaim`.  The result is
+ *  directly comparable to `sfNextPaymentDueDate`, which is also stored as
+ *  `std::uint32_t` seconds since the XRPL epoch.
+ *
+ *  @param view  Read-only ledger view from which the close time is taken.
+ *  @return Close time in seconds since the XRPL epoch.
+ */
 static std::uint32_t
 getStartDate(ReadView const& view)
 {
@@ -568,11 +586,9 @@ LoanSet::doApply()
             WaiveTransferFee::Yes))
         return ter;
 
-    // Get shortcuts to the loan property values
     auto const startDate = getStartDate(view);
     auto loanSequenceProxy = brokerSle->at(sfLoanSequence);
 
-    // Create the loan
     auto loan = std::make_shared<SLE>(keylet::loan(brokerID, *loanSequenceProxy));
 
     // Prevent copy/paste errors
@@ -582,14 +598,12 @@ LoanSet::doApply()
         loan->at(field) = tx[field].value_or(defValue);
     };
 
-    // Set required and fixed tx fields
     loan->at(sfLoanScale) = properties.loanScale;
     loan->at(sfStartDate) = startDate;
     loan->at(sfPaymentInterval) = paymentInterval;
     loan->at(sfLoanSequence) = *loanSequenceProxy;
     loan->at(sfLoanBrokerID) = brokerID;
     loan->at(sfBorrower) = borrower;
-    // Set all other transaction fields directly from the transaction
     if (tx.isFlag(tfLoanOverpayment))
         loan->setFlag(lsfLoanOverpayment);
     setLoanField(~sfLoanOriginationFee);
@@ -602,7 +616,6 @@ LoanSet::doApply()
     setLoanField(~sfCloseInterestRate);
     setLoanField(~sfOverpaymentInterestRate);
     setLoanField(~sfGracePeriod, kDEFAULT_GRACE_PERIOD);
-    // Set dynamic / computed fields to their initial values
     loan->at(sfPrincipalOutstanding) = principalRequested;
     loan->at(sfPeriodicPayment) = properties.periodicPayment;
     loan->at(sfTotalValueOutstanding) = properties.loanState.valueOutstanding;
@@ -612,7 +625,6 @@ LoanSet::doApply()
     loan->at(sfPaymentRemaining) = paymentTotal;
     view.insert(loan);
 
-    // Update the balances in the vault
     vaultAvailableProxy -= principalRequested;
     vaultTotalProxy += state.interestDue;
     XRPL_ASSERT_PARTS(
@@ -621,7 +633,6 @@ LoanSet::doApply()
         "assets available must not be greater than assets outstanding");
     view.update(vaultSle);
 
-    // Update the balances in the loan broker
     adjustImpreciseNumber(brokerSle->at(sfDebtTotal), newDebtDelta, vaultAsset, vaultScale);
     // The broker's owner count is solely for the number of outstanding loans,
     // and is distinct from the broker's pseudo-account's owner count
@@ -633,10 +644,8 @@ LoanSet::doApply()
         return tecMAX_SEQUENCE_REACHED;
     view.update(brokerSle);
 
-    // Put the loan into the pseudo-account's directory
     if (auto const ter = dirLink(view, brokerPseudo, loan, sfLoanBrokerNode))
         return ter;
-    // Borrower is the owner of the loan
     if (auto const ter = dirLink(view, borrower, loan, sfOwnerNode))
         return ter;
 
diff --git a/src/libxrpl/tx/transactors/nft/NFTokenAcceptOffer.cpp b/src/libxrpl/tx/transactors/nft/NFTokenAcceptOffer.cpp
index 2aa2720e46..1ae0235c5c 100644
--- a/src/libxrpl/tx/transactors/nft/NFTokenAcceptOffer.cpp
+++ b/src/libxrpl/tx/transactors/nft/NFTokenAcceptOffer.cpp
@@ -1,3 +1,11 @@
+/** @file
+ *  Implementation of the `NFTokenAcceptOffer` transactor.
+ *
+ *  This is the most financially complex NFT transaction: up to four parties
+ *  (buyer, seller, royalty issuer, broker) may receive funds in a single
+ *  atomic apply.  See the class and method documentation in
+ *  `NFTokenAcceptOffer.h` for the full behavioral contract.
+ */
 #include <xrpl/tx/transactors/nft/NFTokenAcceptOffer.h>
 
 #include <xrpl/basics/Log.h>
@@ -33,12 +41,9 @@ NFTokenAcceptOffer::preflight(PreflightContext const& ctx)
     auto const bo = ctx.tx[~sfNFTokenBuyOffer];
     auto const so = ctx.tx[~sfNFTokenSellOffer];
 
-    // At least one of these MUST be specified
     if (!bo && !so)
         return temMALFORMED;
 
-    // The `BrokerFee` field must not be present in direct mode but may be
-    // present and greater than zero in brokered mode.
     if (auto const bf = ctx.tx[~sfNFTokenBrokerFee])
     {
         if (!bo || !so)
@@ -68,12 +73,12 @@ NFTokenAcceptOffer::preclaim(PreclaimContext const& ctx)
 
             if (hasExpired(ctx.view, (*offerSLE)[~sfExpiration]))
             {
-                // Before fixSecurity3_1_3 amendment, expired offers caused tecEXPIRED in preclaim,
-                // leaving them on ledger forever. After the amendment, we allow expired offers to
-                // reach doApply() where they get deleted and tecEXPIRED is returned.
+                // Before fixSecurity3_1_3, returning tecEXPIRED here left the
+                // expired offer stranded on the ledger (doApply was never reached).
+                // After the amendment, we pass the expired SLE through so doApply
+                // can delete it before returning tecEXPIRED.
                 if (!ctx.view.rules().enabled(fixSecurity3_1_3))
                     return {nullptr, tecEXPIRED};
-                // Amendment enabled: return the expired offer to be handled in doApply.
             }
 
             if ((*offerSLE)[sfAmount].negative())
@@ -93,43 +98,31 @@ NFTokenAcceptOffer::preclaim(PreclaimContext const& ctx)
 
     if (bo && so)
     {
-        // Brokered mode:
-        // The two offers being brokered must be for the same token:
         if ((*bo)[sfNFTokenID] != (*so)[sfNFTokenID])
             return tecNFTOKEN_BUY_SELL_MISMATCH;
 
-        // The two offers being brokered must be for the same asset:
         if ((*bo)[sfAmount].asset() != (*so)[sfAmount].asset())
             return tecNFTOKEN_BUY_SELL_MISMATCH;
 
-        // The two offers may not form a loop.  A broker may not sell the
-        // token to the current owner of the token.
+        // Reject self-trades: a broker may not facilitate a sale from an
+        // account to itself.
         if (((*bo)[sfOwner] == (*so)[sfOwner]))
             return tecCANT_ACCEPT_OWN_NFTOKEN_OFFER;
 
-        // Ensure that the buyer is willing to pay at least as much as the
-        // seller is requesting:
         if ((*so)[sfAmount] > (*bo)[sfAmount])
             return tecINSUFFICIENT_PAYMENT;
 
-        // The destination must be whoever is submitting the tx if the buyer
-        // specified it
+        // In brokered mode the submitter is the broker; both offers'
+        // Destination (if set) must name the broker.
         if (auto const dest = bo->at(~sfDestination); dest && *dest != ctx.tx[sfAccount])
-        {
             return tecNO_PERMISSION;
-        }
 
-        // The destination must be whoever is submitting the tx if the seller
-        // specified it
         if (auto const dest = so->at(~sfDestination); dest && *dest != ctx.tx[sfAccount])
-        {
             return tecNO_PERMISSION;
-        }
 
-        // The broker can specify an amount that represents their cut; if they
-        // have, ensure that the seller will get at least as much as they want
-        // to get *after* this fee is accounted for (but before the issuer's
-        // cut, if any).
+        // The broker fee is deducted from the buyer's amount first; what
+        // remains must still satisfy the seller's ask (issuer royalty is
+        // computed on the post-broker remainder in doApply).
         if (auto const brokerFee = ctx.tx[~sfNFTokenBrokerFee])
         {
             if (brokerFee->asset() != (*bo)[sfAmount].asset())
@@ -162,38 +155,31 @@ NFTokenAcceptOffer::preclaim(PreclaimContext const& ctx)
         if (((*bo)[sfFlags] & lsfSellNFToken) == lsfSellNFToken)
             return tecNFTOKEN_OFFER_TYPE_MISMATCH;
 
-        // An account can't accept an offer it placed:
         if ((*bo)[sfOwner] == ctx.tx[sfAccount])
             return tecCANT_ACCEPT_OWN_NFTOKEN_OFFER;
 
-        // If not in bridged mode, the account must own the token:
+        // In direct mode the submitter must own the token they are selling.
         if (!so && !nft::findToken(ctx.view, ctx.tx[sfAccount], (*bo)[sfNFTokenID]))
             return tecNO_PERMISSION;
 
-        // If not in bridged mode...
         if (!so)
         {
-            // If the offer has a Destination field, the acceptor must be the
-            // Destination.
             if (auto const dest = bo->at(~sfDestination);
                 dest.has_value() && *dest != ctx.tx[sfAccount])
                 return tecNO_PERMISSION;
         }
 
-        // The account offering to buy must have funds:
-        //
-        // After this amendment, we allow an IOU issuer to buy an NFT with their
-        // own currency
+        // An IOU issuer may buy an NFT with their own currency; accountFunds
+        // handles this by treating the issuer's own IOU as zero-cost.
         auto const needed = bo->at(sfAmount);
 
         if (accountFunds(ctx.view, (*bo)[sfOwner], needed, FreezeHandling::ZeroIfFrozen, ctx.j) <
             needed)
             return tecINSUFFICIENT_FUNDS;
 
-        // Check that the account accepting the buy offer (he's selling the NFT)
-        // is allowed to receive IOUs. Also check that this offer's creator is
-        // authorized. But we need to exclude the case when the transaction is
-        // created by the broker.
+        // Trust-line checks for the IOU payment: buyer must be authorized and
+        // the seller (direct mode submitter) must be authorized and not deep-
+        // frozen. Skipped in brokered mode — the broker is not the IOU recipient.
         if (ctx.view.rules().enabled(fixEnforceNFTokenTrustlineV2) && !needed.native())
         {
             auto res = nft::checkTrustlineAuthorized(
@@ -221,47 +207,31 @@ NFTokenAcceptOffer::preclaim(PreclaimContext const& ctx)
         if (((*so)[sfFlags] & lsfSellNFToken) != lsfSellNFToken)
             return tecNFTOKEN_OFFER_TYPE_MISMATCH;
 
-        // An account can't accept an offer it placed:
         if ((*so)[sfOwner] == ctx.tx[sfAccount])
             return tecCANT_ACCEPT_OWN_NFTOKEN_OFFER;
 
-        // The seller must own the token.
         if (!nft::findToken(ctx.view, (*so)[sfOwner], (*so)[sfNFTokenID]))
             return tecNO_PERMISSION;
 
-        // If not in bridged mode...
         if (!bo)
         {
-            // If the offer has a Destination field, the acceptor must be the
-            // Destination.
             if (auto const dest = so->at(~sfDestination);
                 dest.has_value() && *dest != ctx.tx[sfAccount])
                 return tecNO_PERMISSION;
         }
 
-        // The account offering to buy must have funds:
         auto const needed = so->at(sfAmount);
         if (!bo)
         {
-            // After this amendment, we allow buyers to buy with their own
-            // issued currency.
-            //
-            // In the case of brokered mode, this check is essentially
-            // redundant, since we have already confirmed that buy offer is >
-            // than the sell offer, and that the buyer can cover the buy
-            // offer.
-            //
-            // We also _must not_ check the tx submitter in brokered
-            // mode, because then we are confirming that the broker can
-            // cover what the buyer will pay, which doesn't make sense, causes
-            // an unnecessary tec, and is also resolved with this amendment.
+            // In brokered mode this check is skipped: the buyer's solvency is
+            // already confirmed via the buy-offer check, and checking the
+            // broker's balance here would produce a spurious tecINSUFFICIENT_FUNDS.
             if (accountFunds(
                     ctx.view, ctx.tx[sfAccount], needed, FreezeHandling::ZeroIfFrozen, ctx.j) <
                 needed)
                 return tecINSUFFICIENT_FUNDS;
         }
 
-        // Make sure that we are allowed to hold what the taker will pay us.
         if (!needed.native())
         {
             if (ctx.view.rules().enabled(fixEnforceNFTokenTrustlineV2))
@@ -287,8 +257,8 @@ NFTokenAcceptOffer::preclaim(PreclaimContext const& ctx)
         }
     }
 
-    // Additional checks are required in case a minter set a transfer fee for
-    // this nftoken
+    // When a transfer fee is set on the token, the issuer is an additional
+    // IOU payment recipient and must pass trust-line hygiene checks.
     auto const& offer = bo ? bo : so;
     if (!offer)
     {
@@ -302,16 +272,16 @@ NFTokenAcceptOffer::preclaim(PreclaimContext const& ctx)
 
     if (nft::getTransferFee(tokenID) != 0 && !amount.native())
     {
-        // Fix a bug where the transfer of an NFToken with a transfer fee could
-        // give the NFToken issuer an undesired trust line.
-        // Issuer doesn't need a trust line to accept their own currency.
+        // fixEnforceNFTokenTrustline: if the token lacks kFLAG_CREATE_TRUST_LINES
+        // and no trust line already exists between the issuer and the IOU issuer,
+        // the transfer would silently create an unintended trust line for the royalty
+        // payment. Reject unless the NFT issuer is also the IOU issuer (self-payment).
         if (ctx.view.rules().enabled(fixEnforceNFTokenTrustline) &&
             (nft::getFlags(tokenID) & nft::kFLAG_CREATE_TRUST_LINES) == 0 &&
             nftMinter != amount.getIssuer() &&
             !ctx.view.read(keylet::line(nftMinter, amount.get<Issue>())))
             return tecNO_LINE;
 
-        // Check that the issuer is allowed to receive IOUs.
         if (ctx.view.rules().enabled(fixEnforceNFTokenTrustlineV2))
         {
             auto res = nft::checkTrustlineAuthorized(
@@ -332,17 +302,15 @@ NFTokenAcceptOffer::preclaim(PreclaimContext const& ctx)
 TER
 NFTokenAcceptOffer::pay(AccountID const& from, AccountID const& to, STAmount const& amount)
 {
-    // This should never happen, but it's easy and quick to check.
     if (amount < beast::kZERO)
         return tecINTERNAL;  // LCOV_EXCL_LINE
 
     auto const result = accountSend(view(), from, to, amount, j_);
 
-    // If any payment causes a non-IOU-issuer to have a negative balance,
-    // or an IOU-issuer to have a positive balance in their own currency,
-    // we know that something went wrong. This was originally found in the
-    // context of IOU transfer fees. Since there are several payouts in this tx,
-    // just confirm that the end state is OK.
+    // IOU transfer fees can leave the sender with a small negative or the
+    // receiver (when they are the IOU issuer) with a positive balance in their
+    // own currency. Check both parties after every payment to catch these
+    // edge cases before they corrupt the ledger.
     if (!isTesSuccess(result))
         return result;
     if (accountFunds(view(), from, amount, FreezeHandling::ZeroIfFrozen, j_).signum() < 0)
@@ -375,19 +343,11 @@ NFTokenAcceptOffer::transferNFToken(
 
     auto const insertRet = nft::insertToken(view(), buyer, std::move(tokenAndPage->token));
 
-    // if fixNFTokenReserve is enabled, check if the buyer has sufficient
-    // reserve to own a new object, if their OwnerCount changed.
-    //
-    // There was an issue where the buyer accepts a sell offer, the ledger
-    // didn't check if the buyer has enough reserve, meaning that buyer can get
-    // NFTs free of reserve.
     if (view().rules().enabled(fixNFTokenReserve))
     {
-        // To check if there is sufficient reserve, we cannot use preFeeBalance_
-        // because NFT is sold for a price. So we must use the balance after
-        // the deduction of the potential offer price. A small caveat here is
-        // that the balance has already deducted the transaction fee, meaning
-        // that the reserve requirement is a few drops higher.
+        // Use the buyer's current post-purchase balance, not preFeeBalance_.
+        // The tx fee has already been deducted, so the effective reserve bar
+        // is a few drops higher than the owner-count formula alone would imply.
         auto const buyerBalance = sleBuyer->getFieldAmount(sfBalance);
 
         auto const buyerOwnerCountAfter = sleBuyer->getFieldU32(sfOwnerCount);
@@ -414,11 +374,12 @@ NFTokenAcceptOffer::acceptOffer(std::shared_ptr<SLE> const& offer)
 
     if (auto amount = offer->getFieldAmount(sfAmount); amount != beast::kZERO)
     {
-        // Calculate the issuer's cut from this sale, if any:
         if (auto const fee = nft::getTransferFee(nftokenID); fee != 0)
         {
             auto const cut = multiply(amount, nft::transferFeeAsRate(fee));
 
+            // Skip the royalty when either party is the issuer: paying the
+            // issuer their own cut would be a no-op or nonsensical self-transfer.
             if (auto const issuer = nft::getIssuer(nftokenID);
                 cut != beast::kZERO && seller != issuer && buyer != issuer)
             {
@@ -428,12 +389,10 @@ NFTokenAcceptOffer::acceptOffer(std::shared_ptr<SLE> const& offer)
             }
         }
 
-        // Send the remaining funds to the seller of the NFT
         if (auto const r = pay(buyer, seller, amount); !isTesSuccess(r))
             return r;
     }
 
-    // Now transfer the NFT:
     return transferNFToken(buyer, seller, nftokenID);
 }
 
@@ -450,8 +409,8 @@ NFTokenAcceptOffer::doApply()
     auto bo = loadToken(ctx_.tx[~sfNFTokenBuyOffer]);
     auto so = loadToken(ctx_.tx[~sfNFTokenSellOffer]);
 
-    // With fixSecurity3_1_3 amendment, check for expired offers and delete them, returning
-    // tecEXPIRED. This ensures expired offers are properly cleaned up from the ledger.
+    // Under fixSecurity3_1_3, expired offers are passed through preclaim so we
+    // can delete them here, preventing them from becoming permanently stranded.
     if (view().rules().enabled(fixSecurity3_1_3))
     {
         bool foundExpired = false;
@@ -501,7 +460,6 @@ NFTokenAcceptOffer::doApply()
         // LCOV_EXCL_STOP
     }
 
-    // Bridging two different offers
     if (bo && so)
     {
         AccountID const buyer = (*bo)[sfOwner];
@@ -509,23 +467,15 @@ NFTokenAcceptOffer::doApply()
 
         auto const nftokenID = (*so)[sfNFTokenID];
 
-        // The amount is what the buyer of the NFT pays:
         STAmount amount = (*bo)[sfAmount];
 
-        // Three different folks may be paid.  The order of operations is
-        // important.
+        // Payment ordering in brokered mode is strict and critical to correctness:
+        // 1. Broker receives their fee from the buyer's full amount.
+        // 2. Issuer royalty is computed on what remains after the broker cut.
+        // 3. Seller receives the final remainder.
         //
-        // o The broker is paid the cut they requested.
-        // o The issuer's cut is calculated from what remains after the
-        //   broker is paid.  The issuer can take up to 50% of the remainder.
-        // o Finally, the seller gets whatever is left.
-        //
-        // It is important that the issuer's cut be calculated after the
-        // broker's portion is already removed.  Calculating the issuer's
-        // cut before the broker's cut is removed can result in more money
-        // being paid out than the seller authorized.  That would be bad!
-
-        // Send the broker the amount they requested.
+        // Computing the issuer's royalty before removing the broker fee would
+        // allow total disbursements to exceed what the buyer authorised.
         if (auto const cut = ctx_.tx[~sfNFTokenBrokerFee]; cut && cut.value() != beast::kZERO)
         {
             if (auto const r = pay(buyer, account_, cut.value()); !isTesSuccess(r))
@@ -534,7 +484,6 @@ NFTokenAcceptOffer::doApply()
             amount -= cut.value();
         }
 
-        // Calculate the issuer's cut, if any.
         if (auto const fee = nft::getTransferFee(nftokenID); amount != beast::kZERO && fee != 0)
         {
             auto cut = multiply(amount, nft::transferFeeAsRate(fee));
@@ -548,14 +497,12 @@ NFTokenAcceptOffer::doApply()
             }
         }
 
-        // And send whatever remains to the seller.
         if (amount > beast::kZERO)
         {
             if (auto const r = pay(buyer, seller, amount); !isTesSuccess(r))
                 return r;
         }
 
-        // Now transfer the NFT:
         return transferNFToken(buyer, seller, nftokenID);
     }
 
diff --git a/src/libxrpl/tx/transactors/nft/NFTokenBurn.cpp b/src/libxrpl/tx/transactors/nft/NFTokenBurn.cpp
index 95791d220e..947271122a 100644
--- a/src/libxrpl/tx/transactors/nft/NFTokenBurn.cpp
+++ b/src/libxrpl/tx/transactors/nft/NFTokenBurn.cpp
@@ -1,3 +1,18 @@
+/** @file
+ *  Implementation of the `NFTokenBurn` transactor.
+ *
+ *  Permanently destroys an NFToken by removing it from the owner's
+ *  NFTokenPage, incrementing the issuer's `sfBurnedNFTokens` counter, and
+ *  deleting associated buy/sell offers up to `kMAX_DELETABLE_TOKEN_OFFER_ENTRIES`.
+ *
+ *  Permission model (enforced in `preclaim`):
+ *  - The **token owner** may always burn their own token.
+ *  - A **non-owner** requires the token's `nft::kFLAG_BURNABLE` bit to be set
+ *    and must be either the issuer or the issuer's `sfNFTokenMinter` delegate.
+ *
+ *  The issuer is read directly from the packed 256-bit `sfNFTokenID` via
+ *  `nft::getIssuer()` — no secondary ledger lookup is needed to resolve it.
+ */
 #include <xrpl/tx/transactors/nft/NFTokenBurn.h>
 
 #include <xrpl/beast/utility/Journal.h>
@@ -36,8 +51,6 @@ NFTokenBurn::preclaim(PreclaimContext const& ctx)
     if (!nft::findToken(ctx.view, owner, ctx.tx[sfNFTokenID]))
         return tecNO_ENTRY;
 
-    // The owner of a token can always burn it, but the issuer can only
-    // do so if the token is marked as burnable.
     if (auto const account = ctx.tx[sfAccount]; owner != account)
     {
         if ((nft::getFlags(ctx.tx[sfNFTokenID]) & nft::kFLAG_BURNABLE) == 0)
@@ -59,7 +72,6 @@ NFTokenBurn::preclaim(PreclaimContext const& ctx)
 TER
 NFTokenBurn::doApply()
 {
-    // Remove the token, effectively burning it:
     auto const ret = nft::removeToken(
         view(),
         ctx_.tx.isFieldPresent(sfOwner) ? ctx_.tx.getAccountID(sfOwner)
@@ -76,10 +88,9 @@ NFTokenBurn::doApply()
         view().update(issuer);
     }
 
-    // Delete up to 500 offers in total.
-    // Because the number of sell offers is likely to be less than
-    // the number of buy offers, we prioritize the deletion of sell
-    // offers in order to clean up sell offer directory
+    // Sell offers are processed first: their directory is typically smaller,
+    // so clearing them first maximises the chance of a complete cleanup
+    // within the single-transaction 500-offer budget.
     std::size_t const deletedSellOffers = nft::removeTokenOffersWithLimit(
         view(), keylet::nftSells(ctx_.tx[sfNFTokenID]), kMAX_DELETABLE_TOKEN_OFFER_ENTRIES);
 
diff --git a/src/libxrpl/tx/transactors/nft/NFTokenCancelOffer.cpp b/src/libxrpl/tx/transactors/nft/NFTokenCancelOffer.cpp
index 9186d32424..b19e6e5dd1 100644
--- a/src/libxrpl/tx/transactors/nft/NFTokenCancelOffer.cpp
+++ b/src/libxrpl/tx/transactors/nft/NFTokenCancelOffer.cpp
@@ -1,3 +1,15 @@
+/** @file
+ *  Implements the `NFTokenCancelOffer` transactor, which removes one or more
+ *  outstanding `NFTokenOffer` ledger objects in a single atomic transaction.
+ *
+ *  The three phases follow the standard transactor pattern: `preflight`
+ *  performs stateless list validation (size bounds, no duplicates), `preclaim`
+ *  checks per-offer cancellation rights on a read-only view, and `doApply`
+ *  calls `nft::deleteTokenOffer` to remove each offer and release its reserve.
+ *  Both `preclaim` and `doApply` silently skip offers that no longer exist,
+ *  making the operation idempotent when an offer is consumed between submission
+ *  and application.
+ */
 #include <xrpl/tx/transactors/nft/NFTokenCancelOffer.h>
 
 #include <xrpl/basics/Log.h>
@@ -47,25 +59,18 @@ NFTokenCancelOffer::preclaim(PreclaimContext const& ctx)
     auto ret = std::ranges::find_if(ids, [&ctx, &account](uint256 const& id) {
         auto const offer = ctx.view.read(keylet::child(id));
 
-        // If id is not in the ledger we assume the offer was consumed
-        // before we got here.
         if (!offer)
             return false;
 
-        // If id is in the ledger but is not an NFTokenOffer, then
-        // they have no permission.
         if (offer->getType() != ltNFTOKEN_OFFER)
             return true;
 
-        // Anyone can cancel, if expired
         if (hasExpired(ctx.view, (*offer)[~sfExpiration]))
             return false;
 
-        // The owner can always cancel
         if ((*offer)[sfOwner] == account)
             return false;
 
-        // The recipient can always cancel
         if (auto const dest = (*offer)[~sfDestination]; dest == account)
             return false;
 
diff --git a/src/libxrpl/tx/transactors/nft/NFTokenCreateOffer.cpp b/src/libxrpl/tx/transactors/nft/NFTokenCreateOffer.cpp
index 727290a80c..d36608a10f 100644
--- a/src/libxrpl/tx/transactors/nft/NFTokenCreateOffer.cpp
+++ b/src/libxrpl/tx/transactors/nft/NFTokenCreateOffer.cpp
@@ -1,3 +1,20 @@
+/**
+ * @file NFTokenCreateOffer.cpp
+ * @brief Transactor implementation for `ttNFTOKEN_CREATE_OFFER` (type 27).
+ *
+ * This file is intentionally thin: it acts as an adapter that extracts fields
+ * from the transaction context and forwards them to the three shared helpers
+ * declared in `NFTokenHelpers.h` — `tokenOfferCreatePreflight`,
+ * `tokenOfferCreatePreclaim`, and `tokenOfferCreateApply`. The same helpers
+ * are reused by `NFTokenMint`, which can create a sell offer atomically at
+ * mint time, ensuring the two transactors cannot drift apart on offer-creation
+ * rules.
+ *
+ * The only logic that lives here rather than in the shared helpers is the
+ * buy/sell token-ownership check in `preclaim` (which must switch on
+ * `tfSellNFToken` to choose the right account's NFT directory) and the
+ * pre-expiration guard (which requires the current ledger close time).
+ */
 #include <xrpl/tx/transactors/nft/NFTokenCreateOffer.h>
 
 #include <xrpl/basics/base_uint.h>
@@ -31,7 +48,6 @@ NFTokenCreateOffer::preflight(PreflightContext const& ctx)
 
     auto const nftFlags = nft::getFlags(ctx.tx[sfNFTokenID]);
 
-    // Use implementation shared with NFTokenMint
     if (NotTEC notTec = nft::tokenOfferCreatePreflight(
             ctx.tx[sfAccount],
             ctx.tx[sfAmount],
@@ -60,7 +76,6 @@ NFTokenCreateOffer::preclaim(PreclaimContext const& ctx)
             ctx.view, ctx.tx[((txFlags & tfSellNFToken) != 0u) ? sfAccount : sfOwner], nftokenID))
         return tecNO_ENTRY;
 
-    // Use implementation shared with NFTokenMint
     return nft::tokenOfferCreatePreclaim(
         ctx.view,
         ctx.tx[sfAccount],
@@ -77,7 +92,6 @@ NFTokenCreateOffer::preclaim(PreclaimContext const& ctx)
 TER
 NFTokenCreateOffer::doApply()
 {
-    // Use implementation shared with NFTokenMint
     return nft::tokenOfferCreateApply(
         view(),
         ctx_.tx[sfAccount],
@@ -97,7 +111,6 @@ NFTokenCreateOffer::visitInvariantEntry(
     std::shared_ptr<SLE const> const&,
     std::shared_ptr<SLE const> const&)
 {
-    // No transaction-specific invariants yet (future work).
 }
 
 bool
@@ -108,7 +121,6 @@ NFTokenCreateOffer::finalizeInvariants(
     ReadView const&,
     beast::Journal const&)
 {
-    // No transaction-specific invariants yet (future work).
     return true;
 }
 
diff --git a/src/libxrpl/tx/transactors/nft/NFTokenMint.cpp b/src/libxrpl/tx/transactors/nft/NFTokenMint.cpp
index 358e9b6bd6..7a58279b22 100644
--- a/src/libxrpl/tx/transactors/nft/NFTokenMint.cpp
+++ b/src/libxrpl/tx/transactors/nft/NFTokenMint.cpp
@@ -1,3 +1,11 @@
+/** @file
+ *  Implementation of the NFTokenMint transactor.
+ *
+ *  Handles the full lifecycle of NFT creation: stateless field validation
+ *  (`preflight`), read-only ledger checks (`preclaim`), and state mutations
+ *  (`doApply`). Also provides `createNFTokenID`, the canonical algorithm for
+ *  constructing the globally unique 256-bit NFToken identifier.
+ */
 #include <xrpl/tx/transactors/nft/NFTokenMint.h>
 
 #include <xrpl/basics/Expected.h>
@@ -32,12 +40,33 @@
 
 namespace xrpl {
 
+/** Extract the NFToken-flag half of the transaction flags word.
+ *
+ *  NFToken flags are packed into the lower 16 bits of the 32-bit transaction
+ *  flags field. The upper 16 bits are reserved for transaction-level flags
+ *  (e.g., `tfTransferable`, `tfTrustLine`). This helper isolates the token
+ *  flags for storage in the NFToken ID and for passing to offer helpers.
+ *
+ *  @param txFlags  The raw 32-bit flags from `STTx::getFlags()`.
+ *  @return The low 16 bits cast to `uint16_t`.
+ */
 static std::uint16_t
 extractNFTokenFlagsFromTxFlags(std::uint32_t txFlags)
 {
     return static_cast<std::uint16_t>(txFlags & 0x0000FFFF);
 }
 
+/** Return true if the transaction includes any embedded-offer fields.
+ *
+ *  The presence of `sfAmount`, `sfDestination`, or `sfExpiration` signals
+ *  that the minter wants to create an initial sell offer atomically with the
+ *  mint. Used by `checkExtraFeatures` to gate the sub-feature and by
+ *  `preflight`/`preclaim` to decide whether to invoke the shared offer
+ *  validation path.
+ *
+ *  @param ctx  Preflight context providing access to the transaction fields.
+ *  @return `true` if at least one offer-related field is present.
+ */
 static bool
 hasOfferFields(PreflightContext const& ctx)
 {
@@ -54,23 +83,10 @@ NFTokenMint::checkExtraFeatures(PreflightContext const& ctx)
 std::uint32_t
 NFTokenMint::getFlagsMask(PreflightContext const& ctx)
 {
-    // Prior to fixRemoveNFTokenAutoTrustLine, transfer of an NFToken between
-    // accounts allowed a TrustLine to be added to the issuer of that token
-    // without explicit permission from that issuer.  This was enabled by
-    // minting the NFToken with the tfTrustLine flag set.
-    //
-    // That capability could be used to attack the NFToken issuer.  It
-    // would be possible for two accounts to trade the NFToken back and forth
-    // building up any number of TrustLines on the issuer, increasing the
-    // issuer's reserve without bound.
-    //
-    // The fixRemoveNFTokenAutoTrustLine amendment disables minting with the
-    // tfTrustLine flag as a way to prevent the attack.  But until the
-    // amendment passes we still need to keep the old behavior available.
+    // Four combinations: {trustLine disabled, trustLine enabled} x {mutable URI, no mutable URI}
     std::uint32_t const nfTokenMintMask = [&]() -> std::uint32_t {
         if (ctx.rules.enabled(fixRemoveNFTokenAutoTrustLine))
         {
-            // if featureDynamicNFT enabled then new flag allowing mutable URI available
             return ctx.rules.enabled(featureDynamicNFT) ? tfNFTokenMintMask
                                                         : tfNFTokenMintMaskWithoutMutable;
         }
@@ -89,13 +105,12 @@ NFTokenMint::preflight(PreflightContext const& ctx)
         if (f > kMAX_TRANSFER_FEE)
             return temBAD_NFTOKEN_TRANSFER_FEE;
 
-        // If a non-zero TransferFee is set then the tfTransferable flag
-        // must also be set.
+        // A transfer fee on a non-transferable token is contradictory:
+        // there is no transfer that could ever collect it.
         if (f > 0u && !ctx.tx.isFlag(tfTransferable))
             return temMALFORMED;
     }
 
-    // An issuer must only be set if the tx is executed by the minter
     if (auto iss = ctx.tx[~sfIssuer]; iss == ctx.tx[sfAccount])
         return temMALFORMED;
 
@@ -107,14 +122,11 @@ NFTokenMint::preflight(PreflightContext const& ctx)
 
     if (hasOfferFields(ctx))
     {
-        // The Amount field must be present if either the Destination or
-        // Expiration fields are present.
         if (!ctx.tx.isFieldPresent(sfAmount))
             return temMALFORMED;
 
-        // Rely on the common code shared with NFTokenCreateOffer to
-        // do the validation.  We pass tfSellNFToken as the transaction flags
-        // because a Mint is only allowed to create a sell offer.
+        // Pass tfSellNFToken because a mint-bundled offer is always a sell
+        // offer; buy offers cannot be created atomically at mint time.
         if (NotTEC notTec = nft::tokenOfferCreatePreflight(
                 ctx.tx[sfAccount],
                 ctx.tx[sfAmount],
@@ -139,14 +151,8 @@ NFTokenMint::createNFTokenID(
     nft::Taxon taxon,
     std::uint32_t tokenSeq)
 {
-    // An issuer may issue several NFTs with the same taxon; to ensure that NFTs
-    // are spread across multiple pages we lightly mix the taxon up by using the
-    // sequence (which is not under the issuer's direct control) as the seed for
-    // a simple linear congruential generator.  cipheredTaxon() does this work.
     taxon = nft::cipheredTaxon(tokenSeq, taxon);
 
-    // The values are packed inside a 32-byte buffer, so we need to make sure
-    // that the endianess is fixed.
     flags = boost::endian::native_to_big(flags);
     fee = boost::endian::native_to_big(fee);
     taxon = nft::toTaxon(boost::endian::native_to_big(nft::toUInt32(taxon)));
@@ -156,8 +162,6 @@ NFTokenMint::createNFTokenID(
 
     auto ptr = buf.data();
 
-    // This code is awkward but the idea is to pack these values into a single
-    // 256-bit value that uniquely identifies this NFT.
     std::memcpy(ptr, &flags, sizeof(flags));
     ptr += sizeof(flags);
 
@@ -182,8 +186,6 @@ NFTokenMint::createNFTokenID(
 TER
 NFTokenMint::preclaim(PreclaimContext const& ctx)
 {
-    // The issuer of the NFT may or may not be the account executing this
-    // transaction. Check that and verify that this is allowed:
     if (auto issuer = ctx.tx[~sfIssuer])
     {
         auto const sle = ctx.view.read(keylet::account(*issuer));
@@ -197,13 +199,10 @@ NFTokenMint::preclaim(PreclaimContext const& ctx)
 
     if (ctx.tx.isFieldPresent(sfAmount))
     {
-        // The Amount field says create an offer for the minted token.
         if (hasExpired(ctx.view, ctx.tx[~sfExpiration]))
             return tecEXPIRED;
 
-        // Rely on the common code shared with NFTokenCreateOffer to
-        // do the validation.  We pass tfSellNFToken as the transaction flags
-        // because a Mint is only allowed to create a sell offer.
+        // Pass tfSellNFToken: mint-bundled offers are always sell offers.
         if (TER const ter = nft::tokenOfferCreatePreclaim(
                 ctx.view,
                 ctx.tx[sfAccount],
@@ -228,25 +227,17 @@ NFTokenMint::doApply()
         auto const root = view().peek(keylet::account(issuer));
         if (root == nullptr)
         {
-            // Should not happen.  Checked in preclaim.
-            return Unexpected(tecNO_ISSUER);
+            // Should not happen — checked in preclaim.
+            return Unexpected(tecNO_ISSUER);  // LCOV_EXCL_LINE
         }
 
-        // If the issuer hasn't minted an NFToken before we must add a
-        // FirstNFTokenSequence field to the issuer's AccountRoot.  The
-        // value of the FirstNFTokenSequence must equal the issuer's
-        // current account sequence.
-        //
-        // There are three situations:
-        //  o If the first token is being minted by the issuer and
-        //     * If the transaction consumes a Sequence number, then the
-        //       Sequence has been pre-incremented by the time we get here in
-        //       doApply.  We must decrement the value in the Sequence field.
-        //     * Otherwise the transaction uses a Ticket so the Sequence has
-        //       not been pre-incremented.  We use the Sequence value as is.
-        //  o The first token is being minted by an authorized minter.  In
-        //    this case the issuer's Sequence field has been left untouched.
-        //    We use the issuer's Sequence value as is.
+        // Bootstrap sfFirstNFTokenSequence on the very first mint.
+        // By the time doApply runs, the account sequence has already been
+        // pre-incremented for direct-sequence transactions, so we subtract 1
+        // to recover the pre-tx value.  Ticket-based transactions do not
+        // pre-increment the issuer's sequence, nor do authorized-minter
+        // transactions (where the issuer is a different account entirely), so
+        // in those two cases we use the sequence value as-is.
         if (!root->isFieldPresent(sfFirstNFTokenSequence))
         {
             std::uint32_t const acctSeq = root->at(sfSequence);
@@ -262,12 +253,10 @@ NFTokenMint::doApply()
         if ((*root)[sfMintedNFTokens] == 0u)
             return Unexpected(tecMAX_SEQUENCE_REACHED);
 
-        // Get the unique sequence number of this token by
-        // sfFirstNFTokenSequence + sfMintedNFTokens
+        // tokenSeq = sfFirstNFTokenSequence + sfMintedNFTokens (before increment)
         std::uint32_t const offset = (*root)[sfFirstNFTokenSequence];
         std::uint32_t const tokenSeq = offset + mintedNftCnt;
 
-        // Check for more overflow cases
         if (tokenSeq + 1u == 0u || tokenSeq < offset)
             return Unexpected(tecMAX_SEQUENCE_REACHED);
 
@@ -281,13 +270,12 @@ NFTokenMint::doApply()
     std::uint32_t const ownerCountBefore =
         view().read(keylet::account(account_))->getFieldU32(sfOwnerCount);
 
-    // Assemble the new NFToken.
     SOTemplate const* nfTokenTemplate =
         InnerObjectFormats::getInstance().findSOTemplateBySField(sfNFToken);
 
     if (nfTokenTemplate == nullptr)
     {
-        // Should never happen.
+        // Should never happen — sfNFToken is registered at startup.
         return tecINTERNAL;  // LCOV_EXCL_LINE
     }
 
@@ -311,9 +299,7 @@ NFTokenMint::doApply()
 
     if (ctx_.tx.isFieldPresent(sfAmount))
     {
-        // Rely on the common code shared with NFTokenCreateOffer to create
-        // the offer.  We pass tfSellNFToken as the transaction flags
-        // because a Mint is only allowed to create a sell offer.
+        // Pass tfSellNFToken: mint-bundled offers are always sell offers.
         if (TER const ter = nft::tokenOfferCreateApply(
                 view(),
                 ctx_.tx[sfAccount],
@@ -328,10 +314,9 @@ NFTokenMint::doApply()
             return ter;
     }
 
-    // Only check the reserve if the owner count actually changed.  This
-    // allows NFTs to be added to the page (and burn fees) without
-    // requiring the reserve to be met each time.  The reserve is
-    // only managed when a new NFT page or sell offer is added.
+    // Reserve is only checked when the owner count increased (new page or sell
+    // offer created).  Packing tokens into an existing page does not allocate a
+    // new ledger object and therefore imposes no incremental reserve cost.
     if (auto const ownerCountAfter =
             view().read(keylet::account(account_))->getFieldU32(sfOwnerCount);
         ownerCountAfter > ownerCountBefore)
diff --git a/src/libxrpl/tx/transactors/nft/NFTokenModify.cpp b/src/libxrpl/tx/transactors/nft/NFTokenModify.cpp
index a21196ff57..04264f0e5c 100644
--- a/src/libxrpl/tx/transactors/nft/NFTokenModify.cpp
+++ b/src/libxrpl/tx/transactors/nft/NFTokenModify.cpp
@@ -1,3 +1,12 @@
+/** @file
+ *  Implementation of the `NFTokenModify` transactor, which updates the
+ *  metadata URI of a mutable NFT without burning and re-minting it.
+ *
+ *  Heavy lifting is delegated to `nft::changeTokenURI` in
+ *  `NFTokenHelpers.cpp`; this file is responsible only for the three-phase
+ *  validation pipeline (`preflight` → `preclaim` → `doApply`) and the
+ *  no-op invariant hooks.
+ */
 #include <xrpl/tx/transactors/nft/NFTokenModify.h>
 
 #include <xrpl/basics/base_uint.h>
@@ -42,11 +51,9 @@ NFTokenModify::preclaim(PreclaimContext const& ctx)
     if (!nft::findToken(ctx.view, owner, ctx.tx[sfNFTokenID]))
         return tecNO_ENTRY;
 
-    // Check if the NFT is mutable
     if ((nft::getFlags(ctx.tx[sfNFTokenID]) & nft::kFLAG_MUTABLE) == 0)
         return tecNO_PERMISSION;
 
-    // Verify permissions for the issuer
     if (AccountID const issuer = nft::getIssuer(ctx.tx[sfNFTokenID]); issuer != account)
     {
         auto const sle = ctx.view.read(keylet::account(issuer));
diff --git a/src/libxrpl/tx/transactors/oracle/OracleDelete.cpp b/src/libxrpl/tx/transactors/oracle/OracleDelete.cpp
index 99f2a14900..b58ada8a70 100644
--- a/src/libxrpl/tx/transactors/oracle/OracleDelete.cpp
+++ b/src/libxrpl/tx/transactors/oracle/OracleDelete.cpp
@@ -1,3 +1,11 @@
+/** @file
+ *  Implementation of the `OracleDelete` transactor (XLS-47d).
+ *
+ *  Removes a Price Oracle (`ltORACLE`) ledger object, reverting the owner
+ *  reserve that was allocated when the oracle was created by `OracleSet`.
+ *  The `deleteOracle` static helper is also the entry point used by
+ *  `AccountDelete` when sweeping owned objects during account removal.
+ */
 #include <xrpl/tx/transactors/oracle/OracleDelete.h>
 
 #include <xrpl/basics/Log.h>
@@ -17,12 +25,25 @@
 
 namespace xrpl {
 
+/** Unconditionally succeeds.
+ *
+ *  A delete request has no stateless properties to validate — there are no
+ *  field ranges, array size limits, or flag combinations that can be checked
+ *  without ledger state. All meaningful validation is deferred to `preclaim`.
+ */
 NotTEC
 OracleDelete::preflight(PreflightContext const& ctx)
 {
     return tesSUCCESS;
 }
 
+/** Validates that the target oracle exists and is owned by the submitter.
+ *
+ *  The oracle keylet is derived from `(account, sfOracleDocumentID)`, so a
+ *  successful read at that key is already proof of ownership; the explicit
+ *  `sfOwner` comparison that follows is a defensive invariant and is excluded
+ *  from coverage metrics (`LCOV_EXCL`).
+ */
 TER
 OracleDelete::preclaim(PreclaimContext const& ctx)
 {
@@ -39,7 +60,8 @@ OracleDelete::preclaim(PreclaimContext const& ctx)
 
     if (ctx.tx.getAccountID(sfAccount) != sle->getAccountID(sfOwner))
     {
-        // this can't happen because of the above check
+        // Unreachable: the oracle keylet embeds the account ID, so a
+        // successful read above is sufficient proof of ownership.
         // LCOV_EXCL_START
         JLOG(ctx.j.debug()) << "Oracle Delete: invalid account.";
         return tecINTERNAL;
@@ -48,6 +70,26 @@ OracleDelete::preclaim(PreclaimContext const& ctx)
     return tesSUCCESS;
 }
 
+/** Remove the oracle SLE from the ledger and reclaim the owner reserve.
+ *
+ *  Deletion must follow a strict three-step order:
+ *
+ *  1. `dirRemove` — reads `sfOwnerNode` (the directory page index stored by
+ *     `OracleSet::doApply` at creation time) from the live SLE. Erasing the
+ *     SLE first would lose this pointer, making O(1) directory removal
+ *     impossible. Failure here returns `tefBAD_LEDGER`, indicating ledger
+ *     corruption rather than a user error.
+ *
+ *  2. `adjustOwnerCount` — decrements the owner reserve by `-2` if the oracle
+ *     currently holds more than five `sfPriceDataSeries` entries, or by `-1`
+ *     otherwise. This mirrors the creation logic in `OracleSet::doApply` and
+ *     ensures the returned reserve equals the reserve originally taken.
+ *     The threshold is read from the live SLE rather than the transaction to
+ *     keep it immune to a caller passing a mismatched count.
+ *
+ *  3. `view.erase` — removes the SLE. After this call the SLE pointer is
+ *     invalid; no further reads from it are safe.
+ */
 TER
 OracleDelete::deleteOracle(
     ApplyView& view,
@@ -70,6 +112,8 @@ OracleDelete::deleteOracle(
     if (!sleOwner)
         return tecINTERNAL;  // LCOV_EXCL_LINE
 
+    // Mirror the +1/+2 increment in OracleSet::doApply: oracles with more than
+    // 5 price data series occupy two reserve slots, all others occupy one.
     auto const count = sle->getFieldArray(sfPriceDataSeries).size() > 5 ? -2 : -1;
 
     adjustOwnerCount(view, sleOwner, count, j);
@@ -79,6 +123,12 @@ OracleDelete::deleteOracle(
     return tesSUCCESS;
 }
 
+/** Fetches the oracle SLE and delegates to `deleteOracle`.
+ *
+ *  The `peek` returning null is unreachable under normal conditions because
+ *  `preclaim` already confirmed the oracle exists. The `tecINTERNAL` sentinel
+ *  is a fault-detection guard excluded from coverage metrics (`LCOV_EXCL`).
+ */
 TER
 OracleDelete::doApply()
 {
diff --git a/src/libxrpl/tx/transactors/oracle/OracleSet.cpp b/src/libxrpl/tx/transactors/oracle/OracleSet.cpp
index ea828256b8..93eb757463 100644
--- a/src/libxrpl/tx/transactors/oracle/OracleSet.cpp
+++ b/src/libxrpl/tx/transactors/oracle/OracleSet.cpp
@@ -1,3 +1,19 @@
+/** @file
+ *  Implementation of the `OracleSet` transactor (XLS-47d).
+ *
+ *  Creates or updates an `ltORACLE` ledger object that stores off-chain
+ *  price-feed data — base/quote token-pair prices, optional scaling factors,
+ *  and a freshness timestamp — making external market data available to
+ *  on-ledger consumers.
+ *
+ *  Two amendments alter behaviour:
+ *  - **`fixPriceOracleOrder`**: on creation, sorts `sfPriceDataSeries` into
+ *    a canonical lexicographic order so all validators produce identical SLEs
+ *    regardless of client submission order.
+ *  - **`fixIncludeKeyletFields`**: back-fills `sfOracleDocumentID` into
+ *    existing SLEs that predate the amendment, making the object
+ *    self-describing without external context.
+ */
 #include <xrpl/tx/transactors/oracle/OracleSet.h>
 
 #include <xrpl/basics/chrono.h>
@@ -29,6 +45,16 @@
 
 namespace xrpl {
 
+/** Extract a canonical `(BaseAsset, QuoteAsset)` currency pair from a
+ *  `sfPriceData` entry or equivalent STObject, for use as a map/set key.
+ *
+ *  Factoring this out ensures the key-extraction logic is identical in both
+ *  `preclaim` (validation) and `doApply` (mutation), preventing subtle
+ *  divergence bugs.
+ *
+ *  @param pair An STObject containing at least `sfBaseAsset` and `sfQuoteAsset`.
+ *  @return A `std::pair<Currency, Currency>` suitable for ordered containers.
+ */
 static inline std::pair<Currency, Currency>
 tokenPairKey(STObject const& pair)
 {
@@ -66,8 +92,6 @@ OracleSet::preclaim(PreclaimContext const& ctx)
     if (!sleSetter)
         return terNO_ACCOUNT;  // LCOV_EXCL_LINE
 
-    // lastUpdateTime must be within maxLastUpdateTimeDelta seconds
-    // of the last closed ledger
     using namespace std::chrono;
     std::size_t const closeTime =
         duration_cast<seconds>(ctx.view.header().closeTime.time_since_epoch()).count();
@@ -84,10 +108,9 @@ OracleSet::preclaim(PreclaimContext const& ctx)
     auto const sle =
         ctx.view.read(keylet::oracle(ctx.tx.getAccountID(sfAccount), ctx.tx[sfOracleDocumentID]));
 
-    // token pairs to add/update
+    // Entries with sfAssetPrice go into `pairs` (create/update); entries
+    // without sfAssetPrice go into `pairsDel` (deletion request).
     std::set<std::pair<Currency, Currency>> pairs;
-    // token pairs to delete. if a token pair doesn't include
-    // the price then this pair should be deleted from the object.
     std::set<std::pair<Currency, Currency>> pairsDel;
     for (auto const& entry : ctx.tx.getFieldArray(sfPriceDataSeries))
     {
@@ -112,9 +135,8 @@ OracleSet::preclaim(PreclaimContext const& ctx)
         }
     }
 
-    // Lambda is used to check if the value of a field, passed
-    // in the transaction, is equal to the value of that field
-    // in the on-ledger object.
+    // Returns true if `field` is absent from the transaction or matches the
+    // on-ledger value — enforcing immutability of sfProvider / sfAssetClass.
     auto isConsistent = [&ctx, &sle](auto const& field) {
         auto const v = ctx.tx[~field];
         return !v || *v == (*sle)[field];
@@ -123,10 +145,6 @@ OracleSet::preclaim(PreclaimContext const& ctx)
     std::int8_t adjustReserve = 0;
     if (sle)
     {
-        // update
-        // Account is the Owner since we can get sle
-
-        // lastUpdateTime must be more recent than the previous one
         if (ctx.tx[sfLastUpdateTime] <= (*sle)[sfLastUpdateTime])
             return tecINVALID_UPDATE_TIME;
 
@@ -157,8 +175,6 @@ OracleSet::preclaim(PreclaimContext const& ctx)
     }
     else
     {
-        // create
-
         if (!ctx.tx.isFieldPresent(sfProvider) || !ctx.tx.isFieldPresent(sfAssetClass))
             return temMALFORMED;
         adjustReserve = pairs.size() > 5 ? 2 : 1;
@@ -179,6 +195,18 @@ OracleSet::preclaim(PreclaimContext const& ctx)
     return tesSUCCESS;
 }
 
+/** Convenience wrapper around the ledger-helper `adjustOwnerCount` that
+ *  peeks the submitting account's SLE from `ctx` and delegates to the
+ *  standard helper.
+ *
+ *  The `false` return path is unreachable in practice: `preclaim` already
+ *  verified the account exists via `terNO_ACCOUNT`.
+ *
+ *  @param ctx   The apply context for the current transaction.
+ *  @param count Signed reserve-slot delta to apply (positive = increase).
+ *  @return `true` on success; `false` if the account SLE cannot be peeked
+ *      (dead code, annotated `LCOV_EXCL_LINE`).
+ */
 static bool
 adjustOwnerCount(ApplyContext& ctx, int count)
 {
@@ -191,6 +219,16 @@ adjustOwnerCount(ApplyContext& ctx, int count)
     return false;  // LCOV_EXCL_LINE
 }
 
+/** Apply the canonical `sfPriceData` inner-object SOTemplate to `obj`.
+ *
+ *  XRPL's serialization layer requires every inner object to declare its
+ *  field set via an `SOTemplate` before fields can be written to it.
+ *  Without this call, `setField*` operations on a freshly constructed
+ *  `STObject{sfPriceData}` would behave unpredictably.
+ *
+ *  @param obj A freshly constructed or pre-existing `STObject` that will
+ *      hold `sfPriceData` fields.  Modified in place.
+ */
 static void
 setPriceDataInnerObjTemplate(STObject& obj)
 {
@@ -215,12 +253,11 @@ OracleSet::doApply()
 
     if (auto sle = ctx_.view().peek(oracleID))
     {
-        // update
-        // the token pair that doesn't have their price updated will not
-        // include neither price nor scale in the updated PriceDataSeries
-
+        // Update path: build a keyed map of the current pairs, apply the
+        // transaction's deltas (delete / update-in-place / insert), then
+        // serialise the result back. Pairs not mentioned by this transaction
+        // carry over with their existing price and scale unchanged.
         std::map<std::pair<Currency, Currency>, STObject> pairs;
-        // collect current token pairs
         for (auto const& entry : sle->getFieldArray(sfPriceDataSeries))
         {
             STObject priceData{sfPriceData};
@@ -230,25 +267,21 @@ OracleSet::doApply()
             pairs.emplace(tokenPairKey(entry), std::move(priceData));
         }
         auto const oldCount = pairs.size() > 5 ? 2 : 1;
-        // update/add/delete pairs
         for (auto const& entry : ctx_.tx.getFieldArray(sfPriceDataSeries))
         {
             auto const key = tokenPairKey(entry);
             if (!entry.isFieldPresent(sfAssetPrice))
             {
-                // delete token pair
                 pairs.erase(key);
             }
             else if (auto iter = pairs.find(key); iter != pairs.end())
             {
-                // update the price
                 iter->second.setFieldU64(sfAssetPrice, entry.getFieldU64(sfAssetPrice));
                 if (entry.isFieldPresent(sfScale))
                     iter->second.setFieldU8(sfScale, entry.getFieldU8(sfScale));
             }
             else
             {
-                // add a token pair with the price
                 STObject priceData{sfPriceData};
                 populatePriceData(priceData, entry);
                 pairs.emplace(key, std::move(priceData));
@@ -276,8 +309,10 @@ OracleSet::doApply()
     }
     else
     {
-        // create
-
+        // Create path: allocate a new SLE, populate all fields, sort the
+        // sfPriceDataSeries canonically under fixPriceOracleOrder (pre-fix
+        // behaviour preserves raw transaction order for history consistency),
+        // insert into the owner directory, and increment the owner count.
         sle = std::make_shared<SLE>(oracleID);
         sle->setAccountID(sfOwner, ctx_.tx.getAccountID(sfAccount));
         if (ctx_.view().rules().enabled(fixIncludeKeyletFields))
diff --git a/src/libxrpl/tx/transactors/payment/DepositPreauth.cpp b/src/libxrpl/tx/transactors/payment/DepositPreauth.cpp
index 2e298a70d5..86c3b9e3cb 100644
--- a/src/libxrpl/tx/transactors/payment/DepositPreauth.cpp
+++ b/src/libxrpl/tx/transactors/payment/DepositPreauth.cpp
@@ -1,3 +1,19 @@
+/** @file
+ *  Implementation of the `DepositPreauth` transactor.
+ *
+ *  Manages `DepositPreauth` ledger entries, which form the allow-list that
+ *  permits specific accounts or credential-bearing parties to send payments
+ *  to an account that has enabled `lsfDepositAuth`. A single transaction
+ *  performs exactly one of four mutually exclusive operations selected by
+ *  whichever of `sfAuthorize`, `sfUnauthorize`, `sfAuthorizeCredentials`, or
+ *  `sfUnauthorizeCredentials` is present.
+ *
+ *  The credential-based operations are gated on `featureCredentials` and use
+ *  a canonically sorted representation of the credential set for both the
+ *  keylet derivation and ledger storage, ensuring order-independent lookups.
+ *
+ *  @see DepositPreauth.h for the class declaration and full interface docs.
+ */
 #include <xrpl/tx/transactors/payment/DepositPreauth.h>
 
 #include <xrpl/basics/Log.h>
@@ -98,7 +114,6 @@ DepositPreauth::preclaim(PreclaimContext const& ctx)
 {
     AccountID const account(ctx.tx[sfAccount]);
 
-    // Determine which operation we're performing: authorizing or unauthorizing.
     if (ctx.tx.isFieldPresent(sfAuthorize))
     {
         // Verify that the Authorize account is present in the ledger.
diff --git a/src/libxrpl/tx/transactors/payment/Payment.cpp b/src/libxrpl/tx/transactors/payment/Payment.cpp
index d7a1a63ef1..a732678500 100644
--- a/src/libxrpl/tx/transactors/payment/Payment.cpp
+++ b/src/libxrpl/tx/transactors/payment/Payment.cpp
@@ -1,3 +1,15 @@
+/**
+ * @file Payment.cpp
+ * @brief Implementation of the `ttPAYMENT` transactor.
+ *
+ * A single transaction type covers three structurally distinct execution paths:
+ * direct XRP-to-XRP transfers, direct MPToken (MPT) transfers (pre-`featureMPTokensV2`),
+ * and cross-currency / path-based payments routed through `path::RippleCalc`.
+ * The branching lives entirely in `doApply()`; the serialized transaction format
+ * is the same for all three cases.
+ *
+ * See `Payment.h` for the full class documentation and per-method contracts.
+ */
 #include <xrpl/tx/transactors/payment/Payment.h>
 
 #include <xrpl/basics/Log.h>
@@ -59,6 +71,21 @@ Payment::makeTxConsequences(PreflightContext const& ctx)
     return TxConsequences{ctx.tx, calculateMaxXRPSpend(ctx.tx)};
 }
 
+/**
+ * Computes the maximum amount the sender is willing to spend.
+ *
+ * When `sfSendMax` is present it is returned as-is. When it is absent
+ * and the destination asset is an XRP or MPT, the destination amount
+ * itself is the ceiling. For IOU destinations the amount is re-expressed
+ * with the *sender's* account as the issuer, because IOU trust lines are
+ * scoped to the issuer: the "same" currency from two different issuers is
+ * not fungible and must be tracked separately.
+ *
+ * @param account   The sending account, used to substitute the IOU issuer.
+ * @param dstAmount The requested destination amount (`sfAmount`).
+ * @param sendMax   The optional `sfSendMax` field from the transaction.
+ * @return The effective maximum source amount.
+ */
 STAmount
 getMaxSourceAmount(
     AccountID const& account,
@@ -187,8 +214,8 @@ Payment::preflight(PreflightContext const& ctx)
     }
     if (account == dstAccountID && equalTokens(srcAsset, dstAsset) && !hasPaths)
     {
-        // You're signing yourself a payment.
-        // If hasPaths is true, you might be trying some arbitrage.
+        // A self-payment with no paths is always redundant. With paths the
+        // sender may be attempting an arbitrage cycle, which is permitted.
         JLOG(j.trace()) << "Malformed transaction: "
                         << "Redundant payment from " << to_string(account)
                         << " to self without path for " << to_string(dstAsset);
@@ -196,35 +223,30 @@ Payment::preflight(PreflightContext const& ctx)
     }
     if (xrpDirect && hasMax)
     {
-        // Consistent but redundant transaction.
         JLOG(j.trace()) << "Malformed transaction: "
                         << "SendMax specified for XRP to XRP.";
         return temBAD_SEND_XRP_MAX;
     }
     if ((xrpDirect || (!mpTokensV2 && isDstMPT)) && hasPaths)
     {
-        // XRP is sent without paths.
         JLOG(j.trace()) << "Malformed transaction: "
                         << "Paths specified for XRP to XRP or MPT to MPT.";
         return temBAD_SEND_XRP_PATHS;
     }
     if (xrpDirect && partialPaymentAllowed)
     {
-        // Consistent but redundant transaction.
         JLOG(j.trace()) << "Malformed transaction: "
                         << "Partial payment specified for XRP to XRP.";
         return temBAD_SEND_XRP_PARTIAL;
     }
     if ((xrpDirect || (!mpTokensV2 && isDstMPT)) && limitQuality)
     {
-        // Consistent but redundant transaction.
         JLOG(j.trace()) << "Malformed transaction: "
                         << "Limit quality specified for XRP to XRP or MPT to MPT.";
         return temBAD_SEND_XRP_LIMIT;
     }
     if ((xrpDirect || (!mpTokensV2 && isDstMPT)) && !defaultPathsAllowed)
     {
-        // Consistent but redundant transaction.
         JLOG(j.trace()) << "Malformed transaction: "
                         << "No ripple direct specified for XRP to XRP or MPT to MPT.";
         return temBAD_SEND_XRP_NO_DIRECT;
@@ -310,7 +332,6 @@ Payment::checkPermission(ReadView const& view, STTx const& tx)
 TER
 Payment::preclaim(PreclaimContext const& ctx)
 {
-    // Ripple if source or destination is non-native or if there are paths.
     std::uint32_t const txFlags = ctx.tx.getFlags();
     bool const partialPaymentAllowed = (txFlags & tfPartialPayment) != 0u;
     auto const hasPaths = ctx.tx.isFieldPresent(sfPaths);
@@ -324,36 +345,31 @@ Payment::preclaim(PreclaimContext const& ctx)
 
     if (!sleDst)
     {
-        // Destination account does not exist.
         if (!dstAmount.native())
         {
             JLOG(ctx.j.trace()) << "Delay transaction: Destination account does not exist.";
 
-            // Another transaction could create the account and then this
-            // transaction would succeed.
+            // tec (not tem) because another transaction could create the
+            // account first, after which this one would succeed.
             return tecNO_DST;
         }
         if (ctx.view.open() && partialPaymentAllowed)
         {
-            // You cannot fund an account with a partial payment.
-            // Make retry work smaller, by rejecting this.
+            // Partial payments cannot create accounts; use tel (not tec) to
+            // make retry cheaper by dropping the transaction early.
             JLOG(ctx.j.trace()) << "Delay transaction: Partial payment not "
                                    "allowed to create account.";
 
-            // Another transaction could create the account and then this
-            // transaction would succeed.
             return telNO_DST_PARTIAL;
         }
         if (dstAmount < STAmount(ctx.view.fees().reserve))
         {
-            // accountReserve is the minimum amount that an account can have.
-            // Reserve is not scaled by load.
+            // Reserve is not load-scaled; dstAmount must meet the base
+            // account reserve to fund the new account root.
             JLOG(ctx.j.trace()) << "Delay transaction: Destination account does not exist. "
                                 << "Insufficent payment to create account.";
 
             // TODO: de-dupe
-            // Another transaction could create the account and then this
-            // transaction would succeed.
             return tecNO_DST_INSUF_XRP;
         }
     }
@@ -361,17 +377,15 @@ Payment::preclaim(PreclaimContext const& ctx)
         ((sleDst->getFlags() & lsfRequireDestTag) != 0u) &&
         !ctx.tx.isFieldPresent(sfDestinationTag))
     {
-        // The tag is basically account-specific information we don't
-        // understand, but we can require someone to fill it in.
-
-        // We didn't make this test for a newly-formed account because there's
-        // no way for this field to be set.
+        // The destination tag is opaque to the protocol but lets the
+        // destination owner require senders to provide one (e.g. for
+        // exchange sub-account routing). The check is skipped for
+        // newly-formed accounts because lsfRequireDestTag can't be set yet.
         JLOG(ctx.j.trace()) << "Malformed transaction: DestinationTag required.";
 
         return tecDST_TAG_NEEDED;
     }
 
-    // Payment with at least one intermediate step and uses transitive balances.
     if ((hasPaths || sendMax || !dstAmount.native()) && ctx.view.open())
     {
         STPathSet const& paths = ctx.tx.getFieldPathSet(sfPaths);
@@ -405,7 +419,6 @@ Payment::doApply()
 {
     auto const deliverMin = ctx_.tx[~sfDeliverMin];
 
-    // Ripple if source or destination is non-native or if there are paths.
     std::uint32_t const txFlags = ctx_.tx.getFlags();
     bool const partialPaymentAllowed = (txFlags & tfPartialPayment) != 0u;
     bool const limitQuality = (txFlags & tfLimitQuality) != 0u;
@@ -421,13 +434,11 @@ Payment::doApply()
     JLOG(j_.trace()) << "maxSourceAmount=" << maxSourceAmount.getFullText()
                      << " dstAmount=" << dstAmount.getFullText();
 
-    // Open a ledger for editing.
     auto const k = keylet::account(dstAccountID);
     SLE::pointer sleDst = view().peek(k);
 
     if (!sleDst)
     {
-        // Create the account.
         sleDst = std::make_shared<SLE>(k);
         sleDst->setAccountID(sfAccount, dstAccountID);
         sleDst->setFieldU32(sfSequence, view().seq());
@@ -437,9 +448,8 @@ Payment::doApply()
     }
     else
     {
-        // Tell the engine that we are intending to change the destination
-        // account.  The source account gets always charged a fee so it's always
-        // marked as modified.
+        // Mark the destination as modified so the engine tracks it; the source
+        // is always modified because a fee is always deducted.
         view().update(sleDst);
     }
 
@@ -450,14 +460,10 @@ Payment::doApply()
 
     if (ripple)
     {
-        // XRPL payment with at least one intermediate step and uses
-        // transitive balances.
-
-        // An account that requires authorization has two ways to get an
-        // IOU Payment in:
-        //  1. If Account == Destination, or
-        //  2. If Account is deposit preauthorized by destination.
-
+        // An account that requires deposit authorization has two ways to
+        // receive an IOU payment:
+        //  1. Account == Destination, or
+        //  2. Account is deposit-preauthorized by the destination.
         if (auto err = verifyDepositPreauth(
                 ctx_.tx, ctx_.view(), account_, dstAccountID, sleDst, ctx_.journal);
             !isTesSuccess(err))
@@ -483,9 +489,6 @@ Payment::doApply()
                 ctx_.tx[~sfDomainID],
                 ctx_.registry,
                 &rcInput);
-            // VFALCO NOTE We might not need to apply, depending
-            //             on the TER. But always applying *should*
-            //             be safe.
             pv.apply(ctx_.rawView());
         }
 
@@ -505,10 +508,9 @@ Payment::doApply()
 
         auto terResult = rc.result();
 
-        // Because of its overhead, if RippleCalc
-        // fails with a retry code, claim a fee
-        // instead. Maybe the user will be more
-        // careful with their path spec next time.
+        // Promote ter* retry codes to tecPATH_DRY so a fee is charged.
+        // Running the path engine has non-trivial cost; charging a fee
+        // discourages users from submitting poorly-constructed path specs.
         if (isTerRetry(terResult))
             terResult = tecPATH_DRY;
         return terResult;
@@ -535,35 +537,27 @@ Payment::doApply()
 
         auto const& issuer = mptIssue.getIssuer();
 
-        // Transfer rate
         Rate rate{QUALITY_ONE};
-        // Payment between the holders
         if (account_ != issuer && dstAccountID != issuer)
         {
-            // If globally/individually locked then
-            //   - can't send between holders
-            //   - holder can send back to issuer
-            //   - issuer can send to holder
+            // Freeze checks apply only between holders; issuers can always
+            // send to holders and holders can always return to issuers even
+            // when the issuance is globally or individually locked.
             if (isAnyFrozen(view(), {account_, dstAccountID}, mptIssue))
                 return tecLOCKED;
 
-            // Get the rate for a payment between the holders.
             rate = transferRate(view(), mptIssue.getMptID());
         }
 
-        // Amount to deliver.
         STAmount amountDeliver = dstAmount;
-        // Factor in the transfer rate.
-        // No rounding. It'll change once MPT integrated into DEX.
+        // No rounding here — rounding semantics will change once MPT is
+        // integrated into the DEX path engine.
         STAmount requiredMaxSourceAmount = multiply(dstAmount, rate);
 
-        // Send more than the account wants to pay or less than
-        // the account wants to deliver (if no SendMax).
-        // Adjust the amount to deliver.
         if (partialPaymentAllowed && requiredMaxSourceAmount > maxSourceAmount)
         {
             requiredMaxSourceAmount = maxSourceAmount;
-            // No rounding. It'll change once MPT integrated into DEX.
+            // No rounding — same note as above.
             amountDeliver = divide(maxSourceAmount, rate);
         }
 
@@ -577,9 +571,9 @@ Payment::doApply()
         {
             pv.apply(ctx_.rawView());
 
-            // If the actual amount delivered is different from the original
-            // amount due to partial payment or transfer fee, we need to update
-            // DeliveredAmount using the actual delivered amount
+            // Record actual delivered amount for the DeliveredAmount metadata
+            // field when it differs from sfAmount (partial pay or transfer fee).
+            // Gated on fixMPTDeliveredAmount, mirroring the IOU payment pattern.
             if (view().rules().enabled(fixMPTDeliveredAmount) && amountDeliver != dstAmount)
                 ctx_.deliver(amountDeliver);
         }
@@ -599,20 +593,13 @@ Payment::doApply()
     if (!sleSrc)
         return tefINTERNAL;  // LCOV_EXCL_LINE
 
-    // ownerCount is the number of entries in this ledger for this
-    // account that require a reserve.
     auto const ownerCount = sleSrc->getFieldU32(sfOwnerCount);
-
-    // This is the total reserve in drops.
     auto const reserve = view().fees().accountReserve(ownerCount);
 
-    // In a delegated payment, the fee payer is the delegated account,
-    // not the source account (account_).
+    // In a delegated payment the fee is charged to the delegate, not to
+    // account_. When account_ IS the fee payer it must also cover the fee
+    // amount, so minRequiredFunds is max(reserve, fee) rather than just reserve.
     bool const accountIsPayer = (ctx_.tx.getFeePayer() == account_);
-
-    // preFeeBalance_ is the balance on the source account (account_) BEFORE the fees
-    // were charged. If source account is the fee payer, it must also cover the fee.
-    // The final spend may use the reserve to cover fees.
     auto const minRequiredFunds =
         accountIsPayer ? std::max(reserve, ctx_.tx.getFieldAmount(sfFee).xrp()) : reserve;
 
@@ -635,28 +622,17 @@ Payment::doApply()
     if (isPseudoAccount(sleDst))
         return tecNO_PERMISSION;
 
-    // The source account does have enough money.  Make sure the
-    // source account has authority to deposit to the destination.
-    // An account that requires authorization has three ways to get an XRP
-    // Payment in:
-    //  1. If Account == Destination, or
-    //  2. If Account is deposit preauthorized by destination, or
-    //  3. If the destination's XRP balance is
-    //    a. less than or equal to the base reserve and
-    //    b. the deposit amount is less than or equal to the base reserve,
-    // then we allow the deposit.
+    // An account with lsfDepositAuth set has three ways to receive XRP:
+    //  1. Account == Destination, or
+    //  2. Account is deposit-preauthorized by the destination, or
+    //  3. Both the destination's current balance AND the payment amount
+    //     are ≤ the base reserve (Rule 3 / small-balance bypass).
     //
-    // Rule 3 is designed to keep an account from getting wedged
-    // in an unusable state if it sets the lsfDepositAuth flag and
-    // then consumes all of its XRP.  Without the rule if an
-    // account with lsfDepositAuth set spent all of its XRP, it
-    // would be unable to acquire more XRP required to pay fees.
-    //
-    // We choose the base reserve as our bound because it is
-    // a small number that seldom changes but is always sufficient
-    // to get the account un-wedged.
-
-    // Get the base reserve.
+    // Rule 3 prevents an account from becoming permanently wedged: if an
+    // account sets lsfDepositAuth and then spends all its XRP it would be
+    // unable to pay the fee required to unset the flag. The base reserve
+    // is the bound because it is small, seldom changes, and is always
+    // enough to fund the account-management transaction needed to recover.
     XRPAmount const dstReserve{view().fees().reserve};
 
     if (dstAmount > dstReserve || sleDst->getFieldAmount(sfBalance) > dstReserve)
@@ -667,11 +643,11 @@ Payment::doApply()
             return err;
     }
 
-    // Do the arithmetic for the transfer and make the ledger change.
     sleSrc->setFieldAmount(sfBalance, sleSrc->getFieldAmount(sfBalance) - dstAmount);
     sleDst->setFieldAmount(sfBalance, sleDst->getFieldAmount(sfBalance) + dstAmount);
 
-    // Re-arm the password change fee if we can and need to.
+    // Clear lsfPasswordSpent if set — legacy flag from the original
+    // password-based account creation flow; receiving XRP re-enables it.
     if ((sleDst->getFlags() & lsfPasswordSpent) != 0u)
         sleDst->clearFlag(lsfPasswordSpent);
 
diff --git a/src/xrpld/rpc/handlers/Handlers.h b/src/xrpld/rpc/handlers/Handlers.h
index 5a65185e6c..2da67487c0 100644
--- a/src/xrpld/rpc/handlers/Handlers.h
+++ b/src/xrpld/rpc/handlers/Handlers.h
@@ -752,12 +752,18 @@ doFeature(RPC::JsonContext&);
 json::Value
 doGetCounts(RPC::JsonContext&);
 
-/** Dump internal object state to the log (ADMIN).
+/** Serialize the application's `beast::PropertyStream` tree to JSON (ADMIN).
  *
- *  Triggers a diagnostic print of subsystem internals for offline analysis.
+ *  Returns a live introspection snapshot of every subsystem that has
+ *  registered itself as a `PropertyStream::Source` child of `Application`.
+ *  An optional dot-delimited path string in `params[0]` targets a specific
+ *  named sub-source; a missing or malformed parameter falls back silently to
+ *  the full tree. Always succeeds — never returns an error response.
  *
- *  @param context  RPC dispatch context for this call.
- *  @return JSON object confirming the print was triggered.
+ *  @param context  RPC dispatch context; optional path filter read from
+ *      `context.params[jss::params][0u]`.
+ *  @return JSON object containing the serialized property-stream tree.
+ *  @see JsonPropertyStream
  */
 json::Value
 doPrint(RPC::JsonContext&);
diff --git a/src/xrpld/rpc/handlers/admin/data/LedgerRequest.cpp b/src/xrpld/rpc/handlers/admin/data/LedgerRequest.cpp
index 4b15dbdcaf..2f652fa5db 100644
--- a/src/xrpld/rpc/handlers/admin/data/LedgerRequest.cpp
+++ b/src/xrpld/rpc/handlers/admin/data/LedgerRequest.cpp
@@ -8,10 +8,46 @@
 
 namespace xrpl {
 
-// {
-//   ledger_hash : <ledger>
-//   ledger_index : <ledger_index>
-// }
+/** @file
+ *  Admin RPC handler that locates a historical ledger by hash or sequence,
+ *  acquiring it from the network if it is not already cached locally.
+ */
+
+/** Implement the `ledger_request` admin RPC command.
+ *
+ *  Declares a heavy resource cost immediately, then delegates all ledger
+ *  resolution and acquisition logic to `RPC::getOrAcquireLedger()`. On
+ *  success the response contains a compact header-level JSON representation
+ *  of the ledger (no transactions, no state entries) together with the
+ *  `ledger_index` field.
+ *
+ *  Exactly one of `ledger_hash` (64-char hex string) or `ledger_index`
+ *  (positive integer) must be present in `params`; providing both or neither
+ *  is a `rpcBAD_PARAM` error. Shortcut strings (`current`, `closed`,
+ *  `validated`) are not accepted — this command targets specific historical
+ *  ledgers rather than live chain state.
+ *
+ *  When the requested ledger is not locally cached, `getOrAcquireLedger`
+ *  calls `InboundLedgers::acquire()` to initiate a peer-to-peer fetch. While
+ *  that fetch is in progress the returned error JSON contains an `"acquiring"`
+ *  field; callers should poll until the ledger becomes available.
+ *
+ *  @param context JSON-RPC context; `params` must contain exactly one of
+ *      `ledger_hash` or `ledger_index`.
+ *  @return On success, a JSON object with `ledger_index` and a nested
+ *      `ledger` block containing the ledger header fields. On failure, an
+ *      error JSON object; may include an `"acquiring"` field when a network
+ *      fetch is pending.
+ *  @note `context.loadType` is set to `kFEE_HEAVY_BURDEN_RPC` (weight 3000)
+ *      before any work is done so the resource manager can rate-limit or
+ *      deprioritize the caller regardless of whether the call ultimately
+ *      triggers a network fetch.
+ *  @note For the index-based path, the node's validated ledger must not be
+ *      stale (older than `Tuning::kMAX_VALIDATED_LEDGER_AGE`); API v1 returns
+ *      `rpcNO_CURRENT` on staleness, API v2+ returns `rpcNOT_SYNCED`.
+ *  @note Non-admin callers receive an HTTP 403 response rather than a JSON
+ *      error; the result object will be null in that case.
+ */
 json::Value
 doLedgerRequest(RPC::JsonContext& context)
 {
diff --git a/src/xrpld/rpc/handlers/admin/keygen/ValidationCreate.cpp b/src/xrpld/rpc/handlers/admin/keygen/ValidationCreate.cpp
index 0849bad944..9ed344fb56 100644
--- a/src/xrpld/rpc/handlers/admin/keygen/ValidationCreate.cpp
+++ b/src/xrpld/rpc/handlers/admin/keygen/ValidationCreate.cpp
@@ -1,3 +1,8 @@
+/** @file
+ *  Implements the `validation_create` admin RPC command, which generates a
+ *  secp256k1 key pair for use as a validator's signing identity.
+ */
+
 #include <xrpld/rpc/Context.h>
 
 #include <xrpl/json/json_value.h>
@@ -14,6 +19,20 @@
 
 namespace xrpl {
 
+/** Resolve the seed for validator key generation from RPC params.
+ *
+ *  If `params` contains a `secret` field, interprets it via
+ *  `parseGenericSeed()`, which accepts Base58 family seeds, passphrase
+ *  strings (hashed via SHA-512 Half to 128 bits), and RFC 1751 mnemonic
+ *  word lists. If `secret` is absent, generates 128 bits of
+ *  cryptographically secure random entropy via `randomSeed()`.
+ *
+ *  @param params The JSON request parameters object.
+ *  @return The resolved `Seed` on success, or `std::nullopt` if `secret`
+ *      was provided but could not be parsed by `parseGenericSeed()`.
+ *  @note The `Seed` destructor zeroes its 16-byte buffer, so key material
+ *      does not linger in memory after the returned object is destroyed.
+ */
 static std::optional<Seed>
 validationSeed(json::Value const& params)
 {
@@ -23,12 +42,37 @@ validationSeed(json::Value const& params)
     return parseGenericSeed(params[jss::secret].asString());
 }
 
-// {
-//   secret: <string>   // optional
-// }
-//
-// This command requires Role::ADMIN access because it makes
-// no sense to ask an untrusted server for this.
+/** Handle the `validation_create` RPC command.
+ *
+ *  Generates a secp256k1 key pair suitable for use as a validator's signing
+ *  identity. The returned object contains four fields covering the full range
+ *  of operational needs:
+ *
+ *  - `validation_public_key` — Base58 `NodePublic` token; published in UNLs
+ *    and trusted by peers during consensus.
+ *  - `validation_private_key` — Base58 `NodePrivate` token; stored locally
+ *    to sign validation messages.
+ *  - `validation_seed` — Base58 `FamilySeed` token; used in the
+ *    `[validation_seed]` config entry (older deployment style).
+ *  - `validation_key` — RFC 1751 mnemonic; human-readable seed backup.
+ *
+ *  When `secret` is omitted, a random seed is generated. When `secret` is
+ *  provided, it is parsed via `parseGenericSeed()` (Base58, passphrase, or
+ *  RFC 1751). The `NodePublic`/`NodePrivate` token types are structurally
+ *  distinct from `AccountPublic`/`AccountPrivate`, making it impossible at
+ *  the Base58 layer to confuse a validator key for an account key.
+ *
+ *  @param context The RPC dispatch context; `context.params` may contain an
+ *      optional `secret` field (string).
+ *  @return A JSON object with the four key-material fields on success, or an
+ *      `rpcBAD_SEED` error object if the supplied `secret` could not be
+ *      parsed.
+ *  @note This command is restricted to `Role::ADMIN`. Asking an untrusted
+ *      server to generate a validator seed would allow that server to log
+ *      or substitute a seed it controls, subverting the validator's identity.
+ *  @see doWalletPropose() for account key generation (supports ed25519,
+ *      entropy warnings, and account ID derivation).
+ */
 json::Value
 doValidationCreate(RPC::JsonContext& context)
 {
diff --git a/src/xrpld/rpc/handlers/admin/keygen/WalletPropose.cpp b/src/xrpld/rpc/handlers/admin/keygen/WalletPropose.cpp
index c783319049..b894de801c 100644
--- a/src/xrpld/rpc/handlers/admin/keygen/WalletPropose.cpp
+++ b/src/xrpld/rpc/handlers/admin/keygen/WalletPropose.cpp
@@ -1,3 +1,10 @@
+/** @file
+ *  Implements the `wallet_propose` admin RPC command.
+ *
+ *  Generates a complete XRPL account identity — seed, key pair, and account
+ *  address — from a caller-supplied or randomly-generated seed. Exposed only
+ *  to admin-role clients; never reachable by untrusted users.
+ */
 #include <xrpld/rpc/handlers/admin/keygen/WalletPropose.h>
 
 #include <xrpld/rpc/Context.h>
@@ -22,12 +29,23 @@
 
 namespace xrpl {
 
+/** Estimate the Shannon entropy of a string in bits.
+ *
+ *  Computes the per-symbol Shannon entropy from character frequencies and
+ *  multiplies by the string length to yield a total bit estimate. The result
+ *  is floored to be conservative — callers use this to gate brute-force
+ *  vulnerability warnings, so over-estimating entropy would suppress a
+ *  legitimate warning.
+ *
+ *  @param input The string whose entropy is estimated.
+ *  @return Estimated entropy in bits, floored to the nearest integer.
+ *  @note This is a statistical estimate, not a cryptographic strength
+ *      measurement. It is only meaningful for human-chosen passphrases;
+ *      a randomly-generated seed will always score well regardless.
+ */
 double
 estimateEntropy(std::string const& input)
 {
-    // First, we calculate the Shannon entropy. This gives
-    // the average number of bits per symbol that we would
-    // need to encode the input.
     std::map<int, double> freq;
 
     for (auto const& c : input)
@@ -42,21 +60,65 @@ estimateEntropy(std::string const& input)
         se += (x)*log2(x);
     }
 
-    // We multiply it by the length, to get an estimate of
-    // the number of bits in the input. We floor because it
-    // is better to be conservative.
+    // Floor because it is better to be conservative when warning about
+    // low-entropy passphrases.
     return std::floor(-se * input.length());
 }
 
-// {
-//  passphrase: <string>
-// }
+/** RPC dispatch entry point for the `wallet_propose` command.
+ *
+ *  Extracts the request parameters from the JSON context and delegates to
+ *  `walletPropose()`. Separating dispatch from logic allows the core
+ *  function to be called directly in tests without a full RPC context.
+ *
+ *  Accepts an optional `passphrase`, `seed`, or `seed_hex` field (mutually
+ *  exclusive); and an optional `key_type` ("secp256k1" or "ed25519").
+ *
+ *  @param context The RPC dispatch context carrying `params`.
+ *  @return A JSON object with key-generation results, or an error object.
+ */
 json::Value
 doWalletPropose(RPC::JsonContext& context)
 {
     return walletPropose(context.params);
 }
 
+/** Generate a complete XRPL account identity from parameters.
+ *
+ *  Resolves a seed via a priority-ordered chain: XrplLib-encoded Ed25519 seed
+ *  detection (in `passphrase` or `seed` fields) → `getSeedFromRPC()` for
+ *  explicit `passphrase` / `seed` / `seed_hex` → `randomSeed()` as the
+ *  fallback. Key type defaults to `secp256k1` for historical compatibility
+ *  when none is specified.
+ *
+ *  On success, returns a JSON object with seven fields:
+ *  - `master_seed`     — base58-encoded seed (canonical backup format)
+ *  - `master_seed_hex` — raw hex of the seed bytes
+ *  - `master_key`      — RFC 1751 mnemonic encoding
+ *  - `account_id`      — base58check account address
+ *  - `public_key`      — base58-encoded public key with AccountPublic prefix
+ *  - `public_key_hex`  — raw hex public key
+ *  - `key_type`        — resolved algorithm name ("secp256k1" or "ed25519")
+ *
+ *  A `warning` field is appended when a user-supplied passphrase is detected
+ *  that is not itself an encoding of the seed: a strong warning when entropy
+ *  is below 80 bits, and a softer advisory otherwise (any brain-wallet
+ *  derivation is weaker than a random seed). The warning is suppressed when
+ *  the passphrase matches the seed's own 1751, base58, or hex encoding, and
+ *  when a XrplLib-encoded seed is detected.
+ *
+ *  @param params JSON object containing optional fields: `key_type`,
+ *      `passphrase`, `seed`, `seed_hex`. The three seed-input fields are
+ *      mutually exclusive; supplying more than one yields an error from
+ *      `getSeedFromRPC()`.
+ *  @return A JSON result object on success, or a JSON error object on failure.
+ *  @note Supplying a XrplLib-encoded Ed25519 seed together with
+ *      `key_type: "secp256k1"` returns `rpcBAD_SEED` rather than silently
+ *      deriving the wrong key. XrplLib seeds are unambiguously Ed25519.
+ *  @see walletPropose() is called directly by `KeyGeneration_test.cpp` to
+ *      validate known constant vectors for both key types and both warning
+ *      tiers.
+ */
 json::Value
 walletPropose(json::Value const& params)
 {
@@ -77,9 +139,10 @@ walletPropose(json::Value const& params)
             return rpcError(RpcInvalidParams);
     }
 
-    // XrplLib encodes seed used to generate an Ed25519 wallet in a
-    // non-standard way. While we never encode seeds that way, we try
-    // to detect such keys to avoid user confusion.
+    // XrplLib encodes seeds for Ed25519 wallets with a non-standard base58
+    // prefix (0xE1 0x4B), producing an 18-byte form rippled never emits.
+    // Detect it in passphrase/seed fields first so we can enforce the
+    // Ed25519-only constraint and avoid confusing users who migrate keys.
     {
         if (params.isMember(jss::passphrase))
         {
@@ -140,17 +203,20 @@ walletPropose(json::Value const& params)
     obj[jss::key_type] = to_string(*keyType);
     obj[jss::public_key_hex] = strHex(publicKey);
 
-    // If a passphrase was specified, and it was hashed and used as a seed
-    // run a quick entropy check and add an appropriate warning, because
-    // "brain wallets" can be easily attacked.
+    // Warn about brain-wallet weakness when a user passphrase was used.
+    // Skip if the passphrase is just an alternate encoding of the seed
+    // itself — the user is passing a valid seed as a string, not inventing
+    // a memorable phrase, so entropy is already adequate.
     if (!libSeed && params.isMember(jss::passphrase))
     {
         auto const passphrase = params[jss::passphrase].asString();
 
         if (passphrase != seed1751 && passphrase != seedBase58 && passphrase != seedHex)
         {
-            // 80 bits of entropy isn't bad, but it's better to
-            // err on the side of caution and be conservative.
+            // 80 bits is the threshold: below it the passphrase is
+            // acutely vulnerable to brute-force; at or above it we still
+            // warn because any deterministic derivation is weaker than a
+            // truly random seed.
             if (estimateEntropy(passphrase) < 80.0)
             {
                 obj[jss::warning] =
diff --git a/src/xrpld/rpc/handlers/admin/keygen/WalletPropose.h b/src/xrpld/rpc/handlers/admin/keygen/WalletPropose.h
index 7ee302a014..a8880559e4 100644
--- a/src/xrpld/rpc/handlers/admin/keygen/WalletPropose.h
+++ b/src/xrpld/rpc/handlers/admin/keygen/WalletPropose.h
@@ -4,6 +4,41 @@
 
 namespace xrpl {
 
+/** Generate a complete XRPL account identity from caller-supplied or random seed material.
+ *
+ *  Implements the core logic of the `wallet_propose` admin RPC command without
+ *  requiring a full RPC dispatch context, so it can be called directly from
+ *  unit tests. The companion `doWalletPropose()` adapter in `WalletPropose.cpp`
+ *  simply forwards `context.params` here.
+ *
+ *  Seed resolution order:
+ *  1. XrplLib-encoded Ed25519 seed detected in `passphrase` or `seed` fields
+ *     (non-standard 0xE1 0x4B base58 prefix). Forces `key_type` to `ed25519`;
+ *     returns `rpcBAD_SEED` if the caller explicitly requested a conflicting type.
+ *  2. Explicit `passphrase`, `seed`, or `seed_hex` field, parsed via
+ *     `getSeedFromRPC()`. The three fields are mutually exclusive.
+ *  3. `randomSeed()` — used when no seed material is provided at all.
+ *
+ *  Key type defaults to `secp256k1` when unspecified.
+ *
+ *  On success the returned JSON object contains: `master_seed` (base58),
+ *  `master_seed_hex`, `master_key` (RFC 1751 mnemonic), `account_id` (base58check
+ *  address), `public_key` (base58 with AccountPublic prefix), `public_key_hex`,
+ *  and `key_type`. A `warning` field is appended when the caller supplied a
+ *  passphrase that is not itself an encoding of the seed: strong ("vulnerable to
+ *  brute-force attacks") when Shannon-entropy estimate is below 80 bits, softer
+ *  advisory otherwise.
+ *
+ *  @param params JSON object with optional fields: `key_type` ("secp256k1" or
+ *      "ed25519"), `passphrase`, `seed`, `seed_hex`. Providing more than one of
+ *      the three seed-input fields yields an error from `getSeedFromRPC()`.
+ *  @return A JSON result object on success, or a JSON error object on failure.
+ *  @note The passphrase entropy warning is suppressed when the passphrase value
+ *      matches the seed's own base58, hex, or RFC 1751 encoding — the caller is
+ *      presenting an existing seed as a string, not a brain-wallet phrase.
+ *  @see `KeyGeneration_test.cpp` exercises this function directly with known
+ *      constant vectors for both key types and both warning tiers.
+ */
 json::Value
 walletPropose(json::Value const& params);
 
diff --git a/src/xrpld/rpc/handlers/admin/log/LogLevel.cpp b/src/xrpld/rpc/handlers/admin/log/LogLevel.cpp
index 1ff5aa1a27..03ba1eaab5 100644
--- a/src/xrpld/rpc/handlers/admin/log/LogLevel.cpp
+++ b/src/xrpld/rpc/handlers/admin/log/LogLevel.cpp
@@ -1,3 +1,12 @@
+/** @file
+ *  Implements `doLogLevel`, the handler for the `log_level` admin RPC command.
+ *
+ *  Operators use this command at runtime to query or change log verbosity
+ *  thresholds across all logging partitions — or a single named one — without
+ *  restarting the node.  The companion command `logrotate` (implemented in
+ *  `LogRotate.cpp`) completes the set of runtime log-management primitives.
+ */
+
 #include <xrpld/app/main/Application.h>
 #include <xrpld/rpc/Context.h>
 
@@ -15,13 +24,43 @@
 
 namespace xrpl {
 
+/** Query or set runtime log-verbosity thresholds (ADMIN).
+ *
+ *  Dispatches across three modes based on the shape of the request:
+ *
+ *  - **Query** (no `severity` field): returns a `levels` JSON object whose
+ *    `base` key holds the global threshold and whose remaining keys are the
+ *    per-partition thresholds for every named subsystem (e.g. `Ledger`,
+ *    `Consensus`).
+ *  - **Global set** (`severity` only, no `partition`): sets the global base
+ *    threshold; all partitions without an individual override are filtered at
+ *    this level from that point forward.
+ *  - **Partition set** (`severity` + `partition`): sets the threshold on a
+ *    single named partition.  The name `"base"` (case-insensitive) is an alias
+ *    for the global threshold and is handled identically to the global-set
+ *    mode.
+ *
+ *  **Severity conversion:** the raw string is validated by `Logs::fromString()`
+ *  and converted to `beast::severities::Severity` via `Logs::toSeverity()`.
+ *  An unrecognised string causes an immediate `rpcINVALID_PARAMS` error rather
+ *  than silently clamping to a default.
+ *
+ *  @param context  RPC dispatch context carrying `params` and `app` references.
+ *  @return In query mode, a JSON object with a `levels` key.  In set modes, an
+ *      empty JSON object on success, or an `rpcINVALID_PARAMS` error object for
+ *      an unrecognised severity string.
+ *
+ *  @note Unknown partition names are silently accepted: `Logs::get()` creates a
+ *      new sink on demand, so a misspelled partition name creates an isolated
+ *      threshold entry rather than returning an error.
+ *  @note The `"base"` partition alias comparison uses `boost::iequals`, matching
+ *      the case-insensitive storage key comparison used internally by `Logs`.
+ */
 json::Value
 doLogLevel(RPC::JsonContext& context)
 {
-    // log_level
     if (not context.params.isMember(jss::severity))
     {
-        // get log severities
         json::Value ret(json::ValueType::Object);
         json::Value lev(json::ValueType::Object);
 
@@ -40,18 +79,14 @@ doLogLevel(RPC::JsonContext& context)
     if (not severity.has_value())
         return rpcError(RpcInvalidParams);
 
-    // log_level severity
     if (not context.params.isMember(jss::partition))
     {
-        // set base log threshold
         context.app.getLogs().threshold(*severity);
         return json::ValueType::Object;
     }
 
-    // log_level partition severity base?
     if (context.params.isMember(jss::partition))
     {
-        // set partition threshold
         std::string const partition(context.params[jss::partition].asString());
 
         if (boost::iequals(partition, "base"))
diff --git a/src/xrpld/rpc/handlers/admin/log/LogRotate.cpp b/src/xrpld/rpc/handlers/admin/log/LogRotate.cpp
index 5f5c3e64df..20b62913d8 100644
--- a/src/xrpld/rpc/handlers/admin/log/LogRotate.cpp
+++ b/src/xrpld/rpc/handlers/admin/log/LogRotate.cpp
@@ -1,3 +1,13 @@
+/** @file
+ *  Implements `doLogRotate`, the handler for the `logrotate` admin RPC command.
+ *
+ *  Rotating the log file allows external tools such as `logrotate(8)` to rename
+ *  or truncate the on-disk file while the process keeps running; the handler
+ *  closes and reopens the file descriptor so subsequent writes go to the new
+ *  path.  The companion command `log_level` (implemented in `LogLevel.cpp`)
+ *  completes the set of runtime log-management primitives.
+ */
+
 #include <xrpld/app/main/Application.h>
 #include <xrpld/rpc/Context.h>
 #include <xrpld/rpc/detail/Handler.h>
@@ -8,6 +18,23 @@
 
 namespace xrpl {
 
+/** Rotate both the performance log and the application log (ADMIN).
+ *
+ *  Closes and reopens the application log file at its configured path, which
+ *  is the standard interop pattern for `logrotate(8)`: the external tool renames
+ *  or truncates the file first, then signals the process to reopen it.  The
+ *  performance log is rotated via `PerfLog::rotate()` beforehand.
+ *
+ *  No request parameters are consumed; the handler delegates entirely to the
+ *  two logging subsystems and returns their status message.
+ *
+ *  @param context  RPC dispatch context carrying the `app` reference.
+ *  @return A JSON object whose value is the status string returned by
+ *      `Logs::rotate()` (e.g., `"The log file has been rotated"`).
+ *
+ *  @note Access is enforced by the RPC framework before this function is
+ *      called; the handler itself performs no role or condition checks.
+ */
 json::Value
 doLogRotate(RPC::JsonContext& context)
 {
diff --git a/src/xrpld/rpc/handlers/admin/peer/Connect.cpp b/src/xrpld/rpc/handlers/admin/peer/Connect.cpp
index 1d5e537aba..4df8b89cf6 100644
--- a/src/xrpld/rpc/handlers/admin/peer/Connect.cpp
+++ b/src/xrpld/rpc/handlers/admin/peer/Connect.cpp
@@ -1,3 +1,8 @@
+/** @file
+ *  Implements the `connect` admin RPC handler, which instructs the node to
+ *  open an outbound peer connection to a caller-specified IP address and port.
+ */
+
 #include <xrpld/app/main/Application.h>
 #include <xrpld/core/Config.h>
 #include <xrpld/overlay/Overlay.h>
@@ -15,10 +20,31 @@
 
 namespace xrpl {
 
-// {
-//   ip: <string>,
-//   port: <number>
-// }
+/** Initiate a manual outbound peer connection (ADMIN).
+ *
+ *  Validates the caller-supplied `ip` and optional `port`, then delegates to
+ *  `Overlay::connect()`, which is non-blocking — the TCP handshake proceeds
+ *  asynchronously and the response is returned immediately.
+ *
+ *  Request fields:
+ *  - `ip`   (string, required) — IPv4 or IPv6 address of the target peer.
+ *  - `port` (integer, optional) — target port; defaults to `kDEFAULT_PEER_PORT`
+ *      (2459) when absent.
+ *
+ *  @param context  RPC dispatch context carrying the request parameters and
+ *      application references.
+ *  @return A JSON string value confirming the connection attempt, or a JSON
+ *      error object if validation fails.
+ *
+ *  @note Returns `rpcNOT_SYNCED` when the node is running in standalone mode,
+ *      where peer connections are not meaningful.
+ *  @note If `ip` does not parse as a valid address, `Overlay::connect()` is
+ *      silently skipped — the response still reads "attempting connection …"
+ *      with no indication that the address was rejected. DNS names are not
+ *      resolved.
+ *  @note The port value is not range-checked; values outside `[1, 65535]` are
+ *      passed through to the overlay unchanged.
+ */
 // XXX Might allow domain for manual connections.
 json::Value
 doConnect(RPC::JsonContext& context)
diff --git a/src/xrpld/rpc/handlers/admin/peer/PeerReservationsAdd.cpp b/src/xrpld/rpc/handlers/admin/peer/PeerReservationsAdd.cpp
index 23b0d094b4..ab92e49142 100644
--- a/src/xrpld/rpc/handlers/admin/peer/PeerReservationsAdd.cpp
+++ b/src/xrpld/rpc/handlers/admin/peer/PeerReservationsAdd.cpp
@@ -14,6 +14,42 @@
 
 namespace xrpl {
 
+/** Insert or replace a peer reservation (admin: `peer_reservations_add`).
+ *
+ *  A peer reservation gives a specific XRPL node a guaranteed inbound
+ *  connection slot in the overlay, even when the general pool is full.
+ *  This handler is the write path: it validates the caller-supplied node
+ *  public key, optionally records a human-readable description, and
+ *  delegates to `PeerReservationTable::insertOrAssign` which updates both
+ *  the in-memory registry and the backing SQL table under a single lock.
+ *
+ *  Validation is performed in three layers before any state is mutated:
+ *  1. Presence — `public_key` must be present.
+ *  2. Type — `public_key` (and `description`, if present) must be a string.
+ *  3. Cryptographic parse — `public_key` must decode as a NodePublic base58
+ *     key via `parseBase58<PublicKey>`. Only base58 is accepted (not hex),
+ *     as a deliberate design choice to eliminate ambiguous-format bugs.
+ *
+ *  The response object is always a JSON `{}`. If a prior reservation existed
+ *  for the same node key it is returned under `jss::previous` (serialized by
+ *  `PeerReservation::toJson()`), giving callers idempotent-safe confirmation
+ *  of what was displaced. A fresh insert returns an empty object with no
+ *  `previous` field.
+ *
+ *  @note The inline parameter-extraction code intentionally avoids a shared
+ *      helper that returns `Json::Value`. Copying whole JSON objects to
+ *      propagate error codes is expensive and clutters call sites. The right
+ *      abstraction is an error monad (`std::expected`-style
+ *      `optional<T, Error>`); the code uses direct early-returns as the
+ *      practical stand-in until such an abstraction is adopted.
+ *
+ *  @param context  RPC dispatch context carrying `params` and the live
+ *      `Application` reference.
+ *  @return A JSON object, optionally containing a `"previous"` field with
+ *      the reservation that was replaced.
+ *  @throws soci::soci_error  Propagated from `PeerReservationTable::insertOrAssign`
+ *      if the underlying SQL write fails.
+ */
 json::Value
 doPeerReservationsAdd(RPC::JsonContext& context)
 {
@@ -22,24 +58,9 @@ doPeerReservationsAdd(RPC::JsonContext& context)
     if (!params.isMember(jss::public_key))
         return RPC::missingFieldError(jss::public_key);
 
-    // Returning JSON from every function ruins any attempt to encapsulate
-    // the pattern of "get field F as type T, and diagnose an error if it is
-    // missing or malformed":
-    // - It is costly to copy whole JSON objects around just to check whether an
-    //   error code is present.
-    // - It is not as easy to read when cluttered by code to pack and unpack the
-    //   JSON object.
-    // - It is not as easy to write when you have to include all the packing and
-    //   unpacking code.
-    // Exceptions would be easier to use, but have a terrible cost for control
-    // flow. An error monad is purpose-built for this situation; it is
-    // essentially an optional (the "maybe monad" in Haskell) with a non-unit
-    // type for the failure case to capture more information.
     if (!params[jss::public_key].isString())
         return RPC::expectedFieldError(jss::public_key, "a string");
 
-    // Same for the pattern of "if field F is present, make sure it has type T
-    // and get it".
     std::string desc;
     if (params.isMember(jss::description))
     {
@@ -48,8 +69,6 @@ doPeerReservationsAdd(RPC::JsonContext& context)
         desc = params[jss::description].asString();
     }
 
-    // channel_verify takes a key in both base58 and hex.
-    // @nikb prefers that we take only base58.
     std::optional<PublicKey> optPk =
         parseBase58<PublicKey>(TokenType::NodePublic, params[jss::public_key].asString());
     if (!optPk)
diff --git a/src/xrpld/rpc/handlers/admin/peer/PeerReservationsDel.cpp b/src/xrpld/rpc/handlers/admin/peer/PeerReservationsDel.cpp
index 40042a0390..7c343d87d8 100644
--- a/src/xrpld/rpc/handlers/admin/peer/PeerReservationsDel.cpp
+++ b/src/xrpld/rpc/handlers/admin/peer/PeerReservationsDel.cpp
@@ -12,12 +12,45 @@
 
 namespace xrpl {
 
+/** Remove a peer reservation by node public key (admin: `peer_reservations_del`).
+ *
+ *  Deletes the reserved peer slot held by the node identified by `public_key`,
+ *  freeing that slot to be filled by the general overlay pool. Both the
+ *  in-memory registry and the backing SQL table are updated atomically under
+ *  `PeerReservationTable`'s internal mutex, so the deletion is immediately
+ *  visible to concurrent peer-connection logic and survives a restart.
+ *
+ *  Validation is performed in three layers before any state is mutated:
+ *  1. Presence — `public_key` must be present in `params`.
+ *  2. Type — `public_key` must be a JSON string.
+ *  3. Cryptographic parse — `public_key` must decode as a NodePublic base58
+ *     key via `parseBase58<PublicKey>(TokenType::NodePublic, ...)`. The
+ *     `NodePublic` token type is required to prevent account keys or other
+ *     base58-encoded types from being accepted.
+ *
+ *  If the key is valid but no reservation existed, the operation is a no-op
+ *  and the response is an empty JSON object — the handler does not treat a
+ *  missing reservation as an error, making it safe to call idempotently from
+ *  scripts or retry loops.
+ *
+ *  @note Parameter extraction is duplicated from `doPeerReservationsAdd` by
+ *      design. A shared helper returning `Json::Value` would copy whole error
+ *      objects on failure; the right abstraction is an error monad
+ *      (`std::expected`-style), used here as explicit early-returns until
+ *      that abstraction is adopted.
+ *
+ *  @param context  RPC dispatch context carrying `params` and the live
+ *      `Application` reference.
+ *  @return A JSON object, optionally containing a `"previous"` field with
+ *      the reservation that was removed (serialized by
+ *      `PeerReservation::toJson()`). Returns an empty object `{}` when no
+ *      reservation existed for the given key.
+ */
 json::Value
 doPeerReservationsDel(RPC::JsonContext& context)
 {
     auto const& params = context.params;
 
-    // We repeat much of the parameter parsing from `doPeerReservationsAdd`.
     if (!params.isMember(jss::public_key))
         return RPC::missingFieldError(jss::public_key);
     if (!params[jss::public_key].isString())
diff --git a/src/xrpld/rpc/handlers/admin/peer/PeerReservationsList.cpp b/src/xrpld/rpc/handlers/admin/peer/PeerReservationsList.cpp
index 95da4c8567..79bb1f93aa 100644
--- a/src/xrpld/rpc/handlers/admin/peer/PeerReservationsList.cpp
+++ b/src/xrpld/rpc/handlers/admin/peer/PeerReservationsList.cpp
@@ -6,12 +6,27 @@
 
 namespace xrpl {
 
+/** Return a snapshot of all configured peer reservations (ADMIN).
+ *
+ *  Accepts no input parameters. Delegates to `PeerReservationTable::list()`,
+ *  which performs a mutex-guarded copy of the internal unordered set and
+ *  returns it sorted, guaranteeing deterministic output on every call.
+ *  Each reservation is serialized via `PeerReservation::toJson()`, which
+ *  encodes the node public key as a base58 string and omits the
+ *  `description` field when empty.
+ *
+ *  An empty reservation table produces `{"reservations": []}` rather than
+ *  an error, because `PeerReservationTable::load()` always succeeds even
+ *  when the backing SQLite table has no rows.
+ *
+ *  @param context  RPC dispatch context; `context.params` is not read.
+ *  @return JSON object of the form `{"reservations": [...]}` where each
+ *      element is a `PeerReservation` serialized by `toJson()`.
+ */
 json::Value
 doPeerReservationsList(RPC::JsonContext& context)
 {
     auto const& reservations = context.app.getPeerReservations().list();
-    // Enumerate the reservations in context.app.getPeerReservations()
-    // as a json::Value.
     json::Value result{json::ValueType::Object};
     json::Value& jaReservations = result[jss::reservations] = json::ValueType::Array;
     for (auto const& reservation : reservations)
diff --git a/src/xrpld/rpc/handlers/admin/peer/Peers.cpp b/src/xrpld/rpc/handlers/admin/peer/Peers.cpp
index ab14325f0e..53d6202cb1 100644
--- a/src/xrpld/rpc/handlers/admin/peer/Peers.cpp
+++ b/src/xrpld/rpc/handlers/admin/peer/Peers.cpp
@@ -1,3 +1,11 @@
+/** @file
+ *  Implements the `peers` admin RPC handler.
+ *
+ *  Aggregates two distinct views of the network into a single JSON response:
+ *  the real-time overlay snapshot (every TCP-connected peer) and the cluster
+ *  status table (trusted cluster members with their self-reported load).
+ */
+
 #include <xrpld/app/main/Application.h>
 #include <xrpld/core/TimeKeeper.h>
 #include <xrpld/overlay/Cluster.h>
@@ -16,6 +24,35 @@
 
 namespace xrpl {
 
+/** Respond to the `peers` admin RPC command.
+ *
+ *  Builds a JSON object with two top-level keys:
+ *
+ *  - `peers`: snapshot of every active overlay connection, sourced from
+ *    `Overlay::json()`.  Each entry carries a `track` field whose value
+ *    is `"diverged"` (peer is on a different chain) or `"unknown"`
+ *    (consensus not yet established); converged peers omit the field.
+ *
+ *  - `cluster`: one entry per configured cluster member (keyed by
+ *    base58-encoded node public key), excluding the local node.  Each
+ *    entry may carry:
+ *    - `tag` — human-readable name from `rippled.cfg`, omitted when empty.
+ *    - `fee` — load fee as a floating-point multiplier over `loadBase`,
+ *      omitted when equal to `loadBase` or zero (i.e., normal load).
+ *    - `age` — seconds since the member last broadcast its status,
+ *      omitted when the member has never reported; clamped to 0 on
+ *      clock-skew (reportTime >= now).
+ *
+ *  **API v1 compatibility**: when `context.apiVersion == 1` the handler
+ *  post-processes the peers array in-place, injecting a `sanity` field
+ *  alongside each `track` field: `"diverged"` → `"insane"`,
+ *  `"unknown"` → `"unknown"`.  Converged peers (no `track` field) receive
+ *  no `sanity` annotation under either version.
+ *
+ *  @param context  RPC dispatch context providing access to `Overlay`,
+ *      `Cluster`, `TimeKeeper`, and `LoadFeeTrack`.
+ *  @return JSON object with `peers` array and `cluster` object.
+ */
 json::Value
 doPeers(RPC::JsonContext& context)
 {
@@ -23,7 +60,6 @@ doPeers(RPC::JsonContext& context)
 
     jvResult[jss::peers] = context.app.getOverlay().json();
 
-    // Legacy support
     if (context.apiVersion == 1)
     {
         for (auto& p : jvResult[jss::peers])
diff --git a/src/xrpld/rpc/handlers/admin/server_control/LedgerAccept.cpp b/src/xrpld/rpc/handlers/admin/server_control/LedgerAccept.cpp
index ce06a6e480..12b3278dc8 100644
--- a/src/xrpld/rpc/handlers/admin/server_control/LedgerAccept.cpp
+++ b/src/xrpld/rpc/handlers/admin/server_control/LedgerAccept.cpp
@@ -11,6 +11,43 @@
 
 namespace xrpl {
 
+/** Implements the `ledger_accept` admin RPC command.
+ *
+ *  Forces the node to close the current open ledger and advance to the next
+ *  one without waiting for peer votes or the normal consensus timer. This is
+ *  only valid in standalone mode, where no validator peers participate and
+ *  ledger progression must be triggered on demand — for example, by the
+ *  `jtx` integration-test harness between transaction submissions.
+ *
+ *  If the node is not in standalone mode the response contains
+ *  `{"error": "notStandAlone"}` and no state is mutated.
+ *
+ *  When standalone mode is confirmed the handler acquires
+ *  `Application::getMasterMutex()` (a recursive mutex that serialises all
+ *  open-ledger and consensus-engine mutations) before delegating to
+ *  `NetworkOPs::acceptLedger()`. That method drives a synthetic consensus
+ *  round via `mConsensus.simulate()`, bypassing real peer participation and
+ *  producing a fully validated ledger as if consensus had concluded normally,
+ *  including fee adjustments and any pending open-ledger transactions.
+ *
+ *  The response on success contains a single field `ledger_current_index`
+ *  holding the sequence number of the ledger now open for new transactions
+ *  (one past the ledger just closed). Test frameworks use this value to
+ *  anchor subsequent state queries with confidence that the triggered
+ *  transactions have been processed.
+ *
+ *  @note This handler accepts no JSON parameters beyond the implicit RPC
+ *      envelope; validation here is purely a mode-enforcement check rather
+ *      than input sanitisation.
+ *  @note Registered in Handler.cpp with `Role::ADMIN` and
+ *      `Condition::NeedsCurrentLedger`, so it is unreachable for
+ *      non-admin connections and when the ledger is too stale.
+ *
+ *  @param context  The RPC dispatch context providing app services, config,
+ *      `netOps`, and `ledgerMaster`.
+ *  @return A JSON object with `ledger_current_index` on success, or
+ *      `{"error": "notStandAlone"}` when not in standalone mode.
+ */
 json::Value
 doLedgerAccept(RPC::JsonContext& context)
 {
diff --git a/src/xrpld/rpc/handlers/admin/server_control/Stop.cpp b/src/xrpld/rpc/handlers/admin/server_control/Stop.cpp
index 3e86bd4632..2935c92ea4 100644
--- a/src/xrpld/rpc/handlers/admin/server_control/Stop.cpp
+++ b/src/xrpld/rpc/handlers/admin/server_control/Stop.cpp
@@ -10,6 +10,31 @@ namespace RPC {
 struct JsonContext;
 }  // namespace RPC
 
+/** Implements the `stop` admin RPC command.
+ *
+ *  Signals the application to begin a graceful shutdown, then immediately
+ *  returns a confirmation message to the caller. The shutdown itself proceeds
+ *  asynchronously after this handler returns — the response is queued for
+ *  delivery before teardown begins, so the caller reliably receives
+ *  `"<name> server stopping"` even though the server is about to exit.
+ *
+ *  The delegate, `Application::signalStop("RPC")`, sets a C++20
+ *  `std::atomic_flag` exactly once (idempotent under concurrent callers) and
+ *  unblocks the `run()` loop. The `"RPC"` reason string is written to the
+ *  warning log, letting operators distinguish an administrative RPC shutdown
+ *  from a SIGTERM or an internal fault condition.
+ *
+ *  Permission enforcement is handled entirely by the dispatch layer:
+ *  the handler is registered with `Role::ADMIN` and `NO_CONDITION`, so it is
+ *  unreachable for non-admin connections and does not require the server to
+ *  hold a current ledger — a node that is still syncing can be stopped via
+ *  RPC just as readily as a fully-synced one.
+ *
+ *  @param context  The RPC dispatch context providing access to the
+ *      `Application` instance whose `signalStop()` is invoked.
+ *  @return A JSON object with a `"message"` field containing
+ *      `"<systemName> server stopping"`.
+ */
 json::Value
 doStop(RPC::JsonContext& context)
 {
diff --git a/src/xrpld/rpc/handlers/admin/signing/ChannelAuthorize.cpp b/src/xrpld/rpc/handlers/admin/signing/ChannelAuthorize.cpp
index be3ce13d45..dede8e8edd 100644
--- a/src/xrpld/rpc/handlers/admin/signing/ChannelAuthorize.cpp
+++ b/src/xrpld/rpc/handlers/admin/signing/ChannelAuthorize.cpp
@@ -23,12 +23,51 @@
 
 namespace xrpl {
 
-// {
-//   secret_key: <signing_secret_key>
-//   key_type: optional; either ed25519 or secp256k1 (default to secp256k1)
-//   channel_id: 256-bit channel id
-//   drops: 64-bit uint (as string)
-// }
+/** Sign a payment channel authorization (`channel_authorize`).
+ *
+ *  Produces a cryptographic signature that a channel recipient can present
+ *  in a `PaymentChannelClaim` transaction to redeem up to `amount` drops
+ *  without requiring the channel owner to be online at redemption time.
+ *
+ *  The signed payload is constructed by `serializePayChanAuthorization`:
+ *  `HashPrefix::paymentChannelClaim` (4-byte domain separator `'CLM\0'`) +
+ *  32-byte channel ID + 8-byte drops in big-endian. The domain separator
+ *  prevents the signature from being reinterpreted as authorization for any
+ *  other XRPL data structure. The resulting binary signature is returned as a
+ *  hex string in `"signature"`.
+ *
+ *  **Access control:** The handler is restricted to `Role::ADMIN` callers
+ *  or nodes with `[signing_support]` enabled in their configuration. Public
+ *  nodes reject this call by default to avoid exposing key material on
+ *  internet-facing endpoints.
+ *
+ *  **Key material:** Accepts `secret`, `passphrase`, `seed`, or `seed_hex`,
+ *  optionally paired with `key_type` (`"secp256k1"` or `"ed25519"`). When
+ *  `key_type` is absent and `secret` is also absent, a `missingFieldError`
+ *  for `secret` is returned immediately, providing a clear error for legacy
+ *  clients that omit both fields. When `key_type` is present, `secret` alone
+ *  is rejected — the caller must use one of the explicit seed encodings.
+ *
+ *  **Amount encoding:** `amount` must be a decimal-integer string (not a JSON
+ *  number) to avoid precision loss for values that exceed JavaScript's safe
+ *  integer range (~10^17 drops ≈ max XRP supply).
+ *
+ *  @param context  RPC dispatch context carrying `params`, `role`, and `app`.
+ *  @return A JSON object with key `"signature"` containing the hex-encoded
+ *      signature, or an error object on any validation failure.
+ *
+ *  @note Required params: `channel_id` (64-hex-char uint256), `amount`
+ *      (decimal string, drops), and at least one of `secret` / `key_type`.
+ *      Optional: `key_type` (`"secp256k1"` default, or `"ed25519"`),
+ *      `passphrase`, `seed`, `seed_hex`.
+ *  @note Error codes: `rpcNOT_SUPPORTED` (signing disabled), `missingField`
+ *      (missing required param), `rpcCHANNEL_MALFORMED` (bad channel ID),
+ *      `rpcCHANNEL_AMT_MALFORMED` (non-string or unparseable amount),
+ *      `rpcINTERNAL` (unexpected exception from `sign()`; unreachable under
+ *      normal conditions — excluded from coverage via `LCOV_EXCL`).
+ *  @see doChannelVerify, serializePayChanAuthorization,
+ *      RPC::keypairForSignature
+ */
 json::Value
 doChannelAuthorize(RPC::JsonContext& context)
 {
@@ -44,9 +83,8 @@ doChannelAuthorize(RPC::JsonContext& context)
             return RPC::missingFieldError(p);
     }
 
-    // Compatibility if a key type isn't specified. If it is, the
-    // keypairForSignature code will validate parameters and return
-    // the appropriate error.
+    // Early guard for legacy clients that supply neither field; when key_type
+    // is present, keypairForSignature handles the error itself.
     if (!params.isMember(jss::key_type) && !params.isMember(jss::secret))
         return RPC::missingFieldError(jss::secret);
 
diff --git a/src/xrpld/rpc/handlers/admin/signing/Sign.cpp b/src/xrpld/rpc/handlers/admin/signing/Sign.cpp
index 6953dfd3d8..02afb3487d 100644
--- a/src/xrpld/rpc/handlers/admin/signing/Sign.cpp
+++ b/src/xrpld/rpc/handlers/admin/signing/Sign.cpp
@@ -10,10 +10,37 @@
 
 namespace xrpl {
 
-// {
-//   tx_json: <object>,
-//   secret: <secret>
-// }
+/** Sign a transaction and return the signed blob without submitting it.
+ *
+ *  Implements the `sign` JSON-RPC command. Enforces the server's signing
+ *  access policy, tags the request as a heavy resource burden, then delegates
+ *  all cryptographic and structural work — key derivation, field auto-fill
+ *  (`Fee`, `Sequence`), serialization, and ECDSA/Ed25519 signing — to
+ *  `RPC::transactionSign`. The response always carries a `deprecated` field
+ *  steering callers toward client-side signing tools.
+ *
+ *  Access is granted when either condition holds:
+ *  - The caller holds `Role::ADMIN` (trusted local/credentialed connection), or
+ *  - The server is explicitly configured with `[signing_support] = 1`.
+ *  Both failing returns `rpcNOT_SUPPORTED`. The default configuration denies
+ *  non-admin callers, so a server inadvertently exposed to the internet will
+ *  not act as a signing oracle.
+ *
+ *  @param context  RPC dispatch envelope carrying `params` (must include
+ *      `tx_json` and a key field: `secret`, `seed`, `seed_hex`, or
+ *      `passphrase`), the negotiated API version, the caller's role, and
+ *      a reference to the application.
+ *  @return JSON object containing `tx_blob` and `tx_json` on success, or an
+ *      error object on failure. A `deprecated` field is always present.
+ *  @note `fail_hard` is read defensively via `isMember()` before `asBool()`
+ *      to handle its absence safely; the flag is forwarded to
+ *      `transactionSign` where it governs signing-pipeline error treatment.
+ *  @note Signing is rejected if the most recently validated ledger is older
+ *      than `Tuning::kMAX_VALIDATED_LEDGER_AGE` (2 minutes), preventing
+ *      transactions from being built against stale ledger state.
+ *  @see RPC::transactionSign
+ *  @see doSignFor
+ */
 json::Value
 doSign(RPC::JsonContext& context)
 {
diff --git a/src/xrpld/rpc/handlers/admin/signing/SignFor.cpp b/src/xrpld/rpc/handlers/admin/signing/SignFor.cpp
index 102cea08b4..ad4187e53c 100644
--- a/src/xrpld/rpc/handlers/admin/signing/SignFor.cpp
+++ b/src/xrpld/rpc/handlers/admin/signing/SignFor.cpp
@@ -10,11 +10,40 @@
 
 namespace xrpl {
 
-// {
-//   tx_json: <object>,
-//   account: <signing account>
-//   secret: <secret of signing account>
-// }
+/** Contribute one co-signer's signature to a multi-signed transaction.
+ *
+ *  Implements the `sign_for` JSON-RPC command. Enforces the server's signing
+ *  access policy, tags the request as a heavy resource burden, then delegates
+ *  all cryptographic work — key derivation, signature computation over the
+ *  serialized transaction, and injection of the resulting `Signer` entry into
+ *  the `Signers` array — to `RPC::transactionSignFor`. The response always
+ *  carries a `deprecated` field steering callers toward client-side tools.
+ *
+ *  Access is granted when either condition holds:
+ *  - The caller holds `Role::ADMIN` (trusted local/credentialed connection), or
+ *  - The server is explicitly configured with `[signing_support] = 1`.
+ *  Both failing returns `rpcNOT_SUPPORTED`. This two-level design separates
+ *  routing permission (set in the handler table as `Role::USER`) from feature
+ *  permission (enforced here), so public nodes never act as signing oracles
+ *  even if inadvertently exposed to the internet.
+ *
+ *  @param context  RPC dispatch envelope carrying `params` (must include
+ *      `tx_json`, `account` identifying whose signature slot is being filled,
+ *      and a key field: `secret`, `seed`, `seed_hex`, or `passphrase`),
+ *      the negotiated API version, the caller's role, and a reference to
+ *      the application.
+ *  @return JSON object containing the updated `tx_json` (with the new `Signer`
+ *      entry appended) and `tx_blob` on success, or an error object on
+ *      failure. A `deprecated` field is always present on success.
+ *  @note Unlike `doSign`, `fail_hard` is read via `asBool()` directly without
+ *      an `isMember()` guard. `Json::Value` returns `false` for absent fields,
+ *      so the result is correct, but the inconsistency with the sibling
+ *      handler is worth noting for future maintenance.
+ *  @note `tx_json` must carry pre-filled `Sequence` and `SigningPubKey` fields;
+ *      `transactionSignFor` does not auto-fill them, unlike single-signing.
+ *  @see RPC::transactionSignFor
+ *  @see doSign
+ */
 json::Value
 doSignFor(RPC::JsonContext& context)
 {
diff --git a/src/xrpld/rpc/handlers/admin/status/ConsensusInfo.cpp b/src/xrpld/rpc/handlers/admin/status/ConsensusInfo.cpp
index 341980ba6d..51c0d6d4bd 100644
--- a/src/xrpld/rpc/handlers/admin/status/ConsensusInfo.cpp
+++ b/src/xrpld/rpc/handlers/admin/status/ConsensusInfo.cpp
@@ -1,3 +1,12 @@
+/** @file
+ *  Implements the `consensus_info` admin RPC handler.
+ *
+ *  Registered in Handler.cpp as `Role::ADMIN` with `NO_CONDITION`, so the
+ *  handler runs regardless of sync state and is unreachable by non-admin
+ *  connections. The command accepts no parameters; any extra arguments are
+ *  rejected by the RPC framework before dispatch.
+ */
+
 #include <xrpld/rpc/Context.h>
 
 #include <xrpl/json/json_value.h>
@@ -6,6 +15,17 @@
 
 namespace xrpl {
 
+/** Snapshot the live consensus engine state for an admin caller.
+ *
+ *  Delegates to `NetworkOPs::getConsensusInfo()`, which calls
+ *  `Consensus::getJson(true)` — the verbose path that includes the current
+ *  consensus phase, dispute sets, proposal counts, and timing fields in
+ *  addition to the summary fields present in the non-verbose form.
+ *
+ *  @param context RPC dispatch envelope carrying the `NetworkOPs` reference.
+ *  @return JSON object with a single `"info"` key whose value is the verbose
+ *      consensus snapshot.
+ */
 json::Value
 doConsensusInfo(RPC::JsonContext& context)
 {
diff --git a/src/xrpld/rpc/handlers/admin/status/FetchInfo.cpp b/src/xrpld/rpc/handlers/admin/status/FetchInfo.cpp
index 16e4789025..6c0a278808 100644
--- a/src/xrpld/rpc/handlers/admin/status/FetchInfo.cpp
+++ b/src/xrpld/rpc/handlers/admin/status/FetchInfo.cpp
@@ -1,3 +1,11 @@
+/** @file
+ *  Handler for the `fetch_info` admin RPC command.
+ *
+ *  Exposes the internal state of the inbound ledger fetch subsystem and
+ *  optionally clears recorded fetch failures, allowing operators to diagnose
+ *  and recover from stalled ledger acquisition.
+ */
+
 #include <xrpld/rpc/Context.h>
 
 #include <xrpl/json/json_value.h>
@@ -6,6 +14,31 @@
 
 namespace xrpl {
 
+/** Handle the `fetch_info` admin RPC command.
+ *
+ *  Returns a snapshot of the inbound ledger fetch subsystem's current state.
+ *  If the `"clear"` parameter is present and true, failed-fetch records are
+ *  wiped first via `InboundLedgers::clearFailures()` so that previously
+ *  abandoned ledgers become eligible for re-acquisition. The snapshot
+ *  returned under `"info"` always reflects the post-clear state, making a
+ *  single `{"clear": true}` call both an action and a confirmation.
+ *
+ *  Registered in `Handler.cpp` as `"fetch_info"` with `Role::ADMIN` and
+ *  `Condition::NoCondition`.
+ *
+ *  @param context  RPC dispatch envelope; `context.params` may contain an
+ *      optional boolean `"clear"` field. `context.netOps` is the
+ *      `NetworkOPs` abstraction through which the fetch subsystem is reached.
+ *  @return A JSON object with:
+ *      - `"clear"` (boolean, present only when the clear action was taken)
+ *        — echoes `true` to confirm that failed-fetch records were wiped.
+ *      - `"info"` (object) — the fetch-state snapshot from
+ *        `InboundLedgers::getInfo()`.
+ *  @note The `"clear"` field is read with an `isMember` guard before
+ *      `asBool()` to avoid a type-coercion exception when the field is
+ *      absent; unexpected non-boolean values are handled by `Json::Value`'s
+ *      built-in coercion, consistent with sibling handlers in this directory.
+ */
 json::Value
 doFetchInfo(RPC::JsonContext& context)
 {
diff --git a/src/xrpld/rpc/handlers/admin/status/GetCounts.cpp b/src/xrpld/rpc/handlers/admin/status/GetCounts.cpp
index 789c6dcf17..78be22b140 100644
--- a/src/xrpld/rpc/handlers/admin/status/GetCounts.cpp
+++ b/src/xrpld/rpc/handlers/admin/status/GetCounts.cpp
@@ -1,3 +1,11 @@
+/** @file
+ *  Implements the `get_counts` admin RPC command.
+ *
+ *  Provides a single-call snapshot of runtime health: live object reference
+ *  counts, relational database disk usage, multiple cache hit rates, node
+ *  store write pressure, and formatted uptime.
+ */
+
 #include <xrpld/app/ledger/InboundLedgers.h>
 #include <xrpld/app/ledger/LedgerMaster.h>
 #include <xrpld/app/main/Application.h>
@@ -17,6 +25,24 @@
 
 namespace xrpl {
 
+/** Append one time unit to an uptime string and consume it from the remainder.
+ *
+ *  Divides `seconds` by `unitVal`, appends the count and unit name to `text`
+ *  (with a comma separator if `text` is non-empty and an "s" plural suffix
+ *  when count > 1), then subtracts the consumed duration from `seconds`.
+ *  Does nothing when the unit count is zero, so units with no contribution
+ *  are silently omitted from the output.
+ *
+ *  @param text     Accumulator string for the formatted uptime result.
+ *  @param seconds  Remaining uptime; modified in place by subtracting the
+ *      portion consumed by this unit.
+ *  @param unitName Singular name of the time unit (e.g. "hour").
+ *  @param unitVal  Duration value of one unit (e.g. `std::chrono::hours{1}`).
+ *
+ *  @note This function is intended to be called in descending unit order
+ *      (years → days → hours → minutes → seconds). Each call strips the
+ *      largest remaining unit, so later calls never double-count earlier ones.
+ */
 static void
 textTime(
     std::string& text,
@@ -42,6 +68,31 @@ textTime(
         text += "s";
 }
 
+/** Aggregate runtime diagnostics and cache statistics into a JSON object.
+ *
+ *  Collects and returns a snapshot of the node's internal state, including:
+ *  - Live object reference counts from `CountedObjects` (filtered by
+ *    `minObjectCount` to suppress low-population types);
+ *  - Relational database disk usage (`dbKBTotal`, `dbKBLedger`,
+ *    `dbKBTransaction`) and local transaction queue depth, when
+ *    `config().useTxTables()` is enabled;
+ *  - Node store write pressure (`write_load`) and historical ledger fetch
+ *    rate (`historical_perminute`);
+ *  - Cache hit rates for SLEs, the ledger cache, and the `AcceptedLedger`
+ *    cache, plus `NodeFamily` SHAMap tree-node cache sizes;
+ *  - Formatted human-readable uptime string;
+ *  - Additional node store counters appended by
+ *    `NodeStore::Database::getCountsJson`.
+ *
+ *  This function is factored out of the RPC handler so it can be called by
+ *  non-RPC paths (e.g. `OverlayImpl::getServerCounts` for the `/crawl`
+ *  endpoint) without constructing a fake `RPC::JsonContext`.
+ *
+ *  @param app            The running application instance.
+ *  @param minObjectCount Minimum live-instance threshold for including an
+ *      object type in the output. Types with fewer live instances are omitted.
+ *  @return JSON object containing the aggregated diagnostic fields.
+ */
 json::Value
 getCountsJson(Application& app, int minObjectCount)
 {
@@ -107,9 +158,19 @@ getCountsJson(Application& app, int minObjectCount)
     return ret;
 }
 
-// {
-//   min_count: <number>  // optional, defaults to 10
-// }
+/** Handle the `get_counts` admin RPC request.
+ *
+ *  Reads the optional `min_count` parameter (default: 10) and delegates to
+ *  `getCountsJson`. The default of 10 acts as a noise filter, suppressing
+ *  object types with very few live instances that are rarely relevant in
+ *  production diagnostics.
+ *
+ *  @param context RPC dispatch context; `context.params` may contain
+ *      `min_count` (unsigned integer). A missing, non-numeric, or negative
+ *      value silently coerces to 0, causing all object types to be reported.
+ *  @return JSON object of aggregated runtime diagnostics.
+ *  @see getCountsJson
+ */
 json::Value
 doGetCounts(RPC::JsonContext& context)
 {
diff --git a/src/xrpld/rpc/handlers/admin/status/GetCounts.h b/src/xrpld/rpc/handlers/admin/status/GetCounts.h
index 05751637ee..eef745f6e4 100644
--- a/src/xrpld/rpc/handlers/admin/status/GetCounts.h
+++ b/src/xrpld/rpc/handlers/admin/status/GetCounts.h
@@ -1,9 +1,49 @@
+/** @file
+ *  Declares `getCountsJson`, the shared diagnostic snapshot function for the
+ *  `get_counts` admin RPC command and the `/crawl` overlay endpoint.
+ *
+ *  The function is factored out of `GetCounts.cpp` so that non-RPC subsystems
+ *  (specifically `OverlayImpl::getServerCounts`) can obtain the same runtime
+ *  health payload without depending on `RPC::JsonContext` or the full RPC
+ *  dispatch machinery — only on `Application&`.
+ */
+
 #pragma once
 
 #include <xrpld/app/main/Application.h>
 
 namespace xrpl {
 
+/** Aggregate runtime diagnostics and cache statistics into a JSON object.
+ *
+ *  Returns a broad snapshot of the node's internal health, including:
+ *  - Live object reference counts from `CountedObjects` (types with fewer
+ *    than `minObjectCount` live instances are omitted to reduce noise);
+ *  - Relational database disk usage (`dbKBTotal`, `dbKBLedger`,
+ *    `dbKBTransaction`) and local transaction queue depth (`local_txs`) — only
+ *    present when `config().useTxTables()` is enabled;
+ *  - Node store write pressure (`write_load`) and historical ledger fetch
+ *    rate (`historical_perminute`);
+ *  - Cache hit rates for SLEs, the ledger cache, and `AcceptedLedger`, plus
+ *    `NodeFamily` SHAMap tree-node cache sizes;
+ *  - Human-readable formatted uptime string;
+ *  - Additional counters appended by `NodeStore::Database::getCountsJson`.
+ *
+ *  This function is the shared implementation used by both the `doGetCounts`
+ *  RPC handler (default `minObjectCount` of 10, overridable via `min_count`)
+ *  and `OverlayImpl::getServerCounts` (hard-coded threshold of 10) for the
+ *  `/crawl` endpoint, without requiring either caller to construct a fake
+ *  `RPC::JsonContext`.
+ *
+ *  @param app            The running application instance.
+ *  @param minObjectCount Minimum live-instance threshold for including a
+ *      tracked object type in the output. Pass 0 to report all types.
+ *  @return JSON object containing the aggregated diagnostic fields.
+ *
+ *  @note `local_txs` and the `dbKB*` fields are absent when
+ *      `config().useTxTables()` is false (e.g. reporting nodes that do not
+ *      maintain a transaction database).
+ */
 json::Value
 getCountsJson(Application& app, int minObjectCount);
 
diff --git a/src/xrpld/rpc/handlers/admin/status/Print.cpp b/src/xrpld/rpc/handlers/admin/status/Print.cpp
index 99fd01c9f4..945423a826 100644
--- a/src/xrpld/rpc/handlers/admin/status/Print.cpp
+++ b/src/xrpld/rpc/handlers/admin/status/Print.cpp
@@ -1,3 +1,15 @@
+/** @file
+ *  Admin RPC handler that serializes the application's `beast::PropertyStream`
+ *  tree to JSON.
+ *
+ *  `Application` is the root of a named, hierarchical tree of diagnostic
+ *  sources — every major subsystem registers itself as a child. `doPrint`
+ *  drives a `JsonPropertyStream` sink over that tree to produce a runtime
+ *  introspection snapshot. New subsystems that register as
+ *  `PropertyStream::Source` children are automatically included without any
+ *  change to this handler.
+ */
+
 #include <xrpld/app/main/Application.h>
 #include <xrpld/rpc/Context.h>
 
@@ -7,6 +19,29 @@
 
 namespace xrpl {
 
+/** Serialize the application's full `beast::PropertyStream` tree to JSON.
+ *
+ *  Drives a `JsonPropertyStream` sink over the `Application` property-stream
+ *  tree and returns the resulting JSON object as the RPC response. An optional
+ *  dot-delimited path filter may be supplied via
+ *  `params[0]` (e.g. `"ledgermaster"` or `"consensus.*"`) to target a
+ *  specific named sub-source; if the path ends with `*` the subtree is dumped
+ *  recursively. If the parameter is absent or malformed the entire tree is
+ *  returned.
+ *
+ *  Serialization safety is provided by `beast::PropertyStream::Source::write()`,
+ *  which acquires a `std::recursive_mutex` on each source node before
+ *  iterating its children. This handler acquires no additional locks.
+ *
+ *  @param context  RPC dispatch context; `context.app` is the stream root.
+ *      An optional path filter is read from
+ *      `context.params[jss::params][0u]` as a string; all other shapes are
+ *      silently ignored and the full tree is serialized instead.
+ *  @return JSON object containing the serialized property-stream tree (or
+ *      the targeted sub-tree when a valid path filter is provided).
+ *  @note This handler always succeeds — a malformed or mistyped path filter
+ *      produces a full-tree dump rather than an error response.
+ */
 json::Value
 doPrint(RPC::JsonContext& context)
 {
diff --git a/src/xrpld/rpc/handlers/admin/status/ValidatorInfo.cpp b/src/xrpld/rpc/handlers/admin/status/ValidatorInfo.cpp
index efe1529ccb..63c25695b4 100644
--- a/src/xrpld/rpc/handlers/admin/status/ValidatorInfo.cpp
+++ b/src/xrpld/rpc/handlers/admin/status/ValidatorInfo.cpp
@@ -1,5 +1,25 @@
 // Copyright (c) 2019 Dev Null Productions
 
+/** @file
+ *  Admin RPC handler that reports the local node's own validator key
+ *  configuration.
+ *
+ *  Validators use a two-tier key scheme: a **master key** kept offline that
+ *  signs a **manifest** (a certificate binding the master key to the current
+ *  ephemeral signing key), and an **ephemeral key** installed on the live
+ *  node that signs ledger validations. `doValidatorInfo` reads the node's
+ *  ephemeral key from config, resolves the master key through the manifest
+ *  cache, and returns the full identity bundle to the operator. It takes no
+ *  parameters and always describes the local node's own state.
+ *
+ *  @see src/xrpld/rpc/handlers/admin/status/Validators.cpp for the
+ *      complementary handler reporting the set of trusted validators from
+ *      the UNL.
+ *  @see src/xrpld/rpc/handlers/server_info/Manifest.cpp for the public-
+ *      facing handler that looks up manifests for arbitrary validators by
+ *      submitted public key.
+ */
+
 #include <xrpld/app/main/Application.h>
 #include <xrpld/rpc/Context.h>
 
@@ -11,22 +31,48 @@
 #include <xrpl/protocol/tokens.h>
 
 namespace xrpl {
+
+/** Report the local node's validator identity: master key, ephemeral key,
+ *  active manifest, manifest sequence number, and claimed domain.
+ *
+ *  The node's ephemeral signing key is read from `[validator_token]` config
+ *  and passed to `ManifestCache::getMasterKey()`. If `getMasterKey` returns
+ *  the key unchanged (its identity-fallback behaviour when no manifest entry
+ *  exists), the node is either unconfigured for two-tier key rotation or is
+ *  using its master key directly for signing; in this case only `master_key`
+ *  is returned. When the two keys differ, `ephemeral_key`, `manifest`
+ *  (base64-encoded binary), `seq`, and `domain` are also included when
+ *  present in the manifest cache.
+ *
+ *  Both keys are encoded as `n…`-prefixed base58check strings
+ *  (`TokenType::NodePublic`). The manifest blob is base64 because it is a
+ *  binary-serialized XRPL `STObject`.
+ *
+ *  @param context The RPC dispatch context; must carry admin authorization.
+ *      The local node's validation key and manifest cache are accessed via
+ *      `context.app`.
+ *  @return A JSON object containing `master_key` and, when an active manifest
+ *      exists, `ephemeral_key`, `manifest`, `seq`, and (optionally) `domain`.
+ *      Returns a `notValidatorError` JSON error object if no validator key is
+ *      configured.
+ *  @note `manifest`, `seq`, and `domain` are each independently guarded by
+ *      an optional check, so any field may be absent without indicating an
+ *      error — this defends against transient cache states.
+ */
 json::Value
 doValidatorInfo(RPC::JsonContext& context)
 {
-    // return error if not configured as validator
     auto const validationPK = context.app.getValidationPublicKey();
     if (!validationPK)
         return RPC::notValidatorError();
 
     json::Value ret;
 
-    // assume validationPK is ephemeral key, get master key
     auto const mk = context.app.getValidatorManifests().getMasterKey(*validationPK);
     ret[jss::master_key] = toBase58(TokenType::NodePublic, mk);
 
-    // validationPK is master key, this implies that there is no ephemeral
-    // key, no manifest, hence return
+    // When getMasterKey returns the input key unchanged, no manifest exists
+    // for this node: there is no distinct ephemeral key to report.
     if (mk == validationPK)
         return ret;
 
diff --git a/src/xrpld/rpc/handlers/admin/status/ValidatorListSites.cpp b/src/xrpld/rpc/handlers/admin/status/ValidatorListSites.cpp
index 7497105c50..4224be1dd3 100644
--- a/src/xrpld/rpc/handlers/admin/status/ValidatorListSites.cpp
+++ b/src/xrpld/rpc/handlers/admin/status/ValidatorListSites.cpp
@@ -1,3 +1,12 @@
+/** @file
+ *  Handler for the `validator_list_sites` admin RPC command.
+ *
+ *  Exposes the runtime state of the node's validator-list fetching subsystem
+ *  (`ValidatorSite`) as a JSON response. The handler is registered with
+ *  `Role::ADMIN` and no feature-flag condition, restricting it to trusted
+ *  operators performing diagnostic or operational tasks.
+ */
+
 #include <xrpld/app/main/Application.h>
 #include <xrpld/app/misc/ValidatorSite.h>
 #include <xrpld/rpc/Context.h>
@@ -6,6 +15,27 @@
 
 namespace xrpl {
 
+/** Return the current state of all configured validator list sites.
+ *
+ *  Delegates entirely to `ValidatorSite::getJson()`, which serializes the
+ *  per-site state maintained by the periodic HTTP fetch machinery: configured
+ *  URIs, last-refresh timestamps, refresh intervals, redirect history, and
+ *  the disposition of the last fetched list (accepted, rejected, or pending).
+ *
+ *  `ValidatorSite::getJson()` is thread-safe — it acquires `sites_mutex_`
+ *  then `state_mutex_` internally (in that fixed order to prevent deadlock),
+ *  so this handler may be called from any thread concurrently with the fetch
+ *  timer without additional synchronisation.
+ *
+ *  @param context  The RPC dispatch context; `context.app` provides access to
+ *      the application-singleton `ValidatorSite` subsystem.
+ *  @return A JSON object whose structure is defined by
+ *      `ValidatorSite::getJson()`.
+ *  @note Registered in `Handler.cpp` as `{"validator_list_sites", ...,
+ *      Role::ADMIN, Condition::NoCondition}`. No network-sync or ledger
+ *      condition is required — the site list is available regardless of
+ *      ledger state.
+ */
 json::Value
 doValidatorListSites(RPC::JsonContext& context)
 {
diff --git a/src/xrpld/rpc/handlers/admin/status/Validators.cpp b/src/xrpld/rpc/handlers/admin/status/Validators.cpp
index 48e4466861..49e6b15083 100644
--- a/src/xrpld/rpc/handlers/admin/status/Validators.cpp
+++ b/src/xrpld/rpc/handlers/admin/status/Validators.cpp
@@ -1,3 +1,12 @@
+/** @file
+ *  Handler for the `validators` admin RPC command.
+ *
+ *  Exposes the full state of the node's active Unique Node List (UNL) as a
+ *  JSON response. The handler is registered with `Role::ADMIN` and no
+ *  feature-flag condition, restricting it to authenticated operators and
+ *  making it available regardless of ledger sync state.
+ */
+
 #include <xrpld/app/main/Application.h>
 #include <xrpld/app/misc/ValidatorList.h>
 #include <xrpld/rpc/Context.h>
@@ -6,6 +15,33 @@
 
 namespace xrpl {
 
+/** Return the full state of the node's active validator list.
+ *
+ *  Delegates entirely to `ValidatorList::getJson()`, which serializes the
+ *  complete UNL state: trusted signing keys, quorum thresholds, publisher
+ *  public keys, list sequence numbers, expiry timestamps, and per-publisher
+ *  disposition flags (e.g. `accepted`, `expired`, `pending`, `stale`).
+ *
+ *  `ValidatorList::getJson()` is thread-safe and may be called concurrently
+ *  with list updates. No locking is required by this handler.
+ *
+ *  @param context  The RPC dispatch context; `context.app` provides access
+ *      to the application-singleton `ValidatorList` subsystem.
+ *  @return A JSON object whose structure is defined by
+ *      `ValidatorList::getJson()`.
+ *  @note Registered in `Handler.cpp` as `{"validators", ..., Role::ADMIN,
+ *      Condition::NoCondition}`. The handler carries no request parameters
+ *      and performs no input validation — all content and error handling is
+ *      the responsibility of `ValidatorList`. It responds even when the node
+ *      has not yet synced, because UNL metadata is loaded at startup
+ *      independent of ledger progress.
+ *  @see doValidatorListSites (`ValidatorListSites.cpp`) for the sites from
+ *      which this node fetches UNL updates.
+ *  @see doValidatorInfo (`ValidatorInfo.cpp`) for the local node's own
+ *      validator identity (ephemeral key, manifest, master key).
+ *  @see doUnlList (`admin/UnlList.cpp`) for a narrower view that lists only
+ *      trusted public keys without publisher-level metadata.
+ */
 json::Value
 doValidators(RPC::JsonContext& context)
 {
diff --git a/src/xrpld/rpc/handlers/ledger/Ledger.cpp b/src/xrpld/rpc/handlers/ledger/Ledger.cpp
index 7034dce768..68286943b9 100644
--- a/src/xrpld/rpc/handlers/ledger/Ledger.cpp
+++ b/src/xrpld/rpc/handlers/ledger/Ledger.cpp
@@ -1,3 +1,14 @@
+/** @file
+ *  Implements the `ledger` RPC command for both the JSON-RPC path
+ *  (`LedgerHandler`) and the gRPC path (`doLedgerGrpc`).
+ *
+ *  `LedgerHandler` uses the two-phase check()/writeResult() pattern:
+ *  `check()` resolves the ledger and validates parameters; `writeResult()`
+ *  serializes the result. The gRPC handler additionally supports incremental
+ *  state-object diffs and DEX best-offer neighbor tracking, primarily for use
+ *  by the Clio indexing service.
+ */
+
 #include <xrpld/rpc/handlers/ledger/Ledger.h>
 
 #include <xrpld/app/ledger/LedgerToJson.h>
@@ -39,6 +50,31 @@ LedgerHandler::LedgerHandler(JsonContext& context) : context_(context)
 {
 }
 
+/** Validate request parameters, resolve the target ledger, and set options.
+ *
+ *  Parses all boolean flags (`full`, `transactions`, `accounts`, `expand`,
+ *  `binary`, `owner_funds`, `queue`) and OR-combines them into `options_`.
+ *  If none of `ledger`, `ledger_hash`, or `ledger_index` are present in the
+ *  request, the method returns `Status::kOK` immediately without populating
+ *  `ledger_`, which causes `writeResult()` to emit the dual closed+open
+ *  response instead.
+ *
+ *  When a ledger identifier is supplied, `lookupLedger` resolves and stores
+ *  `ledger_` and seeds `result_` with preliminary metadata.
+ *
+ *  @return `Status::kOK` on success; `rpcNO_PERMISSION` if `full` or
+ *      `accounts` is requested by a non-admin caller; `rpcTOO_BUSY` if the
+ *      node is under high local load and a full/accounts dump is requested;
+ *      `rpcINVALID_PARAMS` if any boolean flag is not actually a boolean, or
+ *      if `queue` is requested against a non-open ledger.
+ *
+ *  @note Dumping the entire account state trie (`full` or `accounts`) is
+ *      restricted to admin/unlimited roles and further throttled by local
+ *      load. Binary mode charges `feeMediumBurdenRPC`; JSON mode charges
+ *      `feeHeavyBurdenRPC`. The `queue` flag is only meaningful on the open
+ *      ledger; requesting it against a closed or historical ledger returns
+ *      `rpcINVALID_PARAMS`.
+ */
 Status
 LedgerHandler::check()
 {
@@ -97,8 +133,6 @@ LedgerHandler::check()
 
     if (*full || *accounts)
     {
-        // Until some sane way to get full ledgers has been implemented,
-        // disallow retrieving all state nodes.
         if (!isUnlimited(context_.role))
             return RpcNoPermission;
 
@@ -114,8 +148,6 @@ LedgerHandler::check()
     {
         if (!ledger_ || !ledger_->open())
         {
-            // It doesn't make sense to request the queue
-            // with a non-existent or closed/validated ledger.
             return RpcInvalidParams;
         }
 
@@ -125,6 +157,20 @@ LedgerHandler::check()
     return Status::kOK;
 }
 
+/** Serialize the ledger response into the JSON output value.
+ *
+ *  If `ledger_` was populated by `check()`, merges the metadata already
+ *  accumulated in `result_` and calls `addJson` with the resolved ledger,
+ *  context, `options_` bitmask, and any queued transactions. If `ledger_` is
+ *  not set (no identifier was supplied), emits both the current closed and
+ *  current open ledger as sibling fields `closed` and `open`, giving callers
+ *  a consistent snapshot of the validator frontier.
+ *
+ *  Appends a structured `warnings` array entry (`warnRPC_FIELDS_DEPRECATED`)
+ *  when the deprecated `type` filter field is present in the request.
+ *
+ *  @param value  Output JSON object that receives the ledger description.
+ */
 void
 LedgerHandler::writeResult(json::Value& value)
 {
@@ -164,6 +210,36 @@ LedgerHandler::writeResult(json::Value& value)
 
 }  // namespace RPC
 
+/** @see GRPCHandlers.h for the public contract of this function.
+ *
+ *  Implementation notes:
+ *
+ *  **Transaction iteration** is wrapped in a try-catch: if any transaction
+ *  fails to deserialize mid-iteration the handler logs the anomaly and breaks
+ *  out of the loop, returning whatever transactions were processed. This
+ *  partial-failure tolerance is intentional — a single corrupt entry should
+ *  not abort the entire response.
+ *
+ *  **State-object diff** (`get_objects`) requires both the target ledger and
+ *  its parent to be `dynamic_pointer_cast`-able to `Ledger const`, because
+ *  `stateMap()` is only exposed on the concrete `Ledger` class, not on the
+ *  `ReadView` interface. A plain `ReadView` (e.g., an open ledger) returns
+ *  `NOT_FOUND`. The diff is produced via `SHAMap::compare` and classified
+ *  into CREATED, MODIFIED, and DELETED entries.
+ *
+ *  **DEX book-successor tracking** (`get_object_neighbors`): for any
+ *  `ltDIR_NODE` entry without an `sfOwner` field (i.e., an order-book quality
+ *  directory node, not an account owner directory), the handler uses
+ *  `keylet::quality` and `getQualityNext` to locate the first remaining
+ *  quality tier in the book. Created nodes update the best-offer pointer;
+ *  deleted nodes trigger a search for the new first node in the desired
+ *  state map. This allows Clio to maintain DEX best-offer positions across
+ *  ledger transitions without a full trie scan.
+ *
+ *  @note The performance log at the end divides duration by object and
+ *      transaction counts without guarding against zero-count division — a
+ *      minor robustness gap in the observability path.
+ */
 std::pair<org::xrpl::rpc::v1::GetLedgerResponse, grpc::Status>
 doLedgerGrpc(RPC::GRPCContext<org::xrpl::rpc::v1::GetLedgerRequest>& context)
 {
diff --git a/src/xrpld/rpc/handlers/ledger/Ledger.h b/src/xrpld/rpc/handlers/ledger/Ledger.h
index 83ea4314e5..f666868e90 100644
--- a/src/xrpld/rpc/handlers/ledger/Ledger.h
+++ b/src/xrpld/rpc/handlers/ledger/Ledger.h
@@ -1,3 +1,12 @@
+/** @file
+ *  Declares `LedgerHandler`, the new-style class-based RPC handler for the
+ *  `ledger` JSON-RPC command.
+ *
+ *  `LedgerHandler` is one of only two class-based handlers in the codebase
+ *  (the other being `VersionHandler`). All other handlers are registered as
+ *  bare function pointers in the legacy `handlerArray` table; this handler is
+ *  added via `addHandler<LedgerHandler>()` during `HandlerTable` construction.
+ */
 #pragma once
 
 #include <xrpld/app/ledger/LedgerMaster.h>
@@ -20,40 +29,123 @@ namespace xrpl::RPC {
 
 struct JsonContext;
 
-// ledger [id|index|current|closed] [full]
-// {
-//    ledger: 'current' | 'closed' | <uint256> | <number>,  // optional
-//    full: true | false    // optional, defaults to false.
-// }
-
+/** Two-phase handler for the `ledger` JSON-RPC command.
+ *
+ *  Implements the primary client endpoint for inspecting ledger state,
+ *  transactions, and the transaction queue. The handler follows a two-phase
+ *  protocol: `check()` validates parameters and resolves the target ledger,
+ *  then `writeResult()` serialises the response.
+ *
+ *  The static metadata members (`name`, `role`, `condition`, `minApiVer`,
+ *  `maxApiVer`) are read by `addHandler<T>()` at registration time and
+ *  validated via `static_assert`. `role = Role::USER` makes the command
+ *  available to all authenticated callers without admin privilege.
+ *  `condition = NoCondition` allows the handler to run regardless of network
+ *  synchronisation state, so it can always return whatever ledger state is
+ *  locally available.
+ *
+ *  @see Handler.cpp `HandlerTable` for registration via `addHandler<T>()`.
+ *  @see Ledger.cpp `doLedgerGrpc` for the parallel gRPC surface, which shares
+ *      no code path but lives in the same translation unit.
+ */
 class LedgerHandler
 {
 public:
-    explicit LedgerHandler(JsonContext&);
+    /** Construct a handler bound to the given request context.
+     *
+     *  @param context  The active JSON-RPC request context. Held by reference
+     *      for the lifetime of this handler; the caller must ensure the context
+     *      outlives the handler.
+     */
+    explicit LedgerHandler(JsonContext& context);
 
+    /** Validate request parameters, resolve the target ledger, and build the
+     *  options bitmask for `writeResult()`.
+     *
+     *  Parses all boolean flags (`full`, `transactions`, `accounts`, `expand`,
+     *  `binary`, `owner_funds`, `queue`) and OR-combines them into `options_`.
+     *  If none of `ledger`, `ledger_hash`, or `ledger_index` are present in
+     *  the request, the method returns `Status::kOK` without populating
+     *  `ledger_`, which causes `writeResult()` to emit the dual
+     *  closed-and-open response instead.
+     *
+     *  When a ledger identifier is supplied, `lookupLedger` resolves and
+     *  stores `ledger_` and seeds `result_` with preliminary metadata that
+     *  `writeResult()` will merge into the final output.
+     *
+     *  @return `Status::kOK` on success; `rpcINVALID_PARAMS` if any boolean
+     *      flag is not actually a boolean, or if `queue=true` is requested
+     *      against a non-open ledger; `rpcNO_PERMISSION` if `full` or
+     *      `accounts` is requested by a non-admin (non-unlimited) caller;
+     *      `rpcTOO_BUSY` if the node is under heavy local load and a full or
+     *      accounts dump is requested.
+     *
+     *  @note Dumping the entire account state trie (`full` or `accounts`) is
+     *      restricted to admin/unlimited roles and further throttled by local
+     *      load. Binary mode charges `feeMediumBurdenRPC`; JSON mode charges
+     *      `feeHeavyBurdenRPC`. The `queue` flag is only meaningful against
+     *      the open ledger; supplying it with a closed or historical ledger
+     *      selector returns `rpcINVALID_PARAMS`.
+     */
     Status
     check();
 
+    /** Serialize the resolved ledger into the JSON output value.
+     *
+     *  If `ledger_` was populated by `check()`, merges the diagnostic metadata
+     *  accumulated in `result_` and calls `addJson()` with the `options_`
+     *  bitmask and any captured transaction-queue snapshot. If `ledger_` is
+     *  not set (no ledger selector was given), emits both the current closed
+     *  and current open ledger under the sibling keys `closed` and `open`.
+     *
+     *  Appends a structured `warnings` array entry when the deprecated `type`
+     *  filter field is detected in the request parameters.
+     *
+     *  @param value  Output JSON object that receives the ledger description.
+     */
     void
-    writeResult(json::Value&);
+    writeResult(json::Value& value);
 
     // NOLINTBEGIN(readability-identifier-naming)
+    /** RPC method name used as the dispatch key in the handler table. */
     static constexpr char name[] = "ledger";
 
+    /** Minimum API version that this handler accepts. */
     static constexpr unsigned minApiVer = RPC::kAPI_MINIMUM_SUPPORTED_VERSION;
 
+    /** Maximum API version that this handler accepts. */
     static constexpr unsigned maxApiVer = RPC::kAPI_MAXIMUM_VALID_VERSION;
 
+    /** Access role required; USER means no admin privilege is needed. */
     static constexpr Role role = Role::USER;
 
+    /** Node-state prerequisite; NoCondition allows dispatch during initial sync. */
     static constexpr Condition condition = Condition::NoCondition;
     // NOLINTEND(readability-identifier-naming)
 
 private:
+    /** Active request context providing params, app, role, and API version. */
     JsonContext& context_;
+
+    /** Resolved ledger, populated by `check()` when a ledger selector is given.
+     *  Null when no selector is present; `writeResult()` uses this to choose
+     *  between the single-ledger and dual closed+open response paths.
+     */
     std::shared_ptr<ReadView const> ledger_;
+
+    /** Transaction-queue snapshot fetched by `check()` when `queue=true`.
+     *  Only populated if `ledger_` refers to the open ledger.
+     */
     std::vector<TxQ::TxDetails> queueTxs_;
+
+    /** Intermediate JSON seeded by `lookupLedger()` during `check()`;
+     *  merged into the final output by `writeResult()` via `copyFrom()`.
+     */
     json::Value result_;
+
+    /** Bitmask of `LedgerFill::Options` flags built from request parameters
+     *  during `check()` and passed to `addJson()` in `writeResult()`.
+     */
     int options_ = 0;
 };
 
diff --git a/src/xrpld/rpc/handlers/ledger/LedgerClosed.cpp b/src/xrpld/rpc/handlers/ledger/LedgerClosed.cpp
index 7ea314292f..1424ba7eaa 100644
--- a/src/xrpld/rpc/handlers/ledger/LedgerClosed.cpp
+++ b/src/xrpld/rpc/handlers/ledger/LedgerClosed.cpp
@@ -1,3 +1,11 @@
+/** @file
+ *  Implements the `ledger_closed` RPC handler.
+ *
+ *  Returns the sequence number and hash of the most recently closed ledger —
+ *  the ledger that has completed consensus but may not yet have a validation
+ *  quorum. Registered with `NEEDS_CLOSED_LEDGER` and `Role::USER`.
+ */
+
 #include <xrpld/app/ledger/LedgerMaster.h>
 #include <xrpld/rpc/Context.h>
 
@@ -9,6 +17,26 @@
 
 namespace xrpl {
 
+/** Handle the `ledger_closed` RPC command.
+ *
+ *  Returns the sequence number (`ledger_index`) and hash (`ledger_hash`) of
+ *  the most recently closed ledger. The closed ledger has completed the
+ *  consensus process and is immutable, but a validation supermajority has not
+ *  necessarily been reached yet — it sits between the open current ledger and
+ *  the fully validated one.
+ *
+ *  This handler accepts no client-supplied parameters; the `context` is used
+ *  only to reach `ledgerMaster`.
+ *
+ *  @param context The RPC dispatch context; `context.ledgerMaster` provides
+ *      the closed ledger reference.
+ *  @return A JSON object with exactly two fields: `ledger_index` (uint32
+ *      sequence number) and `ledger_hash` (lowercase hex string).
+ *  @note The `NEEDS_CLOSED_LEDGER` precondition guarantees a closed ledger
+ *      exists before this handler is invoked. The internal `XRPL_ASSERT`
+ *      therefore guards against a framework invariant violation, not a
+ *      normal client error path.
+ */
 json::Value
 doLedgerClosed(RPC::JsonContext& context)
 {
diff --git a/src/xrpld/rpc/handlers/ledger/LedgerCurrent.cpp b/src/xrpld/rpc/handlers/ledger/LedgerCurrent.cpp
index 1d05774163..c098a65467 100644
--- a/src/xrpld/rpc/handlers/ledger/LedgerCurrent.cpp
+++ b/src/xrpld/rpc/handlers/ledger/LedgerCurrent.cpp
@@ -1,3 +1,11 @@
+/** @file
+ *  Implements the `ledger_current` RPC handler.
+ *
+ *  Returns the sequence number of the open (in-progress) ledger — the ledger
+ *  that is currently accepting transactions and has not yet been closed and
+ *  validated. Registered with `NeedsCurrentLedger` and `Role::USER`.
+ */
+
 #include <xrpld/app/ledger/LedgerMaster.h>
 #include <xrpld/rpc/Context.h>
 
@@ -7,6 +15,23 @@
 
 namespace xrpl {
 
+/** Handle the `ledger_current` RPC command.
+ *
+ *  Reports the sequence number of the open ledger: the ledger currently
+ *  accumulating transactions that has not yet been closed or validated.
+ *  Only the sequence number is returned because an open ledger has no
+ *  finalized state root and therefore no deterministic hash — contrast
+ *  with `doLedgerClosed`, which returns both `ledger_index` and
+ *  `ledger_hash`.
+ *
+ *  This handler accepts no client-supplied parameters; the `context` is
+ *  used only to reach `ledgerMaster`.
+ *
+ *  @param context The RPC dispatch context; `context.ledgerMaster` provides
+ *      the current open ledger index via `getCurrentLedgerIndex()`.
+ *  @return A JSON object with a single field: `ledger_current_index`
+ *      (uint32 sequence number of the open ledger).
+ */
 json::Value
 doLedgerCurrent(RPC::JsonContext& context)
 {
diff --git a/src/xrpld/rpc/handlers/ledger/LedgerData.cpp b/src/xrpld/rpc/handlers/ledger/LedgerData.cpp
index 64ab30374b..50eed82b9a 100644
--- a/src/xrpld/rpc/handlers/ledger/LedgerData.cpp
+++ b/src/xrpld/rpc/handlers/ledger/LedgerData.cpp
@@ -24,17 +24,47 @@
 
 namespace xrpl {
 
-// Get state nodes from a ledger
-//   Inputs:
-//     limit:        integer, maximum number of entries
-//     marker:       opaque, resume point
-//     binary:       boolean, format
-//     type:         string // optional, defaults to all ledger node types
-//   Outputs:
-//     ledger_hash:  chosen ledger's hash
-//     ledger_index: chosen ledger's index
-//     state:        array of state nodes
-//     marker:       resume point, if any
+/** Handle the `ledger_data` JSON-RPC command.
+ *
+ *  Returns a paginated forward scan of the raw state-node map for a specified
+ *  closed ledger, enabling bulk retrieval of the complete ledger state. The
+ *  canonical use case is ledger synchronization and archival: callers walk
+ *  the full state by following the opaque `marker` token across successive
+ *  calls.
+ *
+ *  Recognized request fields:
+ *  - `ledger_hash` / `ledger_index` — ledger selector (resolved via
+ *      `RPC::lookupLedger`; defaults to current).
+ *  - `marker` — hex-encoded 256-bit resume key from a prior response.
+ *      Absent on the first call; iteration starts from key zero.
+ *  - `limit` — maximum entries to return. Non-admin callers are silently
+ *      clamped to `RPC::Tuning::pageLength(isBinary)` (2048 binary,
+ *      256 JSON). Admin / unlimited-role clients may request larger pages.
+ *  - `binary` — boolean; when true, each entry is a hex-serialized blob
+ *      (`serializeHex`). When false (default), each entry is expanded JSON.
+ *  - `type` — optional string naming a `LedgerEntryType` to filter results
+ *      (e.g. `"offer"`, `"account"`). Omit or pass `ltANY` for all types.
+ *      An unrecognised type string returns `rpcINVALID_PARAMS`.
+ *
+ *  Response fields:
+ *  - `ledger_hash`, `ledger_index` — identity of the chosen ledger.
+ *  - `ledger` — full ledger header (JSON or binary). Present only on the
+ *      first page (no `marker` in the request) to avoid redundant data on
+ *      continuation calls.
+ *  - `state` — array of ledger entries for this page.
+ *  - `marker` — opaque resume token; absent when the scan is complete.
+ *
+ *  @note Pagination uses `upper_bound(key - 1)` fence-post arithmetic: when
+ *      the page limit is exhausted, `marker` is set to `sle->key() - 1` so
+ *      that the next `upper_bound` resumes on exactly that entry — no entry
+ *      is skipped or duplicated across page boundaries.
+ *  @note State entries are read via `keylet::unchecked`, which bypasses
+ *      keylet validation; this is safe because the keys originate from the
+ *      ledger's own state map rather than untrusted client input.
+ *  @param context  The dispatch envelope carrying request parameters,
+ *      application context, and role information.
+ *  @return JSON object containing the response or an error.
+ */
 json::Value
 doLedgerData(RPC::JsonContext& context)
 {
@@ -81,7 +111,6 @@ doLedgerData(RPC::JsonContext& context)
 
     if (!isMarker)
     {
-        // Return base ledger data on first query
         jvResult[jss::ledger] = getJson(LedgerFill(
             *lpLedger, &context, isBinary ? static_cast<int>(LedgerFill::Options::Binary) : 0));
     }
@@ -105,7 +134,6 @@ doLedgerData(RPC::JsonContext& context)
         auto sle = lpLedger->read(keylet::unchecked((*i)->key()));
         if (limit-- <= 0)
         {
-            // Stop processing before the current key.
             auto k = sle->key();
             jvResult[jss::marker] = to_string(--k);
             break;
@@ -130,6 +158,32 @@ doLedgerData(RPC::JsonContext& context)
     return jvResult;
 }
 
+/** Handle the `GetLedgerData` gRPC request.
+ *
+ *  Binary-only equivalent of `doLedgerData` for the gRPC transport. Every
+ *  SLE is serialized raw into the protobuf response via `Serializer::add`;
+ *  there is no JSON-format option.
+ *
+ *  Differences from the JSON path:
+ *  - Page size is always `RPC::Tuning::pageLength(true)` (2048); role-based
+ *    limit expansion is not available.
+ *  - Both a start key (`marker`) and an end key (`end_marker`) may be
+ *    supplied, bounding the scan from both sides. This allows callers to
+ *    partition the keyspace into disjoint ranges and parallelise state
+ *    downloads — a pattern absent from the JSON API.
+ *  - The resume marker is written as raw bytes into the response protobuf
+ *    rather than a JSON hex string.
+ *
+ *  Error mapping: `rpcINVALID_PARAMS` → `INVALID_ARGUMENT`; all other
+ *  failures → `NOT_FOUND`. A non-OK status discards the response object.
+ *
+ *  @note Like `doLedgerData`, entries are read via `keylet::unchecked` and
+ *      the fence-post `key - 1` marker arithmetic applies identically.
+ *  @param context  The gRPC dispatch envelope carrying the
+ *      `GetLedgerDataRequest` and application context.
+ *  @return A pair of `{GetLedgerDataResponse, grpc::Status}`. On error the
+ *      response is empty and the status carries the error detail.
+ */
 std::pair<org::xrpl::rpc::v1::GetLedgerDataResponse, grpc::Status>
 doLedgerDataGrpc(RPC::GRPCContext<org::xrpl::rpc::v1::GetLedgerDataRequest>& context)
 {
@@ -184,7 +238,6 @@ doLedgerDataGrpc(RPC::GRPCContext<org::xrpl::rpc::v1::GetLedgerDataRequest>& con
         auto sle = ledger->read(keylet::unchecked((*i)->key()));
         if (maxLimit-- <= 0)
         {
-            // Stop processing before the current key.
             auto k = sle->key();
             --k;
             response.set_marker(k.data(), k.size());
diff --git a/src/xrpld/rpc/handlers/ledger/LedgerDiff.cpp b/src/xrpld/rpc/handlers/ledger/LedgerDiff.cpp
index f1a9253de2..0c44d764c6 100644
--- a/src/xrpld/rpc/handlers/ledger/LedgerDiff.cpp
+++ b/src/xrpld/rpc/handlers/ledger/LedgerDiff.cpp
@@ -1,3 +1,12 @@
+/** @file
+ *  Implements the `GetLedgerDiff` gRPC handler (`doLedgerDiffGrpc`).
+ *
+ *  Computes the incremental SHAMap delta between two validated ledgers,
+ *  enabling light clients and indexers to track ledger state mutations
+ *  without replaying the full transaction set. See `GRPCHandlers.h` for
+ *  the full public contract.
+ */
+
 #include <xrpld/rpc/Context.h>
 #include <xrpld/rpc/GRPCHandlers.h>
 #include <xrpld/rpc/detail/RPCLedgerHelpers.h>
@@ -36,6 +45,10 @@ doLedgerDiffGrpc(RPC::GRPCContext<org::xrpl::rpc::v1::GetLedgerDiffRequest>& con
         return {response, errorStatus};
     }
 
+    // `ledgerFromSpecifier` can return a ReadView that is not a finalized
+    // Ledger (e.g., the currently-building open ledger). Only a concrete
+    // `Ledger` exposes `stateMap()`, so the downcast acts as a validation
+    // gate: a null result means the specifier resolved to an unvalidated view.
     std::shared_ptr<Ledger const> const baseLedger =
         std::dynamic_pointer_cast<Ledger const>(baseLedgerRv);
     if (!baseLedger)
@@ -54,6 +67,10 @@ doLedgerDiffGrpc(RPC::GRPCContext<org::xrpl::rpc::v1::GetLedgerDiffRequest>& con
 
     SHAMap::Delta differences;
 
+    // No practical cap: INT_MAX allows arbitrarily large diffs between
+    // distant ledgers. RESOURCE_EXHAUSTED is returned only if compare()
+    // somehow exhausts this limit, which guards against pathological
+    // SHAMap divergence bugs rather than normal operation.
     int const maxDifferences = std::numeric_limits<int>::max();
 
     bool const res =
@@ -65,15 +82,20 @@ doLedgerDiffGrpc(RPC::GRPCContext<org::xrpl::rpc::v1::GetLedgerDiffRequest>& con
         return {response, errorStatus};
     }
 
+    // Each SHAMap::Delta entry is a (base item, desired item) pair.
+    // A null desired item means the key was deleted; a null base item means
+    // it was added; both non-null means the serialized object changed.
+    // Only the desired-side blob is ever emitted — callers that need the
+    // old value of a modified key must fetch it separately.
     for (auto& [k, v] : differences)
     {
         auto diff = response.mutable_ledger_objects()->add_objects();
         auto inBase = v.first;
         auto inDesired = v.second;
 
-        // key does not exist in desired
         if (!inDesired)
         {
+            // Deleted key: emit the key with no data blob.
             diff->set_key(k.data(), k.size());
         }
         else
diff --git a/src/xrpld/rpc/handlers/ledger/LedgerEntry.cpp b/src/xrpld/rpc/handlers/ledger/LedgerEntry.cpp
index f07b7f2f06..5d29b0394e 100644
--- a/src/xrpld/rpc/handlers/ledger/LedgerEntry.cpp
+++ b/src/xrpld/rpc/handlers/ledger/LedgerEntry.cpp
@@ -1,3 +1,16 @@
+/** @file
+ *  Implements the `ledger_entry` RPC handler, which fetches a single ledger
+ *  state object (SLE) from a specified ledger by computing its `uint256` index
+ *  key from a semantic descriptor and returning it as JSON or raw binary.
+ *
+ *  Each supported entry type has a dedicated parser function that converts
+ *  the client-supplied JSON field into a `uint256` key via the appropriate
+ *  `keylet::*` constructor.  A static dispatch table built from the
+ *  `ledger_entries.macro` X-macro drives the central `doLedgerEntry` handler.
+ *
+ *  The parallel `doLedgerEntryGrpc` function performs the same lookup over
+ *  gRPC, accepting a raw 32-byte key and always returning serialized bytes.
+ */
 #include <xrpld/rpc/Context.h>
 #include <xrpld/rpc/GRPCHandlers.h>
 #include <xrpld/rpc/detail/RPCLedgerHelpers.h>
@@ -34,6 +47,17 @@
 
 namespace xrpl {
 
+/** Signature shared by all per-entry-type parser functions.
+ *
+ *  @param params     The JSON value for the entry descriptor field (or the
+ *      entire `context.params` object for the `bridge` special case).
+ *  @param fieldName  The `jss` name of the descriptor field, used in error
+ *      messages.
+ *  @param apiVersion The negotiated API version; controls error format and
+ *      accepted input shapes.
+ *  @return The computed `uint256` ledger-state key on success, or a
+ *      fully-formed error `Json::Value` on failure.
+ */
 using FunctionType = std::function<Expected<uint256, json::Value>(
     json::Value const&,
     json::StaticString const,
@@ -46,9 +70,16 @@ parseFixed(
     json::StaticString const& fieldName,
     unsigned const apiVersion);
 
-// Helper function to return FunctionType for objects that have a fixed
-// location. That is, they don't take parameters to compute the index.
-// e.g. amendments, fees, negative UNL, etc.
+/** Create a `FunctionType` parser for a singleton ledger object at a fixed key.
+ *
+ *  Singletons (Amendments, Fee Settings, Negative UNL) have well-known keys
+ *  that require no parameter derivation.  The returned lambda accepts either
+ *  `true` (fetch the singleton) or a raw hex string (direct key lookup) and
+ *  delegates to `parseFixed`.
+ *
+ *  @param keylet  The fixed `Keylet` whose key is captured into the lambda.
+ *  @return A `FunctionType` callable that resolves the singleton's key.
+ */
 static FunctionType
 fixed(Keylet const& keylet)
 {
@@ -60,6 +91,18 @@ fixed(Keylet const& keylet)
     };
 }
 
+/** Parse a `uint256` ledger-state key directly from a hex string.
+ *
+ *  Used as the fallback path in dual-form parsers when the caller supplies
+ *  a raw hex key instead of a semantic descriptor object.
+ *
+ *  @param params        The JSON value expected to be a 64-character hex string.
+ *  @param fieldName     The field name used in error messages.
+ *  @param expectedType  Human-readable description of the accepted value type,
+ *      used in error messages.
+ *  @return The parsed key on success, or an `rpcINVALID_PARAMS` error on
+ *      failure.
+ */
 static Expected<uint256, json::Value>
 parseObjectID(
     json::Value const& params,
@@ -73,6 +116,25 @@ parseObjectID(
     return LedgerEntryHelpers::invalidFieldError("malformedRequest", fieldName, expectedType);
 }
 
+/** Parse the `index` field, supporting direct hex keys and (API v3+) singleton aliases.
+ *
+ *  In API version 3 and later, the following plain string aliases are
+ *  recognised without knowing the underlying hash:
+ *  - `"amendments"` — the Amendments singleton.
+ *  - `"fee"` — the Fee Settings singleton.
+ *  - `"nunl"` — the Negative UNL singleton.
+ *  - `"hashes"` — the short skip list (hashes since the last flag ledger).
+ *
+ *  For all other values, or for API version ≤ 2, falls through to raw hex
+ *  parsing via `parseObjectID`.
+ *
+ *  @param params      The value of the `index` field in the request.
+ *  @param fieldName   Always `jss::index`; passed through to error messages.
+ *  @param apiVersion  Determines whether string aliases are accepted.
+ *  @return The resolved `uint256` key, or an `rpcINVALID_PARAMS` error.
+ *  @note The `"hashes"` alias resolves to the *short* skip list.  To fetch
+ *      the long (epoch-indexed) skip list, supply its raw hex key directly.
+ */
 static Expected<uint256, json::Value>
 parseIndex(json::Value const& params, json::StaticString const fieldName, unsigned const apiVersion)
 {
@@ -95,6 +157,16 @@ parseIndex(json::Value const& params, json::StaticString const fieldName, unsign
     return parseObjectID(params, fieldName, "hex string");
 }
 
+/** Compute the `AccountRoot` key for a given account address.
+ *
+ *  Accepts a Base58-encoded `AccountID` string and returns
+ *  `keylet::account(*account).key`.  Zero-value accounts are rejected.
+ *
+ *  @param params     The JSON string containing the Base58Check account address.
+ *  @param fieldName  Used in error messages; typically `jss::account_root`.
+ *  @param apiVersion Unused; present for uniform `FunctionType` signature.
+ *  @return The `uint256` key on success, or a `malformedAddress` error.
+ */
 static Expected<uint256, json::Value>
 parseAccountRoot(
     json::Value const& params,
@@ -109,8 +181,20 @@ parseAccountRoot(
     return LedgerEntryHelpers::invalidFieldError("malformedAddress", fieldName, "AccountID");
 }
 
+/** Parser for the Amendments singleton; delegates to `fixed(keylet::amendments())`. */
 auto const parseAmendments = fixed(keylet::amendments());
 
+/** Compute the AMM ledger-entry key from an asset pair or a raw hex key.
+ *
+ *  Accepts either a 64-character hex string (direct lookup) or a JSON object
+ *  with `asset` and `asset2` fields describing the two assets in the pool.
+ *  The pair is passed to `keylet::amm(*asset, *asset2)`.
+ *
+ *  @param params     Hex string or object with `asset` and `asset2`.
+ *  @param fieldName  Used in error messages.
+ *  @param apiVersion Unused; present for uniform `FunctionType` signature.
+ *  @return The `uint256` key, or an `rpcINVALID_PARAMS` error.
+ */
 static Expected<uint256, json::Value>
 parseAMM(
     json::Value const& params,
@@ -139,6 +223,27 @@ parseAMM(
     return keylet::amm(*asset, *asset2).key;
 }
 
+/** Compute the Bridge ledger-entry key from bridge specification fields.
+ *
+ *  Unlike every other parser, this function receives the **entire**
+ *  `context.params` object rather than a single sub-field, because it must
+ *  read two sibling fields: `bridge` (the bridge spec object) and
+ *  `bridge_account` (the door account used to select locking vs. issuing
+ *  chain side).
+ *
+ *  Accepts either:
+ *  - A hex string under `bridge` for a direct key lookup.
+ *  - A bridge specification object under `bridge` together with a
+ *    `bridge_account`; validates that the account matches one of the bridge's
+ *    door accounts, then computes `keylet::bridge(*bridge, chainType).key`.
+ *
+ *  @param params     The full `context.params` JSON object.
+ *  @param fieldName  Always `jss::bridge`; used in error messages.
+ *  @param apiVersion Unused; present for uniform `FunctionType` signature.
+ *  @return The `uint256` key, or an `rpcINVALID_PARAMS` error.
+ *  @note This parser is the only one in `doLedgerEntry`'s dispatch loop that
+ *      receives `context.params` rather than `context.params[fieldName]`.
+ */
 static Expected<uint256, json::Value>
 parseBridge(
     json::Value const& params,
@@ -172,6 +277,16 @@ parseBridge(
     return keylet::bridge(*bridge, chainType).key;
 }
 
+/** Compute the Check ledger-entry key from a raw hex string.
+ *
+ *  Check objects have no semantic constructor — clients must supply their
+ *  256-bit key directly.  Delegates unconditionally to `parseObjectID`.
+ *
+ *  @param params     A 64-character hex string.
+ *  @param fieldName  Used in error messages; typically `jss::check`.
+ *  @param apiVersion Unused; present for uniform `FunctionType` signature.
+ *  @return The `uint256` key, or an `rpcINVALID_PARAMS` error.
+ */
 static Expected<uint256, json::Value>
 parseCheck(
     json::Value const& params,
@@ -181,6 +296,19 @@ parseCheck(
     return parseObjectID(params, fieldName, "hex string");
 }
 
+/** Compute the Credential ledger-entry key from subject/issuer/type or a raw hex key.
+ *
+ *  Accepts either a 64-character hex string (direct lookup) or a JSON object
+ *  with `subject` (AccountID), `issuer` (AccountID), and `credential_type`
+ *  (hex blob, max `kMAX_CREDENTIAL_TYPE_LENGTH` bytes).  The semantic form
+ *  calls `keylet::credential(*subject, *issuer, credTypeSlice).key`.
+ *
+ *  @param cred       Hex string or object with `subject`, `issuer`, and
+ *      `credential_type` fields.
+ *  @param fieldName  Used in error messages.
+ *  @param apiVersion Unused; present for uniform `FunctionType` signature.
+ *  @return The `uint256` key, or an `rpcINVALID_PARAMS` error.
+ */
 static Expected<uint256, json::Value>
 parseCredential(
     json::Value const& cred,
@@ -210,6 +338,17 @@ parseCredential(
     return keylet::credential(*subject, *issuer, Slice(credType->data(), credType->size())).key;
 }
 
+/** Compute the Delegate ledger-entry key from account/authorize pair or a raw hex key.
+ *
+ *  Accepts either a 64-character hex string (direct lookup) or a JSON object
+ *  with `account` and `authorize` (both AccountIDs).  The semantic form calls
+ *  `keylet::delegate(*account, *authorize).key`.
+ *
+ *  @param params     Hex string or object with `account` and `authorize`.
+ *  @param fieldName  Used in error messages.
+ *  @param apiVersion Unused; present for uniform `FunctionType` signature.
+ *  @return The `uint256` key, or an `rpcINVALID_PARAMS` error.
+ */
 static Expected<uint256, json::Value>
 parseDelegate(
     json::Value const& params,
@@ -234,6 +373,20 @@ parseDelegate(
     return keylet::delegate(*account, *authorize).key;
 }
 
+/** Validate and deserialise an `authorized_credentials` JSON array into an `STArray`.
+ *
+ *  Each element must be a JSON object containing `issuer` (AccountID) and
+ *  `credential_type` (hex blob ≤ `kMAX_CREDENTIAL_TYPE_LENGTH` bytes).
+ *  The array must be non-empty and must not exceed `kMAX_CREDENTIALS_ARRAY_SIZE`
+ *  elements.
+ *
+ *  @param jv  The raw JSON array value from the request.
+ *  @return An `STArray` of `sfCredential` inner objects on success, or an
+ *      `rpcINVALID_PARAMS` error with a `malformedAuthorizedCredentials`
+ *      error code on failure.
+ *  @note The returned `STArray` is **unsorted**.  Callers must apply
+ *      `credentials::makeSorted` before computing the deposit-preauth keylet.
+ */
 static Expected<STArray, json::Value>
 parseAuthorizeCredentials(json::Value const& jv)
 {
@@ -299,6 +452,26 @@ parseAuthorizeCredentials(json::Value const& jv)
     return arr;
 }
 
+/** Compute the DepositPreauth ledger-entry key from owner/authorized pair or a raw hex key.
+ *
+ *  Accepts either a 64-character hex string (direct lookup) or a JSON object.
+ *  The object form requires `owner` (AccountID) plus **exactly one of**:
+ *  - `authorized` — a single authorized AccountID; uses
+ *    `keylet::depositPreauth(*owner, *authorized).key`.
+ *  - `authorized_credentials` — a JSON array processed by
+ *    `parseAuthorizeCredentials`; the resulting `STArray` is sorted via
+ *    `credentials::makeSorted` before the keylet is computed, so credentials
+ *    supplied in any order resolve to the same object.
+ *
+ *  @param dp         Hex string or object with `owner` and either `authorized`
+ *      or `authorized_credentials`.
+ *  @param fieldName  Used in error messages.
+ *  @param apiVersion Unused; present for uniform `FunctionType` signature.
+ *  @return The `uint256` key, or an `rpcINVALID_PARAMS` error.
+ *  @note An empty array after sorting is treated as a malformed input; this
+ *      guards against degenerate credential sets that produce a zero-length
+ *      canonical form.
+ */
 static Expected<uint256, json::Value>
 parseDepositPreauth(
     json::Value const& dp,
@@ -350,6 +523,17 @@ parseDepositPreauth(
     return keylet::depositPreauth(*owner, sorted).key;
 }
 
+/** Compute the DID ledger-entry key from an account address.
+ *
+ *  Accepts a Base58-encoded AccountID and calls `keylet::did(*account).key`.
+ *  Unlike `parseAccountRoot`, this parser accepts only the account string form
+ *  (no hex fallback).
+ *
+ *  @param params     A JSON string containing the Base58Check account address.
+ *  @param fieldName  Used in error messages.
+ *  @param apiVersion Unused; present for uniform `FunctionType` signature.
+ *  @return The `uint256` key, or a `malformedAddress` error.
+ */
 static Expected<uint256, json::Value>
 parseDID(
     json::Value const& params,
@@ -365,6 +549,22 @@ parseDID(
     return keylet::did(*account).key;
 }
 
+/** Compute a DirectoryNode ledger-entry key from an owner or root hash plus sub-index.
+ *
+ *  Accepts either a 64-character hex string (direct lookup) or a JSON object
+ *  with **exactly one of** `dir_root` or `owner`, plus an optional `sub_index`
+ *  (defaults to 0):
+ *  - `dir_root` (uint256 hex) — calls `keylet::page(*uDirRoot, uSubIndex).key`.
+ *  - `owner` (AccountID) — calls
+ *    `keylet::page(keylet::ownerDir(*ownerID), uSubIndex).key`.
+ *
+ *  @param params     Hex string, or object with `dir_root` or `owner` and
+ *      optional `sub_index`.
+ *  @param fieldName  Used in error messages.
+ *  @param apiVersion Unused; present for uniform `FunctionType` signature.
+ *  @return The `uint256` key, or an `rpcINVALID_PARAMS` error.
+ *  @note Supplying both `dir_root` and `owner`, or neither, is an error.
+ */
 static Expected<uint256, json::Value>
 parseDirectoryNode(
     json::Value const& params,
@@ -416,6 +616,18 @@ parseDirectoryNode(
     return LedgerEntryHelpers::malformedError("malformedRequest", "");
 }
 
+/** Compute the Escrow ledger-entry key from owner/sequence or a raw hex key.
+ *
+ *  Accepts either a 64-character hex string (direct lookup) or a JSON object
+ *  with `owner` (AccountID) and `seq` (uint32) corresponding to the sequence
+ *  number of the EscrowCreate transaction that created the escrow.  The
+ *  semantic form calls `keylet::escrow(*owner, *seq).key`.
+ *
+ *  @param params     Hex string or object with `owner` and `seq`.
+ *  @param fieldName  Used in error messages.
+ *  @param apiVersion Unused; present for uniform `FunctionType` signature.
+ *  @return The `uint256` key, or an `rpcINVALID_PARAMS` error.
+ */
 static Expected<uint256, json::Value>
 parseEscrow(
     json::Value const& params,
@@ -437,8 +649,22 @@ parseEscrow(
     return keylet::escrow(*id, *seq).key;
 }
 
+/** Parser for the Fee Settings singleton; delegates to `fixed(keylet::fees())`. */
 auto const parseFeeSettings = fixed(keylet::fees());
 
+/** Resolve the key for a singleton ledger object.
+ *
+ *  Accepts either `true` (boolean) to fetch the well-known singleton, or a
+ *  hex string for a direct key override.  A boolean `false` is rejected.
+ *  This function is not invoked directly — it is called from lambdas produced
+ *  by `fixed()`.
+ *
+ *  @param keylet     The singleton's fixed `Keylet`.
+ *  @param params     `true`, or a 64-character hex string.
+ *  @param fieldName  Used in error messages.
+ *  @param apiVersion Unused; present for consistency.
+ *  @return The singleton's `uint256` key, or an `rpcINVALID_PARAMS` error.
+ */
 static Expected<uint256, json::Value>
 parseFixed(
     Keylet const& keylet,
@@ -458,6 +684,19 @@ parseFixed(
     return keylet.key;
 }
 
+/** Compute the LedgerHashes (skip list) key from a ledger index or the short-list sentinel.
+ *
+ *  Accepts:
+ *  - An integer — returns `keylet::skip(index).key` for the long skip list
+ *    covering that ledger sequence range.
+ *  - A boolean `true` or hex string — delegates to `parseFixed(keylet::skip(), ...)`,
+ *    returning the key for the short skip list (hashes since the last flag ledger).
+ *
+ *  @param params      Integer ledger index, boolean `true`, or hex string.
+ *  @param fieldName   Used in error messages; typically `jss::hashes`.
+ *  @param apiVersion  Forwarded to `parseFixed` for the non-integer path.
+ *  @return The `uint256` key, or an `rpcINVALID_PARAMS` error.
+ */
 static Expected<uint256, json::Value>
 parseLedgerHashes(
     json::Value const& params,
@@ -478,6 +717,17 @@ parseLedgerHashes(
     return parseFixed(keylet::skip(), params, fieldName, apiVersion);
 }
 
+/** Compute the LoanBroker ledger-entry key from owner/sequence or a raw hex key.
+ *
+ *  Accepts either a 64-character hex string (direct lookup) or a JSON object
+ *  with `owner` (AccountID) and `seq` (uint32).  The semantic form calls
+ *  `keylet::loanbroker(*owner, *seq).key`.
+ *
+ *  @param params     Hex string or object with `owner` and `seq`.
+ *  @param fieldName  Used in error messages.
+ *  @param apiVersion Unused; present for uniform `FunctionType` signature.
+ *  @return The `uint256` key, or an `rpcINVALID_PARAMS` error.
+ */
 static Expected<uint256, json::Value>
 parseLoanBroker(
     json::Value const& params,
@@ -499,6 +749,17 @@ parseLoanBroker(
     return keylet::loanbroker(*id, *seq).key;
 }
 
+/** Compute the Loan ledger-entry key from broker ID/sequence or a raw hex key.
+ *
+ *  Accepts either a 64-character hex string (direct lookup) or a JSON object
+ *  with `loan_broker_id` (uint256) and `loan_seq` (uint32).  The semantic
+ *  form calls `keylet::loan(*loanBrokerID, *loanSeq).key`.
+ *
+ *  @param params     Hex string or object with `loan_broker_id` and `loan_seq`.
+ *  @param fieldName  Used in error messages.
+ *  @param apiVersion Unused; present for uniform `FunctionType` signature.
+ *  @return The `uint256` key, or an `rpcINVALID_PARAMS` error.
+ */
 static Expected<uint256, json::Value>
 parseLoan(
     json::Value const& params,
@@ -521,6 +782,17 @@ parseLoan(
     return keylet::loan(*id, *seq).key;
 }
 
+/** Compute the MPToken ledger-entry key from issuance ID/account or a raw hex key.
+ *
+ *  Accepts either a 64-character hex string (direct lookup) or a JSON object
+ *  with `mpt_issuance_id` (uint192 hex) and `account` (AccountID).  The
+ *  semantic form calls `keylet::mptoken(*mptIssuanceID, *account).key`.
+ *
+ *  @param params     Hex string or object with `mpt_issuance_id` and `account`.
+ *  @param fieldName  Used in error messages.
+ *  @param apiVersion Unused; present for uniform `FunctionType` signature.
+ *  @return The `uint256` key, or an `rpcINVALID_PARAMS` error.
+ */
 static Expected<uint256, json::Value>
 parseMPToken(
     json::Value const& params,
@@ -545,6 +817,17 @@ parseMPToken(
     return keylet::mptoken(*mptIssuanceID, *account).key;
 }
 
+/** Compute the MPTokenIssuance ledger-entry key from a uint192 issuance ID.
+ *
+ *  Accepts only a 48-character hex string encoding the 192-bit MPT issuance
+ *  ID; there is no structured-object alternative.  Calls
+ *  `keylet::mptIssuance(*mptIssuanceID).key`.
+ *
+ *  @param params     A 48-character hex string (192-bit issuance ID).
+ *  @param fieldName  Used in error messages.
+ *  @param apiVersion Unused; present for uniform `FunctionType` signature.
+ *  @return The `uint256` key, or a `malformedMPTokenIssuance` error.
+ */
 static Expected<uint256, json::Value>
 parseMPTokenIssuance(
     json::Value const& params,
@@ -561,6 +844,16 @@ parseMPTokenIssuance(
     return keylet::mptIssuance(*mptIssuanceID).key;
 }
 
+/** Compute the NFTokenOffer ledger-entry key from a raw hex key.
+ *
+ *  NFTokenOffer objects have no semantic constructor — clients must supply
+ *  the 256-bit key directly.  Delegates unconditionally to `parseObjectID`.
+ *
+ *  @param params     A 64-character hex string.
+ *  @param fieldName  Used in error messages.
+ *  @param apiVersion Unused; present for uniform `FunctionType` signature.
+ *  @return The `uint256` key, or an `rpcINVALID_PARAMS` error.
+ */
 static Expected<uint256, json::Value>
 parseNFTokenOffer(
     json::Value const& params,
@@ -570,6 +863,16 @@ parseNFTokenOffer(
     return parseObjectID(params, fieldName, "hex string");
 }
 
+/** Compute the NFTokenPage ledger-entry key from a raw hex key.
+ *
+ *  NFTokenPage objects have no semantic constructor — clients must supply
+ *  the 256-bit key directly.  Delegates unconditionally to `parseObjectID`.
+ *
+ *  @param params     A 64-character hex string.
+ *  @param fieldName  Used in error messages.
+ *  @param apiVersion Unused; present for uniform `FunctionType` signature.
+ *  @return The `uint256` key, or an `rpcINVALID_PARAMS` error.
+ */
 static Expected<uint256, json::Value>
 parseNFTokenPage(
     json::Value const& params,
@@ -579,8 +882,21 @@ parseNFTokenPage(
     return parseObjectID(params, fieldName, "hex string");
 }
 
+/** Parser for the Negative UNL singleton; delegates to `fixed(keylet::negativeUNL())`. */
 auto const parseNegativeUNL = fixed(keylet::negativeUNL());
 
+/** Compute the Offer ledger-entry key from account/sequence or a raw hex key.
+ *
+ *  Accepts either a 64-character hex string (direct lookup) or a JSON object
+ *  with `account` (AccountID) and `seq` (uint32) — the sequence number of the
+ *  OfferCreate transaction.  The semantic form calls
+ *  `keylet::offer(*account, *seq).key`.
+ *
+ *  @param params     Hex string or object with `account` and `seq`.
+ *  @param fieldName  Used in error messages.
+ *  @param apiVersion Unused; present for uniform `FunctionType` signature.
+ *  @return The `uint256` key, or an `rpcINVALID_PARAMS` error.
+ */
 static Expected<uint256, json::Value>
 parseOffer(
     json::Value const& params,
@@ -603,6 +919,17 @@ parseOffer(
     return keylet::offer(*id, *seq).key;
 }
 
+/** Compute the Oracle ledger-entry key from account/document-ID or a raw hex key.
+ *
+ *  Accepts either a 64-character hex string (direct lookup) or a JSON object
+ *  with `account` (AccountID) and `oracle_document_id` (uint32).  The semantic
+ *  form calls `keylet::oracle(*account, *oracleDocumentID).key`.
+ *
+ *  @param params     Hex string or object with `account` and `oracle_document_id`.
+ *  @param fieldName  Used in error messages.
+ *  @param apiVersion Unused; present for uniform `FunctionType` signature.
+ *  @return The `uint256` key, or an `rpcINVALID_PARAMS` error.
+ */
 static Expected<uint256, json::Value>
 parseOracle(
     json::Value const& params,
@@ -626,6 +953,16 @@ parseOracle(
     return keylet::oracle(*id, *seq).key;
 }
 
+/** Compute the PayChannel ledger-entry key from a raw hex key.
+ *
+ *  PayChannel objects have no semantic constructor — clients must supply the
+ *  256-bit key directly.  Delegates unconditionally to `parseObjectID`.
+ *
+ *  @param params     A 64-character hex string.
+ *  @param fieldName  Used in error messages.
+ *  @param apiVersion Unused; present for uniform `FunctionType` signature.
+ *  @return The `uint256` key, or an `rpcINVALID_PARAMS` error.
+ */
 static Expected<uint256, json::Value>
 parsePayChannel(
     json::Value const& params,
@@ -635,6 +972,17 @@ parsePayChannel(
     return parseObjectID(params, fieldName, "hex string");
 }
 
+/** Compute the PermissionedDomain ledger-entry key from account/sequence or a raw hex key.
+ *
+ *  Accepts either a 64-character hex string (direct lookup) or a JSON object
+ *  with `account` (AccountID) and `seq` (uint32).  The semantic form calls
+ *  `keylet::permissionedDomain(*account, *seq).key`.
+ *
+ *  @param pd         Hex string or object with `account` and `seq`.
+ *  @param fieldName  Used in error messages.
+ *  @param apiVersion Unused; present for uniform `FunctionType` signature.
+ *  @return The `uint256` key, or an `rpcINVALID_PARAMS` error.
+ */
 static Expected<uint256, json::Value>
 parsePermissionedDomain(
     json::Value const& pd,
@@ -664,6 +1012,20 @@ parsePermissionedDomain(
     return keylet::permissionedDomain(*account, pd[jss::seq].asUInt()).key;
 }
 
+/** Compute the RippleState (trust-line) ledger-entry key from accounts/currency or a raw hex key.
+ *
+ *  Accepts either a 64-character hex string (direct lookup) or a JSON object
+ *  with `accounts` (a 2-element array of AccountIDs) and `currency` (a currency
+ *  code string).  The semantic form calls
+ *  `keylet::line(*id1, *id2, uCurrency).key`.
+ *
+ *  @param jvRippleState  Hex string or object with `accounts` and `currency`.
+ *  @param fieldName      Used in error messages; typically `jss::ripple_state`.
+ *  @param apiVersion     Unused; present for uniform `FunctionType` signature.
+ *  @return The `uint256` key, or an `rpcINVALID_PARAMS` error.
+ *  @note Both accounts in the array must be distinct — a trust-line to self
+ *      is rejected with `"Cannot have a trustline to self."`.
+ */
 static Expected<uint256, json::Value>
 parseRippleState(
     json::Value const& jvRippleState,
@@ -713,6 +1075,16 @@ parseRippleState(
     return keylet::line(*id1, *id2, uCurrency).key;
 }
 
+/** Compute the SignerList ledger-entry key from a raw hex key.
+ *
+ *  SignerList objects have no semantic constructor — clients must supply the
+ *  256-bit key directly.  Delegates unconditionally to `parseObjectID`.
+ *
+ *  @param params     A 64-character hex string.
+ *  @param fieldName  Used in error messages.
+ *  @param apiVersion Unused; present for uniform `FunctionType` signature.
+ *  @return The `uint256` key, or an `rpcINVALID_PARAMS` error.
+ */
 static Expected<uint256, json::Value>
 parseSignerList(
     json::Value const& params,
@@ -722,6 +1094,18 @@ parseSignerList(
     return parseObjectID(params, fieldName, "hex string");
 }
 
+/** Compute the Ticket ledger-entry key from account/ticket-sequence or a raw hex key.
+ *
+ *  Accepts either a 64-character hex string (direct lookup) or a JSON object
+ *  with `account` (AccountID) and `ticket_seq` (uint32 — the sequence number
+ *  reserved for the ticket).  The semantic form calls
+ *  `getTicketIndex(*account, *ticketSeq)`.
+ *
+ *  @param params     Hex string or object with `account` and `ticket_seq`.
+ *  @param fieldName  Used in error messages.
+ *  @param apiVersion Unused; present for uniform `FunctionType` signature.
+ *  @return The `uint256` key, or an `rpcINVALID_PARAMS` error.
+ */
 static Expected<uint256, json::Value>
 parseTicket(
     json::Value const& params,
@@ -745,6 +1129,17 @@ parseTicket(
     return getTicketIndex(*id, *seq);
 }
 
+/** Compute the Vault ledger-entry key from owner/sequence or a raw hex key.
+ *
+ *  Accepts either a 64-character hex string (direct lookup) or a JSON object
+ *  with `owner` (AccountID) and `seq` (uint32).  The semantic form calls
+ *  `keylet::vault(*owner, *seq).key`.
+ *
+ *  @param params     Hex string or object with `owner` and `seq`.
+ *  @param fieldName  Used in error messages.
+ *  @param apiVersion Unused; present for uniform `FunctionType` signature.
+ *  @return The `uint256` key, or an `rpcINVALID_PARAMS` error.
+ */
 static Expected<uint256, json::Value>
 parseVault(
     json::Value const& params,
@@ -767,6 +1162,20 @@ parseVault(
     return keylet::vault(*id, *seq).key;
 }
 
+/** Compute the XChainOwnedClaimID ledger-entry key from a bridge spec/sequence or a raw hex key.
+ *
+ *  Accepts either a 64-character hex string (direct lookup) or a JSON object
+ *  containing full bridge specification fields (LockingChainDoor,
+ *  LockingChainIssue, IssuingChainDoor, IssuingChainIssue) plus
+ *  `xchain_owned_claim_id` (uint32).  The semantic form calls
+ *  `keylet::xChainClaimID(*bridgeSpec, *seq).key`.
+ *
+ *  @param claimId    Hex string or object with bridge fields and
+ *      `xchain_owned_claim_id`.
+ *  @param fieldName  Used in error messages.
+ *  @param apiVersion Unused; present for uniform `FunctionType` signature.
+ *  @return The `uint256` key, or an `rpcINVALID_PARAMS` error.
+ */
 static Expected<uint256, json::Value>
 parseXChainOwnedClaimID(
     json::Value const& claimId,
@@ -793,6 +1202,19 @@ parseXChainOwnedClaimID(
     return keylet.key;
 }
 
+/** Compute the XChainOwnedCreateAccountClaimID key from a bridge spec/sequence or a raw hex key.
+ *
+ *  Accepts either a 64-character hex string (direct lookup) or a JSON object
+ *  containing full bridge specification fields plus
+ *  `xchain_owned_create_account_claim_id` (uint32).  The semantic form calls
+ *  `keylet::xChainCreateAccountClaimID(*bridgeSpec, *seq).key`.
+ *
+ *  @param claimId    Hex string or object with bridge fields and
+ *      `xchain_owned_create_account_claim_id`.
+ *  @param fieldName  Used in error messages.
+ *  @param apiVersion Unused; present for uniform `FunctionType` signature.
+ *  @return The `uint256` key, or an `rpcINVALID_PARAMS` error.
+ */
 static Expected<uint256, json::Value>
 parseXChainOwnedCreateAccountClaimID(
     json::Value const& claimId,
@@ -821,6 +1243,18 @@ parseXChainOwnedCreateAccountClaimID(
     return keylet.key;
 }
 
+/** Dispatch table entry mapping a JSON field name to its parser and expected SLE type.
+ *
+ *  The static array `kLEDGER_ENTRY_PARSERS` in `doLedgerEntry` is populated
+ *  from the `ledger_entries.macro` X-macro plus a small set of hand-appended
+ *  aliases.  Each entry binds:
+ *  - `fieldName` — the top-level JSON key that triggers this parser.
+ *  - `parseFunction` — a `FunctionType` callable that derives the `uint256`
+ *    ledger-state key from the field's value.
+ *  - `expectedType` — the `LedgerEntryType` against which the fetched SLE is
+ *    validated; `ltANY` skips the type check (used for `index` and generic
+ *    hex-key paths).
+ */
 struct LedgerEntry
 {
     json::StaticString fieldName;
@@ -828,11 +1262,33 @@ struct LedgerEntry
     LedgerEntryType expectedType;
 };
 
-// {
-//   ledger_hash : <ledger>
-//   ledger_index : <ledger_index>
-//   ...
-// }
+/** Handle the `ledger_entry` JSON-RPC command.
+ *
+ *  Resolves a single ledger state object (SLE) from a caller-specified ledger.
+ *  The request must contain exactly one entry-type descriptor field (e.g.
+ *  `offer`, `ripple_state`, `index`, etc.) whose value is passed to the
+ *  corresponding parser to derive the `uint256` state-tree key.  The SLE is
+ *  then fetched from the `ReadView` and returned either as JSON (`node`) or
+ *  as a hex-encoded serialized blob (`node_binary`) when `binary: true`.
+ *
+ *  The dispatch table (`kLEDGER_ENTRY_PARSERS`) is a static `std::array`
+ *  built from the `ledger_entries.macro` X-macro, ensuring that every
+ *  ledger entry type defined in the protocol is automatically handled.
+ *  Two backward-compatible aliases (`account_root`, `ripple_state`) and the
+ *  generic `index` entry are appended by hand after the macro block.
+ *
+ *  @param context  The JSON-RPC context, including params and API version.
+ *  @return A `Json::Value` object containing the SLE data, or an error.
+ *  @note `index` is always included in the response, even when the SLE is
+ *      not found, so clients can confirm which key was queried.
+ *  @note When the fetched SLE's type does not match the `expectedType` of the
+ *      matched dispatch entry (and `expectedType` is not `ltANY`), the handler
+ *      returns `rpcUNEXPECTED_LEDGER_TYPE`.  This prevents a client from
+ *      receiving the wrong object type when supplying a raw hex key.
+ *  @note For API v1, unrecognised fields produce `error: "unknownOption"` and
+ *      `Json::Error` exceptions are re-thrown.  For API v2+, both conditions
+ *      are translated to structured `rpcINVALID_PARAMS` responses.
+ */
 json::Value
 doLedgerEntry(RPC::JsonContext& context)
 {
@@ -976,6 +1432,20 @@ doLedgerEntry(RPC::JsonContext& context)
     return jvResult;
 }
 
+/** Handle the `GetLedgerEntry` gRPC request.
+ *
+ *  Stripped-down counterpart to `doLedgerEntry`.  Accepts a raw 32-byte key
+ *  from the protobuf request (no semantic parsing), resolves the target ledger
+ *  via `RPC::ledgerFromRequest`, fetches the SLE, and returns it serialized
+ *  with a `Serializer`.  There is no JSON/binary toggle and no type validation
+ *  — the gRPC path always returns raw bytes.
+ *
+ *  @param context  The gRPC context wrapping a `GetLedgerEntryRequest`.
+ *  @return A pair of `(GetLedgerEntryResponse, grpc::Status)`.  On any error
+ *      the response object is empty and the status is non-OK:
+ *      `INVALID_ARGUMENT` for bad parameters or a malformed key, `NOT_FOUND`
+ *      for an unknown ledger or a missing SLE.
+ */
 std::pair<org::xrpl::rpc::v1::GetLedgerEntryResponse, grpc::Status>
 doLedgerEntryGrpc(RPC::GRPCContext<org::xrpl::rpc::v1::GetLedgerEntryRequest>& context)
 {
diff --git a/src/xrpld/rpc/handlers/ledger/LedgerEntryHelpers.h b/src/xrpld/rpc/handlers/ledger/LedgerEntryHelpers.h
index e8e295ca2c..fdc1482602 100644
--- a/src/xrpld/rpc/handlers/ledger/LedgerEntryHelpers.h
+++ b/src/xrpld/rpc/handlers/ledger/LedgerEntryHelpers.h
@@ -1,3 +1,15 @@
+/** @file
+ *  Private JSON parsing and error-construction utilities for the
+ *  `ledger_entry` RPC handler.
+ *
+ *  This header is intentionally included only by `LedgerEntry.cpp`.
+ *  All functions are `inline` because there is a single consumer and no
+ *  ODR risk.  The `Expected<T, Json::Value>` return discipline lets every
+ *  per-type parse function propagate failures via the uniform
+ *  `if (!result) return Unexpected(result.error())` idiom rather than
+ *  throwing.
+ */
+
 #include <xrpld/rpc/detail/RPCHelpers.h>
 
 #include <xrpl/basics/StringUtilities.h>
@@ -12,8 +24,25 @@
 
 #include <functional>
 
+/** Low-level JSON parsing and validation vocabulary for `ledger_entry`.
+ *
+ *  Provides the `parse<T>()` template family, the `required<T>()` combinator,
+ *  concrete typed wrappers (`requiredAccountID`, `requiredUInt32`, …), three
+ *  error builders (`missingFieldError`, `invalidFieldError`, `malformedError`),
+ *  and the `parseBridgeFields` helper used by all XChainBridge-related object
+ *  parsers.  All errors carry `rpcINVALID_PARAMS` and return
+ *  `Unexpected<Json::Value>` compatible with `Expected<T, Json::Value>`.
+ */
 namespace xrpl::LedgerEntryHelpers {
 
+/** Build a `rpcINVALID_PARAMS` error for a field that is absent or null.
+ *
+ *  @param field The JSON field name that was missing.
+ *  @param err   Optional error code string; defaults to `"malformedRequest"`.
+ *      Pass a domain-specific code (e.g. `"malformedLockingChainDoor"`) when
+ *      a more precise code is useful for the caller.
+ *  @return An `Unexpected<Json::Value>` carrying the error object.
+ */
 inline Unexpected<json::Value>
 missingFieldError(json::StaticString const field, std::optional<std::string> err = std::nullopt)
 {
@@ -24,6 +53,16 @@ missingFieldError(json::StaticString const field, std::optional<std::string> err
     return Unexpected(json);
 }
 
+/** Build a `rpcINVALID_PARAMS` error for a field whose value failed parsing.
+ *
+ *  The `error_message` is constructed by `RPC::expectedFieldMessage`, which
+ *  produces a human-readable sentence naming `field` and the expected `type`.
+ *
+ *  @param err   Domain-specific error code string (e.g. `"malformedAddress"`).
+ *  @param field The JSON field name whose value was invalid.
+ *  @param type  Human-readable expected type (e.g. `"AccountID"`, `"Hash256"`).
+ *  @return An `Unexpected<Json::Value>` carrying the error object.
+ */
 inline Unexpected<json::Value>
 invalidFieldError(std::string const& err, json::StaticString const field, std::string const& type)
 {
@@ -34,6 +73,16 @@ invalidFieldError(std::string const& err, json::StaticString const field, std::s
     return Unexpected(json);
 }
 
+/** Build a `rpcINVALID_PARAMS` error with fully caller-defined code and message.
+ *
+ *  Use when the failure is semantic rather than a simple missing-or-wrong-type
+ *  situation — for example, "Cannot have a trustline to self." or "Must have
+ *  exactly one of `owner` and `dir_root` fields."
+ *
+ *  @param err     Error code string (e.g. `"malformedRequest"`).
+ *  @param message Full human-readable error_message string.
+ *  @return An `Unexpected<Json::Value>` carrying the error object.
+ */
 inline Unexpected<json::Value>
 malformedError(std::string const& err, std::string const& message)
 {
@@ -44,6 +93,20 @@ malformedError(std::string const& err, std::string const& message)
     return Unexpected(json);
 }
 
+/** Pre-flight check that all listed fields are present and non-null.
+ *
+ *  Iterates `fields` and short-circuits on the first absent or null entry,
+ *  returning the corresponding `missingFieldError`.  Used as a guard before
+ *  individual field extraction in parsers that need several fields before any
+ *  one of them is useful (e.g. `parseAMM`, `parseRippleState`,
+ *  `parseBridgeFields`, `parseAuthorizeCredentials`).
+ *
+ *  @param params The JSON object to inspect.
+ *  @param fields The required field names, checked in order.
+ *  @param err    Optional error code override forwarded to `missingFieldError`.
+ *  @return `true` wrapped in `Expected` if all fields are present; otherwise
+ *      an `Unexpected` carrying the first missing-field error.
+ */
 inline Expected<bool, json::Value>
 hasRequired(
     json::Value const& params,
@@ -60,10 +123,39 @@ hasRequired(
     return true;
 }
 
+/** Try to decode a JSON value into type `T`.
+ *
+ *  Declared here; only the explicit specializations for `AccountID`,
+ *  `uint256`, `uint192`, `std::uint32_t`, and `Asset` are provided.
+ *  Returns `std::nullopt` on any parse failure with no error detail, keeping
+ *  the function pure and composable for callers that probe multiple types
+ *  before committing (e.g. `parseDirectoryNode` tries `uint256` before
+ *  `AccountID`).
+ *
+ *  @tparam T    The target type.  Must have an explicit specialization.
+ *  @param param The JSON value to decode.
+ *  @return The decoded value, or `std::nullopt` on failure.
+ */
 template <class T>
 std::optional<T>
 parse(json::Value const& param);
 
+/** Extract a required field from a JSON object, returning an error on failure.
+ *
+ *  Combines a presence check with `parse<T>()`: if the field is absent or
+ *  null, returns `missingFieldError`; if present but unparseable, returns
+ *  `invalidFieldError` using `expectedType` as the human-readable type name.
+ *  Concrete wrappers (`requiredAccountID`, `requiredUInt32`, etc.) supply the
+ *  `err` and `expectedType` strings so callers need not repeat them.
+ *
+ *  @tparam T           The target type; must have a `parse<T>` specialization.
+ *  @param params       The JSON object containing the field.
+ *  @param fieldName    The key to look up in `params`.
+ *  @param err          Error code string emitted on a type mismatch.
+ *  @param expectedType Human-readable type string (e.g. `"AccountID"`)
+ *      embedded in the `error_message` on type mismatch.
+ *  @return The decoded value, or an `Unexpected` error object.
+ */
 template <class T>
 Expected<T, json::Value>
 required(
@@ -83,6 +175,16 @@ required(
     return invalidFieldError(err, fieldName, expectedType);
 }
 
+/** Decode a Base58-encoded `AccountID` from a JSON string.
+ *
+ *  Rejects the all-zero account ID (`isZero()` guard) because that sentinel
+ *  value cannot correspond to a real account and would otherwise produce a
+ *  silently incorrect keylet.
+ *
+ *  @param param JSON value expected to be a Base58Check account string.
+ *  @return The decoded `AccountID`, or `std::nullopt` if the value is not a
+ *      string, fails Base58 decoding, or is the zero account.
+ */
 template <>
 inline std::optional<AccountID>
 parse(json::Value const& param)
@@ -99,6 +201,14 @@ parse(json::Value const& param)
     return account;
 }
 
+/** Extract a required `AccountID` field, returning `rpcINVALID_PARAMS` on failure.
+ *
+ *  @param params    The JSON object containing the field.
+ *  @param fieldName The key to look up.
+ *  @param err       Error code string emitted on type mismatch or zero account.
+ *  @return The decoded `AccountID`, or an `Unexpected` error object.
+ *  @see parse<AccountID>
+ */
 inline Expected<AccountID, json::Value>
 requiredAccountID(
     json::Value const& params,
@@ -108,6 +218,17 @@ requiredAccountID(
     return required<AccountID>(params, fieldName, err, "AccountID");
 }
 
+/** Decode a hex-encoded byte blob from a JSON string, enforcing a length cap.
+ *
+ *  Not part of the `parse<T>()` template family because it takes an extra
+ *  `maxLength` parameter.  The credential-type field, for instance, is
+ *  length-bounded by protocol rules.
+ *
+ *  @param param     JSON value expected to be a hex string.
+ *  @param maxLength Maximum number of decoded bytes accepted.
+ *  @return The decoded blob, or `std::nullopt` if the value is not a string,
+ *      fails hex decoding, decodes to an empty blob, or exceeds `maxLength`.
+ */
 inline std::optional<Blob>
 parseHexBlob(json::Value const& param, std::size_t maxLength)
 {
@@ -121,6 +242,16 @@ parseHexBlob(json::Value const& param, std::size_t maxLength)
     return blob;
 }
 
+/** Extract a required hex-blob field, returning `rpcINVALID_PARAMS` on failure.
+ *
+ *  @param params    The JSON object containing the field.
+ *  @param fieldName The key to look up.
+ *  @param maxLength Maximum number of decoded bytes accepted.
+ *  @param err       Error code string emitted when the blob is malformed or
+ *      out of range.
+ *  @return The decoded blob, or an `Unexpected` error object.
+ *  @see parseHexBlob
+ */
 inline Expected<Blob, json::Value>
 requiredHexBlob(
     json::Value const& params,
@@ -139,6 +270,17 @@ requiredHexBlob(
     return invalidFieldError(err, fieldName, "hex string");
 }
 
+/** Decode a `uint32_t` from a JSON unsigned, positive signed integer, or string.
+ *
+ *  Accepts a JSON string form (e.g. `"42"`) via `beast::lexicalCastChecked`
+ *  to accommodate clients that serialize numbers as strings.  Negative signed
+ *  integers are rejected cleanly.
+ *
+ *  @param param JSON value: unsigned integer, non-negative signed integer, or
+ *      decimal string representation.
+ *  @return The decoded value, or `std::nullopt` on type mismatch or negative
+ *      value.
+ */
 template <>
 inline std::optional<std::uint32_t>
 parse(json::Value const& param)
@@ -156,6 +298,14 @@ parse(json::Value const& param)
     return std::nullopt;
 }
 
+/** Extract a required `uint32_t` field, returning `rpcINVALID_PARAMS` on failure.
+ *
+ *  @param params    The JSON object containing the field.
+ *  @param fieldName The key to look up.
+ *  @param err       Error code string emitted on type mismatch.
+ *  @return The decoded value, or an `Unexpected` error object.
+ *  @see parse<std::uint32_t>
+ */
 inline Expected<std::uint32_t, json::Value>
 requiredUInt32(
     json::Value const& params,
@@ -165,6 +315,12 @@ requiredUInt32(
     return required<std::uint32_t>(params, fieldName, err, "number");
 }
 
+/** Decode a 256-bit hash from a hex JSON string.
+ *
+ *  @param param JSON string containing a 64-character hex hash.
+ *  @return The decoded `uint256`, or `std::nullopt` if the value is not a
+ *      string or fails hex parsing.
+ */
 template <>
 inline std::optional<uint256>
 parse(json::Value const& param)
@@ -178,6 +334,13 @@ parse(json::Value const& param)
     return uNodeIndex;
 }
 
+/** Extract a required `uint256` (Hash256) field, returning `rpcINVALID_PARAMS` on failure.
+ *
+ *  @param params    The JSON object containing the field.
+ *  @param fieldName The key to look up.
+ *  @param err       Error code string emitted on type mismatch.
+ *  @return The decoded hash, or an `Unexpected` error object.
+ */
 inline Expected<uint256, json::Value>
 requiredUInt256(
     json::Value const& params,
@@ -187,6 +350,15 @@ requiredUInt256(
     return required<uint256>(params, fieldName, err, "Hash256");
 }
 
+/** Decode a 192-bit value from a hex JSON string.
+ *
+ *  Used for MPT issuance IDs (`mpt_issuance_id`), which are 24-byte (192-bit)
+ *  identifiers.
+ *
+ *  @param param JSON string containing a 48-character hex value.
+ *  @return The decoded `uint192`, or `std::nullopt` if the value is not a
+ *      string or fails hex parsing.
+ */
 template <>
 inline std::optional<uint192>
 parse(json::Value const& param)
@@ -200,6 +372,14 @@ parse(json::Value const& param)
     return field;
 }
 
+/** Extract a required `uint192` (Hash192 / MPT issuance ID) field, returning
+ *  `rpcINVALID_PARAMS` on failure.
+ *
+ *  @param params    The JSON object containing the field.
+ *  @param fieldName The key to look up.
+ *  @param err       Error code string emitted on type mismatch.
+ *  @return The decoded value, or an `Unexpected` error object.
+ */
 inline Expected<uint192, json::Value>
 requiredUInt192(
     json::Value const& params,
@@ -209,6 +389,15 @@ requiredUInt192(
     return required<uint192>(params, fieldName, err, "Hash192");
 }
 
+/** Decode an `Asset` (XRP, IOU issue, or MPT) from a JSON value.
+ *
+ *  Delegates to `assetFromJson`, which throws `std::runtime_error` on
+ *  malformed input; the exception is caught here and converted to
+ *  `std::nullopt` so callers see a uniform optional interface.
+ *
+ *  @param param JSON object or string describing the asset.
+ *  @return The decoded `Asset`, or `std::nullopt` on any parse failure.
+ */
 template <>
 inline std::optional<Asset>
 parse(json::Value const& param)
@@ -223,12 +412,35 @@ parse(json::Value const& param)
     }
 }
 
+/** Extract a required `Asset` field, returning `rpcINVALID_PARAMS` on failure.
+ *
+ *  @param params    The JSON object containing the field.
+ *  @param fieldName The key to look up.
+ *  @param err       Error code string emitted on type mismatch.
+ *  @return The decoded `Asset`, or an `Unexpected` error object.
+ */
 inline Expected<Asset, json::Value>
 requiredAsset(json::Value const& params, json::StaticString const fieldName, std::string const& err)
 {
     return required<Asset>(params, fieldName, err, "Asset");
 }
 
+/** Assemble an `STXChainBridge` from a JSON object containing the four
+ *  canonical cross-chain bridge sub-fields.
+ *
+ *  Expects `params` to carry:
+ *  - `LockingChainDoor` and `IssuingChainDoor` — `AccountID` strings.
+ *  - `LockingChainIssue` and `IssuingChainIssue` — `Issue` objects decoded
+ *    via `issueFromJson`, which throws `std::runtime_error` on malformed
+ *    input; the exception is caught and converted to `invalidFieldError`.
+ *
+ *  Reused by `parseBridge`, `parseXChainOwnedClaimID`, and
+ *  `parseXChainOwnedCreateAccountClaimID` in `LedgerEntry.cpp`.
+ *
+ *  @param params JSON object with the four bridge sub-fields.
+ *  @return The constructed `STXChainBridge`, or an `Unexpected` error object
+ *      if any sub-field is absent, null, or unparseable.
+ */
 inline Expected<STXChainBridge, json::Value>
 parseBridgeFields(json::Value const& params)
 {
diff --git a/src/xrpld/rpc/handlers/ledger/LedgerHeader.cpp b/src/xrpld/rpc/handlers/ledger/LedgerHeader.cpp
index e2cb80615b..84b9ce7723 100644
--- a/src/xrpld/rpc/handlers/ledger/LedgerHeader.cpp
+++ b/src/xrpld/rpc/handlers/ledger/LedgerHeader.cpp
@@ -1,3 +1,10 @@
+/** @file
+ *  Implements `doLedgerHeader`, the handler for the `ledger_header` JSON-RPC
+ *  command. The command returns both the canonical binary encoding of the
+ *  requested ledger's header and its JSON representation, enabling clients to
+ *  cryptographically verify ledger integrity independent of the server.
+ */
+
 #include <xrpl/protocol/LedgerHeader.h>
 
 #include <xrpld/app/ledger/LedgerToJson.h>
@@ -13,10 +20,42 @@
 
 namespace xrpl {
 
-// {
-//   ledger_hash : <ledger>
-//   ledger_index : <ledger_index>
-// }
+/** Handle the `ledger_header` JSON-RPC command (API v1 only).
+ *
+ *  Returns two representations of the same ledger header side by side:
+ *
+ *  - `ledger_data`: the canonical 118-byte binary encoding of the header
+ *    (hex-encoded), serialized via `addRaw` with `includeHash = false`.
+ *    This is the exact pre-image that, when prefixed with
+ *    `HashPrefix::ledgerMaster` and hashed with SHA-512 half, yields the
+ *    ledger's identity hash. Clients can use this to verify the server's
+ *    claims without trusting it.
+ *
+ *  - `ledger` (JSON): the human-readable header fields produced by `addJson`
+ *    with `options = 0` (header only; no transactions, no state objects).
+ *    These fields are the server's interpretation and cannot be independently
+ *    verified from the response alone — hence the trust caveat below.
+ *
+ *  The ledger is resolved from `context.params` by `RPC::lookupLedger`,
+ *  accepting `ledger_hash` (256-bit hex), `ledger_index` (integer), or
+ *  shortcut strings (`"current"`, `"closed"`, `"validated"`). Malformed or
+ *  missing parameters are handled entirely by `lookupLedger`; no input
+ *  validation lives in this function.
+ *
+ *  @param context JSON-RPC context; `context.params` must supply exactly one
+ *      ledger selector: `ledger_hash`, `ledger_index`, or the deprecated
+ *      `ledger` field.
+ *  @return A `Json::Value` containing `ledger_data` (hex binary), `ledger`
+ *      (JSON header fields), and ledger identifying fields on success; an
+ *      error object (`rpcLGR_NOT_FOUND`, `rpcINVALID_PARAMS`, etc.) on
+ *      failure.
+ *  @note This command is restricted to API v1. API v2 clients receive
+ *      `rpcUNKNOWN_COMMAND`. Use the `ledger` command for v2-compatible
+ *      header access.
+ *  @note The JSON fields in `ledger` are not self-verifiable. Only
+ *      `ledger_data` provides a trust anchor for cryptographic verification.
+ *  @see addRaw, addJson, RPC::lookupLedger
+ */
 json::Value
 doLedgerHeader(RPC::JsonContext& context)
 {
@@ -30,8 +69,8 @@ doLedgerHeader(RPC::JsonContext& context)
     addRaw(lpLedger->header(), s);
     jvResult[jss::ledger_data] = strHex(s.peekData());
 
-    // This information isn't verified: they should only use it if they trust
-    // us.
+    // The JSON fields below are the server's interpretation of the header and
+    // cannot be independently re-verified from this response alone.
     addJson(jvResult, {*lpLedger, &context, 0});
 
     return jvResult;
diff --git a/src/xrpld/rpc/handlers/orderbook/AMMInfo.cpp b/src/xrpld/rpc/handlers/orderbook/AMMInfo.cpp
index 38251f855f..dd9d97594c 100644
--- a/src/xrpld/rpc/handlers/orderbook/AMMInfo.cpp
+++ b/src/xrpld/rpc/handlers/orderbook/AMMInfo.cpp
@@ -1,3 +1,10 @@
+/** @file
+ *  Implements the `amm_info` RPC handler, which returns the current state of an
+ *  Automated Market Maker (AMM) pool: reserve balances, trading fee, vote slots,
+ *  and auction slot. The AMM may be addressed either by its `amm_account` or by
+ *  the `asset`+`asset2` pair that identifies the pool.
+ */
+
 #include <xrpld/app/ledger/LedgerMaster.h>
 #include <xrpld/rpc/Context.h>
 #include <xrpld/rpc/detail/RPCLedgerHelpers.h>
@@ -35,6 +42,18 @@
 
 namespace xrpl {
 
+/** Parse an AMM asset from a JSON value, translating parse errors into an RPC error code.
+ *
+ *  `assetFromJson` throws `std::runtime_error` on malformed input. This wrapper
+ *  catches that exception and returns `Unexpected(RpcIssueMalformed)` instead,
+ *  keeping raw exceptions out of the RPC dispatch layer.
+ *
+ *  @param v  JSON value containing the asset specification (currency/issuer object or
+ *      `"XRP"` string).
+ *  @param j  Journal used to log the parse error message at debug level.
+ *  @return The parsed `Asset` on success, or `Unexpected(RpcIssueMalformed)` if
+ *      the input is malformed.
+ */
 Expected<Asset, ErrorCodeI>
 getAsset(json::Value const& v, beast::Journal j)
 {
@@ -49,10 +68,20 @@ getAsset(json::Value const& v, beast::Journal j)
     return Unexpected(RpcIssueMalformed);
 }
 
+/** Format a NetClock time point as an ISO 8601 UTC string.
+ *
+ *  NetClock counts seconds since the Ripple epoch (2000-01-01 00:00:00 UTC),
+ *  while `std::chrono::system_clock` uses the Unix epoch (1970-01-01 00:00:00 UTC).
+ *  This function bridges the gap by adding `kEPOCH_OFFSET` (946,684,800 s) before
+ *  formatting with the Howard Hinnant `date` library. Used exclusively to present
+ *  the auction slot's `sfExpiration` field in a universally readable format.
+ *
+ *  @param tp  NetClock time point to convert.
+ *  @return ISO 8601 string in the form `"YYYY-MM-DDTHH:MM:SS+0000"`.
+ */
 std::string
 toIso8601(NetClock::time_point tp)
 {
-    // 2000-01-01 00:00:00 UTC is 946684800s from 1970-01-01 00:00:00 UTC
     using namespace std::chrono;
     return date::format(
         "%Y-%Om-%dT%H:%M:%OS%z",
@@ -60,6 +89,23 @@ toIso8601(NetClock::time_point tp)
             system_clock::time_point{tp.time_since_epoch() + kEPOCH_OFFSET}));
 }
 
+/** Return information about an AMM pool.
+ *
+ *  Resolves the AMM via `amm_account` (direct keylet by ID) or `asset`+`asset2`
+ *  (derives the AMM via `keylet::amm`). Both paths converge to the same AMM SLE.
+ *  When only `amm_account` is supplied, the assets are back-filled from the SLE's
+ *  `sfAsset`/`sfAsset2` fields.
+ *
+ *  Pool balances are always fetched with `FreezeHandling::IgnoreFreeze`: an AMM
+ *  cannot suspend operation because an issuer froze a trust line. Freeze status is
+ *  reported separately via `asset_frozen`/`asset2_frozen` for non-XRP assets.
+ *
+ *  @param context  RPC dispatch context carrying request parameters, ledger master,
+ *      API version, and journal.
+ *  @return JSON object containing an `amm` sub-object with pool balances, LP token
+ *      supply (or the requesting account's LP balance when `account` is given),
+ *      trading fee, vote slots, and auction slot; plus ledger identification fields.
+ */
 json::Value
 doAMMInfo(RPC::JsonContext& context)
 {
@@ -71,6 +117,7 @@ doAMMInfo(RPC::JsonContext& context)
     if (!ledger)
         return result;
 
+    /** Validated inputs extracted from the RPC request parameters. */
     struct ValuesFromContextParams
     {
         std::optional<AccountID> accountID;
@@ -79,18 +126,38 @@ doAMMInfo(RPC::JsonContext& context)
         std::shared_ptr<SLE const> amm;
     };
 
+    /** Extract and validate AMM lookup parameters from the RPC request.
+     *
+     *  Callers must supply exactly one of: the `asset`+`asset2` pair, or
+     *  `amm_account`. Supplying both or neither is `RpcInvalidParams`.
+     *
+     *  The validity check is evaluated at two different points depending on API
+     *  version to preserve backward-compatible error sequencing:
+     *  - For `apiVersion < 3` the check fires before individual fields are parsed,
+     *    so a conflicting combination short-circuits immediately.
+     *  - For `apiVersion >= 3` the check fires after parsing each field, allowing
+     *    field-level errors (e.g., malformed asset) to take priority.
+     *
+     *  @return Populated `ValuesFromContextParams` on success, or
+     *      `Unexpected(error_code)` with the appropriate RPC error.
+     */
     auto getValuesFromContextParams = [&]() -> Expected<ValuesFromContextParams, ErrorCodeI> {
         std::optional<AccountID> accountID;
         std::optional<Asset> asset1;
         std::optional<Asset> asset2;
         std::optional<uint256> ammID;
 
+        /** Returns true when the combination of asset/amm_account parameters is
+         *  invalid: either only one of `asset`/`asset2` is present, or both
+         *  `asset` and `amm_account` are present (or both absent).
+         */
         constexpr auto kINVALID = [](json::Value const& params) -> bool {
             return (params.isMember(jss::asset) != params.isMember(jss::asset2)) ||
                 (params.isMember(jss::asset) == params.isMember(jss::amm_account));
         };
 
-        // NOTE, identical check for apVersion >= 3 below
+        // NOTE, identical check for apiVersion >= 3 below; placement differs
+        // intentionally — see getValuesFromContextParams docstring above.
         if (context.apiVersion < 3 && kINVALID(params))
             return Unexpected(RpcInvalidParams);
 
@@ -138,7 +205,8 @@ doAMMInfo(RPC::JsonContext& context)
                 return Unexpected(RpcActMalformed);
         }
 
-        // NOTE, identical check for apVersion < 3 above
+        // NOTE, identical check for apiVersion < 3 above; placement differs
+        // intentionally — see getValuesFromContextParams docstring above.
         if (context.apiVersion >= 3 && kINVALID(params))
             return Unexpected(RpcInvalidParams);
 
@@ -176,7 +244,8 @@ doAMMInfo(RPC::JsonContext& context)
 
     auto const ammAccountID = amm->getAccountID(sfAccount);
 
-    // provide funds if frozen, specify asset_frozen flag
+    // IgnoreFreeze: an AMM cannot suspend operations due to a frozen trust
+    // line; freeze status is reported separately via asset_frozen/asset2_frozen.
     auto const [asset1Balance, asset2Balance] = ammPoolHolds(
         *ledger,
         ammAccountID,
diff --git a/src/xrpld/rpc/handlers/orderbook/BookChanges.cpp b/src/xrpld/rpc/handlers/orderbook/BookChanges.cpp
index 947a257916..70d8c35a9e 100644
--- a/src/xrpld/rpc/handlers/orderbook/BookChanges.cpp
+++ b/src/xrpld/rpc/handlers/orderbook/BookChanges.cpp
@@ -1,3 +1,12 @@
+/** @file
+ *  RPC handler for the `book_changes` API method.
+ *
+ *  Resolves the caller's ledger selector and delegates to
+ *  `RPC::computeBookChanges`, which mines transaction metadata to produce
+ *  OHLCV market-data for every order-book pair that had fills in that ledger.
+ *  Registered in `Handler.cpp` as `Role::USER`, `Condition::NoCondition`.
+ */
+
 #include <xrpld/rpc/BookChanges.h>
 
 #include <xrpld/rpc/Context.h>
@@ -9,6 +18,29 @@
 
 namespace xrpl {
 
+/** Entry-point handler for the `book_changes` RPC command.
+ *
+ *  Resolves the ledger identified by the standard XRPL ledger-selector
+ *  parameters (`ledger_hash`, `ledger_index`, or the shorthand strings
+ *  `"validated"`, `"current"`, and `"closed"`) via `RPC::lookupLedger`.
+ *  If no selector is supplied, the current (open) ledger is used by default.
+ *
+ *  The handler checks the resulting `shared_ptr` rather than inspecting the
+ *  JSON error fields: a null pointer means the lookup failed and the partially-
+ *  populated `result` already contains the appropriate error response. This is
+ *  the idiomatic pattern used by all ledger-reading handlers in this subtree.
+ *
+ *  On success, delegates entirely to `RPC::computeBookChanges`, which iterates
+ *  `sfAffectedNodes` across every transaction in the ledger to accumulate
+ *  per-pair OHLCV statistics. See `BookChanges.h` for full algorithmic detail.
+ *
+ *  @param context  RPC dispatch context carrying request parameters, app
+ *      references, and role information.
+ *  @return On success, a JSON object containing `type`, `validated`,
+ *      `ledger_index`, `ledger_hash`, `ledger_time`, and a `changes` array
+ *      of per-pair OHLCV records (see `RPC::computeBookChanges`). On failure,
+ *      the error JSON populated by `RPC::lookupLedger`.
+ */
 json::Value
 doBookChanges(RPC::JsonContext& context)
 {
diff --git a/src/xrpld/rpc/handlers/orderbook/BookOffers.cpp b/src/xrpld/rpc/handlers/orderbook/BookOffers.cpp
index 390dd88166..7c2ddea97c 100644
--- a/src/xrpld/rpc/handlers/orderbook/BookOffers.cpp
+++ b/src/xrpld/rpc/handlers/orderbook/BookOffers.cpp
@@ -1,3 +1,11 @@
+/** @file
+ *  Handler for the `book_offers` JSON-RPC method.
+ *
+ *  Validates the two-sided order book request, resolves optional pagination
+ *  and taker-identity parameters, then delegates to
+ *  `NetworkOPs::getBookPage` for the actual ledger traversal.
+ */
+
 #include <xrpld/app/main/Application.h>
 #include <xrpld/rpc/Context.h>
 #include <xrpld/rpc/detail/RPCHelpers.h>
@@ -27,6 +35,20 @@
 
 namespace xrpl {
 
+/** Validate the structural shape of one side of a book request.
+ *
+ *  Checks that the JSON object for `taker_pays` or `taker_gets` carries
+ *  exactly one of `currency` (IOU/XRP path) or `mpt_issuance_id` (MPT path),
+ *  that the two are never mixed, and that whichever is present is a string.
+ *  This is a pure structural check — no value parsing is attempted.
+ *
+ *  @param taker The JSON object for one side of the book (`taker_pays` or
+ *      `taker_gets`).
+ *  @param name The field name used to format error messages (`jss::taker_pays`
+ *      or `jss::taker_gets`).
+ *  @return `std::nullopt` if the object is structurally valid; a JSON error
+ *      value otherwise.
+ */
 std::optional<json::Value>
 validateTakerJSON(json::Value const& taker, json::StaticString const& name)
 {
@@ -51,6 +73,25 @@ validateTakerJSON(json::Value const& taker, json::StaticString const& name)
     return std::nullopt;
 }
 
+/** Parse the currency or MPT issuance ID for one side of a book request.
+ *
+ *  Translates the string value of `currency` or `mpt_issuance_id` in `taker`
+ *  into a typed `Asset`. On success, `asset` is populated with either an
+ *  `Issue` (currency path, issuer left at its default) or an `MPTID` (MPT
+ *  path). On failure, a side-specific error code is returned:
+ *  `rpcSRC_CUR_MALFORMED` for `taker_pays`, `rpcDST_AMT_MALFORMED` for
+ *  `taker_gets`.
+ *
+ *  @note This function must be called after `validateTakerJSON` has confirmed
+ *      the structural constraints. The issuer field is populated separately by
+ *      `parseTakerIssuerJSON`; MPT assets skip that step entirely.
+ *
+ *  @param asset Output parameter populated with the parsed `Issue` or `MPTID`.
+ *  @param taker The JSON object for one side of the book.
+ *  @param name The field name used to select the error code and format messages.
+ *  @param j Journal for diagnostic logging on parse failure.
+ *  @return `std::nullopt` on success; a JSON error value on failure.
+ */
 std::optional<json::Value>
 parseTakerAssetJSON(
     Asset& asset,
@@ -92,6 +133,27 @@ parseTakerAssetJSON(
     return std::nullopt;
 }
 
+/** Resolve the issuer account for the IOU side of a book request.
+ *
+ *  Fills `issue.account` in the `Issue` held by `asset`. For XRP, the issuer
+ *  defaults to `xrpAccount()` and any explicit `issuer` field is rejected. For
+ *  IOUs, an explicit `issuer` is required, is validated with `toIssuer()`, and
+ *  must not be the `noAccount()` sentinel. Pairing a non-XRP currency with the
+ *  XRP account (or XRP currency with a non-XRP account) is also rejected.
+ *
+ *  @note This function is a no-op for MPT assets: `asset.get<Issue>()` is only
+ *      accessed when `taker` contains a `currency` field, which cannot appear
+ *      alongside `mpt_issuance_id` (enforced upstream by `validateTakerJSON`).
+ *      Error codes are side-specific: `rpcSRC_ISR_MALFORMED` for `taker_pays`,
+ *      `rpcDST_ISR_MALFORMED` for `taker_gets`.
+ *
+ *  @param asset The `Asset` whose embedded `Issue::account` will be filled.
+ *      Must already hold an `Issue` (i.e., `parseTakerAssetJSON` has run).
+ *  @param taker The JSON object for one side of the book.
+ *  @param name The field name used to select the error code and format messages.
+ *  @param j Journal (currently unused; reserved for future diagnostics).
+ *  @return `std::nullopt` on success; a JSON error value on failure.
+ */
 std::optional<json::Value>
 parseTakerIssuerJSON(
     Asset& asset,
@@ -161,6 +223,31 @@ parseTakerIssuerJSON(
     return std::nullopt;
 }
 
+/** Handle a `book_offers` RPC request.
+ *
+ *  Enumerates active offers in a specific trading pair on the XRP Ledger's
+ *  native DEX. Validates the `taker_pays` and `taker_gets` fields through
+ *  three sequential passes (structure → currency/MPT parse → issuer parse),
+ *  resolves optional `taker`, `domain`, `limit`, and `marker` fields, then
+ *  delegates all ledger traversal to `NetworkOPs::getBookPage`.
+ *
+ *  Load shedding: the request is rejected with `rpcTOO_BUSY` immediately if
+ *  the server has more than 200 concurrent `jtCLIENT` jobs outstanding,
+ *  before any ledger access.
+ *
+ *  @note The same `getBookPage` call path is also used by `Subscribe.cpp` for
+ *      streaming order book subscriptions, so behavioural changes here affect
+ *      both the one-shot RPC and the subscription snapshot.
+ *  @note `limit` is clamped to `RPC::Tuning::kBOOK_OFFERS` (default 60, max
+ *      100). Unlimited roles are not exempt from this cap.
+ *  @note `domain` scopes the query to offers within a permissioned DEX domain
+ *      (XLS-80d). Omit the field for the global order book.
+ *
+ *  @param context The full RPC dispatch context, including parsed JSON params,
+ *      the network operations interface, and the resource-cost handle.
+ *  @return A JSON object containing the `offers` array and, if the result is
+ *      paginated, a `marker` field for cursor-based continuation.
+ */
 json::Value
 doBookOffers(RPC::JsonContext& context)
 {
diff --git a/src/xrpld/rpc/handlers/orderbook/DepositAuthorized.cpp b/src/xrpld/rpc/handlers/orderbook/DepositAuthorized.cpp
index 399df7c6ca..11a3a80fe2 100644
--- a/src/xrpld/rpc/handlers/orderbook/DepositAuthorized.cpp
+++ b/src/xrpld/rpc/handlers/orderbook/DepositAuthorized.cpp
@@ -23,20 +23,67 @@
 
 namespace xrpl {
 
-// {
-//   source_account : <ident>
-//   destination_account : <ident>
-//   ledger_hash : <ledger>
-//   ledger_index : <ledger_index>
-//   credentials : [<credentialID>,...]
-// }
+/** @file
+ *  Implements the `deposit_authorized` RPC handler.
+ *
+ *  Answers whether a payment from a source account to a destination account
+ *  would currently be permitted under the destination's DepositAuth rules,
+ *  optionally considering a caller-supplied set of credential IDs. This is a
+ *  pure read-only query — no ledger state is mutated.
+ */
 
+/** Determine whether a source account may deposit to a destination account.
+ *
+ *  Resolves the requested ledger, verifies that both accounts exist, inspects
+ *  the destination's `lsfDepositAuth` flag, and evaluates one or both of two
+ *  authorization paths:
+ *
+ *  1. **Account preauthorization** — the destination has posted a
+ *     `DepositPreauth` object keyed by `(dstAcct, srcAcct)`.
+ *  2. **Credential preauthorization** — the caller supplies credential IDs
+ *     (`credentials` array of hex-encoded `uint256` hashes), each credential
+ *     is valid for `source_account`, and the destination has posted a
+ *     `DepositPreauth` object keyed by the canonical sorted set of
+ *     `(issuer, credentialType)` pairs derived from those credentials.
+ *
+ *  Either path is sufficient; they are OR-ed together. Self-deposits (source
+ *  == destination) are always authorized regardless of the DepositAuth flag,
+ *  mirroring the rule enforced at transaction-apply time.
+ *
+ *  **Credential validation** (when `credentials` is present): each credential
+ *  must exist in the ledger (`lsfAccepted` flag set), must not be expired as
+ *  of `parentCloseTime`, and must belong to `source_account`. Duplicate
+ *  `(issuer, credentialType)` pairs are rejected. The array is capped at
+ *  `kMAX_CREDENTIALS_ARRAY_SIZE` (8) entries.
+ *
+ *  **`lifeExtender` invariant**: the `sorted` set holds `Slice` views into
+ *  `sfCredentialType` data inside SLE objects. `lifeExtender` keeps those
+ *  SLEs alive for the lifetime of `sorted` so the `Slice` references remain
+ *  valid through the `keylet::depositPreauth` call.
+ *
+ *  @note Results reflect the state of the selected ledger using
+ *      `parentCloseTime`. A credential that is valid at query time may expire
+ *      before the actual transaction is submitted; callers should re-query or
+ *      submit promptly. This handler uses a `ReadView` and cannot delete
+ *      expired credentials as `verifyDepositPreauth` (on an `ApplyView`) does.
+ *
+ *  @param context  RPC dispatch context; `context.params` must contain
+ *      `source_account` (Base58 account address string),
+ *      `destination_account` (Base58 account address string), and optionally
+ *      `ledger_hash`/`ledger_index` for ledger selection and `credentials`
+ *      (non-empty array of hex-encoded credential object IDs, at most
+ *      `kMAX_CREDENTIALS_ARRAY_SIZE` entries).
+ *  @return JSON object containing `source_account`, `destination_account`,
+ *      `deposit_authorized` (bool), and `credentials` (if supplied). On
+ *      error, returns a JSON error object with one of: `rpcINVALID_PARAMS`,
+ *      `rpcACT_MALFORMED`, `rpcSRC_ACT_NOT_FOUND`, `rpcDST_ACT_NOT_FOUND`,
+ *      or `rpcBAD_CREDENTIALS`.
+ */
 json::Value
 doDepositAuthorized(RPC::JsonContext& context)
 {
     json::Value const& params = context.params;
 
-    // Validate source_account.
     if (!params.isMember(jss::source_account))
         return RPC::missingFieldError(jss::source_account);
     if (!params[jss::source_account].isString())
@@ -50,7 +97,6 @@ doDepositAuthorized(RPC::JsonContext& context)
         return rpcError(RpcActMalformed);
     auto const srcAcct{srcID.value()};
 
-    // Validate destination_account.
     if (!params.isMember(jss::destination_account))
         return RPC::missingFieldError(jss::destination_account);
     if (!params[jss::destination_account].isString())
@@ -64,21 +110,18 @@ doDepositAuthorized(RPC::JsonContext& context)
         return rpcError(RpcActMalformed);
     auto const dstAcct{dstID.value()};
 
-    // Validate ledger.
     std::shared_ptr<ReadView const> ledger;
     json::Value result = RPC::lookupLedger(ledger, context);
 
     if (!ledger)
         return result;
 
-    // If source account is not in the ledger it can't be authorized.
     if (!ledger->exists(keylet::account(srcAcct)))
     {
         RPC::injectError(RpcSrcActNotFound, result);
         return result;
     }
 
-    // If destination account is not in the ledger you can't deposit to it, eh?
     auto const sleDest = ledger->read(keylet::account(dstAcct));
     if (!sleDest)
     {
@@ -164,8 +207,6 @@ doDepositAuthorized(RPC::JsonContext& context)
         }
     }
 
-    // If the two accounts are the same OR if that flag is
-    // not set, then the deposit should be fine.
     bool depositAuthorized = true;
     if (reqAuth)
     {
diff --git a/src/xrpld/rpc/handlers/orderbook/GetAggregatePrice.cpp b/src/xrpld/rpc/handlers/orderbook/GetAggregatePrice.cpp
index 1d34ca21b2..f897012e56 100644
--- a/src/xrpld/rpc/handlers/orderbook/GetAggregatePrice.cpp
+++ b/src/xrpld/rpc/handlers/orderbook/GetAggregatePrice.cpp
@@ -38,12 +38,49 @@
 namespace xrpl {
 
 using namespace boost::bimaps;
-// sorted descending by lastUpdateTime, ascending by AssetPrice
+
+/** Dual-indexed price dataset for the aggregate-price computation.
+ *
+ *  The left side is keyed by `lastUpdateTime` in descending order so that
+ *  stale entries can be erased in O(log n) via `left.upper_bound(cutoff)`.
+ *  The right side is keyed by `STAmount` in ascending order so that
+ *  statistical operations (median, trimmed mean) iterate over prices already
+ *  sorted by value.  Both views stay automatically synchronized: erasing an
+ *  entry from either side removes the corresponding entry from the other.
+ */
 using Prices =
     bimap<multiset_of<std::uint32_t, std::greater<std::uint32_t>>, multiset_of<STAmount>>;
 
-/** Calls callback "f" on the ledger-object sle and up to three previous
- * metadata objects. Stops early if the callback returns true.
+/** Walk an oracle's current state and up to three prior transaction metadata
+ *  snapshots, invoking a callback on each until a matching price is found.
+ *
+ *  An oracle may have been updated without touching the requested token pair,
+ *  leaving the current `sfPriceDataSeries` with no relevant entry.  This
+ *  function follows `sfPreviousTxnID` / `sfPreviousTxnLgrSeq` backward
+ *  through the ledger history (up to `kMAX_HISTORY = 3` hops) so the caller
+ *  can retrieve a price from the most recent revision that did record the pair.
+ *
+ *  Two pointers track separate concerns:
+ *  - **`oracle`** — the object containing `sfPriceDataSeries`.  Starts as the
+ *      live SLE; after the first hop it becomes `sfNewFields` (create) or
+ *      `sfFinalFields` (modify) inside the matching metadata node.
+ *  - **`chain`** — the object containing the navigation fields
+ *      `sfPreviousTxnID` and `sfPreviousTxnLgrSeq`.  Starts equal to `oracle`
+ *      (the live SLE), then diverges to the enclosing `ModifiedNode` /
+ *      `CreatedNode` wrapper once inside metadata (where those fields live on
+ *      the wrapper, not on the nested field object).
+ *
+ *  The `prevChain == chain` guard detects a missing `ltORACLE` node in the
+ *  inner scan and exits the loop cleanly.  An `isNew` flag short-circuits
+ *  immediately when the earliest hop was a creation transaction, since there
+ *  is no further history behind it.
+ *
+ *  @param context  RPC execution context; used to fetch historical ledgers.
+ *  @param sle      The live `PriceOracle` SLE for the oracle being examined.
+ *                  May be null if the oracle does not exist on the ledger.
+ *  @param f        Callback receiving each `STObject` that has
+ *                  `sfPriceDataSeries`.  Return `true` to stop iteration (price
+ *                  found); return `false` to continue to the next history hop.
  */
 static void
 iteratePriceData(
@@ -118,7 +155,21 @@ iteratePriceData(
     }
 }
 
-// Return avg, sd, data set size
+/** Compute mean, sample standard deviation, and element count over a range of
+ *  price-sorted bimap entries.
+ *
+ *  The mean is computed as the arithmetic average of the `STAmount` values in
+ *  [begin, end).  The standard deviation uses Bessel's correction (`n - 1`
+ *  denominator), appropriate for a sample drawn from a broader population of
+ *  potential oracle reports.  The square root is taken via XRPL's `Number`
+ *  type to preserve financial-grade precision.  When the range contains only
+ *  one element the standard deviation is returned as zero.
+ *
+ *  @param begin  Iterator to the first element of the value-sorted (right)
+ *               view of the `Prices` bimap.
+ *  @param end    Past-the-end iterator for the same range.
+ *  @return A tuple of `{mean, standard_deviation, count}`.
+ */
 static std::tuple<STAmount, Number, std::uint16_t>
 getStats(Prices::right_const_iterator const& begin, Prices::right_const_iterator const& end)
 {
@@ -138,13 +189,46 @@ getStats(Prices::right_const_iterator const& begin, Prices::right_const_iterator
     return {avg, sd, size};
 };
 
-/**
- * oracles: array of {account, oracle_document_id}
- * base_asset: is the asset to be priced
- * quote_asset: is the denomination in which the prices are expressed
- * trim : percentage of outliers to trim [optional]
- * time_threshold : defines a range of prices to include based on the timestamp
- *   range - {most recent, most recent - time_threshold} [optional]
+/** Handler for the `get_aggregate_price` RPC method (XLS-47).
+ *
+ *  Aggregates prices from up to 200 on-chain `PriceOracle` ledger objects
+ *  for a given (base_asset, quote_asset) pair and returns a statistical
+ *  summary: mean, sample standard deviation, median, and — if `trim` is
+ *  supplied — a symmetrically trimmed mean and standard deviation.
+ *
+ *  Because individual oracles may be stale or dishonest, the method is
+ *  designed to be called with a list of independent oracle identifiers so
+ *  that the aggregate resists manipulation by any single reporter.  History
+ *  walking (`iteratePriceData`) recovers prices from oracles that were last
+ *  updated without touching the requested pair.
+ *
+ *  **Input parameters** (all in `context.params`):
+ *  - `oracles` (required) — JSON array of `{account, oracle_document_id}`,
+ *      1–200 entries; empty or oversized arrays return `oracleMalformed`.
+ *  - `base_asset` (required) — currency code for the asset being priced;
+ *      must pass `currencyFromJson` validation.
+ *  - `quote_asset` (required) — currency code for the denomination; same
+ *      validation as `base_asset`.
+ *  - `trim` (optional) — integer 1–25; percentage of lowest and highest
+ *      prices to remove symmetrically before computing trimmed statistics.
+ *      Zero and values above 25 are rejected as `invalidParams`.
+ *  - `time_threshold` (optional) — non-negative integer; prices whose
+ *      `lastUpdateTime` is older than `(latestTime - time_threshold)` are
+ *      excluded.  Zero means no filtering.
+ *
+ *  **Result fields** (on success):
+ *  - `time` — `lastUpdateTime` of the most recently updated oracle.
+ *  - `entire_set.mean`, `entire_set.standard_deviation`, `entire_set.size`.
+ *  - `median`.
+ *  - `trimmed_set.mean`, `trimmed_set.standard_deviation`, `trimmed_set.size`
+ *      (only present when `trim` was supplied and non-zero).
+ *
+ *  @param context  RPC execution context carrying params, ledger master, and
+ *                  application references.
+ *  @return A `Json::Value` containing the aggregate statistics, or an error
+ *          object populated via `RPC::injectError` / `RPC::missingFieldError`.
+ *  @note If no oracle in the list has a price for the requested pair (including
+ *      up to three historical hops), the handler returns `objectNotFound`.
  */
 json::Value
 doGetAggregatePrice(RPC::JsonContext& context)
@@ -168,8 +252,9 @@ doGetAggregatePrice(RPC::JsonContext& context)
     if (!params.isMember(jss::quote_asset))
         return RPC::missingFieldError(jss::quote_asset);
 
-    // Lambda to validate uint type
-    // support positive int, uint, and a number represented as a string
+    // Returns true when the named field is a non-negative integer or a string
+    // that lexically converts to one — accepts JSON uint, non-negative int, or
+    // a decimal string (e.g. "200") to accommodate loose clients.
     auto validUInt = [](json::Value const& params, json::StaticString const& field) {
         auto const& jv = params[field];
         std::uint32_t v = 0;
@@ -177,8 +262,10 @@ doGetAggregatePrice(RPC::JsonContext& context)
             (jv.isString() && beast::lexicalCastChecked(v, jv.asString()));
     };
 
-    // Lambda to get `trim` and `time_threshold` fields. If the field
-    // is not included in the input then a default value is returned.
+    // Reads an optional uint32 parameter from params; returns the field value
+    // on success, `def` when absent, or `RpcInvalidParams` when present but
+    // not a valid non-negative integer.  Return type is a variant so callers
+    // can distinguish a missing field from a parse failure without exceptions.
     auto getField = [&params, &validUInt](
                         json::StaticString const& field,
                         unsigned int def = 0) -> std::variant<std::uint32_t, ErrorCodeI> {
@@ -191,8 +278,10 @@ doGetAggregatePrice(RPC::JsonContext& context)
         return def;
     };
 
-    // Lambda to get `base_asset` and `quote_asset`. The values have
-    // to conform to the Currency type.
+    // Validates that an asset field is a non-empty, well-formed currency code
+    // by delegating to `currencyFromJson`, which throws on malformed input.
+    // Returns the raw JSON value on success so it can be compared textually
+    // against `sfBaseAsset`/`sfQuoteAsset` values in `sfPriceDataSeries`.
     auto getCurrency = [&params](SField const& sField, json::StaticString const& field)
         -> std::variant<json::Value, ErrorCodeI> {
         try
@@ -246,8 +335,8 @@ doGetAggregatePrice(RPC::JsonContext& context)
     if (!ledger)
         return result;  // LCOV_EXCL_LINE
 
-    // Collect the dataset into bimap keyed by lastUpdateTime and
-    // STAmount (Number is int64 and price is uint64)
+    // Collect prices into the bimap.  sfAssetPrice is stored as a uint64
+    // mantissa; sfScale is negated so STAmount represents price * 10^(-scale).
     Prices prices;
     for (auto const& oracle : params[jss::oracles])
     {
@@ -269,7 +358,6 @@ doGetAggregatePrice(RPC::JsonContext& context)
         auto const sle = ledger->read(keylet::oracle(*account, *documentID));
         iteratePriceData(context, sle, [&](STObject const& node) {
             auto const& series = node.getFieldArray(sfPriceDataSeries);
-            // find the token pair entry with the price
             if (auto iter = std::ranges::find_if(
                     series,
                     [&](STObject const& o) -> bool {
@@ -300,22 +388,22 @@ doGetAggregatePrice(RPC::JsonContext& context)
         return result;
     }
 
-    // erase outdated data
-    // sorted in descending, therefore begin is the latest, end is the oldest
+    // Left view is sorted descending, so begin() is the newest entry.
     auto const latestTime = prices.left.begin()->first;
     if (auto const threshold = std::get<std::uint32_t>(timeThreshold))
     {
-        // threshold defines an acceptable range {max,min} of lastUpdateTime as
-        // {latestTime, latestTime - threshold}. Prices with lastUpdateTime
-        // less than (latestTime - threshold) are erased (outdated prices).
+        // Acceptable range is [latestTime - threshold, latestTime].  Prices
+        // older than the lower bound are erased.  When latestTime <= threshold
+        // the subtraction would underflow, so upperBound is clamped to
+        // oldestTime, which preserves all entries.
         auto const oldestTime = prices.left.rbegin()->first;
         auto const upperBound = latestTime > threshold ? (latestTime - threshold) : oldestTime;
         if (upperBound > oldestTime)
             prices.left.erase(prices.left.upper_bound(upperBound), prices.left.end());
 
-        // At least one element should remain since upperBound is either
-        // equal to oldestTime or is less than latestTime, in which case
-        // the data is deleted between the oldestTime and upperBound.
+        // upperBound is either equal to oldestTime (nothing erased) or strictly
+        // less than latestTime (some entries erased, but the newest survives).
+        // An empty set here would be a logic error.
         if (prices.empty())
         {
             // LCOV_EXCL_START
@@ -326,12 +414,13 @@ doGetAggregatePrice(RPC::JsonContext& context)
     }
     result[jss::time] = latestTime;
 
-    // calculate stats
     auto const [avg, sd, size] = getStats(prices.right.begin(), prices.right.end());
     result[jss::entire_set][jss::mean] = avg.getText();
     result[jss::entire_set][jss::size] = size;
     result[jss::entire_set][jss::standard_deviation] = to_string(sd);
 
+    // Helper to return an advanced copy of a bimap iterator by value,
+    // keeping median and trimmed-set arithmetic readable inline.
     auto itAdvance = [&](auto it, int distance) {
         std::advance(it, distance);
         return it;
diff --git a/src/xrpld/rpc/handlers/orderbook/NFTBuyOffers.cpp b/src/xrpld/rpc/handlers/orderbook/NFTBuyOffers.cpp
index 88e4392dad..63163d2122 100644
--- a/src/xrpld/rpc/handlers/orderbook/NFTBuyOffers.cpp
+++ b/src/xrpld/rpc/handlers/orderbook/NFTBuyOffers.cpp
@@ -1,3 +1,12 @@
+/** @file
+ *  Implements the `nft_buy_offers` RPC handler.
+ *
+ *  Validates the `nft_id` field and delegates all ledger traversal,
+ *  pagination, and response construction to `enumerateNFTOffers`.
+ *  The sell-side counterpart (`NFTSellOffers.cpp`) is structurally
+ *  identical, differing only in the keylet passed to that helper.
+ */
+
 #include <xrpld/rpc/Context.h>
 #include <xrpld/rpc/handlers/orderbook/NFTOffersHelpers.h>
 
@@ -9,6 +18,30 @@
 
 namespace xrpl {
 
+/** Return the open buy offers for a given NFToken.
+ *
+ *  Performs two input-validation guards before touching the ledger:
+ *  presence of `nft_id` (returns `missing_field_error` if absent) and
+ *  successful 256-bit hex parse of its value (returns `invalid_field_error`
+ *  if malformed). Both guards ensure `enumerateNFTOffers` always receives
+ *  a structurally valid `uint256`.
+ *
+ *  Ledger resolution, offer-directory existence check, pagination via
+ *  `marker`/`limit`, and per-offer JSON serialization are all handled
+ *  by `enumerateNFTOffers` using `keylet::nftBuys(nftId)` to target the
+ *  buy-side offer directory for this token.
+ *
+ *  @param context  RPC dispatch context carrying `params`, ledger access,
+ *      and load-type tracking. `context.loadType` is set to
+ *      `kFEE_MEDIUM_BURDEN_RPC` by the delegate.
+ *  @return JSON object containing `nft_id`, an `offers` array of
+ *      `ltNFTOKEN_OFFER` entries, and an optional `marker` when the
+ *      result set was truncated at `limit`.
+ *  @note The default page size is 250 offers; the marker is a hex-encoded
+ *      `uint256` referencing the last offer returned, allowing callers to
+ *      resume exactly where the previous page ended.
+ *  @see enumerateNFTOffers, doNFTSellOffers
+ */
 json::Value
 doNFTBuyOffers(RPC::JsonContext& context)
 {
diff --git a/src/xrpld/rpc/handlers/orderbook/NFTOffersHelpers.h b/src/xrpld/rpc/handlers/orderbook/NFTOffersHelpers.h
index 822896a644..cbcd8b4222 100644
--- a/src/xrpld/rpc/handlers/orderbook/NFTOffersHelpers.h
+++ b/src/xrpld/rpc/handlers/orderbook/NFTOffersHelpers.h
@@ -1,3 +1,15 @@
+/** @file
+ *  Shared enumeration logic for the `nft_buy_offers` and `nft_sell_offers`
+ *  RPC handlers.
+ *
+ *  Both commands traverse an NFToken offer directory and serialize results
+ *  with identical pagination semantics; they differ only in the `Keylet`
+ *  used to locate that directory (buy-side vs. sell-side). Rather than
+ *  duplicate this logic, the two handlers are implemented as thin wrappers
+ *  around `enumerateNFTOffers` and `appendNftOfferJson`, which are defined
+ *  here as `inline` free functions.
+ */
+
 #pragma once
 
 #include <xrpld/rpc/Context.h>
@@ -16,6 +28,18 @@
 
 namespace xrpl {
 
+/** Serialize a single NFToken offer SLE into a JSON accumulator array.
+ *
+ *  Always emits `nft_offer_index`, `flags`, `owner`, and `amount`.
+ *  The optional fields `destination` and `expiration` are emitted only
+ *  when present in the SLE, correctly reflecting their optional status
+ *  in the on-ledger format.
+ *
+ *  @param app   The running Application instance (passed for context
+ *      consistency with other JSON helpers; not used directly here).
+ *  @param offer An SLE of type `ltNFTOKEN_OFFER` to serialize.
+ *  @param offers The JSON array to which the new offer object is appended.
+ */
 inline void
 appendNftOfferJson(
     Application const& app,
@@ -37,13 +61,39 @@ appendNftOfferJson(
     offer->getFieldAmount(sfAmount).setJson(obj[jss::amount]);
 }
 
-// {
-//   nft_id: <token hash>
-//   ledger_hash : <ledger>
-//   ledger_index : <ledger_index>
-//   limit: integer                 // optional
-//   marker: opaque                 // optional, resume previous query
-// }
+/** Walk an NFToken offer directory and return a paginated JSON response.
+ *
+ *  Resolves the ledger, checks that `directory` exists, then iterates
+ *  `ltNFTOKEN_OFFER` entries using `forEachItemAfter`. Results are bounded
+ *  by `RPC::Tuning::kNFT_OFFERS` (min 50, default 250, max 500).
+ *
+ *  **Fresh queries (no `marker`):** fetches up to `limit + 1` items. If
+ *  exactly `limit + 1` items are returned, the last item becomes the next
+ *  `marker` and is excluded from the serialized `offers` array.
+ *
+ *  **Resume queries (with `marker`):** the marker is parsed as a hex
+ *  `uint256` ledger key. The corresponding SLE is read and its
+ *  `sfNFTokenID` is validated against `nftId` — mismatches return
+ *  `rpcINVALID_PARAMS`, preventing cross-token marker reuse. The
+ *  `sfNFTokenOfferNode` field is used as `startHint` so `forEachItemAfter`
+ *  jumps directly to the correct directory page. The marker offer itself
+ *  is prepended to the result before fetching the next `limit` items.
+ *
+ *  If `forEachItemAfter` returns `false` (corrupted or inconsistent
+ *  directory), `rpcINVALID_PARAMS` is returned.
+ *
+ *  Sets `context.loadType` to `kFEE_MEDIUM_BURDEN_RPC` on success.
+ *
+ *  @param context    RPC dispatch context; `context.params` is read for
+ *      `ledger_hash`, `ledger_index`, `limit`, and `marker`.
+ *  @param nftId      The 256-bit token ID whose offers are enumerated.
+ *  @param directory  Keylet of the offer directory to traverse — either
+ *      `keylet::nftBuys(nftId)` or `keylet::nftSells(nftId)`.
+ *  @return A JSON object containing `nft_id`, an `offers` array of
+ *      serialized `ltNFTOKEN_OFFER` entries, and an optional `limit` and
+ *      hex-encoded `marker` when the result set was truncated.
+ *  @see appendNftOfferJson, doNFTBuyOffers, doNFTSellOffers
+ */
 inline json::Value
 enumerateNFTOffers(RPC::JsonContext& context, uint256 const& nftId, Keylet const& directory)
 {
@@ -71,8 +121,6 @@ enumerateNFTOffers(RPC::JsonContext& context, uint256 const& nftId, Keylet const
 
     if (context.params.isMember(jss::marker))
     {
-        // We have a start point. Use limit - 1 from the result and use the
-        // very last one for the resume.
         json::Value const& marker(context.params[jss::marker]);
 
         if (!marker.isString())
@@ -92,7 +140,6 @@ enumerateNFTOffers(RPC::JsonContext& context, uint256 const& nftId, Keylet const
     }
     else
     {
-        // We have no start point, limit should be one higher than requested.
         offers.reserve(++reserve);
     }
 
diff --git a/src/xrpld/rpc/handlers/orderbook/NFTSellOffers.cpp b/src/xrpld/rpc/handlers/orderbook/NFTSellOffers.cpp
index 309df93605..47537c3515 100644
--- a/src/xrpld/rpc/handlers/orderbook/NFTSellOffers.cpp
+++ b/src/xrpld/rpc/handlers/orderbook/NFTSellOffers.cpp
@@ -1,3 +1,12 @@
+/** @file
+ *  Implements the `nft_sell_offers` RPC handler.
+ *
+ *  Validates the `nft_id` field and delegates all ledger traversal,
+ *  pagination, and response construction to `enumerateNFTOffers`.
+ *  The buy-side counterpart (`NFTBuyOffers.cpp`) is structurally
+ *  identical, differing only in the keylet passed to that helper.
+ */
+
 #include <xrpld/rpc/Context.h>
 #include <xrpld/rpc/handlers/orderbook/NFTOffersHelpers.h>
 
@@ -9,6 +18,30 @@
 
 namespace xrpl {
 
+/** Return the open sell offers for a given NFToken.
+ *
+ *  Performs two input-validation guards before touching the ledger:
+ *  presence of `nft_id` (returns `missing_field_error` if absent) and
+ *  successful 256-bit hex parse of its value (returns `invalid_field_error`
+ *  if malformed). Both guards ensure `enumerateNFTOffers` always receives
+ *  a structurally valid `uint256`.
+ *
+ *  Ledger resolution, offer-directory existence check, pagination via
+ *  `marker`/`limit`, and per-offer JSON serialization are all handled
+ *  by `enumerateNFTOffers` using `keylet::nftSells(nftId)` to target the
+ *  sell-side offer directory for this token.
+ *
+ *  @param context  RPC dispatch context carrying `params`, ledger access,
+ *      and load-type tracking. `context.loadType` is set to
+ *      `kFEE_MEDIUM_BURDEN_RPC` by the delegate.
+ *  @return JSON object containing `nft_id`, an `offers` array of
+ *      `ltNFTOKEN_OFFER` entries, and an optional `marker` when the
+ *      result set was truncated at `limit`.
+ *  @note The default page size is 250 offers; the marker is a hex-encoded
+ *      `uint256` referencing the last offer returned, allowing callers to
+ *      resume exactly where the previous page ended.
+ *  @see enumerateNFTOffers, doNFTBuyOffers
+ */
 json::Value
 doNFTSellOffers(RPC::JsonContext& context)
 {
diff --git a/src/xrpld/rpc/handlers/orderbook/PathFind.cpp b/src/xrpld/rpc/handlers/orderbook/PathFind.cpp
index da338dfcc8..3cc5348dfc 100644
--- a/src/xrpld/rpc/handlers/orderbook/PathFind.cpp
+++ b/src/xrpld/rpc/handlers/orderbook/PathFind.cpp
@@ -1,3 +1,13 @@
+/** @file
+ *  Implements `doPathFind`, the RPC entry point for the `path_find` command.
+ *
+ *  `path_find` is a subscription-oriented command: it registers a long-lived
+ *  payment-path request on a WebSocket connection and pushes updated results
+ *  after every ledger close. The three subcommands (`create`, `close`,
+ *  `status`) map directly onto the `PathRequestManager` / `PathRequest` /
+ *  `InfoSub` lifecycle.
+ */
+
 #include <xrpld/app/ledger/LedgerMaster.h>
 #include <xrpld/app/main/Application.h>
 #include <xrpld/rpc/Context.h>
@@ -12,6 +22,45 @@
 
 namespace xrpl {
 
+/** Dispatch a `path_find` subcommand for a persistent pathfinding subscription.
+ *
+ *  Handles the three subcommands of the `path_find` WebSocket API:
+ *
+ *  - **`create`** — registers a new path-find request on the current
+ *    subscriber, replacing any existing one (`clearRequest` is called first).
+ *    Charges `kFEE_HEAVY_BURDEN_RPC` because path search traverses order books
+ *    and trust lines across the full ledger graph. The closed (validated)
+ *    ledger is used for the initial computation to ensure a stable view.
+ *    Subsequent updates are pushed asynchronously by `PathRequestManager`
+ *    after each ledger close.
+ *  - **`close`** — tears down the active request and clears it from the
+ *    subscriber. No resource charge; cost was already borne at `create` time.
+ *  - **`status`** — returns the most recently computed path result without
+ *    triggering a new computation. No resource charge.
+ *
+ *  Validations are applied cheapest-first:
+ *  1. `PATH_SEARCH_MAX == 0` → `rpcNOT_SUPPORTED` (admin-disabled pathfinding).
+ *  2. Missing or non-string `subcommand` field → `rpcINVALID_PARAMS`.
+ *  3. No active `infoSub` (non-WebSocket transport) → `rpcNO_EVENTS`.
+ *  4. No live `InfoSubRequest` on `close`/`status` → `rpcNO_PF_REQUEST`.
+ *  5. Unrecognised subcommand string → `rpcINVALID_PARAMS`.
+ *
+ *  The negotiated API version is propagated to the subscriber via
+ *  `setApiVersion` before dispatch so that asynchronous push updates are
+ *  formatted according to the client's negotiated version.
+ *
+ *  @note Only WebSocket transports carry an `infoSub`; HTTP callers always
+ *      receive `rpcNO_EVENTS` because there is no persistent channel over
+ *      which to push path updates.
+ *  @note `InfoSub` holds at most one active `InfoSubRequest` at a time.
+ *      Issuing a second `create` without a `close` silently replaces the
+ *      prior request.
+ *  @param context  RPC dispatch context, including the subscriber, ledger
+ *      master, app handle, and parsed request parameters.
+ *  @return JSON response for the subcommand: an initial path result for
+ *      `create`, a close confirmation for `close`, the cached result for
+ *      `status`, or an `rpcError` object on failure.
+ */
 json::Value
 doPathFind(RPC::JsonContext& context)
 {
diff --git a/src/xrpld/rpc/handlers/orderbook/RipplePathFind.cpp b/src/xrpld/rpc/handlers/orderbook/RipplePathFind.cpp
index 316f26fa32..9f4f8f43f2 100644
--- a/src/xrpld/rpc/handlers/orderbook/RipplePathFind.cpp
+++ b/src/xrpld/rpc/handlers/orderbook/RipplePathFind.cpp
@@ -1,3 +1,13 @@
+/** @file
+ *  Implements `doRipplePathFind`, the handler for the deprecated
+ *  `ripple_path_find` JSON-RPC command.
+ *
+ *  The command provides a single synchronous-looking call that finds payment
+ *  paths and returns them in the HTTP response. Its successor, `path_find`
+ *  (`PathFind.cpp`), uses a WebSocket subscription model instead. This file
+ *  is retained only for backwards compatibility.
+ */
+
 #include <xrpld/app/ledger/LedgerMaster.h>
 #include <xrpld/rpc/Context.h>
 #include <xrpld/rpc/Role.h>
@@ -19,7 +29,60 @@
 
 namespace xrpl {
 
-// This interface is deprecated.
+/** Handle the deprecated `ripple_path_find` one-shot pathfinding RPC command.
+ *
+ *  Finds one or more payment paths between two parties and returns the result
+ *  synchronously in the HTTP response. The successor API is `path_find`, which
+ *  uses a WebSocket subscription to push continuous updates; this handler
+ *  remains only for backwards compatibility.
+ *
+ *  **Gate checks (cheapest first):**
+ *  1. `PATH_SEARCH_MAX == 0` → `rpcNOT_SUPPORTED` (pathfinding administratively
+ *     disabled).
+ *  2. `getValidatedLedgerAge()` > `kMAX_VALIDATED_LEDGER_AGE` (2 min) →
+ *     `rpcNO_NETWORK` (API v1) or `rpcNOT_SYNCED` (API v2+). Only checked in
+ *     the no-ledger (live-network) code path.
+ *  3. `LegacyPathFind` admission control → `rpcTOO_BUSY` when the concurrent
+ *     path-find ceiling (`kMAX_PATHFINDS_IN_PROGRESS = 2`) or job-queue depth
+ *     (`kMAX_PATHFIND_JOB_COUNT = 50`) is exceeded. Only checked in the
+ *     ledger-specified (synchronous) code path.
+ *
+ *  **Execution paths:**
+ *
+ *  - *No ledger specified* (networked mode only): Dispatches to the live
+ *    `PathRequestManager` via `makeLegacyPathRequest()`, then cooperatively
+ *    yields the `JobQueue::Coro` so the path-finding job can run on another
+ *    thread. The handler resumes after the completion callback re-posts the
+ *    coroutine, then calls `request->doStatus()` for the result. If
+ *    `makeLegacyPathRequest()` returns a null request (job queue full at
+ *    enqueue time), the error JSON it produced is returned directly without
+ *    yielding.
+ *
+ *  - *Ledger specified*: Fully synchronous. Resolves the ledger with
+ *    `RPC::lookupLedger()`, acquires a `LegacyPathFind` concurrency slot, and
+ *    calls `PathRequestManager::doLegacyPathRequest()` inline. Ledger metadata
+ *    already placed in `jvResult` by `lookupLedger()` is merged into the final
+ *    result.
+ *
+ *  `loadType` is set to `kFEE_HEAVY_BURDEN_RPC` unconditionally; path-finding
+ *  is one of the most compute-intensive operations on the RPC surface.
+ *
+ *  @note This function runs inside a `JobQueue::Coro` for the no-ledger path.
+ *      Two shutdown failure modes exist: (1) `makeLegacyPathRequest()` returns
+ *      null if the job queue rejects the path-find job; (2) the completion
+ *      callback's `Coro::post()` fails if the queue stops accepting work after
+ *      the path-find runs, in which case `Coro::resume()` is called instead so
+ *      the coroutine drains on the path-finding thread rather than deadlocking.
+ *  @note API v1 reports stale-ledger errors as `rpcNO_NETWORK`; API v2+
+ *      consolidates to `rpcNOT_SYNCED`.
+ *  @see `PathRequestManager::makeLegacyPathRequest()`,
+ *      `PathRequestManager::doLegacyPathRequest()`, `RPC::LegacyPathFind`
+ *  @deprecated Prefer `path_find` (WebSocket subscription) for new clients.
+ *  @param context  RPC dispatch context carrying the parsed request parameters,
+ *      resource consumer, coroutine handle, ledger master, and app handle.
+ *  @return JSON result containing the discovered paths, or an `rpcError` object
+ *      on any failure.
+ */
 json::Value
 doRipplePathFind(RPC::JsonContext& context)
 {
@@ -34,8 +97,6 @@ doRipplePathFind(RPC::JsonContext& context)
     if (!context.app.config().standalone() && !context.params.isMember(jss::ledger) &&
         !context.params.isMember(jss::ledger_index) && !context.params.isMember(jss::ledger_hash))
     {
-        // No ledger specified, use pathfinding defaults
-        // and dispatch to pathfinding engine
         if (context.app.getLedgerMaster().getValidatedLedgerAge() >
             RPC::Tuning::kMAX_VALIDATED_LEDGER_AGE)
         {
@@ -47,91 +108,25 @@ doRipplePathFind(RPC::JsonContext& context)
         PathRequest::pointer request;
         lpLedger = context.ledgerMaster.getClosedLedger();
 
-        // It doesn't look like there's much odd happening here, but you should
-        // be aware this code runs in a JobQueue::Coro, which is a coroutine.
-        // And we may be flipping around between threads.  Here's an overview:
+        // Shutdown failure modes for the coroutine/JobQueue interaction:
         //
-        // 1. We're running doRipplePathFind() due to a call to
-        //    ripple_path_find.  doRipplePathFind() is currently running
-        //    inside of a JobQueue::Coro using a JobQueue thread.
+        // 1. makeLegacyPathRequest() returns null if the JobQueue rejected
+        //    the path-find job (shutting down). The error JSON it produced
+        //    is returned directly; we do not yield.
         //
-        // 2. doRipplePathFind's call to makeLegacyPathRequest() enqueues the
-        //    path-finding request.  That request will (probably) run at some
-        //    indeterminate future time on a (probably different) JobQueue
-        //    thread.
-        //
-        // 3. As a continuation from that path-finding JobQueue thread, the
-        //    coroutine we're currently running in (!) is posted to the
-        //    JobQueue.  Because it is a continuation, that post won't
-        //    happen until the path-finding request completes.
-        //
-        // 4. Once the continuation is enqueued, and we have reason to think
-        //    the path-finding job is likely to run, then the coroutine we're
-        //    running in yield()s.  That means it surrenders its thread in
-        //    the JobQueue.  The coroutine is suspended, but ready to run,
-        //    because it is kept resident by a shared_ptr in the
-        //    path-finding continuation.
-        //
-        // 5. If all goes well then path-finding runs on a JobQueue thread
-        //    and executes its continuation.  The continuation posts this
-        //    same coroutine (!) to the JobQueue.
-        //
-        // 6. When the JobQueue calls this coroutine, this coroutine resumes
-        //    from the line below the coro->yield() and returns the
-        //    path-finding result.
-        //
-        // With so many moving parts, what could go wrong?
-        //
-        // Just in terms of the JobQueue refusing to add jobs at shutdown
-        // there are two specific things that can go wrong.
-        //
-        // 1. The path-finding Job queued by makeLegacyPathRequest() might be
-        //    rejected (because we're shutting down).
-        //
-        //    Fortunately this problem can be addressed by looking at the
-        //    return value of makeLegacyPathRequest().  If
-        //    makeLegacyPathRequest() cannot get a thread to run the path-find
-        //    on, then it returns an empty request.
-        //
-        // 2. The path-finding job might run, but the Coro::post() might be
-        //    rejected by the JobQueue (because we're shutting down).
-        //
-        //    We handle this case by resuming (not posting) the Coro.
-        //    By resuming the Coro, we allow the Coro to run to completion
-        //    on the current thread instead of requiring that it run on a
-        //    new thread from the JobQueue.
-        //
-        // Both of these failure modes are hard to recreate in a unit test
-        // because they are so dependent on inter-thread timing.  However
-        // the failure modes can be observed by synchronously (inside the
-        // xrpld source code) shutting down the application.  The code to
-        // do so looks like this:
-        //
-        //   context.app.signalStop();
-        //   while (! context.app.getJobQueue().jobCounter().joined()) { }
-        //
-        // The first line starts the process of shutting down the app.
-        // The second line waits until no more jobs can be added to the
-        // JobQueue before letting the thread continue.
-        //
-        // May 2017
+        // 2. The path-find job runs but Coro::post() is rejected (JobQueue
+        //    stopped accepting work). The completion lambda falls back to
+        //    Coro::resume() so the coroutine drains on the path-finding
+        //    thread rather than hanging the application on shutdown.
         jvResult = context.app.getPathRequestManager().makeLegacyPathRequest(
             request,
             [&context]() {
-                // Copying the shared_ptr keeps the coroutine alive up
-                // through the return.  Otherwise the storage under the
-                // captured reference could evaporate when we return from
-                // coroCopy->resume().  This is not strictly necessary, but
-                // will make maintenance easier.
+                // Copy the shared_ptr so the coroutine object stays alive
+                // through the return from resume(); the captured reference
+                // could otherwise evaporate beneath us.
                 std::shared_ptr<JobQueue::Coro> const coroCopy{context.coro};
                 if (!coroCopy->post())
-                {
-                    // The post() failed, so we won't get a thread to let
-                    // the Coro finish.  We'll call Coro::resume() so the
-                    // Coro can finish on our thread.  Otherwise the
-                    // application will hang on shutdown.
                     coroCopy->resume();
-                }
             },
             context.consumer,
             lpLedger,
@@ -145,7 +140,6 @@ doRipplePathFind(RPC::JsonContext& context)
         return jvResult;
     }
 
-    // The caller specified a ledger
     jvResult = RPC::lookupLedger(lpLedger, context);
     if (!lpLedger)
         return jvResult;