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	SlotQuorumResult Result of the Phase 6 cumulative slot-quorum tally (D-06).
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, 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.
SlotQuorumResult	EvaluateSlotQuorumStatic(const std::vector< sgns::ConsensusVote > & votes, const Registry & registry, const WeightConfig & weight_config) Pure (stateless) slot-quorum tally for deterministic unit testing.
bool	EvaluateRegularPromotionStatic(const ValidatorEntry & entry, const WeightConfig & weight_config) Pure (stateless) REGULAR -> FULL promotion decision (D-08).
constexpr std::string_view	RegistryKey() Registry object key used in datastore.
constexpr std::string_view	ValidatorTopic() Topic used to publish/subscribe validator registry updates.
constexpr 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.
void	Close() Stops accepting registry work and waits for queued persistence to finish.
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.
SlotQuorumResult	EvaluateSlotQuorum(const std::vector< sgns::ConsensusVote > & votes, const Registry & registry) const Phase 6 cumulative slot-quorum tally for bridge-mint subjects (D-06).
Registry	CreateGenesisRegistry(const std::vector< std::string > & genesis_validator_ids) const Creates an in-memory genesis registry snapshot.
outcome::result< void >	StoreGenesisRegistry(const std::vector< std::string > & genesis_validator_ids, std::function< std::vector< uint8_t >(std::vector< uint8_t >)> sign) Persists a signed genesis registry update.
outcome::result< Registry >	LoadCurrentRegistry() const Loads the currently active registry.
outcome::result< Registry >	LoadRegistryByCid(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	IsActiveValidator(const std::string & validator_id) const Checks whether a validator is active in the current registry.
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::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.
outcome::result< void >	OnFinalizedCertificate(const sgns::ConsensusCertificate & certificate) Handles a finalized consensus certificate.
BatchSubjectDecision	EvaluateBatchSubject(const ConsensusSubject & subject) Evaluates a registry-batch subject payload.
BatchCertificateDecision	HandleBatchCertificate(const std::string & subject_hash, const sgns::ConsensusCertificate & certificate) Handles certificate associated with a registry-batch subject.
void	RetryInitializationIfNeeded() Re-attempts genesis-registry head-CID discovery when initialization has not yet completed (bug fix, D-01/2-of-11-nodes-start-bridge).

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
constexpr size_t	DefaultMaxNewValidatorsPerUpdate Default cap for new validators added per update.
constexpr 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.

Here, a certificate is a finalized ConsensusCertificate: the signed proposal together with the validators' signed votes and the registry CID/epoch against which their voting weight and quorum are evaluated. It is consensus evidence that the proposal was approved, not a TLS/X.509 identity certificate.

The active validator set is the subset of entries in the current registry snapshot whose status is ACTIVE. Each entry identifies a validator and its role and voting weight; only active entries contribute to quorum. Suspended and blacklisted entries remain in the registry but are excluded.

This component stores the registry 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.
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 EvaluateSlotQuorumStatic¶

static SlotQuorumResult EvaluateSlotQuorumStatic(
    const std::vector< sgns::ConsensusVote > & votes,
    const Registry & registry,
    const WeightConfig & weight_config
)

Pure (stateless) slot-quorum tally for deterministic unit testing.

Parameters:

votes Consensus votes (only approve votes counted).
registry Registry snapshot used to resolve voter weights.
weight_config Slot ratio configuration.

Return: Slot tally result.

Identical arithmetic to EvaluateSlotQuorum, but takes the WeightConfig explicitly so it can be exercised without a GlobalDB-backed ValidatorRegistry instance. The member function delegates here.

function EvaluateRegularPromotionStatic¶

static bool EvaluateRegularPromotionStatic(
    const ValidatorEntry & entry,
    const WeightConfig & weight_config
)

Pure (stateless) REGULAR -> FULL promotion decision (D-08).

Parameters:

entry Validator entry under consideration.
weight_config Weight policy supplying thresholds.

Return: true if the entry should be promoted from REGULAR to FULL.

Returns true iff the entry is currently Role::REGULAR, its accumulated weight has reached full_promotion_weight_, AND its penalty_score is strictly below penalty_threshold_. GENESIS, SHARDED, and already-FULL entries never qualify (no GENESIS demotion, idempotent on FULL). Extracted as a pure static helper so the promotion decision is unit-testable without a GlobalDB-backed ValidatorRegistry instance – ApplyVoteEffects delegates here. The function reads ONLY its inputs (REQ-DETERM-01), so every peer mutates the entry identically.

function RegistryKey¶

static inline constexpr std::string_view RegistryKey()

Registry object key used in datastore.

Return: Constant registry key.

function ValidatorTopic¶

static inline constexpr std::string_view ValidatorTopic()

Topic used to publish/subscribe validator registry updates.

Return: Constant validator topic.

function RegistryCidKey¶

static inline constexpr 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 Close¶

void Close()

Stops accepting registry work and waits for queued persistence to finish.

Must be called before shutting down the backing GlobalDB. Safe to call multiple times.

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

SlotQuorumResult EvaluateSlotQuorum(
    const std::vector< sgns::ConsensusVote > & votes,
    const Registry & registry
) const

Phase 6 cumulative slot-quorum tally for bridge-mint subjects (D-06).

Parameters:

votes Consensus votes (only approve votes are counted).
registry Registry snapshot used to resolve voter weights.

Return: Slot tally result.

Reads ONLY the supplied votes and registry snapshot (REQ-DETERM-01). Slot 0: each distinct approver with a non-empty slot_0_hash contributes weight * slot_direct_numerator_ / slot_direct_denominator_ (D-02). Slots 1-2: votes are grouped by slot_N_hash; only groups with at least slot_public_min_group_ distinct validators contribute sum(weight) * slot_public_numerator_ / slot_public_denominator_ (D-03). Solo hashes contribute zero. Abstainers (all slot hashes empty) still count toward total_voting_reputation but zero toward qualified_sum (D-05). has_quorum = (qualified_sum > threshold) – STRICT (D-06).

function CreateGenesisRegistry¶

Registry CreateGenesisRegistry(
    const std::vector< std::string > & genesis_validator_ids
) const

Creates an in-memory genesis registry snapshot.

Parameters:

genesis_validator_ids Validator ids for genesis authorities.

Return: Genesis registry snapshot.

function StoreGenesisRegistry¶

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

Persists a signed genesis registry update.

Parameters:

genesis_validator_ids Validator ids for genesis authorities.
sign Signing callback used for registry-update signatures.

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

function LoadCurrentRegistry¶

outcome::result< Registry > LoadCurrentRegistry() const

Loads the currently active registry.

Return: Registry snapshot or an error.

function LoadRegistryByCid¶

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

Loads a registry by CID.

Parameters:

cid Registry CID.

Return: Registry snapshot or an error.

Each registry CRDT element contains a complete serialized RegistryUpdate snapshot, so this reads the element from the identified delta directly; reconstructing the registry does not require replaying or merging ancestor deltas.

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

bool IsActiveValidator(
    const std::string & validator_id
) const

Checks whether a validator is active in the current registry.

Parameters:

validator_id Validator identifier.

Return: true when the registry is available and the validator is active.

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

outcome::result< void > OnFinalizedCertificate(
    const sgns::ConsensusCertificate & certificate
)

Handles a finalized consensus certificate.

Parameters:

certificate Finalized certificate.

function EvaluateBatchSubject¶

BatchSubjectDecision EvaluateBatchSubject(
    const ConsensusSubject & subject
)

Evaluates a registry-batch subject payload.

Parameters:

subject Subject to evaluate.

Return: Subject decision.

function HandleBatchCertificate¶

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.

function RetryInitializationIfNeeded¶

void RetryInitializationIfNeeded()

Re-attempts genesis-registry head-CID discovery when initialization has not yet completed (bug fix, D-01/2-of-11-nodes-start-bridge).

InitializeCache() runs synchronously once, at construction time. If the genesis registry has not yet synced into this node's local CRDT store at that instant (the common case for a Light node in a large concurrent cluster), it returns without requesting anything further and initialization is left to depend solely on a passive CRDT broadcast (RegistryUpdateReceived) that may never arrive for every node. Callers that periodically retry a deferred blockchain start (e.g. Blockchain::Start()) should call this on every such retry so an active, repeating head-CID request backs up the passive broadcast path.

No-op once the cache is already initialized.

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 constexpr size_t DefaultMaxNewValidatorsPerUpdate =
            10;

Default cap for new validators added per update.

variable DefaultCertificatesPerBatch¶

static constexpr 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-08-14 at 19:28:58 +0000