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.
81 lines
3.3 KiB
C++
81 lines
3.3 KiB
C++
#pragma once
|
|
|
|
#include <xrpl/basics/base_uint.h>
|
|
#include <xrpl/protocol/LedgerFormats.h>
|
|
|
|
namespace xrpl {
|
|
|
|
class STLedgerEntry;
|
|
|
|
/** Bundles the 256-bit SHAMap locator of a ledger object with its expected
|
|
* `LedgerEntryType`, making ledger lookups type-safe by construction.
|
|
*
|
|
* The name is a portmanteau of "key" and "LET" (LedgerEntryType). Callers
|
|
* never build a `Keylet` by hand — they use one of the factory functions in
|
|
* the `keylet::` namespace (see `Indexes.h`), each of which encapsulates the
|
|
* correct SHA-512Half derivation for a specific object type and returns a
|
|
* `Keylet` already annotated with the matching `LedgerEntryType`.
|
|
*
|
|
* The ledger view's `read()` method accepts a `Keylet` and calls `check()`
|
|
* before returning an entry, so an incorrect type annotation surfaces at
|
|
* the access point rather than silently yielding a mistyped object.
|
|
*
|
|
* Two sentinel types participate in the matching protocol but are never
|
|
* stored on-ledger:
|
|
* - `ltANY` — wildcard; bypasses type checking entirely (used by
|
|
* `keylet::unchecked`).
|
|
* - `ltCHILD` — matches any entry that is not a directory node, reflecting
|
|
* the semantics of owner-directory children.
|
|
*
|
|
* @see keylet namespace in `Indexes.h` for all factory functions.
|
|
*/
|
|
struct Keylet
|
|
{
|
|
/** 256-bit SHAMap key that locates the ledger entry in the state tree. */
|
|
uint256 key;
|
|
|
|
/** Expected `LedgerEntryType` of the entry at `key`.
|
|
*
|
|
* May be the sentinel `ltANY` (wildcard) or `ltCHILD` (any non-directory
|
|
* entry); all other values are concrete on-ledger types whose numeric
|
|
* identities are protocol-stable and consensus-critical.
|
|
*/
|
|
LedgerEntryType type;
|
|
|
|
/** Constructs a keylet from an explicit type and key.
|
|
*
|
|
* Prefer the factory functions in the `keylet::` namespace over calling
|
|
* this constructor directly; they ensure the correct key derivation
|
|
* formula is used for each ledger object type.
|
|
*
|
|
* @param type The expected `LedgerEntryType` of the addressed entry.
|
|
* @param key The 256-bit SHAMap key of the entry.
|
|
*/
|
|
Keylet(LedgerEntryType type, uint256 const& key) : key(key), type(type)
|
|
{
|
|
}
|
|
|
|
/** Validates that a deserialized ledger entry corresponds to this keylet.
|
|
*
|
|
* Applies a three-tier match ordered from most-permissive to most-strict:
|
|
* - `ltANY`: always returns `true`; the caller bears full responsibility
|
|
* for type safety.
|
|
* - `ltCHILD`: returns `true` for any entry whose concrete type is not
|
|
* `ltDIR_NODE`. Directory nodes are structural bookkeeping objects; a
|
|
* directory child is definitionally something other than a directory.
|
|
* - Concrete type: requires both `sle.getType() == type` and
|
|
* `sle.key() == key`. This is the common case and gives the strongest
|
|
* safety guarantee.
|
|
*
|
|
* @param sle The deserialized ledger entry retrieved from the state map.
|
|
* @return `true` if `sle` legitimately corresponds to this keylet.
|
|
* @note `sle` must not itself carry `ltANY` or `ltCHILD` as its stored
|
|
* type; those are query-side sentinels, not real on-ledger types.
|
|
* An `XRPL_ASSERT` enforces this precondition in debug builds.
|
|
*/
|
|
[[nodiscard]] bool
|
|
check(STLedgerEntry const&) const;
|
|
};
|
|
|
|
} // namespace xrpl
|