Skip to main content

hopr_protocol_hopr/codec/
mod.rs

1mod decoder;
2mod encoder;
3
4pub use decoder::HoprDecoder;
5pub use encoder::{HoprEncoder, MAX_ACKNOWLEDGEMENTS_BATCH_SIZE};
6use validator::Validate as _;
7
8/// Configuration of [`HoprEncoder`] and [`HoprDecoder`].
9#[cfg_attr(feature = "serde", cfg_eval::cfg_eval, serde_with::serde_as)]
10#[derive(Clone, Copy, Debug, smart_default::SmartDefault, validator::Validate)]
11#[cfg_attr(
12    feature = "serde",
13    derive(serde::Serialize, serde::Deserialize),
14    serde(deny_unknown_fields)
15)]
16pub struct HoprCodecConfig {
17    /// Optional price of outgoing tickets.
18    ///
19    /// If not set (default), the network default will be used, which is the minimum allowed ticket price in the HOPR
20    /// network.
21    #[cfg_attr(
22        feature = "serde",
23        serde(default),
24        serde_as(as = "Option<serde_with::DisplayFromStr>")
25    )]
26    pub outgoing_ticket_price: Option<hopr_api::types::primitive::balance::HoprBalance>,
27    /// Optional minimum price of incoming tickets.
28    ///
29    /// The value cannot be lower than the default outgoing ticket price times the node's path position.
30    ///
31    /// If not set (default), the network default outgoing ticket price times the node's path position
32    /// will be used.
33    #[cfg_attr(
34        feature = "serde",
35        serde(default),
36        serde_as(as = "Option<serde_with::DisplayFromStr>")
37    )]
38    pub min_incoming_ticket_price: Option<hopr_api::types::primitive::balance::HoprBalance>,
39    /// Optional probability of winning an outgoing ticket.
40    ///
41    /// If not set (default), the network default will be used, which is the minimum allowed winning probability in the
42    /// HOPR network.
43    #[cfg_attr(
44        feature = "serde",
45        serde(default),
46        serde_as(as = "Option<serde_with::DisplayFromStr>")
47    )]
48    pub outgoing_win_prob: Option<hopr_api::types::internal::prelude::WinningProbability>,
49    /// Configuration of the packet replay filter used by [`HoprDecoder`].
50    ///
51    /// The filter is global across previous hops: the replay token names the packet, not the sender, so a replay
52    /// injected through a different peer is still caught. See [`ReplayFilterConfig`](crate::ReplayFilterConfig) for
53    /// the retention floor and the memory consequences of the two knobs.
54    #[validate(nested)]
55    #[cfg_attr(feature = "serde", serde(default))]
56    pub replay_filter: crate::ReplayFilterConfig,
57}
58
59impl PartialEq for HoprCodecConfig {
60    fn eq(&self, other: &Self) -> bool {
61        self.outgoing_ticket_price.eq(&other.outgoing_ticket_price)
62            && self.min_incoming_ticket_price.eq(&other.min_incoming_ticket_price)
63            && self.replay_filter.eq(&other.replay_filter)
64            && match (self.outgoing_win_prob, other.outgoing_win_prob) {
65                (Some(a), Some(b)) => a.approx_eq(&b),
66                (None, None) => true,
67                _ => false,
68            }
69    }
70}
71
72#[cfg(test)]
73mod tests {
74    use std::sync::{
75        Arc,
76        atomic::{AtomicU64, Ordering},
77    };
78
79    use anyhow::Context;
80    use bytes::Bytes;
81    use hopr_api::types::{
82        crypto::prelude::*,
83        crypto_random::Randomizable,
84        internal::{prelude::*, routing::ResolvedTransportRouting},
85    };
86    use hopr_chain_connector::{
87        HoprBlockchainSafeConnector,
88        testing::{BlokliTestClient, StaticState},
89    };
90    use hopr_crypto_packet::{HoprPixSpec, prelude::HoprPacket};
91    use hopr_protocol_pix::{EntryShareGenerator, ExitAcknowledgementShareProcessor, SsaId, SsaShareGenerator};
92    use hopr_ticket_manager::{HoprTicketFactory, MemoryStore};
93
94    use crate::{
95        AuxiliaryPacketInfo, HoprCodecConfig, HoprDecoder, HoprEncoder, MemorySurbStore, OutgoingPacket, PacketDecoder,
96        PacketEncoder, SurbStore, SurbStoreConfig, codec::encoder::MAX_ACKNOWLEDGEMENTS_BATCH_SIZE, utils::*,
97    };
98
99    type TestEncoder = HoprEncoder<
100        Arc<HoprBlockchainSafeConnector<BlokliTestClient<StaticState>>>,
101        Arc<SsaShareGenerator<HoprPixSpec>>,
102        Arc<MemorySurbStore>,
103        HoprTicketFactory<MemoryStore>,
104    >;
105
106    type TestDecoder = HoprDecoder<
107        Arc<HoprBlockchainSafeConnector<BlokliTestClient<StaticState>>>,
108        Arc<MemorySurbStore>,
109        HoprTicketFactory<MemoryStore>,
110    >;
111
112    pub fn create_encoder(sender: &Node) -> TestEncoder {
113        HoprEncoder::new(
114            sender.chain_key.clone(),
115            sender.chain_api.clone(),
116            sender.surb_store.clone(),
117            HoprTicketFactory::new(MemoryStore::default()),
118            Hash::default(),
119            sender.ssa_gen.clone(),
120            HoprCodecConfig::default(),
121        )
122    }
123
124    /// A codec config for tests.
125    ///
126    /// The replay filter defaults to a 10-million-token generation, which allocates tens of megabytes per
127    /// decoder; the codec tests build several, so they use the smallest generation the config accepts.
128    pub fn test_codec_config() -> HoprCodecConfig {
129        HoprCodecConfig {
130            replay_filter: crate::ReplayFilterConfig {
131                max_tracked_packets: crate::MIN_TRACKED_PACKETS,
132                ..Default::default()
133            },
134            ..HoprCodecConfig::default()
135        }
136    }
137
138    pub fn create_decoder(receiver: &Node) -> TestDecoder {
139        HoprDecoder::new(
140            (receiver.offchain_key.clone(), receiver.chain_key.clone()),
141            receiver.chain_api.clone(),
142            receiver.surb_store.clone(),
143            HoprTicketFactory::new(MemoryStore::default()),
144            Hash::default(),
145            test_codec_config(),
146        )
147    }
148
149    /// Shared harness for PIX round-trip tests.
150    ///
151    /// Owns three nodes (sender, relay, receiver) with encoders, decoders,
152    /// and pre-built forward/return paths through `sender → relay → receiver`.
153    struct PixTestFixture {
154        sender: Node,
155        relay: Node,
156        receiver: Node,
157        sender_encoder: TestEncoder,
158        sender_decoder: TestDecoder,
159        relay_decoder: TestDecoder,
160        receiver_encoder: TestEncoder,
161        receiver_decoder: TestDecoder,
162        forward_path: ValidatedPath,
163        return_path: ValidatedPath,
164    }
165
166    impl PixTestFixture {
167        async fn new() -> anyhow::Result<Self> {
168            let blokli_client = create_blokli_client()?;
169            let sender = create_node(0, &blokli_client).await?;
170            let relay = create_node(1, &blokli_client).await?;
171            let receiver = create_node(2, &blokli_client).await?;
172
173            let sender_encoder = create_encoder(&sender);
174            let sender_decoder = create_decoder(&sender);
175            let relay_decoder = create_decoder(&relay);
176            let receiver_encoder = create_encoder(&receiver);
177            let receiver_decoder = create_decoder(&receiver);
178
179            let forward_path = ValidatedPath::new(
180                sender.chain_key.public().to_address(),
181                vec![
182                    relay.chain_key.public().to_address(),
183                    receiver.chain_key.public().to_address(),
184                ],
185                &sender.chain_api.as_path_resolver(),
186            )
187            .await?;
188
189            let return_path = ValidatedPath::new(
190                receiver.chain_key.public().to_address(),
191                vec![
192                    relay.chain_key.public().to_address(),
193                    sender.chain_key.public().to_address(),
194                ],
195                &sender.chain_api.as_path_resolver(),
196            )
197            .await?;
198
199            Ok(Self {
200                sender,
201                relay,
202                receiver,
203                sender_encoder,
204                sender_decoder,
205                relay_decoder,
206                receiver_encoder,
207                receiver_decoder,
208                forward_path,
209                return_path,
210            })
211        }
212
213        /// Looks up the SURB sent by `sender_pseudonym` and encodes a reply packet.
214        fn surb_reply(
215            &self,
216            sender_pseudonym: HoprPseudonym,
217            resp: impl AsRef<[u8]> + Send + 'static,
218        ) -> anyhow::Result<OutgoingPacket> {
219            let surb = self
220                .receiver
221                .surb_store
222                .find_surb(SurbMatcher::Pseudonym(sender_pseudonym))
223                .ok_or(anyhow::anyhow!("no surb found for pseudonym"))?;
224            Ok(self.receiver_encoder.encode_packet(
225                resp,
226                ResolvedTransportRouting::Return(surb.sender_id, surb.surb),
227                None,
228                None,
229            )?)
230        }
231
232        /// Decodes the reply that was relayed back to the sender and asserts its plaintext.
233        fn sender_assert_reply(&self, relay_forwarded_data: bytes::Bytes, expected: &[u8]) -> anyhow::Result<()> {
234            let in_packet = self
235                .sender_decoder
236                .decode(self.relay.offchain_key.public().into(), relay_forwarded_data)?;
237            let in_packet = in_packet.try_as_final().ok_or(anyhow::anyhow!("packet is not final"))?;
238            assert_eq!(expected, in_packet.plain_text.as_ref());
239            Ok(())
240        }
241    }
242
243    #[tokio::test]
244    async fn encode_decode_packet() -> anyhow::Result<()> {
245        let blokli_client = create_blokli_client()?;
246        let sender = create_node(0, &blokli_client).await?;
247        let receiver = create_node(1, &blokli_client).await?;
248
249        let encoder = create_encoder(&sender);
250        let decoder = create_decoder(&receiver);
251
252        let data = b"some random message to encode and decode";
253
254        let out_packet = encoder.encode_packet(
255            data,
256            ResolvedTransportRouting::Forward {
257                pseudonym: HoprPseudonym::random(),
258                forward_path: ValidatedPath::direct(
259                    *receiver.offchain_key.public(),
260                    receiver.chain_key.public().to_address(),
261                ),
262                return_paths: vec![],
263            },
264            None,
265            None,
266        )?;
267
268        let in_packet = decoder.decode(sender.offchain_key.public().into(), out_packet.data)?;
269        let in_packet = in_packet.try_as_final().ok_or(anyhow::anyhow!("packet is not final"))?;
270
271        assert_eq!(data, in_packet.plain_text.as_ref());
272        Ok(())
273    }
274
275    #[tokio::test]
276    async fn encode_decode_packet_should_fail_for_too_long_messages() -> anyhow::Result<()> {
277        let blokli_client = create_blokli_client()?;
278        let sender = create_node(0, &blokli_client).await?;
279        let receiver = create_node(1, &blokli_client).await?;
280
281        let encoder = create_encoder(&sender);
282
283        let data = [1u8; HoprPacket::PAYLOAD_SIZE + 1];
284
285        assert!(
286            encoder
287                .encode_packet(
288                    data,
289                    ResolvedTransportRouting::Forward {
290                        pseudonym: HoprPseudonym::random(),
291                        forward_path: ValidatedPath::direct(
292                            *receiver.offchain_key.public(),
293                            receiver.chain_key.public().to_address(),
294                        ),
295                        return_paths: vec![],
296                    },
297                    None,
298                    None,
299                )
300                .is_err()
301        );
302
303        Ok(())
304    }
305
306    #[tokio::test]
307    async fn encode_decode_packet_on_relay() -> anyhow::Result<()> {
308        let blokli_client = create_blokli_client()?;
309        let sender = create_node(0, &blokli_client).await?;
310        let relay = create_node(1, &blokli_client).await?;
311        let receiver = create_node(2, &blokli_client).await?;
312
313        let sender_encoder = create_encoder(&sender);
314        let relay_decoder = create_decoder(&relay);
315        let receiver_decoder = create_decoder(&receiver);
316
317        let data = b"some random message to encode and decode";
318
319        let out_packet = sender_encoder.encode_packet(
320            data,
321            ResolvedTransportRouting::Forward {
322                pseudonym: HoprPseudonym::random(),
323                forward_path: ValidatedPath::new(
324                    sender.chain_key.public().to_address(),
325                    vec![
326                        relay.chain_key.public().to_address(),
327                        receiver.chain_key.public().to_address(),
328                    ],
329                    &sender.chain_api.as_path_resolver(),
330                )
331                .await?,
332                return_paths: vec![],
333            },
334            None,
335            None,
336        )?;
337
338        let fwd_packet = relay_decoder.decode(sender.offchain_key.public().into(), out_packet.data)?;
339        let fwd_packet = fwd_packet
340            .try_as_forwarded()
341            .ok_or(anyhow::anyhow!("packet is not forwarded"))?;
342
343        let in_packet = receiver_decoder.decode(relay.offchain_key.public().into(), fwd_packet.data)?;
344        let in_packet = in_packet.try_as_final().ok_or(anyhow::anyhow!("packet is not final"))?;
345
346        assert_eq!(data, in_packet.plain_text.as_ref());
347        Ok(())
348    }
349
350    #[tokio::test]
351    async fn encode_decode_packet_full_round_trip() -> anyhow::Result<()> {
352        let f = PixTestFixture::new().await?;
353        let data = b"some random message to encode and decode";
354        let resp = b"some random response to encode and decode";
355
356        let pseudonym = HoprPseudonym::random();
357        let out_packet = f.sender_encoder.encode_packet(
358            data,
359            ResolvedTransportRouting::Forward {
360                pseudonym,
361                forward_path: f.forward_path.clone(),
362                return_paths: vec![f.return_path.clone()],
363            },
364            None,
365            None,
366        )?;
367
368        let fwd_packet = f
369            .relay_decoder
370            .decode(f.sender.offchain_key.public().into(), out_packet.data)?;
371        let fwd_packet = fwd_packet
372            .try_as_forwarded()
373            .ok_or(anyhow::anyhow!("packet is not forwarded"))?;
374
375        let in_packet = f
376            .receiver_decoder
377            .decode(f.relay.offchain_key.public().into(), fwd_packet.data)?;
378        let in_packet = in_packet.try_as_final().ok_or(anyhow::anyhow!("packet is not final"))?;
379        assert_eq!(data, in_packet.plain_text.as_ref());
380
381        let out_packet = f.surb_reply(pseudonym, resp)?;
382
383        let fwd_packet = f
384            .relay_decoder
385            .decode(f.receiver.offchain_key.public().into(), out_packet.data)?;
386        let fwd_packet = fwd_packet
387            .try_as_forwarded()
388            .ok_or(anyhow::anyhow!("packet is not forwarded"))?;
389
390        f.sender_assert_reply(fwd_packet.data, resp)?;
391
392        Ok(())
393    }
394
395    /// A reply carries the SURB's alpha, so its replay token is fixed when the SURB was minted. Two replies over
396    /// two different SURBs must both be accepted, and the replay of one must be rejected - which is what keeps the
397    /// shared alpha of the SURB mechanism from looking like a replay to the filter.
398    #[tokio::test]
399    async fn surb_replies_should_be_distinct_but_replayable() -> anyhow::Result<()> {
400        let f = PixTestFixture::new().await?;
401        let pseudonym = HoprPseudonym::random();
402
403        // Ask for two SURBs, so the receiver can produce two distinct replies.
404        let out_packet = f.sender_encoder.encode_packet(
405            b"a message carrying surbs",
406            ResolvedTransportRouting::Forward {
407                pseudonym,
408                forward_path: f.forward_path.clone(),
409                return_paths: vec![f.return_path.clone(), f.return_path.clone()],
410            },
411            None,
412            None,
413        )?;
414
415        let fwd_packet = f
416            .relay_decoder
417            .decode(f.sender.offchain_key.public().into(), out_packet.data)?;
418        let fwd_packet = fwd_packet
419            .try_as_forwarded()
420            .ok_or(anyhow::anyhow!("packet is not forwarded"))?;
421        f.receiver_decoder
422            .decode(f.relay.offchain_key.public().into(), fwd_packet.data)?;
423
424        let first = f.surb_reply(pseudonym, b"first reply")?;
425        let second = f.surb_reply(pseudonym, b"second reply")?;
426
427        // The relay sees each reply, so its filter is where a legitimate reply must not look like a replay.
428        let forwarded_first = f
429            .relay_decoder
430            .decode(f.receiver.offchain_key.public().into(), first.data.clone())?;
431        f.relay_decoder
432            .decode(f.receiver.offchain_key.public().into(), second.data)?;
433
434        let forwarded_first = forwarded_first
435            .try_as_forwarded()
436            .ok_or(anyhow::anyhow!("packet is not forwarded"))?
437            .data
438            .clone();
439
440        // Delivering the reply consumes its opener at the destination.
441        f.sender_assert_reply(forwarded_first.clone(), b"first reply")?;
442
443        // A duplicate must still be recognised as a replay there, rather than reported undecodable because the
444        // opener it needs is already gone.
445        let replayed_at_destination = f
446            .sender_decoder
447            .decode(f.relay.offchain_key.public().into(), forwarded_first);
448        assert!(
449            replayed_at_destination
450                .err()
451                .context("a duplicate reply must be rejected")?
452                .is_replay(),
453            "a duplicate reply must be a replay even though its opener was consumed"
454        );
455
456        // And the wire copy is caught at the relay as well.
457        let replayed = f
458            .relay_decoder
459            .decode(f.receiver.offchain_key.public().into(), first.data);
460        assert!(
461            replayed.err().context("a replayed reply must be rejected")?.is_replay(),
462            "a replayed reply must be caught"
463        );
464
465        Ok(())
466    }
467
468    /// A packet that never authenticates must not consume the SURB reply opener it names. The opener lookup is a
469    /// removing read, so if it ran for a forged packet the genuine reply would find nothing and be lost.
470    #[tokio::test]
471    async fn a_forged_packet_should_not_consume_a_reply_opener() -> anyhow::Result<()> {
472        let f = PixTestFixture::new().await?;
473        let pseudonym = HoprPseudonym::random();
474
475        // One SURB out to the receiver, so the sender holds the opener that will decrypt the reply.
476        let out_packet = f.sender_encoder.encode_packet(
477            b"a message carrying a surb",
478            ResolvedTransportRouting::Forward {
479                pseudonym,
480                forward_path: f.forward_path.clone(),
481                return_paths: vec![f.return_path.clone()],
482            },
483            None,
484            None,
485        )?;
486        let fwd_packet = f
487            .relay_decoder
488            .decode(f.sender.offchain_key.public().into(), out_packet.data)
489            .context("relay must forward the packet carrying the surb")?
490            .try_as_forwarded()
491            .ok_or(anyhow::anyhow!("packet is not forwarded"))?
492            .data
493            .clone();
494        f.receiver_decoder
495            .decode(f.relay.offchain_key.public().into(), fwd_packet)
496            .context("receiver must accept the packet and store the surb")?;
497
498        // The reply leaves the receiver and is relayed back towards the sender, which is where its opener lives.
499        let reply = f.surb_reply(pseudonym, b"the genuine reply")?;
500        let reply_to_sender = f
501            .relay_decoder
502            .decode(f.receiver.offchain_key.public().into(), reply.data)
503            .context("relay must forward the reply")?
504            .try_as_forwarded()
505            .ok_or(anyhow::anyhow!("reply is not forwarded"))?
506            .data
507            .clone();
508
509        // A forged copy of what the sender will receive: a valid alpha, so the tag is derivable and `is_replay`
510        // runs, but a corrupted header, so it never authenticates - and so must never reach the opener lookup.
511        const ALPHA_LEN: usize = 32;
512        let mut forged = reply_to_sender.to_vec();
513        forged[ALPHA_LEN..ALPHA_LEN + 64].fill(0xff);
514        let forged = Bytes::from(forged);
515
516        assert!(
517            f.sender_decoder
518                .decode(f.relay.offchain_key.public().into(), forged)
519                .err()
520                .context("a forged reply must be rejected")?
521                .is_undecodable(),
522            "a forged reply must not decode"
523        );
524
525        // The genuine reply must still decrypt at the sender, which it can only do if its opener survived.
526        f.sender_assert_reply(reply_to_sender, b"the genuine reply")?;
527
528        Ok(())
529    }
530
531    /// Two concurrent decodes of the *same reply* must deliver it, not consume each other's opener.
532    ///
533    /// The pipeline decodes on a pool, so both copies pass `is_replay`, both look the opener up, and only one of
534    /// them can win the tag race. If the lookup consumed the opener, the loser would fail and the winner would
535    /// then find nothing to decrypt with - losing a reply that arrived intact.
536    #[test]
537    fn concurrent_decodes_of_a_reply_should_still_deliver_it() -> anyhow::Result<()> {
538        let runtime = tokio::runtime::Runtime::new()?;
539        let f = runtime.block_on(PixTestFixture::new())?;
540        let pseudonym = HoprPseudonym::random();
541
542        let out_packet = f.sender_encoder.encode_packet(
543            b"a message carrying a surb",
544            ResolvedTransportRouting::Forward {
545                pseudonym,
546                forward_path: f.forward_path.clone(),
547                return_paths: vec![f.return_path.clone()],
548            },
549            None,
550            None,
551        )?;
552        let fwd_packet = f
553            .relay_decoder
554            .decode(f.sender.offchain_key.public().into(), out_packet.data)
555            .context("relay must forward the packet carrying the surb")?
556            .try_as_forwarded()
557            .ok_or(anyhow::anyhow!("packet is not forwarded"))?
558            .data
559            .clone();
560        f.receiver_decoder
561            .decode(f.relay.offchain_key.public().into(), fwd_packet)
562            .context("receiver must accept the packet and store the surb")?;
563
564        let reply = f.surb_reply(pseudonym, b"the genuine reply")?;
565        let reply_to_sender = f
566            .relay_decoder
567            .decode(f.receiver.offchain_key.public().into(), reply.data)
568            .context("relay must forward the reply")?
569            .try_as_forwarded()
570            .ok_or(anyhow::anyhow!("reply is not forwarded"))?
571            .data
572            .clone();
573
574        // Both copies race through the sender's decoder, released together.
575        let sender_decoder = std::sync::Arc::new(create_decoder(&f.sender));
576        let relay_peer_id: PeerId = f.relay.offchain_key.public().into();
577        let barrier = std::sync::Arc::new(std::sync::Barrier::new(2));
578        let outcomes: Vec<_> = std::thread::scope(|scope| {
579            let handles = (0..2)
580                .map(|_| {
581                    let (decoder, data, barrier) = (sender_decoder.clone(), reply_to_sender.clone(), barrier.clone());
582                    scope.spawn(move || {
583                        barrier.wait();
584                        decoder.decode(relay_peer_id, data)
585                    })
586                })
587                .collect::<Vec<_>>();
588            handles
589                .into_iter()
590                .map(|h| h.join().map_err(|_| anyhow::anyhow!("decode must not panic")))
591                .collect::<anyhow::Result<Vec<_>>>()
592        })?;
593
594        let delivered = outcomes.iter().filter(|o| o.is_ok()).count();
595        assert_eq!(1, delivered, "exactly one copy must be delivered; got {outcomes:?}");
596        assert!(
597            outcomes.iter().any(|o| matches!(o, Err(e) if e.is_replay())),
598            "the other copy must be recognised as a replay"
599        );
600
601        Ok(())
602    }
603
604    /// The decoder reports the shortest return path among the SURBs a packet carried, which is what
605    /// lets an Exit turn away a PIX offer whose shares could never be decrypted.
606    #[tokio::test]
607    async fn decode_should_report_the_shortest_return_path_of_the_carried_surbs() -> anyhow::Result<()> {
608        let f = PixTestFixture::new().await?;
609        let direct_return_path = ValidatedPath::direct(
610            *f.sender.offchain_key.public(),
611            f.sender.chain_key.public().to_address(),
612        );
613
614        for (return_paths, expected) in [
615            (vec![], None),
616            (vec![f.return_path.clone()], Some(1)),
617            (vec![f.return_path.clone(), direct_return_path], Some(0)),
618        ] {
619            let out_packet = f.sender_encoder.encode_packet(
620                b"some random message to encode and decode",
621                ResolvedTransportRouting::Forward {
622                    pseudonym: HoprPseudonym::random(),
623                    forward_path: f.forward_path.clone(),
624                    return_paths,
625                },
626                None,
627                None,
628            )?;
629
630            let fwd_packet = f
631                .relay_decoder
632                .decode(f.sender.offchain_key.public().into(), out_packet.data)?;
633            let fwd_packet = fwd_packet
634                .try_as_forwarded()
635                .ok_or(anyhow::anyhow!("packet is not forwarded"))?;
636
637            let in_packet = f
638                .receiver_decoder
639                .decode(f.relay.offchain_key.public().into(), fwd_packet.data)?;
640            let in_packet = in_packet.try_as_final().ok_or(anyhow::anyhow!("packet is not final"))?;
641            assert_eq!(expected, in_packet.info.min_return_path_hops);
642        }
643
644        Ok(())
645    }
646
647    /// Counts the events by level. `enabled` is always true, so the logging macros' bodies actually run.
648    #[derive(Default)]
649    struct LevelCounter {
650        warnings: AtomicU64,
651        debugs: AtomicU64,
652    }
653
654    impl tracing::Subscriber for LevelCounter {
655        fn enabled(&self, _: &tracing::Metadata<'_>) -> bool {
656            true
657        }
658
659        fn new_span(&self, _: &tracing::span::Attributes<'_>) -> tracing::span::Id {
660            tracing::span::Id::from_u64(1)
661        }
662
663        fn record(&self, _: &tracing::span::Id, _: &tracing::span::Record<'_>) {}
664
665        fn record_follows_from(&self, _: &tracing::span::Id, _: &tracing::span::Id) {}
666
667        fn event(&self, event: &tracing::Event<'_>) {
668            match *event.metadata().level() {
669                tracing::Level::WARN => self.warnings.fetch_add(1, Ordering::Relaxed),
670                tracing::Level::DEBUG => self.debugs.fetch_add(1, Ordering::Relaxed),
671                _ => 0,
672            };
673        }
674
675        fn enter(&self, _: &tracing::span::Id) {}
676
677        fn exit(&self, _: &tracing::span::Id) {}
678    }
679
680    /// A sender that bypasses the balancer gate keeps the Exit's share-less tier full, so each packet it
681    /// sends evicts share-less SURBs although no share is lost. The decoder reports that at debug level
682    /// only: the store's interval summary carries the warning, which a lost share always triggers, so such
683    /// a flood must not log once per packet.
684    #[tokio::test]
685    async fn decode_should_not_warn_per_packet_when_a_full_buffer_drops_share_less_surbs() -> anyhow::Result<()> {
686        let f = PixTestFixture::new().await?;
687        let pseudonym = HoprPseudonym::random();
688
689        // A packet carrying a return path, sent as far as the relay's output, which is what the receiver gets.
690        let from_relay = || -> anyhow::Result<bytes::Bytes> {
691            let out_packet = f.sender_encoder.encode_packet(
692                b"some random message to encode and decode",
693                ResolvedTransportRouting::Forward {
694                    pseudonym,
695                    forward_path: f.forward_path.clone(),
696                    return_paths: vec![f.return_path.clone()],
697                },
698                None,
699                None,
700            )?;
701            let fwd_packet = f
702                .relay_decoder
703                .decode(f.sender.offchain_key.public().into(), out_packet.data)?;
704            let fwd_packet = fwd_packet
705                .try_as_forwarded()
706                .ok_or(anyhow::anyhow!("packet is not forwarded"))?;
707            Ok(fwd_packet.data)
708        };
709        let receive = |data: bytes::Bytes| -> anyhow::Result<AuxiliaryPacketInfo> {
710            let in_packet = f.receiver_decoder.decode(f.relay.offchain_key.public().into(), data)?;
711            let in_packet = in_packet.try_as_final().ok_or(anyhow::anyhow!("packet is not final"))?;
712            Ok(in_packet.info)
713        };
714
715        // The first packet leaves a real, share-less SURB behind. Take it, and fill the buffer to capacity
716        // with copies of it, as a sender that has been outproducing the Exit for a while would have.
717        // The full-buffer arithmetic is admitted-ring arithmetic: unadmitted SURBs would cap out at the
718        // quarantine's 16, so admit the pseudonym the way an established Session would have.
719        receive(from_relay()?)?;
720        f.receiver
721            .surb_store
722            .admit(&pseudonym, SurbStoreConfig::default().rb_capacity);
723        let surb = f
724            .receiver
725            .surb_store
726            .find_surb(SurbMatcher::Pseudonym(pseudonym))
727            .ok_or(anyhow::anyhow!("the first packet must have left a SURB behind"))?
728            .surb;
729        let capacity = SurbStoreConfig::default().rb_capacity;
730        let filled = f.receiver.surb_store.insert_surbs(
731            pseudonym,
732            (0..capacity as u64).map(|i| (i.to_be_bytes(), surb.clone())).collect(),
733        );
734        assert_eq!(capacity, filled.retained, "precondition: the buffer is full");
735
736        // Only the receiver's decode is recorded: the fixture's relay logs warnings of its own.
737        let data = from_relay()?;
738        let log = Arc::new(LevelCounter::default());
739        let info = tracing::subscriber::with_default(log.clone(), || receive(data))?;
740
741        assert!(info.num_surbs > 0, "the packet must carry a return path");
742        assert_eq!(
743            info.num_surbs, info.num_evicted_surbs,
744            "each SURB of the packet costs the full buffer one, and that total is what the layers above are told"
745        );
746        assert_eq!(
747            0,
748            log.warnings.load(Ordering::Relaxed),
749            "no share was lost, and the store's summary carries the warning, not the decoder"
750        );
751        assert!(
752            log.debugs.load(Ordering::Relaxed) > 0,
753            "the overflow is still reported, at debug level"
754        );
755
756        Ok(())
757    }
758
759    #[test_log::test(tokio::test)]
760    async fn encode_decode_packet_full_round_trip_with_pix() -> anyhow::Result<()> {
761        let f = PixTestFixture::new().await?;
762
763        let pseudonym = HoprPseudonym::random();
764        let ssa_id = SsaId::new(pseudonym, 1.try_into()?);
765
766        // New commitment of the receiver
767        let _ = f.receiver.ssa_rcn.new_exit_commitment(
768            ssa_id,
769            hopr_protocol_pix::PixParams::try_from_config::<HoprPixSpec>(f.sender.ssa_gen.config())?,
770        )?;
771
772        // Sender makes a commitment too and delivers it to the receiver
773        let sender_commitment = f.sender.ssa_gen.new_ssa_commitment(&pseudonym, ssa_id.ssa_index())?;
774        sender_commitment.process_into_reconstructor(&f.receiver.ssa_rcn)?;
775
776        // Need to generate multiple messages to recover the SSA
777        let threshold = f.sender.ssa_gen.config().threshold as usize;
778        let num_polys = f.sender.ssa_gen.config().polynomials_per_ssa as usize;
779        let surplus = f.sender.ssa_gen.config().surplus_shares as usize;
780        // Shares are emitted round-robin across the emission window, so every polynomial reaches
781        // `threshold` inside the same round and the SSA completes on the last share of round
782        // `threshold` — exactly the `polys × threshold` packets the agreed quota is priced on.
783        // Draining one polynomial at a time instead spent earlier polynomials' surplus before the
784        // last one had any shares at all, pushing recovery out to nearly the whole budget.
785        //
786        // That holds only while the *whole* SSA fits in one emission window. Above it the window
787        // covers a prefix of the queue, later polynomials do not start until earlier ones are drained
788        // to `threshold + surplus`, and recovery moves out to
789        // `(polys − window)(threshold + surplus) + window × threshold`. This fixture is well under
790        // the window; the assertion keeps a future widening from silently making the expectation
791        // wrong rather than loudly failing.
792        assert!(
793            num_polys <= hopr_protocol_pix::SHARE_EMISSION_WINDOW,
794            "recovery_at assumes the whole SSA fits in one emission window ({num_polys} polynomials against a window \
795             of {})",
796            hopr_protocol_pix::SHARE_EMISSION_WINDOW
797        );
798        let recovery_at = num_polys * threshold - 1;
799
800        let num_msgs_to_recover_ssa = num_polys * (threshold + surplus);
801        for i in 0..num_msgs_to_recover_ssa {
802            let data = format!("some random message #{i} to encode and decode");
803            let resp = format!("some random response #{i} to encode and decode");
804
805            // Sender creates a packet
806            let out_packet = f.sender_encoder.encode_packet(
807                data.clone(),
808                ResolvedTransportRouting::Forward {
809                    pseudonym,
810                    forward_path: f.forward_path.clone(),
811                    return_paths: vec![f.return_path.clone()],
812                },
813                None,
814                None,
815            )?;
816
817            // Relay decodes the packet
818            let fwd_packet = f
819                .relay_decoder
820                .decode(f.sender.offchain_key.public().into(), out_packet.data)?;
821            let fwd_packet = fwd_packet
822                .try_as_forwarded()
823                .ok_or(anyhow::anyhow!("packet is not forwarded"))?;
824
825            // Receiver receives the packet from the relay and decodes it
826            let in_packet = f
827                .receiver_decoder
828                .decode(f.relay.offchain_key.public().into(), fwd_packet.data)?;
829            let in_packet = in_packet.try_as_final().ok_or(anyhow::anyhow!("packet is not final"))?;
830
831            assert_eq!(pseudonym, in_packet.sender);
832            assert_eq!(data.as_bytes(), in_packet.plain_text.as_ref());
833
834            // Receiver creates a response packet using a SURB
835            let out_packet = f.surb_reply(pseudonym, resp.clone())?;
836
837            // Receiver discovers the encrypted share from the used SURB
838            let enc_share = out_packet
839                .encrypted_pix_share
840                .ok_or(anyhow::anyhow!("no pix share found"))?;
841            assert_eq!(pseudonym, enc_share.pseudonym);
842
843            // The receiver inserts the encrypted share to be decoded by the acknowledgement from the relay
844            f.receiver.ssa_rcn.insert_encrypted_share(
845                f.relay.offchain_key.public(),
846                out_packet.ack_challenge,
847                enc_share,
848            )?;
849
850            let fwd_packet = f
851                .relay_decoder
852                .decode(f.receiver.offchain_key.public().into(), out_packet.data)?;
853            let fwd_packet = fwd_packet
854                .try_as_forwarded()
855                .ok_or(anyhow::anyhow!("packet is not forwarded"))?;
856
857            // Relay delivers the acknowledgement to back to the receiver
858            let resolutions = f.receiver.ssa_rcn.acknowledge_shares(
859                *f.relay.offchain_key.public(),
860                vec![VerifiedAcknowledgement::new(fwd_packet.ack_key_prev_hop, &f.relay.offchain_key).leak()],
861            )?;
862
863            // Every share that advances reconstruction reports progress, so what distinguishes the
864            // recovering share from the rest is the terminal resolution, not the resolution count.
865            let recovered = resolutions
866                .iter()
867                .filter_map(|r| r.clone().try_as_recovered_ssa())
868                .collect::<Vec<_>>();
869
870            // Once enough shares have been received, the receiver can recover the SSA
871            if i == recovery_at {
872                assert_eq!(
873                    1,
874                    recovered.len(),
875                    "expected exactly one recovery at #{i}: {resolutions:?}"
876                );
877                assert_eq!(recovered[0].ssa_id, ssa_id);
878            } else {
879                assert!(recovered.is_empty(), "no recovery must happen at #{i}: {resolutions:?}");
880            }
881
882            // Sender decodes the response packet
883            f.sender_assert_reply(fwd_packet.data, resp.as_bytes())?;
884        }
885
886        Ok(())
887    }
888
889    #[test_log::test(tokio::test)]
890    async fn encode_decode_packet_full_round_trip_with_pix_multi_commitment() -> anyhow::Result<()> {
891        let f = PixTestFixture::new().await?;
892
893        const NUM_COMMITMENTS: usize = 2;
894        const GAP_MSGS: usize = 10;
895
896        let pseudonym = HoprPseudonym::random();
897
898        let threshold = f.sender.ssa_gen.config().threshold as usize;
899        let num_polys = f.sender.ssa_gen.config().polynomials_per_ssa as usize;
900        let surplus = f.sender.ssa_gen.config().surplus_shares as usize;
901        let shares_per_poly = threshold + surplus;
902        let msgs_per_commitment = num_polys * shares_per_poly;
903
904        // Create SSA IDs for all commitments upfront
905        let ssa_ids: Vec<SsaId<HoprPseudonym>> = (0..NUM_COMMITMENTS)
906            .map(|k| SsaId::new(pseudonym, ((k + 1) as u32).try_into().unwrap()))
907            .collect();
908
909        // --- First commitment setup (before the loop) ---
910        let _ = f.receiver.ssa_rcn.new_exit_commitment(
911            ssa_ids[0],
912            hopr_protocol_pix::PixParams::try_from_config::<HoprPixSpec>(f.sender.ssa_gen.config())?,
913        )?;
914        let sender_commitment = f
915            .sender
916            .ssa_gen
917            .new_ssa_commitment(&pseudonym, ssa_ids[0].ssa_index())?;
918        sender_commitment.process_into_reconstructor(&f.receiver.ssa_rcn)?;
919
920        let segment_len = msgs_per_commitment + GAP_MSGS;
921
922        let mut recovered_ssa_ids: Vec<SsaId<HoprPseudonym>> = Vec::new();
923        let mut no_share_indices: Vec<usize> = Vec::new();
924
925        let total_msgs = NUM_COMMITMENTS * msgs_per_commitment + (NUM_COMMITMENTS - 1) * GAP_MSGS;
926
927        for i in 0..total_msgs {
928            let data = format!("some random message #{i} to encode and decode");
929            let resp = format!("some random response #{i} to encode and decode");
930
931            // 1. Forward: sender encodes with SURB
932            let out_packet = f.sender_encoder.encode_packet(
933                data.clone(),
934                ResolvedTransportRouting::Forward {
935                    pseudonym,
936                    forward_path: f.forward_path.clone(),
937                    return_paths: vec![f.return_path.clone()],
938                },
939                None,
940                None,
941            )?;
942
943            // 2. Relay decodes forward packet
944            let fwd_packet = f
945                .relay_decoder
946                .decode(f.sender.offchain_key.public().into(), out_packet.data)?;
947            let fwd_packet = fwd_packet
948                .try_as_forwarded()
949                .ok_or(anyhow::anyhow!("packet is not forwarded"))?;
950
951            // 3. Receiver decodes forward packet
952            let in_packet = f
953                .receiver_decoder
954                .decode(f.relay.offchain_key.public().into(), fwd_packet.data)?;
955            let in_packet = in_packet.try_as_final().ok_or(anyhow::anyhow!("packet is not final"))?;
956            assert_eq!(pseudonym, in_packet.sender);
957            assert_eq!(data.as_bytes(), in_packet.plain_text.as_ref());
958
959            // 4. Receiver finds SURB and encodes reply
960            let out_packet = f.surb_reply(pseudonym, resp.clone())?;
961
962            // 5. Relay decodes the reply (always)
963            let fwd_packet = f
964                .relay_decoder
965                .decode(f.receiver.offchain_key.public().into(), out_packet.data)?;
966            let fwd_packet = fwd_packet
967                .try_as_forwarded()
968                .ok_or(anyhow::anyhow!("packet is not forwarded"))?;
969
970            let pos_in_segment = i % segment_len;
971
972            // 6. Determine if we are in a share phase or a gap
973            if pos_in_segment < msgs_per_commitment {
974                // Share phase — PIX share should exist
975                let enc_share = out_packet
976                    .encrypted_pix_share
977                    .ok_or(anyhow::anyhow!("expected pix share at msg #{i}"))?;
978                assert_eq!(pseudonym, enc_share.pseudonym);
979
980                f.receiver.ssa_rcn.insert_encrypted_share(
981                    f.relay.offchain_key.public(),
982                    out_packet.ack_challenge,
983                    enc_share,
984                )?;
985
986                let resolutions = f.receiver.ssa_rcn.acknowledge_shares(
987                    *f.relay.offchain_key.public(),
988                    vec![VerifiedAcknowledgement::new(fwd_packet.ack_key_prev_hop, &f.relay.offchain_key).leak()],
989                )?;
990
991                // Progress resolutions accompany every share that advances reconstruction; only a
992                // recovery is a milestone worth collecting here.
993                recovered_ssa_ids.extend(
994                    resolutions
995                        .into_iter()
996                        .filter_map(|r| r.try_as_recovered_ssa())
997                        .map(|r| r.ssa_id),
998                );
999            } else {
1000                // Gap phase — no PIX share
1001                assert!(
1002                    out_packet.encrypted_pix_share.is_none(),
1003                    "unexpected PIX share during gap at message #{i}"
1004                );
1005                no_share_indices.push(i);
1006
1007                // At the last message of this gap, set up the next commitment
1008                if pos_in_segment == segment_len - 1 {
1009                    let next_idx = i / segment_len + 1;
1010                    let _ = f.receiver.ssa_rcn.new_exit_commitment(
1011                        ssa_ids[next_idx],
1012                        hopr_protocol_pix::PixParams::try_from_config::<HoprPixSpec>(f.sender.ssa_gen.config())?,
1013                    )?;
1014                    let next_commitment = f
1015                        .sender
1016                        .ssa_gen
1017                        .new_ssa_commitment(&pseudonym, ssa_ids[next_idx].ssa_index())?;
1018                    next_commitment.process_into_reconstructor(&f.receiver.ssa_rcn)?;
1019                }
1020            }
1021
1022            // 7. Sender decodes the response (always)
1023            f.sender_assert_reply(fwd_packet.data, resp.as_bytes())?;
1024        }
1025
1026        // --- Final verification ---
1027
1028        // 1. Verify the number of recovered secrets equals the number of commitments made
1029        assert_eq!(
1030            recovered_ssa_ids.len(),
1031            NUM_COMMITMENTS,
1032            "expected {NUM_COMMITMENTS} RecoveredSsa (1 per commitment), got {}",
1033            recovered_ssa_ids.len()
1034        );
1035
1036        // 2. Verify each recovered SSA corresponds to the correct commitment
1037        recovered_ssa_ids.sort_by_key(|id| id.ssa_index());
1038        for (k, ssa_id) in ssa_ids.iter().enumerate() {
1039            assert_eq!(
1040                recovered_ssa_ids[k], *ssa_id,
1041                "recovered SSA #{k} should match commitment {k}"
1042            );
1043        }
1044
1045        // 3. Verify that no_share_indices covers exactly all gap periods
1046        let expected_no_share_indices: Vec<usize> = (0..NUM_COMMITMENTS - 1)
1047            .flat_map(|k| {
1048                let gap_start = (k + 1) * msgs_per_commitment + k * GAP_MSGS;
1049                gap_start..gap_start + GAP_MSGS
1050            })
1051            .collect();
1052        assert_eq!(
1053            no_share_indices, expected_no_share_indices,
1054            "no-share indices must match all gap periods"
1055        );
1056
1057        Ok(())
1058    }
1059
1060    #[tokio::test]
1061    async fn encode_decode_acknowledgements() -> anyhow::Result<()> {
1062        let blokli_client = create_blokli_client()?;
1063        let sender = create_node(0, &blokli_client).await?;
1064        let receiver = create_node(1, &blokli_client).await?;
1065
1066        let encoder = create_encoder(&sender);
1067        let decoder = create_decoder(&receiver);
1068
1069        let acks = (0..MAX_ACKNOWLEDGEMENTS_BATCH_SIZE)
1070            .map(|_| VerifiedAcknowledgement::random(&PEERS[0].1))
1071            .collect::<Vec<_>>();
1072        let out_packet = encoder.encode_acknowledgements(&acks, PEERS[1].1.public())?;
1073
1074        let in_packet = decoder.decode(sender.offchain_key.public().into(), out_packet.data)?;
1075        let in_packet = in_packet
1076            .try_as_acknowledgement()
1077            .ok_or(anyhow::anyhow!("packet is not acknowledgement"))?;
1078
1079        assert_eq!(acks.len(), in_packet.received_acks.len());
1080
1081        for (i, ack) in in_packet.received_acks.into_iter().enumerate() {
1082            let verified = ack.verify(PEERS[0].1.public())?;
1083            assert_eq!(acks[i], verified);
1084        }
1085
1086        Ok(())
1087    }
1088
1089    #[tokio::test]
1090    async fn encode_should_fail_on_too_many_acknowledgements() -> anyhow::Result<()> {
1091        let blokli_client = create_blokli_client()?;
1092        let sender = create_node(0, &blokli_client).await?;
1093
1094        let encoder = create_encoder(&sender);
1095        let acks = (0..MAX_ACKNOWLEDGEMENTS_BATCH_SIZE + 1)
1096            .map(|_| VerifiedAcknowledgement::random(&PEERS[0].1))
1097            .collect::<Vec<_>>();
1098
1099        assert!(encoder.encode_acknowledgements(&acks, PEERS[1].1.public()).is_err());
1100
1101        Ok(())
1102    }
1103
1104    #[tokio::test]
1105    async fn decode_should_fail_on_invalid_data() -> anyhow::Result<()> {
1106        let blokli_client = create_blokli_client()?;
1107        let receiver = create_node(0, &blokli_client).await?;
1108        let decoder = create_decoder(&receiver);
1109
1110        let sender_peer_id = PEERS[1].1.public().into();
1111        let invalid_data = bytes::Bytes::from(vec![0u8; 100]);
1112
1113        let result = decoder.decode(sender_peer_id, invalid_data);
1114        assert!(result.is_err());
1115        assert!(result.err().context("must not decode")?.is_undecodable());
1116
1117        Ok(())
1118    }
1119
1120    #[tokio::test]
1121    async fn decode_should_fail_on_replay() -> anyhow::Result<()> {
1122        let blokli_client = create_blokli_client()?;
1123        let sender = create_node(0, &blokli_client).await?;
1124        let receiver = create_node(1, &blokli_client).await?;
1125
1126        let encoder = create_encoder(&sender);
1127        let decoder = create_decoder(&receiver);
1128
1129        let data = b"some message";
1130        let out_packet = encoder.encode_packet(
1131            data,
1132            ResolvedTransportRouting::Forward {
1133                pseudonym: HoprPseudonym::random(),
1134                forward_path: ValidatedPath::direct(
1135                    *receiver.offchain_key.public(),
1136                    receiver.chain_key.public().to_address(),
1137                ),
1138                return_paths: vec![],
1139            },
1140            None,
1141            None,
1142        )?;
1143
1144        // First decode should succeed
1145        decoder.decode(sender.offchain_key.public().into(), out_packet.data.clone())?;
1146
1147        // Second decode with same packet should fail (replay)
1148        let result = decoder.decode(sender.offchain_key.public().into(), out_packet.data);
1149        assert!(result.is_err());
1150        assert!(
1151            result.err().context("a duplicate must be rejected")?.is_replay(),
1152            "a duplicate must be reported as a replay"
1153        );
1154
1155        Ok(())
1156    }
1157
1158    /// The replay check runs before the packet is decoded, so a replay whose remainder has been corrupted is
1159    /// reported as a replay rather than as undecodable. This pins the ordering: if the check moved back after
1160    /// `from_incoming`, this test would see `Undecodable` instead.
1161    #[tokio::test]
1162    async fn replay_should_be_detected_before_the_packet_is_decoded() -> anyhow::Result<()> {
1163        let blokli_client = create_blokli_client()?;
1164        let sender = create_node(0, &blokli_client).await?;
1165        let receiver = create_node(1, &blokli_client).await?;
1166
1167        let encoder = create_encoder(&sender);
1168        let decoder = create_decoder(&receiver);
1169
1170        let out_packet = encoder.encode_packet(
1171            b"a message to replay",
1172            ResolvedTransportRouting::Forward {
1173                pseudonym: HoprPseudonym::random(),
1174                forward_path: ValidatedPath::direct(
1175                    *receiver.offchain_key.public(),
1176                    receiver.chain_key.public().to_address(),
1177                ),
1178                return_paths: vec![],
1179            },
1180            None,
1181            None,
1182        )?;
1183
1184        let sender_peer_id: PeerId = sender.offchain_key.public().into();
1185        decoder.decode(sender_peer_id, out_packet.data.clone())?;
1186
1187        // Keep the alpha, so the shared secret - and hence the tag - is still derivable, but destroy the routing
1188        // header and payload after it, so the packet cannot be decoded any further. The replay must be caught from
1189        // the tag, before the header MAC is checked.
1190        const ALPHA_LEN: usize = 32;
1191        let mut corrupted = out_packet.data.to_vec();
1192        let header_start = ALPHA_LEN;
1193        let header_end = header_start + hopr_crypto_packet::prelude::HoprPacket::SIZE / 2;
1194        corrupted[header_start..header_end].fill(0xff);
1195        let corrupted = Bytes::from(corrupted);
1196
1197        let result = decoder.decode(sender_peer_id, corrupted);
1198        assert!(
1199            result.err().context("a replay must be rejected")?.is_replay(),
1200            "a replay must be caught from the tag, before the rest of the packet is decoded"
1201        );
1202
1203        Ok(())
1204    }
1205
1206    /// Random bytes must not enter the filter: the tag is only derived once the shared secret exists, so garbage is
1207    /// rejected before the filter is consulted at all.
1208    #[tokio::test]
1209    async fn an_undecodable_packet_should_not_be_remembered() -> anyhow::Result<()> {
1210        let blokli_client = create_blokli_client()?;
1211        let sender = create_node(0, &blokli_client).await?;
1212        let receiver = create_node(1, &blokli_client).await?;
1213
1214        let decoder = create_decoder(&receiver);
1215        let sender_peer_id: PeerId = sender.offchain_key.public().into();
1216
1217        let garbage = Bytes::from(vec![0x42u8; hopr_crypto_packet::prelude::HoprPacket::SIZE]);
1218
1219        let first = decoder.decode(sender_peer_id, garbage.clone());
1220        assert!(
1221            first.err().context("random bytes must not decode")?.is_undecodable(),
1222            "random bytes must not decode"
1223        );
1224        assert_eq!(
1225            0,
1226            decoder.replay_filter().count(),
1227            "a failed decode must not enter the filter"
1228        );
1229
1230        let second = decoder.decode(sender_peer_id, garbage);
1231        assert!(
1232            second
1233                .err()
1234                .context("the same garbage must be rejected")?
1235                .is_undecodable(),
1236            "the same garbage must be undecodable twice, not a replay the second time"
1237        );
1238
1239        Ok(())
1240    }
1241
1242    /// The decoder's own check-then-commit must let exactly one of two concurrent decodes of the same packet
1243    /// through. Both threads pass the `contains` check before either commits, so this is the `commit` return value
1244    /// that decides - the filter-level test alone would not catch a decoder that dropped it.
1245    #[test]
1246    fn concurrent_decodes_of_the_same_packet_should_yield_exactly_one_success() -> anyhow::Result<()> {
1247        let runtime = tokio::runtime::Runtime::new()?;
1248        let blokli_client = create_blokli_client()?;
1249        let (sender, receiver) = runtime.block_on(async {
1250            Ok::<_, anyhow::Error>((
1251                create_node(0, &blokli_client).await.context("sender node")?,
1252                create_node(1, &blokli_client).await.context("receiver node")?,
1253            ))
1254        })?;
1255
1256        let encoder = create_encoder(&sender);
1257        let decoder = std::sync::Arc::new(create_decoder(&receiver));
1258        let sender_peer_id: PeerId = sender.offchain_key.public().into();
1259
1260        // Several rounds, so a lost race in one round does not hide an always-broken commit.
1261        for _ in 0..8 {
1262            let out_packet = encoder.encode_packet(
1263                b"a message decoded concurrently",
1264                ResolvedTransportRouting::Forward {
1265                    pseudonym: HoprPseudonym::random(),
1266                    forward_path: ValidatedPath::direct(
1267                        *receiver.offchain_key.public(),
1268                        receiver.chain_key.public().to_address(),
1269                    ),
1270                    return_paths: vec![],
1271                },
1272                None,
1273                None,
1274            )?;
1275
1276            // Two OS threads released together: both pass `contains` before either commits, so only the `commit`
1277            // return value can decide between them.
1278            let barrier = std::sync::Arc::new(std::sync::Barrier::new(2));
1279            let successes = std::thread::scope(|scope| {
1280                let handles = (0..2)
1281                    .map(|_| {
1282                        let (decoder, data, barrier) = (decoder.clone(), out_packet.data.clone(), barrier.clone());
1283                        scope.spawn(move || {
1284                            barrier.wait();
1285                            decoder.decode(sender_peer_id, data).is_ok()
1286                        })
1287                    })
1288                    .collect::<Vec<_>>();
1289                handles
1290                    .into_iter()
1291                    .map(|h| h.join().map_err(|_| anyhow::anyhow!("decode must not panic")))
1292                    .collect::<anyhow::Result<Vec<_>>>()
1293                    .map(|joined| joined.into_iter().filter(|ok| *ok).count())
1294            })?;
1295
1296            assert_eq!(1, successes, "exactly one concurrent decode may succeed");
1297        }
1298
1299        Ok(())
1300    }
1301
1302    /// A packet that fails its header MAC must not enter the filter. The tag is derivable from the node's public
1303    /// key and the wire alpha alone, so were it committed before the MAC, any stranger could rotate the filter at
1304    /// one elliptic-curve multiplication per token.
1305    #[tokio::test]
1306    async fn a_packet_failing_the_header_mac_should_not_enter_the_filter() -> anyhow::Result<()> {
1307        let blokli_client = create_blokli_client()?;
1308        let sender = create_node(0, &blokli_client).await?;
1309        let receiver = create_node(1, &blokli_client).await?;
1310
1311        let encoder = create_encoder(&sender);
1312        let out_packet = encoder.encode_packet(
1313            b"a packet whose header will be damaged",
1314            ResolvedTransportRouting::Forward {
1315                pseudonym: HoprPseudonym::random(),
1316                forward_path: ValidatedPath::direct(
1317                    *receiver.offchain_key.public(),
1318                    receiver.chain_key.public().to_address(),
1319                ),
1320                return_paths: vec![],
1321            },
1322            None,
1323            None,
1324        )?;
1325
1326        let decoder = create_decoder(&receiver);
1327        let sender_peer_id: PeerId = OffchainKeypair::random().public().into();
1328
1329        // Keep the alpha, so the secret and the tag are derivable, but damage the header after it.
1330        const ALPHA_LEN: usize = 32;
1331        let mut forged = out_packet.data.to_vec();
1332        forged[ALPHA_LEN..ALPHA_LEN + 64].fill(0xff);
1333        let forged = Bytes::from(forged);
1334
1335        assert!(
1336            decoder
1337                .decode(sender_peer_id, forged)
1338                .err()
1339                .context("a damaged header must be rejected")?
1340                .is_undecodable(),
1341            "a damaged header must be undecodable, not a replay"
1342        );
1343        assert_eq!(
1344            0,
1345            decoder.replay_filter().count(),
1346            "a packet that fails the header MAC must not be recorded"
1347        );
1348
1349        Ok(())
1350    }
1351
1352    /// The filter is global across previous hops: the token names the packet, not the sender, so replaying the same
1353    /// bytes through a different peer must still be caught.
1354    #[tokio::test]
1355    async fn a_replay_should_be_detected_from_a_different_peer() -> anyhow::Result<()> {
1356        let blokli_client = create_blokli_client()?;
1357        let sender = create_node(0, &blokli_client).await?;
1358        let other_sender = create_node(2, &blokli_client).await?;
1359        let receiver = create_node(1, &blokli_client).await?;
1360
1361        let encoder = create_encoder(&sender);
1362        let decoder = create_decoder(&receiver);
1363
1364        let out_packet = encoder.encode_packet(
1365            b"a message to replay",
1366            ResolvedTransportRouting::Forward {
1367                pseudonym: HoprPseudonym::random(),
1368                forward_path: ValidatedPath::direct(
1369                    *receiver.offchain_key.public(),
1370                    receiver.chain_key.public().to_address(),
1371                ),
1372                return_paths: vec![],
1373            },
1374            None,
1375            None,
1376        )?;
1377
1378        decoder.decode(sender.offchain_key.public().into(), out_packet.data.clone())?;
1379        let result = decoder.decode(other_sender.offchain_key.public().into(), out_packet.data);
1380
1381        assert!(
1382            result.err().context("a replay must be rejected")?.is_replay(),
1383            "a replay must be caught regardless of which peer delivered it"
1384        );
1385
1386        Ok(())
1387    }
1388
1389    #[tokio::test]
1390    async fn decode_should_fail_on_incorrect_key() -> anyhow::Result<()> {
1391        let blokli_client = create_blokli_client()?;
1392        let sender = create_node(0, &blokli_client).await?;
1393        let receiver = create_node(1, &blokli_client).await?;
1394        let incorrect_receiver = create_node(2, &blokli_client).await?;
1395
1396        let encoder = create_encoder(&sender);
1397        let decoder = create_decoder(&incorrect_receiver);
1398
1399        let data = b"some message";
1400        let out_packet = encoder.encode_packet(
1401            data,
1402            ResolvedTransportRouting::Forward {
1403                pseudonym: HoprPseudonym::random(),
1404                forward_path: ValidatedPath::direct(
1405                    *receiver.offchain_key.public(),
1406                    receiver.chain_key.public().to_address(),
1407                ),
1408                return_paths: vec![],
1409            },
1410            None,
1411            None,
1412        )?;
1413
1414        let result = decoder.decode(sender.offchain_key.public().into(), out_packet.data);
1415        assert!(result.is_err());
1416        assert!(result.err().context("must not decode")?.is_undecodable());
1417
1418        Ok(())
1419    }
1420
1421    /// The manual `PartialEq` is what the transport compares configs with, so a field it forgets is a field that
1422    /// silently stops participating in equality. This pins the replay-filter field into it.
1423    #[test]
1424    fn codec_config_equality_should_include_the_replay_filter() {
1425        let base = HoprCodecConfig::default();
1426        assert_eq!(base, HoprCodecConfig::default());
1427
1428        let other = HoprCodecConfig {
1429            replay_filter: crate::ReplayFilterConfig {
1430                max_tracked_packets: base.replay_filter.max_tracked_packets * 2,
1431                ..base.replay_filter
1432            },
1433            ..base
1434        };
1435        assert_ne!(base, other, "a different replay capacity must make the configs unequal");
1436
1437        let other = HoprCodecConfig {
1438            replay_filter: crate::ReplayFilterConfig {
1439                shards: base.replay_filter.shards / 2,
1440                ..base.replay_filter
1441            },
1442            ..base
1443        };
1444        assert_ne!(base, other, "a different shard count must make the configs unequal");
1445    }
1446
1447    #[cfg(feature = "serde")]
1448    #[test]
1449    fn the_replay_filter_config_should_round_trip_through_yaml() -> anyhow::Result<()> {
1450        let doc = "replay_filter:\n  max_tracked_packets: 5000\n  shards: 8\n";
1451        let parsed: HoprCodecConfig = serde_saphyr::from_str(doc)?;
1452
1453        assert_eq!(5000, parsed.replay_filter.max_tracked_packets);
1454        assert_eq!(8, parsed.replay_filter.shards);
1455
1456        let serialized = serde_saphyr::to_string(&parsed)?;
1457        let reparsed: HoprCodecConfig = serde_saphyr::from_str(&serialized)?;
1458        assert_eq!(parsed, reparsed);
1459
1460        // An omitted block must fall back to the defaults, not fail under `deny_unknown_fields`.
1461        let omitted: HoprCodecConfig = serde_saphyr::from_str("outgoing_ticket_price: null\n")?;
1462        assert_eq!(crate::ReplayFilterConfig::default(), omitted.replay_filter);
1463
1464        Ok(())
1465    }
1466
1467    #[cfg(feature = "serde")]
1468    #[test]
1469    fn an_invalid_replay_filter_config_should_be_rejected() -> anyhow::Result<()> {
1470        let doc = "replay_filter:\n  max_tracked_packets: 10\n  shards: 3\n";
1471        let parsed: HoprCodecConfig = serde_saphyr::from_str(doc).context("must deserialize")?;
1472        assert!(
1473            validator::Validate::validate(&parsed).is_err(),
1474            "out-of-range capacity and a non-power-of-two shard count must fail validation"
1475        );
1476        Ok(())
1477    }
1478}