Skip to main content

SurbStore

Trait SurbStore 

Source
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§

Source

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.

Source

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.

Source

fn insert_reply_opener(&self, sender_id: HoprSenderId, opener: ReplyOpener)

Stores the given opener for the given sender_id.

This is done by the sending side, when it creates a packet containing a SURB to be delivered to the replying side.

The operation should happen reasonably fast, as it is called from the packet processing code.

Source

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.

Source

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§

Source

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.

Source

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.

Source

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.

Source

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.

Source

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.

Source

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.

Source

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.

Source

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".

Implementations on Foreign Types§

Source§

impl<'a, T> SurbStore for &'a T
where T: 'a + SurbStore + ?Sized,

Source§

fn find_surb(&self, matcher: SurbMatcher) -> Option<FoundSurb>

Source§

fn insert_surbs( &self, pseudonym: SimplePseudonym, surbs: Vec<([u8; 8], SURB<Ed25519Suite, HoprSphinxHeaderSpec>)>, ) -> SurbInsertOutcome

Source§

fn tier_lens(&self, _pseudonym: &SimplePseudonym) -> Option<(usize, usize)>

Source§

fn insert_reply_opener(&self, sender_id: HoprSenderId, opener: ReplyOpener)

Source§

fn find_reply_opener(&self, sender_id: &HoprSenderId) -> Option<ReplyOpener>

Source§

fn remove_reply_opener(&self, sender_id: &HoprSenderId)

Source§

fn invalidate_relayer(&self, _relayer: &KeyIdent)

Source§

fn revalidate_relayer(&self, _relayer: &KeyIdent)

Source§

fn current_generation(&self, _pseudonym: &SimplePseudonym) -> u8

Source§

fn bump_generation(&self, _pseudonym: &SimplePseudonym) -> u8

Source§

fn admit(&self, _pseudonym: &SimplePseudonym, _expected_surbs: usize) -> u64

Source§

fn retire(&self, _pseudonym: &SimplePseudonym, _token: u64)

Source§

fn surbs_held(&self) -> usize

Source§

impl<T> SurbStore for Arc<T>
where T: SurbStore + ?Sized,

Source§

fn find_surb(&self, matcher: SurbMatcher) -> Option<FoundSurb>

Source§

fn insert_surbs( &self, pseudonym: SimplePseudonym, surbs: Vec<([u8; 8], SURB<Ed25519Suite, HoprSphinxHeaderSpec>)>, ) -> SurbInsertOutcome

Source§

fn tier_lens(&self, _pseudonym: &SimplePseudonym) -> Option<(usize, usize)>

Source§

fn insert_reply_opener(&self, sender_id: HoprSenderId, opener: ReplyOpener)

Source§

fn find_reply_opener(&self, sender_id: &HoprSenderId) -> Option<ReplyOpener>

Source§

fn remove_reply_opener(&self, sender_id: &HoprSenderId)

Source§

fn invalidate_relayer(&self, _relayer: &KeyIdent)

Source§

fn revalidate_relayer(&self, _relayer: &KeyIdent)

Source§

fn current_generation(&self, _pseudonym: &SimplePseudonym) -> u8

Source§

fn bump_generation(&self, _pseudonym: &SimplePseudonym) -> u8

Source§

fn admit(&self, _pseudonym: &SimplePseudonym, _expected_surbs: usize) -> u64

Source§

fn retire(&self, _pseudonym: &SimplePseudonym, _token: u64)

Source§

fn surbs_held(&self) -> usize

Source§

impl<T> SurbStore for Box<T>
where T: SurbStore + ?Sized,

Source§

fn find_surb(&self, matcher: SurbMatcher) -> Option<FoundSurb>

Source§

fn insert_surbs( &self, pseudonym: SimplePseudonym, surbs: Vec<([u8; 8], SURB<Ed25519Suite, HoprSphinxHeaderSpec>)>, ) -> SurbInsertOutcome

Source§

fn tier_lens(&self, _pseudonym: &SimplePseudonym) -> Option<(usize, usize)>

Source§

fn insert_reply_opener(&self, sender_id: HoprSenderId, opener: ReplyOpener)

Source§

fn find_reply_opener(&self, sender_id: &HoprSenderId) -> Option<ReplyOpener>

Source§

fn remove_reply_opener(&self, sender_id: &HoprSenderId)

Source§

fn invalidate_relayer(&self, _relayer: &KeyIdent)

Source§

fn revalidate_relayer(&self, _relayer: &KeyIdent)

Source§

fn current_generation(&self, _pseudonym: &SimplePseudonym) -> u8

Source§

fn bump_generation(&self, _pseudonym: &SimplePseudonym) -> u8

Source§

fn admit(&self, _pseudonym: &SimplePseudonym, _expected_surbs: usize) -> u64

Source§

fn retire(&self, _pseudonym: &SimplePseudonym, _token: u64)

Source§

fn surbs_held(&self) -> usize

Implementors§