f: more Path/TrampolineHop docs

Author: arik-so

lightning/src/routing/router.rs

@@ -400,6 +400,8 @@ pub struct RouteHop {
 	/// If this is the last hop in [`Path::hops`]:
 	/// * if we're sending to a [`BlindedPaymentPath`], this is the fee paid for use of the entire
 	///   blinded path
+	/// * if we're sending to a Trampoline entrypoint, this is the total incoming amount to the
+	///   Trampoline entrypoint
 	/// * otherwise, this is the full value of this [`Path`]'s part of the payment
 	pub fee_msat: u64,
 	/// The CLTV delta added for this hop.
@@ -485,6 +487,11 @@ pub struct Path {
 	/// The list of unblinded hops in this [`Path`]. Must be at least length one.
 	pub hops: Vec<RouteHop>,
 	/// The list of unblinded Trampoline hops. When using Trampoline, must contain at least one hop.
+	///
+	/// Note that the first [`TrampolineHop`] node must also be present as the last [`RouteHop`] node,
+	/// where the RouteHop's fee_msat is the total amount received by the first [`TrampolineHop`],
+	/// including any blinded path, whereas the [`TrampolineHop`]'s fee_msat is the fee that node
+	/// may use to route to the next Trampoline hop and pay itself for the trouble.
 	pub trampoline_hops: Vec<TrampolineHop>,
 	/// The blinded path at which this path terminates, if we're sending to one, and its metadata.
 	pub blinded_tail: Option<BlindedTail>,
@@ -665,6 +672,8 @@ impl Readable for Route {
 
 		let trampoline_paths: Vec<Vec<TrampolineHop>> = trampoline_paths.unwrap_or(Vec::new());
 		if !trampoline_paths.is_empty() {
+			// if we have serialized Trampoline paths, the number of serialized TrampolineHop
+			// vectors must match the number of serialized Paths
 			if trampoline_paths.len() != paths.len() { return Err(DecodeError::InvalidValue) }
 			for (path, trampoline_hops) in paths.iter_mut().zip(trampoline_paths.into_iter()) {
 				path.trampoline_hops = trampoline_hops;