mirror of
https://github.com/XRPLF/rippled.git
synced 2026-06-03 08:46:46 +00:00
88794a1ea9
Bulk documentation pass covering 702 C++ source files in src/libxrpl, src/xrpld, and include/xrpl. Adds class, function, parameter, and invariant docs per docs/DOCUMENTATION_STANDARDS.md. Squashed from the original three-part series (part 1 / part 2 / part 3) to avoid merge-conflict noise when rebasing the work onto current develop.
60 lines
2.5 KiB
C++
60 lines
2.5 KiB
C++
#pragma once
|
|
|
|
namespace xrpl {
|
|
|
|
/** Symbolic names for the three canonical XRPL ledger states.
|
|
*
|
|
* The XRPL consensus model maintains three distinct ledger states at any
|
|
* point in time. Rather than requiring callers to pass magic strings
|
|
* (`"current"`, `"closed"`, `"validated"`) or ad-hoc integer sentinels,
|
|
* `LedgerShortcut` gives the type system a precise vocabulary for expressing
|
|
* ledger-selection intent without a specific sequence number or hash.
|
|
*
|
|
* In `RPCLedgerHelpers.cpp`, `lookupLedger` parsing maps the JSON strings
|
|
* `"current"`, `"closed"`, and `"validated"` onto the corresponding enum
|
|
* values before dispatching to the appropriate `getLedger` overload. The
|
|
* `AccountTx` RPC handler performs the same mapping when processing the
|
|
* `ledger_index` field. The gRPC adapter maps protobuf shortcut constants to
|
|
* these values as well.
|
|
*
|
|
* `LedgerShortcut` also participates as one arm of
|
|
* `RelationalDatabase::LedgerSpecifier` — a
|
|
* `std::variant<LedgerRange, LedgerShortcut, LedgerSequence, LedgerHash>` —
|
|
* allowing symbolic ledger names to flow through the database query layer via
|
|
* `std::visit` dispatch without special-case handling.
|
|
*
|
|
* @note The scoped `enum class` form prevents implicit integer conversions and
|
|
* namespace pollution, both of which are hazards in a codebase that also
|
|
* works extensively with raw integer ledger sequence numbers.
|
|
*/
|
|
enum class LedgerShortcut {
|
|
/** The open, in-progress ledger still accumulating new transactions.
|
|
*
|
|
* This ledger has not been closed or validated, so its contents may
|
|
* change. Results derived from it are not final and may be rolled back
|
|
* during a reorganisation or consensus failure.
|
|
*/
|
|
Current,
|
|
|
|
/** The most recently closed ledger; stable in structure but not yet
|
|
* consensus-validated.
|
|
*
|
|
* No new transactions are accepted into this ledger, but the network has
|
|
* not yet confirmed it as the authoritative chain tip. It is more stable
|
|
* than `Current` but still not suitable for finality guarantees.
|
|
*/
|
|
Closed,
|
|
|
|
/** The most recently validated ledger; the fully consensus-confirmed chain
|
|
* tip.
|
|
*
|
|
* This is the only state considered immutable and trustworthy for finality
|
|
* purposes. An RPC node that cannot provide a fresh validated ledger
|
|
* (i.e., it is stale) will return an error rather than serve potentially
|
|
* incorrect data.
|
|
*/
|
|
Validated
|
|
};
|
|
|
|
} // namespace xrpl
|