Principal-only Vault/LoanBroker accounting

XLS-0065-single-asset-vault/65.1/README.md

@@ -0,0 +1,92 @@
+<pre>
+  xls: 65.1
+  title: Single Asset Vault under LendingProtocolV1_1
+  description: Records the changes the LendingProtocolV1_1 amendment makes to XLS-65
+  author: Vytautas Vito Tumas <vtumas@ripple.com>, Aanchal Malhotra <amalhotra@ripple.com>
+  proposal-from: https://github.com/XRPLF/XRPL-Standards/discussions/192
+  status: Draft
+  category: Amendment
+  requires: [XLS-65](../README.md)
+  created: 2026-09-04
+  updated: 2026-09-07
+</pre>
+
+# Single Asset Vault under `LendingProtocolV1_1`
+
+## 1. Abstract
+
+This patch of [XLS-65](../README.md) records the changes the `LendingProtocolV1_1` amendment makes to the Single Asset Vault. The amendment is not yet live. The consolidated specification is the top-level [README.md](../README.md).
+
+The amendment makes the following changes to XLS-65:
+
+- **Vault Cash-Basis Accounting** — Adds a `LEVersion` field that selects the accounting model a Vault applies to `AssetsTotal`: Vaults created while the amendment is enabled use cash-basis accounting, in which `AssetsTotal` excludes uncollected interest and grows only as interest is collected in cash, and Vaults created before the amendment keep accrual-basis accounting, in which `AssetsTotal` includes interest as it accrues.
+
+## 2. Motivation
+
+**Vault Cash-Basis Accounting.** Accrual-basis accounting credits a Vault with interest that a Borrower has not paid yet, so the share exchange rate reflects income the Vault has not received. A depositor can redeem shares at a rate inflated by interest that later defaults, and the loss falls on the depositors who remain. Cash-basis accounting removes that mismatch by recognising interest only when it is paid.
+
+Existing Vaults cannot switch accounting models without changing the value of shares already issued, so the model has to be recorded per Vault rather than derived from the amendment state at the time of the transaction.
+
+## 3. Specification
+
+### 3.3 Vault Cash-Basis Accounting
+
+#### 3.3.1 Ledger Entry: `Vault`
+
+##### 3.3.1.1 Fields
+
+| Field Name  | Constant | Required | Internal Type | Default Value | Description                                                                                                            |
+| ----------- | :------: | :------: | :-----------: | :-----------: | ---------------------------------------------------------------------------------------------------------------------- |
+| `LEVersion` |   Yes    |    No    |    `UINT8`    | absent (`0`)  | The accounting model the Vault applies to `AssetsTotal`. Absent is treated as `0` (accrual basis). Immutable once set. |
+
+##### 3.3.1.2 `LEVersion`
+
+`LEVersion` selects the accounting model of the Vault:
+
+- `LEVersion` absent (treated as `0`, accrual basis): `AssetsTotal` includes the interest accrued over the life of the connected Loans. This is the pre-amendment behaviour and continues to apply to every Vault created before the amendment was enabled.
+- `LEVersion = 1` (cash basis): `AssetsTotal` excludes uncollected interest and increases only as interest is collected in cash.
+
+The field is written once by `VaultCreate` and is immutable after creation. A Vault created while the amendment is enabled is always cash-basis, and a Vault created before it is always accrual-basis; neither can be converted to the other.
+
+##### 3.3.1.3 Invariants
+
+- `Vault.LEVersion` is immutable once set.
+
+Because `VaultCreate` is the only transaction that writes `LEVersion`, newly created Vaults have either an absent `LEVersion` or `LEVersion = 1`.
+
+##### 3.3.1.4 Example JSON
+
+```json
+{
+  "LedgerEntryType": "Vault",
+  "LEVersion": 1,
+  "Asset": {
+    "currency": "USD",
+    "issuer": "rf1BiGeXwwQoi8Z2ueFYTEXSwuJYfV2Jpn"
+  },
+  "AssetsTotal": "1000",
+  "AssetsAvailable": "1000"
+}
+```
+
+#### 3.3.2 Transaction: `VaultCreate`
+
+##### 3.3.2.1 Failure Conditions
+
+No failure conditions are added or removed. `LEVersion` is not a transaction field and cannot be supplied by the submitter.
+
+##### 3.3.2.2 State Changes
+
+When the amendment is enabled, the created `Vault` ledger entry has `LEVersion = 1`. When it is not enabled, the field is not written and the Vault is accrual-basis.
+
+## 4. Rationale
+
+**Vault Cash-Basis Accounting.** The alternative to a per-entry version field is to derive the accounting model from the amendment state at the time each Loan transaction executes. That was rejected because it would silently change the share exchange rate of every existing Vault on the ledger at the moment the amendment activates.
+
+`LEVersion` is a version number rather than a boolean flag so that a later accounting change can be expressed as a further version without another field.
+
+## 5. Security Considerations
+
+**Vault Cash-Basis Accounting.** Cash-basis accounting reduces, but does not remove, the exposure of a depositor to an unpaid Loan: the Vault still carries the principal at face value until the Loan defaults or is impaired. `LossUnrealized` remains the mechanism for reporting an expected shortfall.
+
+Because `LEVersion` is immutable, an implementation must read it from the `Vault` ledger entry rather than from the amendment state when computing the interest accounting of a Loan. Reading the amendment state instead would apply cash-basis rules to accrual-basis Vaults and misprice their shares.