Skip to main content

hopr_protocol_hopr/codec/
decoder.rs

1use std::ops::Mul;
2
3use bytes::Bytes;
4use hopr_api::{
5    chain::*,
6    types::{crypto::prelude::*, internal::prelude::*, primitive::prelude::*},
7};
8use hopr_crypto_packet::prelude::*;
9use hopr_utils::trace_timed;
10
11use crate::{
12    AuxiliaryPacketInfo, HoprCodecConfig, IncomingAcknowledgementPacket, IncomingFinalPacket, IncomingForwardedPacket,
13    IncomingPacket, IncomingPacketError, PacketDecoder, SurbStore, errors::HoprProtocolError,
14    replay_filter::TagReplayFilter,
15};
16
17/// Default [decoder](PacketDecoder) implementation for HOPR packets.
18pub struct HoprDecoder<Chain, S, T> {
19    chain_api: Chain,
20    surb_store: std::sync::Arc<S>,
21    ticket_factory: T,
22    packet_key: OffchainKeypair,
23    chain_key: ChainKeypair,
24    channels_dst: Hash,
25    cfg: HoprCodecConfig,
26    replay_filter: TagReplayFilter,
27}
28
29impl<Chain, S, T> HoprDecoder<Chain, S, T>
30where
31    Chain: ChainReadChannelOperations + ChainKeyOperations + ChainReadTicketOperations + ChainValues + Send + Sync,
32    S: SurbStore + Send + Sync,
33    T: hopr_api::tickets::TicketFactory + Send + Sync,
34{
35    /// Creates a new instance of the decoder.
36    pub fn new(
37        (packet_key, chain_key): (OffchainKeypair, ChainKeypair),
38        chain_api: Chain,
39        surb_store: S,
40        ticket_factory: T,
41        channels_dst: Hash,
42        cfg: HoprCodecConfig,
43    ) -> Self {
44        Self {
45            chain_api,
46            surb_store: std::sync::Arc::new(surb_store),
47            packet_key,
48            chain_key,
49            channels_dst,
50            cfg,
51            ticket_factory,
52            replay_filter: TagReplayFilter::new(&cfg.replay_filter),
53        }
54    }
55
56    /// The replay filter, for tests and telemetry.
57    pub fn replay_filter(&self) -> &TagReplayFilter {
58        &self.replay_filter
59    }
60
61    #[tracing::instrument(skip(self, fwd), level = "debug", fields(path_pos = fwd.path_pos))]
62    fn validate_and_replace_ticket(
63        &self,
64        mut fwd: HoprForwardedPacket,
65    ) -> Result<(HoprForwardedPacket, UnacknowledgedTicket), HoprProtocolError> {
66        let previous_hop_addr = trace_timed!("previous_hop_addr lookup", {
67            self.chain_api
68                .packet_key_to_chain_key(&fwd.previous_hop)
69                .map_err(HoprProtocolError::resolver)?
70                .ok_or(HoprProtocolError::KeyNotFound)?
71        });
72
73        let next_hop_addr = trace_timed!("next_hop_addr lookup", {
74            self.chain_api
75                .packet_key_to_chain_key(&fwd.outgoing.next_hop)
76                .map_err(HoprProtocolError::resolver)?
77                .ok_or(HoprProtocolError::KeyNotFound)?
78        });
79
80        let incoming_channel = trace_timed!("incoming_channel lookup", {
81            self.chain_api
82                .channel_by_parties(&previous_hop_addr, self.chain_key.as_ref())
83                .map_err(HoprProtocolError::resolver)?
84                .ok_or_else(|| HoprProtocolError::ChannelNotFound(previous_hop_addr, *self.chain_key.as_ref()))?
85        });
86
87        // The ticket price from the oracle times my node's position on the
88        // path is the acceptable minimum
89        let (win_prob, minimum_ticket_price) = self
90            .chain_api
91            .incoming_ticket_values()
92            .map_err(HoprProtocolError::resolver)?;
93
94        let minimum_ticket_price = minimum_ticket_price
95            .mul(U256::from(fwd.path_pos))
96            .max(self.cfg.min_incoming_ticket_price.unwrap_or_default());
97
98        let remaining_balance = trace_timed!("unrealized_balance lookup", {
99            self.ticket_factory
100                .remaining_incoming_channel_stake(&incoming_channel)
101                .map_err(HoprProtocolError::ticket_factory)?
102        });
103
104        // Here also the signature on the ticket gets validated,
105        // so afterward we are sure the source of the `channel`
106        // (which is equal to `previous_hop_addr`) has issued this
107        // ticket.
108
109        let verified_incoming_ticket = trace_timed!("ticket_signature_verification", {
110            validate_unacknowledged_ticket(
111                fwd.outgoing.ticket,
112                &incoming_channel,
113                minimum_ticket_price,
114                win_prob,
115                remaining_balance,
116                &self.channels_dst,
117            )
118        })?;
119
120        // The ticket is now validated:
121        tracing::trace!(%verified_incoming_ticket, "successfully verified incoming ticket");
122
123        // NOTE: that the path position according to the ticket value
124        // may no longer match the path position from the packet header,
125        // because the ticket issuer may set the price of the ticket higher.
126
127        // Create the new ticket for the new packet
128        let ticket_builder = if fwd.path_pos > 1 {
129            // There must be a channel to the next node if it's not the final hop.
130            // If the channel does not exist, the ticket we extracted before cannot be saved,
131            // as there would be no way to acknowledge it without the channel.
132            let outgoing_channel = self
133                .chain_api
134                .channel_by_parties(self.chain_key.as_ref(), &next_hop_addr)
135                .map_err(HoprProtocolError::resolver)?
136                .ok_or_else(|| HoprProtocolError::ChannelNotFound(*self.chain_key.as_ref(), next_hop_addr))?;
137
138            let (outgoing_ticket_win_prob, outgoing_ticket_price) = self
139                .chain_api
140                .outgoing_ticket_values(self.cfg.outgoing_win_prob, self.cfg.outgoing_ticket_price)
141                .map_err(HoprProtocolError::resolver)?;
142
143            // We currently take the maximum of the win prob from the incoming ticket
144            // and the one configured on this node.
145            // Therefore, the winning probability can only increase along the path.
146            let outgoing_ticket_win_prob = outgoing_ticket_win_prob.max(&verified_incoming_ticket.win_prob());
147
148            // The following operation fails if there's not enough balance on the channel to the next hop.
149            // Again, in this case, we cannot save the ticket we previously extracted because there is no way it gets
150            // acknowledged without enough balance.
151            self.ticket_factory
152                .new_multihop_ticket(
153                    &outgoing_channel,
154                    fwd.path_pos.try_into().expect("path position is always > 1"),
155                    outgoing_ticket_win_prob,
156                    outgoing_ticket_price,
157                )
158                .map_err(HoprProtocolError::ticket_factory)?
159        } else {
160            TicketBuilder::zero_hop().counterparty(next_hop_addr)
161        };
162
163        // Finally, replace the ticket in the outgoing packet with a new one
164        let ticket_builder = ticket_builder.eth_challenge(fwd.next_challenge);
165        fwd.outgoing.ticket = trace_timed!("ticket_signing", {
166            ticket_builder.build_signed(&self.chain_key, &self.channels_dst)?.leak()
167        });
168
169        let unack_ticket = verified_incoming_ticket.into_unacknowledged(fwd.own_key);
170        Ok((fwd, unack_ticket))
171    }
172}
173
174impl<Chain, S, T> PacketDecoder for HoprDecoder<Chain, S, T>
175where
176    Chain: ChainReadChannelOperations + ChainKeyOperations + ChainReadTicketOperations + ChainValues + Send + Sync,
177    S: SurbStore + Send + Sync + 'static,
178    T: hopr_api::tickets::TicketFactory + Send + Sync,
179{
180    type Error = HoprProtocolError;
181
182    #[tracing::instrument(skip(self, sender, data), level = "trace", fields(%sender))]
183    fn decode(&self, sender: PeerId, data: Bytes) -> Result<IncomingPacket, IncomingPacketError<Self::Error>> {
184        #[cfg(feature = "trace-timing")]
185        let decode_start = std::time::Instant::now();
186        tracing::trace!(data_len = data.len(), "decoding packet");
187
188        // Phase 1: Peer ID conversion
189        // Reads the key straight out of the peer id's multihash, so there is nothing to cache.
190        let previous_hop = trace_timed!("peer_id_conversion complete", {
191            OffchainPublicKey::from_peerid(&sender).map_err(|error| {
192                tracing::error!(%sender, %error, "dropping packet - cannot convert peer id");
193                IncomingPacketError::Undecodable(HoprProtocolError::InvalidSender)
194            })
195        })?;
196
197        // Phase 2: Sphinx decoding, with the replay filter consulted on the packet tag.
198        //
199        // The tag is derived from the shared secret, so it becomes available right after the elliptic-curve
200        // multiplication - before the header MAC, the payload permutation and the message parse. The filter is
201        // asked from inside the decode, which is what lets a replay skip that remaining work. The check runs
202        // first and records nothing; the commit runs once the header MAC has verified.
203        //
204        // Anybody can *compute* a tag, from the node's public key and an alpha of their choosing, so a tag is not
205        // by itself proof of anything. What costs a well-formed packet is getting one *recorded*: only a packet
206        // whose header MAC verifies reaches the commit. A packet that authenticates and then fails on our side is
207        // recorded too, which costs one slot.
208
209        // If the following operation fails, it means that the packet is not a valid Hopr packet,
210        // and as such should not be acknowledged later.
211        // Which of our SURBs this packet came back on, if any. Captured here because resolving the
212        // opener is the only point that knows it; by the time the decoded packet exists the sender
213        // id is gone.
214        // The opener is *peeked* here and removed below only once the reply has been delivered, so that a copy
215        // which loses a concurrent race cannot take the winner's decryption key with it.
216        let replied_on_surb = std::cell::Cell::new(None);
217        let consumed_opener = std::cell::Cell::new(None);
218        let packet = trace_timed!("sphinx_decode complete", {
219            HoprPacket::from_incoming_checked(
220                &data,
221                &self.packet_key,
222                previous_hop,
223                self.chain_api.key_id_mapper_ref(),
224                |p| {
225                    let opener = self.surb_store.find_reply_opener(p);
226                    if opener.is_some() {
227                        replied_on_surb.set(Some(p.surb_id()));
228                        consumed_opener.set(Some(*p));
229                    }
230                    opener
231                },
232                // Checked once the secret exists, so a replay skips the header MAC, the payload permutation and
233                // the message parse.
234                |tag| {
235                    let is_replay = self.replay_filter.contains(tag);
236                    if is_replay {
237                        tracing::debug!(%sender, "dropping packet - replay detected after the shared secret");
238                    }
239                    is_replay
240                },
241                // Committed once the header MAC and payload permutation have succeeded - the message/ticket parse
242                // follows - so a forged alpha costs a well-formed packet rather than just the node's public key.
243                // Reporting whether the tag was already present closes the race with a concurrent decode of the
244                // same packet.
245                |tag| {
246                    let is_replay = self.replay_filter.commit(tag);
247                    if is_replay {
248                        tracing::debug!(%sender, "dropping packet - replay detected while committing");
249                    }
250                    is_replay
251                },
252            )
253        })
254        .map_err(|error| match error {
255            hopr_crypto_packet::errors::PacketError::PacketReplay => IncomingPacketError::Replay(previous_hop.into()),
256            error => IncomingPacketError::undecodable(HoprProtocolError::from(error)),
257        })?;
258
259        // The reply decoded, so its opener has done its job. Removing it only now means a concurrent copy that
260        // lost the tag race still found - and did not consume - the opener, so its own failure costs nothing.
261        if let Some(sender_id) = consumed_opener.get() {
262            self.surb_store.remove_reply_opener(&sender_id);
263        }
264
265        match packet {
266            HoprPacket::Final(incoming) => {
267                // Extract additional information from the packet that will be passed upwards
268                let mut info = AuxiliaryPacketInfo {
269                    packet_signals: incoming.signals,
270                    num_surbs: incoming.surbs.len(),
271                    num_evicted_surbs: 0,
272                    // Taken before the SURBs move into the store. A malformed chain length of 0
273                    // saturates to a direct return path, the reading that refuses rather than admits.
274                    min_return_path_hops: incoming
275                        .surbs
276                        .iter()
277                        .map(|(_, surb)| {
278                            surb.additional_data_receiver
279                                .proof_of_relay_values()
280                                .chain_length()
281                                .saturating_sub(1)
282                        })
283                        .min(),
284                };
285
286                // Store all incoming SURBs if any
287                if !incoming.surbs.is_empty() {
288                    let outcome = self.surb_store.insert_surbs(incoming.sender, incoming.surbs);
289                    // `num_surbs` above counts every SURB the packet carried, so everything that did
290                    // not stay in the store has to be booked as gone, or the Exit's level estimate
291                    // (`produced - consumed - evicted`) drifts above what the store holds. That is
292                    // the overflow, and also the stock a newer SURB generation wiped and the batch an
293                    // older one refused: after the Entry bumps the generation the Exit's whole stock
294                    // is gone, and its keep-alive must report that rather than the pre-wipe level.
295                    info.num_evicted_surbs = outcome.evicted + outcome.superseded;
296
297                    // The tier split costs a second lookup and a lock, so take it only if the line below is
298                    // going to be emitted.
299                    let tiers = tracing::enabled!(tracing::Level::TRACE)
300                        .then(|| self.surb_store.tier_lens(&incoming.sender))
301                        .flatten();
302                    tracing::trace!(
303                        pseudonym = %incoming.sender,
304                        num_surbs = info.num_surbs,
305                        retained = outcome.retained,
306                        retained_shares = tiers.map(|(shares, _)| shares),
307                        retained_plain = tiers.map(|(_, plain)| plain),
308                        packet_type = "final",
309                        "stored incoming surbs for pseudonym"
310                    );
311
312                    // Debug rather than warn: the store summarises overflows once per report interval and per
313                    // tier (`EvictionStats`), and that summary is what warns, on any lost PIX share and on
314                    // dropped share-less SURBs only above a threshold. A sender that bypasses the balancer gate
315                    // keeps the share-less tier full, so every one of its packets evicts SURBs although no
316                    // share is lost, and a warning here would fire for each of them. This line is for chasing
317                    // a single overflow, and `evicted_shares` is what it cost.
318                    if outcome.evicted > 0 {
319                        tracing::debug!(
320                            pseudonym = %incoming.sender,
321                            evicted = outcome.evicted,
322                            evicted_shares = outcome.evicted_shares,
323                            retained = outcome.retained,
324                            "SURB buffer full; dropped SURBs to make room (share-less first; \
325                             `evicted_shares` of them carried a PIX share, which is lost)"
326                        );
327                    }
328                }
329
330                let result = match incoming.ack_key {
331                    None => {
332                        if incoming.plain_text.len() < size_of::<u16>() {
333                            return Err(IncomingPacketError::Undecodable(
334                                GeneralError::ParseError("invalid acknowledgement packet size".into()).into(),
335                            ));
336                        }
337
338                        let num_acks =
339                            u16::from_be_bytes(incoming.plain_text[..size_of::<u16>()].try_into().map_err(|_| {
340                                IncomingPacketError::Undecodable(
341                                    GeneralError::ParseError("invalid num acks".into()).into(),
342                                )
343                            })?);
344
345                        if incoming.plain_text.len() < size_of::<u16>() + (num_acks as usize) * Acknowledgement::SIZE {
346                            return Err(IncomingPacketError::Undecodable(
347                                GeneralError::ParseError("invalid number of acknowledgements in packet".into()).into(),
348                            ));
349                        }
350                        tracing::trace!(num_acks, packet_type = "final", "received acknowledgement packet");
351
352                        // The contained payload represents an Acknowledgement
353                        IncomingPacket::Acknowledgement(
354                            IncomingAcknowledgementPacket {
355                                packet_tag: incoming.packet_tag,
356                                previous_hop: incoming.previous_hop,
357                                received_acks: incoming.plain_text
358                                    [size_of::<u16>()..size_of::<u16>() + num_acks as usize * Acknowledgement::SIZE]
359                                    .chunks_exact(Acknowledgement::SIZE)
360                                    .map(Acknowledgement::try_from)
361                                    .collect::<Result<Vec<_>, _>>()
362                                    .map_err(|e: GeneralError| IncomingPacketError::Undecodable(e.into()))?,
363                            }
364                            .into(),
365                        )
366                    }
367                    Some(ack_key) => IncomingPacket::Final(
368                        IncomingFinalPacket {
369                            packet_tag: incoming.packet_tag,
370                            previous_hop: incoming.previous_hop,
371                            sender: incoming.sender,
372                            replied_on_surb: replied_on_surb.get(),
373                            plain_text: incoming.plain_text,
374                            ack_key,
375                            info,
376                        }
377                        .into(),
378                    ),
379                };
380                #[cfg(feature = "trace-timing")]
381                tracing::trace!(
382                    total_ms = decode_start.elapsed().as_millis() as u64,
383                    packet_type = "final",
384                    "decode complete"
385                );
386                Ok(result)
387            }
388            HoprPacket::Forwarded(fwd) => {
389                // Phase 3: Ticket validation and replacement for forwarded packets
390                // Transform the ticket so it can be sent to the next hop
391                let (fwd, verified_unack_ticket) = trace_timed!("ticket_validation complete", {
392                    self.validate_and_replace_ticket(*fwd).map_err(|error| match error {
393                        // Distinguish ticket validation errors so that they can get extra treatment later
394                        HoprProtocolError::TicketValidationError(e) => {
395                            IncomingPacketError::InvalidTicket(previous_hop.into(), e)
396                        }
397                        e => IncomingPacketError::ProcessingError(previous_hop.into(), e),
398                    })?
399                });
400
401                let frame = HoprOutgoingPacket::frame(fwd.outgoing.packet, fwd.outgoing.ticket);
402
403                #[cfg(feature = "trace-timing")]
404                tracing::trace!(
405                    total_ms = decode_start.elapsed().as_millis() as u64,
406                    packet_type = "forwarded",
407                    "decode complete"
408                );
409                Ok(IncomingPacket::Forwarded(
410                    IncomingForwardedPacket {
411                        packet_tag: fwd.packet_tag,
412                        previous_hop: fwd.previous_hop,
413                        next_hop: fwd.outgoing.next_hop,
414                        data: frame,
415                        ack_challenge: fwd.outgoing.ack_challenge,
416                        received_ticket: verified_unack_ticket,
417                        ack_key_prev_hop: fwd.ack_key,
418                    }
419                    .into(),
420                ))
421            }
422            HoprPacket::Outgoing(_) => {
423                #[cfg(feature = "trace-timing")]
424                tracing::trace!(
425                    total_ms = decode_start.elapsed().as_millis() as u64,
426                    packet_type = "outgoing",
427                    "decode complete"
428                );
429                Err(IncomingPacketError::ProcessingError(
430                    previous_hop.into(),
431                    HoprProtocolError::InvalidState("cannot be outgoing packet"),
432                ))
433            }
434        }
435    }
436}