Trait TicketFactory 

pub trait TicketFactory {
    type Error: Error + Send + Sync + 'static;

    // Required method
    fn new_multihop_ticket(
        &self,
        channel: &ChannelEntry,
        path_position: NonZero<u8>,
        winning_probability: WinningProbability,
        price_per_hop: Balance<WxHOPR>,
    ) -> Result<TicketBuilder, Self::Error>;

    // Provided method
    fn remaining_incoming_channel_stake(
        &self,
        channel: &ChannelEntry,
    ) -> Result<Balance<WxHOPR>, Self::Error> { ... }
}

Provides API for creating tickets and validating channel stakes inside the packet pipelines.

Every type of node (Entry, Relay, Exit) needs to call TicketFactory::new_multihop_ticket whenever it sends a packet with more than one relay on (the remaining portion of) its path.

The incoming packet pipeline on Relay nodes needs to perform sender ticket validation when forwarding a packet. For this operation it typically needs to call TicketFactory::remaining_incoming_channel_stake to see if the sender still has enough funds to pay for the ticket.

NOTE: the implementors must be able to perform these operations as effectively as possible, due to the high frequency of these operations in the packet processing pipeline.

Required Associated Types

type Error: Error + Send + Sync + 'static

Required Methods

fn new_multihop_ticket( &self, channel: &ChannelEntry, path_position: NonZero<u8>, winning_probability: WinningProbability, price_per_hop: Balance<WxHOPR>, ) -> Result<TicketBuilder, Self::Error>

Creates the multihop ticket builder for the given channel and path position.

The returned builder should have all fields filled in except the challenge and signature fields.

The path_position argument is descending from a certain maximum number of hops until 1. However, the HOPR protocol does not require the existence of a channel for a 0-hop ticket, therefore, this method does not make sense for path_position equal to 1 (indicating the last hop). In such a case, the implementations must return an error.

Since this operation is called per each outgoing packet for every node type, the operation must be fast.

Provided Methods

fn remaining_incoming_channel_stake( &self, channel: &ChannelEntry, ) -> Result<Balance<WxHOPR>, Self::Error>

Returns real remaining value on the given incoming channel.

This is equal to the balance of the given channel minus the sum of all unredeemed tickets currently in that channel.

The value does not make sense for other than incoming channels, in which case the implementation can either simply return the balance of the given channel or an error.

This method is only interesting for relay nodes. When a relay node is about to relay a packet, it must check whether the sender still has enough funds to pay for the ticket.

Since this operation is called per each relayed packet, the operation must be fast.

The non-relay nodes are free to return the balance of the given channel or an error.

The default implementation simply returns the balance of the given channel.

Implementations on Foreign Types

impl<'a, T> TicketFactory for &'a T

where T: 'a + TicketFactory + ?Sized,

type Error = <T as TicketFactory>::Error

fn new_multihop_ticket( &self, channel: &ChannelEntry, path_position: NonZero<u8>, winning_probability: WinningProbability, price_per_hop: Balance<WxHOPR>, ) -> Result<TicketBuilder, <&'a T as TicketFactory>::Error>

fn remaining_incoming_channel_stake( &self, channel: &ChannelEntry, ) -> Result<Balance<WxHOPR>, <&'a T as TicketFactory>::Error>

impl<S> TicketFactory for HoprTicketFactory<S>

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

fn new_multihop_ticket( &self, channel: &ChannelEntry, path_position: NonZero<u8>, winning_probability: WinningProbability, price_per_hop: Balance<WxHOPR>, ) -> Result<TicketBuilder, <HoprTicketFactory<S> as TicketFactory>::Error>

Method fulfills the implementation of TicketFactory::new_multihop_ticket.

Implementation details

The current_path_pos indicates the position of the current hop in the multi-hop path. It is used to determine the value of the ticket: price * (current_path_pos - 1) / winning_prob. The function does not make sense for current_path_pos <= 1 and returns an error if such an argument is provided.

For last-hop tickets (current_path_pos equal to 1), a zero hop ticket should be created instead.

The function will fail for channels that are not opened or do not have enough funds to cover the ticket value. The ticket index of the returned ticket is guaranteed to be greater or equal to the ticket index on the given channel argument.

fn remaining_incoming_channel_stake( &self, channel: &ChannelEntry, ) -> Result<Balance<WxHOPR>, <HoprTicketFactory<S> as TicketFactory>::Error>

Method fulfills the implementation of TicketFactory::remaining_incoming_channel_stake.

Implementation details

If this instance is created as standalone (via HoprTicketFactory::new), or the HoprTicketManager that has been initially created with this instance is dropped, this method returns Ok(channel.balance).

Otherwise, as per requirements, this method returns the balance of the channel diminished by the total value of unredeemed tickets tracked by the associated HoprTicketManager.

type Error = TicketManagerError

impl<T> TicketFactory for Box<T>

where T: TicketFactory + ?Sized,

type Error = <T as TicketFactory>::Error

fn new_multihop_ticket( &self, channel: &ChannelEntry, path_position: NonZero<u8>, winning_probability: WinningProbability, price_per_hop: Balance<WxHOPR>, ) -> Result<TicketBuilder, <Box<T> as TicketFactory>::Error>

fn remaining_incoming_channel_stake( &self, channel: &ChannelEntry, ) -> Result<Balance<WxHOPR>, <Box<T> as TicketFactory>::Error>

impl<T> TicketFactory for Arc<T>

where T: TicketFactory + ?Sized,

type Error = <T as TicketFactory>::Error

fn new_multihop_ticket( &self, channel: &ChannelEntry, path_position: NonZero<u8>, winning_probability: WinningProbability, price_per_hop: Balance<WxHOPR>, ) -> Result<TicketBuilder, <Arc<T> as TicketFactory>::Error>

fn remaining_incoming_channel_stake( &self, channel: &ChannelEntry, ) -> Result<Balance<WxHOPR>, <Arc<T> as TicketFactory>::Error>

Implementors