sgns::TransactionManager¶

Coordinates transaction creation, CRDT propagation, verification, and status tracking.

#include <TransactionManager.hpp>

Inherits from std::enable_shared_from_this< TransactionManager >

Public Types¶

	Name
enum class uint8_t	State { CREATING = 0, INITIALIZING, SYNCING, READY} State of the Transaction Manager.
enum class uint8_t	TransactionStatus { CREATED, SENDING, CONFIRMED, VERIFYING, FAILED, INVALID} Status of a transaction.
enum class uint8_t	WitnessValidationResult
using std::pair< std::shared_ptr< GeniusTransaction >, std::optional< std::vector< uint8_t > > >	TransactionPair
using std::vector< TransactionPair >	TransactionBatch
using std::pair< TransactionBatch, std::optional< std::shared_ptr< crdt::AtomicTransaction > > >	TransactionItem
using std::function< void(const State &previous, const State &current)>	StateChangeCallback

Public Functions¶

	Name
std::shared_ptr< TransactionManager >	New(std::shared_ptr< crdt::GlobalDB > processing_db, std::shared_ptr< boost::asio::io_context > ctx, std::shared_ptr< GeniusAccount > account, std::shared_ptr< crypto::Hasher > hasher, std::shared_ptr< Blockchain > blockchain, bool full_node =false, std::chrono::milliseconds timestamp_tolerance =std::chrono::milliseconds(300000), std::chrono::milliseconds mutability_window =std::chrono::milliseconds(0)) Factory constructor of the TransactionManager.
std::string	GetTransactionPath(uint16_t base, const std::string & tx_hash)
std::string	GetTransactionPath(const GeniusTransaction & element)
std::string	GetTransactionPath(const std::string & tx_hash)
std::string	GetTransactionProofPath(const GeniusTransaction & element)
outcome::result< std::shared_ptr< GeniusTransaction > >	FetchTransaction(const std::shared_ptr< crdt::GlobalDB > & db, std::string_view transaction_key) Fetches and deserializes a transaction from the CRDT by key.
outcome::result< std::shared_ptr< GeniusTransaction > >	DeSerializeTransaction(const base::Buffer & tx_data)
std::string	StateToString(State state)
std::string	GetBlockChainBase(uint16_t network_id) Builds the blockchain key prefix "/bc-/" for the given network.
std::string	GetBlockChainBase() Overload using the current network ID.
outcome::result< std::shared_ptr< GeniusTransaction > >	DeSerializeTransaction(std::string tx_data)
outcome::result< std::shared_ptr< GeniusTransaction > >	DeSerializeEmbeddedTransaction(const EmbeddedTransaction & embedded) Deserializes from EmbeddedTransaction proto oneof field. Dispatches on the oneof case instead of manual type string lookup.
	~TransactionManager()
