bip138: binary encoding clarifications #2299

pull Sjors wants to merge 4 commits into bitcoin:master from Sjors:2026/09/bip138-encoding changing 2 files +35 −9

Sjors commented at 1:05 PM on September 23, 2026: member
This PR clarifies a few details of BIP138's binary encoding.

It adds two test vectors in a new payload.json, but shouldn't be a breaking change.

Three middle commits:
- specify empty associated data: make the AAD input explicit in the encryption and decryption formulas.
- clarify that 0x00 ends payload parsing: add a test vector with a content item followed by a terminator and ignored bytes.
- clarify rejection of empty payloads: add a test vector containing only the terminator, with zero content items.
The first commit introduces a changelog. I'm reusing that commit across a few parallel pull requests.

The last commit updates the changelog; I'll update that depending on merge order.
Sjors commented at 1:06 PM on September 23, 2026: member

cc @pythcoiner

First (changelog) commit is shared with #2298.
Sjors force-pushed on Sep 23, 2026
jonatack added the label Metadata Update on Sep 23, 2026
jonatack added the label Fixups on Sep 23, 2026
murchandamus removed the label Metadata Update on Sep 23, 2026
murchandamus removed the label Fixups on Sep 23, 2026
murchandamus added the label Proposed BIP modification on Sep 23, 2026
murchandamus added the label Pending acceptance on Sep 23, 2026
murchandamus commented at 4:17 PM on September 23, 2026: member

Changed from Fixup to BIP Update, because this seems to add another field to the encryption payload
Sjors referenced this in commit 6840852c25 on Sep 23, 2026
Sjors referenced this in commit 53d4d05e43 on Sep 23, 2026
Sjors referenced this in commit 7180c9ef77 on Sep 23, 2026
Sjors referenced this in commit ba6acd6f08 on Sep 23, 2026
Sjors referenced this in commit 8d131a24bd on Sep 23, 2026
Sjors referenced this in commit 8ae4f8d4a6 on Sep 23, 2026
Sjors commented at 8:51 AM on September 24, 2026: member

add another field to the encryption payload

No, it just makes it explicit. All existing test vectors use an empty AAD.
pythcoiner commented at 10:37 AM on September 24, 2026: contributor

ACK e3cfc053

bip138: specify empty associated data

Make the associated-data input explicit in the encryption and decryption
formulas and specify that it is empty, as used by the existing vectors.

0f8c26b7c2

bip138: clarify that 0x00 ends payload parsing

Specify that parsing stops immediately. Add a vector with an item followed
by a terminator and ignored bytes.

Clarify that TYPE 0x00 also doesn't require TYPE_LENGTH.

aa098559bf

bip138: clarify rejection of empty payloads

Clarify that an empty payload contains zero content items. Add a
vector that rejects a payload consisting only of the 0x00 terminator.

bf64a12098

bip138: record encoding clarifications in changelog 62dc1c4e8f
murchandamus force-pushed on Sep 24, 2026
murchandamus removed the label Proposed BIP modification on Sep 24, 2026
murchandamus removed the label Pending acceptance on Sep 24, 2026
murchandamus added the label Metadata Update on Sep 24, 2026
murchandamus added the label Fixups on Sep 24, 2026
murchandamus commented at 9:54 PM on September 24, 2026: member

Gotcha, thanks for clarifying, @sjors. Thanks for the review, @pythcoiner.

I rebased the PR on the latest commit in the master branch, because the initial Changelog had been added by #2298 which got merged earlier today. I resolved the conflict in the Changelog by moving the new Changelog entries to 0.1.2 incrementing from 0.1.1 which was reached by #2298.
murchandamus merged this on Sep 24, 2026
murchandamus closed this on Sep 24, 2026
Sjors deleted the branch on Sep 25, 2026

Contributors

Sjors

murchandamus

pythcoiner

Labels

Metadata Update Fixups