feat: Propagate underlying MPT flags to vault shares (#7077)

include/xrpl/ledger/View.h

@@ -57,7 +57,7 @@ isVaultPseudoAccountFrozen(
     ReadView const& view,
     AccountID const& account,
     MPTIssue const& mptShare,
-    int depth);
+    std::uint8_t depth);
 
 [[nodiscard]] bool
 isLPTokenFrozen(

include/xrpl/ledger/helpers/MPTokenHelpers.h

@@ -27,14 +27,18 @@ isGlobalFrozen(ReadView const& view, MPTIssue const& mptIssue);
 isIndividualFrozen(ReadView const& view, AccountID const& account, MPTIssue const& mptIssue);
 
 [[nodiscard]] bool
-isFrozen(ReadView const& view, AccountID const& account, MPTIssue const& mptIssue, int depth = 0);
+isFrozen(
+    ReadView const& view,
+    AccountID const& account,
+    MPTIssue const& mptIssue,
+    std::uint8_t depth = 0);
 
 [[nodiscard]] bool
 isAnyFrozen(
     ReadView const& view,
     std::initializer_list<AccountID> const& accounts,
     MPTIssue const& mptIssue,
-    int depth = 0);
+    std::uint8_t depth = 0);
 
 //------------------------------------------------------------------------------
 //
@@ -88,7 +92,7 @@ requireAuth(
     MPTIssue const& mptIssue,
     AccountID const& account,
     AuthType authType = AuthType::Legacy,
-    int depth = 0);
+    std::uint8_t depth = 0);
 
 /** Enforce account has MPToken to match its authorization.
  *
@@ -104,22 +108,68 @@ enforceMPTokenAuthorization(
     XRPAmount const& priorBalance,
     beast::Journal j);
 
-/** Check if the destination account is allowed
- *  to receive MPT. Return tecNO_AUTH if it doesn't
- *  and tesSUCCESS otherwise.
+/** Resolve the underlying asset of a vault share.
+ *
+ *  Reads sfReferenceHolding from @p sleShareIssuance to determine which
+ *  asset the vault wraps. @p sleHolding must be the SLE that
+ *  sfReferenceHolding points to — either an ltMPTOKEN (returns its
+ *  MPTIssue) or an ltRIPPLE_STATE (returns its low/high Issue).
+ *
+ *  @pre Both SLEs must exist and @p sleHolding must be of type ltMPTOKEN
+ *       or ltRIPPLE_STATE. Passing any other type is undefined behaviour.
+ *  @param sleShareIssuance  MPTokenIssuance SLE for the vault share token.
+ *  @param sleHolding        SLE referenced by sfReferenceHolding.
+ *  @return The underlying Asset (MPTIssue or Issue).
+ */
+[[nodiscard]] Asset
+assetOfHolding(SLE const& sleShareIssuance, SLE const& sleHolding);
+
+/** Check whether @p to may receive the given MPT from @p from.
+ *
+ *  The check passes when any of the following is true:
+ *  - @p waive is WaiveMPTCanTransfer::Yes (recovery-path exemption), or
+ *  - @p from or @p to is the issuer, or
+ *  - lsfMPTCanTransfer is set on the MPTokenIssuance.
+ *
+ *  For vault shares (MPTokenIssuances that carry sfReferenceHolding) the
+ *  check recurses into the underlying asset's transferability. This
+ *  recursion is defensive; vault-of-vault-shares is rejected at vault
+ *  creation, so in practice depth never exceeds 1.
+ *
+ *  @param view      Ledger state to read from.
+ *  @param mptIssue  The MPT issuance being transferred.
+ *  @param from      Sending account.
+ *  @param to        Receiving account.
+ *  @param waive     WaiveMPTCanTransfer::Yes skips the lsfMPTCanTransfer
+ *                   check. Use for recovery paths (e.g. unwinding SAV or
+ *                   Lending Protocol positions after an issuer revokes
+ *                   transferability).
+ *  @param depth     Recursion depth; bounded at kMaxAssetCheckDepth.
+ *  @return tesSUCCESS if the transfer is allowed, tecNO_AUTH otherwise.
  */
 [[nodiscard]] TER
 canTransfer(
     ReadView const& view,
     MPTIssue const& mptIssue,
     AccountID const& from,
-    AccountID const& to);
+    AccountID const& to,
+    WaiveMPTCanTransfer waive = WaiveMPTCanTransfer::No,
+    std::uint8_t depth = 0);
 
