XRPLF · Tapanito · Aug 6, 2026 · Aug 6, 2026 · Aug 6, 2026 · Aug 6, 2026
diff --git a/.cspell.config.yaml b/.cspell.config.yaml
@@ -245,6 +245,11 @@ words:
   - queuable
   - Raphson
   - rcflags
+  - recognises
+  - renormalise
+  - Renormalise
+  - renormalises
+  - Renormalising
   - replayer
   - rerandomize
   - rerandomization

diff --git a/cmake/scripts/codegen/templates/LedgerEntry.h.mako b/cmake/scripts/codegen/templates/LedgerEntry.h.mako
@@ -2,6 +2,7 @@
 #pragma once
 
 #include <xrpl/protocol/STLedgerEntry.h>
+#include <xrpl/protocol/STNumber.h>  // IWYU pragma: keep
 #include <xrpl/protocol/STParsedJSON.h>
 #include <xrpl/protocol/jss.h>
 #include <xrpl/protocol_autogen/LedgerEntryBase.h>

diff --git a/include/xrpl/ledger/helpers/TokenHelpers.h b/include/xrpl/ledger/helpers/TokenHelpers.h
@@ -60,6 +60,33 @@ enum class AllowMPTOverflow : bool { No = false, Yes };
  */
 enum class WaiveMPTCanTransfer : bool { No = false, Yes };
 
