Skip to main content

hopr_protocol_hopr/
ticket_processing.rs

1use hopr_api::{
2    chain::ChainReadChannelOperations,
3    types::{crypto::prelude::*, internal::prelude::*, primitive::prelude::Address},
4};
5#[cfg(feature = "rayon")]
6use hopr_utils::parallelize::cpu::rayon::prelude::*;
7use validator::ValidationError;
8
9use crate::{HoprProtocolError, ResolvedAcknowledgement, TicketAcknowledgementError, UnacknowledgedTicketProcessor};
10
11#[cfg(all(feature = "telemetry", not(test)))]
12lazy_static::lazy_static! {
13        /// Whether per-peer metrics are enabled (disabled by default to avoid cardinality explosion).
14        static ref PER_PEER_ENABLED: bool = std::env::var("HOPR_METRICS_UNACK_PER_PEER")
15            .map(|v| v == "1" || v.eq_ignore_ascii_case("true"))
16            .unwrap_or(false);
17
18        static ref UNACK_PEERS: hopr_api::types::telemetry::SimpleGauge = hopr_api::types::telemetry::SimpleGauge::new(
19            "hopr_tickets_unack_peers_total",
20            "Number of peers with unacknowledged tickets in cache",
21        )
22        .unwrap();
23        static ref UNACK_TICKETS: hopr_api::types::telemetry::SimpleGauge = hopr_api::types::telemetry::SimpleGauge::new(
24            "hopr_tickets_unack_tickets_total",
25            "Total number of unacknowledged tickets across all peer caches",
26        )
27        .unwrap();
28        static ref UNACK_INSERTIONS: hopr_api::types::telemetry::SimpleCounter = hopr_api::types::telemetry::SimpleCounter::new(
29            "hopr_tickets_unack_insertions_total",
30            "Total number of unacknowledged tickets inserted into cache",
31        )
32        .unwrap();
33        static ref UNACK_LOOKUPS: hopr_api::types::telemetry::SimpleCounter = hopr_api::types::telemetry::SimpleCounter::new(
34            "hopr_tickets_unack_lookups_total",
35            "Total number of ticket acknowledgement lookups",
36        )
37        .unwrap();
38        static ref UNACK_LOOKUP_MISSES: hopr_api::types::telemetry::SimpleCounter = hopr_api::types::telemetry::SimpleCounter::new(
39            "hopr_tickets_unack_lookup_misses_total",
40            "Total number of ticket lookup failures (unknown ticket)",
41        )
42        .unwrap();
43        static ref UNACK_EVICTIONS: hopr_api::types::telemetry::SimpleCounter = hopr_api::types::telemetry::SimpleCounter::new(
44            "hopr_tickets_unack_evictions_total",
45            "Total number of unacknowledged tickets evicted from cache due to TTL or capacity limits",
46        )
47        .unwrap();
48        static ref UNACK_PEER_EVICTIONS: hopr_api::types::telemetry::SimpleCounter = hopr_api::types::telemetry::SimpleCounter::new(
49            "hopr_tickets_unack_peer_evictions_total",
50            "Total number of peer caches evicted from the outer unacknowledged ticket cache",
51        )
52        .unwrap();
53        static ref UNACK_TICKETS_PER_PEER: hopr_api::types::telemetry::MultiGauge = hopr_api::types::telemetry::MultiGauge::new(
54            "hopr_tickets_unack_tickets_per_peer",
55            "Number of unacknowledged tickets per peer in cache (enable with HOPR_METRICS_UNACK_PER_PEER=1)",
56            &["peer"],
57        )
58        .unwrap();
59}
60
61const MIN_UNACK_TICKET_TIMEOUT: std::time::Duration = std::time::Duration::from_secs(10);
62fn validate_unack_ticket_timeout(timeout: &std::time::Duration) -> Result<(), ValidationError> {
63    if timeout < &MIN_UNACK_TICKET_TIMEOUT {
64        Err(ValidationError::new("unack_ticket_timeout too low"))
65    } else {
66        Ok(())
67    }
68}
69
70fn default_unack_ticket_timeout() -> std::time::Duration {
71    std::time::Duration::from_secs(30)
72}
73
74fn default_max_unack_tickets() -> usize {
75    10_000_000
76}
77
78fn default_max_tracked_ticket_indices() -> usize {
79    10_000_000
80}
81
82fn just_true() -> bool {
83    true
84}
85
86/// Configuration for the [`HoprUnacknowledgedTicketProcessor`].
87
88#[derive(Debug, Clone, Copy, smart_default::SmartDefault, PartialEq, validator::Validate)]
89#[cfg_attr(
90    feature = "serde",
91    derive(serde::Deserialize, serde::Serialize),
92    serde(deny_unknown_fields)
93)]
94pub struct HoprUnacknowledgedTicketProcessorConfig {
95    /// Time after which an unacknowledged ticket is considered stale and is removed from the cache.
96    ///
97    /// If the counterparty does not send an acknowledgement within this period, the ticket is lost forever.
98    ///
99    /// This also bounds replay protection: the record that a ticket index was already accepted expires
100    /// on the same timeout, so an index can be replayed once this period has passed. Raising it
101    /// strengthens that protection at the cost of memory, but unless
102    /// [`max_tracked_ticket_indices`](Self::max_tracked_ticket_indices) is raised accordingly, that capacity
103    /// becomes the binding limit sooner.
104    ///
105    /// Default is 30 seconds.
106    #[default(default_unack_ticket_timeout())]
107    #[validate(custom(function = "validate_unack_ticket_timeout"))]
108    #[cfg_attr(
109        feature = "serde",
110        serde(default = "default_unack_ticket_timeout", with = "humantime_serde")
111    )]
112    pub unack_ticket_timeout: std::time::Duration,
113    /// Maximum number of unacknowledged tickets that can be stored per next hop at any given time.
114    ///
115    /// When more tickets are received, the oldest ones are discarded and lost forever.
116    ///
117    /// Default is 10 000 000.
118    #[default(default_max_unack_tickets())]
119    #[validate(range(min = 100))]
120    #[cfg_attr(feature = "serde", serde(default = "default_max_unack_tickets"))]
121    pub max_unack_tickets: usize,
122    /// Maximum number of accepted ticket indices remembered for replay protection, across all channels.
123    ///
124    /// Once the limit is reached, the least-recently-used records are evicted and those indices become
125    /// replayable again; fresh indices are never refused. Size it for the number of tickets accepted per
126    /// [`unack_ticket_timeout`](Self::unack_ticket_timeout) window.
127    ///
128    /// Default is 10 000 000.
129    #[default(default_max_tracked_ticket_indices())]
130    #[validate(range(min = 100))]
131    #[cfg_attr(feature = "serde", serde(default = "default_max_tracked_ticket_indices"))]
132    pub max_tracked_ticket_indices: usize,
133    /// Indicates whether to use batch verification algorithm for acknowledgements.
134    ///
135    /// This has a positive performance impact on higher workloads.
136    ///
137    /// Default is true.
138    #[default(just_true())]
139    #[cfg_attr(feature = "serde", serde(default = "just_true"))]
140    pub use_batch_verification: bool,
141}
142
143/// HOPR-specific implementation of [`UnacknowledgedTicketProcessor`].
144#[derive(Clone)]
145pub struct HoprUnacknowledgedTicketProcessor<Chain> {
146    unacknowledged_tickets:
147        moka::sync::Cache<OffchainPublicKey, moka::sync::Cache<HalfKeyChallenge, UnacknowledgedTicket>>,
148    /// Tracks ticket indices already accepted per (issuer -> this node channel, epoch), so a
149    /// counterparty cannot replay the same index in many tickets (only one of which would ever be
150    /// redeemable).
151    ///
152    /// Keyed by the verified issuer address rather than the channel id: the destination of the
153    /// channel is always this node, so the issuer identifies the channel equally well, with a
154    /// smaller key and no hashing per ticket.
155    ///
156    /// An entry is never removed upon acknowledgement: a ticket whose acknowledgement is withheld,
157    /// or that turns out to be losing, must not allow its index to be replayed either.
158    ///
159    /// Entries expire after
160    /// [`unack_ticket_timeout`](HoprUnacknowledgedTicketProcessorConfig::unack_ticket_timeout) and, once
161    /// [`max_tracked_ticket_indices`](HoprUnacknowledgedTicketProcessorConfig::max_tracked_ticket_indices)
162    /// is reached, the least-recently-used ones are evicted (see the LRU note in
163    /// `insert_unacknowledged_ticket`). The tracker is in-memory only and does not survive a restart.
164    seen_ticket_indices: moka::sync::Cache<(Address, u32, u64), ()>,
165    chain_api: Chain,
166    chain_key: ChainKeypair,
167    channels_dst: Hash,
168    cfg: HoprUnacknowledgedTicketProcessorConfig,
169}
170
171impl<Chain> HoprUnacknowledgedTicketProcessor<Chain> {
172    /// Creates a new instance of the HOPR unacknowledged ticket processor.
173    pub fn new(
174        chain_api: Chain,
175        chain_key: ChainKeypair,
176        channels_dst: Hash,
177        cfg: HoprUnacknowledgedTicketProcessorConfig,
178    ) -> Self {
179        #[cfg(all(feature = "telemetry", not(test)))]
180        {
181            lazy_static::initialize(&PER_PEER_ENABLED);
182            lazy_static::initialize(&UNACK_PEERS);
183            lazy_static::initialize(&UNACK_TICKETS);
184            lazy_static::initialize(&UNACK_INSERTIONS);
185            lazy_static::initialize(&UNACK_LOOKUPS);
186            lazy_static::initialize(&UNACK_LOOKUP_MISSES);
187            lazy_static::initialize(&UNACK_EVICTIONS);
188            lazy_static::initialize(&UNACK_PEER_EVICTIONS);
189            if *PER_PEER_ENABLED {
190                lazy_static::initialize(&UNACK_TICKETS_PER_PEER);
191            }
192        }
193
194        #[allow(unused_mut)]
195        let mut builder = moka::sync::Cache::builder()
196            .time_to_idle(cfg.unack_ticket_timeout)
197            .max_capacity(100_000);
198
199        #[cfg(all(feature = "telemetry", not(test)))]
200        {
201            builder = builder.eviction_listener(
202                |_, value: moka::sync::Cache<HalfKeyChallenge, UnacknowledgedTicket>, cause| {
203                    if !matches!(cause, moka::notification::RemovalCause::Replaced) {
204                        UNACK_PEERS.decrement(1.0);
205
206                        if matches!(
207                            cause,
208                            moka::notification::RemovalCause::Expired | moka::notification::RemovalCause::Size
209                        ) {
210                            UNACK_PEER_EVICTIONS.increment();
211                        }
212                    }
213                    // Explicitly invalidate all inner cache entries so their eviction
214                    // listeners fire (decrementing UNACK_TICKETS and per-peer metrics).
215                    // Without this, dropping the inner cache silently leaks those metrics.
216                    value.invalidate_all();
217                    // TODO: Improve the metrics in the module in general, because run_pending_tasks() is lengthy
218                    // See https://github.com/hoprnet/hoprnet/issues/8014
219                    // value.run_pending_tasks();
220                },
221            );
222        }
223
224        Self {
225            unacknowledged_tickets: builder.build(),
226            seen_ticket_indices: moka::sync::Cache::builder()
227                .time_to_live(cfg.unack_ticket_timeout)
228                .max_capacity(cfg.max_tracked_ticket_indices as u64)
229                .eviction_policy(moka::policy::EvictionPolicy::lru())
230                .build(),
231            chain_api,
232            chain_key,
233            channels_dst,
234            cfg,
235        }
236    }
237}
238
239#[async_trait::async_trait]
240impl<Chain> UnacknowledgedTicketProcessor for HoprUnacknowledgedTicketProcessor<Chain>
241where
242    Chain: ChainReadChannelOperations + Send + Sync,
243{
244    type Error = HoprProtocolError;
245
246    #[tracing::instrument(skip(self, next_hop, challenge, ticket), level = "trace", fields(next_hop = next_hop.to_peerid_str()))]
247    fn insert_unacknowledged_ticket(
248        &self,
249        next_hop: &OffchainPublicKey,
250        challenge: HalfKeyChallenge,
251        ticket: UnacknowledgedTicket,
252    ) -> Result<(), Self::Error> {
253        tracing::trace!(%ticket, "received unacknowledged ticket");
254
255        // Duplicate detection on (channel, epoch, index): a counterparty must not be able
256        // to have many tickets accepted on the same index, since only one of them would
257        // ever be redeemable on-chain.
258        // NOTE: entries are never removed upon acknowledgement, so an index whose ticket
259        // was losing or whose acknowledgement was withheld cannot be replayed either.
260        //
261        // The channel is identified by the signature-verified issuer (its destination is always this
262        // node), never by the ticket's counterparty field, so it cannot be varied by the sender even if
263        // a decoder skipped the counterparty check. It is the same channel `acknowledge_tickets`
264        // resolves via `channel_by_parties`, and the decoder has already validated the epoch against
265        // it (EpochMismatch).
266        let issuer = *ticket.ticket.verified_issuer();
267        let channel_epoch = ticket.verified_ticket().channel_epoch;
268        let index = ticket.verified_ticket().index;
269        let key = (issuer, channel_epoch, index);
270
271        // The claim is atomic: moka coalesces concurrent calls on the same absent key, so only
272        // one of them observes `is_fresh() == true`.
273        //
274        // The tracker uses LRU eviction because moka's default TinyLFU admission filter rejects new keys
275        // once the cache is at capacity. That would either make `is_fresh()` unreliable (failing open), or,
276        // if every insert were verified, refuse honest traffic on all channels. With LRU a fresh index is
277        // always admitted and, at capacity, the least-recently-used records are evicted: those indices
278        // become replayable again, but fresh indices are never refused.
279        if !self
280            .seen_ticket_indices
281            .entry_by_ref(&key)
282            .or_insert_with(|| ())
283            .is_fresh()
284        {
285            let channel_id = generate_channel_id(&issuer, self.chain_key.as_ref());
286            tracing::debug!(%channel_id, channel_epoch, index, "duplicate ticket index rejected");
287            return Err(HoprProtocolError::DuplicateTicketIndex(
288                channel_id,
289                channel_epoch,
290                index,
291            ));
292        }
293
294        self.unacknowledged_tickets
295            .get_with_by_ref(next_hop, || {
296                // LRU so that, at capacity, the oldest unacknowledged tickets are discarded (they are the
297                // least likely to still be acknowledged): moka's default TinyLFU would instead refuse the
298                // newest ones.
299                #[allow(unused_mut)]
300                let mut builder = moka::sync::Cache::builder()
301                    .time_to_live(self.cfg.unack_ticket_timeout)
302                    .max_capacity(self.cfg.max_unack_tickets as u64)
303                    .eviction_policy(moka::policy::EvictionPolicy::lru());
304
305                #[cfg(all(feature = "telemetry", not(test)))]
306                {
307                    UNACK_PEERS.increment(1.0);
308
309                    let next_hop = *next_hop;
310                    builder = builder.eviction_listener(move |_, _, cause| {
311                        let peer_id = PER_PEER_ENABLED.then(|| next_hop.to_peerid_str());
312                        UNACK_TICKETS.decrement(1.0);
313                        UNACK_TICKETS_PER_PEER.decrement(&[peer_id.as_deref().unwrap_or("redacted")], 1.0);
314
315                        // Only count Expired/Size removals as evictions (not Explicit or Replaced)
316                        if matches!(
317                            cause,
318                            moka::notification::RemovalCause::Expired | moka::notification::RemovalCause::Size
319                        ) {
320                            UNACK_EVICTIONS.increment();
321                        }
322                    });
323                }
324
325                builder.build()
326            })
327            .insert(challenge, ticket);
328
329        #[cfg(all(feature = "telemetry", not(test)))]
330        {
331            let peer_id = PER_PEER_ENABLED.then(|| next_hop.to_peerid_str());
332            UNACK_INSERTIONS.increment();
333            UNACK_TICKETS.increment(1.0);
334            UNACK_TICKETS_PER_PEER.increment(&[peer_id.as_deref().unwrap_or("redacted")], 1.0);
335        }
336
337        Ok(())
338    }
339
340    #[inline]
341    fn is_duplicate_ticket_index_error(error: &Self::Error) -> bool {
342        error.is_duplicate_ticket_index()
343    }
344
345    #[tracing::instrument(skip_all, level = "trace", fields(peer = peer.to_peerid_str()))]
346    fn acknowledge_tickets(
347        &self,
348        peer: OffchainPublicKey,
349        acks: Vec<Acknowledgement>,
350    ) -> Result<Vec<ResolvedAcknowledgement>, TicketAcknowledgementError<Self::Error>> {
351        let Some((awaiting_ack_from_peer, half_keys_challenges)) =
352            hopr_protocol_pix::ack_verify::verify_expected_acknowledgements(
353                peer,
354                acks,
355                &self.unacknowledged_tickets,
356                self.cfg.use_batch_verification,
357            )
358        else {
359            return Err(TicketAcknowledgementError::UnexpectedAcknowledgement);
360        };
361
362        // Find all the tickets that we're awaiting acknowledgement for
363        let mut unack_tickets = Vec::with_capacity(half_keys_challenges.len());
364        for (half_key, challenge) in half_keys_challenges {
365            #[cfg(all(feature = "telemetry", not(test)))]
366            UNACK_LOOKUPS.increment();
367
368            let Some(unack_ticket) = awaiting_ack_from_peer.remove(&challenge) else {
369                #[cfg(all(feature = "telemetry", not(test)))]
370                UNACK_LOOKUP_MISSES.increment();
371                tracing::trace!(%challenge, "received acknowledgement for unknown ticket");
372                continue;
373            };
374
375            let issuer_channel = match self
376                .chain_api
377                .channel_by_parties(unack_ticket.ticket.verified_issuer(), self.chain_key.as_ref())
378            {
379                Ok(Some(channel)) => {
380                    if channel.channel_epoch != unack_ticket.verified_ticket().channel_epoch {
381                        tracing::error!(%unack_ticket, "received acknowledgement for ticket issued in a different epoch");
382                        continue;
383                    }
384                    channel
385                }
386                Ok(None) => {
387                    tracing::error!(%unack_ticket, "received acknowledgement for ticket issued for unknown channel");
388                    continue;
389                }
390                Err(error) => {
391                    tracing::error!(%error, %unack_ticket, "failed to resolve channel for unacknowledged ticket");
392                    continue;
393                }
394            };
395
396            unack_tickets.push((issuer_channel, half_key, unack_ticket));
397        }
398
399        #[cfg(feature = "rayon")]
400        let iter = unack_tickets.into_par_iter();
401
402        #[cfg(not(feature = "rayon"))]
403        let iter = unack_tickets.into_iter();
404
405        Ok(iter
406            .filter_map(|(channel, half_key, unack_ticket)| {
407                // This explicitly checks whether the acknowledgement
408                // solves the challenge on the ticket.
409                // It must be done before we check that the ticket is winning,
410                // which is a lengthy operation and should not be done for
411                // bogus unacknowledged tickets
412                let Ok(ack_ticket) = unack_ticket.acknowledge(&half_key) else {
413                    tracing::error!(%unack_ticket, "failed to acknowledge ticket");
414                    return None;
415                };
416
417                // This operation checks if the ticket is winning, and if it is, it
418                // turns it into a redeemable ticket.
419                match ack_ticket.into_redeemable(&self.chain_key, &self.channels_dst) {
420                    Ok(redeemable) => {
421                        tracing::trace!(%channel, "found winning ticket");
422                        Some(ResolvedAcknowledgement::RelayingWin(Box::new(redeemable)))
423                    }
424                    Err(CoreTypesError::TicketNotWinning) => {
425                        tracing::trace!(%channel, "found losing ticket");
426                        Some(ResolvedAcknowledgement::RelayingLoss(*channel.get_id()))
427                    }
428                    Err(error) => {
429                        tracing::error!(%error, %channel, "error when acknowledging ticket");
430                        Some(ResolvedAcknowledgement::RelayingLoss(*channel.get_id()))
431                    }
432                }
433            })
434            .collect())
435    }
436}
437
438#[cfg(test)]
439mod tests {
440    use anyhow::Context;
441    use hopr_api::types::crypto_random::Randomizable;
442
443    use super::*;
444    use crate::utils::*;
445
446    // Channel id of the channel the test tickets are issued on: the utils.rs channels go
447    // `PEERS[i] -> PEERS[(i+1)%5]` with epoch 1, and the test tickets are signed by `PEERS[0]`
448    // with counterparty `PEERS[1]`, i.e. they travel on the `PEERS[0] -> PEERS[1]` channel.
449    // The processor under test is node 1 (`PEERS[1]`), the destination of that channel.
450    lazy_static::lazy_static! {
451        static ref TEST_CHANNEL_ID: ChannelId =
452            generate_channel_id(&PEERS[0].0.public().to_address(), &PEERS[1].0.public().to_address());
453    }
454
455    /// Builds an unacknowledged ticket on the `PEERS[0] -> PEERS[1]` channel with the given
456    /// `index` and `channel_epoch`, solved by the given `ack_share`.
457    fn build_unack_ticket(index: u64, channel_epoch: u32, ack_share: &HalfKey) -> anyhow::Result<UnacknowledgedTicket> {
458        build_unack_ticket_from(&PEERS[0].0, &PEERS[1].0, index, channel_epoch, ack_share)
459    }
460
461    /// Same as [`build_unack_ticket`], but signed by `issuer` with the ticket's counterparty field set to
462    /// `counterparty`.
463    fn build_unack_ticket_from(
464        issuer: &ChainKeypair,
465        counterparty: &ChainKeypair,
466        index: u64,
467        channel_epoch: u32,
468        ack_share: &HalfKey,
469    ) -> anyhow::Result<UnacknowledgedTicket> {
470        let own_share = HalfKey::random();
471        let challenge = Challenge::from_own_share_and_half_key(&own_share.to_challenge()?, ack_share)?;
472
473        Ok(TicketBuilder::default()
474            .counterparty(counterparty)
475            .index(index)
476            .channel_epoch(channel_epoch)
477            .amount(10_u32)
478            .challenge(challenge)
479            .build_signed(issuer, &Hash::default())?
480            .into_unacknowledged(own_share))
481    }
482
483    /// Inserts a fresh ticket with the given `index` on the `PEERS[0] -> PEERS[1]` channel and epoch 1.
484    fn insert_index<Chain>(
485        ticket_processor: &HoprUnacknowledgedTicketProcessor<Chain>,
486        index: u64,
487    ) -> anyhow::Result<Result<(), HoprProtocolError>>
488    where
489        Chain: ChainReadChannelOperations + Send + Sync,
490    {
491        let ack_share = HalfKey::random();
492        let ticket = build_unack_ticket(index, 1, &ack_share)?;
493        Ok(ticket_processor.insert_unacknowledged_ticket(PEERS[2].1.public(), ack_share.to_challenge()?, ticket))
494    }
495
496    #[parameterized::parameterized(batch = { true, false })]
497    #[parameterized_macro(tokio::test)]
498    async fn ticket_processor_should_acknowledge_previously_inserted_tickets(batch: bool) -> anyhow::Result<()> {
499        let blokli_client = create_blokli_client()?;
500
501        let node = create_node(1, &blokli_client).await?;
502
503        let ticket_processor = HoprUnacknowledgedTicketProcessor::new(
504            node.chain_api.clone(),
505            node.chain_key.clone(),
506            Hash::default(),
507            HoprUnacknowledgedTicketProcessorConfig {
508                use_batch_verification: batch,
509                ..HoprUnacknowledgedTicketProcessorConfig::default()
510            },
511        );
512
513        const NUM_TICKETS: usize = 5;
514
515        let mut acks = Vec::with_capacity(5);
516        for index in 0..NUM_TICKETS {
517            let own_share = HalfKey::random();
518            let ack_share = HalfKey::random();
519            let challenge = Challenge::from_own_share_and_half_key(&own_share.to_challenge()?, &ack_share)?;
520
521            let unack_ticket = TicketBuilder::default()
522                .counterparty(&PEERS[1].0)
523                .index(index as u64)
524                .channel_epoch(1)
525                .amount(10_u32)
526                .challenge(challenge)
527                .build_signed(&PEERS[0].0, &Hash::default())?
528                .into_unacknowledged(own_share);
529
530            ticket_processor.insert_unacknowledged_ticket(
531                PEERS[2].1.public(),
532                ack_share.to_challenge()?,
533                unack_ticket,
534            )?;
535
536            acks.push(VerifiedAcknowledgement::new(ack_share, &PEERS[2].1).leak());
537        }
538
539        let resolutions = ticket_processor.acknowledge_tickets(*PEERS[2].1.public(), acks)?;
540        assert_eq!(NUM_TICKETS, resolutions.len());
541        assert!(
542            resolutions
543                .iter()
544                .all(|res| matches!(res, ResolvedAcknowledgement::RelayingWin(_)))
545        );
546
547        Ok(())
548    }
549
550    #[tokio::test]
551    async fn ticket_processor_should_reject_acknowledgements_from_unexpected_sender() -> anyhow::Result<()> {
552        let blokli_client = create_blokli_client()?;
553
554        let node = create_node(1, &blokli_client).await?;
555
556        let ticket_processor = HoprUnacknowledgedTicketProcessor::new(
557            node.chain_api.clone(),
558            node.chain_key.clone(),
559            Hash::default(),
560            HoprUnacknowledgedTicketProcessorConfig::default(),
561        );
562
563        const NUM_ACKS: usize = 5;
564
565        let mut acks = Vec::with_capacity(5);
566        for _ in 0..NUM_ACKS {
567            let ack_share = HalfKey::random();
568            acks.push(VerifiedAcknowledgement::new(ack_share, &PEERS[2].1).leak());
569        }
570
571        assert!(matches!(
572            ticket_processor.acknowledge_tickets(*PEERS[2].1.public(), acks),
573            Err(TicketAcknowledgementError::UnexpectedAcknowledgement)
574        ));
575
576        Ok(())
577    }
578
579    #[tokio::test]
580    async fn ticket_processor_should_ignore_bogus_acknowledgements() -> anyhow::Result<()> {
581        let blokli_client = create_blokli_client()?;
582        let node = create_node(1, &blokli_client).await?;
583        let ticket_processor = HoprUnacknowledgedTicketProcessor::new(
584            node.chain_api.clone(),
585            node.chain_key.clone(),
586            Hash::default(),
587            HoprUnacknowledgedTicketProcessorConfig::default(),
588        );
589
590        let own_share = HalfKey::random();
591        let ack_share = HalfKey::random();
592        let challenge = Challenge::from_own_share_and_half_key(&own_share.to_challenge()?, &ack_share)?;
593
594        let unack_ticket = TicketBuilder::default()
595            .counterparty(&PEERS[1].0)
596            .index(0)
597            .channel_epoch(1)
598            .amount(10_u32)
599            .challenge(challenge)
600            .build_signed(&PEERS[0].0, &Hash::default())?
601            .into_unacknowledged(own_share);
602
603        ticket_processor.insert_unacknowledged_ticket(PEERS[2].1.public(), ack_share.to_challenge()?, unack_ticket)?;
604
605        // Create an acknowledgement from a DIFFERENT peer, but we'll try to pass it as if it's from PEERS[2]
606        let bogus_ack_share = HalfKey::random();
607        let bogus_ack = VerifiedAcknowledgement::new(bogus_ack_share, &PEERS[1].1).leak();
608
609        let resolutions = ticket_processor.acknowledge_tickets(*PEERS[2].1.public(), vec![bogus_ack])?;
610        // Should ignore because signature is invalid (it's from PEERS[1] but we're telling the processor it's from
611        // PEERS[2])
612        assert_eq!(0, resolutions.len());
613
614        Ok(())
615    }
616
617    #[tokio::test]
618    async fn ticket_processor_should_ignore_unknown_challenges() -> anyhow::Result<()> {
619        let blokli_client = create_blokli_client()?;
620        let node = create_node(1, &blokli_client).await?;
621        let ticket_processor = HoprUnacknowledgedTicketProcessor::new(
622            node.chain_api.clone(),
623            node.chain_key.clone(),
624            Hash::default(),
625            HoprUnacknowledgedTicketProcessorConfig::default(),
626        );
627
628        // We insert ONE ticket
629        let own_share = HalfKey::random();
630        let ack_share = HalfKey::random();
631        let challenge = Challenge::from_own_share_and_half_key(&own_share.to_challenge()?, &ack_share)?;
632
633        let unack_ticket = TicketBuilder::default()
634            .counterparty(&PEERS[1].0)
635            .index(0)
636            .channel_epoch(1)
637            .amount(10_u32)
638            .challenge(challenge)
639            .build_signed(&PEERS[0].0, &Hash::default())?
640            .into_unacknowledged(own_share);
641
642        ticket_processor.insert_unacknowledged_ticket(PEERS[2].1.public(), ack_share.to_challenge()?, unack_ticket)?;
643
644        // Now we send TWO acks: one for the ticket we inserted, and one random/unknown
645        let unknown_ack_share = HalfKey::random();
646        let acks = vec![
647            VerifiedAcknowledgement::new(ack_share, &PEERS[2].1).leak(),
648            VerifiedAcknowledgement::new(unknown_ack_share, &PEERS[2].1).leak(),
649        ];
650
651        let resolutions = ticket_processor.acknowledge_tickets(*PEERS[2].1.public(), acks)?;
652        // Should only resolve the one we knew about
653        assert_eq!(1, resolutions.len());
654
655        Ok(())
656    }
657
658    #[tokio::test]
659    async fn ticket_processor_should_ignore_epoch_mismatch() -> anyhow::Result<()> {
660        let blokli_client = create_blokli_client()?;
661        let node = create_node(1, &blokli_client).await?;
662        let ticket_processor = HoprUnacknowledgedTicketProcessor::new(
663            node.chain_api.clone(),
664            node.chain_key.clone(),
665            Hash::default(),
666            HoprUnacknowledgedTicketProcessorConfig::default(),
667        );
668
669        let own_share = HalfKey::random();
670        let ack_share = HalfKey::random();
671        let challenge = Challenge::from_own_share_and_half_key(&own_share.to_challenge()?, &ack_share)?;
672
673        // Channel in utils.rs has epoch 1. We'll create a ticket with epoch 2.
674        let unack_ticket = TicketBuilder::default()
675            .counterparty(&PEERS[1].0)
676            .index(0)
677            .channel_epoch(2) // Mismatch!
678            .amount(10_u32)
679            .challenge(challenge)
680            .build_signed(&PEERS[0].0, &Hash::default())?
681            .into_unacknowledged(own_share);
682
683        ticket_processor.insert_unacknowledged_ticket(PEERS[2].1.public(), ack_share.to_challenge()?, unack_ticket)?;
684
685        let ack = VerifiedAcknowledgement::new(ack_share, &PEERS[2].1).leak();
686        let resolutions = ticket_processor.acknowledge_tickets(*PEERS[2].1.public(), vec![ack])?;
687        assert_eq!(0, resolutions.len());
688
689        Ok(())
690    }
691
692    #[tokio::test]
693    async fn ticket_processor_should_ignore_missing_channel() -> anyhow::Result<()> {
694        let blokli_client = create_blokli_client()?;
695        let node = create_node(1, &blokli_client).await?;
696        let ticket_processor = HoprUnacknowledgedTicketProcessor::new(
697            node.chain_api.clone(),
698            node.chain_key.clone(),
699            Hash::default(),
700            HoprUnacknowledgedTicketProcessorConfig::default(),
701        );
702
703        let own_share = HalfKey::random();
704        let ack_share = HalfKey::random();
705        let challenge = Challenge::from_own_share_and_half_key(&own_share.to_challenge()?, &ack_share)?;
706
707        let unknown_issuer = ChainKeypair::random();
708
709        let unack_ticket = TicketBuilder::default()
710            .counterparty(&node.chain_key)
711            .index(0)
712            .channel_epoch(1)
713            .amount(10_u32)
714            .challenge(challenge)
715            .build_signed(&unknown_issuer, &Hash::default())?
716            .into_unacknowledged(own_share);
717
718        ticket_processor.insert_unacknowledged_ticket(PEERS[2].1.public(), ack_share.to_challenge()?, unack_ticket)?;
719
720        let ack = VerifiedAcknowledgement::new(ack_share, &PEERS[2].1).leak();
721        let resolutions = ticket_processor.acknowledge_tickets(*PEERS[2].1.public(), vec![ack])?;
722        assert_eq!(
723            0,
724            resolutions.len(),
725            "Expected 0 resolutions for missing channel, got: {:?}",
726            resolutions
727        );
728
729        Ok(())
730    }
731
732    #[tokio::test]
733    async fn ticket_processor_should_handle_losing_tickets() -> anyhow::Result<()> {
734        let blokli_client = create_blokli_client()?;
735        let node = create_node(1, &blokli_client).await?;
736        let ticket_processor = HoprUnacknowledgedTicketProcessor::new(
737            node.chain_api.clone(),
738            node.chain_key.clone(),
739            Hash::default(),
740            HoprUnacknowledgedTicketProcessorConfig::default(),
741        );
742
743        let own_share = HalfKey::random();
744        let ack_share = HalfKey::random();
745        let challenge = Challenge::from_own_share_and_half_key(&own_share.to_challenge()?, &ack_share)?;
746
747        let unack_ticket = TicketBuilder::default()
748            .counterparty(&PEERS[1].0)
749            .index(0)
750            .win_prob(WinningProbability::NEVER)
751            .channel_epoch(1)
752            .amount(0_u32)
753            .challenge(challenge)
754            .build_signed(&PEERS[0].0, &Hash::default())?
755            .into_unacknowledged(own_share);
756
757        ticket_processor.insert_unacknowledged_ticket(PEERS[2].1.public(), ack_share.to_challenge()?, unack_ticket)?;
758
759        let ack = VerifiedAcknowledgement::new(ack_share, &PEERS[2].1).leak();
760        let resolutions = ticket_processor.acknowledge_tickets(*PEERS[2].1.public(), vec![ack])?;
761        assert_eq!(1, resolutions.len());
762        assert!(
763            matches!(resolutions[0], ResolvedAcknowledgement::RelayingLoss(_)),
764            "Expected RelayingLoss for 0-amount ticket, got: {:?}",
765            resolutions[0]
766        );
767
768        Ok(())
769    }
770
771    #[tokio::test]
772    async fn ticket_processor_should_reject_duplicate_ticket_index_on_same_channel_and_epoch() -> anyhow::Result<()> {
773        let blokli_client = create_blokli_client()?;
774        let node = create_node(1, &blokli_client).await?;
775        let ticket_processor = HoprUnacknowledgedTicketProcessor::new(
776            node.chain_api.clone(),
777            node.chain_key.clone(),
778            Hash::default(),
779            HoprUnacknowledgedTicketProcessorConfig::default(),
780        );
781
782        let first_ack_share = HalfKey::random();
783        let first_ticket = build_unack_ticket(5, 1, &first_ack_share).context("should build first ticket")?;
784        ticket_processor.insert_unacknowledged_ticket(
785            PEERS[2].1.public(),
786            first_ack_share.to_challenge()?,
787            first_ticket,
788        )?;
789
790        // Same index on the same channel and epoch, but a different challenge: must be rejected
791        let second_ack_share = HalfKey::random();
792        let second_ticket = build_unack_ticket(5, 1, &second_ack_share).context("should build second ticket")?;
793        let result = ticket_processor.insert_unacknowledged_ticket(
794            PEERS[2].1.public(),
795            second_ack_share.to_challenge()?,
796            second_ticket,
797        );
798
799        assert!(
800            matches!(
801                result,
802                Err(HoprProtocolError::DuplicateTicketIndex(channel_id, epoch, index))
803                    if channel_id == *TEST_CHANNEL_ID && epoch == 1 && index == 5
804            ),
805            "expected DuplicateTicketIndex, got: {:?}",
806            result
807        );
808
809        Ok(())
810    }
811
812    #[tokio::test]
813    async fn ticket_processor_should_accept_reordered_but_distinct_ticket_indices() -> anyhow::Result<()> {
814        let blokli_client = create_blokli_client()?;
815        let node = create_node(1, &blokli_client).await?;
816        let ticket_processor = HoprUnacknowledgedTicketProcessor::new(
817            node.chain_api.clone(),
818            node.chain_key.clone(),
819            Hash::default(),
820            HoprUnacknowledgedTicketProcessorConfig::default(),
821        );
822
823        // The mixer deliberately reorders packets, so indices may arrive out of order;
824        // only exact duplicates may be rejected.
825        for index in [5u64, 3, 7, 4] {
826            let ack_share = HalfKey::random();
827            let ticket = build_unack_ticket(index, 1, &ack_share)
828                .with_context(|| format!("should build ticket with index {index}"))?;
829            ticket_processor
830                .insert_unacknowledged_ticket(PEERS[2].1.public(), ack_share.to_challenge()?, ticket)
831                .with_context(|| format!("ticket with index {index} must be accepted"))?;
832        }
833
834        Ok(())
835    }
836
837    #[tokio::test]
838    async fn ticket_processor_should_accept_same_ticket_index_in_different_epoch() -> anyhow::Result<()> {
839        let blokli_client = create_blokli_client()?;
840        let node = create_node(1, &blokli_client).await?;
841        let ticket_processor = HoprUnacknowledgedTicketProcessor::new(
842            node.chain_api.clone(),
843            node.chain_key.clone(),
844            Hash::default(),
845            HoprUnacknowledgedTicketProcessorConfig::default(),
846        );
847
848        for epoch in [1u32, 2] {
849            let ack_share = HalfKey::random();
850            let ticket = build_unack_ticket(5, epoch, &ack_share)
851                .with_context(|| format!("should build ticket with epoch {epoch}"))?;
852            ticket_processor
853                .insert_unacknowledged_ticket(PEERS[2].1.public(), ack_share.to_challenge()?, ticket)
854                .with_context(|| format!("ticket with epoch {epoch} must be accepted"))?;
855        }
856
857        Ok(())
858    }
859
860    /// Documents and pins the tracker's remaining, *accepted* residual: replay protection expires
861    /// with `unack_ticket_timeout`, independently of on-chain redemption.
862    ///
863    /// An index that was accepted but never redeemed becomes replayable once its record expires,
864    /// so a counterparty that withholds acknowledgements (leaving the on-chain channel index
865    /// unchanged) can recycle a batch of indices once per window. This is materially weaker than
866    /// the reported attack — each replay needs a fresh window rather than a fresh index, and the
867    /// amplification is not unbounded — but it is not nothing, and it is why this timeout is a
868    /// replay-protection knob and not merely a cache knob.
869    ///
870    /// Closing it properly requires retiring indices on redemption rather than on a timer, which
871    /// needs state outside this in-memory tracker. If that lands, this test should be inverted
872    /// rather than deleted, so the guarantee is asserted in whichever direction is intended.
873    #[tokio::test]
874    async fn ticket_processor_replay_is_possible_only_after_the_tracker_ttl_expires() -> anyhow::Result<()> {
875        let blokli_client = create_blokli_client()?;
876        let node = create_node(1, &blokli_client).await?;
877        let ticket_processor = HoprUnacknowledgedTicketProcessor::new(
878            node.chain_api.clone(),
879            node.chain_key.clone(),
880            Hash::default(),
881            HoprUnacknowledgedTicketProcessorConfig {
882                // Below the production minimum of 10s, but `new` does not run the validator and the
883                // test only needs to observe the expiry, not the production default.
884                unack_ticket_timeout: std::time::Duration::from_millis(300),
885                ..HoprUnacknowledgedTicketProcessorConfig::default()
886            },
887        );
888
889        let insert = |index: u64| -> anyhow::Result<Result<(), HoprProtocolError>> {
890            let ack_share = HalfKey::random();
891            let ticket = build_unack_ticket(index, 1, &ack_share)?;
892            Ok(ticket_processor.insert_unacknowledged_ticket(PEERS[2].1.public(), ack_share.to_challenge()?, ticket))
893        };
894
895        insert(42)
896            .context("first insert must be attempted")?
897            .context("a fresh index must be accepted")?;
898        assert!(
899            insert(42).context("immediate replay must be attempted")?.is_err(),
900            "an index must not be replayable while its record is live"
901        );
902
903        tokio::time::sleep(std::time::Duration::from_millis(600)).await;
904        ticket_processor.seen_ticket_indices.run_pending_tasks();
905
906        assert!(
907            insert(42).context("post-expiry replay must be attempted")?.is_ok(),
908            "if this now fails the tracker retains indices beyond its TTL, which is strictly stronger than documented \
909             and should update the docs on unack_ticket_timeout"
910        );
911
912        Ok(())
913    }
914
915    #[tokio::test]
916    async fn ticket_processor_should_accept_same_ticket_index_on_different_channel() -> anyhow::Result<()> {
917        let blokli_client = create_blokli_client()?;
918        let node = create_node(1, &blokli_client).await?;
919        let ticket_processor = HoprUnacknowledgedTicketProcessor::new(
920            node.chain_api.clone(),
921            node.chain_key.clone(),
922            Hash::default(),
923            HoprUnacknowledgedTicketProcessorConfig::default(),
924        );
925
926        // The tracker key is the issuer -> this node channel (this node is `PEERS[1]`), so the same
927        // index from a different issuer is on a different channel and must be accepted.
928        for issuer in [&PEERS[0].0, &PEERS[2].0] {
929            let ack_share = HalfKey::random();
930            let ticket =
931                build_unack_ticket_from(issuer, &PEERS[1].0, 5, 1, &ack_share).context("should build ticket")?;
932            ticket_processor
933                .insert_unacknowledged_ticket(PEERS[2].1.public(), ack_share.to_challenge()?, ticket)
934                .with_context(|| format!("ticket from issuer {} must be accepted", issuer.public().to_address()))?;
935        }
936
937        Ok(())
938    }
939
940    /// The tracker key must not depend on the ticket's counterparty field, which the issuer chooses
941    /// freely: were it part of the key (as it is of `Ticket::channel_id`), one issuer could mint an
942    /// unlimited number of distinct keys for the same index and replay it at will.
943    #[tokio::test]
944    async fn ticket_processor_should_reject_same_ticket_index_with_different_counterparty() -> anyhow::Result<()> {
945        let blokli_client = create_blokli_client()?;
946        let node = create_node(1, &blokli_client).await?;
947        let ticket_processor = HoprUnacknowledgedTicketProcessor::new(
948            node.chain_api.clone(),
949            node.chain_key.clone(),
950            Hash::default(),
951            HoprUnacknowledgedTicketProcessorConfig::default(),
952        );
953
954        let first_ack_share = HalfKey::random();
955        let first_ticket = build_unack_ticket_from(&PEERS[0].0, &PEERS[1].0, 5, 1, &first_ack_share)
956            .context("should build first ticket")?;
957        ticket_processor.insert_unacknowledged_ticket(
958            PEERS[2].1.public(),
959            first_ack_share.to_challenge()?,
960            first_ticket,
961        )?;
962
963        // Same issuer, epoch and index, but the counterparty field differs, so the ticket's own channel
964        // id differs as well.
965        let second_ack_share = HalfKey::random();
966        let second_ticket = build_unack_ticket_from(&PEERS[0].0, &PEERS[3].0, 5, 1, &second_ack_share)
967            .context("should build second ticket")?;
968        assert_ne!(
969            first_ticket.ticket.channel_id(),
970            second_ticket.ticket.channel_id(),
971            "sanity: the tickets must differ in their own channel id"
972        );
973
974        let result = ticket_processor.insert_unacknowledged_ticket(
975            PEERS[2].1.public(),
976            second_ack_share.to_challenge()?,
977            second_ticket,
978        );
979        assert!(
980            matches!(
981                result,
982                Err(HoprProtocolError::DuplicateTicketIndex(channel_id, epoch, index))
983                    if channel_id == *TEST_CHANNEL_ID && epoch == 1 && index == 5
984            ),
985            "expected DuplicateTicketIndex, got: {:?}",
986            result
987        );
988
989        Ok(())
990    }
991
992    #[tokio::test]
993    async fn ticket_processor_should_still_reject_index_replayed_after_acknowledgement() -> anyhow::Result<()> {
994        let blokli_client = create_blokli_client()?;
995        let node = create_node(1, &blokli_client).await?;
996        let ticket_processor = HoprUnacknowledgedTicketProcessor::new(
997            node.chain_api.clone(),
998            node.chain_key.clone(),
999            Hash::default(),
1000            HoprUnacknowledgedTicketProcessorConfig::default(),
1001        );
1002
1003        let ack_share = HalfKey::random();
1004        let ticket = build_unack_ticket(5, 1, &ack_share).context("should build first ticket")?;
1005        ticket_processor.insert_unacknowledged_ticket(PEERS[2].1.public(), ack_share.to_challenge()?, ticket)?;
1006
1007        // The index is NOT removed from the tracker upon acknowledgement: a counterparty could
1008        // otherwise replay any index whose ticket was losing or whose acknowledgement it withheld.
1009        let ack = VerifiedAcknowledgement::new(ack_share, &PEERS[2].1).leak();
1010        let resolutions = ticket_processor.acknowledge_tickets(*PEERS[2].1.public(), vec![ack])?;
1011        assert_eq!(1, resolutions.len());
1012
1013        let replay_ack_share = HalfKey::random();
1014        let replay_ticket = build_unack_ticket(5, 1, &replay_ack_share).context("should build replayed ticket")?;
1015        let result = ticket_processor.insert_unacknowledged_ticket(
1016            PEERS[2].1.public(),
1017            replay_ack_share.to_challenge()?,
1018            replay_ticket,
1019        );
1020        assert!(
1021            matches!(result, Err(HoprProtocolError::DuplicateTicketIndex(..))),
1022            "expected DuplicateTicketIndex after acknowledgement, got: {:?}",
1023            result
1024        );
1025
1026        Ok(())
1027    }
1028
1029    #[tokio::test(flavor = "multi_thread", worker_threads = 8)]
1030    async fn ticket_processor_should_accept_duplicate_index_only_once_concurrently() -> anyhow::Result<()> {
1031        let blokli_client = create_blokli_client()?;
1032        let node = create_node(1, &blokli_client).await?;
1033        let ticket_processor = std::sync::Arc::new(HoprUnacknowledgedTicketProcessor::new(
1034            node.chain_api.clone(),
1035            node.chain_key.clone(),
1036            Hash::default(),
1037            HoprUnacknowledgedTicketProcessorConfig::default(),
1038        ));
1039
1040        const NUM_CONCURRENT: usize = 8;
1041
1042        // Hold every task on the barrier so all inserts race on the SAME absent key at
1043        // once, instead of running to completion sequentially on one worker.
1044        let barrier = std::sync::Arc::new(tokio::sync::Barrier::new(NUM_CONCURRENT));
1045
1046        let handles = (0..NUM_CONCURRENT)
1047            .map(|_| {
1048                let ticket_processor = ticket_processor.clone();
1049                let barrier = barrier.clone();
1050                tokio::task::spawn(async move {
1051                    let inner = async {
1052                        let ack_share = HalfKey::random();
1053                        let ticket = build_unack_ticket(5, 1, &ack_share).context("should build ticket")?;
1054                        let challenge = ack_share.to_challenge().context("should derive challenge")?;
1055                        barrier.wait().await;
1056                        ticket_processor
1057                            .insert_unacknowledged_ticket(PEERS[2].1.public(), challenge, ticket)
1058                            .map_err(anyhow::Error::from)
1059                    }
1060                    .await;
1061                    inner.map_err(|error| anyhow::anyhow!("concurrent insert failed: {error}"))
1062                })
1063            })
1064            .collect::<Vec<_>>();
1065
1066        let mut results = Vec::with_capacity(NUM_CONCURRENT);
1067        for handle in handles {
1068            results.push(handle.await.context("concurrent insert task should not panic")?);
1069        }
1070
1071        let accepted = results.iter().filter(|r| r.is_ok()).count();
1072        assert_eq!(
1073            1, accepted,
1074            "exactly one concurrent insert of the same index must succeed, got: {:?}",
1075            results
1076        );
1077
1078        Ok(())
1079    }
1080
1081    /// Capacity used by the LRU tests below. It equals the minimum accepted by the config validator.
1082    const SMALL_TRACKER_CAPACITY: usize = 100;
1083
1084    /// Once the tracker is full, every further fresh index must still be accepted: the tracker evicts
1085    /// its least-recently-used records instead of refusing newcomers, so honest traffic (on any
1086    /// channel) is never dropped because the tracker is saturated.
1087    ///
1088    /// With moka's default TinyLFU policy plus a retention probe after each insert (an earlier design of
1089    /// this tracker), this test fails: TinyLFU's admission filter rejects new keys at capacity, so the
1090    /// probe refused fresh indices. `ticket_processor_should_reject_recent_ticket_index_when_the_tracker_is_full`
1091    /// is the one that fails if the LRU policy alone is reverted.
1092    #[tokio::test]
1093    async fn ticket_processor_should_accept_every_fresh_ticket_index_once_the_tracker_is_full() -> anyhow::Result<()> {
1094        let blokli_client = create_blokli_client()?;
1095        let node = create_node(1, &blokli_client).await?;
1096        let ticket_processor = HoprUnacknowledgedTicketProcessor::new(
1097            node.chain_api.clone(),
1098            node.chain_key.clone(),
1099            Hash::default(),
1100            HoprUnacknowledgedTicketProcessorConfig {
1101                max_tracked_ticket_indices: SMALL_TRACKER_CAPACITY,
1102                ..HoprUnacknowledgedTicketProcessorConfig::default()
1103            },
1104        );
1105
1106        for index in 0..(5 * SMALL_TRACKER_CAPACITY) as u64 {
1107            insert_index(&ticket_processor, index)
1108                .with_context(|| format!("should build ticket with index {index}"))?
1109                .with_context(|| format!("fresh index {index} must be accepted, even at capacity"))?;
1110        }
1111
1112        ticket_processor.seen_ticket_indices.run_pending_tasks();
1113        assert!(
1114            ticket_processor.seen_ticket_indices.entry_count() <= SMALL_TRACKER_CAPACITY as u64,
1115            "the tracker must stay bounded by its capacity"
1116        );
1117
1118        Ok(())
1119    }
1120
1121    /// A recently accepted index must still be rejected once the tracker is full: LRU eviction only
1122    /// ever drops the oldest records.
1123    #[tokio::test]
1124    async fn ticket_processor_should_reject_recent_ticket_index_when_the_tracker_is_full() -> anyhow::Result<()> {
1125        let blokli_client = create_blokli_client()?;
1126        let node = create_node(1, &blokli_client).await?;
1127        let ticket_processor = HoprUnacknowledgedTicketProcessor::new(
1128            node.chain_api.clone(),
1129            node.chain_key.clone(),
1130            Hash::default(),
1131            HoprUnacknowledgedTicketProcessorConfig {
1132                max_tracked_ticket_indices: SMALL_TRACKER_CAPACITY,
1133                ..HoprUnacknowledgedTicketProcessorConfig::default()
1134            },
1135        );
1136
1137        let last_index = (5 * SMALL_TRACKER_CAPACITY) as u64 - 1;
1138        for index in 0..=last_index {
1139            insert_index(&ticket_processor, index)
1140                .with_context(|| format!("should build ticket with index {index}"))?
1141                .with_context(|| format!("fresh index {index} must be accepted"))?;
1142        }
1143        ticket_processor.seen_ticket_indices.run_pending_tasks();
1144
1145        let result = insert_index(&ticket_processor, last_index).context("should build replayed ticket")?;
1146        assert!(
1147            matches!(
1148                result,
1149                Err(HoprProtocolError::DuplicateTicketIndex(channel_id, 1, index))
1150                    if channel_id == *TEST_CHANNEL_ID && index == last_index
1151            ),
1152            "a recently accepted index must be rejected at capacity, got: {:?}",
1153            result
1154        );
1155
1156        Ok(())
1157    }
1158
1159    /// Documents and pins the second *accepted* residual of the tracker: replay protection is bounded
1160    /// by `max_tracked_ticket_indices` as well as by `unack_ticket_timeout`.
1161    ///
1162    /// Once the tracker is full, its least-recently-used records are evicted, so the oldest index
1163    /// becomes replayable after enough fresh indices were accepted, even within its TTL. This is the
1164    /// price of never refusing a fresh index; the capacity should be sized for the number of tickets
1165    /// accepted per `unack_ticket_timeout` window (see the docs on `max_tracked_ticket_indices`).
1166    ///
1167    /// If the tracker ever gains stronger retention, this test should be inverted rather than deleted,
1168    /// so the guarantee is asserted in whichever direction is intended.
1169    #[tokio::test]
1170    async fn ticket_processor_replay_is_possible_once_the_tracker_evicts_the_oldest_index() -> anyhow::Result<()> {
1171        let blokli_client = create_blokli_client()?;
1172        let node = create_node(1, &blokli_client).await?;
1173        let ticket_processor = HoprUnacknowledgedTicketProcessor::new(
1174            node.chain_api.clone(),
1175            node.chain_key.clone(),
1176            Hash::default(),
1177            HoprUnacknowledgedTicketProcessorConfig {
1178                max_tracked_ticket_indices: SMALL_TRACKER_CAPACITY,
1179                ..HoprUnacknowledgedTicketProcessorConfig::default()
1180            },
1181        );
1182
1183        let oldest_index = 0u64;
1184        insert_index(&ticket_processor, oldest_index)
1185            .context("first insert must be attempted")?
1186            .context("a fresh index must be accepted")?;
1187        assert!(
1188            insert_index(&ticket_processor, oldest_index)
1189                .context("immediate replay must be attempted")?
1190                .is_err(),
1191            "an index must not be replayable while its record is retained"
1192        );
1193
1194        for index in 1..(5 * SMALL_TRACKER_CAPACITY) as u64 {
1195            insert_index(&ticket_processor, index)
1196                .with_context(|| format!("should build ticket with index {index}"))?
1197                .with_context(|| format!("fresh index {index} must be accepted"))?;
1198        }
1199        ticket_processor.seen_ticket_indices.run_pending_tasks();
1200
1201        assert!(
1202            insert_index(&ticket_processor, oldest_index)
1203                .context("post-eviction replay must be attempted")?
1204                .is_ok(),
1205            "if this now fails the tracker retains the oldest index beyond its capacity, which is strictly stronger \
1206             than documented and should update the docs on max_tracked_ticket_indices"
1207        );
1208
1209        Ok(())
1210    }
1211
1212    /// The replay tracker is sized by `max_tracked_ticket_indices` alone: lowering the per-next-hop
1213    /// `max_unack_tickets` must not shrink replay protection.
1214    #[tokio::test]
1215    async fn ticket_processor_replay_protection_should_not_depend_on_max_unack_tickets() -> anyhow::Result<()> {
1216        let blokli_client = create_blokli_client()?;
1217        let node = create_node(1, &blokli_client).await?;
1218        let ticket_processor = HoprUnacknowledgedTicketProcessor::new(
1219            node.chain_api.clone(),
1220            node.chain_key.clone(),
1221            Hash::default(),
1222            HoprUnacknowledgedTicketProcessorConfig {
1223                max_unack_tickets: SMALL_TRACKER_CAPACITY,
1224                ..HoprUnacknowledgedTicketProcessorConfig::default()
1225            },
1226        );
1227
1228        for index in 0..(5 * SMALL_TRACKER_CAPACITY) as u64 {
1229            insert_index(&ticket_processor, index)
1230                .with_context(|| format!("should build ticket with index {index}"))?
1231                .with_context(|| format!("fresh index {index} must be accepted"))?;
1232        }
1233        ticket_processor.seen_ticket_indices.run_pending_tasks();
1234
1235        let result = insert_index(&ticket_processor, 0).context("should build replayed ticket")?;
1236        assert!(
1237            matches!(result, Err(HoprProtocolError::DuplicateTicketIndex(_, 1, 0))),
1238            "the oldest index must still be remembered when only max_unack_tickets is small, got: {:?}",
1239            result
1240        );
1241
1242        Ok(())
1243    }
1244
1245    /// At capacity, a next hop's unacknowledged-ticket cache must discard its oldest tickets and keep
1246    /// the newest, which are the ones still likely to be acknowledged.
1247    #[tokio::test]
1248    async fn ticket_processor_should_discard_the_oldest_unacknowledged_tickets_at_capacity() -> anyhow::Result<()> {
1249        let blokli_client = create_blokli_client()?;
1250        let node = create_node(1, &blokli_client).await?;
1251        let ticket_processor = HoprUnacknowledgedTicketProcessor::new(
1252            node.chain_api.clone(),
1253            node.chain_key.clone(),
1254            Hash::default(),
1255            HoprUnacknowledgedTicketProcessorConfig {
1256                max_unack_tickets: SMALL_TRACKER_CAPACITY,
1257                ..HoprUnacknowledgedTicketProcessorConfig::default()
1258            },
1259        );
1260
1261        let mut challenges = Vec::with_capacity(5 * SMALL_TRACKER_CAPACITY);
1262        for index in 0..(5 * SMALL_TRACKER_CAPACITY) as u64 {
1263            let ack_share = HalfKey::random();
1264            let ticket = build_unack_ticket(index, 1, &ack_share)
1265                .with_context(|| format!("should build ticket with index {index}"))?;
1266            let challenge = ack_share.to_challenge().context("should derive challenge")?;
1267            ticket_processor
1268                .insert_unacknowledged_ticket(PEERS[2].1.public(), challenge, ticket)
1269                .with_context(|| format!("ticket with index {index} must be accepted"))?;
1270            challenges.push(challenge);
1271        }
1272
1273        let awaiting_ack = ticket_processor
1274            .unacknowledged_tickets
1275            .get(PEERS[2].1.public())
1276            .context("the next hop should have an unacknowledged-ticket cache")?;
1277        awaiting_ack.run_pending_tasks();
1278
1279        let (oldest, newest) = (
1280            challenges.first().context("should have the oldest challenge")?,
1281            challenges.last().context("should have the newest challenge")?,
1282        );
1283        assert!(
1284            awaiting_ack.contains_key(newest),
1285            "the newest unacknowledged ticket must be kept at capacity"
1286        );
1287        assert!(
1288            !awaiting_ack.contains_key(oldest),
1289            "the oldest unacknowledged ticket must be discarded at capacity"
1290        );
1291        assert!(
1292            awaiting_ack.entry_count() <= SMALL_TRACKER_CAPACITY as u64,
1293            "the cache must stay bounded by max_unack_tickets"
1294        );
1295
1296        Ok(())
1297    }
1298
1299    /// The predicate that the packet pipeline consults to pick the rejection metric label must be
1300    /// true for a duplicate-index rejection and false for every other error.
1301    ///
1302    /// NOTE: this pins the *predicate* only. The label it selects is applied in
1303    /// `transport/hopr`'s `unack_rejection_metric_label`, which is where the mapping itself is
1304    /// pinned — the counter there is behind `not(test)` and cannot be asserted from here.
1305    #[tokio::test]
1306    async fn ticket_processor_only_duplicate_index_error_maps_to_its_own_metric_label() -> anyhow::Result<()> {
1307        use hopr_api::types::primitive::prelude::{Address, HoprBalance};
1308
1309        type TestProcessor = HoprUnacknowledgedTicketProcessor<
1310            std::sync::Arc<
1311                hopr_chain_connector::HoprBlockchainSafeConnector<
1312                    hopr_chain_connector::testing::BlokliTestClient<hopr_chain_connector::testing::StaticState>,
1313                >,
1314            >,
1315        >;
1316
1317        let duplicate = HoprProtocolError::DuplicateTicketIndex(Hash::default(), 1, 5);
1318        assert!(
1319            TestProcessor::is_duplicate_ticket_index_error(&duplicate),
1320            "DuplicateTicketIndex must be reported under its own metric label"
1321        );
1322
1323        let other_errors = [
1324            HoprProtocolError::InvalidSender,
1325            HoprProtocolError::KeyNotFound,
1326            HoprProtocolError::ChannelNotFound(Address::default(), Address::default()),
1327            HoprProtocolError::OutOfFunds(Default::default(), HoprBalance::zero()),
1328        ];
1329        for error in other_errors {
1330            assert!(
1331                !TestProcessor::is_duplicate_ticket_index_error(&error),
1332                "{error} must not be reported as a duplicate ticket index"
1333            );
1334        }
1335
1336        Ok(())
1337    }
1338}