sgns::Blockchain¶

Manages genesis/account-creation blocks and consensus integration. More...

#include <Blockchain.hpp>

Inherits from std::enable_shared_from_this< Blockchain >

Public Types¶

Name

enum class

Error { GENESIS_BLOCK_CREATION_FAILED = 0, GENESIS_BLOCK_INVALID_SIGNATURE, GENESIS_BLOCK_UNAUTHORIZED_CREATOR, GENESIS_BLOCK_SERIALIZATION_FAILED, GENESIS_BLOCK_MISSING, ACCOUNT_CREATION_BLOCK_MISSING, ACCOUNT_CREATION_BLOCK_CREATION_FAILED, ACCOUNT_CREATION_BLOCK_INVALID_SIGNATURE, ACCOUNT_CREATION_BLOCK_SERIALIZATION_FAILED, ACCOUNT_CREATION_BLOCK_INVALID_GENESIS_LINK, VALIDATOR_REGISTRY_CREATION_FAILED, BLOCKCHAIN_NOT_INITIALIZED}
Error class of the Blockchain module.

using std::function< void(outcome::result< void >)>

BlockchainCallback
Callback invoked when blockchain initialization/processing finishes.

Public Functions¶

	Name
std::shared_ptr< Blockchain >	New(std::shared_ptr< crdt::GlobalDB > global_db, std::shared_ptr< GeniusAccount > account, std::shared_ptr< ipfs_pubsub::GossipPubSub > pubsub, BlockchainCallback callback) Factory method to create Blockchain as shared_ptr.
void	SetAuthorizedFullNodeAddress(const std::string & pub_address) Set the authorized full node public address (for testing purposes).
const std::string &	GetAuthorizedFullNodeAddress() Get the current authorized full node public address.
	~Blockchain() Destroys the blockchain instance.
