hopr-api 1.6.0

Common high-level external and internal API traits used by hopr-lib to implement the HOPR protocol
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72

use futures::future::BoxFuture;
pub use hopr_types::{
    internal::prelude::{RedeemableTicket, VerifiedTicket},
    primitive::prelude::HoprBalance,
};

use crate::chain::{ChainReceipt, WinningProbability};

/// On-chain operations to read values related to tickets.
///
/// These operations are used in critical packet processing pipelines, and therefore,
/// should not query the chain information directly, and they MUST NOT block.
#[auto_impl::auto_impl(&, Box, Arc)]
pub trait ChainReadTicketOperations {
    type Error: std::error::Error + Send + Sync + 'static;

    /// Retrieves the expected minimum winning probability and ticket price for **incoming** tickets.
    ///
    /// This operation MUST not block, as it is typically used within the critical packet processing pipeline.
    fn incoming_ticket_values(&self) -> Result<(WinningProbability, HoprBalance), Self::Error>;

    /// Retrieves the winning probability and ticket price for **outgoing** tickets,
    /// with respect to the optionally pre-configured values.
    ///
    /// The caller, not the implementation, should make sure that the configured values (if provided)
    /// are not less than the expected values for incoming tickets.
    ///
    /// This operation MUST not block, as it is typically used within the critical packet processing pipeline.
    ///
    /// The default implementation calls the `incoming_ticket_values` method and uses the incoming values
    /// unless the configured values are provided.
    fn outgoing_ticket_values(
        &self,
        configured_wp: Option<WinningProbability>,
        configured_price: Option<HoprBalance>,
    ) -> Result<(WinningProbability, HoprBalance), Self::Error> {
        match (configured_wp, configured_price) {
            (Some(wp), Some(price)) => Ok((wp, price)),
            (None, Some(price)) => Ok((self.incoming_ticket_values()?.0, price)),
            (Some(wp), None) => Ok((wp, self.incoming_ticket_values()?.1)),
            _ => self.incoming_ticket_values(),
        }
    }
}

/// Errors that can occur during ticket redemption.
#[derive(Debug, thiserror::Error)]
pub enum TicketRedeemError<E> {
    /// Non-retryable error, the ticket should be discarded
    #[error("redemption of ticket {0} was rejected due to: {1}")]
    Rejected(VerifiedTicket, String),
    /// Retryable error, the ticket redemption should be retried.
    #[error("processing error during redemption of ticket {0}: {1}")]
    ProcessingError(VerifiedTicket, E),
}

/// On-chain write operations with tickets.
#[async_trait::async_trait]
#[auto_impl::auto_impl(&, Box, Arc)]
pub trait ChainWriteTicketOperations {
    type Error: std::error::Error + Send + Sync + 'static;
    /// Redeems a single ticket on-chain.
    ///
    /// The input `ticket` is always returned as [`VerifiedTicket`], either on success or failure.
    async fn redeem_ticket<'a>(
        &'a self,
        ticket: RedeemableTicket,
    ) -> Result<
        BoxFuture<'a, Result<(VerifiedTicket, ChainReceipt), TicketRedeemError<Self::Error>>>,
        TicketRedeemError<Self::Error>,
    >;
}