sgns::ValidatorRegistry¶

Maintains validator registry state and applies certificate-driven updates. More...

#include <ValidatorRegistry.hpp>

Inherits from std::enable_shared_from_this< ValidatorRegistry >

Public Classes¶

	Name
struct	WeightConfig Weight policy used to score validators and update penalties.

Public Types¶

	Name
enum class	BatchSubjectDecision { Approve, Reject, Pending} Decision result when evaluating a registry-batch subject.
enum class	BatchCertificateDecision { Approve, Reject, Pending, Stalled} Decision result when handling a registry-batch certificate.
using validator::ValidatorEntry	ValidatorEntry
using validator::Registry	Registry
using validator::SignatureEntry	SignatureEntry
using validator::RegistryUpdate	RegistryUpdate
using validator::Role	Role
using validator::Status	Status
using std::function< void(bool)>	InitCallback
using std::function< void(const std::string &, std::function< void(outcome::result< std::string >)>)>	BlockRequestMethod

Public Functions¶

	Name
std::shared_ptr< ValidatorRegistry >	New(std::shared_ptr< crdt::GlobalDB > db, uint64_t quorum_numerator, uint64_t quorum_denominator, WeightConfig weight_config, std::string genesis_authority, BlockRequestMethod block_request_method, InitCallback init_callback =nullptr) Creates and initializes a validator registry instance.
uint64_t	TotalWeight(const Registry & registry) Computes total effective weight in a registry snapshot.
std::string_view	RegistryKey() Registry object key used in datastore.
std::string_view	ValidatorTopic() Topic used to publish/subscribe validator registry updates.
std::string_view	RegistryCidKey() Key used to persist the current registry CID.
const ValidatorEntry *	FindValidator(const Registry & registry, const std::string & validator_id) Finds validator entry by id in a registry snapshot.
	~ValidatorRegistry() Destroys the registry instance.
uint64_t	ComputeWeight(Role role) const Computes default weight for a validator role.
uint64_t	QuorumThreshold(uint64_t total_weight) const Computes minimum accumulated weight required for quorum.
bool	IsQuorum(uint64_t accumulated_weight, uint64_t total_weight) const Checks whether accumulated weight satisfies quorum.
Registry	CreateGenesisRegistry(const std::string & genesis_validator_id) const Creates an in-memory genesis registry snapshot.
outcome::result< void >	StoreGenesisRegistry(const std::string & genesis_validator_id, std::function< std::vector< uint8_t >(std::vector< uint8_t >)> sign) Persists a signed genesis registry update.
outcome::result< Registry >	LoadRegistry() const Loads the currently active registry.
outcome::result< Registry >	LoadRegistry(const std::string & cid) const Loads a registry by CID.
outcome::result< RegistryUpdate >	LoadRegistryUpdate() const Loads the currently active registry update payload.
outcome::result< std::optional< uint64_t > >	GetValidatorWeight(const std::string & validator_id) const Looks up validator weight by validator id.
bool	RegisterFilter() Registers CRDT filter/callbacks for registry updates.
outcome::result< RegistryUpdate >	CreateUpdateFromCertificate(const sgns::ConsensusCertificate & certificate) Builds a registry update from a finalized certificate.
outcome::result< void >	StoreRegistryUpdate(const RegistryUpdate & update) Persists a registry update.
outcome::result< std::shared_ptr< crdt::AtomicTransaction > >	BeginRegistryUpdateTransaction(const RegistryUpdate & update) Starts an atomic transaction to apply a registry update.
void	SetMaxNewValidatorsPerUpdate(size_t max_new) Sets the maximum number of unregistered validators added per update.
outcome::result< std::vector< uint8_t > >	SerializeRegistry(const Registry & registry) const Serializes a registry protobuf.
outcome::result< Registry >	DeserializeRegistry(const std::vector< uint8_t > & buffer) const Deserializes a registry protobuf.
outcome::result< std::vector< uint8_t > >	SerializeRegistryUpdate(const RegistryUpdate & update) const Serializes a registry update protobuf.
outcome::result< RegistryUpdate >	DeserializeRegistryUpdate(const std::vector< uint8_t > & buffer) const Deserializes a registry update protobuf.
std::string	GetRegistryCid() const Returns cached/current registry CID.
uint64_t	GetRegistryEpoch() const Returns cached/current registry epoch.
void	SetCertificatesPerBatch(size_t batch_size) Sets certificate count threshold used when creating batch subjects.
void	SetBatchSubjectSubmitter(std::function< outcome::result< void >(const ConsensusSubject &subject)> submitter) Sets callback used to submit generated batch subjects.
void	OnFinalizedCertificate(const sgns::ConsensusCertificate & certificate) Handles a finalized consensus certificate.
outcome::result< BatchSubjectDecision >	EvaluateBatchSubject(const ConsensusSubject & subject) Evaluates a registry-batch subject payload.
outcome::result< BatchCertificateDecision >	HandleBatchCertificate(const std::string & subject_hash, const sgns::ConsensusCertificate & certificate) Handles certificate associated with a registry-batch subject.

