feat: Add a new closed ended vault to extend SAV (#7921)

Co-authored-by: Vito Tumas <5780819+Tapanito@users.noreply.github.com>

include/xrpl/ledger/View.h

@@ -35,6 +35,11 @@ enum class SkipEntry : bool { No = false, Yes };
 //
 //------------------------------------------------------------------------------
 
+/**
+ * Whether an expiration check should be inclusive or exclusive.
+ */
+enum class ExpiryComparison { Inclusive, Exclusive };
+
 /**
  * Determines whether the given expiration time has passed.
  *
@@ -54,11 +59,16 @@ enum class SkipEntry : bool { No = false, Yes };
  *
  * @param view The ledger whose parent time is used as the clock.
  * @param exp The optional expiration time we want to check.
+ * @param comparison Whether the boundary is inclusive (`now >= exp`, the
+ *                   default) or exclusive (`now > exp`).
  *
  * @return `true` if `exp` is in the past; `false` otherwise.
  */
 [[nodiscard]] bool
-hasExpired(ReadView const& view, std::optional<std::uint32_t> const& exp);
+hasExpired(
+    ReadView const& view,
+    std::optional<std::uint32_t> const& exp,
+    ExpiryComparison comparison = ExpiryComparison::Inclusive);
 
 // Note, depth parameter is used to limit the recursion depth
 [[nodiscard]] bool

include/xrpl/ledger/helpers/VaultHelpers.h

@@ -6,10 +6,13 @@
 #include <xrpl/protocol/STAmount.h>
 #include <xrpl/protocol/STLedgerEntry.h>
 
+#include <cstdint>
 #include <optional>
 
 namespace xrpl {
 
+class STTx;
+
 /**
  * From the perspective of a vault, return the number of shares to give
  * depositor when they offer a fixed amount of assets. Note, since shares are
@@ -123,4 +126,82 @@ isSoleShareholder(ReadView const& view, AccountID const& account, SLE::const_ref
 [[nodiscard]] VaultVersion
 getVaultVersion(SLE::const_ref vault);
 
+/**
+ * Resolves the VaultKind of a vault SLE. Returns VaultKind::ClosedEnded when
+ * sfVaultKind is present and equal to that value; anything else (including an
+ * absent field or an unrecognised value) is treated as VaultKind::OpenEnded.
+ *
+ * @param vault The vault SLE.
+ */
+[[nodiscard]] VaultKind
+getVaultKind(SLE::const_ref vault);
+
+/**
+ * Reads sfVaultKind from a transaction. An absent field resolves to
+ * VaultKind::OpenEnded (matching the on-ledger default); any unrecognised
+ * value is also treated as VaultKind::OpenEnded, mirroring the SLE overload.
+ * Callers that need to reject out-of-range values (e.g. preflight) should
+ * gate on isValidVaultKind() first.
+ *
+ * @param tx The transaction.
+ */
+[[nodiscard]] VaultKind
+getVaultKind(STTx const& tx);
+
+/**
+ * Returns true iff sfVaultKind is either absent from @p tx or is present and
+ * equal to a recognised VaultKind enumerator. Intended for use in preflight
+ * to reject malformed transactions before decoding with getVaultKind().
+ *
+ * @param tx The transaction.
+ */
+[[nodiscard]] bool
+isValidVaultKind(STTx const& tx);
+
+/**
+ * Returns true iff the (SubscriptionDate, RedemptionDate) gap of a
+ * closed-ended vault satisfies
+ * kMinInvestmentPeriod <= (red - sub) < kMaxInvestmentPeriod. The arithmetic
+ * is performed in std::int64_t so that @p sub near UINT32_MAX does not
+ * overflow. Shared by VaultCreate::preflight and the ValidVault invariant.
+ *
+ * @param sub The value of sfSubscriptionDate.
+ * @param red The value of sfRedemptionDate.
+ */
+[[nodiscard]] bool
+isValidClosedEndedGap(std::uint32_t sub, std::uint32_t red);
+
+/**
+ * Returns the current lifecycle phase of a vault. Open-ended
+ * vaults are always NoPhase. For closed-ended vaults the phase is derived
+ * from the parent ledger close time and the vault's immutable
+ * SubscriptionDate and RedemptionDate.
+ *
+ * @param view The ledger view whose parent close time is used as the clock.
+ * @param vault The vault SLE.
+ */
+[[nodiscard]] VaultPhase
+getVaultPhase(ReadView const& view, SLE::const_ref vault);
+
+/**
+ * Raw-fields overload of getVaultPhase. Derives the phase from an already
+ * decomposed vault snapshot: an absent or non-ClosedEnded @p vaultKind
+ * resolves to VaultPhase::NoPhase; otherwise the phase is computed from
+ * @p subscriptionDate and @p redemptionDate against the view's parent
+ * close time using the same boundary semantics as the SLE overload
+ * (Subscription is inclusive of now == SubscriptionDate; Investment starts
+ * strictly after).
+ *
+ * @param view The ledger view whose parent close time is used as the clock.
+ * @param vaultKind The value of sfVaultKind, or nullopt if absent.
+ * @param subscriptionDate The value of sfSubscriptionDate, or nullopt if absent.
+ * @param redemptionDate The value of sfRedemptionDate, or nullopt if absent.
+ */
+[[nodiscard]] VaultPhase
+getVaultPhase(
+    ReadView const& view,
+    std::optional<std::uint8_t> vaultKind,
+    std::optional<std::uint32_t> subscriptionDate,
+    std::optional<std::uint32_t> redemptionDate);
+
 }  // namespace xrpl

include/xrpl/protocol/Protocol.h

@@ -9,6 +9,7 @@
 #include <mpt_protocol.h>
 #include <secp256k1_mpt.h>
 
+#include <chrono>
 #include <cstddef>
 #include <cstdint>
 
@@ -327,6 +328,36 @@ enum class VaultVersion : uint8_t {
     CashBasis,
 };
 
+/**
+ * Vault kind. Distinguishes closed-ended vaults from the default open-ended
+ * kind. Persisted as sfVaultKind (UINT8); absent means OpenEnded.
+ */
+enum class VaultKind : std::uint8_t {
+    OpenEnded = 0,
+    ClosedEnded = 1,
+};
+
+/**
+ * Lifecycle phase of a vault. Open-ended vaults are always NoPhase; the other
+ * three values are the phases of a closed-ended vault.
+ */
+enum class VaultPhase : std::uint8_t {
+    NoPhase = 0,
+    Subscription,
+    Investment,
+    Redemption,
+};
+
+/**
+ * Bounds on the length of a closed-ended vault's Investment phase
+ * (RedemptionDate - SubscriptionDate). At vault creation the gap must satisfy
+ * kMinInvestmentPeriod <= gap < kMaxInvestmentPeriod.
+ */
+constexpr std::uint32_t kMinInvestmentPeriod =
+    std::chrono::seconds{std::chrono::minutes{1}}.count();
+// This is 946708560 seconds which 30 x 365.2425 days (the average length of a Gregorian year).
+constexpr std::uint32_t kMaxInvestmentPeriod = std::chrono::seconds{std::chrono::years{30}}.count();
+
 /**
  * Maximum recursion depth for vault shares being put as an asset inside
  * another vault; counted from 0

include/xrpl/protocol/detail/ledger_entries.macro

@@ -506,6 +506,9 @@ LEDGER_ENTRY(ltVAULT, 0x0084, Vault, vault, ({
     {sfWithdrawalPolicy,     SoeRequired},
     {sfScale,                SoeDefault},
     {sfLEVersion,            SoeDefault},
+    {sfVaultKind,            SoeDefault},
+    {sfSubscriptionDate,     SoeOptional},
+    {sfRedemptionDate,       SoeOptional},
     // no SharesTotal ever (use MPTIssuance.sfOutstandingAmount)
     // no PermissionedDomainID ever (use MPTIssuance.sfDomainID)
 }))

include/xrpl/protocol/detail/sfields.macro

@@ -27,6 +27,7 @@ TYPED_SFIELD(sfUNLModifyDisabling,       UINT8,     17)
 TYPED_SFIELD(sfWasLockingChainSend,      UINT8,     19)
 TYPED_SFIELD(sfWithdrawalPolicy,         UINT8,     20)
 TYPED_SFIELD(sfContractResult,           UINT8,     21)
+TYPED_SFIELD(sfVaultKind,                UINT8,     22)
 
 // 16-bit integers (common)
 TYPED_SFIELD(sfLedgerEntryType,          UINT16,     1, SField::kSmdNever)
@@ -116,6 +117,8 @@ TYPED_SFIELD(sfSponsoringOwnerCount,     UINT32,    71)
 TYPED_SFIELD(sfSponsoringAccountCount,   UINT32,    72)
 TYPED_SFIELD(sfRemainingOwnerCount,      UINT32,    73)
 TYPED_SFIELD(sfSponsorFlags,             UINT32,    74)
+TYPED_SFIELD(sfSubscriptionDate,         UINT32,    75)
+TYPED_SFIELD(sfRedemptionDate,           UINT32,    76)
 
 // 64-bit integers (common)
 TYPED_SFIELD(sfIndexNext,                UINT64,     1)

include/xrpl/protocol/detail/transactions.macro

@@ -862,6 +862,9 @@ TRANSACTION(ttVAULT_CREATE, 65, VaultCreate,
     {sfWithdrawalPolicy, SoeOptional},
     {sfData, SoeOptional},
     {sfScale, SoeOptional},
+    {sfVaultKind, SoeOptional},
+    {sfSubscriptionDate, SoeOptional},
+    {sfRedemptionDate, SoeOptional},
 }))
 
 /** This transaction updates a single asset vault. */

include/xrpl/protocol_autogen/ledger_entries/Vault.h

@@ -311,6 +311,78 @@ public:
     {
         return this->sle_->isFieldPresent(sfLEVersion);
     }
+
+    /**
+     * @brief Get sfVaultKind (SoeDefault)
+     * @return The field value, or std::nullopt if not present.
+     */
+    [[nodiscard]]
+    protocol_autogen::Optional<SF_UINT8::type::value_type>
+    getVaultKind() const
+    {
+        if (hasVaultKind())
+            return this->sle_->at(sfVaultKind);
+        return std::nullopt;
+    }
+
+    /**
+     * @brief Check if sfVaultKind is present.
+     * @return True if the field is present, false otherwise.
+     */
+    [[nodiscard]]
+    bool
+    hasVaultKind() const
+    {
+        return this->sle_->isFieldPresent(sfVaultKind);
+    }
+
+    /**
+     * @brief Get sfSubscriptionDate (SoeOptional)
+     * @return The field value, or std::nullopt if not present.
+     */
+    [[nodiscard]]
+    protocol_autogen::Optional<SF_UINT32::type::value_type>
+    getSubscriptionDate() const
+    {
+        if (hasSubscriptionDate())
+            return this->sle_->at(sfSubscriptionDate);
+        return std::nullopt;
+    }
+
+    /**
+     * @brief Check if sfSubscriptionDate is present.
+     * @return True if the field is present, false otherwise.
+     */
+    [[nodiscard]]
+    bool
+    hasSubscriptionDate() const
+    {
+        return this->sle_->isFieldPresent(sfSubscriptionDate);
+    }
+
+    /**
+     * @brief Get sfRedemptionDate (SoeOptional)
+     * @return The field value, or std::nullopt if not present.
+     */
+    [[nodiscard]]
+    protocol_autogen::Optional<SF_UINT32::type::value_type>
+    getRedemptionDate() const
+    {
+        if (hasRedemptionDate())
+            return this->sle_->at(sfRedemptionDate);
+        return std::nullopt;
+    }
+
+    /**
+     * @brief Check if sfRedemptionDate is present.
+     * @return True if the field is present, false otherwise.
+     */
+    [[nodiscard]]
+    bool
+    hasRedemptionDate() const
+    {
+        return this->sle_->isFieldPresent(sfRedemptionDate);
+    }
 };
 
 /**
@@ -543,6 +615,39 @@ public:
         return *this;
     }
 
+    /**
+     * @brief Set sfVaultKind (SoeDefault)
+     * @return Reference to this builder for method chaining.
+     */
+    VaultBuilder&
+    setVaultKind(std::decay_t<typename SF_UINT8::type::value_type> const& value)
+    {
+        object_[sfVaultKind] = value;
+        return *this;
+    }
+
+    /**
+     * @brief Set sfSubscriptionDate (SoeOptional)
+     * @return Reference to this builder for method chaining.
+     */
+    VaultBuilder&
+    setSubscriptionDate(std::decay_t<typename SF_UINT32::type::value_type> const& value)
+    {
+        object_[sfSubscriptionDate] = value;
+        return *this;
+    }
+
+    /**
+     * @brief Set sfRedemptionDate (SoeOptional)
+     * @return Reference to this builder for method chaining.
+     */
+    VaultBuilder&
+    setRedemptionDate(std::decay_t<typename SF_UINT32::type::value_type> const& value)
+    {
+        object_[sfRedemptionDate] = value;
+        return *this;
+    }
+
     /**
      * @brief Build and return the completed Vault wrapper.
      * @param index The ledger entry index.

include/xrpl/protocol_autogen/transactions/VaultCreate.h

@@ -214,6 +214,84 @@ public:
     {
         return this->tx_->isFieldPresent(sfScale);
     }
+
+    /**
+     * @brief Get sfVaultKind (SoeOptional)
+     * @return The field value, or std::nullopt if not present.
+     */
+    [[nodiscard]]
+    protocol_autogen::Optional<SF_UINT8::type::value_type>
+    getVaultKind() const
+    {
+        if (hasVaultKind())
+        {
+            return this->tx_->at(sfVaultKind);
+        }
+        return std::nullopt;
+    }
+
+    /**
+     * @brief Check if sfVaultKind is present.
+     * @return True if the field is present, false otherwise.
+     */
+    [[nodiscard]]
+    bool
+    hasVaultKind() const
+    {
+        return this->tx_->isFieldPresent(sfVaultKind);
+    }
+
+    /**
+     * @brief Get sfSubscriptionDate (SoeOptional)
+     * @return The field value, or std::nullopt if not present.
+     */
+    [[nodiscard]]
+    protocol_autogen::Optional<SF_UINT32::type::value_type>
+    getSubscriptionDate() const
+    {
+        if (hasSubscriptionDate())
+        {
+            return this->tx_->at(sfSubscriptionDate);
+        }
+        return std::nullopt;
+    }
+
+    /**
+     * @brief Check if sfSubscriptionDate is present.
+     * @return True if the field is present, false otherwise.
+     */
+    [[nodiscard]]
+    bool
+    hasSubscriptionDate() const
+    {
+        return this->tx_->isFieldPresent(sfSubscriptionDate);
+    }
+
+    /**
+     * @brief Get sfRedemptionDate (SoeOptional)
+     * @return The field value, or std::nullopt if not present.
+     */
+    [[nodiscard]]
+    protocol_autogen::Optional<SF_UINT32::type::value_type>
+    getRedemptionDate() const
+    {
+        if (hasRedemptionDate())
+        {
+            return this->tx_->at(sfRedemptionDate);
+        }
+        return std::nullopt;
+    }
+
+    /**
+     * @brief Check if sfRedemptionDate is present.
+     * @return True if the field is present, false otherwise.
+     */
+    [[nodiscard]]
+    bool
+    hasRedemptionDate() const
+    {
+        return this->tx_->isFieldPresent(sfRedemptionDate);
+    }
 };
 
 /**
@@ -338,6 +416,39 @@ public:
         return *this;
     }
 
+    /**
+     * @brief Set sfVaultKind (SoeOptional)
+     * @return Reference to this builder for method chaining.
+     */
+    VaultCreateBuilder&
+    setVaultKind(std::decay_t<typename SF_UINT8::type::value_type> const& value)
+    {
+        object_[sfVaultKind] = value;
+        return *this;
+    }
+
+    /**
+     * @brief Set sfSubscriptionDate (SoeOptional)
+     * @return Reference to this builder for method chaining.
+     */
+    VaultCreateBuilder&
+    setSubscriptionDate(std::decay_t<typename SF_UINT32::type::value_type> const& value)
+    {
+        object_[sfSubscriptionDate] = value;
+        return *this;
+    }
+
+    /**
+     * @brief Set sfRedemptionDate (SoeOptional)
+     * @return Reference to this builder for method chaining.
+     */
+    VaultCreateBuilder&
+    setRedemptionDate(std::decay_t<typename SF_UINT32::type::value_type> const& value)
+    {
+        object_[sfRedemptionDate] = value;
+        return *this;
+    }
+
     /**
      * @brief Build and return the VaultCreate wrapper.
      * @param publicKey The public key for signing.

include/xrpl/tx/invariants/LoanInvariant.h

@@ -16,6 +16,8 @@ namespace xrpl {
  * @brief Invariants: Loans are internally consistent
  *
  * 1. If `Loan.PaymentRemaining = 0` then `Loan.PrincipalOutstanding = 0`
+ * 2. A newly-created Loan against a closed-ended vault must satisfy
+ *    `StartDate + PaymentInterval * PaymentRemaining < Vault.RedemptionDate`.
  *
  */
 class ValidLoan

