Add canonical "scale" computation to Number

- Requires a template for STAmount and Asset.
- Update tests and computeMinScale from #6217 to use scale.
- Convert a few other places to use "scale" correctly.

include/xrpl/basics/Number.h

@@ -109,6 +109,10 @@ template <class T>
 concept Integral64 =
     std::is_same_v<T, std::int64_t> || std::is_same_v<T, std::uint64_t>;
 
+template <class STAmount, class Asset>
+concept CanUseAsScale = requires(Asset a, Number n) { STAmount(a, n); } &&
+    requires(STAmount s) { s.exponent(); };
+
 /** Number is a floating point type that can represent a wide range of values.
  *
  * It can represent all values that can be represented by an STAmount -
@@ -268,6 +272,26 @@ public:
     constexpr int
     exponent() const noexcept;
 
+    /** Get the scale of this Number for the given asset.
+     *
+     * "scale" is similar to "exponent", but from the perspective of STAmount,
+     * which has different rules for determining the exponent than Number.
+     *
+     * Because Number does not have access to STAmount or Asset, this function
+     * is implemented as a template, with the expectation that it will only be
+     * used by those types. Any types that fit the requirements will work,
+     * though, if there's a need.
+     *
+     * @tparam STAmount The STAmount type.
+     * @tparam Asset The Asset type.
+     * @param asset The asset to use for determining the scale.
+     * @return The scale of this Number for the given asset.
+     */
+    template <class STAmount, class Asset>
+    int
+    scale(Asset const& asset) const
+        requires CanUseAsScale<STAmount, Asset>;
+
     constexpr Number
     operator+() const noexcept;
     constexpr Number
@@ -602,6 +626,14 @@ Number::exponent() const noexcept
     return e;
 }
 
+template <class STAmount, class Asset>
+int
+Number::scale(Asset const& asset) const
+    requires CanUseAsScale<STAmount, Asset>
+{
+    return STAmount{asset, *this}.exponent();
+}
+
 inline constexpr Number
 Number::operator+() const noexcept
 {

src/test/app/Invariants_test.cpp

@@ -4,6 +4,7 @@
 
 #include <xrpld/app/tx/apply.h>
 #include <xrpld/app/tx/detail/ApplyContext.h>
+#include <xrpld/app/tx/detail/InvariantCheck.h>
 
 #include <xrpl/beast/unit_test/suite.h>
 #include <xrpl/beast/utility/Journal.h>
@@ -20,6 +21,9 @@
 
 #include <boost/algorithm/string/predicate.hpp>
 
+#include <initializer_list>
+#include <string>
+
 namespace xrpl {
 namespace test {
 
@@ -3888,6 +3892,122 @@ class Invariants_test : public beast::unit_test::suite
             precloseMpt);
     }
 
+    void
+    testVaultComputeMinScale()
+    {
+        using namespace jtx;
+
+        Account const issuer{"issuer"};
+        PrettyAsset const vaultAsset = issuer["IOU"];
+
+        struct TestCase
+        {
+            std::string name;
+            std::int32_t expectedMinScale;
+            std::initializer_list<Number const> values;
+        };
+
+        NumberMantissaScaleGuard g{MantissaRange::large};
+
+        auto const testCases = std::vector<TestCase>{
+            {
+                .name = "No values",
+                .expectedMinScale = 0,
+                .values = {},
+            },
+            {
+                .name = "Mixed integer and Number values",
+                .expectedMinScale = -15,
+                .values = {1, -1, Number{10, -1}},
+            },
+            {
+                .name = "Mixed scales",
+                .expectedMinScale = -17,
+                .values = {Number{1, -2}, Number{5, -3}, Number{3, -2}},
+            },
+            {
+                .name = "Mixed mantissa sizes",
+                .expectedMinScale = -12,
+                .values =
+                    {Number{1},
+                     Number{1234, -3},
+                     Number{12345, -6},
+                     Number{123, 1}},
+            },
+        };
+
+        for (auto const& tc : testCases)
+        {
+            testcase("vault computeMinScale: " + tc.name);
+
+            auto const actualScale =
+                ValidVault::computeMinScale(vaultAsset, tc.values);
+
+            BEAST_EXPECTS(
+                actualScale == tc.expectedMinScale,
+                "expected: " + std::to_string(tc.expectedMinScale) +
+                    ", actual: " + std::to_string(actualScale));
+            for (auto const& num : tc.values)
+            {
+                // None of these scales are far enough apart that rounding the
+                // values would lose information, so check that the rounded
+                // value matches the original.
+                auto const actualRounded =
+                    roundToAsset(vaultAsset, num, actualScale);
+                BEAST_EXPECTS(
+                    actualRounded == num,
+                    "number " + to_string(num) + " rounded to scale " +
+                        std::to_string(actualScale) + " is " +
+                        to_string(actualRounded));
+            }
+        }
+
+        auto const testCases2 = std::vector<TestCase>{
+            {
+                .name = "False equivalence",
+                .expectedMinScale = -15,
+                .values =
+                    {
+                        Number{1234567890123456789, -18},
+                        Number{12345, -4},
+                        Number{1},
+                    },
+            },
+        };
+
+        // Unlike the first set of test cases, the values in these test could
+        // look equivalent if using the wrong scale.
+        for (auto const& tc : testCases2)
+        {
+            testcase("vault computeMinScale: " + tc.name);
+
+            auto const actualScale =
+                ValidVault::computeMinScale(vaultAsset, tc.values);
+
+            BEAST_EXPECTS(
+                actualScale == tc.expectedMinScale,
+                "expected: " + std::to_string(tc.expectedMinScale) +
+                    ", actual: " + std::to_string(actualScale));
+            std::optional<Number> first;
+            Number firstRounded;
+            for (auto const& num : tc.values)
+            {
+                if (!first)
+                {
+                    first = num;
+                    firstRounded = roundToAsset(vaultAsset, num, actualScale);
+                    continue;
+                }
+                auto const numRounded =
+                    roundToAsset(vaultAsset, num, actualScale);
+                BEAST_EXPECTS(
+                    numRounded != firstRounded,
+                    "at a scale of " + std::to_string(actualScale) + " " +
+                        to_string(num) + " == " + to_string(*first));
+            }
+        }
+    }
+
 public:
     void
     run() override
@@ -3911,6 +4031,7 @@ public:
         testValidPseudoAccounts();
         testValidLoanBroker();
         testVault();
+        testVaultComputeMinScale();
     }
 };
 

