Does anything in your stack enforce BOLT-11's reader rules?

What I measured

24 invoices from the spec's Examples section — 14 a reader must accept, 10 it must fail the payment on. Every decoder on npm that decodes BOLT-11, run on 2026-08-13 against the then-current version. accept means decode() returned without throwing.

Reproduce it in about thirty seconds: npm i bolt11, download bolt11-vectors.js below, change the one marked import line, run it.

The two every one of them lets through

1. An unknown even feature bit

BOLT-9's it's-ok-to-be-odd convention: in the 9 field, an odd bit you don't understand is optional and you ignore it; an even bit you don't understand is required, and you cannot pay the invoice correctly without understanding it. The spec is not subtle about this:

  - if the `9` field contains unknown _odd_ bits that are non-zero:
    - MUST ignore the bit.
  - if the `9` field contains unknown _even_ bits that are non-zero:
    - MUST fail the payment.

The spec ships an invoice with feature bit 100 set for exactly this case, listed under invalid invoices with the note "adding invalid unknown feature 100". All four decoders return it happily. bolt11 is the interesting one here: it does the work, and exposes tags.feature_bits.data.extra_bits.has_required === true on that invoice and false on a good one. The answer is sitting in the return value. It just isn't the decoder's job to act on it, and nothing in the README points at it.

2. No s field (payment_secret)

payment_secret stopped being optional in 2020. It is what prevents an intermediate node from probing the recipient and from stealing a multi-part payment by guessing the payment hash. The spec: "if a valid s field is not provided: MUST fail the payment."

Every decoder tested returns the spec's s-less example as a normal invoice. bolt11 reports complete: true on it, which is a field name a caller can be forgiven for reading as "this invoice is fine."

If you want just these two, they are about ten lines against a decoded invoice, and you don't need my vectors to write them. The vectors are for making sure they stay written.

Why this isn't a list of bugs

I write security reviews and I send them to maintainers privately. I'm not sending this one, and I want to be straight about why, because a page like this is easy to write as an accusation and that would be dishonest.

Every requirement above is phrased as "MUST fail the payment." A decoder does not make payments. A library that turns a string into a structure, exposes everything it found, and leaves policy to the caller is making a defensible — arguably correct — design choice, and light-bolt11-decoder states its scope in the first paragraph of its README. Filing four bug reports saying "your parser doesn't enforce payment policy" would be crying wolf, and a review service that cries wolf is worth less than no review service.

The reason it's still worth publishing is the 4-out-of-4. When every library in a layer leaves the same check to the layer above, the check has a way of not existing anywhere. The decoders are not wrong. The gap is real. Both things are true, and the only way to find out which side of it your code is on is to run the vectors against your accept/reject decision rather than against a library's.

Run it against your own code

This runs entirely in your browser with new Function. Nothing is sent anywhere — there is no server side to this page, and you can read the source. If you'd rather not paste code into a web page, take the standalone files below instead.

Point it at whatever in your system decides "would I pay this?" — not just decode(). If the answer is "we call decode() and if it doesn't throw we pay", then decode() is that decision, and the score below is your score.

The vector the spec contradicts itself on

One invoice from the Examples section is excluded from the 24 above and shown separately, because I don't think the spec can be satisfied on it. It's listed under valid invoices as "Same, but including fields which must be ignored." Walking its data part gives these tagged fields:

tag p  data_length 52     tag p  data_length 51     tag h  data_length 51
tag d  data_length 20     tag p  data_length 53     tag h  data_length 53
tag s  data_length 52     tag s  data_length 51     tag n  data_length 52
tag 9  data_length 20     tag s  data_length 53     tag n  data_length 54

The trailing fields are deliberately mis-sized, and the point of the vector is that a reader ignores them. But the Requirements section, thirty lines earlier in the same document, says:

  - MUST fail the payment if any field with fixed `data_length`
    (`p`, `h`, `s`, `n`) does not have the correct length (52, 52, 52, 53).

"Any field" is unqualified. Under that sentence this invoice must be rejected; under the Examples section it must be accepted. A conformance suite shouldn't quietly pick a side, so it isn't scored — but you can see below what your code does with it.

The four decoders can't agree on it either, and none of them reaches a verdict on the grounds the spec argues about. @node-lightning/invoice accepts it. bolt11 and bolt11-decoder reject it for an unrelated reason — the trailing n fields are inside the signed data, so the recovered pubkey doesn't match the n field they read, and they throw on that. light-bolt11-decoder rejects it by crashing inside its base32 decoder with radix2.encode input should be Uint8Array, which is the right answer arrived at by accident.

Take the vectors with you

The point isn't this page, it's having the vectors in your test suite so a future refactor can't quietly undo the fix. Both scripts are dependency-free and exit non-zero on failure, so they drop straight into CI.

bolt11-vectors.js  ·  bolt11_vectors.py  ·  bolt11-vectors.json

Transcribed from BOLT #11's own Examples section, keeping its wording for why each invalid one is invalid. Public domain. If you find a transcription error, tell me and I'll fix it and say so on this page.

Doing the same thing for bitcoin addresses: the 23 BIP-350 vectors, same idea, same page shape.