Invariants: Vault object and MPTokenIssuance for vault shares. More...

#include <VaultInvariant.h>

Collaboration diagram for xrpl::ValidVault:

[legend]

Classes
struct	Vault
struct	Shares
struct	DeltaInfo

Public Member Functions
void	visitEntry (bool, SLE::ConstRef, SLE::ConstRef)
bool	finalize (STTx const &, TER const, XRPAmount const, ReadView const &, beast::Journal const &)

Static Public Member Functions
static std::int32_t	computeCoarsestScale (std::vector< DeltaInfo > const &numbers)

Private Member Functions
std::int32_t	computeVaultMinScale (DeltaInfo const &vaultDelta, Rules const &rules) const
	Compute the minimum STAmount scale for rounding invariant calculations.
std::optional< DeltaInfo >	deltaAssets (AccountID const &id) const
	Return the vault-asset balance-change delta for an account.
std::optional< DeltaInfo >	deltaAssetsForParty (ReadView const &view, AccountID const &id, STTx const &tx, XRPAmount fee, bool fix340Enabled) const
	Return the vault-asset delta for a party inspected as a withdrawal/deposit counterparty, adjusted for the fee.
std::optional< DeltaInfo >	deltaShares (AccountID const &id) const
	Return the vault-share balance-change delta for an account.
bool	finalizeLoanSet (ReadView const &view, beast::Journal const &j) const
	Invariant check for `ttLOAN_SET`.

Static Private Member Functions
static std::optional< AccountID >	feePayerAccountRoot (ReadView const &view, STTx const &tx)
	Return the AccountRoot whose XRP balance actually absorbed a transaction's fee, if any.
static bool	isVaultEmpty (Vault const &vault)
	Check whether a vault holds no assets.

Private Attributes
std::vector< Vault >	afterVault_
std::vector< Shares >	afterMPTs_
std::vector< Vault >	beforeVault_
std::vector< Shares >	beforeMPTs_
std::unordered_map< UInt256, DeltaInfo >	deltas_

Static Private Attributes
static constexpr Number	kZero {}

Detailed Description

Invariants: Vault object and MPTokenIssuance for vault shares.

vault deleted and vault created is empty
vault created must be linked to pseudo-account for shares and assets
vault must have MPTokenIssuance for shares
vault without shares outstanding must have no shares
loss unrealized does not exceed the difference between assets total and assets available
assets available do not exceed assets total
vault deposit increases assets and share issuance, and adds to: total assets, assets available, shares outstanding
vault withdrawal and clawback reduce assets and share issuance, and subtracts from: total assets, assets available, shares outstanding
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). From featureLendingProtocolV1_1 onwards, immutability of the vault's Asset, pseudo-account and ShareMPTID is likewise enforced by NoModifiedUnmodifiableFields; prior to that amendment it is checked here.

Definition at line 56 of file VaultInvariant.h.

Member Function Documentation

◆ computeVaultMinScale()

std::int32_t xrpl::ValidVault::computeVaultMinScale	(	DeltaInfo const &	vaultDelta,
		Rules const &	rules ) const

nodiscardprivate

Compute the minimum STAmount scale for rounding invariant calculations.

Post-amendment (fixCleanup3_2_0) this is simply the posterior assetsTotal scale. Pre-amendment it is the coarsest scale across vaultDelta and both asset-field deltas.

Parameters

vaultDelta	Delta of the vault's asset balance for this transaction.
rules	Active ledger rules (used to check the amendment).

Returns: The minimum scale to apply when rounding vault-related amounts.

Definition at line 386 of file VaultInvariant.cpp.

◆ deltaAssets()

std::optional< ValidVault::DeltaInfo > xrpl::ValidVault::deltaAssets ( AccountID const & id ) const

nodiscardprivate

Return the vault-asset balance-change delta for an account.

Looks up the ledger-entry delta recorded during visitEntry for the account entry (XRP), trust line (IOU), or MPToken (MPT) that corresponds to the vault asset held by id.

Parameters

id	Account whose asset delta is requested.

Returns: The delta, or std::nullopt if the entry was not touched.

Definition at line 208 of file VaultInvariant.cpp.

◆ feePayerAccountRoot()

std::optional< AccountID > xrpl::ValidVault::feePayerAccountRoot	(	ReadView const &	view,
		STTx const &	tx )

staticnodiscardprivate

Return the AccountRoot whose XRP balance actually absorbed a transaction's fee, if any.

Mirrors Transactor::getFeePayer, but resolves to std::nullopt for a pre-funded sponsorship: that fee is drawn from the ltSponsorship object's sfFeeAmount, never from the sponsor's own AccountRoot, so there is no balance to add back there.

Parameters

view	Read-only view of the ledger after the transaction.
tx	The transaction being applied.

Returns: The fee-paying AccountRoot's id, or std::nullopt when the fee was not drawn from any AccountRoot balance.

Definition at line 240 of file VaultInvariant.cpp.

◆ deltaAssetsForParty()

std::optional< ValidVault::DeltaInfo > xrpl::ValidVault::deltaAssetsForParty	(	ReadView const &	view,
		AccountID const &	id,
		STTx const &	tx,
		XRPAmount	fee,
		bool	fix340Enabled ) const

