sgns::TransactionManager¶

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

#include <TransactionManager.hpp>

Inherits from std::enable_shared_from_this< TransactionManager >

Public Classes¶

	Name
struct	TransactionCompletion Value delivered when an asynchronous outgoing-transaction wait completes.

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, UNCONFIRMED, 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
using std::function< void(TransactionCompletion)>	TransactionCompletionCallback

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< Blockchain > blockchain, bool full_node =true, uint16_t subnet_id =0, std::chrono::milliseconds timestamp_tolerance =std::chrono::milliseconds(300000), std::chrono::milliseconds mutability_window =std::chrono::milliseconds(0)) Factory constructor of the TransactionManager.
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< Blockchain > blockchain, NodeType node_type, uint16_t subnet_id =0, std::chrono::milliseconds timestamp_tolerance =std::chrono::milliseconds(300000), std::chrono::milliseconds mutability_window =std::chrono::milliseconds(0), uint64_t initial_burn_basis_points =BURN_BASIS_POINTS_DEFAULT, std::shared_ptr< sgns::account::BurnConfig > burn_config =nullptr) Factory constructor variant taking the deployment role.
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(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.
bool	CertificateMatchesTransaction(const ConsensusCertificate & certificate, const GeniusTransaction & transaction) Verifies that an already validated certificate certifies `transaction` itself.
	~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
size_t	CountTransactions(std::optional< TransactionStatus > tx_status =std::nullopt) const
TransactionStatus	GetTransactionStatusByTxId(const std::string & txId) 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 >	RegisterChild(std::string main_address, SGTransaction::RegistrationMetadata metadata, uint64_t sequence) Creates and enqueues a child-wallet registration transaction.
outcome::result< std::string >	RegisterChild(std::string main_address, SGTransaction::RegistrationMetadata metadata) Creates and enqueues a child-wallet registration transaction with auto-derived sequence.
outcome::result< std::string >	RecoverFromChild(std::string child_address, uint64_t amount, TokenID token_id) Creates and enqueues a transfer transaction recovering funds from a registered child wallet back to this account's own address (D-60/D-62/CONS-02).
outcome::result< std::string >	DetachChild(SGTransaction::RegistrationMetadata metadata, uint64_t sequence, uint64_t supersedes_sequence) Creates and enqueues a child-initiated Detach transaction (D-35).
outcome::result< std::string >	DetachChild(SGTransaction::RegistrationMetadata metadata) Creates and enqueues a child-initiated Detach transaction with auto-derived sequence.
outcome::result< std::string >	ReplaceMain(std::string new_main_address, SGTransaction::RegistrationMetadata metadata, uint64_t sequence, uint64_t supersedes_sequence) Creates and enqueues a child-initiated Replace-Main transaction (D-37).
outcome::result< std::string >	ReplaceMain(std::string new_main_address, SGTransaction::RegistrationMetadata metadata) Creates and enqueues a child-initiated Replace-Main transaction with auto-derived sequence.
outcome::result< std::string >	RevokeChild(std::string child_address) Creates and enqueues a main-initiated Revoke transaction (D-36).
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 & 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)
void	AsyncPayEscrow(std::string escrow_path, SGProcessing::TaskResult task_result, std::shared_ptr< crdt::AtomicTransaction > crdt_transaction, std::chrono::milliseconds timeout, TransactionCompletionCallback callback) Submits an escrow payout and observes it without blocking for confirmation.
void	AsyncWaitForTransactionOutgoing(std::string tx_id, std::chrono::milliseconds timeout, TransactionCompletionCallback callback) Asynchronously observes an already-tracked outgoing 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< ConsensusCertificate >	GetTransactionCertificate(const GeniusTransaction & transaction) const Loads the transaction's validated certificate from either durable index.
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::ValidationResult >	HandleNonceConsensusSubject(const ConsensusManager::Subject & subject)
ConsensusManager::ValidationResult	ValidateTransactionForConsensus(const std::shared_ptr< GeniusTransaction > & tx) const
bool	CheckTransactionWellFormed(const GeniusTransaction & tx) const
bool	CheckTransactionAuthorization(const GeniusTransaction & tx) const
bool	CheckParentChildAuthority(const GeniusTransaction & tx) const
bool	CheckTransactionTimestamp(const GeniusTransaction & tx) const
bool	CheckTransactionReplayProtection(const GeniusTransaction & tx) const
ReplayProtectionResult	EvaluateTransactionReplayProtection(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	KeyExistsInDB(const std::string & key) const
outcome::result< std::vector< RegistrationDiscoveryEntry > >	GetRegistrationsForMain(const std::string & main_address) Enumerates child registrations naming a specific main wallet.
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
constexpr std::string_view	GNUS_FULL_NODES_TOPIC
constexpr std::string_view	GNUS_FULL_NODES_TOPIC_LEGACY
constexpr uint64_t	NONCE_REQUEST_TIMEOUT_MS Unified timeout for all nonce requests (10 seconds)
constexpr uint64_t	BURN_BASIS_POINTS_DEFAULT
constexpr uint64_t	BASIS_POINTS_TOTAL
constexpr std::string_view	BURN_ADDRESS Fixed destination of the burn slice of an escrow payout.

Friends¶

	Name
class	GeniusNode
class	Migration3_6_0To3_7_0
class	CertificateFallbackTestAccess
class	TransactionManagerPendingLifecycleTestAccess
class	RegistrationE2ETestAccess
class	RegTestAccess
class	MultiNodeFinalityFaultTestAccess
class	PayoutOutputsTestAccess
class	MultiAccountTestAccess

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.
UNCONFIRMED		Local outgoing transaction expired inconclusively.
FAILED		Transaction failed.
INVALID		Invalid transaction.

Status of a transaction.

enum WitnessValidationResult¶

Enumerator	Value	Description
VALID
DRIFT
PENDING		A producer dependency (transaction or certificate) has not CRDT-synced yet: retryable, not evidence of invalidity.
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 )>;

