Struct SsaShareGenerator 

pub struct SsaShareGenerator<S: PixSpec> {
    polynomials: Cache<S::Pseudonym, Arc<Mutex<SsaPseudonymEntry<S>>>, RandomState>,
    cfg: SsaGeneratorConfig,
}

Generator for Session Stealth Address (SSA) shares distributed over Single Use Reply Blocks (SURBs).

Fields

polynomials: Cache<S::Pseudonym, Arc<Mutex<SsaPseudonymEntry<S>>>, RandomState>

cfg: SsaGeneratorConfig

Implementations

impl<S: PixSpec> SsaShareGenerator<S>

pub fn try_new(cfg: SsaGeneratorConfig) -> Result<Self, S::Pseudonym>

Creates a new share generator with the provided configuration.

Fails if the configuration does not validate. Prefer this over Self::new anywhere the configuration is assembled at runtime — a config built programmatically or read from a file is input, not a constant, and turning it into a panic makes it un-handleable by the caller.

pub fn new(cfg: SsaGeneratorConfig) -> Self

Creates a new share generator with the provided configuration.

Panics

Panics if the configuration fails validation. Use Self::try_new to handle that case instead.

pub fn config(&self) -> &SsaGeneratorConfig

Returns the configuration used to generate this SsaShareGenerator.

pub fn forget(&self, pseudonym: &S::Pseudonym)

Discards all polynomial state held for pseudonym.

The same observable state the cache’s own idle retention produces, reached deliberately: no further share can be emitted for any cycle of this pseudonym, and emission_progress goes back to None.

The distinction that state has been lost rather than never created is not recoverable from here — an evicted entry leaves nothing behind — so a caller that needs it has to hold the fact itself, for as long as it needs it to mean something. hopr-transport-session keeps it per Session, because a successor SsaRequest arriving against lost state is indistinguishable from the opening one otherwise, and the two must not be answered alike.

pub fn emission_progress( &self, pseudonym: &S::Pseudonym, ) -> Option<EmissionProgress>

How far share emission has got for pseudonym.

None when nothing has been committed for the pseudonym yet.

Exists so an Entry can refuse to commit to another batch while emission has not yet reached the end of the batch it is already serving — an Exit asking earlier is asking for deposits it cannot have earned yet. Emission rather than reconstruction, because the Entry never learns what the Exit actually recovered.

Because the window is clamped to one cycle (see SHARE_EMISSION_WINDOW), is_serving_last_committed means every earlier cycle is exhausted — exactly, at every dimension, rather than approximately near a boundary. It becomes true on the last cycle’s first share, though, so it answers “which cycle” and not “how far in”; front_fraction is the second half, and an admission rule needs both.

pub fn recommit( &self, pseudonym: &S::Pseudonym, ssa_index: SsaIndex, runs: impl IntoIterator<Item = (PolynomialIndex, PolynomialIndex)>, ) -> Result<SsaCommitment<S>, S::Pseudonym>

Rebuilds the commitment of an already-committed cycle, restricted to the polynomial indices the peer says it never received.

A cycle’s commitment ships as hundreds of packets and the peer can use it only once every one of them has landed. Nothing else in the protocol repairs a lost packet: the peer cannot reconstruct the missing commitment, and this side cannot tell which one went missing — so without this a single drop costs a cycle the peer has usually already been told to fund. The peer names the gaps, this fills them.

The result is shaped exactly like new_ssa_commitment’s, so the caller re-sends it through the same message splitting, carrying the same bytes and the same proof. It advances no state the peer is charged for: no new index, no new polynomial, and no second deposit — the caller must not announce one, since the address is unchanged and was announced when the cycle was first committed.

Each run is an inclusive (first, last) polynomial-index pair, expected ascending and disjoint. Indices this cycle does not have are skipped.

Errors

• PixError::MissingSsaCommitment — nothing retained for ssa_index. Either it was never committed, or MAX_RETAINED_COMMITMENT_CYCLES newer cycles have pushed it out. Having exhausted a cycle’s polynomials does not put it here: whether a repair still helps depends on what the peer holds, not on what this side can still emit.
• PixError::InvalidInput — MAX_COMMITMENT_RETRANSMISSIONS answers have already been given for this cycle, or runs selects nothing. The cap is what keeps a peer that has already been served from farming whole bursts out of this node; a request that selects nothing still spends an attempt, so malformed scopes are not free either.

Trait Implementations

impl<S: PixSpec> Default for SsaShareGenerator<S>

fn default() -> Self

Returns the “default value” for a type.

impl<S: PixSpec> EntryShareGenerator<S> for SsaShareGenerator<S>

fn next_share( &self, pseudonym: &S::Pseudonym, msg: &impl AsRef<[u8]>, ) -> Result<Option<GeneratedShare<S>>, S::Pseudonym>

Generate the next PartialSsaShare for the given pseudonym and message msg.

IMPORTANT: Each msg MUST be unique for a given pseudonym.

Returns None if all polynomials for the given pseudonym have been used up. This signals that a new SSA must be committed.

fn new_ssa_commitment( &self, pseudonym: &S::Pseudonym, ssa_index: SsaIndex, ) -> Result<SsaCommitment<S>, S::Pseudonym>

Generates a new SSA commitment from the sender side, for the given pseudonym.

Returns the new random SSA-commitment and the corresponding SSA share verifier.

type Error = PixError<<S as PixSpec>::Pseudonym>