Treat offer_amount of 0 as equivalent to None by vincenzopalazzo · Pull Request #4324 · lightningdevkit/rust-lightning

vincenzopalazzo · 2026-01-20T13:57:06Z

Summary

Normalize offer_amount=0 to None in both the builder and parser for consistent internal representation
An amount of zero has no practical meaning (you cannot pay zero), so treating it as "no amount specified" simplifies handling
When parsing offers with amount=0 (with or without currency), the amount is normalized to None

Motivation

Per BOLT12, if no specific minimum amount is required, the offer_amount field should be omitted rather than set to zero. This change ensures offers with amount=0 are handled gracefully rather than causing unexpected behavior downstream.

Spec clarification pending: lightning/bolts#1314

Test plan

Builder test: amount_msats(0) results in amount() == None and as_tlv_stream().0.amount == None
Roundtrip test: serialize and re-parse maintains None state
Parser tests: TLV with amount=0 (with and without currency) results in amount() == None
Invoice request tests: offer with amount=0 requires invoice request to provide amount

ldk-reviews-bot · 2026-01-20T13:57:09Z

👋 Thanks for assigning @jkczyz as a reviewer!
I'll wait for their review and will help manage the review process.
Once they submit their review, I'll check if a second reviewer would be helpful.

codecov · 2026-01-20T15:24:57Z

Codecov Report

❌ Patch coverage is 92.30769% with 4 lines in your changes missing coverage. Please review.
✅ Project coverage is 86.64%. Comparing base (09b3bef) to head (14b7f66).
⚠️ Report is 313 commits behind head on main.

Files with missing lines	Patch %	Lines
lightning/src/offers/offer.rs	90.62%	3 Missing ⚠️
lightning/src/offers/invoice_request.rs	95.00%	1 Missing ⚠️

Additional details and impacted files

@@            Coverage Diff             @@
##             main    #4324      +/-   ##
==========================================
+ Coverage   86.61%   86.64%   +0.02%     
==========================================
  Files         158      158              
  Lines      102730   102782      +52     
  Branches   102730   102782      +52     
==========================================
+ Hits        88984    89052      +68     
+ Misses      11328    11315      -13     
+ Partials     2418     2415       -3

Flag	Coverage Δ
fuzzing	`37.23% <40.00%> (+1.03%)`	⬆️
tests	`85.92% <92.30%> (+0.01%)`	⬆️

Flags with carried forward coverage won't be shown. Click here to find out more.

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

jkczyz

Probably worth waiting on feedback from other implementations. Left some concerns of mine. I'd lean more towards disallowing explicit zero amounts.

jkczyz · 2026-01-20T15:19:45Z

 				return Err(Bolt12SemanticError::InvalidAmount);
 			},
+			// An amount of 0 is equivalent to not setting an amount, so default to None.
+			(None, Some(0)) => None,


Hmmm... I'd rather we not use the same representation for two different serializations. It may still work because when creating the InvoiceRequest we'll serialize using Offer::bytes. If we didn't use that, the issuer may fail to authenticate the offer when receiving an InvoiceRequest.

