bolt12: add Bech32 string codec and spec test vectors by bitromortac · Pull Request #11001 · lightningnetwork/lnd

bitromortac · 2026-07-28T13:14:10Z

Part of #10736.

Adds checksumless Bech32 string encoding and decoding (Encode, Decode) for BOLT 12 objects (lno, lnr, lni), including + continuation line stripping, case normalization, and input length bounding before allocation.

Additionally, this PR vendors upstream lightning/bolts test vectors (offers-test.json, format-string-test.json) to verify Bech32 parsing, TLV decoding, and semantic validation with exact field-level hex and length assertions across all test cases.

bitromortac · 2026-07-31T10:00:39Z

Ready for review @vctt94 @Abdulkbk (if you have time for it as always 🙏).

TechLateef · 2026-07-31T15:51:48Z

+		return "", nil, fmt.Errorf("bolt12: %w", ErrEmptyString)
+	}
+
+	// The characters must be either all lowercase or all uppercase.


nit: Since && short-circuits, we could avoid allocating the uppercase copy unless it's actually needed by doing something like:

lower := strings.ToLower(cleaned) if cleaned != lower && cleaned != strings.ToUpper(cleaned) { return "", nil, fmt.Errorf("bolt12: %w", ErrMixedCase) } cleaned = lower

This preserves the existing behavior while avoiding the extra ToUpper allocation when the input is already lowercase.

Nice, strings.ToUpper now sits inside the condition.

TechLateef · 2026-07-31T16:00:26Z