Protected Functions¶

	Name
outcome::result< void >	MigrateCids(const std::shared_ptr< crdt::GlobalDB > & old_db, const std::shared_ptr< crdt::GlobalDB > & new_db) Migrates registry-related CIDs from old to new datastore.

Public Attributes¶

	Name
size_t	DefaultMaxNewValidatorsPerUpdate Default cap for new validators added per update.
size_t	DefaultCertificatesPerBatch Default number of certificates grouped per batch.

Friends¶

	Name
class	sgns::Migration3_5_0To3_6_0

Detailed Description¶

class sgns::ValidatorRegistry;

Maintains validator registry state and applies certificate-driven updates.

This component stores the active validator set in GlobalDB/CRDT, computes quorum thresholds, validates registry updates, and derives next registry snapshots from consensus certificates.

Public Types Documentation¶

enum BatchSubjectDecision¶

Enumerator	Value	Description
Approve		Subject is valid and should proceed.
Reject		Subject is invalid and should be rejected.
Pending		Subject cannot be decided yet.

Decision result when evaluating a registry-batch subject.

enum BatchCertificateDecision¶

Enumerator	Value	Description
Approve		Certificate is accepted.
Reject		Certificate is rejected.
Pending		Decision is deferred due to missing prerequisites.
Stalled		Processing is stalled and should be retried later.

Decision result when handling a registry-batch certificate.

using ValidatorEntry¶

using sgns::ValidatorRegistry::ValidatorEntry = validator::ValidatorEntry;

using Registry¶

using sgns::ValidatorRegistry::Registry = validator::Registry;

using SignatureEntry¶

using sgns::ValidatorRegistry::SignatureEntry = validator::SignatureEntry;

using RegistryUpdate¶

using sgns::ValidatorRegistry::RegistryUpdate = validator::RegistryUpdate;

using Role¶

using sgns::ValidatorRegistry::Role = validator::Role;

using Status¶

using sgns::ValidatorRegistry::Status = validator::Status;

using InitCallback¶

using sgns::ValidatorRegistry::InitCallback = std::function<void( bool )>;

using BlockRequestMethod¶

using sgns::ValidatorRegistry::BlockRequestMethod = 
std::function<void( const std::string &, std::function<void( outcome::result<std::string> )> )>;

Public Functions Documentation¶

function New¶

static std::shared_ptr< ValidatorRegistry > New(
    std::shared_ptr< crdt::GlobalDB > db,
    uint64_t quorum_numerator,
    uint64_t quorum_denominator,
    WeightConfig weight_config,
    std::string genesis_authority,
    BlockRequestMethod block_request_method,
    InitCallback init_callback =nullptr
)

Creates and initializes a validator registry instance.

Parameters:

db GlobalDB backing store.
quorum_numerator Numerator used for quorum threshold computation.
quorum_denominator Denominator used for quorum threshold computation.
weight_config Validator weighting and penalty configuration.
genesis_authority Validator id treated as genesis authority.
block_request_method Callback used to fetch blocks by CID.
init_callback Optional callback notified after initialization.

