From bf63783c10649a3ae33d4c63d3e54fa1e04d1951 Mon Sep 17 00:00:00 2001 From: Sjors Provoost Date: Wed, 23 Sep 2026 13:09:10 +0200 Subject: [PATCH 1/5] bip138: introduce changelog at version 0.1.0 Record the initial published draft using the BIP3 document-version and changelog convention. --- bip-0138.md | 6 ++++++ 1 file changed, 6 insertions(+) diff --git a/bip-0138.md b/bip-0138.md index 98a77019..cca356ac 100644 --- a/bip-0138.md +++ b/bip-0138.md @@ -10,6 +10,7 @@ Discussion: https://delvingbitcoin.org/t/a-simple-backup-scheme-for-wallet-accounts/1607 https://groups.google.com/g/bitcoindev/c/5NgJbpVDgEc/m/TtGK9sF9BgAJ https://github.com/bitcoin/bips/pull/1951 + Version: 0.1.0 Requires: 32, 340, 380, 388, 389 ``` @@ -617,3 +618,8 @@ Thanks to @Sjors for extensive reviews, many design contributions to the payload encoding, and a proof-of-concept implementation on top of Bitcoin Core. Thanks also to @murchandamus, @jonatack, @craigraw, @jp1ac4, and @torkelrogstad for their reviews and suggestions. + +## Changelog + +* __0.1.0__ (2026-09-21): + * Initial publication. From 51995cc228a6c65f9a74dd24962fe9562a472d83 Mon Sep 17 00:00:00 2001 From: Sjors Provoost Date: Wed, 23 Sep 2026 13:32:00 +0200 Subject: [PATCH 2/5] bip138: clarify receive-only descriptor sets Make change_descriptor explicitly optional for non-multipath descriptors. Add a receive-only document vector with no change descriptor or optional metadata; the existing vectors cover a receive/change pair and multipath. --- bip-0138.md | 3 ++- bip-0138/test_vectors/bip380_descriptor_backup.json | 12 ++++++++++++ 2 files changed, 14 insertions(+), 1 deletion(-) diff --git a/bip-0138.md b/bip-0138.md index cca356ac..9affdfb7 100644 --- a/bip-0138.md +++ b/bip-0138.md @@ -474,7 +474,8 @@ For BIP389 multipath descriptors, `/<0;1>` means receive and change, respectively. The `change_descriptor` field MUST NOT be used. For descriptors without BIP389 multipath key expressions, `descriptor` is the -receive descriptor and `change_descriptor` is the change descriptor. +receive descriptor. The optional `change_descriptor` string can be omitted for a +receive-only set. If optional boolean `archived` is `true`, importing wallets SHOULD NOT use the descriptor set for new address generation. diff --git a/bip-0138/test_vectors/bip380_descriptor_backup.json b/bip-0138/test_vectors/bip380_descriptor_backup.json index 719d0e11..3066c8b3 100644 --- a/bip-0138/test_vectors/bip380_descriptor_backup.json +++ b/bip-0138/test_vectors/bip380_descriptor_backup.json @@ -29,5 +29,17 @@ } ] } + }, + { + "description": "Receive-only descriptor set without optional metadata", + "valid": true, + "document": { + "version": 1, + "descriptor_sets": [ + { + "descriptor": "wpkh([d34db33f/84h/1h/0h]tpubDC5FSnBiZDMmhiuCmWAYsLwgLYrrT9rAqvTySfuCCrgsWz8wxMXUS9Tb9iVMvcRbvFcAHGkMD5Kx8koh4GquNGNTfohfk7pgjhaPCdXpoba/0/*)" + } + ] + } } ] From 399ea2a09155130e9519c58f85f3cf9fa5215f84 Mon Sep 17 00:00:00 2001 From: Sjors Provoost Date: Wed, 23 Sep 2026 13:32:00 +0200 Subject: [PATCH 3/5] bip138: clarify derivation ranges using BIP32 Identify range bounds as BIP32 non-hardened child indexes, ordered from start to end. --- bip-0138.md | 8 +++++--- 1 file changed, 5 insertions(+), 3 deletions(-) diff --git a/bip-0138.md b/bip-0138.md index 9affdfb7..555bb3de 100644 --- a/bip-0138.md +++ b/bip-0138.md @@ -481,7 +481,8 @@ If optional boolean `archived` is `true`, importing wallets SHOULD NOT use the descriptor set for new address generation. `range` is an optional two-element array `[start, end]`, inclusive, describing -the ranged derivation indexes covered by the descriptor set. +the [BIP32](bip-0032.mediawiki) non-hardened child indexes covered by the +descriptor set, with `start <= end`. `birth_time` is an optional integer Unix timestamp in seconds, indicating a lower bound for when the descriptor set may have received funds. Importing @@ -521,8 +522,9 @@ optional metadata fields: If optional boolean `archived` is `true`, importing wallets SHOULD NOT use the policy for new address generation. -`range` is an optional two-element array `[start, end]`, inclusive, describing the -ranged derivation indexes covered by the policy. +`range` is an optional two-element array `[start, end]`, inclusive, describing +the [BIP32](bip-0032.mediawiki) non-hardened child indexes covered by the +policy, with `start <= end`. `birth_time` is an optional integer Unix timestamp in seconds, indicating a lower bound for when the policy may have received funds. Importing wallets MAY use this From ffa6bf4944c4c883970b8a9b6e7386459d5efd0d Mon Sep 17 00:00:00 2001 From: Sjors Provoost Date: Wed, 23 Sep 2026 13:32:01 +0200 Subject: [PATCH 4/5] bip138: clarify zero and omitted birth times Explain that zero and omission both mean the birth time is unknown. Recommend scanning from the wallet birthday if known, otherwise from genesis. --- bip-0138.md | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/bip-0138.md b/bip-0138.md index 555bb3de..e8974260 100644 --- a/bip-0138.md +++ b/bip-0138.md @@ -487,6 +487,8 @@ descriptor set, with `start <= end`. `birth_time` is an optional integer Unix timestamp in seconds, indicating a lower bound for when the descriptor set may have received funds. Importing wallets MAY use this value as a scanning hint. +If `0` or omitted, no lower bound is known. Importers SHOULD scan from the wallet +birthday if known, otherwise from genesis. #### BIP388 Wallet Policy Backup Content @@ -529,6 +531,8 @@ policy, with `start <= end`. `birth_time` is an optional integer Unix timestamp in seconds, indicating a lower bound for when the policy may have received funds. Importing wallets MAY use this value as a scanning hint. +If `0` or omitted, no lower bound is known. Importers SHOULD scan from the wallet +birthday if known, otherwise from genesis. ##### Multiple Policies Document From 8c1314949ec8b3d3bad718488f99f2c9fd9d0b33 Mon Sep 17 00:00:00 2001 From: Sjors Provoost Date: Wed, 23 Sep 2026 13:10:38 +0200 Subject: [PATCH 5/5] bip138: record metadata clarifications in changelog Record this branch's clarifications and test vectors under draft document version 0.1.1. Keep the initial-publication entry in the shared first commit. --- bip-0138.md | 5 ++++- 1 file changed, 4 insertions(+), 1 deletion(-) diff --git a/bip-0138.md b/bip-0138.md index e8974260..90ae803e 100644 --- a/bip-0138.md +++ b/bip-0138.md @@ -10,7 +10,7 @@ Discussion: https://delvingbitcoin.org/t/a-simple-backup-scheme-for-wallet-accounts/1607 https://groups.google.com/g/bitcoindev/c/5NgJbpVDgEc/m/TtGK9sF9BgAJ https://github.com/bitcoin/bips/pull/1951 - Version: 0.1.0 + Version: 0.1.1 Requires: 32, 340, 380, 388, 389 ``` @@ -628,5 +628,8 @@ their reviews and suggestions. ## Changelog +* __0.1.1__ (2026-09-23): + * Clarify derivation range bounds and zero or omitted birth-time semantics for descriptors and policies. + * Clarify receive-only descriptor sets and add a corresponding test vector. * __0.1.0__ (2026-09-21): * Initial publication.