XLS-66: Principal-only Vault/LoanBroker accounting under LendingProtocolV1_1 by Tapanito · Pull Request #582 · XRPLF/XRPL-Standards

Tapanito · 2026-07-16T16:23:05Z

High Level Overview of Change

Defines the LendingProtocolV1_1 amendment path for LoanSet, LoanPay, and LoanManage (impair/unimpair/default) that makes Vault.AssetsTotal and LoanBroker.DebtTotal track loan principal only, excluding interest. Pre-amendment behavior is kept unchanged as the fallback.

As a consequence, valueChange — the mechanism that reconciles Vault.AssetsTotal/LoanBroker.DebtTotal for interest effects from late payments, overpayments, and early full repayments — is no longer used: since neither field tracks interest under the amendment, there is nothing left to reconcile. valueChange becomes dead output; an amendment-only implementation would not need to compute it.

Context of Change

Follows the documentation convention established in #570 (dedicated Amendment-labeled subsections, e.g. ##### 3.8.6.1 State Changes (LendingProtocolV1_1)), keeping the current spec text as the default and adding parallel, clearly separated sections for the amended Failure Conditions/State Changes rather than interleaving inline notes. This PR is independent of #570 (which adds Vault.AssetsReserved for pending loans) — it only reuses the same amendment name and formatting pattern.

Changes by transaction:

LoanSet: Vault.AssetsTotal no longer increases by InterestDue; LoanBroker.DebtTotal increases by PrincipalRequested only. Adds a matching Protocol-Level Failures (LendingProtocolV1_1) subsection overriding the DebtMaximum/AssetsMaximum/CoverAvailable cap checks, which previously included InterestDue.
LoanPay: LoanBroker.DebtTotal decreases by principalPaid only; Vault.AssetsTotal increases by interestPaid only. principalPaid/interestPaid come from the same, unchanged PeriodicPayment/amortization logic in Appendix A-3 — no new machinery.
LoanManage (impair/unimpair/default): collapses to a single, unified DefaultAmount = Loan.PrincipalOutstanding, used consistently for VaultLoss/DefaultCovered, LoanBroker.DebtTotal, and Vault.LossUnrealized (impair/unimpair). Adds a matching failure-condition override for the impairment limit check. Includes a full worked numeric example (LoanSet → LoanPay → default) comparing pre- and post-amendment trajectories, confirming ManagementFeeOutstanding stays excluded and the CoverRateMinimum/CoverRateLiquidation mechanics are unchanged in shape.

Non-goals (intentionally out of scope, called out in the spec): no new Vault-level field: only AssetsTotal, AssetsAvailable, and LossUnrealized are touched; no amendment-transition/mixed-portfolio behavior; no change to Loan-level fields (TotalValueOutstanding etc., which still track interest independent of this amendment); no change to general impair philosophy beyond the impair/default consistency check.

Type of Change

XLS Update (changes to an existing XLS)

gregtatcam · 2026-07-21T18:21:49Z

 24. The `LoanBroker.LoanSequence` has reached its maximum value. (`tecMAX_SEQUENCE_REACHED`)

+##### 3.8.5.3 Protocol-Level Failures (`LendingProtocolV1_1`)
+


Should add updated check 14 since the interest is no longer tracked by AssetsTotal:

Vault.AssetsMaximum != 0 and Vault.AssetsTotal > Vault.AssetsMaximum (expected interest would exceed vault assets cap). (tecLIMIT_EXCEEDED)

gregtatcam · 2026-07-22T14:06:53Z

 | `ShareMPTID`        |    No    |   Yes    |      `number`      |   `UINT192`   |       0       | The identifier of the share MPTokenIssuance object.                                                                                                    |
 | `WithdrawalPolicy`  |    No    |   Yes    |      `string`      |    `UINT8`    |     `N/A`     | Indicates the withdrawal strategy used by the Vault.                                                                                                   |
 | `Scale`             |    No    |   Yes    |      `number`      |    `UINT8`    |       6       | The `Scale` specifies the power of 10 ($10^{\text{scale}}$) to multiply an asset's value by when converting it into an integer-based number of shares. |
