sgns::ConsensusManager¶

Implements Consensus with weighted voting. More...

#include <Consensus.hpp>

Inherits from std::enable_shared_from_this< ConsensusManager >

Public Classes¶

	Name
struct	QuorumTally Quorum tally structure.

Public Types¶

	Name
enum class	Check { Approve, Reject, Pending, Stalled} Object checking values.
using ConsensusProposal	Proposal Alias for Consensus Proposal protobuf type.
using ConsensusVote	Vote Alias for Consensus Vote protobuf type.
using ConsensusVoteBundle	VoteBundle Alias for Consensus Vote Bundle protobuf type.
using ConsensusCertificate	Certificate Alias for Consensus Certificate protobuf type.
using ConsensusSubject	Subject Alias for Consensus Subject protobuf type.
using std::function< outcome::result< std::vector< uint8_t > >(std::vector< uint8_t > payload)>	Signer Alias for a signer method type.
using std::function< outcome::result< Check >(const Subject &subject)>	SubjectHandler Alias for a subject handler method type.
using std::function< outcome::result< Check >(const std::string &subject_hash, const Certificate &certificate)>	CertificateSubjectHandler Alias for a certificate handler method type.
using std::function< void(const std::string &tx_hash)>	ProposalCleanupHandler Alias for a proposal cleanup handler method type Callback invoked when a proposal slot is cleaned up due to timeout. Receives the transaction hash so the handler can clean up associated tracking entries.
using std::function< std::string(const Subject &subject)>	SlotKeyHandler Alias for a slot key handler — produces a deterministic slot key for a proposal. Takes the raw subject, called from GetSlotKey by subject type hash.

Public Functions¶

	Name
std::shared_ptr< ConsensusManager >	New(std::shared_ptr< ValidatorRegistry > registry, std::shared_ptr< crdt::GlobalDB > db, std::shared_ptr< ipfs_pubsub::GossipPubSub > pubsub, Signer signer, std::string address, std::string consensus_topic ="") Creates a ConsensusManager instance.
void	RegisterSlotKeyHandler(std::string_view subject_type, SlotKeyHandler handler) Registers a slot key handler for a canonical subject type.
void	UnregisterSlotKeyHandler(std::string_view subject_type) Unregisters the slot key handler for a canonical subject type.
outcome::result< Proposal >	CreateProposal(const Subject & subject, const std::string & proposer_id, const std::string & registry_cid, uint64_t registry_epoch, Signer sign) Builds and signs a proposal using an explicit signer.
outcome::result< std::vector< uint8_t > >	ProposalSigningBytes(const Proposal & proposal) Computes canonical bytes to sign a proposal.
outcome::result< std::vector< uint8_t > >	VoteSigningBytes(const Vote & vote) Computes canonical bytes to sign a vote.
outcome::result< std::vector< uint8_t > >	VoteBundleSigningBytes(const VoteBundle & bundle) Computes canonical bytes to sign a vote bundle.
outcome::result< std::string >	ComputeSubjectId(const Subject & subject) Computes deterministic subject id/hash.
outcome::result< std::string >	ComputeSubjectTypeHash(std::string_view subject_type) Computes deterministic bytes for a canonical subject type string.
outcome::result< NonceSubject >	DecodeNonceSubject(const Subject & subject)
outcome::result< TaskResultSubject >	DecodeTaskResultSubject(const Subject & subject)
outcome::result< RegistryBatchSubject >	DecodeRegistryBatchSubject(const Subject & subject)
bool	SubjectTypeMatches(const Subject & subject, std::string_view subject_type)
outcome::result< Subject >	CreateNonceSubject(const std::string & account_id, uint64_t nonce, const std::string & tx_hash, const EmbeddedTransaction & transaction, const std::optional< UTXOTransitionCommitment > & utxo_commitment, const std::optional< UTXOWitness > & utxo_witness) Creates a nonce subject.
outcome::result< Subject >	CreateTaskResultSubject(const std::string & account_id, const std::string & escrow_path, const std::string & task_result_hash, uint64_t result_epoch) Creates a task-result subject.
outcome::result< Subject >	CreateRegistryBatchSubject(const std::string & account_id, const std::string & base_registry_cid, uint64_t base_registry_epoch, uint64_t target_registry_epoch, uint32_t certificate_count, const std::string & batch_root) Creates a registry-batch subject.
outcome::result< Subject >	CreateGenericSubject(const std::string & account_id, std::string_view subject_type, const std::vector< uint8_t > & payload) Creates a generic typed subject for application-owned payload schemas.
const std::string &	BestHash(const std::string & a, const std::string & b) Returns the lexicographically better hash among two values.
	~ConsensusManager() Destroys the Consensus Manager object.
