---

title: transaction/TransactionConsensusHandler.hpp summary: Consensus-facing half of TransactionManager: subject validation, certificate finalization, proposal-timeout cleanup and UTXO commitment/witness payloads.

---

transaction/TransactionConsensusHandler.hpp

Consensus-facing half of TransactionManager: subject validation, certificate finalization, proposal-timeout cleanup and UTXO commitment/witness payloads. More...

Namespaces

Name
sgns

Classes

	Name
class	sgns::TransactionConsensusHandler Validates and finalizes transactions on behalf of consensus.
struct	sgns::TransactionConsensusHandler::Metrics Snapshot of the consensus counters, for the manager's shutdown log.
struct	sgns::TransactionConsensusHandler::ReplayProtectionResult Result of replay-protection evaluation for a consensus subject.

Detailed Description

Consensus-facing half of TransactionManager: subject validation, certificate finalization, proposal-timeout cleanup and UTXO commitment/witness payloads.

Date: 2026-09-08 Eduardo Menges Mattje ([email protected])

Source code

#ifndef SGNS_ACCOUNT_TRANSACTION_CONSENSUS_HANDLER_HPP
#define SGNS_ACCOUNT_TRANSACTION_CONSENSUS_HANDLER_HPP

#include <atomic>
#include <cstdint>
#include <optional>
#include <string>

#include "base/logger.hpp"
#include "blockchain/Consensus.hpp"
#include "outcome/outcome.hpp"

namespace sgns
{
    class GeniusTransaction;
    class TransactionManager;

    class TransactionConsensusHandler
    {
    public:
        enum class WitnessValidationResult : uint8_t
        {
            VALID,
            DRIFT,
            PENDING, 
            INVALID
        };

        struct Metrics
        {
            uint64_t cert_fallback_success_;
            uint64_t cert_fallback_failure_;
            uint64_t validation_approve_;
            uint64_t validation_reject_;
        };

        TransactionConsensusHandler( TransactionManager &owner, base::Logger logger ) :
            owner_( owner ), logger_( std::move( logger ) )
        {
        }

        outcome::result<ConsensusManager::Check> OnConsensusCertificate( const std::string          &tx_hash,
                                                                         const ConsensusCertificate &certificate );

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

        void OnProposalTimeoutCleanup( const std::string &tx_hash );

        struct ReplayProtectionResult
        {
            ConsensusManager::ValidationResult validation = ConsensusManager::ValidationResult::Approve();
        };

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

        ReplayProtectionResult EvaluateTransactionReplayProtection( const GeniusTransaction &tx ) const;

        WitnessValidationResult ValidateWitnessForConsensus( const ConsensusSubject  &subject,
                                                             const GeniusTransaction &tx ) const;

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

        [[nodiscard]] Metrics SnapshotMetrics() const
        {
            return { metrics_cert_fallback_success_.load(),
                     metrics_cert_fallback_failure_.load(),
                     metrics_validation_approve_.load(),
                     metrics_validation_reject_.load() };
        }

    private:
        ConsensusManager::ValidationResult ValidateTransactionForConsensus( const GeniusTransaction &tx ) const;
        bool                               CheckTransactionWellFormed( const GeniusTransaction &tx ) const;
        bool                               CheckTransactionTimestamp( const GeniusTransaction &tx ) const;
        bool                               CheckTransactionTypeRules( const GeniusTransaction &tx ) const;

        TransactionManager &owner_;
        base::Logger        logger_;

        static constexpr uint64_t NONCE_WINDOW = 5;

        std::atomic<uint64_t> metrics_cert_fallback_success_{ 0 };
        std::atomic<uint64_t> metrics_cert_fallback_failure_{ 0 };
        std::atomic<uint64_t> metrics_validation_approve_{ 0 };
        std::atomic<uint64_t> metrics_validation_reject_{ 0 };
    };
}

#endif // SGNS_ACCOUNT_TRANSACTION_CONSENSUS_HANDLER_HPP

---

Updated on 2026-09-29 at 16:45:11 +0000