MerkleTreeDiagnostics Class

Definition

Namespace

Bodu.Security.Cryptography

Assembly

Bodu.Security.Cryptography.dll

Package

Bodu.Security.Cryptography 1.2.0

Source

MerkleTreeDiagnostics.Node.cs

Captures the complete node-by-node trace of a Merkle computation, and provides structural inspection and independent hash re-validation.

public sealed class MerkleTreeDiagnostics

Inheritance

object

MerkleTreeDiagnostics

Inherited Members

object.Equals(object)

object.Equals(object, object)

object.GetHashCode()

object.GetType()

object.ReferenceEquals(object, object)

object.ToString()

Extension Methods

ComparableExtensions.AtLeast<T>(T, T, IComparer<T>)

ComparableExtensions.AtMost<T>(T, T, IComparer<T>)

ComparableExtensions.IsEqualTo<T>(T, T, IComparer<T>)

ComparableExtensions.Max<T>(T, T, IComparer<T>)

ComparableExtensions.Min<T>(T, T, IComparer<T>)

Examples

var diagnostics = new MerkleTreeDiagnostics();
byte[] root = tree.ComputeRootOfBlocks(stream, blockSize: 64, diagnostics);

diagnostics.WriteTo(Console.Out);

bool valid = diagnostics.Validate(() => SHA256.Create(), out var errors);

Remarks

An instance is passed to any root computation on MerkleTree or to CreateBlockAccumulator(int, bool, MerkleTreeDiagnostics?). As the tree is built, each leaf and each hashed internal node is recorded; a node promoted to a higher level unchanged is recorded once, at the level that produced it. Once the call returns, the complete trace is available for inspection.

Storing child hash snapshots for every internal node incurs additional allocation proportional to the number of internal nodes and the size of the hash output. This overhead is acceptable for diagnostic use but should not be enabled in production paths.

The Validate(Func<HashAlgorithm>, out IReadOnlyList<string>) method independently re-computes each internal node's hash from its recorded children and confirms the result matches the value stored in the node. Leaf hashes are not re-validated against the original input bytes, as raw blocks are not retained.

Constructors

MerkleTreeDiagnostics()

public MerkleTreeDiagnostics()

Properties

Root

Gets the root node - the sole node at the highest recorded level - or null if no nodes have been recorded.

public MerkleTreeDiagnostics.Node? Root { get; }

Property Value

MerkleTreeDiagnostics.Node

Methods

GetAllNodes()

Returns all recorded nodes sorted by level ascending, then by index ascending.

public IReadOnlyList<MerkleTreeDiagnostics.Node> GetAllNodes()

Returns

IReadOnlyList<MerkleTreeDiagnostics.Node>

A list of all MerkleTreeDiagnostics.Node instances recorded during the computation.

GetLevel(int)

Returns all nodes at the specified level, sorted by index ascending.

public IReadOnlyList<MerkleTreeDiagnostics.Node> GetLevel(int level)

Parameters

level int

The zero-based tree level to retrieve. Level 0 is the leaf level.

Returns

IReadOnlyList<MerkleTreeDiagnostics.Node>

A list of nodes at level, or an empty list if none exist.

GetLevelCount()

Gets the number of distinct levels recorded in the tree, including the leaf level.

public int GetLevelCount()

Returns

int

The total number of levels, or zero if no nodes have been recorded.

Validate(Func<HashAlgorithm>, out IReadOnlyList<string>)

Independently re-computes every internal node's hash from its recorded child hashes and verifies the result matches the value stored in the diagnostic node.

public bool Validate(Func<HashAlgorithm> algorithmFactory, out IReadOnlyList<string> errors)

Parameters

algorithmFactory Func<HashAlgorithm>

Factory returning a fresh HashAlgorithm per call. Must not be null.

errors IReadOnlyList<string>

On return, contains one entry per validation failure describing the node and the hash mismatch. Empty when the method returns true.

Returns

bool

true if all internal node hashes are consistent with their recorded children; false if any mismatch is found.

Remarks

The same algorithmFactory used for the original computation should be supplied so that the hash algorithm, output size, and combination strategy all match.

Leaf nodes are not validated against original input bytes, as raw blocks are not retained.

Exceptions

ArgumentNullException

algorithmFactory is null.

WriteTo(TextWriter, Func<HashAlgorithm>?)

Writes a formatted representation of the recorded tree to writer, including per-node hashes, child references, and a validation summary.

public void WriteTo(TextWriter writer, Func<HashAlgorithm>? algorithmFactory = null)

Parameters

writer TextWriter

The destination writer. Must not be null.

algorithmFactory Func<HashAlgorithm>

Optional factory used to run Validate(Func<HashAlgorithm>, out IReadOnlyList<string>) and append a validation summary. Pass null to skip validation output.

Remarks

The output is for diagnostic use only. Child references are resolved by matching recorded hash values, so an ambiguous match may occur if two nodes share the same hash.

Every character written is ASCII, so the trace survives a console on any code page and a paste into a bug report unchanged. A child list reads parent <- child + child, and the root level is marked *.

Exceptions

ArgumentNullException

writer is null.

Applies to

Product	Versions
.NET	8, 10