f Rename unknown BOLT11 config flag

Use a name that reflects both possible user actions for unknown
BOLT11 payments: either claim them with a preimage or fail them back.

Co-Authored-By: HAL 9000

Author: tnull

CHANGELOG.md

@@ -14,7 +14,7 @@
   versions need to drain pending events before the upgrade.
 - Applications using the BOLT 11 manual-claiming receive APIs
   (`receive_*_for_hash`) now need to set
-  `Config::manually_claim_unknown_bolt11_payments` to `true`. Otherwise
+  `Config::manually_handle_unknown_bolt11_payments` to `true`. Otherwise
   matching inbound HTLCs will be failed back instead of emitting
   `Event::PaymentClaimable`.
 

src/config.rs

@@ -155,7 +155,7 @@ pub(crate) const LIQUIDITY_DISCOVERY_RETRY_MAX_DELAY: Duration = Duration::from_
 /// | `route_parameters`                     | None                                 |
 /// | `tor_config`                           | None                                 |
 /// | `hrn_config`                           | HumanReadableNamesConfig::default()  |
-/// | `manually_claim_unknown_bolt11_payments` | false                              |
+/// | `manually_handle_unknown_bolt11_payments` | false                              |
 ///
 /// See [`AnchorChannelsConfig`] and [`RouteParametersConfig`] for more information regarding their
 /// respective default values.
@@ -230,7 +230,7 @@ pub struct Config {
 	/// failed, or times out.
 	///
 	/// [`Event::PaymentClaimable`]: crate::Event::PaymentClaimable
-	pub manually_claim_unknown_bolt11_payments: bool,
+	pub manually_handle_unknown_bolt11_payments: bool,
 }
 
 impl Default for Config {
@@ -247,7 +247,7 @@ impl Default for Config {
 			route_parameters: None,
 			node_alias: None,
 			hrn_config: HumanReadableNamesConfig::default(),
-			manually_claim_unknown_bolt11_payments: false,
+			manually_handle_unknown_bolt11_payments: false,
 		}
 	}
 }

src/event.rs