void	Close() Close and cleanup members of the Consensus Manager.
bool	RegisterSubjectHandler(std::string_view subject_type, SubjectHandler handler) Registers a subject validation/handling callback by canonical subject type string.
void	UnregisterSubjectHandler(std::string_view subject_type) Unregisters a subject handler by canonical subject type string.
bool	RegisterCertificateHandler(std::string_view subject_type, CertificateSubjectHandler handler) Registers a certificate handling callback by canonical subject type string.
void	UnregisterCertificateHandler(std::string_view subject_type) Unregisters a certificate handler by canonical subject type string.
bool	RegisterProposalCleanupHandler(std::string_view subject_type, ProposalCleanupHandler handler) Registers a proposal cleanup callback by canonical subject type string.
void	UnregisterProposalCleanupHandler(std::string_view subject_type) Unregisters all proposal cleanup handlers for a canonical subject type string.
outcome::result< void >	Publish(const ConsensusMessage & message) Publishes a consensus envelope to pubsub.
outcome::result< Proposal >	CreateProposal(const Subject & subject, const std::string & proposer_id, const std::string & registry_cid, uint64_t registry_epoch) Builds and signs a proposal using the manager signer.
outcome::result< Vote >	CreateVote(const std::string & proposal_id, const std::string & voter_id, bool approve, Signer sign) Builds and signs a vote for a proposal.
outcome::result< VoteBundle >	CreateVoteBundle(const std::string & proposal_id, const std::string & aggregator_id, const std::vector< Vote > & votes, Signer sign) Builds and signs an aggregated vote bundle.
outcome::result< Certificate >	CreateCertificate(const Proposal & proposal, const std::vector< Vote > & votes) Creates a certificate from a proposal and votes.
outcome::result< QuorumTally >	TallyVotes(const Proposal & proposal, const std::vector< Vote > & votes, const ValidatorRegistry::Registry & registry, const std::string & registry_cid) const Tallies votes against an explicit registry snapshot.
outcome::result< QuorumTally >	TallyVotes(const Proposal & proposal, const std::vector< Vote > & votes) const Tallies votes using the manager registry source.
outcome::result< void >	SubmitProposal(const Proposal & proposal, bool self_vote =true) Submits a proposal for local handling and broadcast.
outcome::result< void >	SubmitVote(const Vote & vote, bool self_handle =true) Submits a vote for local handling and broadcast.
outcome::result< void >	SubmitCertificate(const Certificate & certificate) Submits a certificate for local handling and broadcast.
outcome::result< void >	ResumeProposalHandling(const std::string & subject_hash) Retries proposal handling once its subject becomes ready.
void	ProcessCertificates() Processes queued certificate work entries.
void	ConfigureCertificateDelay(std::chrono::milliseconds delay) Configures local delayed processing for received certificates.
outcome::result< Certificate >	GetCertificateBySubjectHash(const std::string & subject_hash) const Retrieves a certificate by subject hash.
bool	CheckCertificateForSubject(const std::string & subject_hash) const Checks whether a certificate exists for a subject hash.
bool	CheckCertificateForSubject(const Subject & subject) const Checks whether a certificate exists for a subject.

Protected Functions¶

	Name
void	ConfigureTimestampWindow(std::chrono::milliseconds window) Sets timestamp validation window for received objects.
void	ConfigureRoundDuration(std::chrono::milliseconds duration) Sets consensus round duration.
void	ConfigureRoundSkew(std::chrono::milliseconds skew) Sets allowable round skew tolerance.

Friends¶

	Name
class	ConsensusManagerTestAccess
class	ConsensusSlotKeyTestAccess

Detailed Description¶

class sgns::ConsensusManager;

Implements Consensus with weighted voting.

 This class implements a consensus algorithm using pubsub messages.

