ARCHIVE/rippled
1
0
Fork 0
mirror of https://github.com/XRPLF/rippled.git synced 2026-10-10 05:38:10 +00:00
Code Issues Packages Projects Releases Wiki Activity

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

Browse Source 
# Conflicts:
#	src/libxrpl/ledger/helpers/VaultHelpers.cpp
#	src/libxrpl/tx/transactors/vault/VaultWithdraw.cpp
This commit is contained in:
Vito
2026-08-20 11:00:36 +02:00
parent ec8a9cdbf8 da57183e0c
commit 0db000bc97
66 changed files with 2558 additions and 297 deletions
Download Patch File Download Diff File Expand all files Collapse all files

38
include/xrpl/ledger/helpers/LendingHelpers.h
View File

@@ -7,6 +7,7 @@
#include <xrpl/beast/utility/instrumentation.h>
#include <xrpl/ledger/ApplyView.h>
#include <xrpl/ledger/ReadView.h>
#include <xrpl/protocol/AccountID.h>
#include <xrpl/protocol/Asset.h>
#include <xrpl/protocol/LedgerFormats.h> // IWYU pragma: keep
#include <xrpl/protocol/Protocol.h>
@@ -21,6 +22,7 @@
#include <cstdint>
#include <expected>
#include <optional>
#include <string_view>
#include <utility>
@@ -58,6 +60,42 @@ canApplyToBrokerCover(
bool
checkLendingProtocolDependencies(Rules const& rules, STTx const& tx);
/**
* The accounts and asset that LoanManage::defaultLoan's fixCleanup3_4_0
* freeze/lock exemption applies to.
*
* `defaultLoan` moves funds from the LoanBroker pseudo-account to the Vault
* pseudo-account via `accountSend`. Since neither is the vault asset's
* issuer, this is a third-party transfer that transits through the issuer in
* two hops (broker -> issuer, issuer -> vault; see
* `directSendNoLimitIOU`/`directSendNoLimitMPT`), so the exemption must cover
* both the issuer/broker and issuer/vault pairs, not a direct broker/vault
* pair. `asset` scopes it further to the vault's own currency/MPT issuance,
* so an unrelated one the same accounts happen to hold is still protected.
*/
struct LoanDefaultFreezeExemptAccounts
{
AccountID issuer;
AccountID broker;
AccountID vault;
Asset asset;
};
/**
* Resolves the accounts and asset a LoanManage default transaction is
* exempt from freeze/lock for.
*
* @param view Ledger view used to resolve the Loan -> LoanBroker -> Vault
* chain.
* @param tx The transaction under invariant review.
* @return The exempt accounts and asset if `tx` is a `ttLOAN_MANAGE`
* transaction with the `tfLoanDefault` flag set, `fixCleanup3_4_0` is
* enabled, and the loan/broker/vault objects it references can all be
* resolved; `std::nullopt` otherwise.
*/
[[nodiscard]] std::optional<LoanDefaultFreezeExemptAccounts>
getLoanDefaultFreezeExemptAccounts(ReadView const& view, STTx const& tx);
static constexpr std::uint32_t kSecondsInYear = 365 * 24 * 60 * 60;
Number

33
include/xrpl/ledger/helpers/VaultHelpers.h
View File

@@ -3,6 +3,7 @@
#include <xrpl/basics/Number.h>
#include <xrpl/ledger/ReadView.h>
#include <xrpl/protocol/AccountID.h>
#include <xrpl/protocol/Asset.h>
#include <xrpl/protocol/Protocol.h>
#include <xrpl/protocol/STAmount.h>
#include <xrpl/protocol/STLedgerEntry.h>
@@ -77,6 +78,38 @@ enum class TruncateShares : bool { No = false, Yes = true };
*/
enum class WaiveUnrealizedLoss : bool { No = false, Yes = true };
/**
* Returns the effective total of assets backing outstanding shares for the
* purposes of a withdrawal, i.e. sfAssetsTotal, discounted by sfLossUnrealized
* unless waived. This is the numerator used by both withdraw conversion
* helpers (assetsToSharesWithdraw and sharesToAssetsWithdraw) to compute the
* share/asset exchange rate.
*
* @param vault The vault SLE.
* @param waive Whether to waive (i.e. not subtract) the vault's unrealized
* loss.
*/
[[nodiscard]] Number
assetsTotalForWithdrawal(SLE::const_ref vault, WaiveUnrealizedLoss waive);
/**
* Returns whether debiting `amount` from `total` — the current value of a
* vault's sfAssetsTotal or sfAssetsAvailable field — would canonicalize back
* to the exact same STAmount value it started at. This happens when a
* genuinely non-zero debit is dust relative to a `total` large enough to
* exceed STAmount's significant-digit precision: the shares still move, but
* the stored total doesn't change, which otherwise trips the ValidVault
* invariant after the fact instead of failing cleanly upfront.
*
* @param asset The vault's underlying asset, used to canonicalize both sides
* the same way the ledger will when the field is stored.
* @param total The field's current value.
* @param amount The amount to debit. A value of zero always returns false;
* that case is rejected separately and unconditionally.
*/
[[nodiscard]] bool
debitIsNonZeroDust(Asset const& asset, Number const& total, Number const& amount);
/**
* 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

18
include/xrpl/tx/ApplyContext.h
View File

@@ -17,7 +17,6 @@
#include <cstddef>
#include <functional>
#include <optional>
#include <utility>
namespace xrpl {
@@ -130,16 +129,6 @@ public:
view_->rawDestroyXRP(fee);
}
/**
* Applies all invariant checkers one by one.
*
* @param result the result generated by processing this transaction.
* @param fee the fee charged for this transaction
* @return the result code that should be returned for this transaction.
*/
TER
checkInvariants(TER const result, XRPAmount const fee);
ApplyViewContext
getApplyViewContext()
{
@@ -150,13 +139,6 @@ public:
}
private:
static TER
failInvariantCheck(TER const result);
template <std::size_t... Is>
TER
checkInvariantsHelper(TER const result, XRPAmount const fee, std::index_sequence<Is...>);
OpenView& base_;
ApplyFlags flags_;
std::optional<ApplyViewImpl> view_;

79
include/xrpl/tx/Transactor.h
View File

@@ -20,6 +20,7 @@
#include <xrpl/protocol/XRPAmount.h>
#include <xrpl/tx/ApplyContext.h>
#include <xrpl/tx/applySteps.h>
#include <xrpl/tx/invariants/InvariantRunner.h>
#include <cstddef>
#include <cstdint>
@@ -147,7 +148,7 @@ struct FeePayer
FeePayerType type{FeePayerType::Account};
};
class Transactor
class Transactor : public TxInvariantCheck
{
protected:
ApplyContext& ctx_;
@@ -158,7 +159,7 @@ protected:
XRPAmount preFeeBalance_{}; // Balance before fees.
public:
virtual ~Transactor() = default;
~Transactor() override = default;
Transactor(Transactor const&) = delete;
Transactor&
operator=(Transactor const&) = delete;
@@ -183,20 +184,50 @@ public:
return ctx_.view();
}
/**
* Which invariant layers to check.
*
* Full runs the protocol invariants plus the transaction-specific
* check. This is always the scope of the initial pass, even when the
* tentative TER is a tec: a bug or exploit could still mutate ledger
* state, so transaction-specific invariants must run for failed
* transactions too.
*
* ProtocolOnly runs only the protocol invariants and is used
* exclusively for the second invariant pass that follows a
* fee-claim reset — specifically, the reset that
* Transactor::operator() performs when the initial invariant pass
* returns tecINVARIANT_FAILED, rolling the transaction's effects back
* to a fee-claim-only state. In that reduced state the
* transaction-specific post-conditions no longer apply, but the
* protocol invariants must still hold against the fee claim itself.
* ProtocolOnly is not intended for other context discards (e.g. the
* reset used to handle tecOVERSIZE/tecKILLED/etc. in
* processPersistentChanges, or the ctx_.discard() done under
* TapFailHard); those paths do not re-run invariants at all.
*/
enum class InvariantScope { Full, ProtocolOnly };
/**
* Check all invariants for the current transaction.
*
* Runs transaction-specific invariants first (visitInvariantEntry +
* finalizeInvariants), then protocol-level invariants. Both layers
* always run; the worst failure code is returned.
* Delegates to the free xrpl::checkInvariants runner. When @p scope is
* InvariantScope::Full, this transactor is passed so both layers
* share a single walk of the modified ledger entries. A failure in
* either layer fails the transaction the same way: tecINVARIANT_FAILED
* on the first pass, which the caller may respond to by rolling the
* transaction back to a fee-claim state and re-invoking this with
* InvariantScope::ProtocolOnly; a failure on that post-reset pass
* escalates to tefINVARIANT_FAILED.
*
* @param result the tentative TER from transaction processing.
* @param fee the fee consumed by the transaction.
* @param scope which invariant layers to check.
*
* @return the final TER after all invariant checks.
*/
[[nodiscard]] TER
checkInvariants(TER result, XRPAmount fee);
checkInvariants(TER result, XRPAmount fee, InvariantScope scope);
/////////////////////////////////////////////////////
/*
@@ -538,20 +569,30 @@ private:
preflightUniversal(PreflightContext const& ctx);
/**
* Check transaction-specific invariants only.
*
* Walks every modified ledger entry via visitInvariantEntry, then
* calls finalizeInvariants on the derived transactor. Returns
* tecINVARIANT_FAILED if any transaction invariant is violated.
*
* @param result the tentative TER from transaction processing.
* @param fee the fee consumed by the transaction.
*
* @return the original result if all invariants pass, or
* tecINVARIANT_FAILED otherwise.
* Bridges the two-phase TxInvariantCheck interface to this transactor's
* visitInvariantEntry/finalizeInvariants hooks. Declared private (rather
* than protected, like the hooks they forward to) so that neither this
* transactor nor any subclass can call them directly through a
* Transactor& — only through the TxInvariantCheck& that the free
* xrpl::checkInvariants runner holds, which is where the two-phase
* ordering is enforced.
*/
[[nodiscard]] TER
checkTransactionInvariants(TER result, XRPAmount fee);
void
visitEntry(bool isDelete, SLE::const_ref before, SLE::const_ref after) final
{
visitInvariantEntry(isDelete, before, after);
}
[[nodiscard]] bool
finalize(
STTx const& tx,
TER result,
XRPAmount fee,
ReadView const& view,
beast::Journal const& j) final
{
return finalizeInvariants(tx, result, fee, view, j);
}
};
inline bool