@@ -199,7 +199,7 @@ pub enum Event {
 	/// This needs to be manually claimed by supplying the correct preimage to [`claim_for_hash`].
 	///
 	/// This event is only emitted for unknown payments if
-	/// [`Config::manually_claim_unknown_bolt11_payments`] is enabled. Enabling it may let any
+	/// [`Config::manually_handle_unknown_bolt11_payments`] is enabled. Enabling it may let any
 	/// holder of a valid invoice generated by this node tie up inbound HTLC slots and grow the
 	/// persisted event queue until the payment is claimed, failed, or times out.
 	///
@@ -208,7 +208,7 @@ pub enum Event {
 	///
 	/// Note claiming will necessarily fail after the `claim_deadline` has been reached.
 	///
-	/// [`Config::manually_claim_unknown_bolt11_payments`]: crate::config::Config::manually_claim_unknown_bolt11_payments
+	/// [`Config::manually_handle_unknown_bolt11_payments`]: crate::config::Config::manually_handle_unknown_bolt11_payments
 	/// [`claim_for_hash`]: crate::payment::Bolt11Payment::claim_for_hash
 	/// [`fail_for_hash`]: crate::payment::Bolt11Payment::fail_for_hash
 	PaymentClaimable {
@@ -931,10 +931,10 @@ where
 					..
 				} = &purpose
 				{
-					if !self.config.manually_claim_unknown_bolt11_payments {
+					if !self.config.manually_handle_unknown_bolt11_payments {
 						log_info!(
 								self.logger,
-								"Refusing unknown BOLT11 payment with hash {} as manual claiming is disabled",
+								"Refusing unknown BOLT11 payment with hash {} as manual handling is disabled",
 								hex_utils::to_string(&payment_hash.0),
 							);
 						self.channel_manager.fail_htlc_backwards(&payment_hash);

src/payment/bolt11.rs

@@ -602,19 +602,19 @@ impl Bolt11Payment {
 	/// Returns a payable invoice that can be used to request a payment of the amount
 	/// given for the given payment hash.
 	///
-	/// If [`Config::manually_claim_unknown_bolt11_payments`] is enabled, a
+	/// If [`Config::manually_handle_unknown_bolt11_payments`] is enabled, a
 	/// [`PaymentClaimable`] event will be emitted once the inbound payment arrives. Otherwise, the
 	/// inbound payment will be failed back when it arrives.
 	///
 	/// **Warning:** it is the user's responsibility to never reuse the same payment hash. Reusing a
 	/// payment hash is unsafe and can lead to loss of funds.
 	///
-	/// **Note:** if manual claiming is enabled, users *MUST* handle this event and claim the
+	/// **Note:** if manual handling is enabled, users *MUST* handle this event and claim the
 	/// payment manually via [`claim_for_hash`] as soon as they have obtained access to the
 	/// preimage of the given payment hash. If they're unable to obtain the preimage, they *MUST*
 	/// immediately fail the payment via [`fail_for_hash`].
 	///
-	/// [`Config::manually_claim_unknown_bolt11_payments`]: crate::config::Config::manually_claim_unknown_bolt11_payments
+	/// [`Config::manually_handle_unknown_bolt11_payments`]: crate::config::Config::manually_handle_unknown_bolt11_payments
 	/// [`PaymentClaimable`]: crate::Event::PaymentClaimable
 	/// [`claim_for_hash`]: Self::claim_for_hash
 	/// [`fail_for_hash`]: Self::fail_for_hash
@@ -643,19 +643,19 @@ impl Bolt11Payment {
 	/// Returns a payable invoice that can be used to request a payment for the given payment hash
 	/// and the amount to be determined by the user, also known as a "zero-amount" invoice.
 	///
-	/// If [`Config::manually_claim_unknown_bolt11_payments`] is enabled, a
+	/// If [`Config::manually_handle_unknown_bolt11_payments`] is enabled, a
 	/// [`PaymentClaimable`] event will be emitted once the inbound payment arrives. Otherwise, the
 	/// inbound payment will be failed back when it arrives.
 	///
 	/// **Warning:** it is the user's responsibility to never reuse the same payment hash. Reusing a
 	/// payment hash is unsafe and can lead to loss of funds.
 	///
-	/// **Note:** if manual claiming is enabled, users *MUST* handle this event and claim the
+	/// **Note:** if manual handling is enabled, users *MUST* handle this event and claim the
 	/// payment manually via [`claim_for_hash`] as soon as they have obtained access to the
 	/// preimage of the given payment hash. If they're unable to obtain the preimage, they *MUST*
 	/// immediately fail the payment via [`fail_for_hash`].
 	///
-	/// [`Config::manually_claim_unknown_bolt11_payments`]: crate::config::Config::manually_claim_unknown_bolt11_payments
+	/// [`Config::manually_handle_unknown_bolt11_payments`]: crate::config::Config::manually_handle_unknown_bolt11_payments
 	/// [`PaymentClaimable`]: crate::Event::PaymentClaimable
 	/// [`claim_for_hash`]: Self::claim_for_hash
 	/// [`fail_for_hash`]: Self::fail_for_hash
@@ -702,7 +702,7 @@ impl Bolt11Payment {
 	/// If set, `max_total_lsp_fee_limit_msat` will limit how much fee we allow the LSP to take for opening the
 	/// channel to us. We'll use its cheapest offer otherwise.
 	///
-	/// If [`Config::manually_claim_unknown_bolt11_payments`] is enabled, a
+	/// If [`Config::manually_handle_unknown_bolt11_payments`] is enabled, a
 	/// [`PaymentClaimable`] event will be emitted once the inbound payment arrives. Otherwise, the
 	/// inbound payment will be failed back when it arrives. The check that
 	/// [`counterparty_skimmed_fee_msat`] is within the limits is performed *before* emitting the
@@ -711,13 +711,13 @@ impl Bolt11Payment {
 	/// **Warning:** it is the user's responsibility to never reuse the same payment hash. Reusing a
 	/// payment hash is unsafe and can lead to loss of funds.
 	///
-	/// **Note:** if manual claiming is enabled, users *MUST* handle this event and claim the
+	/// **Note:** if manual handling is enabled, users *MUST* handle this event and claim the
 	/// payment manually via [`claim_for_hash`] as soon as they have obtained access to the
 	/// preimage of the given payment hash. If they're unable to obtain the preimage, they *MUST*
 	/// immediately fail the payment via [`fail_for_hash`].
 	///
 	/// [LSPS2]: https://github.com/BitcoinAndLightningLayerSpecs/lsp/blob/main/LSPS2/README.md
-	/// [`Config::manually_claim_unknown_bolt11_payments`]: crate::config::Config::manually_claim_unknown_bolt11_payments
+	/// [`Config::manually_handle_unknown_bolt11_payments`]: crate::config::Config::manually_handle_unknown_bolt11_payments
 	/// [`PaymentClaimable`]: crate::Event::PaymentClaimable
 	/// [`claim_for_hash`]: Self::claim_for_hash
 	/// [`fail_for_hash`]: Self::fail_for_hash
@@ -775,7 +775,7 @@ impl Bolt11Payment {
 	/// parts-per-million millisatoshis, we allow the LSP to take for opening the channel to us.
 	/// We'll use its cheapest offer otherwise.
 	///
-	/// If [`Config::manually_claim_unknown_bolt11_payments`] is enabled, a
+	/// If [`Config::manually_handle_unknown_bolt11_payments`] is enabled, a
 	/// [`PaymentClaimable`] event will be emitted once the inbound payment arrives. Otherwise, the
 	/// inbound payment will be failed back when it arrives. The check that
 	/// [`counterparty_skimmed_fee_msat`] is within the limits is performed *before* emitting the
@@ -784,13 +784,13 @@ impl Bolt11Payment {
 	/// **Warning:** it is the user's responsibility to never reuse the same payment hash. Reusing a
 	/// payment hash is unsafe and can lead to loss of funds.
 	///
-	/// **Note:** if manual claiming is enabled, users *MUST* handle this event and claim the
+	/// **Note:** if manual handling is enabled, users *MUST* handle this event and claim the
 	/// payment manually via [`claim_for_hash`] as soon as they have obtained access to the
 	/// preimage of the given payment hash. If they're unable to obtain the preimage, they *MUST*
 	/// immediately fail the payment via [`fail_for_hash`].
 	///
 	/// [LSPS2]: https://github.com/BitcoinAndLightningLayerSpecs/lsp/blob/main/LSPS2/README.md
-	/// [`Config::manually_claim_unknown_bolt11_payments`]: crate::config::Config::manually_claim_unknown_bolt11_payments
+	/// [`Config::manually_handle_unknown_bolt11_payments`]: crate::config::Config::manually_handle_unknown_bolt11_payments
 	/// [`PaymentClaimable`]: crate::Event::PaymentClaimable
 	/// [`claim_for_hash`]: Self::claim_for_hash
 	/// [`fail_for_hash`]: Self::fail_for_hash

tests/common/mod.rs

@@ -623,7 +623,7 @@ pub(crate) fn setup_two_nodes_with_store(
 	println!("\n== Node B ==");
 	let mut config_b = random_config();
 	config_b.store_type = store_type;
-	config_b.node_config.manually_claim_unknown_bolt11_payments = true;
+	config_b.node_config.manually_handle_unknown_bolt11_payments = true;
 
 	if cfg!(hrn_tests) {
 		config_b.node_config.hrn_config = HumanReadableNamesConfig {

tests/integration_tests_postgres.rs

@@ -38,7 +38,7 @@ async fn channel_full_cycle_with_postgres_store() {
 
 	println!("\n== Node B ==");
 	let mut config_b = common::random_config();
-	config_b.node_config.manually_claim_unknown_bolt11_payments = true;
+	config_b.node_config.manually_handle_unknown_bolt11_payments = true;
 	let mut builder_b = Builder::from_config(config_b.node_config);
 	builder_b.set_chain_source_esplora(esplora_url.clone(), None);
 	let node_b = builder_b

tests/integration_tests_vss.rs

@@ -36,7 +36,7 @@ async fn channel_full_cycle_with_vss_store() {
 
 	println!("\n== Node B ==");
 	let mut config_b = common::random_config();
-	config_b.node_config.manually_claim_unknown_bolt11_payments = true;
+	config_b.node_config.manually_handle_unknown_bolt11_payments = true;
 	let mut builder_b = Builder::from_config(config_b.node_config);
 	builder_b.set_chain_source_esplora(esplora_url.clone(), None);
 	let node_b = builder_b