src/xrpld/app/misc/LendingHelpers.h

@@ -176,8 +176,7 @@ getAssetsTotalScale(SLE::const_ref vaultSle)
 {
     if (!vaultSle)
         return Number::minExponent - 1;  // LCOV_EXCL_LINE
-    return STAmount{vaultSle->at(sfAsset), vaultSle->at(sfAssetsTotal)}
-        .exponent();
+    return vaultSle->at(sfAssetsTotal).scale<STAmount>(vaultSle->at(sfAsset));
 }
 
 TER

src/xrpld/app/tx/detail/InvariantCheck.cpp

@@ -22,7 +22,12 @@
 #include <xrpl/protocol/Units.h>
 #include <xrpl/protocol/nftPageMask.h>
 
+#include <algorithm>
+#include <cstddef>
 #include <cstdint>
+#include <initializer_list>
+#include <iostream>
+#include <iterator>
 #include <optional>
 
 namespace xrpl {
@@ -3196,16 +3201,29 @@ ValidVault::finalize(
                     "xrpl::ValidVault::finalize : deposit updated a vault");
                 auto const& beforeVault = beforeVault_[0];
 
-                auto const vaultDeltaAssets = deltaAssets(afterVault.pseudoId);
-
-                if (!vaultDeltaAssets)
+                auto const maybeVaultDeltaAssets =
+                    deltaAssets(afterVault.pseudoId);
+                if (!maybeVaultDeltaAssets)
                 {
                     JLOG(j.fatal()) <<  //
                         "Invariant failed: deposit must change vault balance";
                     return false;  // That's all we can do
                 }
 
-                if (*vaultDeltaAssets > tx[sfAmount])
+                // Get the coarsest scale to round calculations to
+                auto const minScale = computeMinScale(
+                    vaultAsset,
+                    {
+                        *maybeVaultDeltaAssets,
+                        afterVault.assetsTotal - beforeVault.assetsTotal,
+                        afterVault.assetsAvailable -
+                            beforeVault.assetsAvailable,
+                    });
+
+                auto const vaultDeltaAssets =
+                    roundToAsset(vaultAsset, *maybeVaultDeltaAssets, minScale);
+
+                if (vaultDeltaAssets > tx[sfAmount])
                 {
                     JLOG(j.fatal()) <<  //
                         "Invariant failed: deposit must not change vault "
@@ -3213,7 +3231,7 @@ ValidVault::finalize(
                     result = false;
                 }
 
-                if (*vaultDeltaAssets <= zero)
+                if (vaultDeltaAssets <= zero)
                 {
                     JLOG(j.fatal()) <<  //
                         "Invariant failed: deposit must increase vault balance";
@@ -3230,16 +3248,24 @@ ValidVault::finalize(
 
                 if (!issuerDeposit)
                 {
-                    auto const accountDeltaAssets = deltaAssetsTxAccount();
-                    if (!accountDeltaAssets)
+                    auto const maybeAccDeltaAssets = deltaAssetsTxAccount();
+                    if (!maybeAccDeltaAssets)
                     {
                         JLOG(j.fatal()) <<  //
                             "Invariant failed: deposit must change depositor "
                             "balance";
                         return false;
                     }
+                    auto const localMinScale = std::min(
+                        minScale,
+                        computeMinScale(vaultAsset, {*maybeAccDeltaAssets}));
 
-                    if (*accountDeltaAssets >= zero)
+                    auto const accountDeltaAssets = roundToAsset(
+                        vaultAsset, *maybeAccDeltaAssets, localMinScale);
+                    auto const localVaultDeltaAssets = roundToAsset(
+                        vaultAsset, vaultDeltaAssets, localMinScale);
+
+                    if (accountDeltaAssets >= zero)
                     {
                         JLOG(j.fatal()) <<  //
                             "Invariant failed: deposit must decrease depositor "
@@ -3247,7 +3273,7 @@ ValidVault::finalize(
                         result = false;
                     }
 
-                    if (*accountDeltaAssets * -1 != *vaultDeltaAssets)
+                    if (localVaultDeltaAssets * -1 != accountDeltaAssets)
                     {
                         JLOG(j.fatal()) <<  //
                             "Invariant failed: deposit must change vault and "
@@ -3265,16 +3291,17 @@ ValidVault::finalize(
                     result = false;
                 }
 
-                auto const accountDeltaShares = deltaShares(tx[sfAccount]);
-                if (!accountDeltaShares)
+                auto const maybeAccDeltaShares = deltaShares(tx[sfAccount]);
+                if (!maybeAccDeltaShares)
                 {
                     JLOG(j.fatal()) <<  //
                         "Invariant failed: deposit must change depositor "
                         "shares";
                     return false;  // That's all we can do
                 }
-
-                if (*accountDeltaShares <= zero)
+                // We don't need to round shares, they are integral MPT
+                auto const accountDeltaShares = *maybeAccDeltaShares;
+                if (accountDeltaShares <= zero)
                 {
                     JLOG(j.fatal()) <<  //
                         "Invariant failed: deposit must increase depositor "
@@ -3282,15 +3309,18 @@ ValidVault::finalize(
                     result = false;
                 }
 
-                auto const vaultDeltaShares = deltaShares(afterVault.pseudoId);
-                if (!vaultDeltaShares || *vaultDeltaShares == zero)
+                auto const maybeVaultDeltaShares =
+                    deltaShares(afterVault.pseudoId);
+                if (!maybeVaultDeltaShares || *maybeVaultDeltaShares == zero)
                 {
                     JLOG(j.fatal()) <<  //
                         "Invariant failed: deposit must change vault shares";
                     return false;  // That's all we can do
                 }
 
-                if (*vaultDeltaShares * -1 != *accountDeltaShares)
+                // We don't need to round shares, they are integral MPT
+                auto const vaultDeltaShares = *maybeVaultDeltaShares;
+                if (vaultDeltaShares * -1 != accountDeltaShares)
                 {
                     JLOG(j.fatal()) <<  //
                         "Invariant failed: deposit must change depositor and "
@@ -3298,15 +3328,22 @@ ValidVault::finalize(
                     result = false;
                 }
 
-                if (beforeVault.assetsTotal + *vaultDeltaAssets !=
-                    afterVault.assetsTotal)
+                auto const assetTotalDelta = roundToAsset(
+                    vaultAsset,
+                    afterVault.assetsTotal - beforeVault.assetsTotal,
+                    minScale);
+                if (assetTotalDelta != vaultDeltaAssets)
                 {
                     JLOG(j.fatal()) << "Invariant failed: deposit and assets "
                                        "outstanding must add up";
                     result = false;
                 }
-                if (beforeVault.assetsAvailable + *vaultDeltaAssets !=
-                    afterVault.assetsAvailable)
+
+                auto const assetAvailableDelta = roundToAsset(
+                    vaultAsset,
+                    afterVault.assetsAvailable - beforeVault.assetsAvailable,
+                    minScale);
+                if (assetAvailableDelta != vaultDeltaAssets)
                 {
                     JLOG(j.fatal()) << "Invariant failed: deposit and assets "
                                        "available must add up";
@@ -3324,22 +3361,32 @@ ValidVault::finalize(
                     "vault");
                 auto const& beforeVault = beforeVault_[0];
 
-                auto const vaultDeltaAssets = deltaAssets(afterVault.pseudoId);
+                auto const maybeVaultDeltaAssets =
+                    deltaAssets(afterVault.pseudoId);
 
-                if (!vaultDeltaAssets)
+                if (!maybeVaultDeltaAssets)
                 {
                     JLOG(j.fatal()) << "Invariant failed: withdrawal must "
                                        "change vault balance";
                     return false;  // That's all we can do
                 }
 
-                if (*vaultDeltaAssets >= zero)
+                // Get the most coarse scale to round calculations to
+                auto const minScale = computeMinScale(
+                    vaultAsset,
+                    {*maybeVaultDeltaAssets,
+                     afterVault.assetsTotal - beforeVault.assetsTotal,
+                     afterVault.assetsAvailable - beforeVault.assetsAvailable});
+
+                auto const vaultPseudoDeltaAssets =
+                    roundToAsset(vaultAsset, *maybeVaultDeltaAssets, minScale);
+
+                if (vaultPseudoDeltaAssets >= zero)
                 {
                     JLOG(j.fatal()) << "Invariant failed: withdrawal must "
                                        "decrease vault balance";
                     result = false;
                 }
-
                 // Any payments (including withdrawal) going to the issuer
                 // do not change their balance, but destroy funds instead.
                 bool const issuerWithdrawal = [&]() -> bool {
@@ -3352,8 +3399,8 @@ ValidVault::finalize(
 
                 if (!issuerWithdrawal)
                 {
-                    auto const accountDeltaAssets = deltaAssetsTxAccount();
-                    auto const otherAccountDelta =
+                    auto const maybeAccDelta = deltaAssetsTxAccount();
+                    auto const maybeOtherAccDelta =
                         [&]() -> std::optional<Number> {
                         if (auto const destination = tx[~sfDestination];
                             destination && *destination != tx[sfAccount])
@@ -3361,8 +3408,8 @@ ValidVault::finalize(
                         return std::nullopt;
                     }();
 
-                    if (accountDeltaAssets.has_value() ==
-                        otherAccountDelta.has_value())
+                    if (maybeAccDelta.has_value() ==
+                        maybeOtherAccDelta.has_value())
                     {
                         JLOG(j.fatal()) <<  //
                             "Invariant failed: withdrawal must change one "
@@ -3371,10 +3418,18 @@ ValidVault::finalize(
                     }
 
                     auto const destinationDelta =  //
-                        accountDeltaAssets ? *accountDeltaAssets
-                                           : *otherAccountDelta;
+                        maybeAccDelta ? *maybeAccDelta : *maybeOtherAccDelta;
 
-                    if (destinationDelta <= zero)
+                    // the scale of destinationDelta can be coarser than
+                    // minScale, so we take that into account when rounding
+                    auto const localMinScale = std::min(
+                        minScale,
+                        computeMinScale(vaultAsset, {destinationDelta}));
+
+                    auto const roundedDestinationDelta = roundToAsset(
+                        vaultAsset, destinationDelta, localMinScale);
+
+                    if (roundedDestinationDelta <= zero)
                     {
                         JLOG(j.fatal()) <<  //
                             "Invariant failed: withdrawal must increase "
@@ -3382,7 +3437,9 @@ ValidVault::finalize(
                         result = false;
                     }
 
-                    if (*vaultDeltaAssets * -1 != destinationDelta)
+                    auto const localPseudoDeltaAssets = roundToAsset(
+                        vaultAsset, vaultPseudoDeltaAssets, localMinScale);
+                    if (localPseudoDeltaAssets * -1 != roundedDestinationDelta)
                     {
                         JLOG(j.fatal()) <<  //
                             "Invariant failed: withdrawal must change vault "
@@ -3390,7 +3447,7 @@ ValidVault::finalize(
                         result = false;
                     }
                 }
-
+                // We don't need to round shares, they are integral MPT
                 auto const accountDeltaShares = deltaShares(tx[sfAccount]);
                 if (!accountDeltaShares)
                 {
@@ -3407,7 +3464,7 @@ ValidVault::finalize(
                         "shares";
                     result = false;
                 }
-
+                // We don't need to round shares, they are integral MPT
                 auto const vaultDeltaShares = deltaShares(afterVault.pseudoId);
                 if (!vaultDeltaShares || *vaultDeltaShares == zero)
                 {
@@ -3424,17 +3481,24 @@ ValidVault::finalize(
                     result = false;
                 }
 
+                auto const assetTotalDelta = roundToAsset(
+                    vaultAsset,
+                    afterVault.assetsTotal - beforeVault.assetsTotal,
+                    minScale);
                 // Note, vaultBalance is negative (see check above)
-                if (beforeVault.assetsTotal + *vaultDeltaAssets !=
-                    afterVault.assetsTotal)
+                if (assetTotalDelta != vaultPseudoDeltaAssets)
                 {
                     JLOG(j.fatal()) << "Invariant failed: withdrawal and "
                                        "assets outstanding must add up";
                     result = false;
                 }
 
-                if (beforeVault.assetsAvailable + *vaultDeltaAssets !=
-                    afterVault.assetsAvailable)
+                auto const assetAvailableDelta = roundToAsset(
+                    vaultAsset,
+                    afterVault.assetsAvailable - beforeVault.assetsAvailable,
+                    minScale);
+
+                if (assetAvailableDelta != vaultPseudoDeltaAssets)
                 {
                     JLOG(j.fatal()) << "Invariant failed: withdrawal and "
                                        "assets available must add up";
@@ -3468,10 +3532,19 @@ ValidVault::finalize(
                     }
                 }
 
-                auto const vaultDeltaAssets = deltaAssets(afterVault.pseudoId);
-                if (vaultDeltaAssets)
+                auto const maybeVaultDeltaAssets =
+                    deltaAssets(afterVault.pseudoId);
+                if (maybeVaultDeltaAssets)
                 {
-                    if (*vaultDeltaAssets >= zero)
+                    auto const minScale = computeMinScale(
+                        vaultAsset,
+                        {*maybeVaultDeltaAssets,
+                         afterVault.assetsTotal - beforeVault.assetsTotal,
+                         afterVault.assetsAvailable -
+                             beforeVault.assetsAvailable});
+                    auto const vaultDeltaAssets = roundToAsset(
+                        vaultAsset, *maybeVaultDeltaAssets, minScale);
+                    if (vaultDeltaAssets >= zero)
                     {
                         JLOG(j.fatal()) <<  //
                             "Invariant failed: clawback must decrease vault "
@@ -3479,8 +3552,11 @@ ValidVault::finalize(
                         result = false;
                     }
 
-                    if (beforeVault.assetsTotal + *vaultDeltaAssets !=
-                        afterVault.assetsTotal)
+                    auto const assetsTotalDelta = roundToAsset(
+                        vaultAsset,
+                        afterVault.assetsTotal - beforeVault.assetsTotal,
+                        minScale);
+                    if (assetsTotalDelta != vaultDeltaAssets)
                     {
                         JLOG(j.fatal()) <<  //
                             "Invariant failed: clawback and assets outstanding "
@@ -3488,8 +3564,12 @@ ValidVault::finalize(
                         result = false;
                     }
 
-                    if (beforeVault.assetsAvailable + *vaultDeltaAssets !=
-                        afterVault.assetsAvailable)
+                    auto const assetAvailableDelta = roundToAsset(
+                        vaultAsset,
+                        afterVault.assetsAvailable -
+                            beforeVault.assetsAvailable,
+                        minScale);
+                    if (assetAvailableDelta != vaultDeltaAssets)
                     {
                         JLOG(j.fatal()) <<  //
                             "Invariant failed: clawback and assets available "
@@ -3504,15 +3584,15 @@ ValidVault::finalize(
                     return false;  // That's all we can do
                 }
 
-                auto const accountDeltaShares = deltaShares(tx[sfHolder]);
-                if (!accountDeltaShares)
+                // We don't need to round shares, they are integral MPT
+                auto const maybeAccountDeltaShares = deltaShares(tx[sfHolder]);
+                if (!maybeAccountDeltaShares)
                 {
                     JLOG(j.fatal()) <<  //
                         "Invariant failed: clawback must change holder shares";
                     return false;  // That's all we can do
                 }
-
-                if (*accountDeltaShares >= zero)
+                if (*maybeAccountDeltaShares >= zero)
                 {
                     JLOG(j.fatal()) <<  //
                         "Invariant failed: clawback must decrease holder "
@@ -3520,6 +3600,7 @@ ValidVault::finalize(
                     result = false;
                 }
 
+                // We don't need to round shares, they are integral MPT
                 auto const vaultDeltaShares = deltaShares(afterVault.pseudoId);
                 if (!vaultDeltaShares || *vaultDeltaShares == zero)
                 {
@@ -3528,7 +3609,7 @@ ValidVault::finalize(
                     return false;  // That's all we can do
                 }
 
-                if (*vaultDeltaShares * -1 != *accountDeltaShares)
+                if (*vaultDeltaShares * -1 != *maybeAccountDeltaShares)
                 {
                     JLOG(j.fatal()) <<  //
                         "Invariant failed: clawback must change holder and "
@@ -3566,4 +3647,32 @@ ValidVault::finalize(
     return true;
 }
 
+[[nodiscard]] std::int32_t
+ValidVault::computeMinScale(
+    Asset const& asset,
+    std::initializer_list<Number const> numbers)
+{
+    if (numbers.size() == 0)
+        return 0;
+    // Helper to get the minimal scale of an STAmount by removing trailing
+    // zeros from its mantissa
+    auto const getNatScale = [](Asset const& asset,
+                                Number const& value) -> std::int32_t {
+        if (asset.integral())
+            return 0;
+        if (value == beast::zero)
+            return value.exponent();
+
+        return value.scale<STAmount>(asset);
+    };
+
+    std::vector<std::int32_t> natScales;
+    std::transform(
+        numbers.begin(),
+        numbers.end(),
+        std::back_inserter(natScales),
+        [&](Number const& n) { return getNatScale(asset, n); });
+
+    return *std::max_element(natScales.begin(), natScales.end());
+}
 }  // namespace xrpl

src/xrpld/app/tx/detail/InvariantCheck.h

@@ -900,6 +900,12 @@ public:
         XRPAmount const,
         ReadView const&,
         beast::Journal const&);
+
+    // Compute the coarsest scale required to represent all numbers
+    [[nodiscard]] static std::int32_t
+    computeMinScale(
+        Asset const& asset,
+        std::initializer_list<Number const> numbers);
 };
 
 // additional invariant checks can be declared above and then added to this

src/xrpld/app/tx/detail/LoanBrokerCoverWithdraw.cpp

@@ -125,7 +125,7 @@ LoanBrokerCoverWithdraw::preclaim(PreclaimContext const& ctx)
             tenthBipsOfValue(
                 currentDebtTotal,
                 TenthBips32(sleBroker->at(sfCoverRateMinimum))),
-            currentDebtTotal.exponent());
+            currentDebtTotal.scale<STAmount>(vaultAsset));
     }();
     if (coverAvail < amount)
         return tecINSUFFICIENT_FUNDS;