Rename get_inbound_payment_key to get_expanded_key

shaavan · shaavan · commit c7f108056620 · 2025-05-16T16:44:32.000+05:30
The use of ExpandedKey has grown beyond just encrypting inbound
payment data-it now also supports BOLT 12 Offers, spontaneous
payments, and authentication of various payment metadata.

To reflect this broader purpose, this commit renames the function
and updates its documentation accordingly.
diff --git a/fuzz/src/chanmon_consistency.rs b/fuzz/src/chanmon_consistency.rs
@@ -326,7 +326,7 @@ impl NodeSigner for KeyProvider {
 		Ok(SharedSecret::new(other_key, &node_secret))
 	}
 
-	fn get_inbound_payment_key(&self) -> ExpandedKey {
+	fn get_expanded_key(&self) -> ExpandedKey {
 		#[rustfmt::skip]
 		let random_bytes = [0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 1, self.node_secret[31]];
 		ExpandedKey::new(random_bytes)
diff --git a/fuzz/src/full_stack.rs b/fuzz/src/full_stack.rs
@@ -405,7 +405,7 @@ impl NodeSigner for KeyProvider {
 		Ok(SharedSecret::new(other_key, &node_secret))
 	}
 
-	fn get_inbound_payment_key(&self) -> ExpandedKey {
+	fn get_expanded_key(&self) -> ExpandedKey {
 		self.inbound_payment_key
 	}
 
diff --git a/fuzz/src/onion_message.rs b/fuzz/src/onion_message.rs
@@ -228,7 +228,7 @@ impl NodeSigner for KeyProvider {
 		Ok(SharedSecret::new(other_key, &node_secret))
 	}
 
-	fn get_inbound_payment_key(&self) -> ExpandedKey {
+	fn get_expanded_key(&self) -> ExpandedKey {
 		unreachable!()
 	}
 
diff --git a/lightning/src/ln/async_payments_tests.rs b/lightning/src/ln/async_payments_tests.rs
@@ -668,7 +668,7 @@ fn amount_doesnt_match_invreq() {
 			valid_invreq = Some(invoice_request.clone());
 			*invoice_request = offer
 				.request_invoice(
-					&nodes[0].keys_manager.get_inbound_payment_key(),
+					&nodes[0].keys_manager.get_expanded_key(),
 					Nonce::from_entropy_source(nodes[0].keys_manager),
 					&secp_ctx,
 					payment_id,
diff --git a/lightning/src/ln/blinded_payment_tests.rs b/lightning/src/ln/blinded_payment_tests.rs
@@ -83,7 +83,7 @@ pub fn blinded_payment_path(
 	};
 
 	let nonce = Nonce([42u8; 16]);
-	let expanded_key = keys_manager.get_inbound_payment_key();
+	let expanded_key = keys_manager.get_expanded_key();
 	let payee_tlvs = payee_tlvs.authenticate(nonce, &expanded_key);
 
 	let mut secp_ctx = Secp256k1::new();
@@ -168,7 +168,7 @@ fn do_one_hop_blinded_path(success: bool) {
 		payment_context: PaymentContext::Bolt12Refund(Bolt12RefundContext {}),
 	};
 	let nonce = Nonce([42u8; 16]);
-	let expanded_key = chanmon_cfgs[1].keys_manager.get_inbound_payment_key();
+	let expanded_key = chanmon_cfgs[1].keys_manager.get_expanded_key();
 	let payee_tlvs = payee_tlvs.authenticate(nonce, &expanded_key);
 
 	let mut secp_ctx = Secp256k1::new();
@@ -222,7 +222,7 @@ fn mpp_to_one_hop_blinded_path() {
 		payment_context: PaymentContext::Bolt12Refund(Bolt12RefundContext {}),
 	};
 	let nonce = Nonce([42u8; 16]);
-	let expanded_key = chanmon_cfgs[3].keys_manager.get_inbound_payment_key();
+	let expanded_key = chanmon_cfgs[3].keys_manager.get_expanded_key();
 	let payee_tlvs = payee_tlvs.authenticate(nonce, &expanded_key);
 	let blinded_path = BlindedPaymentPath::new(
 		&[], nodes[3].node.get_our_node_id(), payee_tlvs, u64::MAX, TEST_FINAL_CLTV as u16,
@@ -1342,7 +1342,7 @@ fn custom_tlvs_to_blinded_path() {
 		payment_context: PaymentContext::Bolt12Refund(Bolt12RefundContext {}),
 	};
 	let nonce = Nonce([42u8; 16]);
-	let expanded_key = chanmon_cfgs[1].keys_manager.get_inbound_payment_key();
+	let expanded_key = chanmon_cfgs[1].keys_manager.get_expanded_key();
 	let payee_tlvs = payee_tlvs.authenticate(nonce, &expanded_key);
 	let mut secp_ctx = Secp256k1::new();
 	let blinded_path = BlindedPaymentPath::new(
@@ -1396,7 +1396,7 @@ fn fails_receive_tlvs_authentication() {
 		payment_context: PaymentContext::Bolt12Refund(Bolt12RefundContext {}),
 	};
 	let nonce = Nonce([42u8; 16]);
-	let expanded_key = chanmon_cfgs[1].keys_manager.get_inbound_payment_key();
+	let expanded_key = chanmon_cfgs[1].keys_manager.get_expanded_key();
 	let payee_tlvs = payee_tlvs.authenticate(nonce, &expanded_key);
 
 	let mut secp_ctx = Secp256k1::new();
@@ -1622,7 +1622,7 @@ fn route_blinding_spec_test_vector() {
 			}
 			Ok(SharedSecret::new(other_key, &node_secret))
 		}
-		fn get_inbound_payment_key(&self) -> ExpandedKey { unreachable!() }
+		fn get_expanded_key(&self) -> ExpandedKey { unreachable!() }
 		fn get_node_id(&self, _recipient: Recipient) -> Result<PublicKey, ()> { unreachable!() }
 		fn sign_invoice(
 			&self, _invoice: &RawBolt11Invoice, _recipient: Recipient,
@@ -1931,7 +1931,7 @@ fn test_trampoline_inbound_payment_decoding() {
 			}
 			Ok(SharedSecret::new(other_key, &node_secret))
 		}
-		fn get_inbound_payment_key(&self) -> ExpandedKey { unreachable!() }
+		fn get_expanded_key(&self) -> ExpandedKey { unreachable!() }
 		fn get_node_id(&self, _recipient: Recipient) -> Result<PublicKey, ()> { unreachable!() }
 		fn sign_invoice(
 			&self, _invoice: &RawBolt11Invoice, _recipient: Recipient,
@@ -2016,7 +2016,7 @@ fn do_test_trampoline_single_hop_receive(success: bool) {
 		};
 
 		let nonce = Nonce([42u8; 16]);
-		let expanded_key = nodes[2].keys_manager.get_inbound_payment_key();
+		let expanded_key = nodes[2].keys_manager.get_expanded_key();
 		let payee_tlvs = payee_tlvs.authenticate(nonce, &expanded_key);
 		let carol_unblinded_tlvs = payee_tlvs.encode();
 
diff --git a/lightning/src/ln/channelmanager.rs b/lightning/src/ln/channelmanager.rs
@@ -256,7 +256,7 @@ pub enum PendingHTLCRouting {
 		requires_blinded_error: bool,
 		/// Set if we are receiving a keysend to a blinded path, meaning we created the
 		/// [`PaymentSecret`] and should verify it using our
-		/// [`NodeSigner::get_inbound_payment_key`].
+		/// [`NodeSigner::get_expanded_key`].
 		has_recipient_created_payment_secret: bool,
 		/// The [`InvoiceRequest`] associated with the [`Offer`] corresponding to this payment.
 		invoice_request: Option<InvoiceRequest>,
@@ -3576,7 +3576,7 @@ where
 	) -> Self {
 		let mut secp_ctx = Secp256k1::new();
 		secp_ctx.seeded_randomize(&entropy_source.get_secure_random_bytes());
-		let expanded_inbound_key = node_signer.get_inbound_payment_key();
+		let expanded_inbound_key = node_signer.get_expanded_key();
 		ChannelManager {
 			default_configuration: config.clone(),
 			chain_hash: ChainHash::using_genesis_block(params.network),
@@ -14569,7 +14569,7 @@ where
 			}, None));
 		}
 
-		let expanded_inbound_key = args.node_signer.get_inbound_payment_key();
+		let expanded_inbound_key = args.node_signer.get_expanded_key();
 
 		let mut claimable_payments = hash_map_with_capacity(claimable_htlcs_list.len());
 		if let Some(purposes) = claimable_htlc_purposes {
diff --git a/lightning/src/ln/inbound_payment.rs b/lightning/src/ln/inbound_payment.rs
@@ -37,9 +37,9 @@ const AMT_MSAT_LEN: usize = 8;
 // retrieve said payment type bits.
 const METHOD_TYPE_OFFSET: usize = 5;
 
-/// A set of keys that were HKDF-expanded. Returned by [`NodeSigner::get_inbound_payment_key`].
+/// A set of keys that were HKDF-expanded. Returned by [`NodeSigner::get_expanded_key`].
 ///
-/// [`NodeSigner::get_inbound_payment_key`]: crate::sign::NodeSigner::get_inbound_payment_key
+/// [`NodeSigner::get_expanded_key`]: crate::sign::NodeSigner::get_expanded_key
 #[derive(Hash, Copy, Clone, PartialEq, Eq, Debug)]
 pub struct ExpandedKey {
 	/// The key used to encrypt the bytes containing the payment metadata (i.e. the amount and
@@ -133,7 +133,7 @@ fn min_final_cltv_expiry_delta_from_metadata(bytes: [u8; METADATA_LEN]) -> u16 {
 /// `ChannelManager` is required. Useful for generating invoices for [phantom node payments] without
 /// a `ChannelManager`.
 ///
-/// `keys` is generated by calling [`NodeSigner::get_inbound_payment_key`]. It is recommended to
+/// `keys` is generated by calling [`NodeSigner::get_expanded_key`]. It is recommended to
 /// cache this value and not regenerate it for each new inbound payment.
 ///
 /// `current_time` is a Unix timestamp representing the current time.
@@ -142,7 +142,7 @@ fn min_final_cltv_expiry_delta_from_metadata(bytes: [u8; METADATA_LEN]) -> u16 {
 /// on versions of LDK prior to 0.0.114.
 ///
 /// [phantom node payments]: crate::sign::PhantomKeysManager
-/// [`NodeSigner::get_inbound_payment_key`]: crate::sign::NodeSigner::get_inbound_payment_key
+/// [`NodeSigner::get_expanded_key`]: crate::sign::NodeSigner::get_expanded_key
 pub fn create<ES: Deref>(
 	keys: &ExpandedKey, min_value_msat: Option<u64>, invoice_expiry_delta_secs: u32,
 	entropy_source: &ES, current_time: u64, min_final_cltv_expiry_delta: Option<u16>,
@@ -322,7 +322,7 @@ fn construct_payment_secret(
 /// For payments including a custom `min_final_cltv_expiry_delta`, the metadata is constructed as:
 ///   payment method (3 bits) || payment amount (8 bytes - 3 bits) || min_final_cltv_expiry_delta (2 bytes) || expiry (6 bytes)
 ///
-/// In both cases the result is then encrypted using a key derived from [`NodeSigner::get_inbound_payment_key`].
+/// In both cases the result is then encrypted using a key derived from [`NodeSigner::get_expanded_key`].
 ///
 /// Then on payment receipt, we verify in this method that the payment preimage and payment secret
 /// match what was constructed.
@@ -343,7 +343,7 @@ fn construct_payment_secret(
 ///
 /// See [`ExpandedKey`] docs for more info on the individual keys used.
 ///
-/// [`NodeSigner::get_inbound_payment_key`]: crate::sign::NodeSigner::get_inbound_payment_key
+/// [`NodeSigner::get_expanded_key`]: crate::sign::NodeSigner::get_expanded_key
 /// [`create_inbound_payment`]: crate::ln::channelmanager::ChannelManager::create_inbound_payment
 /// [`create_inbound_payment_for_hash`]: crate::ln::channelmanager::ChannelManager::create_inbound_payment_for_hash
 pub(super) fn verify<L: Deref>(
diff --git a/lightning/src/ln/invoice_utils.rs b/lightning/src/ln/invoice_utils.rs
@@ -195,7 +195,7 @@ where
 		},
 	};
 
-	let keys = node_signer.get_inbound_payment_key();
+	let keys = node_signer.get_expanded_key();
 	let (payment_hash, payment_secret) = if let Some(payment_hash) = payment_hash {
 		let payment_secret = create_from_hash(
 			&keys,
diff --git a/lightning/src/ln/max_payment_path_len_tests.rs b/lightning/src/ln/max_payment_path_len_tests.rs
@@ -173,7 +173,7 @@ fn one_hop_blinded_path_with_custom_tlv() {
 		payment_context: PaymentContext::Bolt12Refund(Bolt12RefundContext {}),
 	};
 	let nonce = Nonce([42u8; 16]);
-	let expanded_key = chanmon_cfgs[2].keys_manager.get_inbound_payment_key();
+	let expanded_key = chanmon_cfgs[2].keys_manager.get_expanded_key();
 	let payee_tlvs = payee_tlvs.authenticate(nonce, &expanded_key);
 	let mut secp_ctx = Secp256k1::new();
 	let blinded_path = BlindedPaymentPath::new(
diff --git a/lightning/src/ln/msgs.rs b/lightning/src/ln/msgs.rs
@@ -3443,7 +3443,7 @@ where
 				},
 				ChaChaPolyReadAdapter { readable: BlindedPaymentTlvs::Receive(receive_tlvs) } => {
 					let ReceiveTlvs { tlvs, authentication: (hmac, nonce) } = receive_tlvs;
-					let expanded_key = node_signer.get_inbound_payment_key();
+					let expanded_key = node_signer.get_expanded_key();
 					if tlvs.verify_for_offer_payment(hmac, nonce, &expanded_key).is_err() {
 						return Err(DecodeError::InvalidValue);
 					}
@@ -3595,7 +3595,7 @@ where
 					readable: BlindedTrampolineTlvs::Receive(receive_tlvs),
 				} => {
 					let ReceiveTlvs { tlvs, authentication: (hmac, nonce) } = receive_tlvs;
-					let expanded_key = node_signer.get_inbound_payment_key();
+					let expanded_key = node_signer.get_expanded_key();
 					if tlvs.verify_for_offer_payment(hmac, nonce, &expanded_key).is_err() {
 						return Err(DecodeError::InvalidValue);
 					}
diff --git a/lightning/src/ln/offers_tests.rs b/lightning/src/ln/offers_tests.rs
@@ -2223,7 +2223,7 @@ fn fails_paying_invoice_with_unknown_required_features() {
 	let payment_paths = invoice.payment_paths().to_vec();
 	let payment_hash = invoice.payment_hash();
 
-	let expanded_key = alice.keys_manager.get_inbound_payment_key();
+	let expanded_key = alice.keys_manager.get_expanded_key();
 	let secp_ctx = Secp256k1::new();
 
 	let created_at = alice.node.duration_since_epoch();
diff --git a/lightning/src/sign/mod.rs b/lightning/src/sign/mod.rs
@@ -820,19 +820,24 @@ pub trait EntropySource {
 
 /// A trait that can handle cryptographic operations at the scope level of a node.
 pub trait NodeSigner {
-	/// Get the [`ExpandedKey`] for use in encrypting and decrypting inbound payment data.
+	/// Get the [`ExpandedKey`] which provides cryptographic material for various Lightning Network operations.
+	///
+	/// This key set is used for:
+	/// - Encrypting and decrypting inbound payment metadata
+	/// - Authenticating payment hashes (both LDK-provided and user-provided)
+	/// - Supporting BOLT 12 Offers functionality (signing and encryption)
+	/// - Authenticating spontaneous payments' metadata
 	///
 	/// If the implementor of this trait supports [phantom node payments], then every node that is
 	/// intended to be included in the phantom invoice route hints must return the same value from
 	/// this method.
-	// This is because LDK avoids storing inbound payment data by encrypting payment data in the
-	// payment hash and/or payment secret, therefore for a payment to be receivable by multiple
-	// nodes, they must share the key that encrypts this payment data.
 	///
-	/// This method must return the same value each time it is called.
+	/// This method must return the same value each time it is called, as LDK avoids storing inbound
+	/// payment data by encrypting it in the payment hash and/or payment secret. Consistency is also
+	/// required for signature and encryption verification in Offers and spontaneous payments.
 	///
 	/// [phantom node payments]: PhantomKeysManager
-	fn get_inbound_payment_key(&self) -> ExpandedKey;
+	fn get_expanded_key(&self) -> ExpandedKey;
 
 	/// Get node id based on the provided [`Recipient`].
 	///
@@ -2113,7 +2118,7 @@ impl NodeSigner for KeysManager {
 		Ok(SharedSecret::new(other_key, &node_secret))
 	}
 
-	fn get_inbound_payment_key(&self) -> ExpandedKey {
+	fn get_expanded_key(&self) -> ExpandedKey {
 		self.inbound_payment_key.clone()
 	}
 
@@ -2274,7 +2279,7 @@ impl NodeSigner for PhantomKeysManager {
 		Ok(SharedSecret::new(other_key, &node_secret))
 	}
 
-	fn get_inbound_payment_key(&self) -> ExpandedKey {
+	fn get_expanded_key(&self) -> ExpandedKey {
 		self.inbound_payment_key.clone()
 	}
 
diff --git a/lightning/src/util/dyn_signer.rs b/lightning/src/util/dyn_signer.rs
@@ -214,7 +214,7 @@ inner,
 	fn sign_bolt12_invoice(,
 		invoice: &crate::offers::invoice::UnsignedBolt12Invoice
 	) -> Result<secp256k1::schnorr::Signature, ()>,
-	fn get_inbound_payment_key(,) -> ExpandedKey
+	fn get_expanded_key(,) -> ExpandedKey
 );
 
 delegate!(DynKeysInterface, SignerProvider,
@@ -278,7 +278,7 @@ delegate!(DynPhantomKeysInterface, NodeSigner,
 	fn sign_invoice(, invoice: &RawBolt11Invoice, recipient: Recipient) -> Result<RecoverableSignature, ()>,
 	fn sign_bolt12_invoice(, invoice: &crate::offers::invoice::UnsignedBolt12Invoice
 	) -> Result<secp256k1::schnorr::Signature, ()>,
-	fn get_inbound_payment_key(,) -> ExpandedKey
+	fn get_expanded_key(,) -> ExpandedKey
 );
 
 impl SignerProvider for DynPhantomKeysInterface {
diff --git a/lightning/src/util/test_utils.rs b/lightning/src/util/test_utils.rs
@@ -1486,7 +1486,7 @@ impl TestNodeSigner {
 }
 
 impl NodeSigner for TestNodeSigner {
-	fn get_inbound_payment_key(&self) -> ExpandedKey {
+	fn get_expanded_key(&self) -> ExpandedKey {
 		unreachable!()
 	}
 
@@ -1559,8 +1559,8 @@ impl NodeSigner for TestKeysInterface {
 		self.backing.ecdh(recipient, other_key, tweak)
 	}
 
-	fn get_inbound_payment_key(&self) -> ExpandedKey {
-		self.backing.get_inbound_payment_key()
+	fn get_expanded_key(&self) -> ExpandedKey {
+		self.backing.get_expanded_key()
 	}
 
 	fn sign_invoice(

Original file line number	Diff line number	Diff line change
`@@ -326,7 +326,7 @@ impl NodeSigner for KeyProvider {`
`326`	`326`	`Ok(SharedSecret::new(other_key, &node_secret))`
`327`	`327`	`}`
`328`	`328`
`329`		`- fn get_inbound_payment_key(&self) -> ExpandedKey {`
	`329`	`+ fn get_expanded_key(&self) -> ExpandedKey {`
`330`	`330`	`#[rustfmt::skip]`
`331`	`331`	`let random_bytes = [0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 1, self.node_secret[31]];`
`332`	`332`	`ExpandedKey::new(random_bytes)`
Original file line number	Diff line number	Diff line change
`@@ -405,7 +405,7 @@ impl NodeSigner for KeyProvider {`
`405`	`405`	`Ok(SharedSecret::new(other_key, &node_secret))`
`406`	`406`	`}`
`407`	`407`
`408`		`- fn get_inbound_payment_key(&self) -> ExpandedKey {`
	`408`	`+ fn get_expanded_key(&self) -> ExpandedKey {`
`409`	`409`	`self.inbound_payment_key`
`410`	`410`	`}`
`411`	`411`
Original file line number	Diff line number	Diff line change
`@@ -228,7 +228,7 @@ impl NodeSigner for KeyProvider {`
`228`	`228`	`Ok(SharedSecret::new(other_key, &node_secret))`
`229`	`229`	`}`
`230`	`230`
`231`		`- fn get_inbound_payment_key(&self) -> ExpandedKey {`
	`231`	`+ fn get_expanded_key(&self) -> ExpandedKey {`
`232`	`232`	`unreachable!()`
`233`	`233`	`}`
`234`	`234`