LendingHelpers.h

#pragma once
 
#include <xrpl/basics/Number.h>
#include <xrpl/basics/chrono.h>
#include <xrpl/beast/utility/Journal.h>
#include <xrpl/beast/utility/Zero.h>
#include <xrpl/beast/utility/instrumentation.h>
#include <xrpl/ledger/ApplyView.h>
#include <xrpl/ledger/ReadView.h>
#include <xrpl/protocol/Asset.h>
#include <xrpl/protocol/LedgerFormats.h>  // IWYU pragma: keep
#include <xrpl/protocol/Protocol.h>
#include <xrpl/protocol/Rules.h>
#include <xrpl/protocol/SField.h>
#include <xrpl/protocol/STAmount.h>
#include <xrpl/protocol/STLedgerEntry.h>
#include <xrpl/protocol/STNumber.h>  // IWYU pragma: keep
#include <xrpl/protocol/STTx.h>
#include <xrpl/protocol/TER.h>
#include <xrpl/protocol/Units.h>
 
#include <cstdint>
#include <expected>
#include <string_view>
#include <utility>
 
namespace xrpl {

[[nodiscard]] TER
canApplyToBrokerCover(
    ReadView const& view,
    SLE::const_ref sleBroker,
    Asset const& vaultAsset,
    STAmount const& amount,
    beast::Journal j,
    std::string_view logPrefix);
 
// Lending protocol has dependencies, so capture them here.
bool
checkLendingProtocolDependencies(Rules const& rules, STTx const& tx);
 
static constexpr std::uint32_t kSecondsInYear = 365 * 24 * 60 * 60;
 
Number
loanPeriodicRate(TenthBips32 interestRate, std::uint32_t paymentInterval);

inline Number
roundPeriodicPayment(Asset const& asset, Number const& periodicPayment, std::int32_t scale)
{
    return roundToAsset(asset, periodicPayment, scale, Number::RoundingMode::Upward);
}
 
/* Represents the breakdown of amounts to be paid and changes applied to the
 * Loan object while processing a loan payment.
 *
 * This structure is returned after processing a loan payment transaction and
 * captures the amounts that need to be paid. The actual ledger entry changes
 * are made in LoanPay based on this structure values.
 *
 * The sum of principalPaid, interestPaid, and feePaid represents the total
 * amount to be deducted from the borrower's account. The valueChange field
 * tracks whether the loan's total value increased or decreased beyond normal
 * amortization.
 *
 * This structure is explained in the XLS-66 spec, section 3.2.4.2 (Payment
 * Processing).
 */
struct LoanPaymentParts
{
    // The amount of principal paid that reduces the loan balance.
    // This amount is subtracted from sfPrincipalOutstanding in the Loan object
    // and paid to the Vault
    Number principalPaid = kNumZero;
 
    // The total amount of interest paid to the Vault.
    // This includes:
    // - Tracked interest from the amortization schedule
    // - Untracked interest (e.g., late payment penalty interest)
    // This value is always non-negative.
    Number interestPaid = kNumZero;
 
    // The change in the loan's total value outstanding.
    // - If valueChange < 0: Loan value decreased
    // - If valueChange > 0: Loan value increased
    // - If valueChange = 0: No value adjustment
    //
    // For regular on-time payments, this is always 0. Non-zero values occur
    // when:
    // - Overpayments reduce the loan balance beyond the scheduled amount
    // - Late payments add penalty interest to the loan value
    // - Early full payment may increase or decrease the loan value based on
    // terms
    Number valueChange = kNumZero;
 
    /* The total amount of fees paid to the Broker.
     * This includes:
     * - Tracked management fees from the amortization schedule
     * - Untracked fees (e.g., late payment fees, service fees, origination
     * fees) This value is always non-negative.
     */
    Number feePaid = kNumZero;
 
    LoanPaymentParts&
    operator+=(LoanPaymentParts const& other);
 
    bool
    operator==(LoanPaymentParts const& other) const;
};

struct LoanState
{
    // Total value still due to be paid by the borrower.
    Number valueOutstanding;
    // Principal still due to be paid by the borrower.
    Number principalOutstanding;
    // Interest still due to be paid to the Vault.
    // This is a portion of interestOutstanding
    Number interestDue;
    // Management fee still due to be paid to the broker.
    // This is a portion of interestOutstanding
    Number managementFeeDue;
 