nodiscardprivate

Return the vault-asset delta for a party inspected as a withdrawal/deposit counterparty, adjusted for the fee.

Calls deltaAssets for id and, for XRP transactions, adds the consumed fee back only when id is the AccountRoot that actually paid it (per feePayerAccountRoot) – so the invariant sees the net asset movement rather than a fee-reduced balance change, regardless of whether id is the sender, a distinct destination, a delegate, or a co-signed fee sponsor. Post-fixCleanup3_4_0, any resulting economically-zero delta is always normalized to absence.

Pre-fixCleanup3_4_0 this replicates the legacy behaviour exactly: only tx[sfAccount] could ever receive a fee correction (and only when it was itself, per STTx::getFeePayerID, the fee payer). After that sender-only correction a zero delta is collapsed to absence; if the correction does not apply, a present-zero delta is kept as-is.

Parameters

view	Read-only view of the ledger after the transaction.
id	Account being inspected as sender or destination.
tx	The transaction being applied.
fee	Fee charged by this transaction.
fix340Enabled	Whether `fixCleanup3_4_0` is enabled, as already determined once by `finalize`.

Returns: The fee-adjusted delta, or std::nullopt if the net delta is zero (always post-amendment; pre-amendment only after the sender-only fee correction) or the entry was not touched.

Definition at line 249 of file VaultInvariant.cpp.

◆ deltaShares()

std::optional< ValidVault::DeltaInfo > xrpl::ValidVault::deltaShares ( AccountID const & id ) const

nodiscardprivate

Return the vault-share balance-change delta for an account.

For the vault's pseudo-account the MPTokenIssuance outstanding-amount delta is returned; for all other accounts the MPToken delta is returned.

Parameters

id	Account whose share delta is requested.

Returns: The delta, or std::nullopt if the entry was not touched.

Definition at line 297 of file VaultInvariant.cpp.

◆ isVaultEmpty()

bool xrpl::ValidVault::isVaultEmpty ( Vault const & vault )

staticnodiscardprivate

Check whether a vault holds no assets.

Parameters

vault Snapshot of the vault to test.

Returns: true when both assetsAvailable and assetsTotal are zero.

Definition at line 310 of file VaultInvariant.cpp.

◆ finalizeLoanSet()

bool xrpl::ValidVault::finalizeLoanSet	(	ReadView const &	view,
		beast::Journal const &	j ) const

nodiscardprivate

Invariant check for ttLOAN_SET.

For a closed-ended vault, a loan may only be originated while the vault is in the Investment phase (strictly past SubscriptionDate and before RedemptionDate). Open-ended vaults (NoPhase) are unaffected. The complementary maturity bound (final payment precedes RedemptionDate by at least kLoanRedemptionBuffer) is enforced by ValidLoan.

Definition at line 316 of file VaultInvariant.cpp.

◆ computeCoarsestScale()

std::int32_t xrpl::ValidVault::computeCoarsestScale ( std::vector< DeltaInfo > const & numbers )

staticnodiscard

Definition at line 1375 of file VaultInvariant.cpp.

◆ visitEntry()

void xrpl::ValidVault::visitEntry	(	bool	isDelete,
		SLE::ConstRef	before,
		SLE::ConstRef	after )

Definition at line 87 of file VaultInvariant.cpp.

◆ finalize()

bool xrpl::ValidVault::finalize	(	STTx const &	tx,
		TER const	ret,
		XRPAmount const	fee,
		ReadView const &	view,
		beast::Journal const &	j )

Definition at line 412 of file VaultInvariant.cpp.

Member Data Documentation

◆ kZero

Number xrpl::ValidVault::kZero {}

staticconstexprprivate

Definition at line 58 of file VaultInvariant.h.

◆ afterVault_

std::vector<Vault> xrpl::ValidVault::afterVault_

private

Definition at line 99 of file VaultInvariant.h.

◆ afterMPTs_

std::vector<Shares> xrpl::ValidVault::afterMPTs_

private

Definition at line 100 of file VaultInvariant.h.

◆ beforeVault_

std::vector<Vault> xrpl::ValidVault::beforeVault_

private

Definition at line 101 of file VaultInvariant.h.

◆ beforeMPTs_

std::vector<Shares> xrpl::ValidVault::beforeMPTs_

private

Definition at line 102 of file VaultInvariant.h.

◆ deltas_

std::unordered_map<UInt256, DeltaInfo> xrpl::ValidVault::deltas_

private

Definition at line 103 of file VaultInvariant.h.

Classes

Public Member Functions

Static Public Member Functions

Private Member Functions

Static Private Member Functions

Private Attributes

Static Private Attributes

Detailed Description

Member Function Documentation

◆ computeVaultMinScale()

◆ deltaAssets()

◆ feePayerAccountRoot()

◆ deltaAssetsForParty()

◆ deltaShares()

◆ isVaultEmpty()

◆ finalizeLoanSet()

◆ computeCoarsestScale()

◆ visitEntry()

◆ finalize()

Member Data Documentation

◆ kZero

◆ afterVault_

◆ afterMPTs_

◆ beforeVault_

◆ beforeMPTs_

◆ deltas_