include/xrpl/tx/invariants/VaultInvariant.h

@@ -38,7 +38,17 @@ namespace xrpl {
  * - vault set must not alter the vault assets or shares balance
  * - no vault transaction can change loss unrealized (it's updated by loan
  *   transactions)
+ * - a created closed-ended vault must satisfy
+ *   MIN_INVESTMENT_PERIOD <= RedemptionDate - SubscriptionDate <
+ *   MAX_INVESTMENT_PERIOD
+ * - vault deposit may only succeed when the vault phase is NoPhase or
+ *   Subscription
+ * - vault withdrawal may not succeed when the vault phase is Investment
+ * - closed-ended loan origination (ttLOAN_SET) may only succeed when the
+ *   vault phase is Investment
  *
+ * Immutability of VaultKind, SubscriptionDate and RedemptionDate is enforced
+ * by NoModifiedUnmodifiableFields (see InvariantCheck.cpp).
  */
 class ValidVault
 {
@@ -55,6 +65,9 @@ class ValidVault
         Number assetsAvailable = 0;
         Number assetsMaximum = 0;
         Number lossUnrealized = 0;
+        std::optional<std::uint8_t> vaultKind;
+        std::optional<std::uint32_t> subscriptionDate;
+        std::optional<std::uint32_t> redemptionDate;
 
         Vault static make(SLE const&);
     };
@@ -153,6 +166,17 @@ private:
     [[nodiscard]] static bool
     isVaultEmpty(Vault const& vault);
 
+    /**
+     * @brief Invariant check for @c ttLOAN_SET.
+     *
+     * For a closed-ended vault, a loan may only be originated while the vault is in the Investment
+     * phase (strictly past @c SubscriptionDate and before @c RedemptionDate). Open-ended vaults (@c
+     * NoPhase) are unaffected. The complementary maturity bound (final payment strictly precedes @c
+     * RedemptionDate) is enforced by @c ValidLoan.
+     */
+    [[nodiscard]] bool
+    finalizeLoanSet(ReadView const& view, beast::Journal const& j) const;
+
 public:
     // Compute the coarsest scale required to represent all numbers
     [[nodiscard]] static std::int32_t