Deprecate `pay_for_offer_from_human_readable_name`
What the developer wrote
Authored by Matt Corallo
Deprecate `pay_for_offer_from_human_readable_name`
While its cool to have a super trivial API to initiate payment to
a `HumanReadableName`, most wallets ultimately support multiple
payment instruction formats (eg on-chain) or multiple HRN
resolution schemes (eg LN-Address). Thus, we generally don't expect
this API to get a lot of use.
Meanwhile, we've now ended up with both a
`ChannelManager::pay_for_offer_from_hrn` and
`ChannelManager::pay_for_ofer_from_human_readable_name`, which is
incredibly confusing.
Here, we deprecate `pay_for_offer_from_human_readable_name`,
pushing folks to the `bitcoin-payment-instructions` crate instead.
Because it has outbound payment states associated with it it may be
some time before we can fully remove all the pieces of it, sadly.
What changed, and why it matters
This commit simply marks a convenience payment method as deprecated. It does not fix a bug, change behavior, or address any security issue. The function still works; developers are just being steered toward a different, more flexible crate for handling human-readable payment names.
No security action needed. Developers using the deprecated API should plan migration to bitcoin-payment-instructions and pay_for_offer_from_hrn before a future major version removes the method.
Security signals we found
No strong security signals were identified.
Evidence from the diff
The change adds #[deprecated(…)] to ChannelManager::pay_for_offer_from_human_readable_name and updates its doc comment to recommend the bitcoin-payment-instructions crate plus pay_for_offer_from_hrn. A test call is annotated with #[allow(deprecated)] to suppress warnings. No logic, validation, or cryptographic code is modified.
Changed components
lightning/src/ln/channelmanager.rslightning-dns-resolver/src/lib.rsInspect captured patch +6 / −7
diff --git a/lightning-dns-resolver/src/lib.rs b/lightning-dns-resolver/src/lib.rs
index 426f418..55e3ad7 100644
--- a/lightning-dns-resolver/src/lib.rs
+++ b/lightning-dns-resolver/src/lib.rs
@@ -388,6 +388,7 @@ mod test {
let amt = 42_000;
let mut opts = OptionalOfferPaymentParams::default();
opts.payer_note = payer_note.clone();
+ #[allow(deprecated)]
nodes[0]
.node
.pay_for_offer_from_human_readable_name(name, amt, payment_id, opts, resolvers)
diff --git a/lightning/src/ln/channelmanager.rs b/lightning/src/ln/channelmanager.rs
index 3110ed6..7a9a542 100644
--- a/lightning/src/ln/channelmanager.rs
+++ b/lightning/src/ln/channelmanager.rs
@@ -12600,13 +12600,10 @@ where
/// Pays for an [`Offer`] looked up using [BIP 353] Human Readable Names resolved by the DNS
/// resolver(s) at `dns_resolvers` which resolve names according to [bLIP 32].
///
- /// If the wallet supports paying on-chain schemes, you should instead use
- /// [`OMNameResolver::resolve_name`] and [`OMNameResolver::handle_dnssec_proof_for_uri`] (by
- /// implementing [`DNSResolverMessageHandler`]) directly to look up a URI and then delegate to
- /// your normal URI handling.
- ///
- /// Alternatively, the [`bitcoin-payment-instructions`] crate provides an implementation of
- /// much of this logic, and may be useful to decode and resolve payment instructions generally.
+ /// Because most wallets support on-chain or other payment schemes beyond only offers, this is
+ /// deprecated in favor of the [`bitcoin-payment-instructions`] crate, which can be used to
+ /// build an [`OfferFromHrn`] and call [`Self::pay_for_offer_from_hrn`]. Thus, this method is
+ /// deprecated.
///
/// # Payment
///
@@ -12638,6 +12635,7 @@ where
/// [`PaymentFailureReason::UserAbandoned`]: crate::events::PaymentFailureReason::UserAbandoned
/// [`PaymentFailureReason::InvoiceRequestRejected`]: crate::events::PaymentFailureReason::InvoiceRequestRejected
#[cfg(feature = "dnssec")]
+ #[deprecated(note = "Use bitcoin-payment-instructions and pay_for_offer_from_hrn instead")]
pub fn pay_for_offer_from_human_readable_name(
&self, name: HumanReadableName, amount_msats: u64, payment_id: PaymentId,
optional_params: OptionalOfferPaymentParams, dns_resolvers: Vec<Destination>,
Why this scored 15/100
Community notes
Notes can correct, qualify, or add evidence to the AI analysis. Every note shown here has been validated by a human moderator.
The AI analysis stands alone for now. Submit a note if you can add evidence or important context.