+/**
+ * A caller that maintains its own cached total of a trust line's balance can
+ * ask the credit path to keep sfBalance representable at a scale of the
+ * caller's choosing, parking the remainder in sfDust, and to report what
+ * actually moved. Passing one of these IS the opt-in; the credit path's
+ * default is nullptr, which reproduces today's behaviour exactly.
+ *
+ * All fields below are RECEIVER-POSITIVE: positive means the receiver's
+ * holdings grew. See docs/plan-vault-dust-b-prime-field-accounting-kept.md
+ * §5.2 for the full rationale, including why targetScale has no default.
+ */
+struct DustSplit
+{
+    explicit DustSplit(int targetScale) : targetScale(targetScale)
+    {
+    }
+
+    // --- in ---
+    int targetScale;  // exponent sfBalance must remain representable at
+
+    // --- out ---
+    Number balanceDelta{};  // how much sfBalance moved
+    Number dustDelta{};     // how much sfDust moved. SIGNED: negative means
+                            // previously-deferred dust was promoted into
+                            // sfBalance by this operation.
+};
+
 /* Check if MPToken (for MPT) or trust line (for IOU) exists:
  * - StrongAuth - before checking if authorization is required
  * - WeakAuth
@@ -386,7 +413,8 @@ accountSend(
     beast::Journal j,
     SLE::ref sponsorSle = {},
     WaiveTransferFee waiveFee = WaiveTransferFee::No,
-    AllowMPTOverflow allowOverflow = AllowMPTOverflow::No);
+    AllowMPTOverflow allowOverflow = AllowMPTOverflow::No,
+    DustSplit* dust = nullptr);
 
 using MultiplePaymentDestinations = std::vector<std::pair<AccountID, Number>>;
 /**

diff --git a/include/xrpl/ledger/helpers/VaultHelpers.h b/include/xrpl/ledger/helpers/VaultHelpers.h
@@ -1,11 +1,16 @@
 #pragma once
 
+#include <xrpl/basics/Number.h>
+#include <xrpl/beast/utility/Journal.h>
+#include <xrpl/ledger/ApplyView.h>
 #include <xrpl/ledger/ReadView.h>
 #include <xrpl/protocol/AccountID.h>
 #include <xrpl/protocol/Protocol.h>
 #include <xrpl/protocol/STAmount.h>
 #include <xrpl/protocol/STLedgerEntry.h>
+#include <xrpl/protocol/TER.h>
 
+#include <expected>
 #include <optional>
 
 namespace xrpl {
@@ -123,4 +128,111 @@ isSoleShareholder(ReadView const& view, AccountID const& account, SLE::const_ref
 [[nodiscard]] VaultVersion
 getVaultVersion(SLE::const_ref vault);
 
+/**
+ * Whether this Vault's custody trust line participates in the sfDust
+ * mechanism (docs/plan-vault-dust-b-prime-field-accounting-kept.md §2.2).
+ * True only for a cash-basis Vault (sfLEVersion == VaultVersion::CashBasis)
+ * holding an IOU asset. A Vault that pre-dates the amendment (Legacy) or
+ * that holds an integral asset (XRP/MPT, which never produces sub-quantum
+ * remainders) is excluded, and every dust-aware code path is skipped for
+ * it, unconditionally and forever.
+ *
+ * @param vault The vault SLE.
+ */
+[[nodiscard]] bool
+useVaultDust(SLE::const_ref vault);
+
+/**
+ * Promotes whole quanta of dust stranded on a Vault's custody line back
+ * into sfBalance after a scale-refining removal (VaultWithdraw,
+ * VaultClawback, LoanManage::defaultLoan) — the only situation that can
+ * leave representable value in sfDust with no accompanying credit to
+ * recompute it (every credit already promotes automatically, see
+ * TokenHelpers.h's DustSplit). A no-op when useVaultDust(vault) is false,
+ * when the custody line does not exist, or when sfDust is still below one
+ * quantum.
+ *
+ * Moves both sfAssetsAvailable and sfAssetsTotal by the same amount: this
+ * recognises deferred cash and creates no new receivable, so
+ * AssetsTotal - AssetsAvailable must be unchanged by this call (the same
+ * receivable-invariance law as addAssetsToVault's dust adjustment, with
+ * recognitionDelta == 0).
+ *
+ * @param view The ApplyView to mutate.
+ * @param vault The vault SLE (mutated in place; caller retains ownership).
+ * @param j Journal.
+ *
+ * @return tesSUCCESS always (there is no "still sub-quantum" failure mode).
+ */
+[[nodiscard]] TER
+maybeRenormaliseVaultDust(ApplyView& view, SLE::ref vault, beast::Journal j);
+
+/**
+ * The single owner of every write to a Vault's two accounting fields,
+ * sfAssetsAvailable and sfAssetsTotal, for a cash-moving-in operation
+ * (deposit, repayment, or default settlement).
+ *
+ * On this branch this is a pure bookkeeping refactor with no behaviour
+ * change: it performs exactly
+ *   sfAssetsAvailable += cashIn
+ *   sfAssetsTotal     += recognitionDelta
+ *   view.update(vault)
+ * and nothing else. In particular it does NOT enforce
+ * sfAssetsAvailable <= sfAssetsTotal — callers keep their own guard exactly
+ * where it is today, because that guard is order-sensitive and, at at least
+ * one call site (LoanManage::defaultLoan), the fields legitimately cross
+ * transiently before an existing post-write correction runs.
+ *
+ * @param view The ApplyView to mutate.
+ * @param vault The vault SLE (mutated in place; caller retains ownership).
+ * @param cashIn The amount of cash arriving at the vault's main custody.
+ *               Must already be rounded to whatever scale the caller's
+ *               transactor uses; this function performs no rounding.
+ * @param recognitionDelta The signed amount sfAssetsTotal should recognise,
+ *                          independently of cashIn.
+ * @param j Journal (currently unused; reserved for the dust-mechanism
+ *          amendment gate that lands on the solution branches).
+ *
+ * @return What sfAssetsAvailable actually moved by. On this branch that is
+ *         always exactly cashIn.
+ */
+[[nodiscard]] std::expected<Number, TER>
+addAssetsToVault(
+    ApplyView& view,
+    SLE::ref vault,
+    Number const& cashIn,
+    Number const& recognitionDelta,
+    beast::Journal j);
+
+/**
+ * The counterpart of addAssetsToVault for a cash-moving-out operation
+ * (withdrawal, clawback, or loan funding). Performs
+ *   sfAssetsAvailable -= cashOut
+ *   sfAssetsTotal     += recognitionDelta
+ *   view.update(vault)
+ * See addAssetsToVault for the guard-placement rationale.
+ *
+ * @return What sfAssetsAvailable actually moved by (as a negative number).
+ *         On this branch that is always exactly -cashOut.
+ */
+[[nodiscard]] std::expected<Number, TER>
+removeAssetsFromVault(
+    ApplyView& view,
+    SLE::ref vault,
+    Number const& cashOut,
+    Number const& recognitionDelta,
+    beast::Journal j);
+
+/**
+ * The terminal-withdrawal entry point: assigns both accounting fields to
+ * zero. This is an assignment, not a delta, which is why it is a separate
+ * function rather than a degenerate call to removeAssetsFromVault
+ * (VaultWithdraw.cpp's "Do not let dust accumulate in the Vault" branch).
+ *
+ * @return sfAssetsAvailable's value immediately before it was zeroed (i.e.
+ *         what the caller still owes the departing shareholder).
+ */
+[[nodiscard]] std::expected<Number, TER>
+closeVaultAssets(ApplyView& view, SLE::ref vault, beast::Journal j);
+
 }  // namespace xrpl
