1#include <xrpl/ledger/helpers/LendingHelpers.h>
3#include <xrpl/basics/Log.h>
4#include <xrpl/basics/Number.h>
5#include <xrpl/basics/chrono.h>
6#include <xrpl/beast/utility/Journal.h>
7#include <xrpl/beast/utility/Zero.h>
8#include <xrpl/beast/utility/instrumentation.h>
9#include <xrpl/ledger/ApplyView.h>
10#include <xrpl/ledger/ReadView.h>
11#include <xrpl/ledger/View.h>
12#include <xrpl/ledger/helpers/VaultHelpers.h>
13#include <xrpl/protocol/Asset.h>
14#include <xrpl/protocol/Feature.h>
15#include <xrpl/protocol/Indexes.h>
16#include <xrpl/protocol/LedgerFormats.h>
17#include <xrpl/protocol/Protocol.h>
18#include <xrpl/protocol/Rules.h>
19#include <xrpl/protocol/SField.h>
20#include <xrpl/protocol/STAmount.h>
21#include <xrpl/protocol/STLedgerEntry.h>
22#include <xrpl/protocol/STTx.h>
23#include <xrpl/protocol/TER.h>
24#include <xrpl/protocol/TxFlags.h>
25#include <xrpl/protocol/TxFormats.h>
26#include <xrpl/protocol/Units.h>
42 Asset const& vaultAsset,
48 sleBroker && sleBroker->getType() == ltLOAN_BROKER,
49 "xrpl::canApplyToBrokerCover : valid LoanBroker sle");
50 XRPL_ASSERT(vaultAsset == amount.
asset(),
"xrpl::canApplyToBrokerCover : valid asset");
58 int const coverScale =
scale(sleBroker->at(sfCoverAvailable), vaultAsset);
62 <<
" rounds to zero at cover scale " << coverScale;
75 vault && vault->getType() == ltVAULT,
76 "xrpl::detail::getPosteriorBrokerCoverScale : valid Vault sle");
78 broker && broker->getType() == ltLOAN_BROKER,
79 "xrpl::detail::getPosteriorBrokerCoverScale : valid LoanBroker sle");
85 broker->at(sfCoverAvailable),
97 vault && vault->getType() == ltVAULT,
98 "xrpl::detail::roundToPosteriorBrokerCoverScale : valid Vault sle");
100 broker && broker->getType() == ltLOAN_BROKER,
101 "xrpl::detail::roundToPosteriorBrokerCoverScale : valid LoanBroker sle");
103 delta.
asset() == vault->at(sfAsset),
104 "xrpl::detail::roundToPosteriorBrokerCoverScale : delta and Vault asset match");
112[[nodiscard]] STAmount
120 vault && vault->getType() == ltVAULT,
121 "xrpl::creditToPosteriorBrokerCoverScale : valid Vault sle");
123 broker && broker->getType() == ltLOAN_BROKER,
124 "xrpl::creditToPosteriorBrokerCoverScale : valid LoanBroker sle");
125 Asset const asset = vault->at(sfAsset);
132 Number const reference = broker->at(sfCoverAvailable);
137[[nodiscard]] STAmount
145 vault && vault->getType() == ltVAULT,
146 "xrpl::debitToPosteriorBrokerCoverScale : valid Vault sle");
148 broker && broker->getType() == ltLOAN_BROKER,
149 "xrpl::debitToPosteriorBrokerCoverScale : valid LoanBroker sle");
151 amount.
asset() == vault->at(sfAsset),
152 "xrpl::debitToPosteriorBrokerCoverScale : amount and Vault asset match");
153 XRPL_ASSERT(!amount.
negative(),
"xrpl::debitToPosteriorBrokerCoverScale : non-negative amount");
161 vault && vault->getType() == ltVAULT,
162 "xrpl::checkOptionalBrokerCoverInflow : valid Vault sle");
164 broker && broker->getType() == ltLOAN_BROKER,
165 "xrpl::checkOptionalBrokerCoverInflow : valid LoanBroker sle");
167 amount.
asset() == vault->at(sfAsset),
168 "xrpl::checkOptionalBrokerCoverInflow : amount and Vault asset match");
169 XRPL_ASSERT(!amount.
negative(),
"xrpl::checkOptionalBrokerCoverInflow : non-negative amount");
184 Number const posterior = [&] {
186 return broker->at(sfCoverAvailable) + rounded;
204 brokerSle->at(sfDebtTotal) += delta;
216 vaultSle && vaultSle->getType() == ltVAULT,
"xrpl::minimumBrokerCover : valid Vault sle");
219 vaultSle->at(sfAsset),
227 if (!rules.
enabled(featureSingleAssetVault))
230 if (!rules.
enabled(featureMPTokensV1))
265 Asset const vaultAsset = vaultSle->at(sfAsset);
268 .broker = brokerSle->at(sfAccount),
269 .vault = vaultSle->at(sfAccount),
280 "xrpl::LoanPaymentParts::operator+= : other principal "
284 "xrpl::LoanPaymentParts::operator+= : other interest paid "
288 "xrpl::LoanPaymentParts::operator+= : other fee paid "
333 loanSle->at(sfNextPaymentDueDate),
338namespace instant_recognition {
343 return {.assetsTotalDelta = interestDue, .debtTotalDelta = principalRequested + interestDue};
348 Number const& vaultMaximum,
350 Number const& interestDue)
352 return vaultMaximum != 0 && interestDue > vaultMaximum - vaultTotal;
365 return loanSle->at(sfTotalValueOutstanding) - loanSle->at(sfManagementFeeOutstanding);
379namespace cash_basis {
384 return {.assetsTotalDelta =
kNumZero, .debtTotalDelta = principalRequested};
395 return loanSle->at(sfPrincipalOutstanding);
422 Number const& principalRequested,
423 Number const& interestDue)
425 return cashBasisEnabled(vaultSle)
434 Number const& interestDue)
438 if (cashBasisEnabled(vaultSle))
441 auto const vaultMaximum = vaultSle->at(sfAssetsMaximum);
443 vaultMaximum, vaultTotal, interestDue);
490 "xrpl::detail::computePowerMinusOne",
491 "periodicRate is non-negative");
493 if (paymentsRemaining == 0 || periodicRate ==
beast::kZero)
497 Number term = paymentsRemaining * periodicRate;
502 term = term * periodicRate * (paymentsRemaining - k) / (k + 1);
529 "xrpl::detail::computePowerMinusOneHybrid",
530 "periodicRate is non-negative");
532 if (paymentsRemaining == 0 || periodicRate ==
beast::kZero)
540 Number const cancellationThreshold{1, -9};
541 if (paymentsRemaining * periodicRate >= cancellationThreshold)
542 return power(1 + periodicRate, paymentsRemaining) - 1;
555 Number const& periodicRate,
558 if (paymentsRemaining == 0)
563 return Number{1} / paymentsRemaining;
565 if (rules.
enabled(fixCleanup3_2_0))
567 Number const raisedRateMinusOne =
569 Number const raisedRate = 1 + raisedRateMinusOne;
571 return (periodicRate * raisedRate) / raisedRateMinusOne;
577 Number const raisedRate =
power(1 + periodicRate, paymentsRemaining);
579 return (periodicRate * raisedRate) / (raisedRate - 1);
590 Number const& principalOutstanding,
591 Number const& periodicRate,
594 if (principalOutstanding == 0 || paymentsRemaining == 0)
599 return principalOutstanding / paymentsRemaining;
612 Number const& periodicPayment,
613 Number const& periodicRate,
616 if (paymentsRemaining == 0)
619 if (periodicRate == 0)
620 return periodicPayment * paymentsRemaining;
652 Number const& rawInterest,
657 auto const interest =
roundToAsset(asset, rawInterest, loanScale, mode);
668 Number const& principalOutstanding,
683 if (now <= nextPaymentDueDate)
687 auto const secondsOverdue = now - nextPaymentDueDate;
691 return principalOutstanding * rate;
701 Number const& principalOutstanding,
702 Number const& periodicRate,
711 if (paymentInterval == 0)
714 auto const lastPaymentDate =
std::max(prevPaymentDate, startDate);
719 if (now <= lastPaymentDate)
723 auto const secondsSinceLastPayment = now - lastPaymentDate;
728 return principalOutstanding * periodicRate * secondsSinceLastPayment / paymentInterval;
740 auto totalValueOutstandingProxy = loan->at(sfTotalValueOutstanding);
741 auto principalOutstandingProxy = loan->at(sfPrincipalOutstanding);
742 auto managementFeeOutstandingProxy = loan->at(sfManagementFeeOutstanding);
743 auto paymentRemainingProxy = loan->at(sfPaymentRemaining);
744 auto prevPaymentDateProxy = loan->at(sfPreviousPaymentDueDate);
745 auto nextDueDateProxy = loan->at(sfNextPaymentDueDate);
746 std::uint32_t const paymentInterval = loan->at(sfPaymentInterval);
748 XRPL_ASSERT_PARTS(nextDueDateProxy,
"xrpl::detail::doPayment",
"Next due date proxy set");
754 "xrpl::detail::doPayment",
755 "Full principal payment");
758 "xrpl::detail::doPayment",
759 "Full value payment");
762 "xrpl::detail::doPayment",
763 "Full management fee payment");
766 paymentRemainingProxy = 0;
769 prevPaymentDateProxy = *nextDueDateProxy;
773 nextDueDateProxy = 0;
778 principalOutstandingProxy = 0;
779 totalValueOutstandingProxy = 0;
780 managementFeeOutstandingProxy = 0;
787 paymentRemainingProxy -= 1;
789 prevPaymentDateProxy = nextDueDateProxy;
790 nextDueDateProxy += paymentInterval;
794 "xrpl::detail::doPayment",
795 "Partial principal payment");
798 "xrpl::detail::doPayment",
799 "Partial value payment");
804 "xrpl::detail::doPayment",
805 "Valid management fee");
815 static_cast<Number>(principalOutstandingProxy) <=
816 static_cast<Number>(totalValueOutstandingProxy),
817 "xrpl::detail::doPayment",
818 "principal does not exceed total");
822 "xrpl::detail::doPayment",
823 "fee outstanding stays valid");
856std::expected<std::pair<LoanPaymentParts, LoanProperties>,
TER>
863 Number const& periodicPayment,
864 Number const& periodicRate,
871 rules, periodicPayment, periodicRate, paymentRemaining, managementFeeRate);
877 auto const errors = roundedOldState - theoreticalState;
881 auto const newTheoreticalPrincipal =
std::max(
891 newTheoreticalPrincipal,
897 JLOG(j.
debug()) <<
"new periodic payment: " << newLoanProperties.periodicPayment
898 <<
", new total value: " << newLoanProperties.loanState.valueOutstanding
899 <<
", first payment principal: " << newLoanProperties.firstPaymentPrincipal;
904 auto const newTheoreticalState = [&] {
907 newLoanProperties.periodicPayment,
913 if (!rules.
enabled(fixCleanup3_2_0))
925 Number const managementFee =
930 JLOG(j.
debug()) <<
"new theoretical value: " << newTheoreticalState.valueOutstanding
931 <<
", principal: " << newTheoreticalState.principalOutstanding
932 <<
", interest gross: " << newTheoreticalState.interestOutstanding();
940 newTheoreticalState.principalOutstanding,
945 auto const totalValueOutstanding =
std::clamp(
948 principalOutstanding + newTheoreticalState.interestOutstanding(),
953 auto const managementFeeOutstanding =
std::clamp(
954 roundToAsset(asset, newTheoreticalState.managementFeeDue, loanScale),
958 auto const roundedNewState =
959 constructLoanState(totalValueOutstanding, principalOutstanding, managementFeeOutstanding);
963 newLoanProperties.loanState = roundedNewState;
965 JLOG(j.
debug()) <<
"new rounded value: " << roundedNewState.valueOutstanding
966 <<
", principal: " << roundedNewState.principalOutstanding
967 <<
", interest gross: " << roundedNewState.interestOutstanding();
972 principalOutstanding,
982 JLOG(j.
warn()) <<
"Principal overpayment would cause the loan to be in "
983 "an invalid state. Ignore the overpayment";
990 if (newLoanProperties.periodicPayment <= 0 ||
991 newLoanProperties.loanState.valueOutstanding <= 0 ||
992 newLoanProperties.loanState.managementFeeDue < 0)
995 JLOG(j.
warn()) <<
"Overpayment not allowed: Computed loan "
996 "properties are invalid. Does "
997 "not compute. TotalValueOutstanding: "
998 << newLoanProperties.loanState.valueOutstanding
999 <<
", PeriodicPayment : " << newLoanProperties.periodicPayment
1000 <<
", ManagementFeeOwedToBroker: "
1001 << newLoanProperties.loanState.managementFeeDue;
1006 auto const deltas = roundedOldState - roundedNewState;
1011 deltas.managementFee == roundedOldState.
managementFeeDue - managementFeeOutstanding,
1012 "xrpl::detail::tryOverpayment",
1022 auto const valueChange = -deltas.interest;
1023 if (valueChange > 0)
1025 JLOG(j.
warn()) <<
"Principal overpayment would increase the value of "
1026 "the loan. Ignore the overpayment";
1033 .principalPaid = deltas.principal,
1059std::expected<LoanPaymentParts, TER>
1066 Number const& periodicRate,
1070 auto totalValueOutstandingProxy = loan->at(sfTotalValueOutstanding);
1071 auto principalOutstandingProxy = loan->at(sfPrincipalOutstanding);
1072 auto managementFeeOutstandingProxy = loan->at(sfManagementFeeOutstanding);
1073 auto periodicPaymentProxy = loan->at(sfPeriodicPayment);
1074 auto const paymentsRemaining = loan->at(sfPaymentRemaining);
1077 totalValueOutstandingProxy, principalOutstandingProxy, managementFeeOutstandingProxy);
1078 auto const periodicPayment = periodicPaymentProxy;
1079 JLOG(j.
debug()) <<
"overpayment components:"
1080 <<
", totalValue before: " << *totalValueOutstandingProxy
1086 <<
", totalDue: " << overpaymentComponents.
totalDue
1087 <<
", payments remaining :" << paymentsRemaining;
1095 overpaymentComponents,
1105 auto const& [loanPaymentParts, newLoanProperties] = *ret;
1106 auto const newRoundedLoanState = newLoanProperties.loanState;
1111 if (principalOutstandingProxy <= newRoundedLoanState.principalOutstanding)
1114 JLOG(j.
warn()) <<
"Overpayment not allowed: principal "
1115 <<
"outstanding did not decrease. Before: " << *principalOutstandingProxy
1116 <<
". After: " << newRoundedLoanState.principalOutstanding;
1124 JLOG(j.
debug()) <<
"valueChange: " << loanPaymentParts.valueChange
1125 <<
", totalValue before: " << *totalValueOutstandingProxy
1126 <<
", totalValue after: " << newRoundedLoanState.valueOutstanding
1127 <<
", totalValue delta: "
1128 << (totalValueOutstandingProxy - newRoundedLoanState.valueOutstanding)
1130 <<
", principalPaid: " << loanPaymentParts.principalPaid
1131 <<
", Computed difference: "
1133 (totalValueOutstandingProxy - newRoundedLoanState.valueOutstanding);
1156 [[maybe_unused]]
bool const fix320Enabled = rules.
enabled(fixCleanup3_2_0);
1160 principalOutstandingProxy - newRoundedLoanState.principalOutstanding,
1161 "xrpl::detail::doOverpayment : principal change agrees");
1166 Number const tvoChange = newRoundedLoanState.valueOutstanding -
1168 Number const managementFeeReleased =
1169 managementFeeOutstandingProxy - newRoundedLoanState.managementFeeDue;
1171 return loanPaymentParts.valueChange == tvoChange + managementFeeReleased + interestPart;
1173 "xrpl::detail::doOverpayment : interest paid agrees");
1178 "xrpl::detail::doOverpayment : principal payment matches");
1182 totalValueOutstandingProxy = newRoundedLoanState.valueOutstanding;
1183 principalOutstandingProxy = newRoundedLoanState.principalOutstanding;
1184 managementFeeOutstandingProxy = newRoundedLoanState.managementFeeDue;
1185 periodicPaymentProxy = newLoanProperties.periodicPayment;
1187 return loanPaymentParts;
1203std::expected<ExtendedPaymentComponents, TER>
1213 std::int32_t const nextDueDate = loan->at(sfNextPaymentDueDate);
1226 loan->at(sfPrincipalOutstanding),
1233 auto const [roundedLateInterest, roundedLateManagementFee] =
1236 XRPL_ASSERT(roundedLateInterest >= 0,
"xrpl::detail::computeLatePayment : valid late interest");
1239 "xrpl::detail::computeLatePayment",
1240 "no extra parts to this payment");
1264 "xrpl::detail::computeLatePayment",
1265 "total due is rounded");
1272 JLOG(j.
warn()) <<
"Late loan payment amount is insufficient. Due: " << late.
totalDue
1273 <<
", paid: " << amount;
1299std::expected<ExtendedPaymentComponents, TER>
1304 Number const& periodicRate,
1309 std::uint32_t const paymentRemaining = loan->at(sfPaymentRemaining);
1313 if (paymentRemaining <= 1)
1316 JLOG(j.
warn()) <<
"Last payment cannot be a full payment.";
1324 view.
rules(), loan->at(sfPeriodicPayment), periodicRate, paymentRemaining);
1329 theoreticalPrincipalOutstanding,
1332 loan->at(sfPaymentInterval),
1333 loan->at(sfPreviousPaymentDueDate),
1334 loan->at(sfStartDate),
1346 Number const closePaymentFee =
roundToAsset(asset, loan->at(sfClosePaymentFee), loanScale);
1353 .trackedValueDelta =
1354 principalOutstanding + totalInterestOutstanding + managementFeeOutstanding,
1355 .trackedPrincipalDelta = principalOutstanding,
1359 .trackedManagementFeeDelta = managementFeeOutstanding,
1370 closePaymentFee + roundedFullManagementFee - managementFeeOutstanding,
1379 roundedFullInterest - totalInterestOutstanding,
1384 "xrpl::detail::computeFullPayment",
1385 "total due is rounded");
1387 JLOG(j.
trace()) <<
"computeFullPayment result: periodicRate: " << periodicRate
1388 <<
", paymentRemaining: " << paymentRemaining
1389 <<
", theoreticalPrincipalOutstanding: " << theoreticalPrincipalOutstanding
1390 <<
", fullPaymentInterest: " << fullPaymentInterest
1391 <<
", roundedFullInterest: " << roundedFullInterest
1392 <<
", roundedFullManagementFee: " << roundedFullManagementFee
1434 Number const& totalValueOutstanding,
1435 Number const& principalOutstanding,
1436 Number const& managementFeeOutstanding,
1437 Number const& periodicPayment,
1438 Number const& periodicRate,
1446 "xrpl::detail::computePaymentComponents",
1447 "Outstanding values are rounded");
1449 paymentRemaining > 0,
"xrpl::detail::computePaymentComponents",
"some payments remaining");
1455 if (paymentRemaining == 1 || totalValueOutstanding <= roundedPeriodicPayment)
1460 .trackedValueDelta = totalValueOutstanding,
1461 .trackedPrincipalDelta = principalOutstanding,
1462 .trackedManagementFeeDelta = managementFeeOutstanding,
1470 rules, periodicPayment, periodicRate, paymentRemaining - 1, managementFeeRate);
1479 bool const fixCleanup320Enabled = rules.
enabled(fixCleanup3_2_0);
1486 .principalOutstanding =
1494 constructLoanState(totalValueOutstanding, principalOutstanding, managementFeeOutstanding);
1507 "xrpl::detail::computePaymentComponents",
1508 "principal delta not greater than outstanding");
1513 if (fixCleanup320Enabled)
1517 "xrpl::detail::computePaymentComponents",
1518 "interest due delta not greater than outstanding");
1530 "xrpl::detail::computePaymentComponents",
1531 "management fee due delta not greater than outstanding");
1545 auto takeFrom = [](
Number& component,
Number& excess) {
1548 auto const part =
std::min(component, excess);
1554 "xrpl::detail::computePaymentComponents",
1555 "excess non-negative");
1575 "xrpl::detail::computePaymentComponents : payment exceeded loan "
1577 addressExcess(deltas, totalOverpayment);
1582 Number shortage = roundedPeriodicPayment - deltas.
total();
1586 "xrpl::detail::computePaymentComponents",
1587 "shortage is rounded");
1592 Number excess = -shortage;
1593 addressExcess(deltas, excess);
1602 "xrpl::detail::computePaymentComponents",
1603 "no shortage or excess");
1608 "xrpl::detail::computePaymentComponents",
1609 "total value adds up");
1614 "xrpl::detail::computePaymentComponents",
1615 "valid principal result");
1618 "xrpl::detail::computePaymentComponents",
1619 "valid interest result");
1623 "xrpl::detail::computePaymentComponents",
1624 "valid fee result");
1628 "xrpl::detail::computePaymentComponents",
1629 "payment parts add to payment");
1633 .trackedValueDelta =
1635 .trackedPrincipalDelta =
1637 .trackedManagementFeeDelta =
1654 Number const& periodicRate,
1660 loan->at(sfLoanScale),
1661 loan->at(sfTotalValueOutstanding),
1662 loan->at(sfPrincipalOutstanding),
1663 loan->at(sfManagementFeeOutstanding),
1664 loan->at(sfPeriodicPayment),
1666 loan->at(sfPaymentRemaining),
1688ExtendedPaymentComponents
1692 int32_t
const loanScale,
1693 Number const& overpayment,
1699 rules.
enabled(fixCleanup3_2_0),
1700 overpayment > 0 &&
isRounded(asset, overpayment, loanScale),
1701 "xrpl::detail::computeOverpaymentComponents : valid overpayment "
1707 Number const overpaymentFee =
1714 auto const [roundedOverpaymentInterest, roundedOverpaymentManagementFee] =
1726 .trackedValueDelta = overpayment - overpaymentFee,
1727 .trackedPrincipalDelta = overpayment - roundedOverpaymentInterest -
1728 roundedOverpaymentManagementFee - overpaymentFee,
1729 .trackedManagementFeeDelta = roundedOverpaymentManagementFee,
1739 roundedOverpaymentInterest};
1741 result.trackedInterestPart() == roundedOverpaymentInterest,
1742 "xrpl::detail::computeOverpaymentComponents",
1743 "valid interest computation");
1754 TenthBips16 const managementFeeRate{brokerSle->at(sfManagementFeeRate)};
1755 TenthBips32 const interestRate{loan->at(sfInterestRate)};
1757 XRPL_ASSERT(interestRate == 0 || periodicRate > 0,
"xrpl::detail::loanRatesFor : valid rate");
1758 return {managementFeeRate, periodicRate};
1765std::expected<LoanPaymentParts, TER>
1774 auto const [managementFeeRate, periodicRate] =
loanRatesFor(loan, brokerSle);
1776 auto const fullPaymentComponents =
1781 if (fullPaymentComponents.has_value())
1782 return doPayment(*fullPaymentComponents, loan);
1790std::expected<LoanPaymentParts, TER>
1799 auto const [managementFeeRate, periodicRate] =
loanRatesFor(loan, brokerSle);
1801 Number const serviceFee = loan->at(sfLoanServiceFee);
1807 "xrpl::detail::makeLatePayment",
1808 "regular payment valid principal");
1810 auto const latePaymentComponents =
1815 if (latePaymentComponents.has_value())
1816 return doPayment(*latePaymentComponents, loan);
1824std::expected<LoanPaymentParts, TER>
1838 "xrpl::detail::makeRegularPayment",
1839 "regular payment type");
1841 auto const [managementFeeRate, periodicRate] =
loanRatesFor(loan, brokerSle);
1844 Number const serviceFee = loan->at(sfLoanServiceFee);
1851 "xrpl::detail::makeRegularPayment",
1852 "regular payment valid principal");
1862 auto const paymentRemainingProxy = loan->at(sfPaymentRemaining);
1864 while ((amount >= (totalPaid + periodic.
totalDue)) && paymentRemainingProxy > 0 &&
1865 numPayments < kLoanMaximumPaymentsPerTransaction)
1870 "xrpl::detail::makeRegularPayment",
1871 "payment pays non-negative principal");
1874 totalParts +=
doPayment(periodic, loan);
1879 "xrpl::detail::makeRegularPayment",
1880 "final payment is the final payment");
1891 if (numPayments == 0)
1893 JLOG(j.
warn()) <<
"Regular loan payment amount is insufficient. Due: " << periodic.
totalDue
1894 <<
", paid: " << amount;
1900 "xrpl::detail::makeRegularPayment",
1901 "payment parts add up");
1903 totalParts.
valueChange == 0,
"xrpl::detail::makeRegularPayment",
"no value change");
1914 auto const roundedAmount = view.
rules().
enabled(fixCleanup3_1_3)
1918 bool const overpaymentSupported =
1921 bool const overpaymentAllowed =
1922 paymentRemainingProxy > 0 &&
1923 totalPaid < roundedAmount &&
1924 numPayments < kLoanMaximumPaymentsPerTransaction;
1926 if (overpaymentSupported && overpaymentAllowed)
1928 TenthBips32 const overpaymentInterestRate{loan->at(sfOverpaymentInterestRate)};
1929 TenthBips32 const overpaymentFeeRate{loan->at(sfOverpaymentFee)};
1934 Number const overpaymentRaw =
1935 std::min(roundedAmount - totalPaid, *loan->at(sfTotalValueOutstanding));
1937 bool const fixEnabled = view.
rules().
enabled(fixCleanup3_2_0);
1938 Number const overpayment = fixEnabled
1944 if (!fixEnabled || overpayment > 0)
1951 overpaymentInterestRate,
1961 "xrpl::detail::makeRegularPayment",
1962 "overpayment penalty did not reduce value of loan");
1967 overpaymentComponents,
1973 totalParts += *overResult;
1975 else if (overResult.error())
1992 "xrpl::detail::makeRegularPayment : total principal paid is valid");
1996 "xrpl::detail::makeRegularPayment : total interest paid is valid");
1999 "xrpl::detail::makeRegularPayment : loan value change is valid");
2002 "xrpl::detail::makeRegularPayment : fee paid is valid");
2008detail::LoanStateDeltas
2048 Asset const& vaultAsset,
2049 Number const& principalRequested,
2050 bool expectInterest,
2055 auto const totalInterestOutstanding =
2060 if (expectInterest && totalInterestOutstanding <= 0)
2064 JLOG(j.
warn()) <<
"Loan for " << principalRequested <<
" with interest has no interest due";
2069 if (!expectInterest && totalInterestOutstanding > 0)
2072 JLOG(j.
warn()) <<
"Loan for " << principalRequested <<
" with no interest has interest due";
2086 JLOG(j.
warn()) <<
"Loan is unable to pay principal.";
2093 auto const roundedPayment =
2098 <<
") rounds to 0. ";
2111 computedPayments != paymentTotal)
2114 <<
") rounding (" << roundedPayment <<
") on a total value of "
2116 <<
" can not complete the loan in the specified "
2117 "number of payments ("
2118 << computedPayments <<
" != " << paymentTotal <<
")";
2133 Number const& theoreticalPrincipalOutstanding,
2134 Number const& periodicRate,
2142 theoreticalPrincipalOutstanding,
2149 accruedInterest >= 0,
2150 "xrpl::detail::computeFullPaymentInterest : valid accrued "
2154 auto const prepaymentPenalty = closeInterestRate ==
beast::kZero
2159 prepaymentPenalty >= 0,
2160 "xrpl::detail::computeFullPaymentInterest : valid prepayment "
2164 return accruedInterest + prepaymentPenalty;
2192 Number const& periodicPayment,
2193 Number const& periodicRate,
2197 if (paymentRemaining == 0)
2200 .valueOutstanding = 0,
2201 .principalOutstanding = 0,
2203 .managementFeeDue = 0,
2208 Number const totalValueOutstanding = periodicPayment * paymentRemaining;
2211 rules, periodicPayment, periodicRate, paymentRemaining);
2214 Number const interestOutstandingGross = totalValueOutstanding - principalOutstanding;
2217 Number const managementFeeOutstanding =
2221 Number const interestOutstandingNet = interestOutstandingGross - managementFeeOutstanding;
2224 .valueOutstanding = totalValueOutstanding,
2225 .principalOutstanding = principalOutstanding,
2226 .interestDue = interestOutstandingNet,
2227 .managementFeeDue = managementFeeOutstanding,
2253 Number const& totalValueOutstanding,
2254 Number const& principalOutstanding,
2255 Number const& managementFeeOutstanding)
2260 .valueOutstanding = totalValueOutstanding,
2261 .principalOutstanding = principalOutstanding,
2262 .interestDue = totalValueOutstanding - principalOutstanding - managementFeeOutstanding,
2263 .managementFeeDue = managementFeeOutstanding,
2270 XRPL_ASSERT(loan && loan->getType() == ltLOAN,
"xrpl::constructLoanState : valid loan SLE");
2273 loan->at(sfTotalValueOutstanding),
2274 loan->at(sfPrincipalOutstanding),
2275 loan->at(sfManagementFeeOutstanding));
2307 Number const& principalOutstanding,
2315 XRPL_ASSERT(interestRate == 0 || periodicRate > 0,
"xrpl::computeLoanProperties : valid rate");
2319 principalOutstanding,
2338 Number const& principalOutstanding,
2339 Number const& periodicRate,
2344 auto const periodicPayment =
2347 auto const [totalValueOutstanding, loanScale] = [&] {
2356 STAmount amount{asset, periodicPayment * paymentsRemaining};
2363 (amount.
integral() && loanScale == 0) ||
2365 "xrpl::computeLoanProperties",
2366 "loanScale value fits expectations");
2378 auto const roundedPrincipalOutstanding =
2382 auto const totalInterestOutstanding = totalValueOutstanding - roundedPrincipalOutstanding;
2383 auto const feeOwedToBroker =
2389 auto const firstPaymentPrincipal = [&] {
2393 rules, periodicPayment, periodicRate, paymentsRemaining, managementFeeRate);
2396 rules, periodicPayment, periodicRate, paymentsRemaining - 1, managementFeeRate);
2400 return startingState.principalOutstanding - firstPaymentState.principalOutstanding;
2404 .periodicPayment = periodicPayment,
2406 constructLoanState(totalValueOutstanding, roundedPrincipalOutstanding, feeOwedToBroker),
2407 .loanScale = loanScale,
2408 .firstPaymentPrincipal = firstPaymentPrincipal,
2418std::expected<LoanPaymentParts, TER>
2428 if (loan->at(sfPaymentRemaining) == 0 || loan->at(sfPrincipalOutstanding) == 0)
2432 JLOG(j.
warn()) <<
"Loan is already paid off.";
2438 auto const nextDueDateProxy = loan->at(sfNextPaymentDueDate);
2439 if (*nextDueDateProxy == 0)
2441 JLOG(j.
warn()) <<
"Loan next payment due date is not set.";
2446 *loan->at(sfTotalValueOutstanding) > 0,
"xrpl::loanMakePayment : valid total value");
2456 JLOG(j.
warn()) <<
"Loan payment is overdue. Use the tfLoanLatePayment transaction flag to "
2457 "make a late payment. Loan was created on "
2458 << loan->at(sfStartDate) <<
", prev payment due date is "
2459 << loan->at(sfPreviousPaymentDueDate) <<
", next payment due date is "
2460 << nextDueDateProxy <<
", ledger time is "
2465 switch (paymentType)
2477 UNREACHABLE(
"xrpl::loanMakePayment : invalid payment type");
A generic endpoint for log messages.
Stream trace() const
Severity stream access functions.
Writeable view to a ledger, for applying a transaction.
virtual void update(SLE::Ref sle)=0
Indicate changes to a peeked SLE.
AccountID const & getIssuer() const
std::chrono::time_point< NetClock > time_point
Number is a floating point type that can represent a wide range of values.
static RoundingMode getround()
constexpr int exponent() const noexcept
Returns the exponent of the external view of the Number.
virtual Rules const & rules() const =0
Returns the tx processing rules.
NetClock::time_point parentCloseTime() const
Returns the close time of the previous ledger.
virtual SLE::const_pointer read(Keylet const &k) const =0
Return the state item associated with a key.
Rules controlling protocol behavior.
bool enabled(UInt256 const &feature) const
Returns true if a feature is enabled.
std::string getFullText() const override
bool negative() const noexcept
bool integral() const noexcept
Asset const & asset() const
int exponent() const noexcept
bool isZeroAtScale(int scale) const
Checks if this amount evaluates to zero when constrained to a specific accounting scale.
std::shared_ptr< STLedgerEntry const > const & ConstRef
std::shared_ptr< STLedgerEntry > const & Ref
bool isFlag(std::uint32_t) const
bool isFieldPresent(SField const &field) const
TxType getTxnType() const
AccountingDeltas loanPaymentDeltas(LoanPaymentParts const &parts)
AccountingDeltas loanOriginationDeltas(Number const &principalRequested)
Number loanVaultExposure(SLE::ConstRef loanSle)
std::expected< LoanPaymentParts, TER > makeFullPayment(Asset const &asset, ApplyView const &view, SLE::Ref loan, SLE::ConstRef brokerSle, STAmount const &amount, beast::Journal j)
Number computePaymentFactor(Rules const &rules, Number const &periodicRate, std::uint32_t paymentsRemaining)
LoanPaymentParts doPayment(ExtendedPaymentComponents const &payment, SLE::Ref loan)
std::pair< TenthBips16, Number > loanRatesFor(SLE::ConstRef loan, SLE::ConstRef brokerSle)
Number loanPrincipalFromPeriodicPayment(Rules const &rules, Number const &periodicPayment, Number const &periodicRate, std::uint32_t paymentsRemaining)
std::expected< ExtendedPaymentComponents, TER > computeLatePayment(Asset const &asset, ReadView const &view, SLE::ConstRef loan, ExtendedPaymentComponents const &periodic, STAmount const &amount, TenthBips16 managementFeeRate, beast::Journal j)
Number computePowerMinusOneHybrid(Number const &periodicRate, std::uint32_t paymentsRemaining)
Number loanPeriodicPayment(Rules const &rules, Number const &principalOutstanding, Number const &periodicRate, std::uint32_t paymentsRemaining)
int posteriorAssetScale(VaultVersion version, Asset const &asset, int baseScale, Number const &reference, Number const &delta)
Shared core of getPosteriorVaultScale and getPosteriorBrokerCoverScale: the exponent reference + delt...
std::expected< ExtendedPaymentComponents, TER > computeFullPayment(Asset const &asset, ReadView const &view, SLE::ConstRef loan, Number const &periodicRate, STAmount const &amount, TenthBips16 managementFeeRate, beast::Journal j)
Number loanAccruedInterest(Number const &principalOutstanding, Number const &periodicRate, NetClock::time_point parentCloseTime, std::uint32_t startDate, std::uint32_t prevPaymentDate, std::uint32_t paymentInterval)
STAmount roundToPosteriorBrokerCoverScale(SLE::ConstRef vault, SLE::ConstRef broker, STAmount const &delta, Number::RoundingMode roundingMode)
Round a cover outflow delta (cover withdraw, cover clawback, the broker-side decrease of a default's ...
int getPosteriorBrokerCoverScale(SLE::ConstRef vault, SLE::ConstRef broker, Number const &delta)
Return a LoanBroker's posterior live cover exponent after applying an unrounded delta.
std::pair< Number, Number > roundAndSplitInterest(Asset const &asset, Number const &rawInterest, TenthBips16 managementFeeRate, std::int32_t loanScale, Number::RoundingMode mode=Number::getround())
std::pair< Number, Number > computeInterestAndFeeParts(Asset const &asset, Number const &interest, TenthBips16 managementFeeRate, std::int32_t loanScale)
Number loanLatePaymentInterest(Number const &principalOutstanding, TenthBips32 lateInterestRate, NetClock::time_point parentCloseTime, std::uint32_t nextPaymentDueDate)
STAmount creditToPosteriorScale(Asset const &asset, Number const &reference, int baseScale, Number const &raw, Number::RoundingMode roundingMode)
Shared core of creditToPosteriorAvailableScale and creditToPosteriorBrokerCoverScale: floors referenc...
std::expected< std::pair< LoanPaymentParts, LoanProperties >, TER > tryOverpayment(Rules const &rules, Asset const &asset, std::int32_t loanScale, ExtendedPaymentComponents const &overpaymentComponents, LoanState const &roundedLoanState, Number const &periodicPayment, Number const &periodicRate, std::uint32_t paymentRemaining, TenthBips16 const managementFeeRate, beast::Journal j)
std::expected< LoanPaymentParts, TER > makeLatePayment(Asset const &asset, ApplyView const &view, SLE::Ref loan, SLE::ConstRef brokerSle, STAmount const &amount, beast::Journal j)
std::expected< LoanPaymentParts, TER > doOverpayment(Rules const &rules, Asset const &asset, std::int32_t loanScale, ExtendedPaymentComponents const &overpaymentComponents, SLE::Ref loan, Number const &periodicRate, TenthBips16 const managementFeeRate, beast::Journal j)
ExtendedPaymentComponents computeOverpaymentComponents(Rules const &rules, Asset const &asset, int32_t const loanScale, Number const &overpayment, TenthBips32 const overpaymentInterestRate, TenthBips32 const overpaymentFeeRate, TenthBips16 const managementFeeRate)
std::expected< LoanPaymentParts, TER > makeRegularPayment(Asset const &asset, ApplyView const &view, SLE::Ref loan, SLE::ConstRef brokerSle, STAmount const &amount, LoanPaymentType const paymentType, beast::Journal j)
Number computePowerMinusOne(Number const &periodicRate, std::uint32_t paymentsRemaining)
PaymentComponents computePaymentComponents(Rules const &rules, Asset const &asset, std::int32_t scale, Number const &totalValueOutstanding, Number const &principalOutstanding, Number const &managementFeeOutstanding, Number const &periodicPayment, Number const &periodicRate, std::uint32_t paymentRemaining, TenthBips16 managementFeeRate)
AccountingDeltas loanPaymentDeltas(LoanPaymentParts const &parts)
Number loanVaultExposure(SLE::ConstRef loanSle)
AccountingDeltas loanOriginationDeltas(Number const &principalRequested, Number const &interestDue)
bool loanOriginationExceedsVaultMaximum(Number const &vaultMaximum, Number const &vaultTotal, Number const &interestDue)
Keylet vault(AccountID const &owner, SeqProxy const &seq) noexcept
Keylet loanBroker(AccountID const &owner, SeqProxy const &seq) noexcept
Keylet loan(UInt256 const &loanBrokerID, SeqProxy const &loanSeq) noexcept
Use hash_* containers for keys that do not need a cryptographically secure hashing algorithm.
static constexpr Number kNumZero
constexpr BaseUInt< Bits, Tag > operator+(BaseUInt< Bits, Tag > const &a, BaseUInt< Bits, Tag > const &b)
void adjustBrokerDebtTotal(SLE::Ref brokerSle, SLE::ConstRef vaultSle, Number const &delta, int vaultScale)
Apply a signed delta to a LoanBroker's DebtTotal: on FixedPrecision Vaults, add the exact delta (Debt...
Number loanPeriodicRate(TenthBips32 interestRate, std::uint32_t paymentInterval)
static auto sum(TCollection const &col)
bool loanOriginationExceedsVaultMaximum(SLE::ConstRef vaultSle, Number const &vaultTotal, Number const &interestDue)
bool hasExpired(ReadView const &view, std::optional< std::uint32_t > const &exp, ExpiryComparison comparison=ExpiryComparison::Inclusive)
Determines whether the given expiration time has passed.
STAmount debitToPosteriorBrokerCoverScale(SLE::ConstRef vault, SLE::ConstRef broker, STAmount const &amount, Number::RoundingMode roundingMode)
Round a cover debit (cover withdraw, cover clawback, the broker-side decrease of a default's cover cr...
Number operator-(Number const &x, Number const &y)
constexpr T tenthBipsOfValue(T value, TenthBips< TBips > bips)
void adjustImpreciseNumber(NumberProxy value, Number const &adjustment, Asset const &asset, int vaultScale)
int scale(Number const &number, Asset const &asset)
Get the scale of a Number for a given asset.
std::expected< LoanPaymentParts, TER > loanMakePayment(Asset const &asset, ApplyView &view, SLE::Ref loan, SLE::ConstRef brokerSle, STAmount const &amount, LoanPaymentType const paymentType, beast::Journal j)
Number power(Number const &f, unsigned n)
TenthBips< std::uint32_t > TenthBips32
TenthBips< std::uint16_t > TenthBips16
TER checkLoanGuards(Asset const &vaultAsset, Number const &principalRequested, bool expectInterest, std::uint32_t paymentTotal, LoanProperties const &properties, beast::Journal j)
STAmount roundToScale(STAmount const &value, std::int32_t scale, Number::RoundingMode rounding=Number::getround())
Round an arbitrary precision Amount to the precision of an STAmount that has a given exponent.
Number minimumBrokerCover(Number const &debtTotal, TenthBips32 coverRateMinimum, SLE::ConstRef vaultSle)
Minimum required broker cover, rounded up.
bool isPaymentLate(ReadView const &view, SLE::ConstRef loanSle)
std::optional< LoanDefaultFreezeExemptAccounts > getLoanDefaultFreezeExemptAccounts(ReadView const &view, STTx const &tx)
Resolves the accounts and asset a LoanManage default transaction is exempt from freeze/lock for.
int getVaultBaseScale(SLE::ConstRef vault)
Return the Vault's base exponent.
LoanState computeTheoreticalLoanState(Rules const &rules, Number const &periodicPayment, Number const &periodicRate, std::uint32_t const paymentRemaining, TenthBips32 const managementFeeRate)
AccountingDeltas loanPaymentDeltas(SLE::ConstRef vaultSle, LoanPaymentParts const &parts)
TER checkOptionalBrokerCoverInflow(SLE::ConstRef vault, SLE::ConstRef broker, STAmount const &amount)
Check whether amount is an admissible optional cover inflow.
void roundToAsset(A const &asset, Number &value)
Round an arbitrary precision Number IN PLACE to the precision of a given Asset.
Number roundPeriodicPayment(Asset const &asset, Number const &periodicPayment, std::int32_t scale)
Ensure the periodic payment is always rounded consistently.
Number computeManagementFee(Asset const &asset, Number const &interest, TenthBips32 managementFeeRate, std::int32_t scale)
Number getVaultOpenLimit(SLE::ConstRef vault)
Open-zone capacity ceiling: 9 * 10^(15 + baseScale).
TERSubset< CanCvtToTER > TER
Number loanVaultExposure(SLE::ConstRef vaultSle, SLE::ConstRef loanSle)
@ tecINSUFFICIENT_PAYMENT
static constexpr std::uint32_t kSecondsInYear
LoanProperties computeLoanProperties(Rules const &rules, Asset const &asset, Number const &principalOutstanding, TenthBips32 interestRate, std::uint32_t paymentInterval, std::uint32_t paymentsRemaining, TenthBips32 managementFeeRate, std::int32_t minimumScale)
VaultVersion getVaultVersion(SLE::ConstRef vault)
Resolves a Vault's LEVersion.
AccountingDeltas loanOriginationDeltas(SLE::ConstRef vaultSle, Number const &principalRequested, Number const &interestDue)
LoanState constructLoanState(Number const &totalValueOutstanding, Number const &principalOutstanding, Number const &managementFeeOutstanding)
TER canApplyToBrokerCover(ReadView const &view, SLE::ConstRef sleBroker, Asset const &vaultAsset, STAmount const &amount, beast::Journal j, std::string_view logPrefix)
Broker cover preclaim precision guard (fixCleanup3_2_0).
Number computeFullPaymentInterest(Number const &theoreticalPrincipalOutstanding, Number const &periodicRate, NetClock::time_point parentCloseTime, std::uint32_t paymentInterval, std::uint32_t prevPaymentDate, std::uint32_t startDate, TenthBips32 closeInterestRate)
bool checkLendingProtocolDependencies(Rules const &rules, STTx const &tx)
STAmount creditToPosteriorBrokerCoverScale(SLE::ConstRef vault, SLE::ConstRef broker, Number const &raw, Number::RoundingMode roundingMode)
Round a cover inflow (cover deposit, LoanPay's fee redirect into cover) into CoverAvailable by floori...
bool isRounded(Asset const &asset, Number const &value, std::int32_t scale)
The accounts and asset that LoanManage::defaultLoan's fixCleanup3_4_0 freeze/lock exemption applies t...
bool operator==(LoanPaymentParts const &other) const
LoanPaymentParts & operator+=(LoanPaymentParts const &other)
Number firstPaymentPrincipal
This structure captures the parts of a loan state.
Number principalOutstanding
Number untrackedManagementFee
Number total() const
Calculates the total change across all components.
Number trackedPrincipalDelta
PaymentSpecialCase specialCase
Number trackedManagementFeeDelta
Number trackedInterestPart() const
Calculates the tracked interest portion of this payment.
T time_since_epoch(T... args)