using TransactionCompletionCallback¶

using sgns::TransactionManager::TransactionCompletionCallback =  std::function<void( TransactionCompletion )>;

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< Blockchain > blockchain,
    bool full_node =true,
    uint16_t subnet_id =0,
    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
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 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< Blockchain > blockchain,
    NodeType node_type,
    uint16_t subnet_id =0,
    std::chrono::milliseconds timestamp_tolerance =std::chrono::milliseconds(300000),
    std::chrono::milliseconds mutability_window =std::chrono::milliseconds(0),
    uint64_t initial_burn_basis_points =BURN_BASIS_POINTS_DEFAULT,
    std::shared_ptr< sgns::account::BurnConfig > burn_config =nullptr
)

Factory constructor variant taking the deployment role.

Parameters:

node_type Deployment role of this node (Full / Light / Archive). Full maps onto the legacy full-node behaviour (full-node topic subscription).
initial_burn_basis_points Burn slice used until BurnConfig publishes a quorum-signed value.
burn_config Optional BurnConfig whose refresh callback updates the cached burn slice at runtime.

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(
    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 CertificateMatchesTransaction¶

static bool CertificateMatchesTransaction(
    const ConsensusCertificate & certificate,
    const GeniusTransaction & transaction
)

Verifies that an already validated certificate certifies transaction itself.

Callers must locate the record through the transaction-derived canonical slot first. This supplies the second, exact-subject check required for shared slots, so a competing transaction cannot inherit finality.

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 CountTransactions¶

size_t CountTransactions(
    std::optional< TransactionStatus > tx_status =std::nullopt
) const

function GetTransactionStatusByTxId¶

TransactionStatus GetTransactionStatusByTxId(
    const std::string & txId
) 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 RegisterChild¶

outcome::result< std::string > RegisterChild(
    std::string main_address,
    SGTransaction::RegistrationMetadata metadata,
    uint64_t sequence
)

Creates and enqueues a child-wallet registration transaction.

Parameters:

main_address Main wallet public address (128-hex).
metadata Optional registration metadata (game_id, publisher_id, dev_wallet, peers_cut).
sequence Registration sequence number (caller-supplied per D-42).

Return: Transaction hash on success.

function RegisterChild¶

outcome::result< std::string > RegisterChild(
    std::string main_address,
    SGTransaction::RegistrationMetadata metadata
)

Creates and enqueues a child-wallet registration transaction with auto-derived sequence.

Parameters:

main_address Main wallet public address (128-hex).
metadata Optional registration metadata (game_id, publisher_id, dev_wallet, peers_cut).

Return: Transaction hash on success.

Reads the existing reg/{child_addr} CRDT record and uses stored sequence + 1 (or 1 if no prior registration exists).

function RecoverFromChild¶

outcome::result< std::string > RecoverFromChild(
    std::string child_address,
    uint64_t amount,
    TokenID token_id
)

Creates and enqueues a transfer transaction recovering funds from a registered child wallet back to this account's own address (D-60/D-62/CONS-02).

Parameters:

child_address Registered child wallet address to recover funds from.
amount Amount to recover.
token_id Token being recovered.

Return: Transaction hash on success.

Selects UTXOs owned by child_address (never this account's own UTXOs), builds a DAGStruct scoped to child_address (child's own nonce/previous-hash chain, not this account's), and signs both the whole-transaction and every per-input signature with this account's own key. Consensus accepts the resulting transaction because the CRDT registration record certifies the parent-child relationship (Blockchain::CheckCertifiedParent), not because this account possesses the child's private key.

function DetachChild¶

outcome::result< std::string > DetachChild(
    SGTransaction::RegistrationMetadata metadata,
    uint64_t sequence,
    uint64_t supersedes_sequence
)

Creates and enqueues a child-initiated Detach transaction (D-35).

Parameters:

metadata Registration metadata carried forward on the lifecycle-change tx.
sequence New registration sequence number (caller-supplied).
supersedes_sequence Sequence of the reg/ record this Detach supersedes.

Return: Transaction hash on success.

Clears the registration's main_address to a 128-character zero-sentinel and sets detach_flag=true, superseding the current registration record. Child-signed only.

function DetachChild¶

outcome::result< std::string > DetachChild(
    SGTransaction::RegistrationMetadata metadata
)

Creates and enqueues a child-initiated Detach transaction with auto-derived sequence.

Parameters:

metadata Registration metadata carried forward on the lifecycle-change tx.

Return: Transaction hash on success.

Reads the existing reg/{child_addr} CRDT record and uses stored sequence + 1 as the new sequence and stored sequence as supersedes_sequence. Fails if no prior registration exists.

function ReplaceMain¶

outcome::result< std::string > ReplaceMain(
    std::string new_main_address,
    SGTransaction::RegistrationMetadata metadata,
    uint64_t sequence,
    uint64_t supersedes_sequence
)

Creates and enqueues a child-initiated Replace-Main transaction (D-37).

Parameters:

new_main_address New main wallet public address (128-hex).
metadata Registration metadata carried forward on the lifecycle-change tx.
sequence New registration sequence number (caller-supplied).
supersedes_sequence Sequence of the reg/ record this Replace-Main supersedes.

Return: Transaction hash on success.

Sets main_address to the caller-supplied new main and detach_flag=false, superseding the current registration record. Handles both Registered->Registered replacement AND re-registration from Detached/Revoked. Child-signed only — no consent from the old main.

function ReplaceMain¶

outcome::result< std::string > ReplaceMain(
    std::string new_main_address,
    SGTransaction::RegistrationMetadata metadata
)

Creates and enqueues a child-initiated Replace-Main transaction with auto-derived sequence.

Parameters:

new_main_address New main wallet public address (128-hex).
metadata Registration metadata carried forward on the lifecycle-change tx.

Return: Transaction hash on success.

Reads the existing reg/{child_addr} CRDT record and uses stored sequence + 1 as the new sequence and stored sequence as supersedes_sequence. Fails if no prior registration exists.

function RevokeChild¶

outcome::result< std::string > RevokeChild(
    std::string child_address
)

Creates and enqueues a main-initiated Revoke transaction (D-36).

Parameters:

child_address Registered child wallet address being revoked.

Return: Transaction hash on success.

Main-signed — this account is the tx's own source. Fails fast client-side if the target's reg/ record is absent or already detached, avoiding broadcast of a transaction CheckParentChildAuthority would reject anyway.

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 & job_id
)

Creates and enqueues an escrow-hold transaction.

Parameters:

amount Total amount to lock in escrow.
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 AsyncPayEscrow¶

void AsyncPayEscrow(
    std::string escrow_path,
    SGProcessing::TaskResult task_result,
    std::shared_ptr< crdt::AtomicTransaction > crdt_transaction,
    std::chrono::milliseconds timeout,
    TransactionCompletionCallback callback
)

Submits an escrow payout and observes it without blocking for confirmation.

Transaction construction is performed during initiation; confirmation is event-driven on the manager io_context. Pending observations are cancelled by Stop. The callback must not own the GeniusNode; capture immutable context or a weak observer instead.

function AsyncWaitForTransactionOutgoing¶

void AsyncWaitForTransactionOutgoing(
    std::string tx_id,
    std::chrono::milliseconds timeout,
    TransactionCompletionCallback callback
)

Asynchronously observes an already-tracked outgoing 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 GetTransactionCertificate¶

outcome::result< ConsensusCertificate > GetTransactionCertificate(
    const GeniusTransaction & transaction
) const

Loads the transaction's validated certificate from either durable index.

Prefers the authoritative canonical-slot record and falls back to the subject-hash index record (develop consumer contract). Callers must still pass the result through CertificateMatchesTransaction.

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::ValidationResult > HandleNonceConsensusSubject(
    const ConsensusManager::Subject & subject
)

function ValidateTransactionForConsensus¶

ConsensusManager::ValidationResult 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 CheckParentChildAuthority¶

bool CheckParentChildAuthority(
    const GeniusTransaction & tx
) const

function CheckTransactionTimestamp¶

bool CheckTransactionTimestamp(
    const GeniusTransaction & tx
) const

function CheckTransactionReplayProtection¶

bool CheckTransactionReplayProtection(
    const GeniusTransaction & tx
) const

function EvaluateTransactionReplayProtection¶

ReplayProtectionResult EvaluateTransactionReplayProtection(
    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 KeyExistsInDB¶

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

function GetRegistrationsForMain¶

outcome::result< std::vector< RegistrationDiscoveryEntry > > GetRegistrationsForMain(
    const std::string & main_address
)

Enumerates child registrations naming a specific main wallet.

Parameters:

main_address Main wallet public address (128-hex) to query for.

Return: Vector of RegistrationDiscoveryEntry on success.

Scans the reg/ CRDT namespace across all monitored networks and returns entries whose main_address matches main_address.

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 constexpr std::string_view GNUS_FULL_NODES_TOPIC = "SuperGNUSNode.TestNet.FullNode";

variable GNUS_FULL_NODES_TOPIC_LEGACY¶

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

variable NONCE_REQUEST_TIMEOUT_MS¶

static constexpr uint64_t NONCE_REQUEST_TIMEOUT_MS =
            5000;

Unified timeout for all nonce requests (10 seconds)

variable BURN_BASIS_POINTS_DEFAULT¶

static constexpr uint64_t BURN_BASIS_POINTS_DEFAULT = 100;

Fraction of an escrow payout burned to the zero address during PayEscrow, in basis points. Pre-quorum/genesis-absent fallback only – the live value is cached in burn_basis_points_ and refreshed via BurnConfig's quorum-signed CRDT value (BURN-02, BURN-03).

variable BASIS_POINTS_TOTAL¶

static constexpr uint64_t BASIS_POINTS_TOTAL = 10000;

variable BURN_ADDRESS¶

static constexpr std::string_view BURN_ADDRESS = "0x0000000000000000000000000000000000000000";

Fixed destination of the burn slice of an escrow payout.

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 
);

friend TransactionManagerPendingLifecycleTestAccess¶

friend class TransactionManagerPendingLifecycleTestAccess(
    TransactionManagerPendingLifecycleTestAccess 
);

friend RegistrationE2ETestAccess¶

friend class RegistrationE2ETestAccess(
    RegistrationE2ETestAccess 
);

friend RegTestAccess¶

friend class RegTestAccess(
    RegTestAccess 
);

friend MultiNodeFinalityFaultTestAccess¶

friend class MultiNodeFinalityFaultTestAccess(
    MultiNodeFinalityFaultTestAccess 
);

friend PayoutOutputsTestAccess¶

friend class PayoutOutputsTestAccess(
    PayoutOutputsTestAccess 
);

friend MultiAccountTestAccess¶

friend class MultiAccountTestAccess(
    MultiAccountTestAccess 
);

Updated on 2026-09-17 at 06:29:13 +0000