From fcceb0aac10c1cbd12c0dc3e3a2d21b711e64497 Mon Sep 17 00:00:00 2001 From: Edward Hennis Date: Wed, 12 Apr 2017 19:56:00 -0400 Subject: [PATCH] Update developer documentation --- docs/source.dox | 2 + src/ripple/app/tx/apply.h | 102 ++++++++++++++++++--------- src/ripple/app/tx/applySteps.h | 122 ++++++++++++++++++++++++++++----- 3 files changed, 175 insertions(+), 51 deletions(-) diff --git a/docs/source.dox b/docs/source.dox index 6dd9f77a67..7475222c9b 100644 --- a/docs/source.dox +++ b/docs/source.dox @@ -117,6 +117,8 @@ INPUT = \ ../src/ripple/app/consensus/RCLCxLedger.h \ ../src/ripple/app/consensus/RCLConsensus.h \ ../src/ripple/app/consensus/RCLCxPeerPos.h \ + ../src/ripple/app/tx/apply.h \ + ../src/ripple/app/tx/applySteps.h \ ../src/ripple/app/tx/impl/InvariantCheck.h \ INPUT_ENCODING = UTF-8 diff --git a/src/ripple/app/tx/apply.h b/src/ripple/app/tx/apply.h index 1c2c83d0f9..cabfe66798 100644 --- a/src/ripple/app/tx/apply.h +++ b/src/ripple/app/tx/apply.h @@ -33,21 +33,32 @@ namespace ripple { class Application; class HashRouter; +/** Describes the pre-processing validity of a transaction. + + @see checkValidity, forceValidity +*/ enum class Validity { - SigBad, // Signature is bad. Didn't do local checks. - SigGoodOnly, // Signature is good, but local checks fail. - Valid // Signature and local checks are good / passed. + /// Signature is bad. Didn't do local checks. + SigBad, + /// Signature is good, but local checks fail. + SigGoodOnly, + /// Signature and local checks are good / passed. + Valid }; -/** Checks transaction signature and local checks. Returns - a Validity enum representing how valid the STTx is - and, if not Valid, a reason string. - Results are cached internally, so tests will not be - repeated over repeated calls, unless cache expires. +/** Checks transaction signature and local checks. - @return std::pair, where `.first` is the status, and + @return A `Validity` enum representing how valid the + `STTx` is and, if not `Valid`, a reason string. + + @note Results are cached internally, so tests will not be + repeated over repeated calls, unless cache expires. + + @return `std::pair`, where `.first` is the status, and `.second` is the reason if appropriate. + + @see Validity */ std::pair checkValidity(HashRouter& router, @@ -56,38 +67,57 @@ checkValidity(HashRouter& router, /** Sets the validity of a given transaction in the cache. - Use with extreme care. + + @warning Use with extreme care. @note Can only raise the validity to a more valid state, and can not override anything cached bad. + + @see checkValidity, Validity */ void forceValidity(HashRouter& router, uint256 const& txid, Validity validity); -/** Apply a transaction to a ReadView. +/** Apply a transaction to an `OpenView`. - Throws: - Does not throw. + This function is the canonical way to apply a transaction + to a ledger. It rolls the validation and application + steps into one function. To do the steps manually, the + correct calling order is: + @code{.cpp} + preflight -> preclaim -> doApply + @endcode + The result of one function must be passed to the next. + The `preflight` result can be safely cached and reused + asynchronously, but `preclaim` and `doApply` must be called + in the same thread and with the same view. - For open ledgers, the Transactor will catch and - return tefEXCEPTION. For closed ledgers, the - Transactor will attempt to only charge a fee, - and return tecFAILED_PROCESSING. + @note Does not throw. - If the Transactor gets an exception while trying - to charge the fee, it will be caught here and - turned into tefEXCEPTION. + For open ledgers, the `Transactor` will catch exceptions + and return `tefEXCEPTION`. For closed ledgers, the + `Transactor` will attempt to only charge a fee, + and return `tecFAILED_PROCESSING`. - This try/catch handler is the last resort, any - uncaught exceptions will be turned into - tefEXCEPTION. + If the `Transactor` gets an exception while trying + to charge the fee, it will be caught and + turned into `tefEXCEPTION`. - For network health, a Transactor makes its - best effort to at least charge a fee if the - ledger is closed. + For network health, a `Transactor` makes its + best effort to at least charge a fee if the + ledger is closed. - @return A pair with the TER and a bool indicating + @param app The current running `Application`. + @param view The open ledger that the transaction + will attempt to be applied to. + @param tx The transaction to be checked. + @param flags `ApplyFlags` describing processing options. + @param journal A journal. + + @see preflight, preclaim, doApply + + @return A pair with the `TER` and a `bool` indicating whether or not the transaction was applied. */ std::pair @@ -96,18 +126,26 @@ apply (Application& app, OpenView& view, beast::Journal journal); -/** Class for return value from applyTransaction */ +/** Enum class for return value from `applyTransaction` + + @see applyTransaction +*/ enum class ApplyResult { - Success, // Applied to this ledger - Fail, // Should not be retried in this ledger - Retry // Should be retried in this ledger + /// Applied to this ledger + Success, + /// Should not be retried in this ledger + Fail, + /// Should be retried in this ledger + Retry }; /** Transaction application helper Provides more detailed logging and decodes the - correct behavior based on the TER type + correct behavior based on the `TER` type + + @see ApplyResult */ ApplyResult applyTransaction(Application& app, OpenView& view, diff --git a/src/ripple/app/tx/applySteps.h b/src/ripple/app/tx/applySteps.h index 46d0fe287b..a9acd1664b 100644 --- a/src/ripple/app/tx/applySteps.h +++ b/src/ripple/app/tx/applySteps.h @@ -28,18 +28,28 @@ namespace ripple { class Application; class STTx; +/** Describes the results of the `preflight` check + + @note All members are const to make it more difficult + to "fake" a result without calling `preflight`. + @see preflight, preclaim, doApply, apply +*/ struct PreflightResult { public: - // from the context + /// From the input - the transaction STTx const& tx; + /// From the input - the rules Rules const rules; + /// From the input - the flags ApplyFlags const flags; + /// From the input - the journal beast::Journal const j; - // result + /// Intermediate transaction result TER const ter; + /// Constructor template PreflightResult(Context const& ctx_, TER ter_) @@ -51,23 +61,37 @@ public: { } + /// Deleted copy assignment operator PreflightResult& operator=(PreflightResult const&) = delete; }; +/** Describes the results of the `preclaim` check + + @note All members are const to make it more difficult + to "fake" a result without calling `preclaim`. + @see preflight, preclaim, doApply, apply +*/ struct PreclaimResult { public: - // from the context + /// From the input - the ledger view ReadView const& view; + /// From the input - the transaction STTx const& tx; + /// From the input - the flags ApplyFlags const flags; + /// From the input - the journal beast::Journal const j; - // result + /// Intermediate transaction result TER const ter; + /// Transaction-specific base fee std::uint64_t const baseFee; + /// Success flag - whether the transaction is likely to + /// claim a fee bool const likelyToClaimFee; + /// Constructor template PreclaimResult(Context const& ctx_, TER ter_, std::uint64_t const& baseFee_) @@ -82,6 +106,7 @@ public: { } + /// Constructor template PreclaimResult(Context const& ctx_, std::pair const& result) @@ -89,26 +114,39 @@ public: { } + /// Deleted copy assignment operator PreclaimResult& operator=(PreclaimResult const&) = delete; }; +/** Structure describing the consequences to the account + of applying a transaction if the transaction consumes + the maximum XRP allowed. + + @see calculateConsequences +*/ struct TxConsequences { - enum Category + /// Describes how the transaction affects subsequent + /// transactions + enum ConsequenceCategory { - // Moves currency around, creates offers, etc. + /// Moves currency around, creates offers, etc. normal = 0, - // Affects the ability of subsequent transactions - // to claim a fee. Eg. SetRegularKey + /// Affects the ability of subsequent transactions + /// to claim a fee. Eg. `SetRegularKey` blocker }; - Category const category; + /// Describes how the transaction affects subsequent + /// transactions + ConsequenceCategory const category; + /// Transaction fee XRPAmount const fee; - // Does NOT include the fee. + /// Does NOT include the fee. XRPAmount const potentialSpend; - TxConsequences(Category const category_, + /// Constructor + TxConsequences(ConsequenceCategory const category_, XRPAmount const fee_, XRPAmount const spend_) : category(category_) , fee(fee_) @@ -116,9 +154,13 @@ struct TxConsequences { } + /// Constructor TxConsequences(TxConsequences const&) = default; + /// Deleted copy assignment operator TxConsequences& operator=(TxConsequences const&) = delete; + /// Constructor TxConsequences(TxConsequences&&) = default; + /// Deleted copy assignment operator TxConsequences& operator=(TxConsequences&&) = delete; }; @@ -128,8 +170,16 @@ struct TxConsequences The transaction is checked against all possible validity constraints that do not require a ledger. - @return A PreflightResult object constaining, among - other things, the TER code. + @param app The current running `Application`. + @param rules The `Rules` in effect at the time of the check. + @param tx The transaction to be checked. + @param flags `ApplyFlags` describing processing options. + @param j A journal. + + @see PreflightResult, preclaim, doApply, apply + + @return A `PreflightResult` object containing, among + other things, the `TER` code. */ PreflightResult preflight(Application& app, Rules const& rules, @@ -149,8 +199,19 @@ preflight(Application& app, Rules const& rules, "Succeeds" in this case is defined as returning a `tes` or `tec`, since both lead to claiming a fee. - @return A PreclaimResult object containing, among - other things the TER code and the base fee value for + @pre The transaction has been checked + and validated using `preflight` + + @param preflightResult The result of a previous + call to `preflight` for the transaction. + @param app The current running `Application`. + @param view The open ledger that the transaction + will attempt to be applied to. + + @see PreclaimResult, preflight, doApply, apply + + @return A `PreclaimResult` object containing, among + other things the `TER` code and the base fee value for this transaction. */ PreclaimResult @@ -168,6 +229,11 @@ preclaim(PreflightResult const& preflightResult, Since none should be thrown, that will usually mean terminating. + @param app The current running `Application`. + @param view The current open ledger. + @param tx The transaction to be checked. + @param j A journal. + @return The base fee. */ std::uint64_t @@ -176,18 +242,36 @@ calculateBaseFee(Application& app, ReadView const& view, /** Determine the XRP balance consequences if a transaction consumes the maximum XRP allowed. + + @pre The transaction has been checked + and validated using `preflight` + + @param preflightResult The result of a previous + call to `preflight` for the transaction. + + @return A `TxConsequences` object containing the "worst + case" consequences of applying this transaction to + a ledger. + + @see TxConsequences */ TxConsequences calculateConsequences(PreflightResult const& preflightResult); /** Apply a prechecked transaction to an OpenView. - See also: apply() + @pre The transaction has been checked + and validated using `preflight` and `preclaim` - Precondition: The transaction has been checked - and validated using the above functions. + @param preclaimResult The result of a previous + call to `preclaim` for the transaction. + @param app The current running `Application`. + @param view The open ledger that the transaction + will attempt to be applied to. - @return A pair with the TER and a bool indicating + @see preflight, preclaim, apply + + @return A pair with the `TER` and a `bool` indicating whether or not the transaction was applied. */ std::pair