sgns::utxo_merkle¶

Utilities for building deterministic Merkle roots over ordered UTXO payloads.

Functions¶

	Name
void	AppendUInt32BE(std::vector< uint8_t > & out, uint32_t value) Appends a 32-bit unsigned integer in big-endian order.
void	AppendUInt64BE(std::vector< uint8_t > & out, uint64_t value) Appends a 64-bit unsigned integer in big-endian order.
uint32_t	ReadUInt32BE(const uint8_t * data) Reads a 32-bit unsigned integer from big-endian bytes.
uint64_t	ReadUInt64BE(const uint8_t * data) Reads a 64-bit unsigned integer from big-endian bytes.
std::string	OutPointKey(const base::Hash256 & txid, uint32_t idx) Generates a canonical key for a UTXO outpoint, used for deterministic ordering in Merkle tree construction.
std::vector< uint8_t >	SerializeUTXOLeafPayload(const GeniusUTXO & utxo) Serializes a UTXO into the canonical leaf payload used for Merkle hashing.
base::Hash256	HashLeaf(const std::vector< uint8_t > & payload) Hashes a serialized UTXO leaf payload with the leaf domain separator.
base::Hash256	HashNode(const base::Hash256 & left, const base::Hash256 & right) Hashes two child nodes with the internal-node domain separator.
base::Hash256	EmptyUTXOMerkleRoot() Returns the canonical root used for an empty UTXO set.
base::Hash256	ComputeMerkleRootFromLeafHashes(std::vector< base::Hash256 > level_hashes) Reduces a list of leaf hashes into a single Merkle root.
base::Hash256	ComputeMerkleRootFromPayloads(std::vector< std::vector< uint8_t > > payloads) Sorts canonical payloads, hashes them as leaves, and computes the Merkle root.
base::Hash256	ComputeMerkleRootFromUTXOs(const std::vector< GeniusUTXO > & utxos) Computes the Merkle root for a given set of UTXOs by serializing them into canonical payloads and hashing them.

Attributes¶

	Name
uint8_t	kLeafPrefix Domain separator prefix used for hashed leaf payloads.
uint8_t	kNodePrefix Domain separator prefix used for hashed internal nodes.

Functions Documentation¶

function AppendUInt32BE¶

inline void AppendUInt32BE(
    std::vector< uint8_t > & out,
    uint32_t value
)

Appends a 32-bit unsigned integer in big-endian order.

Parameters:

out The vector to append to
value the value to append

function AppendUInt64BE¶

inline void AppendUInt64BE(
    std::vector< uint8_t > & out,
    uint64_t value
)

Appends a 64-bit unsigned integer in big-endian order.

Parameters:

out The vector to append to
value the value to append

function ReadUInt32BE¶

inline uint32_t ReadUInt32BE(
    const uint8_t * data
)

Reads a 32-bit unsigned integer from big-endian bytes.

Parameters:

data A pointer to the byte array

Return: the 32 bit unsigned integer represented by the bytes

function ReadUInt64BE¶

inline uint64_t ReadUInt64BE(
    const uint8_t * data
)

Reads a 64-bit unsigned integer from big-endian bytes.

Parameters:

data A pointer to the byte array

Return: the 64 bit unsigned integer represented by the bytes

function OutPointKey¶

inline std::string OutPointKey(
    const base::Hash256 & txid,
    uint32_t idx
)

Generates a canonical key for a UTXO outpoint, used for deterministic ordering in Merkle tree construction.

Parameters:

txid The transaction hash that created the UTXO
idx The output index of the UTXO within the transaction

Return: Canonical string key in the format "txid:idx" where txid is the readable hex representation of the transaction hash

function SerializeUTXOLeafPayload¶

inline std::vector< uint8_t > SerializeUTXOLeafPayload(
    const GeniusUTXO & utxo
)

Serializes a UTXO into the canonical leaf payload used for Merkle hashing.

Parameters:

utxo The UTXO to serialize

Return: The serialized leaf payload

function HashLeaf¶

inline base::Hash256 HashLeaf(
    const std::vector< uint8_t > & payload
)

Hashes a serialized UTXO leaf payload with the leaf domain separator.

Parameters:

payload The payload to hash

Return: The hash of the payload as a leaf node in the Merkle tree

function HashNode¶

inline base::Hash256 HashNode(
    const base::Hash256 & left,
    const base::Hash256 & right
)

Hashes two child nodes with the internal-node domain separator.

Parameters:

left The hash of the left child node
right The hash of the right child node

Return: The hash of the parent node

function EmptyUTXOMerkleRoot¶

inline base::Hash256 EmptyUTXOMerkleRoot()

Returns the canonical root used for an empty UTXO set.

Return: The canonical root for an empty UTXO set

function ComputeMerkleRootFromLeafHashes¶

inline base::Hash256 ComputeMerkleRootFromLeafHashes(
    std::vector< base::Hash256 > level_hashes
)

Reduces a list of leaf hashes into a single Merkle root.

Parameters:

level_hashes The list of leaf hashes

Return: The computed Merkle root

function ComputeMerkleRootFromPayloads¶

inline base::Hash256 ComputeMerkleRootFromPayloads(
    std::vector< std::vector< uint8_t > > payloads
)

Sorts canonical payloads, hashes them as leaves, and computes the Merkle root.

Parameters:

payloads The list of serialized UTXO payloads to include in the Merkle tree

Return: The computed Merkle root of the payloads

function ComputeMerkleRootFromUTXOs¶

inline base::Hash256 ComputeMerkleRootFromUTXOs(
    const std::vector< GeniusUTXO > & utxos
)

Computes the Merkle root for a given set of UTXOs by serializing them into canonical payloads and hashing them.

Parameters:

utxos The list of UTXOs to include in the Merkle tree

Return: The computed Merkle root of the UTXOs

Attributes Documentation¶

variable kLeafPrefix¶

uint8_t kLeafPrefix = 0x00;

Domain separator prefix used for hashed leaf payloads.

variable kNodePrefix¶

uint8_t kNodePrefix = 0x01;

Domain separator prefix used for hashed internal nodes.

Updated on 2026-06-05 at 17:22:18 -0700