sgns::UTXOManager¶

Owns the local UTXO set, supports coin selection, validation, persistence, reservations, and deterministic snapshot hashing.

#include <UTXOManager.hpp>

Public Classes¶

	Name
struct	UTXOEntry Metadata tracked for each outpoint in the local registry.
struct	UTXOCheckpoint Persisted checkpoint snapshot used to audit finalized UTXO state at a given epoch.

Public Types¶

	Name
enum class uint8_t	UTXOState { UTXO_READY, UTXO_CONSUMED} Lifecycle state stored for each tracked UTXO.
using std::pair< UTXOState, GeniusUTXO >	UTXOData UTXO state paired with the actual UTXO.
using std::unordered_map< OutPoint, UTXOEntry, OutPointHash >	UTXOOutPointMap Maps an outpoint to its UTXO Entry.
using std::unordered_map< std::string, std::vector< OutPoint > >	AddressOutPointList Maps an owner address to a list of outpoints they own.
using std::function< std::vector< uint8_t >(const std::vector< uint8_t > &data)>	SignFunc Method to sign a vector of bytes, returning the signature bytes.
using std::function< bool(const std::string &address, const std::vector< uint8_t > &signature, const std::vector< uint8_t > &data)>	VerifySignatureFunc Method to verify a signature given an address, signature bytes, and original data.

Public Functions¶

	Name
	UTXOManager(const bool is_full_node, std::string address, SignFunc sign, VerifySignatureFunc verify_signature) Construct a new UTXOManager object.
uint64_t	GetBalance() const Get the account's balance.
uint64_t	GetBalance(const std::string & address) const Get the informed address balance.
uint64_t	GetBalance(const TokenID & token_id) const Get the accounts balance for a specific token.
uint64_t	GetBalance(const TokenID & token_id, const std::string & address) const Get the balance of the informed address for a specific token.
outcome::result< bool >	PutUTXO(GeniusUTXO new_utxo, const std::string & address) Add a new UTXO to the account.
outcome::result< bool >	PutUTXO(const GeniusUTXO & new_utxo) Adds a new UTXO to the account using the manager's default address.
outcome::result< void >	DeleteUTXO(const base::Hash256 & utxo_id, uint32_t output_idx, const std::string & address) Delete a UTXO from the account.
outcome::result< bool >	ConsumeUTXOs(const std::vector< InputUTXOInfo > & infos, const std::string & address) Consume UTXOs from the account.
outcome::result< bool >	ConsumeUTXOs(const std::vector< InputUTXOInfo > & infos) Consume UTXOs from the default owner address tracked by this manager.
std::vector< GeniusUTXO >	GetUTXOs(const std::string & address) const Get UTXOs for a specific address.
std::vector< GeniusUTXO >	GetUTXOs() const Returns spendable UTXOs owned by the manager's default address.
std::vector< GeniusUTXO >	GetUTXOsForReservation(const std::string & address, const std::string & reservation_id) const Get UTXOs for a specific address that are reserved under a given reservation ID.
std::unordered_map< std::string, std::vector< UTXOData > >	GetAllUTXOs() const Get all UTXOs tracked by the manager, grouped by owner address.
outcome::result< void >	SetUTXOs(const std::vector< GeniusUTXO > & utxos, const std::string & address) Set UTXOs for a specific address (replaces existing UTXOs).
outcome::result< void >	SetUTXOs(const std::vector< GeniusUTXO > & utxos) Set UTXOs for the manager's default address (replaces existing UTXOs).
outcome::result< UTXOTxParameters >	CreateTxParameter(uint64_t amount, std::string dest_address, TokenID token_id) Create the input and output parameters for a single-output transfer, selecting from available UTXOs.
outcome::result< UTXOTxParameters >	CreateTxParameter(const std::vector< OutputDestInfo > & destinations, const TokenID & token_id) Selects and signs inputs for a multi-output transfer.
void	ReserveUTXOs(const std::vector< InputUTXOInfo > & inputs, const std::string & reservation_id) Marks inputs as reserved so they are not reused by concurrent transaction assembly.
void	RollbackUTXOs(const std::vector< InputUTXOInfo > & inputs, const std::string & reservation_id) Releases a previous reservation without consuming the inputs.
bool	VerifyParameters(const UTXOTxParameters & params) const Verifies ownership and signatures for UTXO transaction parameters using the default address.
bool	VerifyParameters(const UTXOTxParameters & params, const std::string & address) const Verifies ownership and signatures for UTXO transaction parameters using an explicit address.
std::optional< UTXOState >	GetOutPointState(const base::Hash256 & utxo_id, uint32_t output_idx) const Returns the tracked state of a specific outpoint when present.
bool	IsOutPointConsumed(const base::Hash256 & utxo_id, uint32_t output_idx) const Indicates whether a specific outpoint has already been consumed.
base::Hash256	ComputeUTXOMerkleRoot() const Compute a deterministic Merkle root for unspent UTXOs owned by this node address.
base::Hash256	ComputeUTXOMerkleRoot(const std::string & address) const Compute a deterministic Merkle root for unspent UTXOs from a specific address.
base::Hash256	ComputeUTXOMerkleRootFromSnapshot(const std::vector< GeniusUTXO > & utxos) const Compute deterministic UTXO Merkle root from an explicit UTXO snapshot.
outcome::result< bool >	LoadUTXOs(std::shared_ptr< storage::rocksdb > db) Loads the UTXO state for the manager's default address from persistent storage.
void	ReleaseStorage() Releases the current RocksDB handle used for persistence.
outcome::result< void >	StoreUTXOs(const std::string & address) Stores the current UTXO state for the manager's default address to persistent storage.
outcome::result< void >	CreateCheckpoint(uint64_t epoch, const base::Hash256 & last_finalized_tx, const base::Hash256 & registry_hash) Creates a checkpoint for the manager's default address.
outcome::result< void >	CreateCheckpoint(const std::string & address, uint64_t epoch, const base::Hash256 & last_finalized_tx, const base::Hash256 & registry_hash) Creates a checkpoint for an explicit owner address.
outcome::result< std::optional< UTXOCheckpoint > >	LoadLatestCheckpoint() const Loads the latest checkpoint for the default owner address.
outcome::result< std::optional< UTXOCheckpoint > >	LoadLatestCheckpoint(const std::string & address) const Loads the latest checkpoint for the provided owner address.