    // Interest still due to be paid by the borrower.
    [[nodiscard]] Number
    interestOutstanding() const
    {
        XRPL_ASSERT_PARTS(
            interestDue + managementFeeDue == valueOutstanding - principalOutstanding,
            "xrpl::LoanState::interestOutstanding",
            "other values add up correctly");
        return interestDue + managementFeeDue;
    }
};
 
/* Describes the initial computed properties of a loan.
 *
 * This structure contains the fundamental calculated values that define a
 * loan's payment structure and amortization schedule. These properties are
 * computed:
 * - At loan creation (LoanSet transaction)
 * - When loan terms change (e.g., after an overpayment that reduces the loan
 * balance)
 */
struct LoanProperties
{
    // The unrounded amount to be paid at each regular payment period.
    // Calculated using the standard amortization formula based on principal,
    // interest rate, and number of payments.
    // The actual amount paid in the LoanPay transaction must be rounded up to
    // the precision of the asset and loan.
    Number periodicPayment;
 
    // The loan's current state, with all values rounded to the loan's scale.
    LoanState loanState;
 
    // The scale (decimal places) used for rounding all loan amounts.
    // This is the maximum of:
    // - The asset's native scale
    // - A minimum scale required to represent the periodic payment accurately
    // All loan state values (principal, interest, fees) are rounded to this
    // scale.
    std::int32_t loanScale{};
 
    // The principal portion of the first payment.
    Number firstPaymentPrincipal;
};
 
// Some values get re-rounded to the vault scale any time they are adjusted. In
// addition, they are prevented from ever going below zero. This helps avoid
// accumulated rounding errors and leftover dust amounts.
template <class NumberProxy>
void
adjustImpreciseNumber(
    NumberProxy value,
    Number const& adjustment,
    Asset const& asset,
    int vaultScale)
{
    value = roundToAsset(asset, value + adjustment, vaultScale);
 
    if (*value < beast::kZero)
        value = 0;
}
 
inline int
getAssetsTotalScale(SLE::const_ref vaultSle)
{
    if (!vaultSle)
        return Number::kMinExponent - 1;  // LCOV_EXCL_LINE
    return scale(vaultSle->at(sfAssetsTotal), vaultSle->at(sfAsset));
}
 
// Compute the minimum required broker cover, rounded consistently.
// DebtTotal is a broker-level aggregate maintained at vault scale, so the
// rounding must also use vault scale — never an individual loan's scale.
inline Number
minimumBrokerCover(Number const& debtTotal, TenthBips32 coverRateMinimum, SLE::const_ref vaultSle)
{
    XRPL_ASSERT(
        vaultSle && vaultSle->getType() == ltVAULT, "xrpl::minimumBrokerCover : valid Vault sle");
    NumberRoundModeGuard const mg(Number::RoundingMode::Upward);
    return roundToAsset(
        vaultSle->at(sfAsset),
        tenthBipsOfValue(debtTotal, coverRateMinimum),
        getAssetsTotalScale(vaultSle));
}
 
TER
checkLoanGuards(
    Asset const& vaultAsset,
    Number const& principalRequested,
    bool expectInterest,
    std::uint32_t paymentTotal,
    LoanProperties const& properties,
    beast::Journal j);
 
LoanState
computeTheoreticalLoanState(
    Rules const& rules,
    Number const& periodicPayment,
    Number const& periodicRate,
    std::uint32_t const paymentRemaining,
    TenthBips32 const managementFeeRate);
 
// Constructs a valid LoanState object from arbitrary inputs
LoanState
constructLoanState(
    Number const& totalValueOutstanding,
    Number const& principalOutstanding,
    Number const& managementFeeOutstanding);
 
// Overload of constructLoanState() that reads the three tracked fields
// directly from a Loan ledger object, which always holds rounded values,
// rather than taking them as separate Number arguments.
LoanState
constructLoanState(SLE::const_ref loan);
 
Number
computeManagementFee(
    Asset const& asset,
    Number const& interest,
    TenthBips32 managementFeeRate,
    std::int32_t scale);
 
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);
 
// Deltas applied to Vault.AssetsTotal and LoanBroker.DebtTotal at a single
// accounting touch point (origination, payment, impair/unimpair/default).
struct AccountingDeltas
{
    Number assetsTotalDelta;
    Number debtTotalDelta;
};
 
// Whole-life (pre-LendingProtocolV1_1) recognition model: interest is
// recognized into AssetsTotal/DebtTotal up front, at origination.
namespace accrual {
 
// LoanSet origination: what's added to Vault.AssetsTotal and LoanBroker.DebtTotal
AccountingDeltas
loanOriginationDeltas(Number const& principalRequested, Number const& interestDue);
 
// LoanSet origination: would recognizing this loan's interest push
// Vault.AssetsTotal past Vault.AssetsMaximum?
bool
loanOriginationExceedsVaultMaximum(
    Number const& vaultMaximum,
    Number const& vaultTotal,
    Number const& interestDue);
 
// LoanManage impair/unimpair/default: the vault's exposure to this loan
Number
loanVaultExposure(SLE::const_ref loanSle);
 
// LoanPay: what's added to Vault.AssetsTotal and subtracted from LoanBroker.DebtTotal for a payment
AccountingDeltas
loanPaymentDeltas(LoanPaymentParts const& parts);
 
}  // namespace accrual
 