diff --git a/include/xrpl/protocol/detail/ledger_entries.macro b/include/xrpl/protocol/detail/ledger_entries.macro
@@ -291,6 +291,7 @@ LEDGER_ENTRY(ltRIPPLE_STATE, 0x0072, RippleState, state, ({
     {sfHighQualityOut,       SoeOptional},
     {sfHighSponsor,          SoeOptional},
     {sfLowSponsor,           SoeOptional},
+    {sfDust,                 SoeDefault},
 }))
 
 /** The ledger object which lists the network's fee settings.

diff --git a/include/xrpl/protocol/detail/sfields.macro b/include/xrpl/protocol/detail/sfields.macro
@@ -236,6 +236,11 @@ TYPED_SFIELD(sfPrincipalRequested,       NUMBER,     14)
 TYPED_SFIELD(sfTotalValueOutstanding,    NUMBER,     15, SField::kSmdNeedsAsset | SField::kSmdDefault)
 TYPED_SFIELD(sfPeriodicPayment,          NUMBER,     16)
 TYPED_SFIELD(sfManagementFeeOutstanding, NUMBER,     17, SField::kSmdNeedsAsset | SField::kSmdDefault)
+// sfDust is deliberately WITHOUT kSmdNeedsAsset: that flag rounds the field
+// to the asset's representable precision via associateAsset(), which is the
+// opposite of this field's purpose (it exists to hold value finer than that
+// precision). See docs/plan-vault-dust-b-prime-field-accounting-kept.md §4.
+TYPED_SFIELD(sfDust,                     NUMBER,     18, SField::kSmdDefault)
 
 // int32
 TYPED_SFIELD(sfLoanScale,                INT32,      1)

diff --git a/include/xrpl/protocol_autogen/ledger_entries/AMM.h b/include/xrpl/protocol_autogen/ledger_entries/AMM.h
@@ -2,6 +2,7 @@
 #pragma once
 
 #include <xrpl/protocol/STLedgerEntry.h>
+#include <xrpl/protocol/STNumber.h>  // IWYU pragma: keep
 #include <xrpl/protocol/STParsedJSON.h>
 #include <xrpl/protocol/jss.h>
 #include <xrpl/protocol_autogen/LedgerEntryBase.h>

diff --git a/include/xrpl/protocol_autogen/ledger_entries/AccountRoot.h b/include/xrpl/protocol_autogen/ledger_entries/AccountRoot.h
@@ -2,6 +2,7 @@
 #pragma once
 
 #include <xrpl/protocol/STLedgerEntry.h>
+#include <xrpl/protocol/STNumber.h>  // IWYU pragma: keep
 #include <xrpl/protocol/STParsedJSON.h>
 #include <xrpl/protocol/jss.h>
 #include <xrpl/protocol_autogen/LedgerEntryBase.h>

diff --git a/include/xrpl/protocol_autogen/ledger_entries/Amendments.h b/include/xrpl/protocol_autogen/ledger_entries/Amendments.h
@@ -2,6 +2,7 @@
 #pragma once
 
 #include <xrpl/protocol/STLedgerEntry.h>
+#include <xrpl/protocol/STNumber.h>  // IWYU pragma: keep
 #include <xrpl/protocol/STParsedJSON.h>
 #include <xrpl/protocol/jss.h>
 #include <xrpl/protocol_autogen/LedgerEntryBase.h>

diff --git a/include/xrpl/protocol_autogen/ledger_entries/Bridge.h b/include/xrpl/protocol_autogen/ledger_entries/Bridge.h
@@ -2,6 +2,7 @@
 #pragma once
 
 #include <xrpl/protocol/STLedgerEntry.h>
+#include <xrpl/protocol/STNumber.h>  // IWYU pragma: keep
 #include <xrpl/protocol/STParsedJSON.h>
 #include <xrpl/protocol/jss.h>
 #include <xrpl/protocol_autogen/LedgerEntryBase.h>

diff --git a/include/xrpl/protocol_autogen/ledger_entries/Check.h b/include/xrpl/protocol_autogen/ledger_entries/Check.h
@@ -2,6 +2,7 @@
 #pragma once
 
 #include <xrpl/protocol/STLedgerEntry.h>
+#include <xrpl/protocol/STNumber.h>  // IWYU pragma: keep
 #include <xrpl/protocol/STParsedJSON.h>
 #include <xrpl/protocol/jss.h>
 #include <xrpl/protocol_autogen/LedgerEntryBase.h>

diff --git a/include/xrpl/protocol_autogen/ledger_entries/Credential.h b/include/xrpl/protocol_autogen/ledger_entries/Credential.h
@@ -2,6 +2,7 @@
 #pragma once
 
 #include <xrpl/protocol/STLedgerEntry.h>
+#include <xrpl/protocol/STNumber.h>  // IWYU pragma: keep
 #include <xrpl/protocol/STParsedJSON.h>
 #include <xrpl/protocol/jss.h>
 #include <xrpl/protocol_autogen/LedgerEntryBase.h>

diff --git a/include/xrpl/protocol_autogen/ledger_entries/DID.h b/include/xrpl/protocol_autogen/ledger_entries/DID.h
@@ -2,6 +2,7 @@
 #pragma once
 
 #include <xrpl/protocol/STLedgerEntry.h>
+#include <xrpl/protocol/STNumber.h>  // IWYU pragma: keep
 #include <xrpl/protocol/STParsedJSON.h>
 #include <xrpl/protocol/jss.h>
 #include <xrpl/protocol_autogen/LedgerEntryBase.h>

diff --git a/include/xrpl/protocol_autogen/ledger_entries/Delegate.h b/include/xrpl/protocol_autogen/ledger_entries/Delegate.h
@@ -2,6 +2,7 @@
 #pragma once
 
 #include <xrpl/protocol/STLedgerEntry.h>
+#include <xrpl/protocol/STNumber.h>  // IWYU pragma: keep
 #include <xrpl/protocol/STParsedJSON.h>
 #include <xrpl/protocol/jss.h>
 #include <xrpl/protocol_autogen/LedgerEntryBase.h>

diff --git a/include/xrpl/protocol_autogen/ledger_entries/DepositPreauth.h b/include/xrpl/protocol_autogen/ledger_entries/DepositPreauth.h
@@ -2,6 +2,7 @@
 #pragma once
 
 #include <xrpl/protocol/STLedgerEntry.h>
+#include <xrpl/protocol/STNumber.h>  // IWYU pragma: keep
 #include <xrpl/protocol/STParsedJSON.h>
 #include <xrpl/protocol/jss.h>
 #include <xrpl/protocol_autogen/LedgerEntryBase.h>

diff --git a/include/xrpl/protocol_autogen/ledger_entries/DirectoryNode.h b/include/xrpl/protocol_autogen/ledger_entries/DirectoryNode.h
@@ -2,6 +2,7 @@
 #pragma once
 
 #include <xrpl/protocol/STLedgerEntry.h>
+#include <xrpl/protocol/STNumber.h>  // IWYU pragma: keep
 #include <xrpl/protocol/STParsedJSON.h>
 #include <xrpl/protocol/jss.h>
 #include <xrpl/protocol_autogen/LedgerEntryBase.h>

diff --git a/include/xrpl/protocol_autogen/ledger_entries/Escrow.h b/include/xrpl/protocol_autogen/ledger_entries/Escrow.h
@@ -2,6 +2,7 @@
 #pragma once
 
 #include <xrpl/protocol/STLedgerEntry.h>
+#include <xrpl/protocol/STNumber.h>  // IWYU pragma: keep
 #include <xrpl/protocol/STParsedJSON.h>
 #include <xrpl/protocol/jss.h>
 #include <xrpl/protocol_autogen/LedgerEntryBase.h>

diff --git a/include/xrpl/protocol_autogen/ledger_entries/FeeSettings.h b/include/xrpl/protocol_autogen/ledger_entries/FeeSettings.h
@@ -2,6 +2,7 @@
 #pragma once
 
 #include <xrpl/protocol/STLedgerEntry.h>
+#include <xrpl/protocol/STNumber.h>  // IWYU pragma: keep
 #include <xrpl/protocol/STParsedJSON.h>
 #include <xrpl/protocol/jss.h>
 #include <xrpl/protocol_autogen/LedgerEntryBase.h>

diff --git a/include/xrpl/protocol_autogen/ledger_entries/LedgerHashes.h b/include/xrpl/protocol_autogen/ledger_entries/LedgerHashes.h
@@ -2,6 +2,7 @@
 #pragma once
 
 #include <xrpl/protocol/STLedgerEntry.h>
+#include <xrpl/protocol/STNumber.h>  // IWYU pragma: keep
 #include <xrpl/protocol/STParsedJSON.h>
 #include <xrpl/protocol/jss.h>
 #include <xrpl/protocol_autogen/LedgerEntryBase.h>

diff --git a/include/xrpl/protocol_autogen/ledger_entries/Loan.h b/include/xrpl/protocol_autogen/ledger_entries/Loan.h
@@ -2,6 +2,7 @@
 #pragma once
 
 #include <xrpl/protocol/STLedgerEntry.h>
+#include <xrpl/protocol/STNumber.h>  // IWYU pragma: keep
 #include <xrpl/protocol/STParsedJSON.h>
 #include <xrpl/protocol/jss.h>
 #include <xrpl/protocol_autogen/LedgerEntryBase.h>

diff --git a/include/xrpl/protocol_autogen/ledger_entries/LoanBroker.h b/include/xrpl/protocol_autogen/ledger_entries/LoanBroker.h
@@ -2,6 +2,7 @@
 #pragma once
 
 #include <xrpl/protocol/STLedgerEntry.h>
+#include <xrpl/protocol/STNumber.h>  // IWYU pragma: keep
 #include <xrpl/protocol/STParsedJSON.h>
 #include <xrpl/protocol/jss.h>
 #include <xrpl/protocol_autogen/LedgerEntryBase.h>

diff --git a/include/xrpl/protocol_autogen/ledger_entries/MPToken.h b/include/xrpl/protocol_autogen/ledger_entries/MPToken.h
@@ -2,6 +2,7 @@
 #pragma once
 
 #include <xrpl/protocol/STLedgerEntry.h>
+#include <xrpl/protocol/STNumber.h>  // IWYU pragma: keep
 #include <xrpl/protocol/STParsedJSON.h>
 #include <xrpl/protocol/jss.h>
 #include <xrpl/protocol_autogen/LedgerEntryBase.h>

diff --git a/include/xrpl/protocol_autogen/ledger_entries/MPTokenIssuance.h b/include/xrpl/protocol_autogen/ledger_entries/MPTokenIssuance.h
@@ -2,6 +2,7 @@
 #pragma once
 
 #include <xrpl/protocol/STLedgerEntry.h>
+#include <xrpl/protocol/STNumber.h>  // IWYU pragma: keep
 #include <xrpl/protocol/STParsedJSON.h>
 #include <xrpl/protocol/jss.h>
 #include <xrpl/protocol_autogen/LedgerEntryBase.h>

diff --git a/include/xrpl/protocol_autogen/ledger_entries/NFTokenOffer.h b/include/xrpl/protocol_autogen/ledger_entries/NFTokenOffer.h
@@ -2,6 +2,7 @@
 #pragma once
 
 #include <xrpl/protocol/STLedgerEntry.h>
+#include <xrpl/protocol/STNumber.h>  // IWYU pragma: keep
 #include <xrpl/protocol/STParsedJSON.h>
 #include <xrpl/protocol/jss.h>
 #include <xrpl/protocol_autogen/LedgerEntryBase.h>

diff --git a/include/xrpl/protocol_autogen/ledger_entries/NFTokenPage.h b/include/xrpl/protocol_autogen/ledger_entries/NFTokenPage.h
@@ -2,6 +2,7 @@
 #pragma once
 
 #include <xrpl/protocol/STLedgerEntry.h>
+#include <xrpl/protocol/STNumber.h>  // IWYU pragma: keep
 #include <xrpl/protocol/STParsedJSON.h>
 #include <xrpl/protocol/jss.h>
 #include <xrpl/protocol_autogen/LedgerEntryBase.h>

diff --git a/include/xrpl/protocol_autogen/ledger_entries/NegativeUNL.h b/include/xrpl/protocol_autogen/ledger_entries/NegativeUNL.h
@@ -2,6 +2,7 @@
 #pragma once
 
 #include <xrpl/protocol/STLedgerEntry.h>
+#include <xrpl/protocol/STNumber.h>  // IWYU pragma: keep
 #include <xrpl/protocol/STParsedJSON.h>
 #include <xrpl/protocol/jss.h>
 #include <xrpl/protocol_autogen/LedgerEntryBase.h>

diff --git a/include/xrpl/protocol_autogen/ledger_entries/Offer.h b/include/xrpl/protocol_autogen/ledger_entries/Offer.h
@@ -2,6 +2,7 @@
 #pragma once
 
 #include <xrpl/protocol/STLedgerEntry.h>
+#include <xrpl/protocol/STNumber.h>  // IWYU pragma: keep
 #include <xrpl/protocol/STParsedJSON.h>
 #include <xrpl/protocol/jss.h>
 #include <xrpl/protocol_autogen/LedgerEntryBase.h>

diff --git a/include/xrpl/protocol_autogen/ledger_entries/Oracle.h b/include/xrpl/protocol_autogen/ledger_entries/Oracle.h
@@ -2,6 +2,7 @@
 #pragma once
 
 #include <xrpl/protocol/STLedgerEntry.h>
+#include <xrpl/protocol/STNumber.h>  // IWYU pragma: keep
 #include <xrpl/protocol/STParsedJSON.h>
 #include <xrpl/protocol/jss.h>
 #include <xrpl/protocol_autogen/LedgerEntryBase.h>

diff --git a/include/xrpl/protocol_autogen/ledger_entries/PayChannel.h b/include/xrpl/protocol_autogen/ledger_entries/PayChannel.h
@@ -2,6 +2,7 @@
 #pragma once
 
 #include <xrpl/protocol/STLedgerEntry.h>
+#include <xrpl/protocol/STNumber.h>  // IWYU pragma: keep
 #include <xrpl/protocol/STParsedJSON.h>
 #include <xrpl/protocol/jss.h>
 #include <xrpl/protocol_autogen/LedgerEntryBase.h>