Public Types Documentation¶

enum UTXOState¶

Enumerator	Value	Description
UTXO_READY		UTXO is unspent and available for use.
UTXO_CONSUMED		UTXO has been consumed by a transaction and is no longer available.

Lifecycle state stored for each tracked UTXO.

using UTXOData¶

using sgns::UTXOManager::UTXOData = std::pair<UTXOState, GeniusUTXO>;

UTXO state paired with the actual UTXO.

using UTXOOutPointMap¶

using sgns::UTXOManager::UTXOOutPointMap = std::unordered_map<OutPoint, UTXOEntry, OutPointHash>;

Maps an outpoint to its UTXO Entry.

using AddressOutPointList¶

using sgns::UTXOManager::AddressOutPointList = std::unordered_map<std::string, std::vector<OutPoint>>;

Maps an owner address to a list of outpoints they own.

using SignFunc¶

using sgns::UTXOManager::SignFunc = std::function<std::vector<uint8_t>( const std::vector<uint8_t> &data )>;

Method to sign a vector of bytes, returning the signature bytes.

using VerifySignatureFunc¶

using sgns::UTXOManager::VerifySignatureFunc = std::function<bool( const std::string          &address,
                                                       const std::vector<uint8_t> &signature,
                                                       const std::vector<uint8_t> &data )>;

Method to verify a signature given an address, signature bytes, and original data.

Public Functions Documentation¶

function UTXOManager¶

inline UTXOManager(
    const bool is_full_node,
    std::string address,
    SignFunc sign,
    VerifySignatureFunc verify_signature
)

Construct a new UTXOManager object.

Parameters:

is_full_node True if the node is a full node
address The address of the node
sign The signer method
verify_signature The verifier method

function GetBalance¶

uint64_t GetBalance() const

Get the account's balance.

Return: The total balance of the account

function GetBalance¶

uint64_t GetBalance(
    const std::string & address
) const

Get the informed address balance.

Parameters:

address The address to get the balance for

Return: The total balance of the account

function GetBalance¶

uint64_t GetBalance(
    const TokenID & token_id
) const

Get the accounts balance for a specific token.

Parameters:

token_id Token ID to get the balance

Return: The balance of the account for the specific token

function GetBalance¶

uint64_t GetBalance(
    const TokenID & token_id,
    const std::string & address
) const

Get the balance of the informed address for a specific token.

Parameters:

token_id The token ID to get the balance for
address The address to get the balance for

Return: The balance of the account for the specific token and address

function PutUTXO¶

outcome::result< bool > PutUTXO(
    GeniusUTXO new_utxo,
    const std::string & address
)

Add a new UTXO to the account.

Parameters:

new_utxo The new UTXO to be added
address Address to add the UTXO to

