hopr_db_api/
protocol.rs

1use async_trait::async_trait;
2pub use hopr_crypto_packet::{HoprSurb, prelude::HoprSenderId};
3use hopr_crypto_types::prelude::*;
4use hopr_internal_types::prelude::*;
5use hopr_network_types::prelude::{ResolvedTransportRouting, SurbMatcher};
6use hopr_primitive_types::balance::HoprBalance;
7
8use crate::errors::Result;
9
10/// Trait defining all DB functionality needed by packet/acknowledgement processing pipeline.
11#[async_trait]
12pub trait HoprDbProtocolOperations {
13    /// Processes the acknowledgements for the pending tickets
14    ///
15    /// There are three cases:
16    /// 1. There is an unacknowledged ticket and we are awaiting a half key.
17    /// 2. We were the creator of the packet, hence we do not wait for any half key
18    /// 3. The acknowledgement is unexpected and stems from a protocol bug or an attacker
19    async fn handle_acknowledgement(&self, ack: Acknowledgement) -> Result<()>;
20
21    /// Loads (presumably cached) value of the network's minimum winning probability from the DB.
22    async fn get_network_winning_probability(&self) -> Result<WinningProbability>;
23
24    /// Loads (presumably cached) value of the network's minimum ticket price from the DB.
25    async fn get_network_ticket_price(&self) -> Result<HoprBalance>;
26
27    /// Attempts to find SURB and its ID given the [`SurbMatcher`].
28    async fn find_surb(&self, matcher: SurbMatcher) -> Result<(HoprSenderId, HoprSurb)>;
29
30    /// Process the data into an outgoing packet that is not going to be acknowledged.
31    async fn to_send_no_ack(&self, data: Box<[u8]>, destination: OffchainPublicKey) -> Result<OutgoingPacket>;
32
33    /// Process the data into an outgoing packet
34    async fn to_send(
35        &self,
36        data: Box<[u8]>,
37        routing: ResolvedTransportRouting,
38        outgoing_ticket_win_prob: WinningProbability,
39        outgoing_ticket_price: HoprBalance,
40    ) -> Result<OutgoingPacket>;
41
42    /// Process the incoming packet into data
43    #[allow(clippy::wrong_self_convention)]
44    async fn from_recv(
45        &self,
46        data: Box<[u8]>,
47        pkt_keypair: &OffchainKeypair,
48        sender: OffchainPublicKey,
49        outgoing_ticket_win_prob: WinningProbability,
50        outgoing_ticket_price: HoprBalance,
51    ) -> Result<Option<IncomingPacket>>;
52}
53
54#[allow(clippy::large_enum_variant)] // TODO: Uses too large objects
55pub enum IncomingPacket {
56    /// Packet is intended for us
57    Final {
58        packet_tag: PacketTag,
59        previous_hop: OffchainPublicKey,
60        sender: HoprPseudonym,
61        plain_text: Box<[u8]>,
62        ack_key: HalfKey,
63    },
64    /// Packet must be forwarded
65    Forwarded {
66        packet_tag: PacketTag,
67        previous_hop: OffchainPublicKey,
68        next_hop: OffchainPublicKey,
69        data: Box<[u8]>,
70        ack: Acknowledgement,
71    },
72}
73
74/// Packet that is being sent out by us
75pub struct OutgoingPacket {
76    pub next_hop: OffchainPublicKey,
77    pub ack_challenge: HalfKeyChallenge,
78    pub data: Box<[u8]>,
79}
80
81#[allow(clippy::large_enum_variant)] // TODO: Uses too large objects
82pub enum ResolvedAcknowledgement {
83    Sending(Acknowledgement),
84    RelayingWin(AcknowledgedTicket),
85    RelayingLoss(Hash),
86}