void	Start()
void	RegisterTopicNames()
void	StartListeningTopics()
void	StartCore()
void	PrintAccountInfo() const
std::vector< std::vector< uint8_t > >	GetOutTransactions() const
std::vector< std::vector< uint8_t > >	GetInTransactions() const
std::vector< std::vector< uint8_t > >	GetTransactions(std::optional< TransactionStatus > tx_status =std::nullopt) const
std::vector< std::vector< uint8_t > >	GetTransactions() const
outcome::result< std::string >	TransferFunds(uint64_t amount, std::string destination, TokenID token_id) Creates and enqueues a transfer transaction.
outcome::result< std::string >	MintFunds(uint64_t amount, std::string transaction_hash, std::string chainid, TokenID tokenid, std::string destination ="") Creates and enqueues a mint transaction.
outcome::result< std::string >	MigrationFunds(uint64_t amount, std::string from_version, TokenID tokenid, std::string destination ="") Creates and enqueues a one-time migration mint transaction.
outcome::result< std::pair< std::string, EscrowDataPair > >	HoldEscrow(uint64_t amount, const std::string & dev_addr, uint64_t peers_cut, const std::string & job_id) Creates and enqueues an escrow-hold transaction.
outcome::result< std::string >	PayEscrow(const std::string & escrow_path, const SGProcessing::TaskResult & task_result, std::shared_ptr< crdt::AtomicTransaction > crdt_transaction)
TransactionStatus	WaitForTransactionIncoming(const std::string & txId, std::chrono::milliseconds timeout) const
TransactionStatus	WaitForTransactionOutgoing(const std::string & txId, std::chrono::milliseconds timeout) const
TransactionStatus	WaitForEscrowRelease(const std::string & originalEscrowId, std::chrono::milliseconds timeout) const Polls until an EscrowReleaseTransaction referencing `originalEscrowId` reaches a terminal state or `timeout` expires.
State	GetState() const
TransactionStatus	GetOutgoingStatusByTxId(const std::string & txId) const
TransactionStatus	GetIncomingStatusByTxId(const std::string & txId) const
outcome::result< std::shared_ptr< GeniusTransaction > >	GetConflictingTransaction(const GeniusTransaction & element) const Finds a tracked transaction that shares the same nonce and source address as `element`.
void	Stop() Idempotent stop. Sets the stopped flag and wakes the tick loop.
void	RegisterStateChangeCallback(StateChangeCallback callback)
void	UnregisterStateChangeCallback()
outcome::result< void >	QueryTransactions() Queries all transaction keys from the CRDT across monitored networks and processes each one via FetchAndProcessTransaction.
outcome::result< void >	FetchAndProcessTransaction(const std::string & tx_key, std::optional< base::Buffer > tx_data =std::nullopt) Deserializes, parses, and adds a single transaction to the processed map.
outcome::result< std::string >	GetTransactionCID(const std::string & tx_hash) const Looks up the CID associated with a transaction hash in RocksDB, searching across all monitored networks.
outcome::result< ConsensusManager::Check >	HandleNonceConsensusSubject(const ConsensusManager::Subject & subject)
bool	ValidateTransactionForConsensus(const std::shared_ptr< GeniusTransaction > & tx) const
bool	CheckTransactionWellFormed(const GeniusTransaction & tx) const
bool	CheckTransactionAuthorization(const GeniusTransaction & tx) const
bool	CheckTransactionTimestamp(const GeniusTransaction & tx) const
bool	CheckTransactionReplayProtection(const GeniusTransaction & tx) const
bool	CheckTransactionTypeRules(const std::shared_ptr< GeniusTransaction > & tx) const
std::optional< UTXOTransitionCommitment >	BuildUTXOTransitionCommitment(const std::shared_ptr< GeniusTransaction > & tx) const
std::optional< UTXOWitness >	BuildUTXOWitness(const std::shared_ptr< GeniusTransaction > & tx) const
bool	ApplyTransactionToUTXOSnapshot(const std::shared_ptr< GeniusTransaction > & tx, std::vector< GeniusUTXO > & snapshot) const
WitnessValidationResult	ValidateWitnessForConsensus(const ConsensusSubject & subject, const std::shared_ptr< GeniusTransaction > & tx) const
bool	ValidateUTXOParametersForConsensus(const UTXOTxParameters & params, const std::string & address) const
void	SetNonceWindow(uint64_t window)
outcome::result< void >	ChangeTransactionState(const std::shared_ptr< GeniusTransaction > & tx, TransactionStatus new_status)
bool	HasConfirmedInputConflict(const std::shared_ptr< GeniusTransaction > & candidate_tx) const
bool	IsGoingToOverwrite(const std::string & key) const
PublicChainInputValidator &	GetPublicChainInputValidator() Obtains the public-chain input validator for RPC endpoint wiring.
const PublicChainInputValidator &	GetPublicChainInputValidator() const Obtains the public-chain input validator for RPC endpoint wiring (const).

Protected Functions¶

	Name
void	EnqueueTransaction(TransactionPair element)
void	EnqueueTransaction(TransactionItem element)
void	SetTimeFrameToleranceMs(uint64_t timeframe_tolerance)
void	SetMutabilityWindowMs(uint64_t mutability_window)

Public Attributes¶

	Name
std::string_view	GNUS_FULL_NODES_TOPIC
std::string_view	GNUS_FULL_NODES_TOPIC_LEGACY
uint64_t	NONCE_REQUEST_TIMEOUT_MS Unified timeout for all nonce requests (10 seconds).

Friends¶

	Name
class	GeniusNode
class	Migration3_6_0To3_7_0
class	CertificateFallbackTestAccess

Public Types Documentation¶

enum State¶

Enumerator	Value	Description
CREATING	0	Creating the object.
INITIALIZING		Initializing the object.
SYNCING		Syncing the transactions.
READY		Ready to process transactions.

State of the Transaction Manager.

enum TransactionStatus¶

Enumerator	Value	Description
CREATED		Transaction created but not yet sent.
SENDING		Transaction is being sent.
CONFIRMED		Transaction confirmed.
VERIFYING		Transaction being verified.
FAILED		Transaction failed.
INVALID		Invalid transaction.

