title: sgns::networkregistry::NetworkRegistry summary: Per-privateNetworkId membership registry (D-06): a child trust domain of the global TrustedPeerRegistry. Delegates ALL signature/quorum logic to SecureCrdt/SecureCrdtRegistry.
sgns::networkregistry::NetworkRegistry¶
Per-privateNetworkId membership registry (D-06): a child trust domain of the global TrustedPeerRegistry. Delegates ALL signature/quorum logic to SecureCrdt/SecureCrdtRegistry. More...
#include <NetworkRegistry.hpp>
Inherits from std::enable_shared_from_this< NetworkRegistry >, sgns::peerregistry::PeerRegistry
Public Functions¶
| Name | |
|---|---|
| NetworkRegistry(std::shared_ptr< sgns::securecrdt::SecureCrdt > secure_crdt, std::shared_ptr< sgns::trustedpeer::TrustedPeerRegistry > global_trusted_peers, std::string private_network_id, std::vector< std::string > initial_network_peers, uint64_t network_quorum_threshold, std::vector< std::string > initial_network_signers, std::string pnet_key_fingerprint, sgns::crdt::HierarchicalKey base_key, std::shared_ptr< sgns::crdt::GlobalDB > global_db =nullptr) Constructs a NetworkRegistry (prefer New()). |
|
| ~NetworkRegistry() | |
| outcome::result< void > | SeedBootstrap(const std::vector< std::string > & initial_network_peers) Proposes the bootstrap membership record through SecureCrdt. Does NOT self-sign: TPR member nodes add their signatures through the standard propose/sign flow (SignMembershipChange / SecureCrdt::AddSignature) until the TPR-majority quorum is met. |
| outcome::result< void > | ProposeMembershipChange(const std::vector< std::string > & new_peers, const std::vector< std::string > & new_signers ={}) Proposes a membership-change record (full replacement list). |
| outcome::result< void > | SignMembershipChange(const std::string & signer_address, const std::vector< uint8_t > & signature) Adds a signature over the currently-proposed record. |
| outcome::result< bool > | TryConfirm() Attempts to confirm the currently-proposed record against quorum. On confirmation, decodes/verifies/applies the payload and overwrites BOTH cached membership lists – never speculatively before quorum is independently confirmed. |
| virtual outcome::result< sgns::securecrdt::SignerSetSnapshot > | CurrentSignerSet() const override PeerRegistry override: resolves the current authorized signer set from cached state ONLY – the TPR snapshot at TPR-majority pre-confirmation, the cached member signers at network_quorum_threshold_ afterwards. NEVER re-enters the SecureCrdt quorum-read path (Pitfall 9). |
| virtual std::vector< std::string > | GetCurrentPeers() const override Returns a copy of the cached libp2p PeerId membership list (connection-gater allow-list source, D-07). |
| virtual sgns::crdt::HierarchicalKey | BaseKey() const override PeerRegistry override: returns this registry's CRDT base key. |
| bool | IsBootstrapConfirmed() const Reports whether the bootstrap record has been confirmed. |
| uint64_t | RefreshAttemptsForTesting() const TEST SEAM: number of TryConfirm attempts the refresh thread has performed (one increment per attempt). Lets regression tests observe drain-once refresh semantics – after a notification is consumed the thread must return to waiting instead of spinning (WR-02). |
| void | Unregister() Unregisters this instance's signer-set source, change callback, AND the GlobalDB ingest element filter RegisterFilters installed for its pattern (G-WR-01: no stale filter callback outlives the policy owner on a live GlobalDB; test-fixture teardown helper and failure-path cleanup). Idempotent – safe to call from both an explicit teardown and the re-entering destructor. |
| outcome::result< std::shared_ptr< NetworkRegistry > > | New(std::shared_ptr< sgns::securecrdt::SecureCrdt > secure_crdt, std::shared_ptr< sgns::trustedpeer::TrustedPeerRegistry > global_trusted_peers, std::string private_network_id, std::vector< std::string > initial_network_peers, uint64_t network_quorum_threshold, std::vector< std::string > initial_network_signers ={}, std::string pnet_key_fingerprint ={}, std::shared_ptr< sgns::crdt::GlobalDB > global_db =nullptr) Constructs a NetworkRegistry and registers its signer-set source with SecureCrdtRegistry. Validates the quorum floor TWICE (D-06): once for the bootstrap threshold – the strict majority floor ceil(0.51*TPR_SIZE) over the TPR's current peers – and once for network_quorum_threshold over initial_network_peers.size() (and, when member signers are provisioned, over their count as well). |
| sgns::crdt::HierarchicalKey | DefaultBaseKey(const std::string & private_network_id) Per-network CRDT base key: "network-registry/ |
Additional inherited members¶
Public Functions inherited from sgns::peerregistry::PeerRegistry
| Name | |
|---|---|
| virtual | ~PeerRegistry() =default |
Detailed Description¶
Per-privateNetworkId membership registry (D-06): a child trust domain of the global TrustedPeerRegistry. Delegates ALL signature/quorum logic to SecureCrdt/SecureCrdtRegistry.
Lifecycle: pre-confirmation the authorized signer set is the TPR's current peers snapshotted at construction, at a TPR-strict-majority threshold – so the bootstrap record confirms only with a majority of the global trusted peers. Once TryConfirm() confirms a record, the registry resolves its signer set from its OWN cached member signers at its own quorum threshold (self-governance); a single member can never admit itself.
Signer-set resolution reads cached state ONLY and never re-enters the SecureCrdt quorum-read path (Pitfall 9).
Public Functions Documentation¶
function NetworkRegistry¶
NetworkRegistry(
std::shared_ptr< sgns::securecrdt::SecureCrdt > secure_crdt,
std::shared_ptr< sgns::trustedpeer::TrustedPeerRegistry > global_trusted_peers,
std::string private_network_id,
std::vector< std::string > initial_network_peers,
uint64_t network_quorum_threshold,
std::vector< std::string > initial_network_signers,
std::string pnet_key_fingerprint,
sgns::crdt::HierarchicalKey base_key,
std::shared_ptr< sgns::crdt::GlobalDB > global_db =nullptr
)
Constructs a NetworkRegistry (prefer New()).
Parameters:
- secure_crdt SecureCrdt wrapper to delegate propose/sign/ quorum operations to.
- global_trusted_peers Global root trust domain (D-05) – the bootstrap authority; never null.
- private_network_id Public network identity (0x-hex 32B per D-01/D-02) scoping this registry's base key.
- initial_network_peers Initial libp2p PeerId membership (cached immediately, TPR genesis-cache pattern).
- network_quorum_threshold Self-governance quorum applied once the bootstrap record is confirmed.
- initial_network_signers Initial member signing addresses (128-hex). May be empty – an empty signer set then fail-closes all post-confirmation updates.
- pnet_key_fingerprint Optional short hex credential fingerprint carried in records (never raw material).
- base_key Registered CRDT key this instance owns.
- global_db Optional GlobalDB used to register the change-callback that refreshes the cache when new quorum-signed membership elements arrive (BurnConfig pattern); null disables the callback.
function ~NetworkRegistry¶
function SeedBootstrap¶
Proposes the bootstrap membership record through SecureCrdt. Does NOT self-sign: TPR member nodes add their signatures through the standard propose/sign flow (SignMembershipChange / SecureCrdt::AddSignature) until the TPR-majority quorum is met.
Parameters:
- initial_network_peers Membership list to seed.
Return: outcome::success on success, or the failing SecureCrdt call's error.
function ProposeMembershipChange¶
outcome::result< void > ProposeMembershipChange(
const std::vector< std::string > & new_peers,
const std::vector< std::string > & new_signers ={}
)
Proposes a membership-change record (full replacement list).
Parameters:
- new_peers Proposed new full libp2p PeerId membership.
- new_signers Proposed member signing addresses; empty keeps the currently-cached signer list (proposing an empty signer list would permanently fail-close the network's self-governance).
Return: outcome::success on success, or the failing SecureCrdt call's error.
function SignMembershipChange¶
outcome::result< void > SignMembershipChange(
const std::string & signer_address,
const std::vector< uint8_t > & signature
)
Adds a signature over the currently-proposed record.
Parameters:
- signer_address Address claimed to have produced
signature. - signature Raw signature bytes.
Return: outcome::success on success, or the failing SecureCrdt call's error.
function TryConfirm¶
Attempts to confirm the currently-proposed record against quorum. On confirmation, decodes/verifies/applies the payload and overwrites BOTH cached membership lists – never speculatively before quorum is independently confirmed.
Return: outcome::success(true) if this call newly confirmed a record, outcome::success(false) if quorum is not yet met, or a failure if the confirmed payload is malformed/invalid.
function CurrentSignerSet¶
PeerRegistry override: resolves the current authorized signer set from cached state ONLY – the TPR snapshot at TPR-majority pre-confirmation, the cached member signers at network_quorum_threshold_ afterwards. NEVER re-enters the SecureCrdt quorum-read path (Pitfall 9).
Return: Signer set snapshot for the current state.
Reimplements: sgns::peerregistry::PeerRegistry::CurrentSignerSet
function GetCurrentPeers¶
Returns a copy of the cached libp2p PeerId membership list (connection-gater allow-list source, D-07).
Return: Current PeerId membership list.
Reimplements: sgns::peerregistry::PeerRegistry::GetCurrentPeers
function BaseKey¶
PeerRegistry override: returns this registry's CRDT base key.
Return: HierarchicalKey of the "network-registry/
Reimplements: sgns::peerregistry::PeerRegistry::BaseKey
function IsBootstrapConfirmed¶
Reports whether the bootstrap record has been confirmed.
Return: true once TryConfirm has confirmed a record.
function RefreshAttemptsForTesting¶
TEST SEAM: number of TryConfirm attempts the refresh thread has performed (one increment per attempt). Lets regression tests observe drain-once refresh semantics – after a notification is consumed the thread must return to waiting instead of spinning (WR-02).
Return: Total refresh-loop TryConfirm attempt count.
function Unregister¶
Unregisters this instance's signer-set source, change callback, AND the GlobalDB ingest element filter RegisterFilters installed for its pattern (G-WR-01: no stale filter callback outlives the policy owner on a live GlobalDB; test-fixture teardown helper and failure-path cleanup). Idempotent – safe to call from both an explicit teardown and the re-entering destructor.
function New¶
static outcome::result< std::shared_ptr< NetworkRegistry > > New(
std::shared_ptr< sgns::securecrdt::SecureCrdt > secure_crdt,
std::shared_ptr< sgns::trustedpeer::TrustedPeerRegistry > global_trusted_peers,
std::string private_network_id,
std::vector< std::string > initial_network_peers,
uint64_t network_quorum_threshold,
std::vector< std::string > initial_network_signers ={},
std::string pnet_key_fingerprint ={},
std::shared_ptr< sgns::crdt::GlobalDB > global_db =nullptr
)
Constructs a NetworkRegistry and registers its signer-set source with SecureCrdtRegistry. Validates the quorum floor TWICE (D-06): once for the bootstrap threshold – the strict majority floor ceil(0.51*TPR_SIZE) over the TPR's current peers – and once for network_quorum_threshold over initial_network_peers.size() (and, when member signers are provisioned, over their count as well).
Parameters:
- secure_crdt SecureCrdt wrapper (never null).
- global_trusted_peers Bootstrap authority (never null).
- private_network_id Public network identity.
- initial_network_peers Initial libp2p PeerId membership.
- network_quorum_threshold Self-governance quorum.
- initial_network_signers Initial member signing addresses (optional; empty fail-closes post-confirmation updates).
- pnet_key_fingerprint Optional credential fingerprint (optional).
- global_db Optional GlobalDB for the change-callback cache refresh (optional).
Return: outcome::success(instance), or outcome::failure(SecureCrdt::Error::QUORUM_THRESHOLD_BELOW_FLOOR) if either floor check fails – construction fails, no instance is produced – or outcome::failure(std::errc::address_in_use) if a registry for this private network id is already registered (the duplicate attempt registers NOTHING and the live entry – and the registry using it – is left fully functional), or if the CRDT change callback could not be registered on the provided global_db (G-WR-02: fail-closed construction – live membership refresh never silently degrades; the failed construction explicitly unregisters its just-registered policy entry before returning, leaving nothing behind).
function DefaultBaseKey¶
Per-network CRDT base key: "network-registry/
Parameters:
- private_network_id Public network identity.
Return: HierarchicalKey of this network's registry branch.
Updated on 2026-10-06 at 13:34:20 +0000