Merge remote-tracking branch 'origin/develop' into tapanito/vault-donation

# Conflicts:
#	include/xrpl/ledger/helpers/VaultHelpers.h
#	src/libxrpl/ledger/helpers/VaultHelpers.cpp
This commit is contained in:
Vito
2026-08-13 22:25:43 +02:00
73 changed files with 3162 additions and 480 deletions

View File

@@ -1,6 +1,6 @@
#pragma once
#include <boost/filesystem.hpp>
#include <filesystem>
namespace xrpl {
@@ -13,6 +13,6 @@ namespace xrpl {
* @throws runtime_error
*/
void
extractTarLz4(boost::filesystem::path const& src, boost::filesystem::path const& dst);
extractTarLz4(std::filesystem::path const& src, std::filesystem::path const& dst);
} // namespace xrpl

View File

@@ -1,24 +1,79 @@
#pragma once
#include <boost/filesystem.hpp>
#include <boost/system/error_code.hpp>
#include <cstddef>
#include <filesystem>
#include <optional>
#include <string>
#include <system_error>
namespace xrpl {
std::string
getFileContents(
boost::system::error_code& ec,
boost::filesystem::path const& sourcePath,
std::error_code& ec,
std::filesystem::path const& sourcePath,
std::optional<std::size_t> maxSize = std::nullopt);
void
writeFileContents(
boost::system::error_code& ec,
boost::filesystem::path const& destPath,
std::error_code& ec,
std::filesystem::path const& destPath,
std::string const& contents);
/**
* Generate a unique, non-existing path under @p base whose filename starts with
* @p prefix and ends with a random hex suffix.
*
* Attempts up to @p maxAttempts paths. Throws `std::runtime_error` if a unique
* path cannot be found or if the filesystem returns an error while checking for
* existence.
*/
std::filesystem::path
uniqueRandomPath(
std::filesystem::path const& base,
std::string const& prefix = "",
std::size_t maxAttempts = 100);
/**
* RAII temporary directory.
*
* The directory and all its contents are deleted when
* the instance of `TempDir` is destroyed.
*/
class TempDir
{
std::filesystem::path path_;
public:
#if !GENERATING_DOCS
TempDir(TempDir const&) = delete;
TempDir&
operator=(TempDir const&) = delete;
#endif
/**
* Construct a temporary directory.
*/
TempDir();
/**
* Destroy a temporary directory.
*/
~TempDir();
/**
* Get the native path for the temporary directory.
*/
[[nodiscard]] std::string
path() const;
/**
* Get the native path for a file.
*
* The file does not need to exist.
*/
[[nodiscard]] std::string
file(std::string const& name) const;
};
} // namespace xrpl

View File

@@ -3,8 +3,8 @@
#include <xrpl/beast/utility/Journal.h>
#include <boost/beast/core/string.hpp>
#include <boost/filesystem.hpp>
#include <filesystem>
#include <fstream>
#include <map>
#include <memory>
@@ -84,7 +84,7 @@ private:
* @return `true` if the file was opened.
*/
bool
open(boost::filesystem::path const& path);
open(std::filesystem::path const& path);
/**
* Close and re-open the system file associated with the log
@@ -133,7 +133,7 @@ private:
private:
std::unique_ptr<std::ofstream> stream_;
boost::filesystem::path path_;
std::filesystem::path path_;
};
std::mutex mutable mutex_;
@@ -152,7 +152,7 @@ public:
virtual ~Logs() = default;
bool
open(boost::filesystem::path const& pathToLogFile);
open(std::filesystem::path const& pathToLogFile);
beast::Journal::Sink&
get(std::string const& name);

View File

@@ -6,10 +6,10 @@
#include <xrpl/beast/unit_test/runner.h>
#include <boost/filesystem.hpp>
#include <boost/throw_exception.hpp>
#include <exception>
#include <filesystem>
#include <memory>
#include <ostream>
#include <sstream>
@@ -26,7 +26,7 @@ makeReason(String const& reason, char const* file, int line)
std::string s(reason);
if (!s.empty())
s.append(": ");
namespace fs = boost::filesystem;
namespace fs = std::filesystem;
s.append(fs::path{file}.filename().string());
s.append("(");
s.append(std::to_string(line));

View File

@@ -1,71 +0,0 @@
#pragma once
#include <boost/filesystem.hpp>
#include <string>
namespace beast {
/**
* RAII temporary directory.
*
* The directory and all its contents are deleted when
* the instance of `temp_dir` is destroyed.
*/
class TempDir
{
boost::filesystem::path path_;
public:
#if !GENERATING_DOCS
TempDir(TempDir const&) = delete;
TempDir&
operator=(TempDir const&) = delete;
#endif
/**
* Construct a temporary directory.
*/
TempDir()
{
auto const dir = boost::filesystem::temp_directory_path();
do
{
path_ = dir / boost::filesystem::unique_path();
} while (boost::filesystem::exists(path_));
boost::filesystem::create_directory(path_);
}
/**
* Destroy a temporary directory.
*/
~TempDir()
{
// use non-throwing calls in the destructor
boost::system::error_code ec;
boost::filesystem::remove_all(path_, ec);
// TODO: warn/notify if ec set ?
}
/**
* Get the native path for the temporary directory
*/
[[nodiscard]] std::string
path() const
{
return path_.string();
}
/**
* Get the native path for the a file.
*
* The file does not need to exist.
*/
[[nodiscard]] std::string
file(std::string const& name) const
{
return (path_ / name).string();
}
};
} // namespace beast

