Merge branch 'develop' into ximinez/number-fix-maxrepcusp

include/xrpl/ledger/helpers/VaultHelpers.h

@@ -1,5 +1,7 @@
 #pragma once
 
+#include <xrpl/ledger/ReadView.h>
+#include <xrpl/protocol/AccountID.h>
 #include <xrpl/protocol/STAmount.h>
 #include <xrpl/protocol/STLedgerEntry.h>
 
@@ -43,6 +45,14 @@ sharesToAssetsDeposit(
 /** Controls whether to truncate shares instead of rounding. */
 enum class TruncateShares : bool { No = false, Yes = true };
 
+/** Controls whether the withdraw conversion helpers
+    (assetsToSharesWithdraw and sharesToAssetsWithdraw) subtract
+    sfLossUnrealized from sfAssetsTotal before computing the exchange rate.
+    The default (No) applies the standard discounted rate; Yes is used when
+    the redeemer is the sole remaining shareholder.
+*/
+enum class WaiveUnrealizedLoss : bool { No = false, Yes = true };
+
 /** From the perspective of a vault, return the number of shares to demand from
     the depositor when they ask to withdraw a fixed amount of assets. Since
     shares are MPT this number is integral, and it will be rounded to nearest
@@ -52,6 +62,8 @@ enum class TruncateShares : bool { No = false, Yes = true };
     @param issuance The MPTokenIssuance SLE for the vault's shares.
     @param assets The amount of assets to convert.
     @param truncate Whether to truncate instead of rounding.
+    @param waive Whether to waive the unrealized-loss discount when computing
+                 the exchange rate.
 
     @return The number of shares, or nullopt on error.
 */
@@ -60,7 +72,8 @@ assetsToSharesWithdraw(
     std::shared_ptr<SLE const> const& vault,
     std::shared_ptr<SLE const> const& issuance,
     STAmount const& assets,
-    TruncateShares truncate = TruncateShares::No);
+    TruncateShares truncate = TruncateShares::No,
+    WaiveUnrealizedLoss waive = WaiveUnrealizedLoss::No);
 
 /** From the perspective of a vault, return the number of assets to give the
     depositor when they redeem a fixed amount of shares. Note, since shares are
@@ -69,6 +82,8 @@ assetsToSharesWithdraw(
     @param vault The vault SLE.
     @param issuance The MPTokenIssuance SLE for the vault's shares.
     @param shares The amount of shares to convert.
+    @param waive Whether to waive (i.e. not subtract) the vault's unrealized
+                 loss when computing the exchange rate.
 
     @return The number of assets, or nullopt on error.
 */
@@ -76,6 +91,22 @@ assetsToSharesWithdraw(
 sharesToAssetsWithdraw(
     std::shared_ptr<SLE const> const& vault,
     std::shared_ptr<SLE const> const& issuance,
-    STAmount const& shares);
+    STAmount const& shares,
+    WaiveUnrealizedLoss waive = WaiveUnrealizedLoss::No);
+
+/** Returns true iff `account` holds all of the vault's outstanding shares —
+    i.e. is the sole remaining shareholder. Returns false if the account
+    holds no shares or fewer than the total outstanding.
+
+    @param view The ledger view.
+    @param account The candidate sole shareholder.
+    @param issuance The MPTokenIssuance SLE for the vault's shares; provides
+                    both the share MPTID and the outstanding-amount total.
+*/
+[[nodiscard]] bool
+isSoleShareholder(
+    ReadView const& view,
+    AccountID const& account,
+    std::shared_ptr<SLE const> const& issuance);
 
 }  // namespace xrpl