Return: true if the UTXO was added, false otherwise

function PutUTXO¶

inline outcome::result< bool > PutUTXO(
    const GeniusUTXO & new_utxo
)

Adds a new UTXO to the account using the manager's default address.

Parameters:

new_utxo The UTXO to be added

Return: true if added successfully, false otherwise

function DeleteUTXO¶

outcome::result< void > DeleteUTXO(
    const base::Hash256 & utxo_id,
    uint32_t output_idx,
    const std::string & address
)

Delete a UTXO from the account.

Parameters:

utxo_id The ID of the UTXO to be deleted
output_idx The output index of the UTXO
address Address to remove the UTXO from

function ConsumeUTXOs¶

outcome::result< bool > ConsumeUTXOs(
    const std::vector< InputUTXOInfo > & infos,
    const std::string & address
)

Consume UTXOs from the account.

Parameters:

infos Vector of UTXO information to be consumed
address Address to consume UTXOs from

Return: true if all UTXOs were consumed, false otherwise

function ConsumeUTXOs¶

inline outcome::result< bool > ConsumeUTXOs(
    const std::vector< InputUTXOInfo > & infos
)

Consume UTXOs from the default owner address tracked by this manager.

Parameters:

infos Vector of UTXO information to be consumed

Return: true if all UTXOs were consumed, false otherwise

function GetUTXOs¶

std::vector< GeniusUTXO > GetUTXOs(
    const std::string & address
) const

Get UTXOs for a specific address.

Parameters:

address The address to get UTXOs for

Return: Vector of UTXOs for the address

function GetUTXOs¶

inline std::vector< GeniusUTXO > GetUTXOs() const

Returns spendable UTXOs owned by the manager's default address.

Return: The vector of UTXOs for the manager's default address

function GetUTXOsForReservation¶

std::vector< GeniusUTXO > GetUTXOsForReservation(
    const std::string & address,
    const std::string & reservation_id
) const

Get UTXOs for a specific address that are reserved under a given reservation ID.

Parameters:

address The address to get UTXOs for
reservation_id The reservation ID to filter UTXOs by

Return: The vector of UTXOs for the address under the reservation ID

function GetAllUTXOs¶

std::unordered_map< std::string, std::vector< UTXOData > > GetAllUTXOs() const

Get all UTXOs tracked by the manager, grouped by owner address.

Return: A map of owner addresses to their corresponding vectors of UTXOs

function SetUTXOs¶

outcome::result< void > SetUTXOs(
    const std::vector< GeniusUTXO > & utxos,
    const std::string & address
)

Set UTXOs for a specific address (replaces existing UTXOs).

Parameters:

utxos Vector of UTXOs to set for the address
address The address to set UTXOs for

function SetUTXOs¶

inline outcome::result< void > SetUTXOs(
    const std::vector< GeniusUTXO > & utxos
)

Set UTXOs for the manager's default address (replaces existing UTXOs).

Parameters:

utxos Vector of UTXOs to set for the manager's default address

function CreateTxParameter¶

outcome::result< UTXOTxParameters > CreateTxParameter(
    uint64_t amount,
    std::string dest_address,
    TokenID token_id
)

Create the input and output parameters for a single-output transfer, selecting from available UTXOs.

Parameters:

amount The amount to transfer
dest_address The destination address for the transfer
token_id The token ID to transfer

Return: The combined input and output parameters for the transaction if successful, or an error if selection or signing failed

function CreateTxParameter¶

outcome::result< UTXOTxParameters > CreateTxParameter(
    const std::vector< OutputDestInfo > & destinations,
    const TokenID & token_id
)

Selects and signs inputs for a multi-output transfer.

Parameters:

destinations The list of destination addresses and amounts for the transfer
token_id The token ID to transfer

Return: The combined input and output parameters for the transaction if successful, or an error if selection or signing failed

function ReserveUTXOs¶

void ReserveUTXOs(
    const std::vector< InputUTXOInfo > & inputs,
    const std::string & reservation_id
)

Marks inputs as reserved so they are not reused by concurrent transaction assembly.

Parameters:

inputs The list of UTXOs to reserve
reservation_id The ID for the reservation

function RollbackUTXOs¶

void RollbackUTXOs(
    const std::vector< InputUTXOInfo > & inputs,
    const std::string & reservation_id
)

Releases a previous reservation without consuming the inputs.

Parameters:

inputs The list of UTXOs to release
reservation_id The ID for the reservation

function VerifyParameters¶

inline bool VerifyParameters(
    const UTXOTxParameters & params
) const

