sgns::base

Namespaces

Name
sgns::base::detail

Classes

	Name
class	sgns::base::Blob
class	sgns::base::Buffer Class represents arbitrary (including empty) byte buffer.
struct	sgns::base::OpenedGossipPayload
struct	sgns::base::Wrapper Make strongly typed structures from different concepts of the equal types. E.g. block height and round number are both uint64_t, but better to be different types. Or, ID and Signature both vectors.

Types

	Name
enum class	BlobError
enum class	GossipPayloadAuthError { NOT_AN_ENVELOPE = 1, MALFORMED_ENVELOPE, KEY_FROM_MISMATCH, SIGNATURE_INVALID, SEAL_FAILED, DERIVE_FAILED} Failure kinds reported by OpenGossipPayload / SealGossipPayload.
enum class	UnhexError { NOT_ENOUGH_INPUT = 1, NON_HEX_INPUT, VALUE_OUT_OF_RANGE, MISSING_0X_PREFIX, UNKNOWN} error codes for exceptions that may occur during unhexing
using Blob< 8 >	Hash64
using Blob< 16 >	Hash128
using Blob< 32 >	Hash256
using Blob< 64 >	Hash512
template <typename T > using libp2p::outcome::result< T, GossipPayloadAuthError, libp2p::outcome::policy::terminate >	GossipAuthResult
using std::shared_ptr< spdlog::logger >	Logger

Functions

	Name