A subject needs to be created and with it a proposal as well. The proposal gets sent to the network and gets voted by peers who receive it. This class has hooks to be filled by the caller to register methods to handle subject and proposal. The idea is to leave out the validation of specific data (transaction, job result and etc) for whomever creates the subject. It relies on ValidatorRegistry class to get the voters and their weights. Once consensus is reached a round scheme determines who amongst the validators will create the certificate which is the finality of the subject. The certificate also enabled registry updates to register new validators according to peer who voted correctly or penalize people who votes incorrectly.

Public Types Documentation¶

enum Check¶

Enumerator	Value	Description
Approve		Object is approved.
Reject		Object is rejected.
Pending		Object evaluation is pending.
Stalled		Object evaluation is stalled.

Object checking values.

using Proposal¶

using sgns::ConsensusManager::Proposal = ConsensusProposal;

Alias for Consensus Proposal protobuf type.

using Vote¶

using sgns::ConsensusManager::Vote = ConsensusVote;

Alias for Consensus Vote protobuf type.

using VoteBundle¶

using sgns::ConsensusManager::VoteBundle = ConsensusVoteBundle;

Alias for Consensus Vote Bundle protobuf type.

using Certificate¶

using sgns::ConsensusManager::Certificate = ConsensusCertificate;

Alias for Consensus Certificate protobuf type.

using Subject¶

using sgns::ConsensusManager::Subject = ConsensusSubject;

Alias for Consensus Subject protobuf type.

using Signer¶

using sgns::ConsensusManager::Signer = std::function<outcome::result<std::vector<uint8_t>>( std::vector<uint8_t> payload )>;

Alias for a signer method type.

using SubjectHandler¶

using sgns::ConsensusManager::SubjectHandler = std::function<outcome::result<Check>( const Subject &subject )>;

Alias for a subject handler method type.

using CertificateSubjectHandler¶

using sgns::ConsensusManager::CertificateSubjectHandler = 
std::function<outcome::result<Check>( const std::string &subject_hash, const Certificate &certificate )>;

Alias for a certificate handler method type.

using ProposalCleanupHandler¶

using sgns::ConsensusManager::ProposalCleanupHandler = std::function<void( const std::string &tx_hash )>;

Alias for a proposal cleanup handler method type Callback invoked when a proposal slot is cleaned up due to timeout. Receives the transaction hash so the handler can clean up associated tracking entries.

using SlotKeyHandler¶

using sgns::ConsensusManager::SlotKeyHandler = std::function<std::string( const Subject &subject )>;

Alias for a slot key handler — produces a deterministic slot key for a proposal. Takes the raw subject, called from GetSlotKey by subject type hash.

Public Functions Documentation¶

function New¶

static std::shared_ptr< ConsensusManager > New(
    std::shared_ptr< ValidatorRegistry > registry,
    std::shared_ptr< crdt::GlobalDB > db,
    std::shared_ptr< ipfs_pubsub::GossipPubSub > pubsub,
    Signer signer,
    std::string address,
    std::string consensus_topic =""
)

Creates a ConsensusManager instance.

Parameters:

registry Validator registry used for voter set and weights.
db GlobalDB instance used for persistence and CRDT interactions.
pubsub PubSub transport for consensus message propagation.
signer Local signing callback for outbound signed objects.
address Local validator/account identifier.
consensus_topic Optional topic override used to derive consensus channels.

Return: Shared pointer to a new manager instance.

function RegisterSlotKeyHandler¶

static void RegisterSlotKeyHandler(
    std::string_view subject_type,
    SlotKeyHandler handler
)

Registers a slot key handler for a canonical subject type.

Parameters:

subject_type Canonical subject type (e.g. "sgns.nonce.v1").
handler Callback that produces a slot key from the raw subject.

RegisterSlotKeyHandler also changed to match subject type pattern:

function UnregisterSlotKeyHandler¶

static void UnregisterSlotKeyHandler(
    std::string_view subject_type
)

Unregisters the slot key handler for a canonical subject type.

Parameters:

subject_type Canonical subject type to remove.

function CreateProposal¶

static outcome::result< Proposal > CreateProposal(
    const Subject & subject,
    const std::string & proposer_id,
    const std::string & registry_cid,
    uint64_t registry_epoch,
    Signer sign
)

