bolt12: add string-codec wrappers and fuzz harnesses by bitromortac · Pull Request #11146 · lightningnetwork/lnd

bitromortac · 2026-08-31T13:37:12Z

Based on #11061, part of #10736.

Adds Decode/EncodeOfferString, Decode/EncodeInvoiceRequestString, and Decode/EncodeInvoiceString, composing bech32, the per-message TLV codec, and the spec reader gates into one call as the package's consumer entry point. Gates run against Bolt12Features, defined here. Wire-form encodes require and verify a populated signature, while pre-sign Encode stays permitted on (*X).Encode for Merkle-root computation.

We add a ValidateInvoiceForPayment method that is a validator that should be used to validate a received invoice against a sent invoice request.

Also adds fuzz harnesses for the codec decoders and wires bolt12 into make fuzz. Byte-level targets pin no-panic decode and byte-identical round-trips, string-level targets pin no-panic through the reader gates, and two more pin the bech32 bijection and Merkle-root determinism. Seeds come from the spec test vectors.

github-actions · 2026-08-31T13:40:13Z

🟠 PR Severity: HIGH

gh pr view | 20 files | 2880 lines changed

🟡 Medium (10 files, bumped to HIGH)

bolt12/doc.go - package doc update for new BOLT12 package
bolt12/invoice.go - BOLT12 invoice encode/decode logic
bolt12/invoice_request.go - BOLT12 invoice-request encode/decode logic
bolt12/merkle.go - new Merkle-root computation for BOLT12 messages
bolt12/offer.go - BOLT12 offer encode/decode logic
bolt12/signature.go - new BIP-340 signature creation/verification for BOLT12
bolt12/subtypes.go - BOLT12 TLV subtype definitions
bolt12/validate.go - BOLT12 message validation gates/features
docs/release-notes/release-notes-0.22.0.md - release notes
make/fuzz_flags.mk - wires bolt12 into fuzz build

🟢 Low (10 files, tests/fuzz/vectors, excluded from bump calculation)

bolt12/decode_test.go, bolt12/fuzz_test.go, bolt12/helpers_test.go, bolt12/invoice_request_test.go, bolt12/invoice_test.go, bolt12/merkle_test.go, bolt12/offer_test.go, bolt12/signature_test.go, bolt12/validate_test.go, bolt12/test-vectors/signature-test.json

Analysis