-/** Check if Asset can be traded on DEX. return tecNO_PERMISSION
- * if it doesn't and tesSUCCESS otherwise.
+/** Check whether @p asset may be traded on the DEX.
+ *
+ *  For IOU assets the check delegates to the existing offer/AMM freeze
+ *  logic. For MPT assets it checks lsfMPTCanTrade on the MPTokenIssuance.
+ *  Vault shares recurse into the underlying asset's tradability via
+ *  sfReferenceHolding; depth is bounded at kMaxAssetCheckDepth.
+ *
+ *  @param view   Ledger state to read from.
+ *  @param asset  The asset to check.
+ *  @param depth  Recursion depth; bounded at kMaxAssetCheckDepth.
+ *  @return tesSUCCESS if trading is allowed, tecNO_PERMISSION otherwise.
  */
 [[nodiscard]] TER
-canTrade(ReadView const& view, Asset const& asset);
+canTrade(ReadView const& view, Asset const& asset, std::uint8_t depth = 0);
 
 //------------------------------------------------------------------------------
 //

include/xrpl/ledger/helpers/RippleStateHelpers.h

@@ -93,7 +93,7 @@ isFrozen(ReadView const& view, AccountID const& account, Issue const& issue)
 // Overload with depth parameter for uniformity with MPTIssue version.
 // The depth parameter is ignored for IOUs since they don't have vault recursion.
 [[nodiscard]] inline bool
-isFrozen(ReadView const& view, AccountID const& account, Issue const& issue, int /*depth*/)
+isFrozen(ReadView const& view, AccountID const& account, Issue const& issue, std::uint8_t /*depth*/)
 {
     return isFrozen(view, account, issue);
 }
@@ -110,7 +110,7 @@ isDeepFrozen(
     ReadView const& view,
     AccountID const& account,
     Issue const& issue,
-    int = 0 /*ignored*/)
+    std::uint8_t = 0 /*ignored*/)
 {
     return isDeepFrozen(view, account, issue.currency, issue.account);
 }

include/xrpl/ledger/helpers/TokenHelpers.h

@@ -34,6 +34,15 @@ enum class WaiveTransferFee : bool { No = false, Yes };
 /** Controls whether accountSend is allowed to overflow OutstandingAmount **/
 enum class AllowMPTOverflow : bool { No = false, Yes };
 
+/** Controls whether canTransfer enforces lsfMPTCanTransfer on MPTs.
+ *
+ *  Default is No (enforce). Use Yes at call sites that must remain available
+ *  even when an MPT issuer has cleared lsfMPTCanTransfer - for example,
+ *  unwinding existing positions in SAV or the Lending Protocol. Has no
+ *  effect on the IOU branch of canTransfer.
+ */
+enum class WaiveMPTCanTransfer : bool { No = false, Yes };
+
 /* Check if MPToken (for MPT) or trust line (for IOU) exists:
  * - StrongAuth - before checking if authorization is required
  * - WeakAuth
@@ -63,7 +72,11 @@ isIndividualFrozen(ReadView const& view, AccountID const& account, Asset const&
  *   purely defensive, as we currently do not allow such vaults to be created.
  */
 [[nodiscard]] bool
