feat: Implement LoanBroker cash-basis accounting (#7817)

include/xrpl/ledger/helpers/LendingHelpers.h

@@ -286,6 +286,77 @@ computeFullPaymentInterest(
     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 CashBasis {
+
+AccountingDeltas
+loanOriginationDeltas(Number const& principalRequested);
+
+Number
+loanVaultExposure(SLE::const_ref loanSle);
+
+AccountingDeltas
+loanPaymentDeltas(LoanPaymentParts const& parts);
+
+}  // namespace CashBasis
+
+// Public dispatchers: pick CashBasis:: 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

include/xrpl/ledger/helpers/VaultHelpers.h

@@ -2,6 +2,7 @@
 
 #include <xrpl/ledger/ReadView.h>
 #include <xrpl/protocol/AccountID.h>
+#include <xrpl/protocol/Protocol.h>
 #include <xrpl/protocol/STAmount.h>
 #include <xrpl/protocol/STLedgerEntry.h>
 
@@ -107,4 +108,19 @@ sharesToAssetsWithdraw(
 [[nodiscard]] bool
 isSoleShareholder(ReadView const& view, AccountID const& account, SLE::const_ref issuance);
 
+/**
+ * Resolves a Vault's LEVersion, the single point every accounting touch
+ * point should call to determine which recognition model (accrual vs.
+ * cash-basis) a Vault uses. Vaults created before featureLendingProtocolV1_1
+ * activated never have sfLEVersion set, which resolves here to
+ * VaultVersion::Legacy.
+ *
+ * @param vault The vault SLE.
+ *
+ * @return The Vault's LEVersion, or VaultVersion::Legacy if the field is
+ * absent.
+ */
+[[nodiscard]] VaultVersion
+getVaultVersion(SLE::const_ref vault);
+
 }  // namespace xrpl

include/xrpl/protocol/Protocol.h

@@ -316,6 +316,17 @@ constexpr std::uint8_t kVaultDefaultIouScale = 6;
  */
 constexpr std::uint8_t kVaultMaximumIouScale = 18;
 
+/**
+ * Vault ledger-entry schema versions. Assigned to newly created
+ * Vaults once featureLendingProtocolV1_1 is enabled. Vaults created before
+ * activation are left without LEVersion (implicit legacy version 0,
+ * accrual-basis accounting).
+ */
+enum class VaultVersion : uint8_t {
+    Legacy = 0,
+    CashBasis,
+};
+
 /**
  * Maximum recursion depth for vault shares being put as an asset inside
  * another vault; counted from 0

include/xrpl/protocol/detail/ledger_entries.macro

@@ -505,6 +505,7 @@ LEDGER_ENTRY(ltVAULT, 0x0084, Vault, vault, ({
     {sfShareMPTID,           SoeRequired},
     {sfWithdrawalPolicy,     SoeRequired},
     {sfScale,                SoeDefault},
+    {sfLEVersion,            SoeDefault},
     // no SharesTotal ever (use MPTIssuance.sfOutstandingAmount)
     // no PermissionedDomainID ever (use MPTIssuance.sfDomainID)
 }))

include/xrpl/protocol/detail/sfields.macro

@@ -18,6 +18,7 @@ TYPED_SFIELD(sfMethod,                   UINT8,      2)
 TYPED_SFIELD(sfTransactionResult,        UINT8,      3)
 TYPED_SFIELD(sfScale,                    UINT8,      4)
 TYPED_SFIELD(sfAssetScale,               UINT8,      5)
+TYPED_SFIELD(sfLEVersion,                UINT8,      6)
 
 // 8-bit integers (uncommon)
 TYPED_SFIELD(sfTickSize,                 UINT8,     16)

include/xrpl/protocol_autogen/ledger_entries/Vault.h

@@ -287,6 +287,30 @@ public:
     {
         return this->sle_->isFieldPresent(sfScale);
     }
+
+    /**
+     * @brief Get sfLEVersion (SoeDefault)
+     * @return The field value, or std::nullopt if not present.
+     */
+    [[nodiscard]]
+    protocol_autogen::Optional<SF_UINT8::type::value_type>
+    getLEVersion() const
+    {
+        if (hasLEVersion())
+            return this->sle_->at(sfLEVersion);
+        return std::nullopt;
+    }
+
+    /**
+     * @brief Check if sfLEVersion is present.
+     * @return True if the field is present, false otherwise.
+     */
+    [[nodiscard]]
+    bool
+    hasLEVersion() const
+    {
+        return this->sle_->isFieldPresent(sfLEVersion);
+    }
 };
 
 /**
@@ -508,6 +532,17 @@ public:
         return *this;
     }
 
+    /**
+     * @brief Set sfLEVersion (SoeDefault)
+     * @return Reference to this builder for method chaining.
+     */
+    VaultBuilder&
+    setLEVersion(std::decay_t<typename SF_UINT8::type::value_type> const& value)
+    {
+        object_[sfLEVersion] = value;
+        return *this;
+    }
+
     /**
      * @brief Build and return the completed Vault wrapper.
      * @param index The ledger entry index.