Verifies ownership and signatures for UTXO transaction parameters using the default address.

Parameters:

params The transaction parameters to verify, including inputs and outputs

Return: true if all signatures are valid and correspond to the default address, false otherwise

function VerifyParameters¶

bool VerifyParameters(
    const UTXOTxParameters & params,
    const std::string & address
) const

Verifies ownership and signatures for UTXO transaction parameters using an explicit address.

Parameters:

params The transaction parameters to verify, including inputs and outputs
address The address to verify ownership against

Return: true if all signatures are valid and correspond to the specified address, false otherwise

function GetOutPointState¶

std::optional< UTXOState > GetOutPointState(
    const base::Hash256 & utxo_id,
    uint32_t output_idx
) const

Returns the tracked state of a specific outpoint when present.

Parameters:

utxo_id The transaction hash that created the UTXO
output_idx The output index of the UTXO within the transaction

Return: If the outpoint is tracked, returns its current state (e.g. ready or consumed); if not tracked, returns std::nullopt

function IsOutPointConsumed¶

bool IsOutPointConsumed(
    const base::Hash256 & utxo_id,
    uint32_t output_idx
) const

Indicates whether a specific outpoint has already been consumed.

Parameters:

utxo_id The transaction hash that created the UTXO
output_idx The output index of the UTXO within the transaction

Return: true if the outpoint is consumed, false otherwise

function ComputeUTXOMerkleRoot¶

base::Hash256 ComputeUTXOMerkleRoot() const

Compute a deterministic Merkle root for unspent UTXOs owned by this node address.

Return: The computed UTXO Merkle root for this node address

function ComputeUTXOMerkleRoot¶

base::Hash256 ComputeUTXOMerkleRoot(
    const std::string & address
) const

Compute a deterministic Merkle root for unspent UTXOs from a specific address.

Parameters:

address The address to compute the UTXO Merkle root for

Return: The computed UTXO Merkle root for the specified address

function ComputeUTXOMerkleRootFromSnapshot¶

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

Compute deterministic UTXO Merkle root from an explicit UTXO snapshot.

Parameters:

utxos The list of UTXOs to include in the Merkle root computation

Return: The computed UTXO Merkle root

function LoadUTXOs¶

outcome::result< bool > LoadUTXOs(
    std::shared_ptr< storage::rocksdb > db
)

Loads the UTXO state for the manager's default address from persistent storage.

Parameters:

db The RocksDB instance to load from

Return: true if loaded successfully, false if no UTXOs were found, or an error if loading failed

function ReleaseStorage¶

void ReleaseStorage()

Releases the current RocksDB handle used for persistence.

function StoreUTXOs¶

outcome::result< void > StoreUTXOs(
    const std::string & address
)

Stores the current UTXO state for the manager's default address to persistent storage.

Parameters:

address The address to store UTXOs for

function CreateCheckpoint¶

outcome::result< void > CreateCheckpoint(
    uint64_t epoch,
    const base::Hash256 & last_finalized_tx,
    const base::Hash256 & registry_hash
)

Creates a checkpoint for the manager's default address.

Parameters:

epoch The epoch number associated with the checkpoint
last_finalized_tx The transaction ID of the last finalized transaction at the time of checkpointing
registry_hash The hash of the full registry state at the time of checkpointing

function CreateCheckpoint¶

outcome::result< void > CreateCheckpoint(
    const std::string & address,
    uint64_t epoch,
    const base::Hash256 & last_finalized_tx,
    const base::Hash256 & registry_hash
)

Creates a checkpoint for an explicit owner address.

Parameters:

address The address for which to create a checkpoint
epoch The epoch number associated with the checkpoint
last_finalized_tx The transaction ID of the last finalized transaction at the time of checkpointing
registry_hash The hash of the full registry state at the time of checkpointing

function LoadLatestCheckpoint¶

inline outcome::result< std::optional< UTXOCheckpoint > > LoadLatestCheckpoint() const

Loads the latest checkpoint for the default owner address.

Return: If successful, returns the latest checkpoint for the manager's default address; if no checkpoint is found, returns std::nullopt; if an error occurs during loading, returns the error

function LoadLatestCheckpoint¶

outcome::result< std::optional< UTXOCheckpoint > > LoadLatestCheckpoint(
    const std::string & address
) const

Loads the latest checkpoint for the provided owner address.

Parameters:

address The owner address to load the checkpoint for

Return: If successful, returns the latest checkpoint for the manager's default address; if no checkpoint is found, returns std::nullopt; if an error occurs during loading, returns the error

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