Read invoice TLV records above the experimental range
What changed, and why it matters
This commit fixes a backward-compatibility bug in LDK's BOLT 12 invoice parser. A previous change had capped the range of 'experimental' TLV record types at 4 billion, but the Lightning spec imposes no upper bound. As a result, invoices created or stored by LDK 0.2 that contained odd experimental TLVs above 4 billion became unreadable after upgrading. Because these invoices are embedded in channel monitors, a single unreadable monitor could block all of a node's channels from being watched until the operator manually intervened. The patch reopens the parsing range while keeping the 4 billion limit only where it is still meaningful: payer-proof validation and refusing to pay such invoices.
Apply the patch to restore backward-compatible invoice parsing. Operators already affected by unreadable monitors should upgrade and restart; the fix allows monitors with such invoices to load. Review any custom tooling that may have relied on the 4 billion upper bound for parsing experimental TLVs.
Security signals we found
Backward-compatibility regression in deserialization of persisted channel monitors
Denial-of-service via unreadable monitor blocking all channel monitoring
Spec compliance fix: TLV record types have no upper bound
Payer-proof validation still enforces the 4 billion bound for omitted markers
Payment refusal for invoices with records above 4 billion retained in following commit
Evidence from the diff
Commit 5747866a6 narrowed EXPERIMENTAL_INVOICE_TYPES from 3_000_000_000.. to 3_000_000_000..4_000_000_000. Bolt12Invoice parsing is reused by HTLCSource::OutboundRoute’s bolt12_invoice field, which ChannelMonitor::read deserializes for holder-commitment HTLCs. Consequently, a monitor written by LDK 0.2 for a channel that paid an invoice with an odd TLV >= 4_000_000_000 would fail to load with DecodeError::InvalidValue, and read_channel_monitors aborts on the first unreadable monitor. The fix changes EXPERIMENTAL_INVOICE_TYPES to a RangeFrom (3_000_000_000..), preserving backward deserialization, and introduces EXPERIMENTAL_INVOICE_TYPES_END (4_000_000_000) only for payer-proof omitted-marker validation and the subsequent payment-refusal logic. Tests are added for Bolt12Invoice and StaticInvoice parsing of records above the experimental range.
Changed components
lightning/src/offers/invoice.rslightning/src/offers/payer_proof.rslightning/src/offers/static_invoice.rslightning/src/offers/test_utils.rsChannelMonitor deserialization (HTLCSource::OutboundRoute bolt12_invoice)read_channel_monitorsInspect captured patch +133 / −8
### lightning/src/offers/invoice.rs
@@ -1577,8 +1577,18 @@ tlv_stream!(InvoiceTlvStream, InvoiceTlvStreamRef<'a>, INVOICE_TYPES, {
(236, held_htlc_available_paths: (Vec<BlindedMessagePath>, WithoutLength)),
});
-/// Valid type range for experimental invoice TLV records.
-pub(super) const EXPERIMENTAL_INVOICE_TYPES: core::ops::Range<u64> = 3_000_000_000..4_000_000_000;
+/// Type range parsed as experimental invoice TLV records.
+///
+/// The spec does not bound TLV record types, so this is open-ended, as LDK 0.2 and earlier read
+/// it. In particular, invoices persisted by those versions may contain records at or above
+/// [`EXPERIMENTAL_INVOICE_TYPES_END`] and must remain deserializable.
+pub(super) const EXPERIMENTAL_INVOICE_TYPES: core::ops::RangeFrom<u64> = 3_000_000_000..;
+
+/// 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.
+pub(super) const EXPERIMENTAL_INVOICE_TYPES_END: u64 = 4_000_000_000;
#[cfg(not(test))]
tlv_stream!(
@@ -1927,7 +1937,7 @@ mod tests {
use crate::prelude::*;
use crate::types::features::{Bolt12InvoiceFeatures, InvoiceRequestFeatures, OfferFeatures};
use crate::types::string::PrintableString;
- use crate::util::ser::{BigSize, Iterable, Writeable};
+ use crate::util::ser::{BigSize, Iterable, LengthReadable, Writeable};
#[cfg(not(c_bindings))]
use {crate::offers::offer::OfferBuilder, crate::offers::refund::RefundBuilder};
#[cfg(c_bindings)]
@@ -3590,6 +3600,26 @@ mod tests {
}
}
+ #[test]
+ 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 mut encoded_invoice = Vec::new();
+ invoice.write(&mut encoded_invoice).unwrap();
+
+ match Bolt12Invoice::try_from(encoded_invoice.clone()) {
+ Ok(invoice) => assert_eq!(invoice.bytes, encoded_invoice),
+ Err(e) => panic!("error parsing invoice: {:?}", e),
+ }
+
+ match Bolt12Invoice::read_from_fixed_length_buffer(&mut &encoded_invoice[..]) {
+ Ok(invoice) => assert_eq!(invoice.bytes, encoded_invoice),
+ Err(e) => panic!("error reading invoice: {:?}", e),
+ }
+ }
+
#[test]
fn serializes_unsigned_invoice_with_experimental_tlv_records() {
let expanded_key = ExpandedKey::new([42; 32]);
### 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, 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::{
@@ -953,7 +953,7 @@ fn validate_omitted_markers_for_parsing(
for &marker in omitted_markers {
if SIGNATURE_TYPES.contains(&marker)
|| PAYER_PROOF_DATA_TYPES.contains(&marker)
- || marker >= EXPERIMENTAL_INVOICE_TYPES.end
+ || marker >= EXPERIMENTAL_INVOICE_TYPES_END
{
return Err(DecodeError::InvalidValue);
}
### lightning/src/offers/static_invoice.rs
@@ -747,7 +747,7 @@ mod tests {
use crate::ln::msgs::DecodeError;
use crate::offers::invoice::{
ExperimentalInvoiceTlvStreamRef, InvoiceTlvStreamRef, EXPERIMENTAL_INVOICE_TYPES,
- INVOICE_TYPES,
+ EXPERIMENTAL_INVOICE_TYPES_END, INVOICE_TYPES,
};
use crate::offers::merkle;
use crate::offers::merkle::{SignatureTlvStreamRef, TaggedHash, TlvStream};
@@ -762,7 +762,7 @@ mod tests {
};
use crate::offers::test_utils::*;
use crate::types::features::{Bolt12InvoiceFeatures, OfferFeatures};
- use crate::util::ser::{BigSize, Iterable, Writeable};
+ use crate::util::ser::{BigSize, Iterable, LengthReadable, Writeable};
use bitcoin::constants::ChainHash;
use bitcoin::secp256k1::{self, Secp256k1};
use bitcoin::Network;
@@ -1678,6 +1678,73 @@ mod tests {
}
}
+ fn static_invoice_with_record_above_experimental_range() -> StaticInvoice {
+ let node_id = recipient_pubkey();
+ let expanded_key = ExpandedKey::new([42; 32]);
+ let entropy = FixedEntropy {};
+ let nonce = Nonce::from_entropy_source(&entropy);
+ let secp_ctx = Secp256k1::new();
+
+ let offer = OfferBuilder::deriving_signing_pubkey(node_id, &expanded_key, nonce, &secp_ctx)
+ .path(blinded_path())
+ .build()
+ .unwrap();
+
+ let (mut unsigned_invoice, keys) = StaticInvoiceBuilder::for_offer_using_derived_keys(
+ &offer,
+ payment_paths(),
+ vec![blinded_path()],
+ now(),
+ &expanded_key,
+ nonce,
+ &secp_ctx,
+ )
+ .unwrap()
+ .build()
+ .unwrap();
+
+ // The record is odd so it is unknown to the parser rather than indicating a required
+ // feature.
+ const UNKNOWN_ODD_TYPE: u64 = EXPERIMENTAL_INVOICE_TYPES_END + 1;
+ assert!(UNKNOWN_ODD_TYPE % 2 == 1);
+ let mut unknown_bytes = Vec::new();
+ BigSize(UNKNOWN_ODD_TYPE).write(&mut unknown_bytes).unwrap();
+ BigSize(32).write(&mut unknown_bytes).unwrap();
+ [42u8; 32].write(&mut unknown_bytes).unwrap();
+
+ unsigned_invoice.experimental_bytes.extend_from_slice(&unknown_bytes);
+
+ let tlv_stream = TlvStream::new(&unsigned_invoice.bytes)
+ .chain(TlvStream::new(&unsigned_invoice.experimental_bytes));
+ unsigned_invoice.tagged_hash = TaggedHash::from_tlv_stream(SIGNATURE_TAG, tlv_stream);
+
+ unsigned_invoice
+ .sign(|message: &UnsignedStaticInvoice| {
+ Ok(secp_ctx.sign_schnorr_no_aux_rand(message.as_ref().as_digest(), &keys))
+ })
+ .unwrap()
+ }
+
+ #[test]
+ 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 = static_invoice_with_record_above_experimental_range();
+
+ let mut encoded_invoice = Vec::new();
+ invoice.write(&mut encoded_invoice).unwrap();
+
+ match StaticInvoice::try_from(encoded_invoice.clone()) {
+ Ok(invoice) => assert_eq!(invoice.bytes, encoded_invoice),
+ Err(e) => panic!("error parsing invoice: {:?}", e),
+ }
+
+ match StaticInvoice::read_from_fixed_length_buffer(&mut &encoded_invoice[..]) {
+ Ok(invoice) => assert_eq!(invoice.bytes, encoded_invoice),
+ Err(e) => panic!("error reading invoice: {:?}", e),
+ }
+ }
+
#[test]
fn fails_parsing_invoice_with_out_of_range_tlv_records() {
let invoice = invoice();
### lightning/src/offers/test_utils.rs
@@ -17,11 +17,13 @@ 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_request::InvoiceRequest;
use crate::offers::merkle::TaggedHash;
use crate::sign::EntropySource;
use crate::types::features::BlindedHopFeatures;
use crate::types::payment::PaymentHash;
+use crate::util::ser::{BigSize, Writeable};
use core::time::Duration;
#[allow(unused_imports)]
@@ -184,3 +186,29 @@ pub(crate) fn dummy_invoice_request() -> InvoiceRequest {
.build_and_sign()
.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 {
+ let mut bytes = Vec::new();
+ dummy_invoice_request()
+ .respond_with_no_std(payment_paths(), payment_hash(), now())
+ .unwrap()
+ .build()
+ .unwrap()
+ .write(&mut bytes)
+ .unwrap();
+
+ // The record is odd so it is unknown to the parser rather than indicating a required feature.
+ const UNKNOWN_ODD_TYPE: u64 = EXPERIMENTAL_INVOICE_TYPES_END + 1;
+ assert!(UNKNOWN_ODD_TYPE % 2 == 1);
+ BigSize(UNKNOWN_ODD_TYPE).write(&mut bytes).unwrap();
+ BigSize(32).write(&mut bytes).unwrap();
+ [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()
+}Why this scored 64/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.