+	hrp := cleaned[:one]
+	if _, ok := validHRPs[hrp]; !ok {
+		return "", nil, fmt.Errorf(
+			"bolt12: %w %q (want lno/lnr/lni)",


Nit: The accepted HRPs are already defined in validHRPs, but the error message duplicates them as string literals. It might be worth deriving the list from validHRPs so there's a single source of truth if the accepted HRPs ever change.

Have changed it such that we reuse the definition.

ViktorT-11

Really awesome progress on this 🔥🎉!

Just posting some initial findings when crosschecking with the spec & the other Lightning implementations 🚀.

ViktorT-11 · 2026-08-03T16:12:10Z

+	// ~210,000 characters. A cap of 300,000 accommodates all valid payloads
+	// while preventing hostile inputs from forcing excessive allocations
+	// during decoding.
+	maxBolt12StringLen = 300_000


I'm not sure if we should include this cap, and if we do, I think we may need to raise the cap. BOLT12 doesn't specify any strict cap that should be enforced, and I double checked (I checked through LLM) in Eclair, Core Lightning & LDK, and I think none of those repos include such a cap.

Additionally, if these fields are set to the max:

offer_metadata: 65,535 bytes offer_description: 65,535 valid UTF-8 bytes offer_issuer: 65,535 valid UTF-8 bytes

The Encode function will accept that request and produce a string longer than 300k characters, while the Decode function will error with ErrStringTooLong.

So if we keep it, we should at least cap both Encode & Decode at the same length.

Thank you, I wanted to be conservative here, but we can discuss if it makes sense to remove the limit. I have increased the limit and added some explanation to the constant's docstring.

ViktorT-11 · 2026-08-03T16:47:32Z

+		if i == 0 || !isBech32Char(s[i-1]) {
+			return "", fmt.Errorf(
+				"bolt12: %w: '+' must follow a bech32 "+
+					"character",
+				ErrInvalidContinuation,
+			)
+		}
+
+		// Skip '+' and any following whitespace.
+		j := i + 1
+		for j < len(s) && isWhitespace(s[j]) {
+			j++
+		}
+		if j >= len(s) || !isBech32Char(s[j]) {
+			return "", fmt.Errorf(
+				"bolt12: %w: '+' must precede a bech32 "+
+					"character", ErrInvalidContinuation,
+			)
+		}


This specifically ties the left & right neighbouring characters after the + char to be a "Bech32Char". I don't think that should be required for the lno1 prefix part of the of the string.

The test vectors do define that using the + char in the prefix is allowed:
https://github.com/lightning/bolts/blob/311119388a46dfa859da3d2eda0ca836cfc5f078/bolt12/format-string-test.json#L13-L15

That testcase inserts the + char at:
l+no1....

However if the + char was instead inserted at:
ln+o1....

Our implementation would now fail as the o char is not a "Bech32Char".

I crosschecked with Eclair, Core Lightning, and LDK, and they'd all allow the + char to be inserted anywhere in the prefix, so I therefore think that's the correct implementation.

If you think it makes sense, I can open a PR to add a testcase to the spec repo's test vectors, which inserts the + char at ln+o1...., just to get consensus on that this should be a valid case.

Right, looking at the test vectors, it says '+ can join anywhere', so changed it to not taking the spec literally.

ViktorT-11 · 2026-08-03T16:54:38Z

+		{
+			name:    "plus right neighbour not bech32",
+			input:   "ln+o1pqps7sjq",
+			wantErr: true,
+		},
+		{
+			name:    "plus left and right neighbour not bech32",
+			input:   "lno+1pqps7sjq",
+			wantErr: true,
+		},


following up on #11001 (comment):

I.e. I don't think these test cases should error?

Agreed, have updated the tests.

vctt94

Awesome progress on this 🔥!

I reviewed the PR locally, all five commits passed the focused bolt12 tests independently, and the overall structure looks solid.

I left a few comments around keeping the Encode/Decode contract symmetric, along with a small release-note link issue.

While reviewing the new lni path, I also reproduced the unknown-even signature-range behavior previously discussed in #10941. I’m not duplicating the finding here, but the new string decoding path makes the existing asymmetry directly observable.

Thanks again for pushing this forward 🚀

github-actions · 2026-08-06T09:41:19Z

🟡 PR Severity: MEDIUM

gh pr view | 10 files | 1958 lines changed (320 lines / 1 file excluding tests & docs)

🟡 Medium (1 file)

bolt12/bech32.go - new Go source file implementing Bech32 encode/decode logic; not in any specifically categorized package, falls under "other Go files"

🟢 Low (9 files)

bolt12/bech32_test.go - test file
bolt12/helpers_test.go - test file
bolt12/invoice_request_test.go - test file
bolt12/offer_test.go - test file
bolt12/validate_test.go - test file
bolt12/test-vectors/README.md - docs
bolt12/test-vectors/format-string-test.json - test fixture data
docs/release-notes/release-notes-0.22.0.md - release notes

Analysis

This PR adds a new bolt12/bech32.go file implementing checksumless Bech32 encoding/decoding for BOLT 12 objects, plus a large body of test-only additions (unit tests and vendored upstream spec test vectors) and a release-notes update. The bolt12 package isn't one of the explicitly listed CRITICAL or HIGH packages, so the single non-test Go file (320 lines) is classified as MEDIUM ("other Go files not categorized above"). Excluding tests, docs, and test-vector fixtures, the change is well under the file-count (>20) and line-count (>500) bump thresholds, and it doesn't touch multiple critical packages, so no severity bump applies. Overall this looks like a focused, self-contained codec addition with strong test coverage against upstream spec vectors.

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

bitromortac · 2026-08-06T09:49:51Z

Thanks all for your reviews 🙏

Rebased on master and fixed a go mod issue.

vctt94

LGTM!

Great job 🚀

ziggie1984

LGTM nice and clean

ziggie1984 · 2026-08-13T02:11:44Z

+// string above maxBolt12StringLen, but the caller must set a smaller limit for
+// its own medium. See the caller obligations in the package documentation.
+func Decode(s string) (string, []byte, error) {
+	if len(s) > maxBolt12StringLen {


Nice-to-have / non-blocking: this limit is checked before stripContinuation, so continuation formatting counts toward the payload-derived string limit. At the boundary, Encode can produce an unwrapped string of exactly maxBolt12StringLen, while inserting a legal + (and optional whitespace) makes Decode return ErrStringTooLong even though the cleaned string and decoded payload are unchanged. This only affects unusually large strings near the 1 MiB limit, so I do not consider it blocking. It may still be worth applying the canonical/payload limit after normalization, keeping a separate raw transport limit if desired, and adding a wrapped-max-payload test.

GeorgeTsagk · 2026-08-13T12:37:05Z

+func toBech32Bytes(s string) ([]byte, error) {
+	result := make([]byte, len(s))
+	for i := 0; i < len(s); i++ {
+		idx := strings.IndexByte(charset, s[i])
+		if idx < 0 {
+			return nil, fmt.Errorf(
+				"bolt12: %w: invalid character 0x%02x at "+
+					"position %d of the cleaned data "+
+					"string %s",
+				ErrInvalidCharacter, s[i], i, s,


nit: Could we avoid including the full data string in this error since it can be about 1.68 MB and may expose invoice contents if logged?

TechLateef

LGTM!

The bolt12 package can already encode and decode the TLV layer but has no way to carry an offer as a human-transportable string, which is the form the spec specifies for QR codes, URLs and email signatures. BOLT 12's envelope is subtractive relative to BIP-173: there is no BCH checksum, because the BIP-340 signature over the Merkle root already secures the payload, and a '+' continuation marker may split the string across lines. btcutil/bech32's public API always wraps the checksum, so the alphabet layer is duplicated here rather than reused. Enforce a whitelist of BOLT 12 prefixes (lno, lnr, lni) on both Encode and Decode.

Vendor the BOLT 12 offers-test.json fixtures so the offer decoder and validator are checked against the specification's own strings rather than hand-authored ones, which cannot drift from the spec without someone noticing. Invalid vectors are tested to verify they are rejected at some layer, and an aggregate stage census pins the distribution across bech32 decode, TLV decode, and validation.

The invoice_request codec has round-trip coverage against locally- constructed messages only, so a canonical-encoding bug would go unnoticed until a real peer rejected a signature. Drive the decoder from the spec's signature-test invoice_request and assert that re-encoding is byte-identical to the wire bytes, because the signature commits to the Merkle root of that exact encoding.

Add changes for the bech32 work in bolt12.

ViktorT-11

Nice, thanks for the updates. LGTM 🔥!

Adding a few non-blocking comments below, where I think the comment regarding the offer length cap for decoding is important feedback.

ViktorT-11 · 2026-08-18T13:45:23Z

+		for j < len(s) && isWhitespace(s[j]) {
+			j++
+		}
+		if j >= len(s) || !isContinuationNeighbour(s[j]) {
+			return "", fmt.Errorf(
+				"bolt12: %w: '+' must precede a "+
+					"non-whitespace character",
+				ErrInvalidContinuation,
+			)
+		}


Not sure if: "bolt12: %w: '+' must precede a non-whitespace character" is the correct error message to use here, as you're actually skipping the whitespaces after the "+" char above.

ViktorT-11 · 2026-08-18T14:03:27Z

+
+	// maxBolt12RawStringLen is the largest raw BOLT 12 string the codec
+	// accepts, continuation markers and whitespace included.
+	maxBolt12RawStringLen = 2 * maxBolt12StringLen


I'm still not fully convinced that it's a great idea for only lnd to include this cap (at least for Decoding), and IMO we should increase this cap quite a bit if we do.

The risk I see with including it, is that there'll for some reason in the future be use cases where undefined unknown odd fields become used which pushes the length over our current limit. If that becomes the case, they'll become incompatible with old lnd implementations, despite them perhaps being fully payable by lnd.

One such use case would for example be a scheme that specifies:

IF you can read and interpret the "undefined unknown odd fields", then pay via a today undefined payment method.

OR

IF NOT, then proceed with the payment as per the BOLT12 specification today.

I.e. an idea similar to what "BIP 21/321" offers for on-chain & lightning payments, but using BOLT12 offers with lightning + a currently unknown payment method.

Ultimately, I don't see this issue as fully blocking, but I think it's worth discussing among the reviewers if this is something we actually want to include or not.

Personally, I'd be in favour of removing this cap or at least increase the cap quite a bit just to minimize the above ever becoming an issue.

I agree with Viktor here. My main concern is that this turns an lnd resource limit into a restriction of the generic BOLT12 decoder.

Since unknown odd fields are explicitly meant to allow forward-compatible extensions, we could eventually reject otherwise valid/payable objects just because they exceed a limit chosen today.

I'd prefer Decode to enforce BOLT12 encoding rules and leave resource limits to the caller/transport.

Not blocking from my side either, but I'd lean toward removing the decoding cap.

I'll research the tradeoffs here and will get back to it 🙏. Will address this in a follow-up.

ViktorT-11 · 2026-08-18T14:11:27Z

@@ -0,0 +1,7 @@
+# BOLT 12 Spec Test Vectors
+
+These test vectors are vendored from the upstream [lightning/bolts](https://github.com/lightning/bolts) specification repository.


nit: Line length

ViktorT-11 · 2026-08-18T14:13:42Z

+		t.Run(tc.Description, func(t *testing.T) {
+			t.Parallel()
+
+			_, tlvBytes, bech32Err := Decode(tc.Bolt12)


I think potentially there would be value in expanding this test to call the bech32 Encode function with the contents of this, and then also call offer.Encode below, just to include test coverage of those functions with the contents of the test vectors.

GeorgeTsagk

Looks good!

bitromortac mentioned this pull request Jul 28, 2026

[epic]: BOLT 12 Implementation Roadmap #10736

Open

6 tasks

saubyk assigned bitromortac Jul 28, 2026

saubyk added this to lnd v0.22 Jul 28, 2026

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

saubyk moved this from Backlog to In progress in lnd v0.22 Jul 28, 2026

saubyk added this to the v0.22.0 milestone Jul 28, 2026

saubyk added the bolt12 label Jul 28, 2026

bitromortac force-pushed the 2604-bolt12-1e branch from 7c3ac94 to 14fb769 Compare July 28, 2026 18:10

bitromortac requested review from GeorgeTsagk and ViktorT-11 July 31, 2026 09:59

TechLateef reviewed Jul 31, 2026

View reviewed changes

ViktorT-11 reviewed Aug 3, 2026

View reviewed changes

vctt94 reviewed Aug 5, 2026

View reviewed changes

Comment thread bolt12/bech32.go

Comment thread docs/release-notes/release-notes-0.22.0.md Outdated

Comment thread docs/release-notes/release-notes-0.22.0.md Outdated

Comment thread bolt12/bech32.go Outdated

bitromortac force-pushed the 2604-bolt12-1e branch from 14fb769 to 3d0cf2b Compare August 6, 2026 09:38

github-actions Bot added the severity-medium Focused review required label Aug 6, 2026

bolt12: add tests for offer decoding and validation

7415b08

bitromortac force-pushed the 2604-bolt12-1e branch 2 times, most recently from ba47762 to 70cd09c Compare August 6, 2026 09:49

bitromortac requested review from TechLateef, ViktorT-11 and vctt94 August 6, 2026 09:50

vctt94 approved these changes Aug 6, 2026

View reviewed changes

bitromortac mentioned this pull request Aug 11, 2026

bolt12: add Merkle tree and BIP-340 message signatures #11061

Open

ziggie1984 approved these changes Aug 13, 2026

View reviewed changes

ziggie1984 reviewed Aug 13, 2026

View reviewed changes

GeorgeTsagk reviewed Aug 13, 2026

View reviewed changes

TechLateef reviewed Aug 13, 2026

View reviewed changes

bitromortac added 4 commits August 18, 2026 13:18

docs: update release notes

c73b0d0

Add changes for the bech32 work in bolt12.

bitromortac force-pushed the 2604-bolt12-1e branch from 70cd09c to c73b0d0 Compare August 18, 2026 13:24

bitromortac requested a review from GeorgeTsagk August 18, 2026 13:25

ViktorT-11 approved these changes Aug 18, 2026

View reviewed changes

GeorgeTsagk approved these changes Aug 18, 2026

View reviewed changes

ziggie1984 merged commit ae9e86a into lightningnetwork:master Aug 18, 2026
54 of 56 checks passed

github-project-automation Bot moved this from In progress to Done in lnd v0.22 Aug 18, 2026

		@@ -0,0 +1,7 @@
		# BOLT 12 Spec Test Vectors

		These test vectors are vendored from the upstream [lightning/bolts](https://github.com/lightning/bolts) specification repository.

Uh oh!

Conversation

bitromortac commented Jul 28, 2026

Uh oh!

bitromortac commented Jul 31, 2026

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!

ViktorT-11 left a comment

Choose a reason for hiding this comment

Uh oh!

ViktorT-11 Aug 3, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

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!

vctt94 left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

github-actions Bot commented Aug 6, 2026

🟡 PR Severity: MEDIUM

Analysis

Uh oh!

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

Uh oh!

Uh oh!

vctt94 left a comment

Choose a reason for hiding this comment

Uh oh!

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

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

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

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!

Uh oh!

Reviewers

ViktorT-11 Aug 3, 2026 •

edited

Loading

bitromortac commented Aug 6, 2026 •

edited

Loading

bitromortac Aug 18, 2026 •

edited

Loading