Builds and signs a proposal using an explicit signer.

Parameters:

subject Consensus subject to propose.
proposer_id Validator identifier of the proposer.
registry_cid CID of the validator registry snapshot.
registry_epoch Epoch of the validator registry snapshot.
sign Signing callback.

Return: Signed proposal on success, otherwise an error.

function ProposalSigningBytes¶

static outcome::result< std::vector< uint8_t > > ProposalSigningBytes(
    const Proposal & proposal
)

Computes canonical bytes to sign a proposal.

Parameters:

proposal Proposal to encode.

Return: Signing bytes on success, otherwise an error.

function VoteSigningBytes¶

static outcome::result< std::vector< uint8_t > > VoteSigningBytes(
    const Vote & vote
)

Computes canonical bytes to sign a vote.

Parameters:

vote Vote to encode.

Return: Signing bytes on success, otherwise an error.

function VoteBundleSigningBytes¶

static outcome::result< std::vector< uint8_t > > VoteBundleSigningBytes(
    const VoteBundle & bundle
)

Computes canonical bytes to sign a vote bundle.

Parameters:

bundle Vote bundle to encode.

Return: Signing bytes on success, otherwise an error.

function ComputeSubjectId¶

static outcome::result< std::string > ComputeSubjectId(
    const Subject & subject
)

Computes deterministic subject id/hash.

Parameters:

subject Subject to hash.

Return: Subject identifier on success, otherwise an error.

function ComputeSubjectTypeHash¶

static outcome::result< std::string > ComputeSubjectTypeHash(
    std::string_view subject_type
)

Computes deterministic bytes for a canonical subject type string.

Parameters:

subject_type Canonical subject type, e.g. "gnus.bridge_event.v1".

Return: 32-byte subject type hash on success, otherwise an error.

function DecodeNonceSubject¶

static outcome::result< NonceSubject > DecodeNonceSubject(
    const Subject & subject
)

function DecodeTaskResultSubject¶

static outcome::result< TaskResultSubject > DecodeTaskResultSubject(
    const Subject & subject
)

function DecodeRegistryBatchSubject¶

static outcome::result< RegistryBatchSubject > DecodeRegistryBatchSubject(
    const Subject & subject
)

function SubjectTypeMatches¶

static bool SubjectTypeMatches(
    const Subject & subject,
    std::string_view subject_type
)

function CreateNonceSubject¶

static outcome::result< Subject > CreateNonceSubject(
    const std::string & account_id,
    uint64_t nonce,
    const std::string & tx_hash,
    const EmbeddedTransaction & transaction,
    const std::optional< UTXOTransitionCommitment > & utxo_commitment,
    const std::optional< UTXOWitness > & utxo_witness
)

Creates a nonce subject.

Parameters:

account_id Account identifier bound to the subject.
nonce Account nonce.
tx_hash Transaction hash associated with the nonce transition.
transaction_data Full serialized transaction bytes (SerializeByteVector output).
utxo_commitment Optional UTXO commitment payload.
utxo_witness Optional UTXO witness payload.

Return: Constructed subject or an error.

function CreateTaskResultSubject¶

static outcome::result< Subject > CreateTaskResultSubject(
    const std::string & account_id,
    const std::string & escrow_path,
    const std::string & task_result_hash,
    uint64_t result_epoch
)

Creates a task-result subject.

Parameters:

account_id Account identifier bound to the subject.
escrow_path Escrow path associated with task execution.
task_result_hash Result hash for the task output.
result_epoch Epoch for the task result.

Return: Constructed subject or an error.

function CreateRegistryBatchSubject¶

static outcome::result< Subject > CreateRegistryBatchSubject(
    const std::string & account_id,
    const std::string & base_registry_cid,
    uint64_t base_registry_epoch,
    uint64_t target_registry_epoch,
    uint32_t certificate_count,
    const std::string & batch_root
)

Creates a registry-batch subject.

Parameters:

account_id Account identifier bound to the subject.
base_registry_cid Base registry CID used for the batch.
base_registry_epoch Base registry epoch.
target_registry_epoch Target registry epoch after applying batch.
certificate_count Number of certificates in the batch.
batch_root Merkle/root hash of the batch payload.