Status of a transaction.

enum WitnessValidationResult¶

Enumerator	Value	Description
VALID
DRIFT
INVALID

using TransactionPair¶

using sgns::TransactionManager::TransactionPair = std::pair<std::shared_ptr<GeniusTransaction>, std::optional<std::vector<uint8_t>>>;

using TransactionBatch¶

using sgns::TransactionManager::TransactionBatch = std::vector<TransactionPair>;

using TransactionItem¶

using sgns::TransactionManager::TransactionItem = std::pair<TransactionBatch, std::optional<std::shared_ptr<crdt::AtomicTransaction>>>;

using StateChangeCallback¶

using sgns::TransactionManager::StateChangeCallback = std::function<void( const State &previous, const State &current )>;

Public Functions Documentation¶

function New¶

static std::shared_ptr< TransactionManager > New(
    std::shared_ptr< crdt::GlobalDB > processing_db,
    std::shared_ptr< boost::asio::io_context > ctx,
    std::shared_ptr< GeniusAccount > account,
    std::shared_ptr< crypto::Hasher > hasher,
    std::shared_ptr< Blockchain > blockchain,
    bool full_node =false,
    std::chrono::milliseconds timestamp_tolerance =std::chrono::milliseconds(300000),
    std::chrono::milliseconds mutability_window =std::chrono::milliseconds(0)
)

Factory constructor of the TransactionManager.

Parameters:

processing_db Database of the CRDT
ctx The io context used to run its inner methods
account Genius account to be used
hasher Hasher to be used
full_node Parameter to indicate if the account is a full node
timestamp_tolerance Time to analyze a transaction with the same nonce/key
mutability_window Window of time where a transaction can be modified

Return: shared_ptr to the fully-wired TransactionManager instance

Note:

Default timestamp_tolerance is 5 minutes (300000 ms)
Default mutability_window is 10 minutes (600000 ms)
timestamp_tolerance must be smaller than mutability_window

function GetTransactionPath¶

static std::string GetTransactionPath(
    uint16_t base,
    const std::string & tx_hash
)

function GetTransactionPath¶

static std::string GetTransactionPath(
    const GeniusTransaction & element
)

function GetTransactionPath¶

static std::string GetTransactionPath(
    const std::string & tx_hash
)

function GetTransactionProofPath¶

static std::string GetTransactionProofPath(
    const GeniusTransaction & element
)

function FetchTransaction¶

static outcome::result< std::shared_ptr< GeniusTransaction > > FetchTransaction(
    const std::shared_ptr< crdt::GlobalDB > & db,
    std::string_view transaction_key
)

Fetches and deserializes a transaction from the CRDT by key.

function DeSerializeTransaction¶

static outcome::result< std::shared_ptr< GeniusTransaction > > DeSerializeTransaction(
    const base::Buffer & tx_data
)

function StateToString¶

static inline std::string StateToString(
    State state
)

function GetBlockChainBase¶

static std::string GetBlockChainBase(
    uint16_t network_id
)

Builds the blockchain key prefix "/bc-/" for the given network.

function GetBlockChainBase¶

static std::string GetBlockChainBase()

Overload using the current network ID.

function DeSerializeTransaction¶

static outcome::result< std::shared_ptr< GeniusTransaction > > DeSerializeTransaction(
    std::string tx_data
)

function DeSerializeEmbeddedTransaction¶

static outcome::result< std::shared_ptr< GeniusTransaction > > DeSerializeEmbeddedTransaction(
    const EmbeddedTransaction & embedded
)

Deserializes from EmbeddedTransaction proto oneof field. Dispatches on the oneof case instead of manual type string lookup.

function ~TransactionManager¶

~TransactionManager()

function Start¶

void Start()

function RegisterTopicNames¶

void RegisterTopicNames()

function StartListeningTopics¶

void StartListeningTopics()

function StartCore¶

void StartCore()

function PrintAccountInfo¶

void PrintAccountInfo() const

function GetOutTransactions¶

std::vector< std::vector< uint8_t > > GetOutTransactions() const

function GetInTransactions¶

std::vector< std::vector< uint8_t > > GetInTransactions() const

function GetTransactions¶

std::vector< std::vector< uint8_t > > GetTransactions(
    std::optional< TransactionStatus > tx_status =std::nullopt
) const

function GetTransactions¶

std::vector< std::vector< uint8_t > > GetTransactions() const

function TransferFunds¶

outcome::result< std::string > TransferFunds(
    uint64_t amount,
    std::string destination,
    TokenID token_id
)