// Cash-basis (LendingProtocolV1_1) recognition model: AssetsTotal/DebtTotal
// are principal-only, interest is recognized only as it's actually paid.
namespace cash_basis {
 
AccountingDeltas
loanOriginationDeltas(Number const& principalRequested);
 
Number
loanVaultExposure(SLE::const_ref loanSle);
 
AccountingDeltas
loanPaymentDeltas(LoanPaymentParts const& parts);
 
}  // namespace cash_basis
 
// Public dispatchers: pick cash_basis:: if featureLendingProtocolV1_1 is
// enabled AND the Vault's LEVersion (VaultHelpers::getVaultVersion) is
// VaultVersion::CashBasis, else accrual::. These are the only entry points
// transactors call.
AccountingDeltas
loanOriginationDeltas(
    SLE::const_ref vaultSle,
    Number const& principalRequested,
    Number const& interestDue);
 
bool
loanOriginationExceedsVaultMaximum(
    SLE::const_ref vaultSle,
    Number const& vaultTotal,
    Number const& interestDue);
 
Number
loanVaultExposure(SLE::const_ref vaultSle, SLE::const_ref loanSle);
 
AccountingDeltas
loanPaymentDeltas(SLE::const_ref vaultSle, LoanPaymentParts const& parts);
 
namespace detail {
// These classes and functions should only be accessed by LendingHelper
// functions and unit tests
 
enum class PaymentSpecialCase { None, Final, Extra };
 
/* Represents a single loan payment component parts.
 
* This structure captures the "delta" (change) values that will be applied to
* the tracked fields in the Loan ledger object when a payment is processed.
*
* These are called "deltas" because they represent the amount by which each
* corresponding field in the Loan object will be reduced.
* They are "tracked" as they change tracked loan values.
*/
struct PaymentComponents
{
    // The change in total value outstanding for this payment.
    // This amount will be subtracted from sfTotalValueOutstanding in the Loan
    // object. Equal to the sum of trackedPrincipalDelta,
    // trackedInterestPart(), and trackedManagementFeeDelta.
    Number trackedValueDelta;
 
    // The change in principal outstanding for this payment.
    // This amount will be subtracted from sfPrincipalOutstanding in the Loan
    // object, representing the portion of the payment that reduces the
    // original loan amount.
    Number trackedPrincipalDelta;
 
    // The change in management fee outstanding for this payment.
    // This amount will be subtracted from sfManagementFeeOutstanding in the
    // Loan object. This represents only the tracked management fees from the
    // amortization schedule and does not include additional untracked fees
    // (such as late payment fees) that go directly to the broker.
    Number trackedManagementFeeDelta;
 
    // Indicates if this payment has special handling requirements.
    // - none: Regular scheduled payment
    // - final: The last payment that closes out the loan
    // - extra: An additional payment beyond the regular schedule (overpayment)
    PaymentSpecialCase specialCase = PaymentSpecialCase::None;

    [[nodiscard]] Number
    trackedInterestPart() const;
};
 
/* Extends PaymentComponents with untracked payment amounts.
 *
 * This structure adds untracked fees and interest to the base
 * PaymentComponents, representing amounts that don't affect the Loan object's
 * tracked state but are still part of the total payment due from the borrower.
 *
 * Untracked amounts include:
 * - Late payment fees that go directly to the Broker
 * - Late payment penalty interest that goes directly to the Vault
 * - Service fees
 *
 * The key distinction is that tracked amounts reduce the Loan object's state
 * (sfTotalValueOutstanding, sfPrincipalOutstanding,
 * sfManagementFeeOutstanding), while untracked amounts are paid directly to the
 * recipient without affecting the loan's amortization schedule.
 */
struct ExtendedPaymentComponents : public PaymentComponents
{
    // Additional management fees that go directly to the Broker.
    // This includes fees not part of the standard amortization schedule
    // (e.g., late fees, service fees, origination fees).
    // This value may be negative, though the final value returned in
    // LoanPaymentParts.feePaid will never be negative.
    Number untrackedManagementFee;
 