Return: Shared pointer to the created registry.

function TotalWeight¶

static uint64_t TotalWeight(
    const Registry & registry
)

Computes total effective weight in a registry snapshot.

Parameters:

registry Registry snapshot.

Return: Sum of validator weights.

function RegistryKey¶

static inline std::string_view RegistryKey()

Registry object key used in datastore.

Return: Constant registry key.

function ValidatorTopic¶

static inline std::string_view ValidatorTopic()

Topic used to publish/subscribe validator registry updates.

Return: Constant validator topic.

function RegistryCidKey¶

static inline std::string_view RegistryCidKey()

Key used to persist the current registry CID.

Return: Constant CID key.

function FindValidator¶

static const ValidatorEntry * FindValidator(
    const Registry & registry,
    const std::string & validator_id
)

Finds validator entry by id in a registry snapshot.

Parameters:

registry Registry snapshot.
validator_id Validator identifier.

Return: Pointer to entry when found, otherwise nullptr.

function ~ValidatorRegistry¶

~ValidatorRegistry()

Destroys the registry instance.

function ComputeWeight¶

uint64_t ComputeWeight(
    Role role
) const

Computes default weight for a validator role.

Parameters:

role Validator role.

Return: Weight associated with the role.

function QuorumThreshold¶

uint64_t QuorumThreshold(
    uint64_t total_weight
) const

Computes minimum accumulated weight required for quorum.

Parameters:

total_weight Total eligible weight.

Return: Quorum threshold.

function IsQuorum¶

bool IsQuorum(
    uint64_t accumulated_weight,
    uint64_t total_weight
) const

Checks whether accumulated weight satisfies quorum.

Parameters:

accumulated_weight Weight accumulated by votes.
total_weight Total eligible weight.

Return: true when quorum is reached.

function CreateGenesisRegistry¶

Registry CreateGenesisRegistry(
    const std::string & genesis_validator_id
) const

Creates an in-memory genesis registry snapshot.

Parameters:

genesis_validator_id Validator id for the genesis authority.

Return: Genesis registry snapshot.

function StoreGenesisRegistry¶

outcome::result< void > StoreGenesisRegistry(
    const std::string & genesis_validator_id,
    std::function< std::vector< uint8_t >(std::vector< uint8_t >)> sign
)

Persists a signed genesis registry update.

Parameters:

genesis_validator_id Validator id for the genesis authority.
sign Signing callback used for registry-update signatures.

Return: outcome::success on success, otherwise an error.

function LoadRegistry¶

outcome::result< Registry > LoadRegistry() const

Loads the currently active registry.

Return: Registry snapshot or an error.

function LoadRegistry¶

outcome::result< Registry > LoadRegistry(
    const std::string & cid
) const

Loads a registry by CID.

Parameters:

cid Registry CID.

Return: Registry snapshot or an error.

function LoadRegistryUpdate¶

outcome::result< RegistryUpdate > LoadRegistryUpdate() const

Loads the currently active registry update payload.

Return: Registry update or an error.

function GetValidatorWeight¶

outcome::result< std::optional< uint64_t > > GetValidatorWeight(
    const std::string & validator_id
) const

Looks up validator weight by validator id.

Parameters:

validator_id Validator identifier.

Return: Optional weight when validator exists, or an error.

function RegisterFilter¶

bool RegisterFilter()

Registers CRDT filter/callbacks for registry updates.

Return: true when registration succeeds.

function CreateUpdateFromCertificate¶

outcome::result< RegistryUpdate > CreateUpdateFromCertificate(
    const sgns::ConsensusCertificate & certificate
)

Builds a registry update from a finalized certificate.

Parameters:

certificate Consensus certificate.

Return: Registry update or an error.

function StoreRegistryUpdate¶

outcome::result< void > StoreRegistryUpdate(
    const RegistryUpdate & update
)

Persists a registry update.

Parameters:

update Registry update to store.

Return: outcome::success on success, otherwise an error.

function BeginRegistryUpdateTransaction¶