Creates and enqueues a transfer transaction.

Parameters:

amount Amount to transfer.
destination Recipient address.
token_id Token being transferred.

Return: Transaction hash on success.

function MintFunds¶

outcome::result< std::string > MintFunds(
    uint64_t amount,
    std::string transaction_hash,
    std::string chainid,
    TokenID tokenid,
    std::string destination =""
)

Creates and enqueues a mint transaction.

Parameters:

amount Amount to mint.
transaction_hash Source-chain transaction hash used as the previous hash in the DAG.
chainid Originating chain identifier.
tokenid Token to mint.
destination Recipient address; defaults to the local account address when empty.

Return: Transaction hash on success.

function MigrationFunds¶

outcome::result< std::string > MigrationFunds(
    uint64_t amount,
    std::string from_version,
    TokenID tokenid,
    std::string destination =""
)

Creates and enqueues a one-time migration mint transaction.

Parameters:

amount Amount to migrate.
from_version Legacy version namespace for the migration source key.
tokenid Token to mint.
destination Recipient address; defaults to the local account address when empty.

Return: Transaction hash on success.

function HoldEscrow¶

outcome::result< std::pair< std::string, EscrowDataPair > > HoldEscrow(
    uint64_t amount,
    const std::string & dev_addr,
    uint64_t peers_cut,
    const std::string & job_id
)

Creates and enqueues an escrow-hold transaction.

Parameters:

amount Total amount to lock in escrow.
dev_addr Developer address that receives the remainder after peer payouts.
peers_cut Multiplier (as a TokenAmount) applied to the escrow amount to calculate the per-peer share.
job_id Job identifier whose blake2b-256 hash becomes the escrow destination address.

Return: Pair of (transaction hash, (escrow address, serialized transaction)) on success.

Hashes job_id with blake2b-256 to derive the escrow destination address, selects UTXOs, reserves them, and signs the transaction.

function PayEscrow¶

outcome::result< std::string > PayEscrow(
    const std::string & escrow_path,
    const SGProcessing::TaskResult & task_result,
    std::shared_ptr< crdt::AtomicTransaction > crdt_transaction
)

function WaitForTransactionIncoming¶

TransactionStatus WaitForTransactionIncoming(
    const std::string & txId,
    std::chrono::milliseconds timeout
) const

function WaitForTransactionOutgoing¶

TransactionStatus WaitForTransactionOutgoing(
    const std::string & txId,
    std::chrono::milliseconds timeout
) const

function WaitForEscrowRelease¶

TransactionStatus WaitForEscrowRelease(
    const std::string & originalEscrowId,
    std::chrono::milliseconds timeout
) const

Polls until an EscrowReleaseTransaction referencing originalEscrowId reaches a terminal state or timeout expires.

Return: TransactionStatus of the release tx, or INVALID if not found within timeout.

function GetState¶

inline State GetState() const

function GetOutgoingStatusByTxId¶

TransactionStatus GetOutgoingStatusByTxId(
    const std::string & txId
) const

function GetIncomingStatusByTxId¶

TransactionStatus GetIncomingStatusByTxId(
    const std::string & txId
) const

function GetConflictingTransaction¶

outcome::result< std::shared_ptr< GeniusTransaction > > GetConflictingTransaction(
    const GeniusTransaction & element
) const

Finds a tracked transaction that shares the same nonce and source address as element.

Return: The conflicting transaction, or failure if none exists.

function Stop¶

void Stop()

Idempotent stop. Sets the stopped flag and wakes the tick loop.

function RegisterStateChangeCallback¶

void RegisterStateChangeCallback(
    StateChangeCallback callback
)

function UnregisterStateChangeCallback¶

void UnregisterStateChangeCallback()

function QueryTransactions¶

outcome::result< void > QueryTransactions()

Queries all transaction keys from the CRDT across monitored networks and processes each one via FetchAndProcessTransaction.

function FetchAndProcessTransaction¶

outcome::result< void > FetchAndProcessTransaction(
    const std::string & tx_key,
    std::optional< base::Buffer > tx_data =std::nullopt
)

Deserializes, parses, and adds a single transaction to the processed map.

Parameters:

tx_key Full CRDT key of the transaction.
tx_data Optional pre-fetched serialized data (avoids a CRDT read).

Skips transactions that are already tracked. When tx_data is provided it is deserialized directly; otherwise the transaction is fetched from the CRDT by tx_key. On success the peer nonce is updated and the transaction is recorded as CONFIRMED.

