xrpld
Loading...
Searching...
No Matches
xrpl::tests::DeepChain Struct Reference

A chain of inner nodes in wire form, from the root down to one deepest node, each with one real child and, under withDecoys(), an unresolvable second one. More...

#include <DeepChain.h>

Collaboration diagram for xrpl::tests::DeepChain:

Public Member Functions

 DeepChain (unsigned int seed=1)
 A chain of inner nodes reaching SHAMap::kLeafDepth, a depth only a leaf may occupy.
SHAMapTreeNodePtr nodeAt (unsigned int depth) const
 The node the chain holds at the given depth, root first.
SHAMapNodeID idAt (unsigned int depth) const
 Where the node at the given depth claims to belong, which is on the path to pathKey.
Blob prefixedNodeAt (unsigned int depth) const
 The same node in the prefixed form used for storage and fetch packs, which is what hashes to the node's own hash.
std::vector< std::pair< SHAMapNodeID, SHAMapTreeNodePtr > > nodesBelowRoot (unsigned int firstDepth=1) const
 Every node below the root, down to and including the deepest one.
bool fill (SHAMap &map) const
 Fill a synching map, stopping one level short of the deepest node so the caller offers that one itself.
SHAMapAddNode addOffendingNode (SHAMap &map) const
 Offer the deepest node, which for a fabricated chain is the inner node at SHAMap::kLeafDepth, a depth only a leaf may occupy.

Static Public Member Functions

static DeepChain withDecoys (unsigned int seed=1)
 The same chain, with an unresolvable second child at every level, so a backed map's descendAsync() posts a real asynchronous read per level.
static DeepChain toLeaf (unsigned int depth, unsigned int seed=1)
 A chain ending in a real transaction leaf, which completes an acquisition.

Public Attributes

std::vector< SHAMapTreeNodePtr > nodes
SHAMapHash rootHash
UInt256 pathKey
unsigned int deepestDepth {SHAMap::kLeafDepth}

Static Public Attributes

static constexpr std::size_t kLeafItemBytes = kMinShaMapItemBytes
 The payload size of the leaf toLeaf() builds, which is the smallest a SHAMap item may be.

Private Types

enum class  Decoy { No , Yes }

Private Member Functions

 DeepChain (std::optional< unsigned int > leafDepth, unsigned int seed, Decoy decoy)
 Build any of the shapes.
void buildInnersDownTo (unsigned int deepest, SHAMapHash childHash, Decoy decoy)
 Fill in inner nodes, each with one real child (and, under Decoy::Yes, an additional unresolvable second child), from the root down to the given depth, and record the root hash.

Detailed Description

A chain of inner nodes in wire form, from the root down to one deepest node, each with one real child and, under withDecoys(), an unresolvable second one.

Built bottom-up, so every node hashes correctly and the root hash commits to the whole shape. Each node sits on the branch pathKey selects at its depth.

Two shapes: the constructors run inner nodes all the way to SHAMap::kLeafDepth, a depth only a leaf may occupy, and toLeaf() ends at a real transaction leaf.

Depends only on libxrpl, so either test tree can include it. The xrpld counterpart is test::packetFor() in src/test/app/AcquireTestHelpers.h.

Definition at line 37 of file DeepChain.h.

Member Enumeration Documentation

◆ Decoy

enum class xrpl::tests::DeepChain::Decoy
strongprivate
Enumerator
No 
Yes 

Definition at line 205 of file DeepChain.h.

Constructor & Destructor Documentation

◆ DeepChain() [1/2]

xrpl::tests::DeepChain::DeepChain ( unsigned int seed = 1)
explicit

A chain of inner nodes reaching SHAMap::kLeafDepth, a depth only a leaf may occupy.

Parameters
seedVaries the chain's nodes. Two chains built from one seed hold the same nodes, which caches and fetch packs key by hash.

Definition at line 63 of file DeepChain.h.

◆ DeepChain() [2/2]

xrpl::tests::DeepChain::DeepChain ( std::optional< unsigned int > leafDepth,
unsigned int seed,
Decoy decoy )
private

Build any of the shapes.

Parameters
leafDepthWhere a real transaction leaf sits, or nullopt to run inner nodes all the way to SHAMap::kLeafDepth instead.
seedVaries the chain's contents. See the public entry points.
decoyWhether every level carries an unresolvable second child.

Definition at line 215 of file DeepChain.h.

Member Function Documentation

◆ withDecoys()

DeepChain xrpl::tests::DeepChain::withDecoys ( unsigned int seed = 1)
staticnodiscard

The same chain, with an unresolvable second child at every level, so a backed map's descendAsync() posts a real asynchronous read per level.

Offered only for this shape: the decoy sits on branch 1, which is free only while pathKey is zero.