Return: Constructed subject or an error.

function CreateGenericSubject¶

static outcome::result< Subject > CreateGenericSubject(
    const std::string & account_id,
    std::string_view subject_type,
    const std::vector< uint8_t > & payload
)

Creates a generic typed subject for application-owned payload schemas.

Parameters:

account_id Account identifier bound to the subject.
subject_type Canonical subject type, e.g. "gnus.bridge_event.v1".
payload Canonical serialized application payload.

Return: Constructed subject or an error.

function BestHash¶

static const std::string & BestHash(
    const std::string & a,
    const std::string & b
)

Returns the lexicographically better hash among two values.

Parameters:

a First hash candidate.
b Second hash candidate.

Return: Reference to the selected hash string.

function ~ConsensusManager¶

~ConsensusManager()

Destroys the Consensus Manager object.

function Close¶

void Close()

Close and cleanup members of the Consensus Manager.

function RegisterSubjectHandler¶

bool RegisterSubjectHandler(
    std::string_view subject_type,
    SubjectHandler handler
)

Registers a subject validation/handling callback by canonical subject type string.

Parameters:

subject_type Canonical subject type, e.g. "gnus.bridge_event.v1".
handler Callback invoked for matching subject type hash.

Return: true when registered, false when input is invalid.

function UnregisterSubjectHandler¶

void UnregisterSubjectHandler(
    std::string_view subject_type
)

Unregisters a subject handler by canonical subject type string.

Parameters:

subject_type Canonical subject type associated with the handler.

function RegisterCertificateHandler¶

bool RegisterCertificateHandler(
    std::string_view subject_type,
    CertificateSubjectHandler handler
)

Registers a certificate handling callback by canonical subject type string.

Parameters:

subject_type Canonical subject type associated with certificates.
handler Callback invoked for matching certificate subjects.

Return: true when registered, false when input is invalid.

function UnregisterCertificateHandler¶

void UnregisterCertificateHandler(
    std::string_view subject_type
)

Unregisters a certificate handler by canonical subject type string.

Parameters:

subject_type Canonical subject type associated with the handler.

function RegisterProposalCleanupHandler¶

bool RegisterProposalCleanupHandler(
    std::string_view subject_type,
    ProposalCleanupHandler handler
)

Registers a proposal cleanup callback by canonical subject type string.

Parameters:

subject_type Canonical subject type to handle.
handler Callback invoked when a proposal is cleaned up due to timeout.

Return: true on successful registration.

function UnregisterProposalCleanupHandler¶

void UnregisterProposalCleanupHandler(
    std::string_view subject_type
)

Unregisters all proposal cleanup handlers for a canonical subject type string.

Parameters:

subject_type Canonical subject type to remove.

function Publish¶

outcome::result< void > Publish(
    const ConsensusMessage & message
)

Publishes a consensus envelope to pubsub.

Parameters:

message Consensus message envelope.

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

function CreateProposal¶

outcome::result< Proposal > CreateProposal(
    const Subject & subject,
    const std::string & proposer_id,
    const std::string & registry_cid,
    uint64_t registry_epoch
)

Builds and signs a proposal using the manager signer.

Parameters:

subject Consensus subject to propose.
proposer_id Validator identifier of the proposer.
registry_cid CID of the validator registry snapshot.
registry_epoch Epoch of the validator registry snapshot.

Return: Signed proposal on success, otherwise an error.

function CreateVote¶

outcome::result< Vote > CreateVote(
    const std::string & proposal_id,
    const std::string & voter_id,
    bool approve,
    Signer sign
)

Builds and signs a vote for a proposal.

Parameters:

proposal_id Proposal identifier being voted on.
voter_id Validator identifier of the voter.
approve true for approval vote, false for rejection vote.
sign Signing callback.

Return: Signed vote on success, otherwise an error.

function CreateVoteBundle¶

outcome::result< VoteBundle > CreateVoteBundle(
    const std::string & proposal_id,
    const std::string & aggregator_id,
    const std::vector< Vote > & votes,
    Signer sign
)

Builds and signs an aggregated vote bundle.

Parameters:

proposal_id Proposal identifier associated with the votes.
aggregator_id Validator identifier of the aggregator.
votes Votes to aggregate in the bundle.
sign Signing callback.