View File

@@ -4,10 +4,9 @@
#include <xrpl/core/Job.h>
#include <xrpl/json/json_value.h>
#include <boost/filesystem.hpp>
#include <chrono>
#include <cstdint>
#include <filesystem>
#include <functional>
#include <memory>
#include <string>
@@ -44,7 +43,7 @@ public:
*/
struct Setup
{
boost::filesystem::path perfLog;
std::filesystem::path perfLog;
// log_interval is in milliseconds to support faster testing.
milliseconds logInterval{seconds(1)};
};
@@ -149,7 +148,7 @@ public:
};
PerfLog::Setup
setupPerfLog(Section const& section, boost::filesystem::path const& configDir);
setupPerfLog(Section const& section, std::filesystem::path const& configDir);
std::unique_ptr<PerfLog>
makePerfLog(

View File

@@ -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

View File

@@ -7,10 +7,13 @@
#include <xrpl/protocol/STLedgerEntry.h>
#include <xrpl/protocol/STTx.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
@@ -127,4 +130,82 @@ getVaultVersion(SLE::const_ref vault);
[[nodiscard]] bool
isVaultDonate(Rules const& rules, STTx const& tx);
/**
* 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

View File

@@ -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

View File

@@ -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)
}))

View File

@@ -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)

View File

@@ -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. */

View File

@@ -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.

View File

@@ -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.

View File

@@ -6,13 +6,12 @@
#include <xrpl/core/StartUpType.h>
#include <xrpl/rdb/SociDB.h>
#include <boost/filesystem/path.hpp>
#include <soci/statement.h>
#include <array>
#include <cstddef>
#include <cstdint>
#include <filesystem>
#include <functional>
#include <memory>
#include <mutex>
@@ -80,7 +79,7 @@ public:
StartUpType startUp = StartUpType::Normal;
bool standAlone = false;
boost::filesystem::path dataDir;
std::filesystem::path dataDir;
// Indicates whether or not to return the `globalPragma`
// from commonPragma()
bool useGlobalPragma = false;
@@ -143,7 +142,7 @@ public:
template <std::size_t N, std::size_t M>
DatabaseCon(
boost::filesystem::path const& dataDir,
std::filesystem::path const& dataDir,
std::string const& dbName,
std::array<std::string, N> const& pragma,
std::array<char const*, M> const& initSQL,
@@ -155,7 +154,7 @@ public:
// Use this constructor to setup checkpointing
template <std::size_t N, std::size_t M>
DatabaseCon(
boost::filesystem::path const& dataDir,
std::filesystem::path const& dataDir,
std::string const& dbName,
std::array<std::string, N> const& pragma,
std::array<char const*, M> const& initSQL,
@@ -190,7 +189,7 @@ private:
template <std::size_t N, std::size_t M>
DatabaseCon(
boost::filesystem::path const& pPath,
std::filesystem::path const& pPath,
std::vector<std::string> const* commonPragma,
std::array<std::string, N> const& pragma,
std::array<char const*, M> const& initSQL,

View File

@@ -14,7 +14,6 @@
#include <xrpl/protocol/TxMeta.h>
#include <xrpl/protocol/TxSearched.h>
#include <boost/filesystem.hpp>
#include <boost/variant.hpp>
#include <concepts>

View File

@@ -4,8 +4,6 @@
#include <xrpl/rdb/DatabaseCon.h>
#include <xrpl/rdb/SociDB.h>
#include <boost/filesystem.hpp>
#include <string>
namespace xrpl {

View File

@@ -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

View File

@@ -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