pub trait SurbStore {
Show 13 methods
// Required methods
fn find_surb(&self, matcher: SurbMatcher) -> Option<FoundSurb>;
fn insert_surbs(
&self,
pseudonym: SimplePseudonym,
surbs: Vec<([u8; 8], SURB<Ed25519Suite, HoprSphinxHeaderSpec>)>,
) -> SurbInsertOutcome;
fn insert_reply_opener(&self, sender_id: HoprSenderId, opener: ReplyOpener);
fn find_reply_opener(&self, sender_id: &HoprSenderId) -> Option<ReplyOpener>;
fn remove_reply_opener(&self, sender_id: &HoprSenderId);
// Provided methods
fn tier_lens(&self, _pseudonym: &SimplePseudonym) -> Option<(usize, usize)> { ... }
fn invalidate_relayer(&self, _relayer: &KeyIdent) { ... }
fn revalidate_relayer(&self, _relayer: &KeyIdent) { ... }
fn current_generation(&self, _pseudonym: &SimplePseudonym) -> u8 { ... }
fn bump_generation(&self, _pseudonym: &SimplePseudonym) -> u8 { ... }
fn admit(&self, _pseudonym: &SimplePseudonym, _expected_surbs: usize) -> u64 { ... }
fn retire(&self, _pseudonym: &SimplePseudonym, _token: u64) { ... }
fn surbs_held(&self) -> usize { ... }
}Expand description
A trait defining the operations required to store and retrieve SURBs (Single Use Reply Blocks) and their reply openers.
The sending side stores the reply openers, whereas the SURBs are stored by the replying side of the communication.
Required Methods§
Sourcefn find_surb(&self, matcher: SurbMatcher) -> Option<FoundSurb>
fn find_surb(&self, matcher: SurbMatcher) -> Option<FoundSurb>
Tries to find SURB using the given matcher.
This is used by the replying side when it is about to send a reply packet back to the sender.
Sourcefn insert_surbs(
&self,
pseudonym: SimplePseudonym,
surbs: Vec<([u8; 8], SURB<Ed25519Suite, HoprSphinxHeaderSpec>)>,
) -> SurbInsertOutcome
fn insert_surbs( &self, pseudonym: SimplePseudonym, surbs: Vec<([u8; 8], SURB<Ed25519Suite, HoprSphinxHeaderSpec>)>, ) -> SurbInsertOutcome
Stores the surbs and associates them with the given pseudonym.
This is used by the replying side when it receives packets containing SURBs from the sender
with the given pseudonym.
Returns the total number of SURBs available for that pseudonym including the newly inserted
ones, along with how many had to be dropped to make room. The eviction count must not be
discarded lightly: it is the only evidence that the sender is over-producing. Evictions fall on
share-less SURBs first, so an evicted SURB takes an undelivered PIX share with it only once the
buffer holds nothing but share-bearing ones; SurbInsertOutcome::evicted_shares is the exact
number of shares lost that way. SURBs that a change of SURB generation took out of play (the
stock a newer generation cleared, or an older-generation batch that was refused) are not
evictions; they are reported apart, as SurbInsertOutcome::superseded.
Sourcefn insert_reply_opener(&self, sender_id: HoprSenderId, opener: ReplyOpener)
fn insert_reply_opener(&self, sender_id: HoprSenderId, opener: ReplyOpener)
Sourcefn find_reply_opener(&self, sender_id: &HoprSenderId) -> Option<ReplyOpener>
fn find_reply_opener(&self, sender_id: &HoprSenderId) -> Option<ReplyOpener>
Tries to find a ReplyOpener given the sender_id, without consuming it.
This is done by the sending side of the original packet when the reply to that packet is received and needs to be decrypted. It is the read half of a check-then-use pair: the decoder peeks to decrypt the reply, and removes the opener only once the packet has been delivered. Consuming it at lookup time instead would lose the reply when two copies of it are decoded concurrently - the copy that loses the race would remove the opener and then fail, taking the winner’s decryption key with it.
The operation should happen reasonably fast, as it is called from the packet processing code.
Sourcefn remove_reply_opener(&self, sender_id: &HoprSenderId)
fn remove_reply_opener(&self, sender_id: &HoprSenderId)
Removes a ReplyOpener that has been used to deliver a reply.
Called after the reply decrypted with this opener has been delivered, so a reply is only ever spent once it has actually produced a packet. Removing an opener that is already gone is a no-op, which is what makes the concurrent case safe: the two copies both decrypt, and only one removal is meaningful.
Provided Methods§
Sourcefn tier_lens(&self, _pseudonym: &SimplePseudonym) -> Option<(usize, usize)>
fn tier_lens(&self, _pseudonym: &SimplePseudonym) -> Option<(usize, usize)>
How many SURBs are held for pseudonym in each of the store’s tiers, as (share-bearing, share-less), or None if the store holds no SURBs for it or does not tell its SURBs apart that
way.
For observability only (it feeds a trace line), so it may take a lock and need not be cheap.
The two numbers add up to SurbInsertOutcome::retained as of the last insert, unless a pop
or another insert got in between.
Defaults to None, for stores that keep no such tiers.
Sourcefn invalidate_relayer(&self, _relayer: &KeyIdent)
fn invalidate_relayer(&self, _relayer: &KeyIdent)
Marks the edge from this node to relayer as unusable, so stored SURBs whose return path
starts there are no longer handed out.
Used by the replying side once the payment channel towards relayer is closing or closed:
replying over it would only burn the SURB. SURBs with a direct return path are unaffected —
their first relayer is the final recipient and needs no channel.
Defaults to a no-op, for stores that do not track edge validity.
Sourcefn revalidate_relayer(&self, _relayer: &KeyIdent)
fn revalidate_relayer(&self, _relayer: &KeyIdent)
Reverts SurbStore::invalidate_relayer once the channel towards relayer re-opens.
Defaults to a no-op, for stores that do not track edge validity.
Sourcefn current_generation(&self, _pseudonym: &SimplePseudonym) -> u8
fn current_generation(&self, _pseudonym: &SimplePseudonym) -> u8
Current SURB-batch generation to stamp into SURBs minted for pseudonym.
Used by the sending side at mint time. The value is written into every SURB of the batch so
the replying side can tell SURBs for the current return path from ones left over after a
return-path change (see SurbStore::bump_generation).
Defaults to 0, for stores that do not track generations.
Sourcefn bump_generation(&self, _pseudonym: &SimplePseudonym) -> u8
fn bump_generation(&self, _pseudonym: &SimplePseudonym) -> u8
Advances the SURB-batch generation for pseudonym and returns the new value.
Called by the sending side when it changes the return path for a session (a re-plan): the
next batch it mints will carry the advanced generation, and the replying side drops the SURBs
it still holds for the superseded path. A u8 serial (RFC-1982) is sufficient because only
two adjacent generations are ever in flight.
Defaults to a no-op returning 0, for stores that do not track generations.
Sourcefn admit(&self, _pseudonym: &SimplePseudonym, _expected_surbs: usize) -> u64
fn admit(&self, _pseudonym: &SimplePseudonym, _expected_surbs: usize) -> u64
Admits pseudonym into the store’s trusted class, behind an established Session, and returns
the raw number naming this admission.
Until this is called, SURBs arriving for pseudonym are held in the store’s untrusted class
(if it has one): tightly capped and short-lived, because the pseudonym a packet names is chosen
by its sender and no ticket on the receiving path binds it to a Session. Admission is what lifts
that cap, so it belongs to the Session lifecycle — never to a mere packet’s arrival.
expected_surbs is the Session’s announced SURB target; the store sizes the admitted ring from
it and owns the headroom math. It may be 0 when no target was announced, which the store
treats as “unknown”, not as “one SURB”.
An implementation that admits must never return 0: that value is reserved for “no admission”
— the session side’s AdmissionToken::NONE — and a retire presenting it
must match nothing, so a store that minted it would let every teardown of a never-committed
Session release a live admission. Returning 0 from a store that does not admit is how the
default below honours the rule.
Calling this twice for the same pseudonym must not discard what it already holds, and
invalidates the number the earlier admission returned.
Defaults to a no-op, for stores that do not separate a trusted class.
Sourcefn retire(&self, _pseudonym: &SimplePseudonym, _token: u64)
fn retire(&self, _pseudonym: &SimplePseudonym, _token: u64)
Retires pseudonym from the store’s trusted class, on behalf of the admission token names.
The counterpart of SurbStore::admit, called on every teardown path. It must be idempotent —
retiring a pseudonym that was never admitted is a no-op — and must not touch any SURBs the
pseudonym still holds in the untrusted class, which expire there on their own short lifetime.
token names the admission the teardown is retiring. A teardown may run its retire some time
after it closes the Session — the closing Session’s own return-routed notification still needs
its ring while the packet pipeline resolves the route — so the store must treat a token that
no longer matches pseudonym’s current admission as a no-op: a successor Session was admitted
on the same pseudonym in the meantime, and its ring is not this retire’s to release.
Defaults to a no-op, for stores that do not separate a trusted class.
Sourcefn surbs_held(&self) -> usize
fn surbs_held(&self) -> usize
Total SURBs the store currently holds, across all classes.
For tests and observability only; not a hot path and not required to be cheap. Defaults to 0,
for stores that do not account for it.
Dyn Compatibility§
This trait is dyn compatible.
In older versions of Rust, dyn compatibility was called "object safety".