    // Additional interest that goes directly to the Vault.
    // This includes interest not part of the standard amortization schedule
    // (e.g., late payment penalty interest).
    // This value may be negative, though the final value returned in
    // LoanPaymentParts.interestPaid will never be negative.
    Number untrackedInterest;
 
    // The complete amount due from the borrower for this payment.
    // Calculated as: trackedValueDelta + untrackedInterest +
    // untrackedManagementFee
    //
    // This value is used to validate that the payment amount provided by the
    // borrower is sufficient to cover all components of the payment.
    Number totalDue;
 
    ExtendedPaymentComponents(PaymentComponents const& p, Number fee, Number interest = kNumZero)
        : PaymentComponents(p)
        , untrackedManagementFee(fee)
        , untrackedInterest(interest)
        , totalDue(trackedValueDelta + untrackedInterest + untrackedManagementFee)
    {
    }
};
 
/* Represents the differences between two loan states.
 *
 * This structure is used to capture the change in each component of a loan's
 * state, typically when computing the difference between two LoanState objects
 * (e.g., before and after a payment). It is a convenient way to capture changes
 * in each component. How that difference is used depends on the context.
 */
struct LoanStateDeltas
{
    // The difference in principal outstanding between two loan states.
    Number principal;
 
    // The difference in interest due between two loan states.
    Number interest;
 
    // The difference in management fee outstanding between two loan states.
    Number managementFee;

    [[nodiscard]] Number
    total() const
    {
        return principal + interest + managementFee;
    }
 
    // Ensures all delta values are non-negative.
    void
    nonNegative();
};
 
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);
 
[[nodiscard]] Number
computePowerMinusOne(Number const& periodicRate, std::uint32_t paymentsRemaining);
 
[[nodiscard]] Number
computePowerMinusOneHybrid(Number const& periodicRate, std::uint32_t paymentsRemaining);
 
[[nodiscard]] Number
computePaymentFactor(
    Rules const& rules,
    Number const& periodicRate,
    std::uint32_t paymentsRemaining);
 
std::pair<Number, Number>
computeInterestAndFeeParts(
    Asset const& asset,
    Number const& interest,
    TenthBips16 managementFeeRate,
    std::int32_t loanScale);
 
Number
loanPeriodicPayment(
    Rules const& rules,
    Number const& principalOutstanding,
    Number const& periodicRate,
    std::uint32_t paymentsRemaining);
 
Number
loanPrincipalFromPeriodicPayment(
    Rules const& rules,
    Number const& periodicPayment,
    Number const& periodicRate,
    std::uint32_t paymentsRemaining);
 
Number
loanLatePaymentInterest(
    Number const& principalOutstanding,
    TenthBips32 lateInterestRate,
    NetClock::time_point parentCloseTime,
    std::uint32_t nextPaymentDueDate);
 
Number
loanAccruedInterest(
    Number const& principalOutstanding,
    Number const& periodicRate,
    NetClock::time_point parentCloseTime,
    std::uint32_t startDate,
    std::uint32_t prevPaymentDate,
    std::uint32_t paymentInterval);
 
ExtendedPaymentComponents
computeOverpaymentComponents(
    Rules const& rules,
    Asset const& asset,
    int32_t const loanScale,
    Number const& overpayment,
    TenthBips32 const overpaymentInterestRate,
    TenthBips32 const overpaymentFeeRate,
    TenthBips16 const managementFeeRate);
 
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);
 
}  // namespace detail
 
detail::LoanStateDeltas
operator-(LoanState const& lhs, LoanState const& rhs);
 
LoanState
operator-(LoanState const& lhs, detail::LoanStateDeltas const& rhs);
 
LoanState
operator+(LoanState const& lhs, detail::LoanStateDeltas const& rhs);
 
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);
 
LoanProperties
computeLoanProperties(
    Rules const& rules,
    Asset const& asset,
    Number const& principalOutstanding,
    Number const& periodicRate,
    std::uint32_t paymentsRemaining,
    TenthBips32 managementFeeRate,
    std::int32_t minimumScale);
 
bool
isRounded(Asset const& asset, Number const& value, std::int32_t scale);
 
// Indicates what type of payment is being made.
// regular, late, and full are mutually exclusive.
// overpayment is an "add on" to a regular payment, and follows that path with
// potential extra work at the end.
enum class LoanPaymentType { Regular = 0, Late, Full, Overpayment };
 
std::expected<LoanPaymentParts, TER>
loanMakePayment(
    Asset const& asset,
    ApplyView& view,
    SLE::ref loan,
    SLE::const_ref brokerSle,
    STAmount const& amount,
    LoanPaymentType const paymentType,
    beast::Journal j);
 
}  // namespace xrpl