-isFrozen(ReadView const& view, AccountID const& account, Asset const& asset, int depth = 0);
+isFrozen(
+    ReadView const& view,
+    AccountID const& account,
+    Asset const& asset,
+    std::uint8_t depth = 0);
 
 [[nodiscard]] TER
 checkFrozen(ReadView const& view, AccountID const& account, Issue const& issue);
@@ -85,14 +98,14 @@ isAnyFrozen(
     ReadView const& view,
     std::initializer_list<AccountID> const& accounts,
     Asset const& asset,
-    int depth = 0);
+    std::uint8_t depth = 0);
 
 [[nodiscard]] bool
 isDeepFrozen(
     ReadView const& view,
     AccountID const& account,
     MPTIssue const& mptIssue,
-    int depth = 0);
+    std::uint8_t depth = 0);
 
 /**
  *   isFrozen check is recursive for MPT shares in a vault, descending to
@@ -100,7 +113,11 @@ isDeepFrozen(
  *   purely defensive, as we currently do not allow such vaults to be created.
  */
 [[nodiscard]] bool
-isDeepFrozen(ReadView const& view, AccountID const& account, Asset const& asset, int depth = 0);
+isDeepFrozen(
+    ReadView const& view,
+    AccountID const& account,
+    Asset const& asset,
+    std::uint8_t depth = 0);
 
 [[nodiscard]] TER
 checkDeepFrozen(ReadView const& view, AccountID const& account, MPTIssue const& mptIssue);
@@ -234,7 +251,13 @@ requireAuth(
     AuthType authType = AuthType::Legacy);
 
 [[nodiscard]] TER
-canTransfer(ReadView const& view, Asset const& asset, AccountID const& from, AccountID const& to);
+canTransfer(
+    ReadView const& view,
+    Asset const& asset,
+    AccountID const& from,
+    AccountID const& to,
+    WaiveMPTCanTransfer waive = WaiveMPTCanTransfer::No,
+    std::uint8_t depth = 0);
 
 //------------------------------------------------------------------------------
 //

include/xrpl/protocol/detail/ledger_entries.macro