Return: Signed vote bundle on success, otherwise an error.

function CreateCertificate¶

outcome::result< Certificate > CreateCertificate(
    const Proposal & proposal,
    const std::vector< Vote > & votes
)

Creates a certificate from a proposal and votes.

Parameters:

proposal Proposal to certify.
votes Votes used for quorum/certificate construction.

Return: Certificate on success, otherwise an error.

function TallyVotes¶

outcome::result< QuorumTally > TallyVotes(
    const Proposal & proposal,
    const std::vector< Vote > & votes,
    const ValidatorRegistry::Registry & registry,
    const std::string & registry_cid
) const

Tallies votes against an explicit registry snapshot.

Parameters:

proposal Proposal being evaluated.
votes Votes to tally.
registry Registry snapshot used to compute weight.
registry_cid Registry CID expected by the proposal.

Return: Quorum tally result or an error.

function TallyVotes¶

outcome::result< QuorumTally > TallyVotes(
    const Proposal & proposal,
    const std::vector< Vote > & votes
) const

Tallies votes using the manager registry source.

Parameters:

proposal Proposal being evaluated.
votes Votes to tally.

Return: Quorum tally result or an error.

function SubmitProposal¶

outcome::result< void > SubmitProposal(
    const Proposal & proposal,
    bool self_vote =true
)

Submits a proposal for local handling and broadcast.

Parameters:

proposal Proposal to submit.
self_vote Whether the local node should auto-vote for its own proposal.

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

function SubmitVote¶

outcome::result< void > SubmitVote(
    const Vote & vote,
    bool self_handle =true
)

Submits a vote for local handling and broadcast.

Parameters:

vote Vote to submit.
self_handle Whether the local node should handle the vote immediately.

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

function SubmitCertificate¶

outcome::result< void > SubmitCertificate(
    const Certificate & certificate
)

Submits a certificate for local handling and broadcast.

Parameters:

certificate Certificate to submit.

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

function ResumeProposalHandling¶

outcome::result< void > ResumeProposalHandling(
    const std::string & subject_hash
)

Retries proposal handling once its subject becomes ready.

Parameters:

subject_hash Subject hash used to locate pending proposals.

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

function ProcessCertificates¶

void ProcessCertificates()

Processes queued certificate work entries.

function ConfigureCertificateDelay¶

void ConfigureCertificateDelay(
    std::chrono::milliseconds delay
)

Configures local delayed processing for received certificates.

Parameters:

delay Delay applied before certificate processing.

function GetCertificateBySubjectHash¶

outcome::result< Certificate > GetCertificateBySubjectHash(
    const std::string & subject_hash
) const

Retrieves a certificate by subject hash.

Parameters:

subject_hash Subject hash key.

Return: Certificate when present, or an error.

function CheckCertificateForSubject¶

bool CheckCertificateForSubject(
    const std::string & subject_hash
) const

Checks whether a certificate exists for a subject hash.

Parameters:

subject_hash Subject hash key.

Return: true if a certificate exists, otherwise false.

function CheckCertificateForSubject¶

bool CheckCertificateForSubject(
    const Subject & subject
) const

Checks whether a certificate exists for a subject.

Parameters:

subject Subject instance to hash and lookup.

Return: true if a certificate exists, otherwise false.

Protected Functions Documentation¶

function ConfigureTimestampWindow¶

void ConfigureTimestampWindow(
    std::chrono::milliseconds window
)

Sets timestamp validation window for received objects.

Parameters:

window Allowed timestamp drift window.

function ConfigureRoundDuration¶

void ConfigureRoundDuration(
    std::chrono::milliseconds duration
)

Sets consensus round duration.

Parameters:

duration Round duration.

function ConfigureRoundSkew¶

void ConfigureRoundSkew(
    std::chrono::milliseconds skew
)

Sets allowable round skew tolerance.

Parameters:

skew Allowed round skew.

Friends¶

friend ConsensusManagerTestAccess¶

friend class ConsensusManagerTestAccess(
    ConsensusManagerTestAccess 
);

friend ConsensusSlotKeyTestAccess¶

friend class ConsensusSlotKeyTestAccess(
    ConsensusSlotKeyTestAccess 
);

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