ARCHIVE/rippled
1
0
Fork 0
mirror of https://github.com/XRPLF/rippled.git synced 2025-12-06 17:27:55 +00:00
Code Issues Packages Projects Releases Wiki Activity

Update developer documentation

Browse Source
This commit is contained in:
Edward Hennis
2017-04-12 19:56:00 -04:00
committed by Nik Bougalis
parent 2680b78b5b
commit fcceb0aac1
3 changed files with 175 additions and 51 deletions
Download Patch File Download Diff File Expand all files Collapse all files

102
src/ripple/app/tx/apply.h
View File

@@ -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<Validity, std::string>
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<TER, bool>
@@ -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,

122
src/ripple/app/tx/applySteps.h
View File

@@ -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<class Context>
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<class Context>
PreclaimResult(Context const& ctx_,
TER ter_, std::uint64_t const& baseFee_)
@@ -82,6 +106,7 @@ public:
{
}
/// Constructor
template<class Context>
PreclaimResult(Context const& ctx_,
std::pair<TER, std::uint64_t> 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<TER, bool>