Limit phantom invoice hints to 3

Author: freddiekrugerrand

lightning-invoice/src/utils.rs

@@ -86,9 +86,11 @@ where
 ///   participating node
 /// * It is fine to cache `phantom_route_hints` and reuse it across invoices, as long as the data is
 ///   updated when a channel becomes disabled or closes
-/// * Note that if too many channels are included in [`PhantomRouteHints::channels`], the invoice
-///   may be too long for QR code scanning. To fix this, `PhantomRouteHints::channels` may be pared
-///   down
+/// * Note that the route hints generated from `phantom_route_hints` will be limited to a maximum
+///   of 3 hints to ensure that the invoice can be scanned in a QR code. These hints are selected
+///   in the order that the nodes in `PhantomRouteHints` are specified, selecting one hint per node
+///   until the maximum is hit. Callers may provide as many `PhantomRouteHints::channels` as
+///   desired, but note that some nodes will be trimmed if more than 3 nodes are provided.
 ///
 /// `description_hash` is a SHA-256 hash of the description text
 ///
@@ -220,12 +222,16 @@ where
 
 /// Utility to select route hints for phantom invoices.
 /// See [`PhantomKeysManager`] for more information on phantom node payments.
+/// 
+/// To ensure that the phantom invoice is still readable by QR code, we limit to 3 hints per invoice:
+/// * Select up to three channels per node.
+/// * Select one hint from each node, up to three hints or until we run out of hints.
 fn select_phantom_hints<L: Deref>(amt_msat: Option<u64>, phantom_route_hints: Vec<PhantomRouteHints>, 
     logger: L) -> Vec<RouteHint> 
 where
 	L::Target: Logger,
 {
-	let mut phantom_hints : Vec<RouteHint> = Vec::new();
+	let mut phantom_hints : Vec<Vec<RouteHint>> = Vec::new();
 
 	for PhantomRouteHints { channels, phantom_scid, real_node_pubkey } in phantom_route_hints {
 		log_trace!(logger, "Generating phantom route hints for node {}",
@@ -239,7 +245,7 @@ where
 		if route_hints.is_empty() {
 			route_hints.push(RouteHint(vec![]))
 		}
-		for mut route_hint in route_hints {
+		for route_hint in &mut route_hints {
 			route_hint.0.push(RouteHintHop {
 				src_node_id: real_node_pubkey,
 				short_channel_id: phantom_scid,
@@ -250,12 +256,36 @@ where
 				cltv_expiry_delta: MIN_CLTV_EXPIRY_DELTA,
 				htlc_minimum_msat: None,
 				htlc_maximum_msat: None,});
+		}
+
+		phantom_hints.push(route_hints);
+	}
 
-			phantom_hints.push(route_hint.clone());
+	// We have one vector per real node involved in creating the phantom invoice. To distribute 
+	// the hints across our real nodes we add one hint from each in turn until no node has any hints
+	// left (if one node has more hints than any other, these will accumulate at the end of the
+	// vector).
+	let mut invoice_hints: Vec<&RouteHint> = Vec::new();
+	let mut hint_idx = 0;
+
+	loop {
+		let mut remaining_hints = false;
+
+		for hints in phantom_hints.iter() {
+			if hint_idx < hints.len() {
+				invoice_hints.push(&hints[hint_idx]);
+				remaining_hints = true
+			}
 		}
+
+		if !remaining_hints {
+			break
+		}
+
+		hint_idx +=1;
 	}
 
-	phantom_hints
+	invoice_hints.into_iter().take(3).cloned().collect()
 }
 
 #[cfg(feature = "std")]
@@ -1536,6 +1566,64 @@ mod test {
 		);
 	}
 
+	#[test]
+	fn test_multi_node_hints_limited_to_3() {
+		let mut chanmon_cfgs = create_chanmon_cfgs(5);
+		let seed_1 = [42 as u8; 32];
+		let seed_2 = [43 as u8; 32];
+		let seed_3 = [44 as u8; 32];
+		let cross_node_seed = [44 as u8; 32];
+		chanmon_cfgs[2].keys_manager.backing = PhantomKeysManager::new(&seed_1, 43, 44, &cross_node_seed);
+		chanmon_cfgs[3].keys_manager.backing = PhantomKeysManager::new(&seed_2, 43, 44, &cross_node_seed);
+		chanmon_cfgs[4].keys_manager.backing = PhantomKeysManager::new(&seed_3, 43, 44, &cross_node_seed);
+		let node_cfgs = create_node_cfgs(5, &chanmon_cfgs);
+		let node_chanmgrs = create_node_chanmgrs(5, &node_cfgs, &[None, None, None, None, None]);
+		let nodes = create_network(5, &node_cfgs, &node_chanmgrs);
+
+		// Setup each phantom node with two channels from distinct peers. 
+		let _chan_0_2 = create_unannounced_chan_between_nodes_with_value(&nodes, 0, 2, 10_000, 0);
+		let _chan_1_2 = create_unannounced_chan_between_nodes_with_value(&nodes, 1, 2, 20_000, 0);
+		let _chan_0_3 = create_unannounced_chan_between_nodes_with_value(&nodes, 0, 3, 20_000, 0);
+		let _chan_1_3 = create_unannounced_chan_between_nodes_with_value(&nodes, 1, 3, 10_000, 0);
+		let _chan_0_4 = create_unannounced_chan_between_nodes_with_value(&nodes, 0, 4, 20_000, 0);
+		let _chan_1_4 = create_unannounced_chan_between_nodes_with_value(&nodes, 1, 4, 10_000, 0);
+
+		// Since the invoice amount is above all channels inbound, every one is eligible. Test that 
+		// we include one channel from each of our three nodes.
+		match_multi_node_invoice_distinct_nodes(
+		    Some(100_000_000), 
+		    &nodes[3], 
+		    vec![&nodes[2], &nodes[3], &nodes[4],],
+		    3,
+		);
+	}
+
+	#[test]
+	fn test_multi_node_hints_at_least_3() {
+		let mut chanmon_cfgs = create_chanmon_cfgs(5);
+		let seed_1 = [42 as u8; 32];
+		let seed_2 = [43 as u8; 32];
+		let cross_node_seed = [44 as u8; 32];
+		chanmon_cfgs[1].keys_manager.backing = PhantomKeysManager::new(&seed_1, 43, 44, &cross_node_seed);
+		chanmon_cfgs[2].keys_manager.backing = PhantomKeysManager::new(&seed_2, 43, 44, &cross_node_seed);
+		let node_cfgs = create_node_cfgs(5, &chanmon_cfgs);
+		let node_chanmgrs = create_node_chanmgrs(5, &node_cfgs, &[None, None, None, None, None]);
+		let nodes = create_network(5, &node_cfgs, &node_chanmgrs);
+
+		let _chan_0_3 = create_unannounced_chan_between_nodes_with_value(&nodes, 0, 3, 10_000, 0);
+		let _chan_1_3 = create_unannounced_chan_between_nodes_with_value(&nodes, 1, 3, 20_000, 0);
+		let _chan_2_3 = create_unannounced_chan_between_nodes_with_value(&nodes, 2, 3, 30_000, 0);
+		let _chan_0_4 = create_unannounced_chan_between_nodes_with_value(&nodes, 0, 4, 10_000, 0);
+
+		// Since the invoice amount is above all channels inbound, all four are eligible. Test that
+		// we still include 3 hints from 2 distinct nodes.
+		match_multi_node_invoice_distinct_nodes(
+		    Some(100_000_000), 
+		    &nodes[3],vec![&nodes[3], &nodes[4],], 
+		    2,
+		);
+	}
+
 	fn create_multi_node_invoice<'a, 'b: 'a, 'c: 'b>(
 		invoice_amt: Option<u64>,
 		invoice_node: &Node<'a, 'b, 'c>,
@@ -1556,6 +1644,29 @@ mod test {
 		(invoice, phantom_scids)
 	}
 
+	fn match_multi_node_invoice_distinct_nodes<'a, 'b: 'a, 'c: 'b>(
+		invoice_amt: Option<u64>,
+		invoice_node: &Node<'a, 'b, 'c>,
+		network_multi_nodes: Vec<&Node<'a, 'b, 'c>>,
+		distinct_nodes: usize,
+	){
+		let (invoice, phantom_scids) = create_multi_node_invoice(invoice_amt, invoice_node, network_multi_nodes);
+
+		let mut hint_nodes = crate::HashMap::new();
+		for hint in invoice.private_routes() {
+			let hints = &(hint.0).0;
+			match hints.len() {
+				2 => {
+					hint_nodes.insert(hints[1].src_node_id, true);
+					let phantom_scid = hints[1].short_channel_id;
+					assert!(phantom_scids.contains(&phantom_scid));
+				},
+				_ => panic!("Incorrect hint length generated")
+			}
+		}
+		assert_eq!(hint_nodes.len(), distinct_nodes, "Unmatched number of distinct phantom nodes for hints.");
+	}
+
 	fn match_multi_node_invoice_routes<'a, 'b: 'a, 'c: 'b>(
 		invoice_amt: Option<u64>,
 		invoice_node: &Node<'a, 'b, 'c>,