mirror of
https://github.com/XRPLF/rippled.git
synced 2026-07-26 16:40:20 +00:00
refactor: Extract invariant invocation into free checkInvariants runner
Move the invariant-check orchestration out of ApplyContext and Transactor into a free function xrpl::checkInvariants(ApplyContext&, TER, XRPAmount, optional<reference_wrapper<InvariantCheck>>). The two previously separate traversals (one in ApplyContext driving the protocol tuple fold, one in Transactor driving the tx-specific check) are merged into a single ctx.visit walk. Per-layer try/catch inside the lambda isolates collection faults: a throw in one layer stops only that layer from visiting further entries while the other continues. A layer whose collection faulted skips its finalize phase. ApplyContext loses checkInvariants/checkInvariantsHelper/failInvariantCheck. Transactor delegates to the free runner via a private InvariantCheckAdapter that bridges visitInvariantEntry+finalizeInvariants into the InvariantCheck interface. A SkipTxInvariants::Yes/No enum makes the fee-claim-reset call site explicit about omitting the tx-specific check. Protocol checks remain duck-typed in the InvariantChecks tuple (static dispatch, no vtable on the hot path). InvariantCheck is the runtime interface used only by InvariantCheckAdapter.
This commit is contained in:
Vito
@@ -103,23 +103,7 @@ 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);
|
||||
|
||||
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_;
|
||||
|
||||
@@ -6,6 +6,7 @@
|
||||
#include <xrpl/protocol/XRPAmount.h>
|
||||
#include <xrpl/tx/ApplyContext.h>
|
||||
#include <xrpl/tx/applySteps.h>
|
||||
#include <xrpl/tx/invariants/CheckInvariants.h>
|
||||
|
||||
#include <utility>
|
||||
|
||||
@@ -142,19 +143,30 @@ public:
|
||||
return ctx_.view();
|
||||
}
|
||||
|
||||
/** Whether to run the transaction-specific invariant check.
|
||||
*
|
||||
* After a fee-claim reset the transaction's effects have been rolled back,
|
||||
* so only the protocol invariants are meaningful; pass @c Yes to skip the
|
||||
* transaction-specific check in that case.
|
||||
*/
|
||||
enum class SkipTxInvariants : bool { No = false, Yes = true };
|
||||
|
||||
/** 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 @c xrpl::checkInvariants runner. Unless @p skip is
|
||||
* @c SkipTxInvariants::Yes, the transaction-specific adapter is passed so
|
||||
* both layers share a single walk of the modified ledger entries.
|
||||
* Protocol faults (tefINVARIANT_FAILED) take priority over transaction
|
||||
* faults (tecINVARIANT_FAILED).
|
||||
*
|
||||
* @param result the tentative TER from transaction processing.
|
||||
* @param fee the fee consumed by the transaction.
|
||||
* @param skip whether to skip the transaction-specific invariant check.
|
||||
*
|
||||
* @return the final TER after all invariant checks.
|
||||
*/
|
||||
[[nodiscard]] TER
|
||||
checkInvariants(TER result, XRPAmount fee);
|
||||
checkInvariants(TER result, XRPAmount fee, SkipTxInvariants skip);
|
||||
|
||||
/////////////////////////////////////////////////////
|
||||
/*
|
||||
@@ -404,20 +416,34 @@ private:
|
||||
static NotTEC
|
||||
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.
|
||||
*/
|
||||
[[nodiscard]] TER
|
||||
checkTransactionInvariants(TER result, XRPAmount fee);
|
||||
/** Bridges the transaction-specific two-phase invariant hooks
|
||||
* (visitInvariantEntry + finalizeInvariants) into the InvariantCheck
|
||||
* interface consumed by the free xrpl::checkInvariants runner. */
|
||||
class InvariantCheckAdapter : public InvariantCheck
|
||||
{
|
||||
Transactor& self_;
|
||||
|
||||
public:
|
||||
explicit InvariantCheckAdapter(Transactor& self) : self_(self)
|
||||
{
|
||||
}
|
||||
|
||||
void
|
||||
visitEntry(bool isDelete, SLE::const_ref before, SLE::const_ref after) override
|
||||
{
|
||||
self_.visitInvariantEntry(isDelete, before, after);
|
||||
}
|
||||
|
||||
[[nodiscard]] bool
|
||||
finalize(
|
||||
STTx const& tx,
|
||||
TER result,
|
||||
XRPAmount fee,
|
||||
ReadView const& view,
|
||||
beast::Journal const& j) const override;
|
||||
};
|
||||
|
||||
InvariantCheckAdapter invariantCheck_{*this};
|
||||
};
|
||||
|
||||
inline bool
|
||||
|
||||
129
include/xrpl/tx/invariants/CheckInvariants.h
Normal file
129
include/xrpl/tx/invariants/CheckInvariants.h
Normal file
@@ -0,0 +1,129 @@
|
||||
#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>
|
||||
|
||||
namespace xrpl {
|
||||
|
||||
/**
|
||||
* @brief Runtime interface for a transaction-specific invariant check.
|
||||
*
|
||||
* The free @c checkInvariants runner drives two layers of checks over a single
|
||||
* walk of the modified ledger entries:
|
||||
*
|
||||
* - **Protocol checks** are the concrete types in @c InvariantChecks, held in
|
||||
* a @c 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 @c 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.
|
||||
*
|
||||
* 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.
|
||||
*
|
||||
* ## Rules for implementing `finalize`
|
||||
*
|
||||
* ### Invariants must run regardless of transaction result
|
||||
*
|
||||
* `finalize` MUST perform meaningful checks even when the transaction has
|
||||
* failed (`!isTesSuccess(result)`). 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.
|
||||
*
|
||||
* ### 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 InvariantCheck
|
||||
{
|
||||
public:
|
||||
virtual ~InvariantCheck() = 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
|
||||
* `after == nullptr` to detect deletions.
|
||||
*/
|
||||
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) const = 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.
|
||||
* Protocol faults (tefINVARIANT_FAILED) take precedence over transaction
|
||||
* faults (tecINVARIANT_FAILED).
|
||||
*
|
||||
* Every transaction is guaranteed to supply a @p txCheck (either a real check
|
||||
* or a no-op stub). The invariant contract requires @c finalize to handle
|
||||
* failed results gracefully, so passing the same @p txCheck after a fee-claim
|
||||
* reset is safe.
|
||||
*
|
||||
* @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<InvariantCheck>> txCheck);
|
||||
|
||||
[[nodiscard]] inline TER
|
||||
checkInvariants(ApplyContext& ctx, TER result, XRPAmount fee)
|
||||
{
|
||||
return checkInvariants(ctx, result, fee, std::nullopt);
|
||||
}
|
||||
|
||||
} // namespace xrpl
|
||||
Reference in New Issue
Block a user