From 9ae863d89e345a862cd5711dc49677f82eacd8d3 Mon Sep 17 00:00:00 2001
From: Vito <5780819+Tapanito@users.noreply.github.com>
Date: Tue, 22 Sep 2026 13:41:10 +0200
Subject: [PATCH] docs: Clarify LEVersion and deprecate kVaultMaximumIouScale.

Split the pre-V1.2 Scale cap to kVaultMaximumLegacyIouScale so the old name can warn without breaking V1.2 call sites.
---
 include/xrpl/ledger/helpers/VaultHelpers.h    | 12 +++---
 include/xrpl/protocol/Protocol.h              | 39 +++++++++++++------
 .../tx/transactors/vault/VaultCreate.cpp      |  2 +-
 .../app/vault/VaultFixedPrecision_test.cpp    |  2 +-
 4 files changed, 37 insertions(+), 18 deletions(-)

diff --git a/include/xrpl/ledger/helpers/VaultHelpers.h b/include/xrpl/ledger/helpers/VaultHelpers.h
index 91ca6d689c..f3d1d02061 100644
--- a/include/xrpl/ledger/helpers/VaultHelpers.h
+++ b/include/xrpl/ledger/helpers/VaultHelpers.h
@@ -235,11 +235,13 @@ sharesToAssetsWithdraw(
 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 (instant interest
- * recognition vs. cash-basis) a Vault uses. Vaults created before featureLendingProtocolV1_1
- * activated never have sfLEVersion set, which resolves here to
- * VaultVersion::Legacy.
+ * Resolves a Vault's LEVersion.
+ *
+ * LEVersion is the single point every accounting and rounding helper
+ * should call to decide which protocol a Vault follows. It is written
+ * at VaultCreate and is not updated afterwards, so a Vault created
+ * under an older amendment keeps that behaviour after later amendments
+ * activate. Absent sfLEVersion resolves to VaultVersion::Legacy.
  *
  * @param vault The vault SLE.
  *
diff --git a/include/xrpl/protocol/Protocol.h b/include/xrpl/protocol/Protocol.h
index 9e95e7af61..0323842b5e 100644
--- a/include/xrpl/protocol/Protocol.h
+++ b/include/xrpl/protocol/Protocol.h
@@ -311,23 +311,40 @@ constexpr std::uint8_t kVaultStrategyFirstComeFirstServe = 1;
  * Default IOU scale factor for a Vault
  */
 constexpr std::uint8_t kVaultDefaultIouScale = 6;
-/**
- * Maximum scale factor for a Vault. The number is chosen to ensure that
- * 1 IOU can be always converted to shares.
- * 10^19 > maxMPTokenAmount (2^64-1) > 10^18
- */
-constexpr std::uint8_t kVaultMaximumIouScale = 18;
 
 /**
- * Maximum fixed-precision IOU scale factor for a Vault.
+ * Maximum Scale for a Vault created before featureLendingProtocolV1_2.
+ * Chosen so 1 IOU can always convert to shares:
+ * 10^19 > maxMPTokenAmount (2^64-1) > 10^18.
+ */
+constexpr std::uint8_t kVaultMaximumLegacyIouScale = 18;
+
+/**
+ * Maximum Scale for a Vault created under featureLendingProtocolV1_2.
  */
 constexpr std::uint8_t kVaultMaximumFixedIouScale = 10;
 
 /**
- * Vault ledger-entry schema versions. Assigned to newly created Vaults by
- * featureLendingProtocolV1_1 and later protocol amendments. Vaults created
- * before activation are left without LEVersion (implicit legacy version 0,
- * instant interest recognition).
+ * @deprecated Use kVaultMaximumFixedIouScale for V1.2 vaults, or
+ * kVaultMaximumLegacyIouScale for pre-V1.2 vaults.
+ */
+[[deprecated("Use kVaultMaximumFixedIouScale or kVaultMaximumLegacyIouScale")]]
+constexpr std::uint8_t kVaultMaximumIouScale = kVaultMaximumLegacyIouScale;
+
+/**
+ * Vault ledger-entry schema versions, persisted as sfLEVersion.
+ *
+ * LEVersion records which protocol a Vault was created under so later
+ * amendments can change the rules for new Vaults without rewriting
+ * existing ones. VaultCreate writes it from the then-active lending
+ * amendments; later transactions do not update it. A Vault created
+ * under an older amendment keeps that amendment's behaviour for its
+ * lifetime, even after a newer lending amendment activates.
+ *
+ * Absent sfLEVersion is implicit Legacy (version 0): instant interest
+ * recognition and a dynamic AssetsTotal scale. CashBasis (V1.1) uses
+ * cash-basis recognition on the same dynamic scale. FixedPrecision
+ * (V1.2) keeps cash-basis recognition and adds the lifetime base grid.
  */
 enum class VaultVersion : uint8_t {
     Legacy = 0,
diff --git a/src/libxrpl/tx/transactors/vault/VaultCreate.cpp b/src/libxrpl/tx/transactors/vault/VaultCreate.cpp
index 49105e5d46..86873432d4 100644
--- a/src/libxrpl/tx/transactors/vault/VaultCreate.cpp
+++ b/src/libxrpl/tx/transactors/vault/VaultCreate.cpp
@@ -103,7 +103,7 @@ VaultCreate::preflight(PreflightContext const& ctx)
 
         auto const maximumScale = ctx.rules.enabled(featureLendingProtocolV1_2)
             ? kVaultMaximumFixedIouScale
-            : kVaultMaximumIouScale;
+            : kVaultMaximumLegacyIouScale;
         if (scale > maximumScale)
             return temMALFORMED;
     }
diff --git a/src/test/app/vault/VaultFixedPrecision_test.cpp b/src/test/app/vault/VaultFixedPrecision_test.cpp
index ac2c89dd9c..a252a2e712 100644
--- a/src/test/app/vault/VaultFixedPrecision_test.cpp
+++ b/src/test/app/vault/VaultFixedPrecision_test.cpp
@@ -97,7 +97,7 @@ class VaultFixedPrecision_test : public VaultTestBase
 
             Vault const vault{env};
             auto [tx, keylet] = vault.create({.owner = owner, .asset = asset});
-            tx[sfScale] = kVaultMaximumIouScale;
+            tx[sfScale] = kVaultMaximumLegacyIouScale;
             env(tx);
             env.close();