template <class Stream ,size_t size,typename =std::enable_if_t> Stream &	operator<<(Stream & s, const Blob< size > & blob) scale-encodes blob instance to stream
template <class Stream ,size_t size,typename =std::enable_if_t> Stream &	operator>>(Stream & s, Blob< size > & blob) decodes blob instance from stream
template <size_t N> std::ostream &	operator<<(std::ostream & os, const Blob< N > & blob)
std::ostream &	operator<<(std::ostream & os, const Buffer & buffer)
template <class Stream ,typename =std::enable_if_t> Stream &	operator<<(Stream & s, const Buffer & buffer) override operator<< for all streams except std::ostream
template <class Stream ,typename =std::enable_if_t> Stream &	operator>>(Stream & s, Buffer & buffer) decodes buffer object from stream
GossipAuthResult< libp2p::common::ByteArray >	DeriveGossipFromBytes(const libp2p::crypto::KeyPair & keypair) Derives the transport from-bytes a publisher sealing with keypair must present: PeerId::fromPublicKey(marshalled public key).toVector(). Call once and reuse – this equals the local_peer_id_ the vendored gossip stamps into from at publish.
GossipAuthResult< libp2p::common::ByteArray >	SealGossipPayload(const libp2p::crypto::KeyPair & keypair, gsl::span< const uint8_t > from_bytes, gsl::span< const uint8_t > payload) Seals payload into an authenticated envelope signed with keypair's private key (CR-G01 publisher side).
GossipAuthResult< OpenedGossipPayload >	OpenGossipPayload(gsl::span< const uint8_t > from_bytes, gsl::span< const uint8_t > wire_data) Verifies an authenticated gossip envelope (CR-G01 gate side).
std::string	hex_upper(gsl::span< const uint8_t > bytes) Converts bytes to uppercase hex representation.
std::string	hex_lower(gsl::span< const uint8_t > bytes) Converts bytes to hex representation.
bool	IsHexAddress(std::string_view address) Checks whether a string is a 128-character lowercase hexadecimal address.
bool	IsLowerHex(std::string_view value) Checks whether a string consists solely of lowercase hexadecimal digits (length is the caller's concern).
outcome::result< std::vector< uint8_t > >	unhex(std::string_view hex) Converts hex representation to bytes.
outcome::result< std::vector< uint8_t > >	unhexWith0x(std::string_view hex) Unhex hex-string with 0x in the begining.
Logger	createLogger(const std::string & tag, const std::string & basepath ="") Create a logger instance.
template <typename T ,typename =std::enable_if_t<std::is_enum_v>> void	raise(T t) throws outcome::result error as boost exception
template <typename T ,typename =std::enable_if_t<!std::is_enum_v>> void	raise(const T & t) throws outcome::result error made of error as boost exception
template <typename T ,typename Tag ,typename =std::enable_if_t<std::is_arithmetic_v>> bool	operator<(const Wrapper< T, Tag > & a, const Wrapper< T, Tag > & b)

Attributes

	Name
constexpr std::array< uint8_t, 12 >	kGossipAuthEnvelopeMagic 12-byte ASCII magic prefix identifying an authenticated gossip envelope.

Types Documentation

enum BlobError

Enumerator	Value	Description
INCORRECT_LENGTH	1

Error codes for exceptions that may occur during blob initialization

enum GossipPayloadAuthError

Enumerator	Value	Description
NOT_AN_ENVELOPE	1	wire data carries no envelope magic (raw public payload)
MALFORMED_ENVELOPE		truncated header/lengths or unparseable embedded public key
KEY_FROM_MISMATCH		PeerId::fromPublicKey(embedded key) != PeerId::fromBytes(from)
SIGNATURE_INVALID		signature does not verify over the canonical signable bytes
SEAL_FAILED		sealing-side failure (marshal/sign)
DERIVE_FAILED		from-bytes derivation failure (marshal/PeerId)

Failure kinds reported by OpenGossipPayload / SealGossipPayload.

enum UnhexError

Enumerator	Value	Description
NOT_ENOUGH_INPUT	1
NON_HEX_INPUT
VALUE_OUT_OF_RANGE
MISSING_0X_PREFIX
UNKNOWN

error codes for exceptions that may occur during unhexing

using Hash64

using sgns::base::Hash64 = typedef Blob<8>;

using Hash128

using sgns::base::Hash128 = typedef Blob<16>;

using Hash256

using sgns::base::Hash256 = typedef Blob<32>;

using Hash512

using sgns::base::Hash512 = typedef Blob<64>;

using GossipAuthResult

template <typename T >
using sgns::base::GossipAuthResult = typedef libp2p::outcome::result<T, GossipPayloadAuthError, libp2p::outcome::policy::terminate>;

Result type carrying the local error enum. The terminate policy avoids instantiating outcome's exception-throw path (which only supports std::error_code error types); every caller MUST check has_error() before value() – all gate call sites do.

using Logger

using sgns::base::Logger = typedef std::shared_ptr<spdlog::logger>;

Functions Documentation

function operator<<

template <class Stream ,
size_t size,
typename  =std::enable_if_t<Stream::is_encoder_stream>>
Stream & operator<<(
    Stream & s,
    const Blob< size > & blob
)

scale-encodes blob instance to stream

Parameters:

• s output stream reference
• blob value to encode

Template Parameters:

• Stream output stream type
• size blob size

Return: reference to stream

function operator>>

template <class Stream ,
size_t size,
typename  =std::enable_if_t<Stream::is_decoder_stream>>
Stream & operator>>(
    Stream & s,
    Blob< size > & blob
)

decodes blob instance from stream

Parameters:

• s input stream reference
• blob value to encode

Template Parameters:

• Stream output stream type
• size blob size

Return: reference to stream

function operator<<

template <size_t N>
inline std::ostream & operator<<(
    std::ostream & os,
    const Blob< N > & blob
)

function operator<<

std::ostream & operator<<(
    std::ostream & os,
    const Buffer & buffer
)

function operator<<

template <class Stream ,
typename  =std::enable_if_t<Stream::is_encoder_stream>>
Stream & operator<<(
    Stream & s,
    const Buffer & buffer
)

override operator<< for all streams except std::ostream

Parameters:

• s stream reference
• buffer value to encode

Template Parameters:

• Stream stream type

Return: reference to stream

function operator>>

template <class Stream ,
typename  =std::enable_if_t<Stream::is_decoder_stream>>
Stream & operator>>(
    Stream & s,
    Buffer & buffer
)

decodes buffer object from stream

Parameters:

• s stream reference
• buffer value to decode

Template Parameters:

• Stream input stream type

Return: reference to stream

function DeriveGossipFromBytes

inline GossipAuthResult< libp2p::common::ByteArray > DeriveGossipFromBytes(
    const libp2p::crypto::KeyPair & keypair
)

Derives the transport from-bytes a publisher sealing with keypair must present: PeerId::fromPublicKey(marshalled public key).toVector(). Call once and reuse – this equals the local_peer_id_ the vendored gossip stamps into from at publish.

function SealGossipPayload

inline GossipAuthResult< libp2p::common::ByteArray > SealGossipPayload(
    const libp2p::crypto::KeyPair & keypair,
    gsl::span< const uint8_t > from_bytes,
    gsl::span< const uint8_t > payload
)

Seals payload into an authenticated envelope signed with keypair's private key (CR-G01 publisher side).

Parameters:

• keypair Gossip-host keypair (the same one that constructed the GossipPubSub host).
• from_bytes Publisher's own from-bytes – MUST equal DeriveGossipFromBytes(keypair) or receivers will reject the binding.
• payload Serialized application payload to seal.

Return: Envelope bytes to publish, or SEAL_FAILED on marshal/sign error.

function OpenGossipPayload

inline GossipAuthResult< OpenedGossipPayload > OpenGossipPayload(
    gsl::span< const uint8_t > from_bytes,
    gsl::span< const uint8_t > wire_data
)

Verifies an authenticated gossip envelope (CR-G01 gate side).

Parameters:

• from_bytes Transport gossip from-field (wire-supplied).
• wire_data Message payload as received (envelope or raw).

Return: OpenedGossipPayload with the authenticated PeerId (equal to the from PeerId) and the inner payload view.

Check order (every failure denies under a set membership filter):

1. magic present – else NOT_AN_ENVELOPE (raw public payload; a set filter treats this as deny, fail-closed);
2. lengths parse and the embedded public key unmarshals – else MALFORMED_ENVELOPE;
3. PeerId::fromPublicKey(embedded key) == PeerId::fromBytes(from) (an empty/malformed from also fails here) – else KEY_FROM_MISMATCH: a same-PSK peer forging from= cannot pass, because the embedded key does not derive that PeerId;
4. signature verifies over the recomputed signable bytes – else SIGNATURE_INVALID: covers payload AND from, so tampering either fails.

function hex_upper

std::string hex_upper(
    gsl::span< const uint8_t > bytes
)

Converts bytes to uppercase hex representation.

Parameters:

• bytes input bytes

Return: hexstring

function hex_lower

std::string hex_lower(
    gsl::span< const uint8_t > bytes
)

Converts bytes to hex representation.

Parameters:

• bytes input bytes

Return: hexstring

function IsHexAddress

bool IsHexAddress(
    std::string_view address
)

Checks whether a string is a 128-character lowercase hexadecimal address.

Parameters:

• address address to validate

Return: true when the address has the expected length and contains only lowercase hexadecimal characters

function IsLowerHex

bool IsLowerHex(
    std::string_view value
)

Checks whether a string consists solely of lowercase hexadecimal digits (length is the caller's concern).

function unhex

outcome::result< std::vector< uint8_t > > unhex(
    std::string_view hex
)

Converts hex representation to bytes.

Parameters:

• hex hex string input

See: https://www.boost.org/doc/libs/1_51_0/libs/algorithm/doc/html/the_boost_algorithm_library/Misc/hex.html

Return: result containing array of bytes if input string is hex encoded and has even length

Note: reads both uppercase and lowercase hexstrings

function unhexWith0x

outcome::result< std::vector< uint8_t > > unhexWith0x(
    std::string_view hex
)

Unhex hex-string with 0x in the begining.

Parameters:

• hex hex string with 0x in the beginning

Return: unhexed buffer

function createLogger

Logger createLogger(
    const std::string & tag,
    const std::string & basepath =""
)

Create a logger instance.

Parameters:

• tag Tagging name for identifying logger.
• basepath Optional base path for log output (platform dependent).

Return: Logger object.

function raise

template <typename T ,
typename  =std::enable_if_t<std::is_enum_v<T>>>
void raise(
    T t
)

throws outcome::result error as boost exception

Parameters:

• t error value

Template Parameters:

• T enum error type, only outcome::result enums are allowed

function raise

template <typename T ,
typename  =std::enable_if_t<!std::is_enum_v<T>>>
void raise(
    const T & t
)

throws outcome::result error made of error as boost exception

Parameters:

• t outcome error value

Template Parameters:

• T outcome error type

function operator<

template <typename T ,
typename Tag ,
typename  =std::enable_if_t<std::is_arithmetic_v<T>>>
bool operator<(
    const Wrapper< T, Tag > & a,
    const Wrapper< T, Tag > & b
)

Attributes Documentation

variable kGossipAuthEnvelopeMagic

constexpr std::array< uint8_t, 12 > kGossipAuthEnvelopeMagic = {
        'S', 'G', 'N', 'S', 'G', 'O', 'S', 'S', 'I', 'P', '0', '1' };

12-byte ASCII magic prefix identifying an authenticated gossip envelope.

---

Updated on 2026-10-06 at 13:34:20 +0000