Refuse to pay BOLT 12 invoices with records above experimental range
What changed, and why it matters
This commit hardens LDK's BOLT 12 payment logic so it refuses to pay invoices containing very large unknown record types (4 billion and up). These records are legal under the Lightning spec, but LDK doesn't understand them, so the change treats them like unknown required features and aborts payment before funds move. It is a defensive safety fix, not a response to an active exploit.
No immediate action beyond normal review and merge. Users should upgrade to a release containing this commit if they process BOLT 12 invoices from untrusted payees. Monitor the linked issue #5668 for any related spec clarification.
Security signals we found
Defensive refusal to pay invoices with unknown high-numbered TLV records
Reuses existing UnknownRequiredFeatures failure path instead of adding a new one
Adds explicit checks before payment state insertion and route construction
Includes unit tests for detection and payment rejection
References a spec discussion (#5668) about payer-proof safety
Evidence from the diff
The patch adds has_records_above_experimental_range() checks for Bolt12Invoice and StaticInvoice, and rejects payment initiation in outbound_payment.rs via Bolt12PaymentError::UnknownRequiredFeatures / PaymentFailureReason::UnknownRequiredFeatures. It covers pay_for_bolt12_invoice, send_payment_for_bolt12_invoice, and the async/static invoice paths. The previous commit had made such invoices deserializable again; this commit keeps deserialization but blocks payment.
Changed components
BOLT 12 invoice payment flowStatic invoice / async payments flowOutbound payment handling (ChannelManager::pay_for_bolt12_invoice, send_payment_for_bolt12_invoice)Invoice and static invoice parsing helpersInspect captured patch +106 / −17
### lightning/src/events/mod.rs
@@ -899,6 +899,10 @@ pub enum PaymentFailureReason {
/// your router.
UnexpectedError,
/// An invoice was received that required unknown features.
+ ///
+ /// Also used when an invoice contains TLV records with a type above the experimental invoice
+ /// range, which are valid per the spec but unknown to this version of LDK, and are refused
+ /// for payment.
UnknownRequiredFeatures,
/// A [`Bolt12Invoice`] was not received in a reasonable amount of time.
InvoiceRequestExpired,
### lightning/src/ln/offers_tests.rs
@@ -65,7 +65,9 @@ use crate::offers::nonce::Nonce;
use crate::offers::offer::OfferBuilder;
use crate::offers::parse::Bolt12SemanticError;
use crate::offers::payer_proof::PayerProof;
-use crate::offers::test_utils::{recipient_pubkey, recipient_sign};
+use crate::offers::test_utils::{
+ invoice_with_record_above_experimental_range, recipient_pubkey, recipient_sign,
+};
use crate::onion_message::messenger::{DefaultMessageRouter, Destination, MessageRouter, MessageSendInstructions, NodeIdMessageRouter, NullMessageRouter, PeeledOnion, DUMMY_HOPS_PATH_LENGTH, QR_CODED_DUMMY_HOPS_PATH_LENGTH};
use crate::onion_message::offers::OffersMessage;
use crate::routing::router::{DEFAULT_PAYMENT_DUMMY_HOPS, PaymentParameters, RouteParameters, RouteParametersConfig};
@@ -3067,6 +3069,17 @@ fn pay_for_bolt12_invoice_error_cases() {
Err(Bolt12PaymentError::UnsupportedChain),
);
+ // An invoice containing an unknown TLV record above the experimental invoice range is
+ // rejected before any state is inserted.
+ let invoice_above_experimental_range =
+ invoice_with_record_above_experimental_range(Network::Testnet);
+ assert!(invoice_above_experimental_range.has_records_above_experimental_range());
+ assert_eq!(
+ bob.node
+ .pay_for_bolt12_invoice(&invoice_above_experimental_range, payment_id, Default::default()),
+ Err(Bolt12PaymentError::UnknownRequiredFeatures),
+ );
+
// First call succeeds and starts the payment.
bob.node.pay_for_bolt12_invoice(&invoice, payment_id, Default::default()).unwrap();
### lightning/src/ln/outbound_payment.rs
@@ -696,6 +696,10 @@ pub enum Bolt12PaymentError {
/// Payment for an invoice with the corresponding [`PaymentId`] was already initiated.
DuplicateInvoice,
/// The invoice was valid for the corresponding [`PaymentId`], but required unknown features.
+ ///
+ /// Also returned when the invoice contains TLV records with a type above the experimental
+ /// invoice range, which are valid per the spec but unknown to this version of LDK, and are
+ /// refused for payment.
UnknownRequiredFeatures,
/// Incorrect amount was provided to [`ChannelManager::pay_for_bolt12_invoice`].
///
@@ -1187,6 +1191,13 @@ impl OutboundPayments {
return Err(Bolt12PaymentError::UnknownRequiredFeatures);
}
+ if invoice.has_records_above_experimental_range() {
+ self.abandon_payment(
+ payment_id, PaymentFailureReason::UnknownRequiredFeatures, pending_events,
+ );
+ return Err(Bolt12PaymentError::UnknownRequiredFeatures);
+ }
+
let route_params = Self::bolt12_route_params(invoice, invoice.amount_msats(), params_config);
let invoice = PaidBolt12Invoice::Bolt12Invoice(invoice.clone());
self.send_payment_for_bolt12_invoice_internal(
@@ -1238,6 +1249,10 @@ impl OutboundPayments {
return Err(Bolt12PaymentError::UnknownRequiredFeatures);
}
+ if invoice.has_records_above_experimental_range() {
+ return Err(Bolt12PaymentError::UnknownRequiredFeatures);
+ }
+
let payment_hash = invoice.payment_hash();
match self.pending_outbound_payments.lock().unwrap().entry(payment_id) {
@@ -1432,6 +1447,10 @@ impl OutboundPayments {
abandon_with_entry!(entry, PaymentFailureReason::UnknownRequiredFeatures);
return Err(Bolt12PaymentError::UnknownRequiredFeatures);
}
+ if invoice.has_records_above_experimental_range() {
+ abandon_with_entry!(entry, PaymentFailureReason::UnknownRequiredFeatures);
+ return Err(Bolt12PaymentError::UnknownRequiredFeatures);
+ }
if duration_since_epoch
> invoice.created_at().saturating_add(invoice.relative_expiry())
{
### lightning/src/offers/invoice.rs
@@ -989,6 +989,15 @@ impl Bolt12Invoice {
&self.bytes
}
+ /// Whether the invoice contains any TLV record with a type at or above the experimental
+ /// invoice range, i.e., a type of 4,000,000,000 or above.
+ ///
+ /// Such records are valid per the spec, but unknown to this version of LDK, so invoices
+ /// containing them should generally not be paid.
+ pub fn has_records_above_experimental_range(&self) -> bool {
+ has_records_above_experimental_range(&self.bytes)
+ }
+
/// Hash that was used for signing the invoice.
pub fn signable_hash(&self) -> [u8; 32] {
self.tagged_hash.as_digest().as_ref().clone()
@@ -1586,10 +1595,20 @@ pub(super) const EXPERIMENTAL_INVOICE_TYPES: core::ops::RangeFrom<u64> = 3_000_0
/// Exclusive upper bound of the experimental invoice TLV range that this version of LDK acts on.
///
-/// Records at or above this type are unknown to this version of LDK. The payer proof extension
-/// rejects omitted record markers in the range.
+/// Records at or above this type are unknown to this version of LDK: invoices containing them
+/// are refused for payment, and the payer proof extension rejects omitted record markers in the
+/// range.
pub(super) const EXPERIMENTAL_INVOICE_TYPES_END: u64 = 4_000_000_000;
+/// Returns whether the serialized invoice contains any TLV record with a type at or above
+/// [`EXPERIMENTAL_INVOICE_TYPES_END`].
+///
+/// The stream must be well-formed, as always produced by a successfully parsed or builder-built
+/// invoice; malformed input panics.
+pub(super) fn has_records_above_experimental_range(bytes: &[u8]) -> bool {
+ TlvStream::new(bytes).any(|record| record.r#type >= EXPERIMENTAL_INVOICE_TYPES_END)
+}
+
#[cfg(not(test))]
tlv_stream!(
ExperimentalInvoiceTlvStream,
@@ -3604,7 +3623,7 @@ mod tests {
fn parses_invoice_with_tlv_records_above_experimental_range() {
// LDK 0.2 and earlier read the experimental invoice range as open-ended and may have
// persisted invoices containing such records, which must remain deserializable.
- let invoice = invoice_with_record_above_experimental_range();
+ let invoice = invoice_with_record_above_experimental_range(Network::Bitcoin);
let mut encoded_invoice = Vec::new();
invoice.write(&mut encoded_invoice).unwrap();
### lightning/src/offers/payer_proof.rs
@@ -25,8 +25,8 @@ use crate::ln::inbound_payment::ExpandedKey;
use crate::ln::msgs::DecodeError;
use crate::offers::invoice::{
Bolt12Invoice, DerivedSigningPubkey, ExperimentalInvoiceTlvStream, ExplicitSigningPubkey,
- InvoiceTlvStream, SigningPubkeyStrategy, EXPERIMENTAL_INVOICE_TYPES_END,
- INVOICE_AMOUNT_TYPE, INVOICE_CREATED_AT_TYPE, INVOICE_FEATURES_TYPE, INVOICE_NODE_ID_TYPE,
+ InvoiceTlvStream, SigningPubkeyStrategy, EXPERIMENTAL_INVOICE_TYPES_END, INVOICE_AMOUNT_TYPE,
+ INVOICE_CREATED_AT_TYPE, INVOICE_FEATURES_TYPE, INVOICE_NODE_ID_TYPE,
INVOICE_PAYMENT_HASH_TYPE, SIGNATURE_TAG,
};
use crate::offers::invoice_request::{
### lightning/src/offers/static_invoice.rs
@@ -16,8 +16,8 @@ use crate::ln::inbound_payment::ExpandedKey;
use crate::ln::msgs::DecodeError;
use crate::offers::invoice::{
check_invoice_signing_pubkey, construct_payment_paths, filter_fallbacks,
- ExperimentalInvoiceTlvStream, ExperimentalInvoiceTlvStreamRef, FallbackAddress,
- InvoiceTlvStream, InvoiceTlvStreamRef,
+ has_records_above_experimental_range, ExperimentalInvoiceTlvStream,
+ ExperimentalInvoiceTlvStreamRef, FallbackAddress, InvoiceTlvStream, InvoiceTlvStreamRef,
};
#[cfg(test)]
use crate::offers::invoice_macros::invoice_builder_methods_test_common;
@@ -405,6 +405,15 @@ impl StaticInvoice {
self.signature
}
+ /// Whether the invoice contains any TLV record with a type at or above the experimental
+ /// invoice range, i.e., a type of 4,000,000,000 or above.
+ ///
+ /// Such records are valid per the spec, but unknown to this version of LDK, so invoices
+ /// containing them should generally not be paid.
+ pub fn has_records_above_experimental_range(&self) -> bool {
+ has_records_above_experimental_range(&self.bytes)
+ }
+
/// Whether the [`Offer`] that this invoice is based on is expired.
#[cfg(feature = "std")]
pub fn is_offer_expired(&self) -> bool {
@@ -1745,6 +1754,15 @@ mod tests {
}
}
+ #[test]
+ fn detects_tlv_records_above_experimental_range() {
+ let invoice = static_invoice_with_record_above_experimental_range();
+ assert!(invoice.has_records_above_experimental_range());
+
+ let invoice = dummy_static_invoice();
+ assert!(!invoice.has_records_above_experimental_range());
+ }
+
#[test]
fn fails_parsing_invoice_with_out_of_range_tlv_records() {
let invoice = invoice();
### lightning/src/offers/test_utils.rs
@@ -9,6 +9,7 @@
//! Utilities for testing BOLT 12 Offers interfaces
+use bitcoin::network::Network;
use bitcoin::secp256k1::schnorr::Signature;
use bitcoin::secp256k1::{Keypair, PublicKey, Secp256k1, SecretKey};
@@ -17,7 +18,9 @@ use crate::blinded_path::payment::{BlindedPayInfo, BlindedPaymentPath};
use crate::blinded_path::BlindedHop;
use crate::ln::channelmanager::PaymentId;
use crate::ln::inbound_payment::ExpandedKey;
-use crate::offers::invoice::{Bolt12Invoice, UnsignedBolt12Invoice, EXPERIMENTAL_INVOICE_TYPES_END};
+use crate::offers::invoice::{
+ Bolt12Invoice, UnsignedBolt12Invoice, EXPERIMENTAL_INVOICE_TYPES_END,
+};
use crate::offers::invoice_request::InvoiceRequest;
use crate::offers::merkle::TaggedHash;
use crate::sign::EntropySource;
@@ -187,11 +190,27 @@ pub(crate) fn dummy_invoice_request() -> InvoiceRequest {
.unwrap()
}
-/// A [`Bolt12Invoice`] containing an unknown odd TLV record with a type above the experimental
-/// invoice range. Such invoices are deserialized, but refused for payment.
-pub(crate) fn invoice_with_record_above_experimental_range() -> Bolt12Invoice {
+/// A [`Bolt12Invoice`] for the given chain containing an unknown odd TLV record with a type above
+/// the experimental invoice range. Such invoices are deserialized, but refused for payment.
+pub(crate) fn invoice_with_record_above_experimental_range(chain: Network) -> Bolt12Invoice {
+ let expanded_key = ExpandedKey::new([42; 32]);
+ let entropy = FixedEntropy {};
+ let nonce = Nonce::from_entropy_source(&entropy);
+ let secp_ctx = Secp256k1::new();
+ let payment_id = PaymentId([1; 32]);
+
let mut bytes = Vec::new();
- dummy_invoice_request()
+ OfferBuilder::new(recipient_pubkey())
+ .chain(chain)
+ .amount_msats(1000)
+ .build()
+ .unwrap()
+ .request_invoice(&expanded_key, nonce, &secp_ctx, payment_id)
+ .unwrap()
+ .chain(chain)
+ .unwrap()
+ .build_and_sign()
+ .unwrap()
.respond_with_no_std(payment_paths(), payment_hash(), now())
.unwrap()
.build()
@@ -207,8 +226,5 @@ pub(crate) fn invoice_with_record_above_experimental_range() -> Bolt12Invoice {
[42u8; 32].write(&mut bytes).unwrap();
// Re-parse the modified bytes so the invoice's tagged hash covers the appended record.
- UnsignedBolt12Invoice::try_from(bytes)
- .unwrap()
- .sign(recipient_sign)
- .unwrap()
+ UnsignedBolt12Invoice::try_from(bytes).unwrap().sign(recipient_sign).unwrap()
}Why this scored 48/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.