outcome::result< std::shared_ptr< crdt::AtomicTransaction > > BeginRegistryUpdateTransaction(
    const RegistryUpdate & update
)

Starts an atomic transaction to apply a registry update.

Parameters:

update Registry update being applied.

Return: Transaction handle or an error.

function SetMaxNewValidatorsPerUpdate¶

void SetMaxNewValidatorsPerUpdate(
    size_t max_new
)

Sets the maximum number of unregistered validators added per update.

Parameters:

max_new New cap value.

function SerializeRegistry¶

outcome::result< std::vector< uint8_t > > SerializeRegistry(
    const Registry & registry
) const

Serializes a registry protobuf.

Parameters:

registry Registry to serialize.

Return: Serialized bytes or an error.

function DeserializeRegistry¶

outcome::result< Registry > DeserializeRegistry(
    const std::vector< uint8_t > & buffer
) const

Deserializes a registry protobuf.

Parameters:

buffer Serialized registry bytes.

Return: Parsed registry or an error.

function SerializeRegistryUpdate¶

outcome::result< std::vector< uint8_t > > SerializeRegistryUpdate(
    const RegistryUpdate & update
) const

Serializes a registry update protobuf.

Parameters:

update Registry update to serialize.

Return: Serialized bytes or an error.

function DeserializeRegistryUpdate¶

outcome::result< RegistryUpdate > DeserializeRegistryUpdate(
    const std::vector< uint8_t > & buffer
) const

Deserializes a registry update protobuf.

Parameters:

buffer Serialized registry update bytes.

Return: Parsed update or an error.

function GetRegistryCid¶

std::string GetRegistryCid() const

Returns cached/current registry CID.

Return: Registry CID string.

function GetRegistryEpoch¶

uint64_t GetRegistryEpoch() const

Returns cached/current registry epoch.

Return: Registry epoch.

function SetCertificatesPerBatch¶

void SetCertificatesPerBatch(
    size_t batch_size
)

Sets certificate count threshold used when creating batch subjects.

Parameters:

batch_size Number of certificates per batch.

function SetBatchSubjectSubmitter¶

void SetBatchSubjectSubmitter(
    std::function< outcome::result< void >(const ConsensusSubject &subject)> submitter
)

Sets callback used to submit generated batch subjects.

Parameters:

submitter Subject submitter callback.

function OnFinalizedCertificate¶

void OnFinalizedCertificate(
    const sgns::ConsensusCertificate & certificate
)

Handles a finalized consensus certificate.

Parameters:

certificate Finalized certificate.

function EvaluateBatchSubject¶

outcome::result< BatchSubjectDecision > EvaluateBatchSubject(
    const ConsensusSubject & subject
)

Evaluates a registry-batch subject payload.

Parameters:

subject Subject to evaluate.

Return: Subject decision or an error.

function HandleBatchCertificate¶

outcome::result< BatchCertificateDecision > HandleBatchCertificate(
    const std::string & subject_hash,
    const sgns::ConsensusCertificate & certificate
)

Handles certificate associated with a registry-batch subject.

Parameters:

subject_hash Subject hash key.
certificate Certificate to process.

Return: Certificate handling decision or an error.

Protected Functions Documentation¶

function MigrateCids¶

static outcome::result< void > MigrateCids(
    const std::shared_ptr< crdt::GlobalDB > & old_db,
    const std::shared_ptr< crdt::GlobalDB > & new_db
)

Migrates registry-related CIDs from old to new datastore.

Parameters:

old_db Source GlobalDB.
new_db Target GlobalDB.

Return: outcome::success on success, otherwise an error.

Public Attributes Documentation¶

variable DefaultMaxNewValidatorsPerUpdate¶

static size_t DefaultMaxNewValidatorsPerUpdate                                                      =
10;

Default cap for new validators added per update.

variable DefaultCertificatesPerBatch¶

static size_t DefaultCertificatesPerBatch = 5;

Default number of certificates grouped per batch.

Friends¶

friend sgns::Migration3_5_0To3_6_0¶

friend class sgns::Migration3_5_0To3_6_0(
    sgns::Migration3_5_0To3_6_0 
);

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