The bolt12/* package isn't explicitly listed in the severity tiers, so it was treated as "other Go files" (MEDIUM baseline). However, non-test/non-generated changes total ~639 lines across 10 files (new merkle.go and signature.go implement Merkle-root computation and BIP-340 signature creation/verification for BOLT12 offers/invoices — cryptographic and consensus-relevant logic), exceeding the 500-line bump threshold. Severity is therefore bumped one level to HIGH. This package underlies BOLT12 wire-form encode/decode and signature verification, so correctness here has security implications similar to lnwire.

_{To override, add a severity-override-{critical,high,medium,low} label.}

ViktorT-11

Did a first pass of this PR, and in general I think this looks great. I don't have that much useful feedback to provide, and think this should be pretty much ready to go once its dependant PR has been merged.

Potentially the fuzzing commit could be broken out into a separate PR as well.

ViktorT-11 · 2026-09-04T21:48:41Z

+	// The gap this closes: a validly Alice-signed invoice passes the
+	// reader, so only validateInvoiceNodeID separates it from a genuine
+	// one.
+	inv := validInvoice(t)
+	inv.InvoiceNodeID = tlv.SomeRecordT(
+		tlv.NewPrimitiveRecord[tlv.TlvType176](alicePub),
+	)
+	sig, err := SignInvoice(inv, alicePriv)
 	require.NoError(t, err)
+	inv.Signature = tlv.SomeRecordT(
+		tlv.NewPrimitiveRecord[tlv.TlvType240](sig),
+	)

-	ir.InvreqPayerID = tlv.SomeRecordT(
-		tlv.NewPrimitiveRecord[tlv.TlvType88](privKey.PubKey()),
+	require.NoError(t, ValidateInvoiceRead(
+		inv, bitcoinMainnetGenesisHash, InvoiceFeatureCatalogues{},
+	))
+	require.ErrorIs(
+		t, validateInvoiceNodeID(inv, bobPub),
+		ErrInvoicePathNodeIDMismatch,


I think this case here is better suited for the TestValidateInvoiceForPayment test. However, as this already covered in that test to some extent, it's IMO more confusing to include it here than to just remove this part from the TestValidateInvoiceNodeID test.

I shifted it into TestValidateInvoiceForPayment

ViktorT-11 · 2026-09-04T21:51:42Z

+// representation (lni1...). The spec reader gates (chain, features, signature)
+// are folded in via ValidateInvoiceRead, and the expiry gate is enforced via
+// ValidateInvoiceExpiry.
+func DecodeInvoiceString(s string, now time.Time,


Building on top of the commit prior to this one: Could it potentially also be useful to also export a "DecodeInvoiceStringForPayment" function that decodes an invoice string, but which additionally also takes an invoice request string param, and then calls the ValidateInvoiceForPayment function?

Given that this exported function will be vulnerable to the issue described in the previous commit, in case it's the response from an invoice request.

I would postpone this until we have specific call sites. This helper is only intended for invoices that have been received out of band (which may not have an invoice request?). The usual bolt12 branch only receives an invoice embedded in an onion message in tlv-byte form, which then is decoded and validated via ValidateInvoiceForPayment, which could be called after this. But I see the problem that this could be forgotten.

Gotcha :)! Yeah I think what makes it harder for me to determine what's useful and not is that at the state of this PR the ValidateInvoiceForPayment function is never used outside of tests :).

GeorgeTsagk

The PR description does not mention the ValidateInvoiceForPayment commit. Worth adding a line since it is the new exported payer entry point.

GeorgeTsagk · 2026-09-07T11:45:31Z

+	return VerifyInvoice(inv)
+}
+
+// ValidateInvoiceForPayment runs the full set of payer-side invoice checks in


This runs everything except the expiry gate, so the full set claim is off. ValidateInvoiceRead skips expiry by design and only DecodeInvoiceString folds ValidateInvoiceExpiry in. In the main payment flow invoices arrive as raw TLV over onion messages, not as lni strings, so a caller trusting this composite never hits the expiry MUST and can pay an expired invoice. Same argument as for the path binding: take a now time.Time and fold ValidateInvoiceExpiry in so the caller cannot forget it.

Right, good call, added that.

GeorgeTsagk · 2026-09-07T11:45:31Z

+		return nil
+	}
+
+	return validateInvoiceNodeID(inv, finalBlindedNodeID)


Doc suggestion only, behavior is fine. An offerless request lands here too, where the spec says MAY reject if invoice_node_id cannot be confirmed out-of-band. Rejecting fail-closed is stricter than the spec and that is good, but the doc and param name only speak of blinded paths. Worth a sentence that an offerless caller passes the node id it confirmed out-of-band.

That's true, I reworded the parameter to be a bit more neutral and updated the function's docstring to note what one should pass in.

github-actions · 2026-09-10T10:44:26Z

⚠️ Severity changed: HIGH → MEDIUM (files changed since last classification)

🟡 PR Severity: MEDIUM

gh pr view | 13 files | 1225 lines changed

🟡 Medium (5 files)

bolt12/doc.go - package doc update, not a categorized package
bolt12/invoice.go - BOLT12 invoice encode/decode logic (uncategorized package, treated as other Go file)
bolt12/invoice_request.go - BOLT12 invoice-request encode/decode logic
bolt12/offer.go - BOLT12 offer encode/decode logic
bolt12/validate.go - BOLT12 message validation gates/features

🟢 Low (8 files)

docs/release-notes/release-notes-0.22.0.md - release notes
make/fuzz_flags.mk - build config for fuzz targets
bolt12/fuzz_test.go, bolt12/helpers_test.go, bolt12/invoice_request_test.go, bolt12/invoice_test.go, bolt12/offer_test.go, bolt12/validate_test.go - test-only changes

Analysis

The bolt12/* package is not explicitly listed in any severity tier, so it falls back to "other Go files not categorized above" (MEDIUM baseline). Excluding test files, docs, and build config, the non-test Go changes total ~248 lines across 5 files (doc.go, invoice.go, invoice_request.go, offer.go, validate.go) — well under the 20-file / 500-line bump thresholds, and no critical packages are touched. This PR no longer includes the merkle.go and signature.go files (Merkle-root computation and BIP-340 signature logic) that drove the prior HIGH classification, so severity drops back to MEDIUM.

_{To override, add a severity-override-{critical,high,medium,low} label.}

GeorgeTsagk

LGTM

ViktorT-11

Nice, LGTM 🔥

ViktorT-11 · 2026-09-18T10:18:06Z

+// cannot forget any of them. expectedNodeID is only consulted when
+// offer_issuer_id is absent. Otherwise the expected signer is derived from
+// the request.


Nit: The doc mentions: "expectedNodeID is only consulted when offer_issuer_id is absent.", but this function then tests that it's still consulted after this comment in the test:

// The check is unconditional, so a wrong expectation is caught even // though offer_issuer_id is present and the readers already bound it.

So I think this is a stale comment which should be removed?

Improved the comments around this.

ViktorT-11 · 2026-09-18T10:21:40Z

+// cannot forget any of them. expectedNodeID is only consulted when
+// offer_issuer_id is absent. Otherwise the expected signer is derived from
+// the request.
+func TestValidateInvoiceForPayment(t *testing.T) {


nit: Could also include test coverage for when there's a missmatch in the amount between the invoice and the invoice request, hence failing the ValidateInvoiceAgainstRequest part of the ValidateInvoiceForPayment function.

Good idea, addressed!

ViktorT-11 · 2026-09-18T10:23:32Z

+// representation (lni1...). The spec reader gates (chain, features, signature)
+// are folded in via ValidateInvoiceRead, and the expiry gate is enforced via
+// ValidateInvoiceExpiry.
+func DecodeInvoiceString(s string, now time.Time,


Gotcha :)! Yeah I think what makes it harder for me to determine what's useful and not is that at the state of this PR the ValidateInvoiceForPayment function is never used outside of tests :).

Bundle the payer-side invoice checks into one call so the sender flow cannot forget any of them: the reader gates, the expiry gate, the byte-for-byte mirror match against the originating request, and the binding of invoice_node_id to the node the payer expected to answer.

Decode/EncodeOfferString, Decode/EncodeInvoiceRequestString, and Decode/EncodeInvoiceString compose bech32, the per-message TLV codec, and the previously-landed validators into a single reader/writer API that consumers should use. Reader gates run against Bolt12Features, the package's known feature-bit set, defined in this commit. The string codecs that emit a wire-form message also gate Signature validity, since pre-sign Encode (used to compute the Merkle root) is permitted on (*X).Encode but not at the bech32 boundary.

The bolt12 codec parses bytes that arrive untrusted inside onion messages, so every decoder gets a property-based check that no input pattern drives a panic or breaks the encode/decode bijection. A further harness asserts merkleRoot is a pure function of its record set, since non-determinism there would silently break signature reproducibility. Wiring bolt12 into FUZZPKG makes 'make fuzz' exercise the package alongside the existing entries.

Add changes for the string-codec wrappers, the combined payment validator, and the fuzz harnesses in bolt12.

bitromortac mentioned this pull request Aug 31, 2026

[epic]: BOLT 12 Implementation Roadmap #10736

Open

6 tasks

github-actions Bot added the severity-high Requires knowledgeable engineer review label Aug 31, 2026

ziggie1984 assigned bitromortac Sep 1, 2026

ziggie1984 added this to lnd v0.22 Sep 1, 2026

github-project-automation Bot moved this to Backlog in lnd v0.22 Sep 1, 2026

ziggie1984 added this to the v0.22.0 milestone Sep 1, 2026

bitromortac force-pushed the 2604-bolt12-1g branch from 30f2828 to 90fc244 Compare September 2, 2026 15:29

bitromortac requested review from GeorgeTsagk and ViktorT-11 September 2, 2026 15:30

ViktorT-11 reviewed Sep 4, 2026

View reviewed changes

GeorgeTsagk reviewed Sep 7, 2026

View reviewed changes

bitromortac force-pushed the 2604-bolt12-1g branch from 90fc244 to b359c2b Compare September 10, 2026 10:34

github-actions Bot added severity-medium Focused review required and removed severity-high Requires knowledgeable engineer review labels Sep 10, 2026

bitromortac requested review from GeorgeTsagk and ViktorT-11 September 10, 2026 11:32

bitromortac mentioned this pull request Sep 11, 2026

bolt12: finalize the codec package #11191

Merged

GeorgeTsagk approved these changes Sep 14, 2026

View reviewed changes

ViktorT-11 approved these changes Sep 18, 2026

View reviewed changes

bitromortac added 4 commits September 21, 2026 13:49

docs: update release notes

a80db77

Add changes for the string-codec wrappers, the combined payment validator, and the fuzz harnesses in bolt12.

bitromortac force-pushed the 2604-bolt12-1g branch from b359c2b to a80db77 Compare September 21, 2026 13:52

yyforyongyu merged commit f02cf4a into lightningnetwork:master Sep 21, 2026
40 of 46 checks passed

github-project-automation Bot moved this from Backlog to Done in lnd v0.22 Sep 21, 2026

Conversation

bitromortac commented Aug 31, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

github-actions Bot commented Aug 31, 2026

🟠 PR Severity: HIGH

Analysis

Uh oh!

ViktorT-11 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!

GeorgeTsagk 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!

github-actions Bot commented Sep 10, 2026

🟡 PR Severity: MEDIUM

Analysis

Uh oh!

GeorgeTsagk left a comment

Choose a reason for hiding this comment

Uh oh!

ViktorT-11 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!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

5 participants

bitromortac commented Aug 31, 2026 •

edited

Loading