Fixed — this now returns Err(Bolt12SemanticError::InvalidAmount) instead of normalizing to None, so there is no representation mismatch between Offer::bytes and parsed OfferContents. Per the spec clarification (lightning/bolts#1316), readers MUST NOT respond to offers where offer_amount is zero.

jkczyz · 2026-01-20T17:18:42Z

+			// An amount of 0 with a currency is equivalent to not setting an amount.
+			(Some(_), Some(0)) => None,


This prevents the currency code check. Also, I don't think it's useful to drop information from the Offer even if we still retain it in Offer::bytes. At very least it would be surprising if viewing an Offer that is suppose to have a currency but LDK shows that it doesn't.

Good point — fixed. The (Some(_), Some(0)) case now returns Err(Bolt12SemanticError::InvalidAmount) instead of dropping the currency info. No information is discarded since we reject the offer outright.

jkczyz · 2026-01-20T17:24:30Z

+				// An amount of 0 is equivalent to not setting an amount, so default to None.
+				if amount_msats == 0 {
+					$self.offer.amount = None;
+				}


I'm somewhat unsure about this change. It could hide an error on the user's end. It might be better to fail in this case instead of allowing them to accept any amount.

Agreed — updated to return Err(Bolt12SemanticError::InvalidAmount) when amount_msats == 0. This aligns with the spec clarification in lightning/bolts#1316 which requires writers MUST set offer_amount greater than zero.

ldk-reviews-bot · 2026-01-20T17:28:28Z

👋 The first review has been submitted!

Do you think this PR is ready for a second reviewer? If so, click here to assign a second reviewer.

vincenzopalazzo · 2026-03-09T20:52:52Z

Rebased on main and reworked based on review feedback. The approach now rejects offer_amount=0 instead of normalizing to None, which aligns with:

@jkczyz's preference to disallow explicit zero amounts
The spec clarification in BOLT 12: clarify that offer_amount must be greater than zero lightning/bolts#1316:
- Writers MUST set offer_amount greater than zero when present
- Readers MUST NOT respond to offers where offer_amount is zero

Changes in the updated commit:

Builder: amount_msats(0) returns Err(Bolt12SemanticError::InvalidAmount)
Parser: (None, Some(0)) and (Some(_), Some(0)) both return InvalidAmount error
Tests: Updated to assert rejection instead of normalization

This resolves all three inline review concerns (no silent normalization, no representation mismatch, no dropped currency info).

Force push incoming once we agree on the direction.

Per the spec clarification in lightning/bolts#1316: - Writers MUST set offer_amount greater than zero when present - Readers MUST NOT respond to offers where offer_amount is zero Reject amount_msats(0) in the builder with InvalidAmount, and reject parsed offers with amount=0 (with or without currency) during TLV deserialization. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

ldk-reviews-bot · 2026-03-11T21:18:06Z

🔔 1st Reminder

Hey @jkczyz! This PR has been waiting for your review.
Please take a look when you have a chance. If you're unable to review, please let us know so we can find another reviewer.

ldk-reviews-bot · 2026-03-14T00:01:41Z

🔔 2nd Reminder

Hey @jkczyz! This PR has been waiting for your review.
Please take a look when you have a chance. If you're unable to review, please let us know so we can find another reviewer.

ldk-reviews-bot · 2026-03-16T00:02:49Z

🔔 3rd Reminder

Hey @jkczyz! This PR has been waiting for your review.
Please take a look when you have a chance. If you're unable to review, please let us know so we can find another reviewer.

TheBlueMatt

Alrighty.

TheBlueMatt · 2026-03-17T12:42:54Z

IMO for the 0.1 and 0.2 backports we should silently accept 0 amounts and convert to None instead of rejecting and changing the semantics of the API in a point release.

TheBlueMatt · 2026-03-17T12:54:26Z

Backported to 0.1 in #4487, 0.2 in #4488

jkczyz · 2026-03-17T16:12:23Z

 		let amount = match (currency, amount) {
 			(None, None) => None,
-			(None, Some(amount_msats)) if amount_msats > MAX_VALUE_MSAT => {
+			(None, Some(amount_msats)) if amount_msats == 0 || amount_msats > MAX_VALUE_MSAT => {


@TheBlueMatt We'll want to note in the changelog that we'll now reject any InvoiceRequest for offers created with 0 explicitly for the amount.

jkczyz · 2026-03-17T16:15:20Z

+		// An offer with amount_msats(0) must be rejected by the builder per BOLT 12.
+		match OfferBuilder::new(recipient_pubkey()).amount_msats(0).build() {
+			Ok(_) => panic!("expected error"),
+			Err(e) => assert_eq!(e, Bolt12SemanticError::InvalidAmount),
+		}


This is already tested in offer.rs. We really want to test that we can't parse an InvoiceRequest that has a Some(0) for the amount TLV. OfferBuilder::build_unchecked should help creating one.

jkczyz · 2026-03-17T16:17:53Z

+		// BOLT 12 test vectors: verify rejection of offers with amount=0 from their
+		// bech32 encoding (see bolt12/offers-test.json).
+		match "lno1pqqq5qqkyyp4he0fg7pqje62jmnq78cr0ashv4q06qql58tyd9rhp3t2wuyugtq".parse::<Offer>()
+		{
+			Ok(_) => panic!("expected error"),
+			Err(e) => assert_eq!(
+				e,
+				Bolt12ParseError::InvalidSemantics(Bolt12SemanticError::InvalidAmount)
+			),
+		}
+
+		match "lno1qcp4256ypqqq5qqkyyp4he0fg7pqje62jmnq78cr0ashv4q06qql58tyd9rhp3t2wuyugtq"
+			.parse::<Offer>()
+		{
+			Ok(_) => panic!("expected error"),
+			Err(e) => assert_eq!(
+				e,
+				Bolt12ParseError::InvalidSemantics(Bolt12SemanticError::InvalidAmount)
+			),
+		}
 	}


Could you move these to bolt12_tests?

v0.1.10 - Jun 18, 2026 - "Loupe de Loupe" API Updates =========== * `DefaultMessageRouter` will now always generate blinded message paths that provide no privacy (where our node is the introduction node) for nodes with public channels. This works around an issue which will appear for any nodes with LND peers that enable onion messaging - such peers will refuse to forward BOLT 12 messages from unknown third parties, which most BOLT 12 payers rely on today (#4647). * Explicit `amount_msats` of 0 is rejected in BOLT 12 `Offer`s; `OfferBuilder` now maps 0-amounts to an amount of `None` (#4324). Bug Fixes ========= * Async `ChannelMonitorUpdate` persistence operations which complete, but are not marked as complete in a persisted `ChannelManager` prior to restart, followed immediately by a block connection and then another restart could result in some channel operations hanging leading for force-closures (#4377). * If an MPP payment is claimed but `ChannelMonitorUpdate`s for some parts are still being completed asynchronously, further channel updates (e.g. forwarding another payment) are pending and the node restarts, the channel could have become stuck (#4520). * The presence of unconfirmed transactions actually no longer causes `ElectrumSyncClient` to spuriously fail to sync (#4590). * `FilesystemStore::list_all_keys` will no longer fail if there are stale intermediate files lying around from a previous unclean shutdown (#4618). * When forwarding an HTLC while in a blinded path with proportional fees over 200%, LDK will no longer spuriously allow a forward that pays us 1 msat too little in fees (#4697). * Fixed a rare case where a channel could get stuck on reconnect when using both async `ChannelMonitorUpdate` persistence and async signing (#4684). * `Event::PaymentSent::fee_paid_msat` is no longer `None` in cases where `ChannelManager::abandon_payment` was called before the payment ultimately completes anyway (#4651). * Syncing a `ChainMonitor` using the `Confirm` trait will no longer write some full `ChannelMonitor`s to disk several times per block (#4544). * `OMDomainResolver` now correctly accounts for failed queries when rate limiting, ensuring we continue to respond to queries after failures (#4591). * Calling `ChannelManager::send_payment_with_route` without a `route_params` and with an invalid `Route` will no longer panic (#4707). * `lightning-custom-message`'s handling of `peer_connected` events now ensures that sub-handlers will see a `peer_disconnected` event if a different sub-handler refused the connection by `Err`ing `peer_connected` (#4595). * Incomplete MPP keysend payments will no longer see their HTLCs held until expiry (#4558). * `InvoiceRequestBuilder` will no longer accept a `quantity` of `0` for a BOLT 12 `Offer`, allowing any quantity up to a bound (#4667). * `lightning-custom-message` handlers that return `Ok(None)` when asked to deserialize a message in their defined range no longer cause panics (#4709). * Several spurious debug assertions were fixed (#4537, #4618). Security ======== 0.1.10 fixes a sanitization issue and several denial-of-service vulnerabilities. * `Bolt11Invoice::recover_payee_pub_key` no longer panics if called on an invoice which set an explicit public key, rather than relying on public key recovery. This method is called from `payment_parameters_from_invoice` and `payment_parameters_from_variable_amount_invoice` (#4717). * Maliciously-crafted unpayable invoices which have overflowing feerates will no longer cause an `unwrap` failure panic (#4716). * `possiblyrandom` did not properly generate random data except when it was explicitly configured to. By default this means LDK is vulnerable to various HashDoS attacks (#4719). * `OMNameResolver` will no longer panic when looking up payment instructions which include unicode characters at the start of a TXT record (#4718). * `PrintableString` did not properly sanitize unicode format characters, allowing an attacker to corrupt the rendering of logs or UI (#4593, #4605). * RGS data is now limited in how large of a graph it is able to cause a client to store in memory. Note that RGS data is still considered a DoS vector in general and you should only use semi-trusted RGS data (#4713). * Counterparty-provided strings in failure messages are no longer logged in full, reducing the ability of such a counterparty to spam our logs (#4714). * Reading a corrupted `ChannelManager` or `ProbabilisticScorer` can no longer cause us to allocate large amounts of memory (#4712). Thanks to Project Loupe for reporting most of the issues fixed in this release.

v0.2.3 - Jun 18, 2026 - "Through the Loupe" API Updates =========== * `DefaultMessageRouter` will now always generate blinded message paths that provide no privacy (where our node is the introduction node) for nodes with public channels. This works around an issue which will appear for any nodes with LND peers that enable onion messaging - such peers will refuse to forward BOLT 12 messages from unknown third parties, which most BOLT 12 payers rely on today (lightningdevkit#4647). * Explicit `amount_msats` of 0 is rejected in BOLT 12 `Offer`s; `OfferBuilder` now maps 0-amounts to an amount of `None` (lightningdevkit#4324). Bug Fixes ========= * `Features::supports_zero_conf` no longer clears the `ZeroConf` features and `Features::requires_zero_conf` now correctly reports required, rather than supported, status (lightningdevkit#4517). * If an MPP payment is claimed but `ChannelMonitorUpdate`s for some parts are still being completed asynchronously, further channel updates (e.g. forwarding another payment) are pending and the node restarts, the channel could have become stuck (lightningdevkit#4520). * The presence of unconfirmed transactions actually no longer causes `ElectrumSyncClient` to spuriously fail to sync (lightningdevkit#4590). * LSPS1, LSPS2, and LSPS5 persistence will no longer get stuck and refuse to persist again after a single failure from the KVStore (lightningdevkit#4597, lightningdevkit#4282). * Dropping the future returned by `OutputSweeper::regenerate_and_broadcast_spend_if_necessary` no longer results in future calls to the same method being spuriously ignored (lightningdevkit#4598). * Used async-receive offers are no longer refreshed on every timer tick once their refresh time is reached (lightningdevkit#4672). * `FilesystemStore::list_all_keys` will no longer fail if there are stale intermediate files lying around from a previous unclean shutdown (lightningdevkit#4618). * When forwarding an HTLC while in a blinded path with proportional fees over 200%, LDK will no longer spuriously allow a forward that pays us 1 msat too little in fees (lightningdevkit#4697). * Fixed a rare case where a channel could get stuck on reconnect when using both async `ChannelMonitorUpdate` persistence and async signing (lightningdevkit#4684). * If we had exactly zero balance in a zero-fee-commitment channel, the counterparty was able to splice all of their balance out, violating the reserve requirements they'd otherwise be forced to keep (lightningdevkit#4580). * Providing an `Event::HTLCIntercepted` to the `LSPS2ServiceHandler` twice no longer results in spuriously opening a channel early (lightningdevkit#4656). * `Event::PaymentSent::fee_paid_msat` is no longer `None` in cases where `ChannelManager::abandon_payment` was called before the payment ultimately completes anyway (lightningdevkit#4651). * `AnchorDescriptor::previous_utxo` now provides the correct `script_pubkey` for non-zero-commitment-fee anchor channels (lightningdevkit#4669). * Syncing a `ChainMonitor` using the `Confirm` trait will no longer write some full `ChannelMonitor`s to disk several times per block (lightningdevkit#4544). * `OMDomainResolver` now correctly accounts for failed queries when rate limiting, ensuring we continue to respond to queries after failures (lightningdevkit#4591). * Calling `ChannelManager::send_payment_with_route` without a `route_params` and with an invalid `Route` will no longer panic (lightningdevkit#4707). * `LSPS2ServiceHandler::channel_open_failed` now correctly fails intercepted HTLCs rather than allowing them to fail just before expiry (lightningdevkit#4677). * `StaticInvoice::is_offer_expired` was corrected to check offer, rather than static invoice, expiry (lightningdevkit#4594). * `lightning-custom-message`'s handling of `peer_connected` events now ensures that sub-handlers will see a `peer_disconnected` event if a different sub-handler refused the connection by `Err`ing `peer_connected` (lightningdevkit#4595). * Replay protection for LSPS5 signatures now detects replays which are only different in the encoded signature's case (lightningdevkit#4701). * When `lightning-liquidity` is configured in the background processor, there is no longer a stream of `Persisting LiquidityManager...` log spam (lightningdevkit#4246). * Incomplete MPP keysend payments will no longer see their HTLCs held until expiry (lightningdevkit#4558). * `InvoiceRequestBuilder` will no longer accept a `quantity` of `0` for a BOLT 12 `Offer`, allowing any quantity up to a bound (lightningdevkit#4667). * `lightning-custom-message` handlers that return `Ok(None)` when asked to deserialize a message in their defined range no longer cause panics (lightningdevkit#4709). * Several spurious debug assertions were fixed (lightningdevkit#4537, lightningdevkit#4618, lightningdevkit#4026) Security ======== 0.2.3 fixes several underestimates of the anchor reserves required to ensure we can reliably close channels, several denial-of-service vulnerabilities and a sanitization issue. * `Bolt11Invoice::recover_payee_pub_key` no longer panics if called on an invoice which set an explicit public key, rather than relying on public key recovery. Note that this method is called from `PaymentParameters::from_bolt11_invoice` (lightningdevkit#4717). * Maliciously-crafted unpayable invoices which have overflowing feerates will no longer cause an `unwrap` failure panic (lightningdevkit#4716). * Parsing an `LSPSDateTime` which is before 1970 no longer panics. This is reachable when parsing messages from counterparties (lightningdevkit#4715). * `possiblyrandom` did not properly generate random data except when it was explicitly configured to. By default this means LDK is vulnerable to various HashDoS attacks (lightningdevkit#4719). * `OMNameResolver` will no longer panic when looking up payment instructions which include unicode characters at the start of a TXT record (lightningdevkit#4718). * When using the `anchor_channel_reserves` module to calculate reserves required to pay for fees when closing anchor channels, zero-fee-commitment channels were not considered. This could allow a counterparty to open many channels, leaving us unable to properly force-close (lightningdevkit#4592). * The `anchor_channel_reserves` module overestimated the value of `Utxo`s in the wallet by ignoring the `TxIn` cost to spend them (lightningdevkit#4670). * `PrintableString` did not properly sanitize unicode format characters, allowing an attacker to corrupt the rendering of logs or UI (lightningdevkit#4593, lightningdevkit#4605). * RGS data is now limited in how large of a graph it is able to cause a client to store in memory. Note that RGS data is still considered a DoS vector in general and you should only use semi-trusted RGS data (lightningdevkit#4713). * Counterparty-provided strings in failure messages are no longer logged in full, reducing the ability of such a counterparty to spam our logs (lightningdevkit#4714). * Reading a corrupted `ChannelManager` or `ProbabilisticScorer` can no longer cause us to allocate large amounts of memory (lightningdevkit#4712). Thanks to Project Loupe for reporting most of the issues fixed in this release. Conflicts resolved in: * lightning/src/chain/channelmonitor.rs * lightning/src/events/mod.rs * lightning/src/ln/channelmanager.rs * lightning/src/ln/mod.rs * lightning/src/ln/offers_tests.rs * lightning/src/ln/onion_utils.rs

ldk-reviews-bot requested a review from wpaulino January 20, 2026 14:08

jkczyz requested review from jkczyz and removed request for wpaulino January 20, 2026 15:16

jkczyz reviewed Jan 20, 2026

View reviewed changes

TheBlueMatt added backport 0.1 backport 0.2 labels Feb 27, 2026

TheBlueMatt added this to the 0.3 milestone Feb 27, 2026

TheBlueMatt added the blocked on spec label Feb 27, 2026

vincenzopalazzo force-pushed the macros/bolt12-offer-amount-0 branch 2 times, most recently from f329173 to 61d3509 Compare March 9, 2026 21:04

vincenzopalazzo force-pushed the macros/bolt12-offer-amount-0 branch from 61d3509 to a06c446 Compare March 9, 2026 21:08

vincenzopalazzo requested a review from jkczyz March 9, 2026 21:17

TheBlueMatt approved these changes Mar 17, 2026

View reviewed changes

TheBlueMatt merged commit 8b1dc05 into lightningdevkit:main Mar 17, 2026
18 of 20 checks passed

vincenzopalazzo deleted the macros/bolt12-offer-amount-0 branch March 17, 2026 08:41

This was referenced Mar 17, 2026

[0.1] Reject offer_amount of 0 as invalid per BOLT 12 #4487

Merged

[0.2] Reject offer_amount of 0 as invalid per BOLT 12 #4488

Merged

TheBlueMatt removed blocked on spec backport 0.1 backport 0.2 labels Mar 17, 2026

vincenzopalazzo mentioned this pull request Mar 17, 2026

fix: reject offers with offer_amount=0 per BOLT 12 lndk-org/lndk#253

Merged

3 tasks

jkczyz reviewed Mar 17, 2026

View reviewed changes

bolty-from-atl-bitlab Bot mentioned this pull request Mar 21, 2026

Bitcoin Socratic Seminar #51 - Topic Suggestions atlantabitdevs/atlbit.dev#149

Closed

		// An amount of 0 with a currency is equivalent to not setting an amount.
		(Some(_), Some(0)) => None,

Uh oh!

Conversation

vincenzopalazzo commented Jan 20, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Summary

Motivation

Test plan

Uh oh!

ldk-reviews-bot commented Jan 20, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

codecov Bot commented Jan 20, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Codecov Report

Uh oh!

jkczyz left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

ldk-reviews-bot commented Jan 20, 2026

Uh oh!

vincenzopalazzo commented Mar 9, 2026

Uh oh!

ldk-reviews-bot commented Mar 11, 2026

Uh oh!

ldk-reviews-bot commented Mar 14, 2026

Uh oh!

ldk-reviews-bot commented Mar 16, 2026

Uh oh!

TheBlueMatt left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

TheBlueMatt commented Mar 17, 2026

Uh oh!

TheBlueMatt commented Mar 17, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

vincenzopalazzo commented Jan 20, 2026 •

edited

Loading

ldk-reviews-bot commented Jan 20, 2026 •

edited

Loading

codecov Bot commented Jan 20, 2026 •

edited

Loading

TheBlueMatt commented Mar 17, 2026 •

edited

Loading