8
include/xrpl/tx/invariants/FreezeInvariant.h
View File

@@ -2,6 +2,7 @@
#include <xrpl/beast/utility/Journal.h>
#include <xrpl/ledger/ReadView.h>
#include <xrpl/ledger/helpers/LendingHelpers.h>
#include <xrpl/protocol/AccountID.h>
#include <xrpl/protocol/Issue.h>
#include <xrpl/protocol/STAmount.h>
@@ -11,6 +12,7 @@
#include <xrpl/protocol/XRPAmount.h>
#include <map>
#include <optional>
#include <vector>
namespace xrpl {
@@ -70,7 +72,8 @@ private:
STTx const& tx,
beast::Journal const& j,
bool enforce,
bool fixOverrideFreeze);
bool fixOverrideFreeze,
std::optional<LoanDefaultFreezeExemptAccounts> const& loanDefaultAccounts);
static bool
validateFrozenState(
@@ -80,7 +83,8 @@ private:
beast::Journal const& j,
bool enforce,
bool globalFreeze,
bool fixOverrideFreeze);
bool fixOverrideFreeze,
std::optional<LoanDefaultFreezeExemptAccounts> const& loanDefaultAccounts);
};
} // namespace xrpl

140
include/xrpl/tx/invariants/InvariantRunner.h Normal file
View File

