BIP32: specify the maximum depth of 255 #2322

pull fametrano wants to merge 3 commits into bitcoin:master from fametrano:bip32-max-depth changing 1 files +30 −8

fametrano commented at 7:41 AM on October 2, 2026: contributor

BIP32 serializes the depth as one byte but does not say what happens when deriving past depth 255. Bitcoin Core refuses, while several libraries let the depth overflow (bitcoin/bitcoin#32201). In that issue @sipa said a hard limit is better for interoperability and that he would add a note to the BIP: https://github.com/bitcoin/bitcoin/issues/32201#issuecomment-3847331033

I added that note: deriving a child of a depth-255 key must fail. I also added test vector 6, with the keys at depth 255 on the chain m/0/0/.../0 (255 levels). I checked them with Bitcoin Core 31.1 and btclib-wallet, and both refuse to derive any child of them.

I left out the derivation path parsing rules raised in bitcoin/bitcoin#35306. I am happy to add them here if reviewers prefer.

Made with my usual tools: a computer, the Internet and an LLM. The mistakes, as usual, are all mine.

BIP32: specify the maximum depth of 255

The depth is serialized as one byte. Deriving a child of a depth-255
key must fail, as Bitcoin Core already does.

ca1cb3351d

BIP32: add test vectors for the maximum depth

Test vector 6 gives the keys at depth 255 on the chain m/0/.../0.
Deriving any child of them must fail.

fe2bd469d0

murchandamus added the label Proposed BIP modification on Oct 14, 2026
murchandamus added the label Pending acceptance on Oct 14, 2026
in bip-0032.mediawiki:8 in fe2bd469d0
```
   4 | @@ -5,6 +5,7 @@ RECENT CHANGES:
   5 |  * (15 Jan 2014) Rename keys with index ≥ 0x80000000 to hardened keys, and add explicit conversion functions.
   6 |  * (24 Feb 2017) Added test vectors for hardened derivation with leading zeros
   7 |  * (4 Nov 2020) Added new test vectors for hardened derivation with leading zeros
   8 | +* (2 Oct 2026) Specified the maximum depth of 255 and added test vectors for it
```
murchandamus commented at 5:26 AM on October 14, 2026:

I’m surprised that this passes CI, but perhaps the addition of another line could be used to turn this in a Changelog as specified by BIP3 instead of it appearing as a block preceding the preamble.
fametrano commented at 12:13 PM on October 14, 2026:

Thank you, done in baa9dffa.

The block before the preamble is gone. BIP 32 now has a ==Changelog== section at the end and a Version: 2.1.0 header. The six historic entries keep their text and dates, in the format of BIP 3.

The version numbers are a proposal. They follow BIP 3, one version per entry, with the oldest entry as 1.0.0, as in BIP 85. If BIP 32 was still a draft in April 2013, the 2013 entries could be 0.x.y instead, as in BIP 8 and BIP 127:

1.0.0 (2013-04-16) private derivation for hardened indexes

2.0.0 (2013-04-30) addition instead of multiplication (incompatible, so major)

2.0.1 (2013-05-25) test vectors

2.0.2 (2014-01-15) hardened terminology and conversion functions

2.0.3 (2017-02-24) test vectors

2.0.4 (2020-11-04) test vectors

2.1.0 (this change) maximum depth, backward-compatible, so minor @sipa, could you confirm or correct these numbers?

in bip-0032.mediawiki:318 in fe2bd469d0

 309 | @@ -307,6 +310,15 @@ These vectors test that invalid extended keys are recognized as invalid.
 310 |  * xpub661MyMwAqRbcEYS8w7XLSVeEsBXy79zSzH1J8vCdxAZningWLdN3zgtU6Q5JXayek4PRsn35jii4veMimro1xefsM58PgBMrvdYre8QyULY (invalid pubkey 020000000000000000000000000000000000000000000000000000000000000007)
 311 |  * xprv9s21ZrQH143K3QTDL4LXw2F7HEK3wJUD2nW2nRk4stbPy6cq3jPPqjiChkVvvNKmPGJxWUtg6LnF5kejMRNNU3TGtRBeJgk33yuGBxrMPHL (invalid checksum)
 312 |  
 313 | +===Test vector 6===
 314 | +
 315 | +These vectors test the maximum depth of 255. The chain is 255 steps of index 0, so it can be derived from the master public key too. Deriving any child of these keys must fail.
 316 | +
 317 | +Seed (hex): 000102030405060708090a0b0c0d0e0f
 318 | +* Chain m/0/0/.../0 (255 levels)

murchandamus commented at 5:27 AM on October 14, 2026:

It would be preferable if the 255 levels were written out here, as it is easy to get an off-by-one error. The human readable explanation should move to a comment.

fametrano commented at 12:13 PM on October 14, 2026:

Thank you, done in baa9dffa.

The chain is now written out as the literal path, with all 255 levels. I counted the /0 components with a script (255), and checked that the xpub and xprv decode to depth 255 and match a derivation from the seed along that path, both from the private key and from the master public key.

The note "(255 levels)" is now a comment above the path. The sentence that deriving any child must fail stays visible.

murchandamus commented at 5:27 AM on October 14, 2026: member

Could use a couple touch-ups. cc: @sipa.
murchandamus added the label PR Author action required on Oct 14, 2026

BIP32: use a Changelog section, write out the depth-255 chain

BIP3 asks for a Changelog section and a Version header. The list
above the preamble becomes the Changelog. The version numbers are
a proposal.

Test vector 6 now writes out all 255 levels of the chain. The level
count is a comment next to the path.

baa9dffaa2

Contributors

fametrano

murchandamus

Labels

Proposed BIP modification Pending acceptance PR Author action required