+| `LEVersion`         |    No    |    No    |      `number`      |    `UINT8`    |       0       | Introduced by the `LendingProtocolV1_1` amendment. See [3.1.2.2](#3122-leversion-lendingprotocolv1_1).                                                 |


LEVersion sounds like it's a format version. Also sounds like the only reason for LE prefix is to disambiguate it from the existing Version. How about Generation or Revision?

mvadari · 2026-08-04T15:38:38Z

 #### 3.8.6 State Changes

 1. Create the `Loan` object with computed fields (`TotalValueOutstanding`, `PeriodicPayment`, `ManagementFeeOutstanding`, `LoanScale`, etc.).
 2. Increment `AccountRoot(Borrower).OwnerCount` by `1`.


Suggested change

2. Increment `AccountRoot(Borrower).OwnerCount` by `3`.

1. In XLS-65.1, this was `2`.

1. In XLS-65.0, this was `1`.

mvadari · 2026-08-04T15:45:43Z

 8. Directory linking:
   - Add `LoanID` to the `OwnerDirectory` of the `LoanBroker` _pseudo-account_ (sets `LoanBrokerNode`).
   - Add `LoanID` to the `OwnerDirectory` of the `Borrower` (sets `OwnerNode`).


Suggested change

- Add `LoanID` to the `OwnerDirectory` of the `Borrower` (sets `OwnerNode`).

8. Directory linking:

- Add `LoanID` to the `OwnerDirectory` of the `LoanBroker` _pseudo-account_ (sets `LoanBrokerNode`).

- Add `LoanID` to the `OwnerDirectory` of the `Borrower` (sets `OwnerNode`).

- Add `LoanID` to something else (added in `LendingProtocolV1_1`).

mvadari · 2026-08-04T15:46:43Z


 ## 3. Specification

 ### 3.1 Ledger Entry: `Vault`


Suggested change

### 3.1 Amendments

#### 3.1.1 `SingleAssetVault`

Brief explanation, link to patch

#### 3.1.2 `LendingProtocolV1_1`

Brief explanation, link to patch

### 3.2 Ledger Entry: `Vault`

mvadari · 2026-08-04T15:54:14Z


 # Appendix

 ## A-1 F.A.Q.


Suggested change

## A-1 Changelog

### A-1.1 `LendingProtocol`: released 2026-01-32

This amendment releases the feature

### A-1.2 `fixCleanup3_1_3`: released 2026-some-date

This amendment makes XYZ minor changes

### A-1.3 `fixCleanup3_2_0`: released 2026-06-something

This amendment makes ABC minor changes

## A-2 F.A.Q.

adds cash-based share valuation

5480349

Tapanito requested a review from gregtatcam July 21, 2026 09:47

adds Vault version

ec48162

gregtatcam requested changes Jul 21, 2026

View reviewed changes

update the spec to not skip SLEVersion 1

8edeab3

Tapanito mentioned this pull request Jul 22, 2026

feat: Implement LoanBroker cash-basis accounting XRPLF/rippled#7817

Merged

4 tasks

gregtatcam reviewed Jul 22, 2026

View reviewed changes

Merge branch 'master' into tapanito/lending-cash-basis

4a1b926

mvadari reviewed Aug 4, 2026

View reviewed changes

Navigation Menu

Uh oh!

XLS-66: Principal-only Vault/LoanBroker accounting under LendingProtocolV1_1 - #582

XLS-66: Principal-only Vault/LoanBroker accounting under LendingProtocolV1_1#582
Tapanito wants to merge 4 commits into
masterfrom
tapanito/lending-cash-basis

Tapanito commented Jul 16, 2026

Uh oh!

gregtatcam Jul 21, 2026

Uh oh!

Uh oh!

gregtatcam Jul 22, 2026

Uh oh!

mvadari Aug 4, 2026

Uh oh!

mvadari Aug 4, 2026

Uh oh!

mvadari Aug 4, 2026 •

edited

Loading

Uh oh!

mvadari Aug 4, 2026 •

edited

Loading

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

		24. The `LoanBroker.LoanSequence` has reached its maximum value. (`tecMAX_SEQUENCE_REACHED`)

		##### 3.8.5.3 Protocol-Level Failures (`LendingProtocolV1_1`)

+. Increment `AccountRoot(Borrower).OwnerCount` by `3`.
+. In XLS-65.1, this was `2`.
+. In XLS-65.0, this was `1`.

+### 3.1 Amendments
+#### 3.1.1 `SingleAssetVault`
+Brief explanation, link to patch
+#### 3.1.2 `LendingProtocolV1_1`
+Brief explanation, link to patch
+### 3.2 Ledger Entry: `Vault`

+## A-1 Changelog
+### A-1.1 `LendingProtocol`: released 2026-01-32
+This amendment releases the feature
+### A-1.2 `fixCleanup3_1_3`: released 2026-some-date
+This amendment makes XYZ minor changes
+### A-1.3 `fixCleanup3_2_0`: released 2026-06-something
+This amendment makes ABC minor changes
+## A-2 F.A.Q.

Uh oh!

Conversation

Tapanito commented Jul 16, 2026

High Level Overview of Change

Context of Change

Type of Change

Uh oh!

gregtatcam Jul 21, 2026

Choose a reason for hiding this comment

Uh oh!

Uh oh!

gregtatcam Jul 22, 2026

Choose a reason for hiding this comment

Uh oh!

mvadari Aug 4, 2026

Choose a reason for hiding this comment

Uh oh!

mvadari Aug 4, 2026

Choose a reason for hiding this comment

Uh oh!

mvadari Aug 4, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

mvadari Aug 4, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

mvadari Aug 4, 2026 •

edited

Loading

mvadari Aug 4, 2026 •

edited

Loading