@@ -0,0 +1,140 @@
#pragma once
#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>
#include <xrpl/protocol/XRPAmount.h>
#include <xrpl/tx/ApplyContext.h>
#include <functional>
#include <optional>
namespace xrpl {
/**
* @brief Runtime interface for a transaction-specific invariant check.
*
* The free checkInvariants runner drives two layers of checks over a single
* walk of the modified ledger entries:
*
* - Protocol checks are the concrete types in InvariantChecks, held in a
* std::tuple and dispatched statically by a compile-time fold (no
* virtual calls). They are duck-typed against the two-phase contract
* described below; see InvariantChecker_PROTOTYPE in InvariantCheck.h.
* - The transaction-specific check is injected at runtime through this
* interface, so the runner can call it without depending on the concrete
* transactor type. Transactor implements this interface directly (see
* Transactor.h) so that the interface's access can stay narrower than
* Transactor's own public surface: calling through a TxInvariantCheck&
* (all the runner ever holds) is public, but calling through a
* Transactor& is not, since Transactor overrides these as private
* (forwarding to its own protected visitInvariantEntry/finalizeInvariants).
*
* Both layers honour the same two-phase protocol:
*
* Phase 1 — state collection (visitEntry). Called once for each ledger
* entry created, modified, or deleted by the transaction. Implementations
* accumulate whatever state they need to evaluate their post-conditions.
* Must not throw.
*
* Phase 2 — condition evaluation (finalize). Called once after every
* modified entry has been visited. Returns true if all post-conditions
* hold, false to fail the transaction.
*
* Rule: invariants must run regardless of transaction result. finalize
* MUST perform meaningful checks even when the transaction has failed
* (when result is not tesSUCCESS). A bug or exploit could cause a failed
* transaction to mutate ledger state in unexpected ways; invariants are the
* last line of defense.
*
* The typical pattern: an invariant that expects a domain-specific state
* change (e.g. a Vault being created) should expect that change only when
* the transaction succeeded. A failed VaultCreate must not have created a
* Vault.
*
* Rule: privilege-gated checks apply to failed transactions too. Failed
* transactions carry no privileges. Any privilege-gated assertion must
* therefore also be enforced for failed transactions.
*/
class TxInvariantCheck
{
public:
virtual ~TxInvariantCheck() = default;
/**
* @brief Called for each ledger entry modified by the transaction.
*
* @param isDelete true if the SLE is being deleted.
* @param before the entry's state before the transaction (nullptr for
* newly created entries).
* @param after the entry's state after the transaction. For deletions
* this is the SLE being erased; use @p isDelete rather than
* a null @p after to detect deletions. @p after is
* never null.
*/
virtual void
visitEntry(bool isDelete, SLE::const_ref before, SLE::const_ref after) = 0;
/**
* @brief Called after all entries have been visited.
*
* @param tx the transaction being applied.
* @param result the tentative TER result of the transaction.
* @param fee the fee consumed by the transaction.
* @param view read-only view of the ledger after the transaction.
* @param j journal for logging invariant failures.
* @return true if all invariants hold; false to fail with
* tecINVARIANT_FAILED / tefINVARIANT_FAILED.
*/
[[nodiscard]] virtual bool
finalize(
STTx const& tx,
TER result,
XRPAmount fee,
ReadView const& view,
beast::Journal const& j) = 0;
};
/**
* @brief Run all protocol invariant checks plus the transaction-specific check
* in a single pass over the modified entries.
*
* Both layers share one walk of the modified-entry set: @p txCheck's
* visitEntry accumulates state on the same traversal that drives the
* protocol checkers, then both layers' finalize run on the complete state.
*
* Any failure (a finalize returning false or an exception anywhere in the
* check) returns failInvariantCheck(result). On the first pass that yields
* tecINVARIANT_FAILED, which the transactor treats as a signal to roll the
* transaction's effects back to a fee-claim-only state and re-run this
* runner against the reduced state (see Transactor::InvariantScope). If
* that second pass also fails, the result escalates to tefINVARIANT_FAILED,
* which excludes the transaction from the ledger entirely.
*
* The whole traversal — both layers' visitEntry calls and both layers'
* finalize calls — runs under a single try/catch. There is no per-layer
* isolation: an exception anywhere aborts the remaining traversal and
* finalize calls and fails the transaction.
*
* @param ctx the apply context for the current transaction.
* @param result the tentative TER from transaction processing.
* @param fee the fee consumed by the transaction.
* @param txCheck the transaction-specific invariant check.
* @return the final TER after all invariant checks.
*/
[[nodiscard]] TER
checkInvariants(
ApplyContext& ctx,
TER result,
XRPAmount fee,
std::optional<std::reference_wrapper<TxInvariantCheck>> txCheck);
[[nodiscard]] inline TER
checkInvariants(ApplyContext& ctx, TER result, XRPAmount fee)
{
return checkInvariants(ctx, result, fee, std::nullopt);
}
} // namespace xrpl