Struct HoprTicketManager 

pub struct HoprTicketManager<S, Q> {
    channel_tickets: Arc<CachedQueueMap<Q>>,
    store: Arc<RwLock<S>>,
}

Keeps track of incoming redeemable tickets and provides ticket redemption and neglection operations.

To synchronize the on-chain state with the store, it is advised to call sync_incoming_channels early after the construction of the manager, to make sure outdated data is discarded early. This is typically done only once after construction and not needed to be done during the life-time of the manager.

The manager is safe to be shared via an Arc.

This usage is for Relay nodes only because other types of nodes do not need to keep track of incoming redeemable tickets.

Usage in incoming packet pipeline

The incoming packet pipeline usually just calls the insert_incoming_ticket whenever a new winning, redeemable ticket is received on an incoming channel.

Redeemable ticket extraction

On Relay nodes, the manager maintains FIFO queues of redeemable tickets per incoming channel. There are two ways to extract tickets from the queue on a Relay:

1. redeeming them via redeem_stream
2. neglecting them via neglect_tickets

Both of these operations extract the tickets in the FIFO order from the queue, making sure that they are always processed in their natural order (by epoch and index).

Both ticket extraction operations are mutually exclusive and cannot be performed simultaneously.

Locking and lock-contention

There are several methods in the HoprTicketManager object that are expected to be called in the highly performance-sensitive code, on a per-packet basis.

Incoming winning ticket retrieval

The insert_incoming_ticket method is designed to be high-performance and to be called per each incoming packet after it has been forwarded to a next hop.

This operation acquires the write-part of an RW lock (per incoming channel). This may block the hot-path only if one of the following (also write) operations is performed: 1. Ticket redemption has just finished in that particular channel, and the redeemed ticket is dropped from the same incoming channel queue. 2. Ticket neglection has just finished in that particular channel, and the neglected ticket is dropped from the same incoming channel queue.

Both of these operations happen rarely, and the write lock is usually held only for a short time. In addition, incoming winning tickets are not supposed to usually happen very often. Therefore, high contention on the write lock is not expected.

Incoming unacknowledged ticket verification

The unrealized_value method is designed to be high-performance and to be called per each incoming packet before it is forwarded to a next hop.

This operation acquires the read-part of an RW lock (per incoming channel). This may block the hot-path only if one of the following (write) operations is performed at the same moment: 1. A new incoming winning ticket is inserted into the same incoming channel queue. 2. Ticket redemption has just finished in that particular channel, and the redeemed ticket is dropped from the same incoming channel queue. 3. Ticket neglection has just finished in that particular channel, and the neglected ticket is dropped from the same incoming channel queue.

All 3 of these operations are not expected to happen very often on a single channel; therefore, high contention on the RW lock is not expected.

Fields

channel_tickets: Arc<CachedQueueMap<Q>>

store: Arc<RwLock<S>>

Implementations

impl<S> HoprTicketManager<S, S::Queue>

where S: OutgoingIndexStore + TicketQueueStore + 'static, S::Queue: Send + Sync + 'static,

pub fn new_with_factory(store: S) -> (Self, HoprTicketFactory<S>)

Creates the ticket manager in a pair with HoprTicketFactory, both backed by the given store.

The store must be OutgoingIndexStore and TicketQueueStore.

impl<S> HoprTicketManager<S, S::Queue>

where S: TicketQueueStore + Send + Sync + 'static, S::Queue: Send + Sync + 'static,

pub fn sync_from_incoming_channels( &self, incoming_channels: &[ChannelEntry], ) -> Result<Vec<VerifiedTicket>, TicketManagerError>

Synchronizes the existing incoming redeemable ticket queues with the state of the current incoming_channels.

Any incoming ticket queues that correspond to a channel that is no longer open or effectively open (in incoming_channels) will be dropped and the tickets neglected.

For all opened or effectively opened incoming channels inside incoming_channels, either an existing ticket queue is opened or a new one is created (without any tickets in it).

If there are any unredeemable tickets in the existing queues (with an older epoch or lower index than the current index), they are neglected as well.

All the neglected tickets are returned from the function to make further accounting possible, but they are no longer redeemable.

It is advised to call this function early after the construction of the HoprTicketManager to ensure pruning of dangling or out-of-date values.

pub fn unrealized_value( &self, channel_id: &ChannelId, min_index: Option<u64>, ) -> Result<Option<HoprBalance>, TicketManagerError>

Inserts a new incoming winning redeemable ticket into the ticket manager.

On success, the method returns all tickets that have been neglected in the ticket queue of this channel, in case the inserted ticket has a greater channel epoch than the next extractable ticket in the queue. This situation can happen when unredeemed tickets are left in the queue, while the corresponding channel restarts its lifecycle and a new winning ticket is received. Otherwise, the returned vector is empty. Returns the total value of unredeemed tickets in the given channel and its latest epoch.

NOTE: The function is less efficient when the min_index is specified, as a full scan of the queue is required to calculate the unrealized value.

Trait Implementations

impl<S: Debug, Q: Debug> Debug for HoprTicketManager<S, Q>

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl<S> TicketManagement for HoprTicketManager<S, S::Queue>

where S: TicketQueueStore + Send + Sync + 'static, S::Queue: Send + Sync + 'static,

fn redeem_stream<C: ChainWriteTicketOperations + Send + Sync + 'static>( &self, chain: C, channel_id: ChannelId, min_amount: Option<HoprBalance>, ) -> Result<impl Stream<Item = Result<RedemptionResult, Self::Error>> + Send, Self::Error>

Creates a stream that redeems tickets in-order one by one in the given channel, using the given [ChainWriteTicketOperations] on-chain client implementation.

If min_redeem_value is given, all the tickets that are lower than the given value are neglected in the process.

If there’s already an existing redeem stream for the channel, an error is returned without creating a new stream.

The stream terminates when there are no more tickets to process in the queue, or an error is encountered.

fn neglect_tickets( &self, channel_id: &ChannelId, up_to_index: Option<u64>, ) -> Result<Vec<VerifiedTicket>, TicketManagerError>

Removes all the tickets in the given [ChannelId], optionally only up to the given ticket index (inclusive).

If the up_to_index is given and lower than the lowest index of an unredeemed ticket in the queue, the function does nothing.

If there’s ticket redemption ongoing in the same channel and the neglection intersects with the redeemed range, the redemption will be cut short, with remaining unredeemed tickets neglected.

fn ticket_stats( &self, channel: Option<&ChannelId>, ) -> Result<ChannelStats, TicketManagerError>

Computes statistics for the given channel or for all channels if None is given.

If the given channel does not exist, it returns zero statistics instead of an error.

Apart from unredeemed_value, the statistics are not persistent.

type Error = TicketManagerError

fn insert_incoming_ticket( &self, ticket: RedeemableTicket, ) -> Result<Vec<VerifiedTicket>, TicketManagerError>

Inserts an incoming winning ticket into the management queue.