Parameters
seedVaries the whole chain. See the constructor.
Returns
The chain.

Definition at line 78 of file DeepChain.h.

◆ toLeaf()

DeepChain xrpl::tests::DeepChain::toLeaf ( unsigned int depth,
unsigned int seed = 1 )
staticnodiscard

A chain ending in a real transaction leaf, which completes an acquisition.

Parameters
depthWhere the leaf sits, at most SHAMap::kLeafDepth. Zero puts the leaf at the root. A deeper value throws std::logic_error, since no leaf can sit there.
seedVaries the leaf's contents, and so the whole chain. See the constructor.
Returns
The chain.

Definition at line 95 of file DeepChain.h.

◆ nodeAt()

SHAMapTreeNodePtr xrpl::tests::DeepChain::nodeAt ( unsigned int depth) const
nodiscard

The node the chain holds at the given depth, root first.

Parameters
depthThe depth of the node to return, at most deepestDepth.
Returns
The node.

Definition at line 109 of file DeepChain.h.

◆ idAt()

SHAMapNodeID xrpl::tests::DeepChain::idAt ( unsigned int depth) const
nodiscard

Where the node at the given depth claims to belong, which is on the path to pathKey.

Parameters
depthThe depth of the node to locate.
Returns
The node's claimed position.

Definition at line 122 of file DeepChain.h.

◆ prefixedNodeAt()

Blob xrpl::tests::DeepChain::prefixedNodeAt ( unsigned int depth) const
nodiscard

The same node in the prefixed form used for storage and fetch packs, which is what hashes to the node's own hash.

Parameters
depthThe depth of the node to serialize.
Returns
The node's prefixed serialized form.

Definition at line 135 of file DeepChain.h.

◆ nodesBelowRoot()

std::vector< std::pair< SHAMapNodeID, SHAMapTreeNodePtr > > xrpl::tests::DeepChain::nodesBelowRoot ( unsigned int firstDepth = 1) const
nodiscard

Every node below the root, down to and including the deepest one.

Parameters
firstDepthThe shallowest node to include, so a caller can feed the chain in more than one batch.
Returns
The nodes, each with its claimed position.

Definition at line 150 of file DeepChain.h.

◆ fill()

bool xrpl::tests::DeepChain::fill ( SHAMap & map) const
nodiscard

Fill a synching map, stopping one level short of the deepest node so the caller offers that one itself.

Reports rather than asserts: the two binaries sharing this header use different test frameworks.

Parameters
mapThe map to fill.
Returns
Whether the root and every node above the deepest one was accepted, which is a property of the chain.

Definition at line 170 of file DeepChain.h.

◆ addOffendingNode()

SHAMapAddNode xrpl::tests::DeepChain::addOffendingNode ( SHAMap & map) const
nodiscard

Offer the deepest node, which for a fabricated chain is the inner node at SHAMap::kLeafDepth, a depth only a leaf may occupy.

A chain whose only node is the root has nothing below it to offer, and addKnownNode() refuses a root ID, so a toLeaf(0) chain throws std::logic_error.

Parameters
mapThe map to offer the node to, filled by fill() first.
Returns
The verdict addKnownNode() reached.

Definition at line 196 of file DeepChain.h.

◆ buildInnersDownTo()

void xrpl::tests::DeepChain::buildInnersDownTo ( unsigned int deepest,
SHAMapHash childHash,
Decoy decoy )
private

Fill in inner nodes, each with one real child (and, under Decoy::Yes, an additional unresolvable second child), from the root down to the given depth, and record the root hash.

Bottom-up, since each node's hash covers the child hash below it.

Parameters
deepestThe depth of the deepest inner node to build. May be SHAMap::kLeafDepth, which is the fabricated chain's whole point.
childHashWhat that deepest inner node points at.
decoyWhether to add an unresolvable second child at every level.

Definition at line 270 of file DeepChain.h.

Member Data Documentation

◆ nodes

std::vector<SHAMapTreeNodePtr> xrpl::tests::DeepChain::nodes

Definition at line 40 of file DeepChain.h.

◆ rootHash

SHAMapHash xrpl::tests::DeepChain::rootHash

Definition at line 41 of file DeepChain.h.

◆ pathKey

UInt256 xrpl::tests::DeepChain::pathKey

Definition at line 45 of file DeepChain.h.

◆ deepestDepth

unsigned int xrpl::tests::DeepChain::deepestDepth {SHAMap::kLeafDepth}

Definition at line 48 of file DeepChain.h.

◆ kLeafItemBytes

std::size_t xrpl::tests::DeepChain::kLeafItemBytes = kMinShaMapItemBytes
staticconstexpr

The payload size of the leaf toLeaf() builds, which is the smallest a SHAMap item may be.

Definition at line 54 of file DeepChain.h.