refactor: Rename raw state to theoretical state (#6187)

Tapanito · ximinez · commit 5835dffd1b25 · 2026-01-08T20:31:49.000-05:00
diff --git a/src/test/app/Loan_test.cpp b/src/test/app/Loan_test.cpp
@@ -914,7 +914,7 @@ class Loan_test : public beast::unit_test::suite
             state.principalOutstanding,
             state.managementFeeOutstanding);
         {
-            auto const raw = computeRawLoanState(
+            auto const raw = computeTheoreticalLoanState(
                 state.periodicPayment,
                 periodicRate,
                 state.paymentRemaining,
@@ -967,7 +967,7 @@ class Loan_test : public beast::unit_test::suite
         Number totalFeesPaid = 0;
         std::size_t totalPaymentsMade = 0;
 
-        ripple::LoanState currentTrueState = computeRawLoanState(
+        ripple::LoanState currentTrueState = computeTheoreticalLoanState(
             state.periodicPayment,
             periodicRate,
             state.paymentRemaining,
@@ -1022,7 +1022,7 @@ class Loan_test : public beast::unit_test::suite
                     paymentComponents.trackedInterestPart() +
                     paymentComponents.trackedManagementFeeDelta);
 
-            ripple::LoanState const nextTrueState = computeRawLoanState(
+            ripple::LoanState const nextTrueState = computeTheoreticalLoanState(
                 state.periodicPayment,
                 periodicRate,
                 state.paymentRemaining - 1,
@@ -2673,7 +2673,7 @@ class Loan_test : public beast::unit_test::suite
                         Number::upward));
 
                 {
-                    auto const raw = computeRawLoanState(
+                    auto const raw = computeTheoreticalLoanState(
                         state.periodicPayment,
                         periodicRate,
                         state.paymentRemaining,
@@ -2716,11 +2716,12 @@ class Loan_test : public beast::unit_test::suite
                 Number totalInterestPaid = 0;
                 std::size_t totalPaymentsMade = 0;
 
-                ripple::LoanState currentTrueState = computeRawLoanState(
-                    state.periodicPayment,
-                    periodicRate,
-                    state.paymentRemaining,
-                    broker.params.managementFeeRate);
+                ripple::LoanState currentTrueState =
+                    computeTheoreticalLoanState(
+                        state.periodicPayment,
+                        periodicRate,
+                        state.paymentRemaining,
+                        broker.params.managementFeeRate);
 
                 while (state.paymentRemaining > 0)
                 {
@@ -2741,11 +2742,12 @@ class Loan_test : public beast::unit_test::suite
                         paymentComponents.trackedValueDelta <=
                         roundedPeriodicPayment);
 
-                    ripple::LoanState const nextTrueState = computeRawLoanState(
-                        state.periodicPayment,
-                        periodicRate,
-                        state.paymentRemaining - 1,
-                        broker.params.managementFeeRate);
+                    ripple::LoanState const nextTrueState =
+                        computeTheoreticalLoanState(
+                            state.periodicPayment,
+                            periodicRate,
+                            state.paymentRemaining - 1,
+                            broker.params.managementFeeRate);
                     detail::LoanStateDeltas const deltas =
                         currentTrueState - nextTrueState;
 
@@ -5919,7 +5921,7 @@ class Loan_test : public beast::unit_test::suite
 
         auto const periodicRate =
             loanPeriodicRate(interestRateValue, state.paymentInterval);
-        auto const rawLoanState = computeRawLoanState(
+        auto const rawLoanState = computeTheoreticalLoanState(
             state.periodicPayment,
             periodicRate,
             state.paymentRemaining,
diff --git a/src/xrpld/app/misc/LendingHelpers.h b/src/xrpld/app/misc/LendingHelpers.h
@@ -86,8 +86,8 @@ struct LoanPaymentParts
 
 /** This structure captures the parts of a loan state.
  *
- *  Whether the values are raw (unrounded) or rounded will depend on how it was
- * computed.
+ *  Whether the values are theoretical (unrounded) or rounded will depend on how
+ * it was computed.
  *
  *  Many of the fields can be derived from each other, but they're all provided
  *  here to reduce code duplication and possible mistakes.
@@ -190,7 +190,7 @@ checkLoanGuards(
     beast::Journal j);
 
 LoanState
-computeRawLoanState(
+computeTheoreticalLoanState(
     Number const& periodicPayment,
     Number const& periodicRate,
     std::uint32_t const paymentRemaining,
@@ -217,7 +217,7 @@ computeManagementFee(
 
 Number
 computeFullPaymentInterest(
-    Number const& rawPrincipalOutstanding,
+    Number const& theoreticalPrincipalOutstanding,
     Number const& periodicRate,
     NetClock::time_point parentCloseTime,
     std::uint32_t paymentInterval,
diff --git a/src/xrpld/app/misc/detail/LendingHelpers.cpp b/src/xrpld/app/misc/detail/LendingHelpers.cpp
@@ -395,27 +395,28 @@ tryOverpayment(
     beast::Journal j)
 {
     // Calculate what the loan state SHOULD be theoretically (at full precision)
-    auto const raw = computeRawLoanState(
+    auto const theoreticalState = computeTheoreticalLoanState(
         periodicPayment, periodicRate, paymentRemaining, managementFeeRate);
 
     // Calculate the accumulated rounding errors. These need to be preserved
     // across the re-amortization to maintain consistency with the loan's
     // payment history. Without preserving these errors, the loan could end
     // up with a different total value than what the borrower has actually paid.
-    auto const errors = roundedOldState - raw;
+    auto const errors = roundedOldState - theoreticalState;
 
-    // Compute the new principal by applying the overpayment to the raw
-    // (theoretical) principal. Use max with 0 to ensure we never go negative.
-    auto const newRawPrincipal = std::max(
-        raw.principalOutstanding - overpaymentComponents.trackedPrincipalDelta,
+    // Compute the new principal by applying the overpayment to the theoretical
+    // principal. Use max with 0 to ensure we never go negative.
+    auto const newTheoreticalPrincipal = std::max(
+        theoreticalState.principalOutstanding -
+            overpaymentComponents.trackedPrincipalDelta,
         Number{0});
 
     // Compute new loan properties based on the reduced principal. This
     // recalculates the periodic payment, total value, and management fees
     // for the remaining payment schedule.
     auto newLoanProperties = computeLoanProperties(
         asset,
-        newRawPrincipal,
+        newTheoreticalPrincipal,
         periodicRate,
         paymentRemaining,
         managementFeeRate,
@@ -429,35 +430,41 @@ tryOverpayment(
                     << newLoanProperties.firstPaymentPrincipal;
 
     // Calculate what the new loan state should be with the new periodic payment
-    auto const newRaw = computeRawLoanState(
-                            newLoanProperties.periodicPayment,
-                            periodicRate,
-                            paymentRemaining,
-                            managementFeeRate) +
+    // including rounding errors
+    auto const newTheoreticalState = computeTheoreticalLoanState(
+                                         newLoanProperties.periodicPayment,
+                                         periodicRate,
+                                         paymentRemaining,
+                                         managementFeeRate) +
         errors;
 
-    JLOG(j.debug()) << "new raw value: " << newRaw.valueOutstanding
-                    << ", principal: " << newRaw.principalOutstanding
-                    << ", interest gross: " << newRaw.interestOutstanding();
-    // Update the loan state variables with the new values PLUS the preserved
-    // rounding errors. This ensures the loan's tracked state remains
-    // consistent with its payment history.
+    JLOG(j.debug()) << "new theoretical value: "
+                    << newTheoreticalState.valueOutstanding << ", principal: "
+                    << newTheoreticalState.principalOutstanding
+                    << ", interest gross: "
+                    << newTheoreticalState.interestOutstanding();
 
+    // Update the loan state variables with the new values that include the
+    // preserved rounding errors. This ensures the loan's tracked state remains
+    // consistent with its payment history.
     auto const principalOutstanding = std::clamp(
         roundToAsset(
-            asset, newRaw.principalOutstanding, loanScale, Number::upward),
+            asset,
+            newTheoreticalState.principalOutstanding,
+            loanScale,
+            Number::upward),
         numZero,
         roundedOldState.principalOutstanding);
     auto const totalValueOutstanding = std::clamp(
         roundToAsset(
             asset,
-            principalOutstanding + newRaw.interestOutstanding(),
+            principalOutstanding + newTheoreticalState.interestOutstanding(),
             loanScale,
             Number::upward),
         numZero,
         roundedOldState.valueOutstanding);
     auto const managementFeeOutstanding = std::clamp(
-        roundToAsset(asset, newRaw.managementFeeDue, loanScale),
+        roundToAsset(asset, newTheoreticalState.managementFeeDue, loanScale),
         numZero,
         roundedOldState.managementFeeDue);
 
@@ -829,15 +836,16 @@ computeFullPayment(
     }
 
     // Calculate the theoretical principal based on the payment schedule.
-    // This raw (unrounded) value is used to compute interest and penalties
-    // accurately.
-    Number const rawPrincipalOutstanding = loanPrincipalFromPeriodicPayment(
-        periodicPayment, periodicRate, paymentRemaining);
+    // This theoretical (unrounded) value is used to compute interest and
+    // penalties accurately.
+    Number const theoreticalPrincipalOutstanding =
+        loanPrincipalFromPeriodicPayment(
+            periodicPayment, periodicRate, paymentRemaining);
 
     // Full payment interest includes both accrued interest (time since last
     // payment) and prepayment penalty (for closing early).
     auto const fullPaymentInterest = computeFullPaymentInterest(
-        rawPrincipalOutstanding,
+        theoreticalPrincipalOutstanding,
         periodicRate,
         view.parentCloseTime(),
         paymentInterval,
@@ -897,7 +905,8 @@ computeFullPayment(
     JLOG(j.trace()) << "computeFullPayment result: periodicPayment: "
                     << periodicPayment << ", periodicRate: " << periodicRate
                     << ", paymentRemaining: " << paymentRemaining
-                    << ", rawPrincipalOutstanding: " << rawPrincipalOutstanding
+                    << ", theoreticalPrincipalOutstanding: "
+                    << theoreticalPrincipalOutstanding
                     << ", fullPaymentInterest: " << fullPaymentInterest
                     << ", roundedFullInterest: " << roundedFullInterest
                     << ", roundedFullManagementFee: "
@@ -977,7 +986,7 @@ computePaymentComponents(
 
     // Calculate what the loan state SHOULD be after this payment (the target).
     // This is computed at full precision using the theoretical amortization.
-    LoanState const trueTarget = computeRawLoanState(
+    LoanState const trueTarget = computeTheoreticalLoanState(
         periodicPayment, periodicRate, paymentRemaining - 1, managementFeeRate);
 
     // Round the target to the loan's scale to match how actual loan values
@@ -1348,7 +1357,7 @@ checkLoanGuards(
  */
 Number
 computeFullPaymentInterest(
-    Number const& rawPrincipalOutstanding,
+    Number const& theoreticalPrincipalOutstanding,
     Number const& periodicRate,
     NetClock::time_point parentCloseTime,
     std::uint32_t paymentInterval,
@@ -1357,7 +1366,7 @@ computeFullPaymentInterest(
     TenthBips32 closeInterestRate)
 {
     auto const accruedInterest = detail::loanAccruedInterest(
-        rawPrincipalOutstanding,
+        theoreticalPrincipalOutstanding,
         periodicRate,
         parentCloseTime,
         startDate,
@@ -1371,7 +1380,7 @@ computeFullPaymentInterest(
     // Equation (28) from XLS-66 spec, Section A-2 Equation Glossary
     auto const prepaymentPenalty = closeInterestRate == beast::zero
         ? Number{}
-        : tenthBipsOfValue(rawPrincipalOutstanding, closeInterestRate);
+        : tenthBipsOfValue(theoreticalPrincipalOutstanding, closeInterestRate);
 
     XRPL_ASSERT(
         prepaymentPenalty >= 0,
@@ -1388,11 +1397,11 @@ computeFullPaymentInterest(
  * This function computes what the loan's outstanding balances should be based
  * on the periodic payment amount and number of payments remaining,
  * without considering any rounding that may have been applied to the actual
- * Loan object's state. This "raw" (unrounded) state is used as a target for
- * computing payment components and validating that the loan's tracked state
+ * Loan object's state. This "theoretical" (unrounded) state is used as a target
+ * for computing payment components and validating that the loan's tracked state
  * hasn't drifted too far from the theoretical values.
  *
- * The raw state serves several purposes:
+ * The theoretical state serves several purposes:
  * 1. Computing the expected payment breakdown (principal, interest, fees)
  * 2. Detecting and correcting rounding errors that accumulate over time
  * 3. Validating that overpayments are calculated correctly
@@ -1402,7 +1411,7 @@ computeFullPaymentInterest(
  *       representing a completely paid-off loan.
  */
 LoanState
-computeRawLoanState(
+computeTheoreticalLoanState(
     Number const& periodicPayment,
     Number const& periodicRate,
     std::uint32_t const paymentRemaining,
@@ -1418,40 +1427,42 @@ computeRawLoanState(
     }
 
     // Equation (30) from XLS-66 spec, Section A-2 Equation Glossary
-    Number const rawTotalValueOutstanding = periodicPayment * paymentRemaining;
+    Number const totalValueOutstanding = periodicPayment * paymentRemaining;
 
-    Number const rawPrincipalOutstanding =
+    Number const principalOutstanding =
         detail::loanPrincipalFromPeriodicPayment(
             periodicPayment, periodicRate, paymentRemaining);
 
     // Equation (31) from XLS-66 spec, Section A-2 Equation Glossary
-    Number const rawInterestOutstandingGross =
-        rawTotalValueOutstanding - rawPrincipalOutstanding;
+    Number const interestOutstandingGross =
+        totalValueOutstanding - principalOutstanding;
 
     // Equation (32) from XLS-66 spec, Section A-2 Equation Glossary
-    Number const rawManagementFeeOutstanding =
-        tenthBipsOfValue(rawInterestOutstandingGross, managementFeeRate);
+    Number const managementFeeOutstanding =
+        tenthBipsOfValue(interestOutstandingGross, managementFeeRate);
 
     // Equation (33) from XLS-66 spec, Section A-2 Equation Glossary
-    Number const rawInterestOutstandingNet =
-        rawInterestOutstandingGross - rawManagementFeeOutstanding;
+    Number const interestOutstandingNet =
+        interestOutstandingGross - managementFeeOutstanding;
 
     return LoanState{
-        .valueOutstanding = rawTotalValueOutstanding,
-        .principalOutstanding = rawPrincipalOutstanding,
-        .interestDue = rawInterestOutstandingNet,
-        .managementFeeDue = rawManagementFeeOutstanding};
+        .valueOutstanding = totalValueOutstanding,
+        .principalOutstanding = principalOutstanding,
+        .interestDue = interestOutstandingNet,
+        .managementFeeDue = managementFeeOutstanding,
+    };
 };
 
 /* Constructs a LoanState from rounded Loan ledger object values.
  *
  * This function creates a LoanState structure from the three tracked values
- * stored in a Loan ledger object. Unlike calculateRawLoanState(), which
+ * stored in a Loan ledger object. Unlike calculateTheoreticalLoanState(), which
  * computes theoretical unrounded values, this function works with values
  * that have already been rounded to the loan's scale.
  *
- * The key difference from calculateRawLoanState():
- * - calculateRawLoanState: Computes theoretical values at full precision
+ * The key difference from calculateTheoreticalLoanState():
+ * - calculateTheoreticalLoanState: Computes theoretical values at full
+ * precision
  * - constructRoundedLoanState: Builds state from actual rounded ledger values
  *
  * The interestDue field is derived from the other three values rather than
@@ -1592,13 +1603,13 @@ computeLoanProperties(
     auto const firstPaymentPrincipal = [&]() {
         // Compute the parts for the first payment. Ensure that the
         // principal payment will actually change the principal.
-        auto const startingState = computeRawLoanState(
+        auto const startingState = computeTheoreticalLoanState(
             periodicPayment,
             periodicRate,
             paymentsRemaining,
             managementFeeRate);
 
-        auto const firstPaymentState = computeRawLoanState(
+        auto const firstPaymentState = computeTheoreticalLoanState(
             periodicPayment,
             periodicRate,
             paymentsRemaining - 1,
