Skip to main content

hopr_protocol_hopr/codec/
encoder.rs

1use std::collections::HashMap;
2
3use hopr_api::{
4    chain::*,
5    types::{
6        crypto::{crypto_traits::Randomizable, prelude::*},
7        internal::prelude::*,
8        primitive::prelude::*,
9    },
10};
11use hopr_crypto_packet::prelude::*;
12use hopr_protocol_pix::EntryShareGenerator;
13
14use crate::{HoprCodecConfig, OutgoingPacket, PacketEncoder, SurbStore, errors::HoprProtocolError};
15
16/// Maximum number of acknowledgements that can be packed into a single HOPR packet.
17///
18/// Currently, the [`HoprPacket::PAYLOAD_SIZE`] minus 16-bit acknowledgement batch size counter
19/// divided by [`Acknowledgement::SIZE`].
20pub const MAX_ACKNOWLEDGEMENTS_BATCH_SIZE: usize =
21    (HoprPacket::PAYLOAD_SIZE - size_of::<u16>()) / Acknowledgement::SIZE;
22
23/// Maximum number of decompressed packet keys kept by [`CachingKeyExpander`].
24///
25/// A sender only ever expands the keys of the relays on the paths it currently uses, which is a
26/// far smaller set than the peers it knows about.
27const EXPANDED_KEY_CACHE_CAPACITY: usize = 4_096;
28
29/// A [`KeyExpander`] that memoizes the decompressed form of a packet key.
30///
31/// Deriving shared secrets for an outgoing packet needs the expanded key of every hop, on both the
32/// forward path and each SURB return path - up to twelve per packet. Decompression is a field
33/// exponentiation, so paying it per packet would be a measurable share of packet construction,
34/// whereas the set of relays a sender uses turns over slowly.
35///
36/// This memoizes a pure function of public data, so it deliberately avoids an eviction-tracking
37/// cache: a plain map behind an `RwLock` costs nothing to construct and a read is a single hash,
38/// where a managed cache would charge per-entry bookkeeping on the packet path.
39#[derive(Debug, Default)]
40pub struct CachingKeyExpander(parking_lot::RwLock<HashMap<OffchainPublicKey, ExpandedOffchainPublicKey>>);
41
42impl KeyExpander for CachingKeyExpander {
43    fn expand(&self, key: &OffchainPublicKey) -> hopr_api::types::crypto::errors::Result<ExpandedOffchainPublicKey> {
44        if let Some(expanded) = self.0.read().get(key) {
45            return Ok(expanded.clone());
46        }
47
48        // Two senders racing on the same missing key will both decompress it. That is cheaper
49        // than holding the lock across the computation, and is not a correctness concern.
50        let expanded = DirectKeyExpander.expand(key)?;
51
52        let mut cache = self.0.write();
53        // Another thread may have inserted this key while the lock was not held; without this check it would be
54        // inserted again, and at capacity the insert would flush the whole map for a key that is already cached.
55        if let Some(existing) = cache.get(key) {
56            return Ok(existing.clone());
57        }
58
59        // The set of relays in use turns over slowly, so overflowing the bound means the node's
60        // routing has changed wholesale; dropping everything then is rarer and cheaper than
61        // tracking recency on every packet.
62        if cache.len() >= EXPANDED_KEY_CACHE_CAPACITY {
63            cache.clear();
64        }
65        cache.insert(*key, expanded.clone());
66
67        Ok(expanded)
68    }
69}
70
71/// Default [encoder](PacketEncoder) implementation for HOPR packets.
72pub struct HoprEncoder<Chain, G, S, T> {
73    chain_api: Chain,
74    surb_store: S,
75    ticket_factory: T,
76    chain_key: ChainKeypair,
77    channels_dst: Hash,
78    ssa_generator: G,
79    key_expander: CachingKeyExpander,
80    cfg: HoprCodecConfig,
81}
82
83impl<Chain, G, S, T> HoprEncoder<Chain, G, S, T> {
84    /// Creates a new instance of the encoder.
85    pub fn new(
86        chain_key: ChainKeypair,
87        chain_api: Chain,
88        surb_store: S,
89        ticket_factory: T,
90        channels_dst: Hash,
91        ssa_generator: G,
92        cfg: HoprCodecConfig,
93    ) -> Self {
94        Self {
95            chain_api,
96            surb_store,
97            ticket_factory,
98            chain_key,
99            channels_dst,
100            ssa_generator,
101            key_expander: CachingKeyExpander::default(),
102            cfg,
103        }
104    }
105}
106
107impl<Chain, G, S, T> HoprEncoder<Chain, G, S, T>
108where
109    Chain: ChainKeyOperations + ChainReadChannelOperations + ChainReadTicketOperations + ChainValues + Sync,
110    G: EntryShareGenerator<HoprPixSpec>,
111    S: SurbStore,
112    T: hopr_api::tickets::TicketFactory + Sync,
113{
114    fn encode_packet_internal<D: AsRef<[u8]> + Send + 'static, Sig: Into<PacketSignals> + Send + 'static>(
115        &self,
116        next_peer: OffchainPublicKey,
117        data: D,
118        num_hops: usize,
119        signals: Sig,
120        routing: PacketRouting<ValidatedPath>,
121        pseudonym: HoprPseudonym,
122    ) -> Result<OutgoingPacket, HoprProtocolError> {
123        let next_peer = self
124            .chain_api
125            .packet_key_to_chain_key(&next_peer)
126            .map_err(HoprProtocolError::resolver)?
127            .ok_or(HoprProtocolError::KeyNotFound)?;
128
129        // Decide whether to create a multi-hop or a zero-hop ticket
130        let next_ticket = if num_hops > 1 {
131            let channel = self
132                .chain_api
133                .channel_by_parties(self.chain_key.as_ref(), &next_peer)
134                .map_err(HoprProtocolError::resolver)?
135                .ok_or_else(|| HoprProtocolError::ChannelNotFound(*self.chain_key.as_ref(), next_peer))?;
136
137            let (outgoing_ticket_win_prob, outgoing_ticket_price) = self
138                .chain_api
139                .outgoing_ticket_values(self.cfg.outgoing_win_prob, self.cfg.outgoing_ticket_price)
140                .map_err(HoprProtocolError::resolver)?;
141
142            self.ticket_factory
143                .new_multihop_ticket(
144                    &channel,
145                    (num_hops as u8).try_into().expect("cannot fail due to num_hops > 1"),
146                    outgoing_ticket_win_prob,
147                    outgoing_ticket_price,
148                )
149                .map_err(HoprProtocolError::ticket_factory)?
150        } else {
151            TicketBuilder::zero_hop().counterparty(next_peer)
152        };
153
154        // Construct the outgoing packet
155        let (packet, openers) = HoprPacket::into_outgoing(
156            data.as_ref(),
157            &pseudonym,
158            routing,
159            &self.chain_key,
160            next_ticket,
161            self.chain_api.key_id_mapper_ref(),
162            &self.key_expander,
163            &self.channels_dst,
164            &self.ssa_generator,
165            signals,
166        )?;
167
168        // Store the reply openers under the given SenderId
169        // This is a no-op for reply packets
170        let mut minted_surbs = Vec::with_capacity(openers.len());
171        openers.into_iter().for_each(|(surb_id, opener)| {
172            minted_surbs.push(surb_id);
173            self.surb_store
174                .insert_reply_opener(HoprSenderId::from_pseudonym_and_id(&pseudonym, surb_id), opener);
175        });
176
177        let out = packet.try_as_outgoing().ok_or(HoprProtocolError::InvalidState(
178            "cannot send out packet that is not outgoing",
179        ))?;
180
181        Ok(OutgoingPacket {
182            next_hop: out.next_hop,
183            ack_challenge: out.ack_challenge,
184            encrypted_pix_share: out.encrypted_pix_share,
185            data: HoprOutgoingPacket::frame(out.packet, out.ticket),
186            minted_surbs,
187        })
188    }
189}
190
191impl<Chain, G, S, T> PacketEncoder for HoprEncoder<Chain, G, S, T>
192where
193    Chain: ChainKeyOperations + ChainReadChannelOperations + ChainReadTicketOperations + ChainValues + Send + Sync,
194    G: EntryShareGenerator<HoprPixSpec>,
195    S: SurbStore + Send + Sync,
196    T: hopr_api::tickets::TicketFactory + Send + Sync,
197{
198    type Error = HoprProtocolError;
199
200    #[tracing::instrument(skip_all, level = "trace")]
201    fn encode_packet<D: AsRef<[u8]> + Send + 'static, Sig: Into<PacketSignals> + Send + 'static>(
202        &self,
203        data: D,
204        routing: ResolvedTransportRouting<HoprSurb>,
205        signals: Sig,
206        generation: Option<u8>,
207    ) -> Result<OutgoingPacket, Self::Error> {
208        // Get necessary packet routing values
209        let (next_peer, num_hops, pseudonym, routing) = match routing {
210            ResolvedTransportRouting::Forward {
211                pseudonym,
212                forward_path,
213                return_paths,
214            } => (
215                forward_path[0],
216                forward_path.num_hops(),
217                pseudonym,
218                PacketRouting::ForwardPath {
219                    forward_path,
220                    return_paths,
221                    // Stamp the SURB-batch generation captured when these return paths were resolved,
222                    // so the replying side drops SURBs left over from a superseded return path. It is
223                    // captured with the plan (not read here) so a concurrent re-plan/bump cannot
224                    // label this already-chosen batch with a newer generation; falling back to the
225                    // store's current value only when a caller did not supply one.
226                    generation: generation.unwrap_or_else(|| self.surb_store.current_generation(&pseudonym)),
227                },
228            ),
229            ResolvedTransportRouting::Return(sender_id, surb) => {
230                let next = self
231                    .chain_api
232                    .key_id_mapper_ref()
233                    .map_id_to_public(&surb.first_relayer)
234                    .ok_or(HoprProtocolError::KeyNotFound)?;
235
236                (
237                    next,
238                    surb.additional_data_receiver.proof_of_relay_values().chain_length() as usize,
239                    sender_id.pseudonym(),
240                    PacketRouting::Surb(sender_id, surb),
241                )
242            }
243        };
244
245        tracing::trace!(len = data.as_ref().len(), "encoding packet");
246        self.encode_packet_internal(next_peer, data, num_hops, signals, routing, pseudonym)
247    }
248
249    #[tracing::instrument(skip_all, level = "trace", fields(destination = destination.to_peerid_str()))]
250    fn encode_acknowledgements(
251        &self,
252        acks: &[VerifiedAcknowledgement],
253        destination: &OffchainPublicKey,
254    ) -> Result<OutgoingPacket, Self::Error> {
255        tracing::trace!(num_acks = acks.len(), "encoding acknowledgements");
256
257        let mut all_acks = Vec::<u8>::with_capacity(size_of::<u16>() + acks.len() * Acknowledgement::SIZE);
258        all_acks.extend((acks.len() as u16).to_be_bytes());
259        acks.iter().for_each(|ack| all_acks.extend(ack.leak().as_ref()));
260
261        self.encode_packet_internal(
262            *destination,
263            all_acks,
264            0,
265            None,
266            PacketRouting::NoAck(*destination),
267            HoprPseudonym::random(),
268        )
269    }
270}
271
272#[cfg(test)]
273mod tests {
274    use anyhow::Context;
275    use hopr_api::types::crypto::keypairs::OffchainKeypair;
276
277    use super::*;
278
279    fn random_key() -> OffchainPublicKey {
280        *OffchainKeypair::random().public()
281    }
282
283    /// A key the compact parser accepts but that is not a point on the curve.
284    fn off_curve_key() -> anyhow::Result<OffchainPublicKey> {
285        (1..=u8::MAX)
286            .map(|b| OffchainPublicKey::try_from([b; OffchainPublicKey::SIZE].as_slice()))
287            .filter_map(Result::ok)
288            .find(|key| DirectKeyExpander.expand(key).is_err())
289            .context("no off-curve key among the candidates")
290    }
291
292    #[test]
293    fn expanding_a_key_gives_the_same_result_as_direct_expansion() -> anyhow::Result<()> {
294        let key = random_key();
295        let expander = CachingKeyExpander::default();
296
297        let cached = expander.expand(&key).context("caching expansion")?;
298        let direct = DirectKeyExpander.expand(&key).context("direct expansion")?;
299
300        assert_eq!(OffchainPublicKey::from(&cached), OffchainPublicKey::from(&direct));
301        Ok(())
302    }
303
304    #[test]
305    fn a_key_is_stored_on_the_first_expansion_and_served_from_the_cache_after() -> anyhow::Result<()> {
306        let key = random_key();
307        let expander = CachingKeyExpander::default();
308        assert!(expander.0.read().is_empty());
309
310        let first = expander.expand(&key).context("first expansion")?;
311        assert_eq!(expander.0.read().len(), 1);
312
313        let second = expander.expand(&key).context("second expansion")?;
314        assert_eq!(expander.0.read().len(), 1, "a hit must not add an entry");
315        assert_eq!(OffchainPublicKey::from(&first), OffchainPublicKey::from(&second));
316        Ok(())
317    }
318
319    #[test]
320    fn a_key_that_is_not_on_the_curve_is_rejected_and_not_cached() -> anyhow::Result<()> {
321        let expander = CachingKeyExpander::default();
322
323        assert!(expander.expand(&off_curve_key()?).is_err());
324        assert!(expander.0.read().is_empty());
325        Ok(())
326    }
327
328    #[test]
329    fn reaching_the_capacity_drops_the_cache_and_keeps_only_the_new_key() -> anyhow::Result<()> {
330        let expander = CachingKeyExpander::default();
331        let expanded = DirectKeyExpander
332            .expand(&random_key())
333            .context("expanding a filler key")?;
334        {
335            let mut cache = expander.0.write();
336            while cache.len() < EXPANDED_KEY_CACHE_CAPACITY {
337                cache.insert(random_key(), expanded.clone());
338            }
339        }
340        let newcomer = random_key();
341
342        expander.expand(&newcomer).context("expanding at capacity")?;
343
344        let cache = expander.0.read();
345        assert_eq!(cache.len(), 1);
346        assert!(cache.contains_key(&newcomer));
347        Ok(())
348    }
349
350    #[test]
351    fn a_key_already_cached_at_capacity_does_not_flush_the_cache() -> anyhow::Result<()> {
352        let expander = CachingKeyExpander::default();
353        let cached = random_key();
354        let expanded = DirectKeyExpander.expand(&cached).context("expanding the cached key")?;
355        {
356            let mut cache = expander.0.write();
357            cache.insert(cached, expanded.clone());
358            while cache.len() < EXPANDED_KEY_CACHE_CAPACITY {
359                cache.insert(random_key(), expanded.clone());
360            }
361        }
362
363        expander.expand(&cached).context("expanding a cached key at capacity")?;
364
365        assert_eq!(expander.0.read().len(), EXPANDED_KEY_CACHE_CAPACITY);
366        Ok(())
367    }
368}