outcome::result< void >	Start() Start the blockchain with async genesis block handling.
outcome::result< void >	Stop() Stops blockchain background processing and callbacks.
outcome::result< void >	OnGenesisBlockReceived(const base::Buffer & serialized_genesis) Handle received genesis block from pubsub.
outcome::result< void >	OnAccountCreationBlockReceived(const base::Buffer & serialized_account_creation) Handle received account creation block from pubsub.
outcome::result< std::string >	GetGenesisCID() const Returns the stored CID of the selected genesis block.
outcome::result< std::string >	GetAccountCreationCID() const Returns the stored CID of the selected account-creation block.
std::shared_ptr< ValidatorRegistry >	GetValidatorRegistry() const Returns validator registry owned by this blockchain instance.
void	SetFullNodeMode() Forces full-node mode behavior for bootstrap/generation flow.
bool	RegisterSubjectHandler(std::string_view subject_type, ConsensusManager::SubjectHandler handler) Registers a consensus subject handler by canonical subject type string.
void	UnregisterSubjectHandler(std::string_view subject_type) Unregisters a consensus subject handler by canonical subject type string.
bool	RegisterCertificateHandler(std::string_view subject_type, ConsensusManager::CertificateSubjectHandler handler) Registers a consensus certificate handler by canonical subject type string.
void	UnregisterCertificateHandler(std::string_view subject_type) Unregisters a consensus certificate handler by canonical subject type string.
bool	RegisterProposalCleanupHandler(std::string_view subject_type, ConsensusManager::ProposalCleanupHandler handler) Registers a proposal cleanup callback by canonical subject type string.
void	RegisterSlotKeyHandler(std::string_view subject_type, ConsensusManager::SlotKeyHandler handler) Registers a slot key handler for a specific embedded transaction oneof case.
void	UnregisterSlotKeyHandler(std::string_view subject_type)
outcome::result< ConsensusManager::Subject >	CreateConsensusNonceSubject(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 consensus subject for nonce/transaction transition.
outcome::result< ConsensusManager::Proposal >	CreateConsensusProposal(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 signed proposal for nonce/transaction transition.
outcome::result< void >	SubmitProposal(const ConsensusManager::Proposal & proposal) Submits a proposal through consensus manager.
outcome::result< void >	TryResumeProposal(const std::string & hash) Attempts to resume deferred handling for a subject hash.
bool	CheckCertificate(const std::string & subject_hash) const Checks whether any certificate exists for subject hash.
bool	CheckCertificateStrict(const ConsensusManager::Subject & subject) const Performs strict certificate check for a specific subject object.
outcome::result< ConsensusManager::Certificate >	GetCertificateBySubjectHash(const std::string & subject_hash) const Loads certificate by subject hash.
const std::string &	BestHash(const std::string & a, const std::string & b) const Chooses the preferred hash among two candidates.

Protected Functions¶

	Name
outcome::result< void >	MigrateCids(const std::shared_ptr< crdt::GlobalDB > & old_db, const std::shared_ptr< crdt::GlobalDB > & new_db) Migrates blockchain-related CIDs between GlobalDB instances.

Friends¶

	Name
class	Migration3_5_0To3_6_0
class	Migration3_6_0To3_7_0
class	MultiAccountTestAccess

Detailed Description¶

class sgns::Blockchain;

Manages genesis/account-creation blocks and consensus integration.

This class coordinates CRDT-backed persistence of blockchain bootstrap blocks, validates signatures, tracks authoritative CIDs, and exposes a high-level interface to submit and verify consensus subjects/proposals.

Public Types Documentation¶

enum Error¶

Enumerator	Value	Description
GENESIS_BLOCK_CREATION_FAILED	0	Failed to create the genesis block.
GENESIS_BLOCK_INVALID_SIGNATURE		Genesis block has invalid signature.
GENESIS_BLOCK_UNAUTHORIZED_CREATOR		Genesis block created by unauthorized key.
GENESIS_BLOCK_SERIALIZATION_FAILED		Failed to serialize/deserialize genesis block.
GENESIS_BLOCK_MISSING		Genesis block wasn't received.
ACCOUNT_CREATION_BLOCK_MISSING		Account creation is missing.
ACCOUNT_CREATION_BLOCK_CREATION_FAILED		Failed to create account creation block.
ACCOUNT_CREATION_BLOCK_INVALID_SIGNATURE		Account creation block has invalid signature.
ACCOUNT_CREATION_BLOCK_SERIALIZATION_FAILED		Failed to serialize/deserialize account creation block.
ACCOUNT_CREATION_BLOCK_INVALID_GENESIS_LINK		Account creation block not properly linked to genesis.
VALIDATOR_REGISTRY_CREATION_FAILED		Failed to create validator registry.
BLOCKCHAIN_NOT_INITIALIZED		Blockchain not fully initialized yet.

Error class of the Blockchain module.

using BlockchainCallback¶

using sgns::Blockchain::BlockchainCallback = std::function<void( outcome::result<void> )>;

Callback invoked when blockchain initialization/processing finishes.

Public Functions Documentation¶

function New¶

static std::shared_ptr< Blockchain > New(
    std::shared_ptr< crdt::GlobalDB > global_db,
    std::shared_ptr< GeniusAccount > account,
    std::shared_ptr< ipfs_pubsub::GossipPubSub > pubsub,
    BlockchainCallback callback
)

Factory method to create Blockchain as shared_ptr.

Parameters:

global_db CRDT database instance.
account GeniusAccount instance.
pubsub PubSub instance used by consensus manager.
callback Called when initialization completes.

Return: Shared pointer to blockchain instance.

function SetAuthorizedFullNodeAddress¶

static void SetAuthorizedFullNodeAddress(
    const std::string & pub_address
)

Set the authorized full node public address (for testing purposes).

Parameters:

pub_address The public address that is authorized to create genesis blocks

function GetAuthorizedFullNodeAddress¶

static const std::string & GetAuthorizedFullNodeAddress()

Get the current authorized full node public address.

Return: The authorized full node public address

function ~Blockchain¶

~Blockchain()

Destroys the blockchain instance.

function Start¶

outcome::result< void > Start()

Start the blockchain with async genesis block handling.

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

function Stop¶

outcome::result< void > Stop()

Stops blockchain background processing and callbacks.

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

function OnGenesisBlockReceived¶

outcome::result< void > OnGenesisBlockReceived(
    const base::Buffer & serialized_genesis
)

Handle received genesis block from pubsub.

Parameters:

serialized_genesis The received genesis block data

Return: outcome::success when processed, otherwise an error.

function OnAccountCreationBlockReceived¶

outcome::result< void > OnAccountCreationBlockReceived(
    const base::Buffer & serialized_account_creation
)

Handle received account creation block from pubsub.

Parameters:

serialized_account_creation The received account creation block data

Return: outcome::success when processed, otherwise an error.

function GetGenesisCID¶

outcome::result< std::string > GetGenesisCID() const

Returns the stored CID of the selected genesis block.

Return: Genesis CID on success, otherwise an error.

function GetAccountCreationCID¶

outcome::result< std::string > GetAccountCreationCID() const

Returns the stored CID of the selected account-creation block.

Return: Account-creation CID on success, otherwise an error.

function GetValidatorRegistry¶

std::shared_ptr< ValidatorRegistry > GetValidatorRegistry() const

Returns validator registry owned by this blockchain instance.

Return: Shared pointer to validator registry, possibly null when unavailable.

function SetFullNodeMode¶

void SetFullNodeMode()

Forces full-node mode behavior for bootstrap/generation flow.

function RegisterSubjectHandler¶

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

Registers a consensus subject handler by canonical subject type string.

Parameters:

subject_type Canonical subject type to handle.
handler Callback invoked for matching subjects.

Return: true on successful registration.

function UnregisterSubjectHandler¶

void UnregisterSubjectHandler(
    std::string_view subject_type
)

Unregisters a consensus subject handler by canonical subject type string.

Parameters:

subject_type Canonical subject type to remove.

function RegisterCertificateHandler¶

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

Registers a consensus certificate handler by canonical subject type string.

Parameters:

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

Return: true on successful registration.

function UnregisterCertificateHandler¶

void UnregisterCertificateHandler(
    std::string_view subject_type
)

Unregisters a consensus certificate handler by canonical subject type string.

Parameters:

subject_type Canonical subject type to remove.

function RegisterProposalCleanupHandler¶

bool RegisterProposalCleanupHandler(
    std::string_view subject_type,
    ConsensusManager::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 slot is cleaned up due to timeout.

Return: true on successful registration via the consensus manager.

function RegisterSlotKeyHandler¶

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

Registers a slot key handler for a specific embedded transaction oneof case.

Parameters:

transaction_case EmbeddedTransaction oneof case number (e.g. kMintV2).
handler Callback that produces a deterministic slot key for proposals carrying this embedded transaction type.

function UnregisterSlotKeyHandler¶

void UnregisterSlotKeyHandler(
    std::string_view subject_type
)

function CreateConsensusNonceSubject¶

outcome::result< ConsensusManager::Subject > CreateConsensusNonceSubject(
    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 consensus subject for nonce/transaction transition.

Parameters:

account_id Account identifier.
nonce Account nonce.
tx_hash Transaction hash.
transaction EmbeddedTransaction proto with typed oneof field set.
utxo_commitment Optional UTXO commitment payload.
utxo_witness Optional UTXO witness payload.

Return: Constructed subject or an error.

function CreateConsensusProposal¶

outcome::result< ConsensusManager::Proposal > CreateConsensusProposal(
    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 signed proposal for nonce/transaction transition.

Parameters:

account_id Account identifier.
nonce Account nonce.
tx_hash Transaction hash.
transaction EmbeddedTransaction proto with typed oneof field set.
utxo_commitment Optional UTXO commitment payload.
utxo_witness Optional UTXO witness payload.

Return: Constructed proposal or an error.

function SubmitProposal¶

outcome::result< void > SubmitProposal(
    const ConsensusManager::Proposal & proposal
)

Submits a proposal through consensus manager.

Parameters:

proposal Proposal to submit.

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

function TryResumeProposal¶

outcome::result< void > TryResumeProposal(
    const std::string & hash
)

Attempts to resume deferred handling for a subject hash.

Parameters:

hash Subject hash key.

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

function CheckCertificate¶

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

Checks whether any certificate exists for subject hash.

Parameters:

subject_hash Subject hash key.

Return: true when certificate exists.

function CheckCertificateStrict¶

bool CheckCertificateStrict(
    const ConsensusManager::Subject & subject
) const

Performs strict certificate check for a specific subject object.

Parameters:

subject Subject to evaluate.

Return: true when certificate exists and matches strictly.

function GetCertificateBySubjectHash¶

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

Loads certificate by subject hash.

Parameters:

subject_hash Subject hash key.

Return: Certificate on success, otherwise an error.

function BestHash¶

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

Chooses the preferred hash among two candidates.

Parameters:

a First hash candidate.
b Second hash candidate.

Return: Reference to selected hash.

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 blockchain-related CIDs between GlobalDB instances.

Parameters:

old_db Source GlobalDB.
new_db Target GlobalDB.

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

Friends¶

friend Migration3_5_0To3_6_0¶

friend class Migration3_5_0To3_6_0(
    Migration3_5_0To3_6_0 
);

friend Migration3_6_0To3_7_0¶

friend class Migration3_6_0To3_7_0(
    Migration3_6_0To3_7_0 
);

friend MultiAccountTestAccess¶

friend class MultiAccountTestAccess(
    MultiAccountTestAccess 
);

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