function GetTransactionCID¶

outcome::result< std::string > GetTransactionCID(
    const std::string & tx_hash
) const

Looks up the CID associated with a transaction hash in RocksDB, searching across all monitored networks.

function HandleNonceConsensusSubject¶

outcome::result< ConsensusManager::Check > HandleNonceConsensusSubject(
    const ConsensusManager::Subject & subject
)

function ValidateTransactionForConsensus¶

bool ValidateTransactionForConsensus(
    const std::shared_ptr< GeniusTransaction > & tx
) const

function CheckTransactionWellFormed¶

bool CheckTransactionWellFormed(
    const GeniusTransaction & tx
) const

function CheckTransactionAuthorization¶

bool CheckTransactionAuthorization(
    const GeniusTransaction & tx
) const

function CheckTransactionTimestamp¶

bool CheckTransactionTimestamp(
    const GeniusTransaction & tx
) const

function CheckTransactionReplayProtection¶

bool CheckTransactionReplayProtection(
    const GeniusTransaction & tx
) const

function CheckTransactionTypeRules¶

bool CheckTransactionTypeRules(
    const std::shared_ptr< GeniusTransaction > & tx
) const

function BuildUTXOTransitionCommitment¶

std::optional< UTXOTransitionCommitment > BuildUTXOTransitionCommitment(
    const std::shared_ptr< GeniusTransaction > & tx
) const

function BuildUTXOWitness¶

std::optional< UTXOWitness > BuildUTXOWitness(
    const std::shared_ptr< GeniusTransaction > & tx
) const

function ApplyTransactionToUTXOSnapshot¶

bool ApplyTransactionToUTXOSnapshot(
    const std::shared_ptr< GeniusTransaction > & tx,
    std::vector< GeniusUTXO > & snapshot
) const

function ValidateWitnessForConsensus¶

WitnessValidationResult ValidateWitnessForConsensus(
    const ConsensusSubject & subject,
    const std::shared_ptr< GeniusTransaction > & tx
) const

function ValidateUTXOParametersForConsensus¶

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

function SetNonceWindow¶

void SetNonceWindow(
    uint64_t window
)

function ChangeTransactionState¶

outcome::result< void > ChangeTransactionState(
    const std::shared_ptr< GeniusTransaction > & tx,
    TransactionStatus new_status
)

function HasConfirmedInputConflict¶

bool HasConfirmedInputConflict(
    const std::shared_ptr< GeniusTransaction > & candidate_tx
) const

function IsGoingToOverwrite¶

bool IsGoingToOverwrite(
    const std::string & key
) const

function GetPublicChainInputValidator¶

inline PublicChainInputValidator & GetPublicChainInputValidator()

Obtains the public-chain input validator for RPC endpoint wiring.

Return: Mutable reference to the PublicChainInputValidator.

function GetPublicChainInputValidator¶

inline const PublicChainInputValidator & GetPublicChainInputValidator() const

Obtains the public-chain input validator for RPC endpoint wiring (const).

Return: Const reference to the PublicChainInputValidator.

Protected Functions Documentation¶

function EnqueueTransaction¶

void EnqueueTransaction(
    TransactionPair element
)

function EnqueueTransaction¶

void EnqueueTransaction(
    TransactionItem element
)

function SetTimeFrameToleranceMs¶

void SetTimeFrameToleranceMs(
    uint64_t timeframe_tolerance
)

function SetMutabilityWindowMs¶

void SetMutabilityWindowMs(
    uint64_t mutability_window
)

Public Attributes Documentation¶

variable GNUS_FULL_NODES_TOPIC¶

static std::string_view GNUS_FULL_NODES_TOPIC = "SuperGNUSNode.TestNet.FullNode";

variable GNUS_FULL_NODES_TOPIC_LEGACY¶

static std::string_view GNUS_FULL_NODES_TOPIC_LEGACY = "SuperGNUSNode.TestNet.FullNode.963";

variable NONCE_REQUEST_TIMEOUT_MS¶

static uint64_t NONCE_REQUEST_TIMEOUT_MS                                                        =
5000;

Unified timeout for all nonce requests (10 seconds).

Friends¶

friend GeniusNode¶

friend class GeniusNode(
    GeniusNode 
);

friend Migration3_6_0To3_7_0¶

friend class Migration3_6_0To3_7_0(
    Migration3_6_0To3_7_0 
);

friend CertificateFallbackTestAccess¶

friend class CertificateFallbackTestAccess(
    CertificateFallbackTestAccess 
);

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