trustedpeer/TrustStateStore.hpp

Crash-safe local authority for confirmed trust state.

Namespaces

Name
sgns
sgns::storage
sgns::trustedpeer

Classes

	Name
struct	sgns::trustedpeer::ConfirmedBurnState
struct	sgns::trustedpeer::ConfirmedTrustSnapshot
class	sgns::trustedpeer::TrustStateStore Synchronous, network-scoped last-known-good trust store.

Types

	Name
enum class uint8_t	BurnAuthorizationKind

Functions

	Name
std::string	BurnGenesisAnchorHash(const std::string & genesis_fingerprint)
	OUTCOME_HPP_DECLARE_ERROR_2(sgns::trustedpeer , TrustStateStore::Error )

Types Documentation

enum BurnAuthorizationKind

Enumerator	Value	Description
BootstrapOnly	0
PeerQuorum

Functions Documentation

function BurnGenesisAnchorHash

std::string BurnGenesisAnchorHash(
    const std::string & genesis_fingerprint
)

Domain-separated predecessor used by the deterministic burn v1 candidate.

function OUTCOME_HPP_DECLARE_ERROR_2

OUTCOME_HPP_DECLARE_ERROR_2(
    sgns::trustedpeer ,
    TrustStateStore::Error 
)

Source code

#ifndef SUPERGENIUS_TRUST_STATE_STORE_HPP
#define SUPERGENIUS_TRUST_STATE_STORE_HPP

#include <cstdint>
#include <functional>
#include <memory>
#include <mutex>
#include <optional>
#include <string>
#include <utility>
#include <vector>

#include "base/buffer.hpp"
#include "multisig/MultiSig.hpp"
#include "outcome/outcome.hpp"
#include "trustedpeer/GenesisManifest.hpp"
#include "trustedpeer/QuorumPolicy.hpp"

namespace sgns::storage
{
    class rocksdb;
}

namespace sgns::trustedpeer
{
    struct ConfirmedBurnState
    {
        static constexpr uint8_t ENCODING_VERSION = 1;

        uint8_t     encoding_version = ENCODING_VERSION;
        uint16_t    network_id       = 0;
        uint64_t    version          = 0;
        std::string expected_previous_hash;
        std::string authorizing_policy_hash;
        uint64_t    basis_points = 0;

        [[nodiscard]] std::optional<std::vector<uint8_t>>      CanonicalBytes() const;
        [[nodiscard]] std::optional<std::string>               Hash() const;
        [[nodiscard]] static std::optional<ConfirmedBurnState> DecodeCanonical( const std::vector<uint8_t> &bytes );
        bool                                                   operator==( const ConfirmedBurnState &other ) const;
    };

    enum class BurnAuthorizationKind : uint8_t
    {
        BootstrapOnly = 0,
        PeerQuorum,
    };

    struct ConfirmedTrustSnapshot
    {
        GenesisManifest               genesis;
        std::string                   genesis_fingerprint;
        std::vector<uint8_t>          bootstrap_signature;
        QuorumPolicyState             policy;
        multisig::CollectedSignatures policy_proof;
        ConfirmedBurnState            burn;
        multisig::CollectedSignatures burn_proof;
        BurnAuthorizationKind         burn_authorization = BurnAuthorizationKind::BootstrapOnly;

        bool operator==( const ConfirmedTrustSnapshot &other ) const;
    };

    class TrustStateStore
    {
    public:
        enum class Error : uint8_t
        {
            NOT_FOUND = 0,
            ALREADY_INITIALIZED,
            NETWORK_MISMATCH,
            CORRUPT_GENESIS,
            CORRUPT_FINGERPRINT,
            INVALID_GENESIS_PROOF,
            MISSING_POLICY_RECORD,
            MISSING_BURN_RECORD,
            CORRUPT_POLICY_RECORD,
            CORRUPT_BURN_RECORD,
            INVALID_POLICY_PROOF,
            INVALID_BURN_PROOF,
            VERSION_DECREASE,
            VERSION_SKIP,
            WRONG_PREDECESSOR,
            WRONG_AUTHORIZER,
            INITIAL_BURN_NOT_CONFIRMED,
            STALE_HEAD,
            COMMIT_FAILED,
        };

        using Write          = std::pair<base::Buffer, base::Buffer>;
        using BatchCommitter = std::function<outcome::result<void>( storage::rocksdb &, const std::vector<Write> & )>;
        // Invoked after the policy history is verified but before the burn head
        // is read (crash-injection seam for tests).
        using LoadObserver = std::function<void()>;

        static outcome::result<std::shared_ptr<TrustStateStore>> Open( const std::string &path,
                                                                       uint16_t           network_id,
                                                                       BatchCommitter     committer = {},
                                                                       LoadObserver       load_observer = {} );

        outcome::result<ConfirmedTrustSnapshot> LoadAndVerify() const;
        outcome::result<ConfirmedTrustSnapshot> CommitGenesis( const GenesisManifest      &manifest,
                                                               const std::vector<uint8_t> &bootstrap_signature,
                                                               const std::vector<uint8_t> &authorization_bytes = {} );
        outcome::result<ConfirmedTrustSnapshot> CommitPolicySuccessor(
            const QuorumPolicyState             &candidate,
            const multisig::CollectedSignatures &proof,
            const std::vector<uint8_t>          &authorization_bytes = {} );
        outcome::result<ConfirmedTrustSnapshot> CommitBurnSuccessor(
            const ConfirmedBurnState            &candidate,
            const multisig::CollectedSignatures &proof,
            const std::vector<uint8_t>          &authorization_bytes = {} );

    private:
        TrustStateStore( std::shared_ptr<storage::rocksdb> database,
                         uint16_t                          network_id,
                         BatchCommitter                    committer,
                         LoadObserver                      load_observer );

        outcome::result<ConfirmedTrustSnapshot> LoadAndVerifyUnlocked() const;
        outcome::result<void> CommitWrites( const std::vector<Write> &writes );
        outcome::result<ConfirmedTrustSnapshot> CommitRecordAndHead( Write record_write, Write head_write );

        // Shared successor-chain invariants: identical for the policy and burn
        // chains, since both hang off the same monotonic-version/predecessor/
        // authorizer rules. Kept separate from the equal-version-replay and
        // domain-specific validation branches, which genuinely differ.
        outcome::result<void> CheckVersionSkip( uint64_t current_version, uint64_t candidate_version ) const;
        outcome::result<void> CheckPredecessorAndAuthorizer( const std::string &expected_previous_hash,
                                                             const std::string &authorizing_policy_hash,
                                                             const std::string &current_domain_hash,
                                                             const std::string &current_policy_hash ) const;

        std::shared_ptr<storage::rocksdb> database_;
        uint16_t                          network_id_ = 0;
        BatchCommitter                    committer_;
        LoadObserver                      load_observer_;
        mutable std::mutex                transition_mutex_;
    };

    [[nodiscard]] std::string BurnGenesisAnchorHash( const std::string &genesis_fingerprint );
} // namespace sgns::trustedpeer

OUTCOME_HPP_DECLARE_ERROR_2( sgns::trustedpeer, TrustStateStore::Error );

#endif // SUPERGENIUS_TRUST_STATE_STORE_HPP

---

Updated on 2026-09-25 at 15:46:12 +0000