@@ -400,6 +400,7 @@ LEDGER_ENTRY(ltMPTOKEN_ISSUANCE, 0x007e, MPTokenIssuance, mpt_issuance, ({
     {sfPreviousTxnLgrSeq,        SoeRequired},
     {sfDomainID,                 SoeOptional},
     {sfMutableFlags,             SoeDefault},
+    {sfReferenceHolding,         SoeOptional},
 }))
 
 /** A ledger object which tracks MPToken

include/xrpl/protocol/detail/sfields.macro

@@ -205,6 +205,7 @@ TYPED_SFIELD(sfParentBatchID,            UINT256,   36)
 TYPED_SFIELD(sfLoanBrokerID,             UINT256,   37,
     SField::kSmdPseudoAccount | SField::kSmdDefault)
 TYPED_SFIELD(sfLoanID,                   UINT256,   38)
+TYPED_SFIELD(sfReferenceHolding,         UINT256,   39)
 
 // number (common)
 TYPED_SFIELD(sfNumber,                   NUMBER,     1)

include/xrpl/protocol_autogen/ledger_entries/MPTokenIssuance.h

@@ -278,6 +278,30 @@ public:
     {
         return this->sle_->isFieldPresent(sfMutableFlags);
     }
+
+    /**
+     * @brief Get sfReferenceHolding (SoeOptional)
+     * @return The field value, or std::nullopt if not present.
+     */
+    [[nodiscard]]
+    protocol_autogen::Optional<SF_UINT256::type::value_type>
+    getReferenceHolding() const
+    {
+        if (hasReferenceHolding())
+            return this->sle_->at(sfReferenceHolding);
+        return std::nullopt;
+    }
+
+    /**
+     * @brief Check if sfReferenceHolding is present.
+     * @return True if the field is present, false otherwise.
+     */
+    [[nodiscard]]
+    bool
+    hasReferenceHolding() const
+    {
+        return this->sle_->isFieldPresent(sfReferenceHolding);
+    }
 };
 
 /**
@@ -469,6 +493,17 @@ public:
         return *this;
     }
 
+    /**
+     * @brief Set sfReferenceHolding (SoeOptional)
+     * @return Reference to this builder for method chaining.
+     */
+    MPTokenIssuanceBuilder&
+    setReferenceHolding(std::decay_t<typename SF_UINT256::type::value_type> const& value)
+    {
+        object_[sfReferenceHolding] = value;
+        return *this;
+    }
+
     /**
      * @brief Build and return the completed MPTokenIssuance wrapper.
      * @param index The ledger entry index.

include/xrpl/tx/invariants/MPTInvariant.h

@@ -2,6 +2,7 @@
 
 #include <xrpl/beast/utility/Journal.h>
 #include <xrpl/ledger/ReadView.h>
+#include <xrpl/protocol/STLedgerEntry.h>
 #include <xrpl/protocol/STTx.h>
 #include <xrpl/protocol/TER.h>
 
@@ -22,6 +23,18 @@ class ValidMPTIssuance
     // MPToken by an issuer
     bool mptCreatedByIssuer_ = false;
 
+    /// sfReferenceHolding is intended to be set exactly once at vault
+    /// creation and immutable thereafter; true when that rule was violated.
+    bool referenceHoldingSetOnCreate_ = false;
+
+    /// True when sfReferenceHolding was mutated on an existing MPTokenIssuance.
+    bool referenceHoldingMutated_ = false;
+
+    /// MPTokens and RippleStates deleted during apply. finalize() checks each
+    /// holder's AccountRoot to detect vault pseudo-account holdings deleted
+    /// outside VaultDelete. All these checks are gated on fixCleanup3_2_0.
+    std::vector<std::shared_ptr<SLE const>> deletedHoldings_;
+
 public:
     void
     visitEntry(bool, std::shared_ptr<SLE const> const&, std::shared_ptr<SLE const> const&);

include/xrpl/tx/transactors/token/MPTokenIssuanceCreate.h

@@ -6,23 +6,28 @@
 
 namespace xrpl {
 
+// NOLINTBEGIN(readability-redundant-member-init)
 struct MPTCreateArgs
 {
     std::optional<XRPAmount> priorBalance;
     AccountID const& account;
     std::uint32_t sequence = 0;
     std::uint32_t flags = 0;
-    std::optional<std::uint64_t> maxAmount =
-        std::nullopt;  // NOLINT(readability-redundant-member-init)
-    std::optional<std::uint8_t> assetScale =
-        std::nullopt;  // NOLINT(readability-redundant-member-init)
-    std::optional<std::uint16_t> transferFee =
-        std::nullopt;  // NOLINT(readability-redundant-member-init)
+    std::optional<std::uint64_t> maxAmount = std::nullopt;
+    std::optional<std::uint8_t> assetScale = std::nullopt;
+    std::optional<std::uint16_t> transferFee = std::nullopt;
     std::optional<Slice> const& metadata{};
-    std::optional<uint256> domainId = std::nullopt;  // NOLINT(readability-redundant-member-init)
-    std::optional<std::uint32_t> mutableFlags =
-        std::nullopt;  // NOLINT(readability-redundant-member-init)
+    std::optional<uint256> domainId = std::nullopt;
+    std::optional<std::uint32_t> mutableFlags = std::nullopt;
+    // Set only by callers that issue an MPT representing a wrapped asset
+    // (e.g. VaultCreate's share token). The keylet must point to an
+    // existing MPToken or RippleState owned by `account`. Surfaces on
+    // the resulting MPTokenIssuance via the optional sfReferenceHolding
+    // field. Used by readers (canTransfer, canTrade, freezing) to
+    // inherit the underlying asset's transferability.
+    std::optional<uint256> referenceHolding = std::nullopt;
 };
+// NOLINTEND(readability-redundant-member-init)
 
 class MPTokenIssuanceCreate : public Transactor
 {