BIP139: Wallet Metadata Backup Format #2130

pythcoiner commented at 10:39 AM on March 27, 2026: contributor

This is a bip for wallet metadata backup format. Mailing list post: https://groups.google.com/g/bitcoindev/c/ylPeOnEIhO8

pythcoiner force-pushed on Mar 27, 2026

murchandamus commented at 1:34 PM on March 27, 2026: member

Could you perhaps expound the relationship to #1951?

in bip-0139.md:108 in 45b4a5bb37 outdated

 103 | +- `timestamp`: Optional integer Unix timestamp representing account creation time in
 104 | +  seconds.  
 105 | +- `iso_8601_datetime`: optional string representing account creation time in ISO 8601
 106 | +  format.  
 107 | +- `block_height`: Optional integer representing account creation time in bitcoin block
 108 | +  height unit.

seedhammer commented at 11:26 AM on April 3, 2026:

3 different ways of representing the birth date doesn't seem ideal. Also "iso_8601_datetime" specifies the data format, not the purpose of the field. I'd prefer short, purposeful names (e.g. "birthblock" or "birthdate") and leave the type and format out of the name.

pythcoiner commented at 7:59 AM on April 7, 2026:

I'm open to represent in a different way, but few points why it's end up like this:

we use a backup format based on this in Liana with the timestamp field
we had a discussion w/ @ethicnology here where he seems prefering iso 8601, I've used a simplified approach in this draft compared to what discussed, but I'm eager to get feedback.
it comes to my mind later that block_height rather than unix timestamp could make more sense

murchandamus commented at 6:18 PM on June 24, 2026:

I was about to comment on there being three different birth time fields as well. Seconding @seedhammer’s concern here.

pythcoiner commented at 5:43 AM on August 20, 2026:

kept a single birth_block field

in bip-0139.md:75 in 45b4a5bb37 outdated

  70 | +All other fields are optional.  
  71 | +
  72 | +- `version`: Optional integer version of the backup format.  
  73 | +- `bip`: Optional integer value representing the number of this BIP.  
  74 | +- `name`: Optional string wallet name.  
  75 | +  NOTE: `alias` is an alias of `name`.

seedhammer commented at 11:33 AM on April 3, 2026:

Why mention alias in a new BIP?

pythcoiner commented at 8:00 AM on April 7, 2026:

because we already use name in Liana backup format, but in the end I think alias is more clear

pythcoiner commented at 5:44 AM on August 20, 2026:

dropped all aliases

in bip-0139.md:92 in 45b4a5bb37 outdated

  87 | +All fields are optional, allowing wallets to include only the metadata they support.
  88 | +
  89 | +- `name`: Optional string account name.  
  90 | +  NOTE: `alias` is an alias of `name`.  
  91 | +- `description`: Optional string account description.  
  92 | +- `active`: Optional boolean field indicating if the account is active.

seedhammer commented at 11:35 AM on April 3, 2026:

active doesn't seem very useful for a backup. In fact, some of these fields feel like the union of all possible metadata fields useful to any wallet software. If so, this leads to the question: what is the standard for adding new fields to this standard?

I think it's better to specify a small(er) set of widely useful fields.

pythcoiner commented at 8:03 AM on April 7, 2026:

iirc it was requested by @ethicnology to represent an usage they already have in Bull Bitcoin wallet

pythcoiner commented at 10:03 AM on April 9, 2026:

and I just notice it is also something tracked in bitcoin core: https://github.com/bitcoin/bitcoin/blob/2b541eeb363cd43fc225c7c7f9691c925b0e4f9d/src/wallet/rpc/backup.cpp#L515

in bip-0139.md:127 in 45b4a5bb37 outdated

 122 | +  by [BIP-0174](https://github.com/bitcoin/bips/blob/master/bip-0174.mediawiki).  
 123 | +- `bip370_psbts`: Optional array containing unspent but partially signed transactions as defined
 124 | +  by [BIP-0370](https://github.com/bitcoin/bips/blob/master/bip-370.mediawiki).  
 125 | +- `psbts`: Optinnal array than can contains both BIP-0174 & BIP-0370 PSBTs.  
 126 | +- `bip39_mnemonic`: Optional string containing mnemonic words following BIP39.  
 127 | +  Since backups may be stored online, storing mainnet mnemonics is strongly discouraged.

seedhammer commented at 11:36 AM on April 3, 2026:

It feels wrong to specify a field which is immediately "strongly discouraged".

pythcoiner commented at 8:07 AM on April 7, 2026:

Need a rewording, I think mainnet mnemonic should be strongly discouraged, but it could be useful for testnet, like in a bug report, join a testnet/signet/regtest backup of a wllet can make it easy to import the wallet state in order to reproduce the bug.

pythcoiner commented at 12:49 AM on June 15, 2026:

reworded

in bip-0139.md:81 in 45b4a5bb37 outdated

  76 | +- `description`: Optional string wallet description.  
  77 | +- `accounts`: Mandatory array of account objects.  
  78 | +  Must contain at least one account.  
  79 | +  See [Account Object Structure](#account-object-structure).  
  80 | +- `network`: Optional string network identifier.  
  81 | +  Valid values are `bitcoin` (mainnet), `testnet3`, `testnet4`, `signet`, and `regtest`.

seedhammer commented at 11:37 AM on April 3, 2026:

Non-main networks are not useful for backups. Can the "network" field be left out entirely?

pythcoiner commented at 8:07 AM on April 7, 2026:

cf previous message for rationale

seedhammer commented at 11:37 AM on April 3, 2026: contributor

This BIP seems to overlap #2099. It would be ideal to have a single way of encoding wallet metadata.

murchandamus commented at 6:51 PM on April 6, 2026: member

Thanks for reviewing related work, @seedhammer!

pythcoiner commented at 7:36 AM on April 7, 2026: contributor

Thanks for review @seedhammer, I'll reply inline

pythcoiner commented at 8:23 AM on April 7, 2026: contributor

This BIP seems to overlap #2099. It would be ideal to have a single way of encoding wallet metadata.

I think they have different use case:

I see whats offered in #2099 as a minimal backup that a user make once at wallet(descriptor) creation time, that contains only informations related to "scanning"
Whats offered in this PR intends to be a format for backup/export of a complete wallet state, that could be also done later & recurently in the wallet lifetime.

pythcoiner commented at 8:34 AM on April 7, 2026: contributor

Something that I should add in the bip abstract is, that I see this bip as a "central repository" where a wallet implementer can "register" a field usage & share it's usage of the format in a test vector. The intend is not to force anyone to be interoperable in both way with every other implem, but rather to make it easy if one want to be interoperable in at least one way.

murchandamus commented at 4:03 PM on April 7, 2026: member

I think this also has overlap with BIPs 329. Perhaps @craigraw would be interested in taking a look.

pythcoiner force-pushed on Apr 8, 2026

pythcoiner force-pushed on Apr 9, 2026

pythcoiner commented at 8:56 AM on April 9, 2026: contributor

I've clauded a draft implem of this format on bitcoin core here and then added few fields and a transaction object here

pythcoiner force-pushed on Apr 9, 2026

pythcoiner commented at 9:38 AM on April 9, 2026: contributor

Could you perhaps expound the relationship to #1951?

added an Encryption section in order to link them, will update as soon as there is a BIP # for #1951

murchandamus added the label New BIP on Apr 14, 2026

pythcoiner force-pushed on Apr 24, 2026

pythcoiner marked this as ready for review on Apr 24, 2026

in bip-wallet-backup.md:11 in 32a6893af6

   6 | +Status: Draft.
   7 | +Type: Specification.
   8 | +Assigned: ?
   9 | +License: BSD-2-Clause.
  10 | +Discussion: https://x.com/pythcoiner/status/1893923445974425840?s=20
  11 | +            https://groups.google.com/g/bitcoindev/c/ylPeOnEIhO8

murchandamus commented at 10:48 PM on April 28, 2026:

Did some regex-powered find and replace go wild on this whole document? There is also a fullstop after almost every headline.

BIP: ?
Layer: Applications
Title: Wallet Backup Metadata Format
Authors: Pyth <pythcoiner@wizardsardine.com>
Status: Draft
Type: Specification
Assigned: ?
License: BSD-2-Clause
Discussion: https://x.com/pythcoiner/status/1893923445974425840?s=20
            https://groups.google.com/g/bitcoindev/c/ylPeOnEIhO8

murchandamus commented at 10:51 PM on April 28, 2026:

I don’t think the Twitter discussion linked there is what we usually have in mind when we think of this preamble header.

Discussion: https://groups.google.com/g/bitcoindev/c/ylPeOnEIhO8

murchandamus commented at 11:02 PM on April 28, 2026:

I’m not sure it’s worth linking to this Twitter discussion, it seems mostly about coordinating and linking to some related work.

Discussion: https://groups.google.com/g/bitcoindev/c/ylPeOnEIhO8

pythcoiner commented at 6:45 AM on April 29, 2026:

I think I was a "tired regex" :smile:

pythcoiner commented at 6:46 AM on April 29, 2026:

dropped

pythcoiner commented at 6:47 AM on April 29, 2026:

dropped

murchandamus commented at 11:08 PM on April 28, 2026: member

Just a quick first pass. I think I’d be interested in seeing a few more wallet developers take a look at this and provide their thoughts on how this would match their needs.

in bip-wallet-backup.md:4 in 32a6893af6

   0 | @@ -0,0 +1,285 @@
   1 | +```
   2 | +BIP: ?
   3 | +Layer: Applications.
   4 | +Title: Wallet Backup Metadata Format.

murchandamus commented at 11:10 PM on April 28, 2026:

Wouldn’t it rather be “Wallet Metadata Backup Format”?

pythcoiner commented at 6:53 AM on April 29, 2026:

changed

pythcoiner force-pushed on Apr 29, 2026

pythcoiner commented at 6:53 AM on April 29, 2026: contributor

@murchandamus thanks for your review, comments addressed.

murchandamus force-pushed on May 11, 2026

murchandamus commented at 7:45 PM on May 11, 2026: member

Assigned BIP139

murchandamus renamed this:
~~Bip draft: Wallet Backup Metadata Format~~
BIP139: Wallet Backup Metadata Format
on May 11, 2026

murchandamus force-pushed on May 11, 2026

murchandamus commented at 8:08 PM on May 11, 2026: member

It took me a moment to figure out what the issue was: the preamble needed to be indented.

murchandamus renamed this:
~~BIP139: Wallet Backup Metadata Format~~
BIP139: Wallet Metadata Backup Format
on May 11, 2026

in bip-0139.md:254 in b17c8a5990

 249 | +* Wallets should validate the structure and ensure at least one account is present before
 250 | +  attempting import.  
 251 | +
 252 | +## Encryption
 253 | +
 254 | +This format can be encrypted following [BIP-XXXX](https://github.com/bitcoin/bips/pull/1951).

murchandamus commented at 8:14 PM on May 11, 2026:

This format can be encrypted following [BIP-0138](https://github.com/bitcoin/bips/pull/1951).

murchandamus added the label PR Author action required on May 19, 2026

Sjors commented at 12:08 PM on May 26, 2026: member

I'm not sure if it's a good idea to create one kitchen-sink JSON blob for everything. BIP138 can easily handle multiple JSON blobs each specified in their own BIP.

murchandamus commented at 6:09 PM on June 12, 2026: member

Hey, any update on this? Is there something I could help with? I was waiting for the open review to be addressed to take another look, but I wanted to check that we are not crossing our wires in regard to where it’s currently held up.

pythcoiner force-pushed on Jun 15, 2026

pythcoiner commented at 12:57 AM on June 15, 2026: contributor

I'm not sure if it's a good idea to create one kitchen-sink JSON blob for everything. BIP138 can easily handle multiple JSON blobs each specified in their own BIP.

I think the OP was misleading, look like I've copy/pasted from BIP-138 PR w/o edit.

This spec is only related to BIP-139 in the way that it could be encryptd with it but have an independent purpose.

pythcoiner commented at 12:59 AM on June 15, 2026: contributor

Hey, any update on this? Is there something I could help with? I was waiting for the open review to be addressed to take another look, but I wanted to check that we are not crossing our wires in regard to where it’s currently held up.

Thanks for the BIP # @murchandamus!

Sorry for late reply, I was a bit underwater on past weeks, I think all comments are adressed now.

murchandamus removed the label PR Author action required on Jun 16, 2026

in bip-0139.md:25 in 94fdbc5e6b

  20 | +conventions.
  21 | +All fields are optional except for the base structure, which must include at least one
  22 | +account entry.
  23 | +
  24 | +This BIP also acts as a central repository where a wallet implementer can register its
  25 | +usage of a field and share that usage through a test vector.

murchandamus commented at 6:03 PM on June 24, 2026:

I would advise against collecting fields in the BIP directly. We have had several BIPs in the past that were extensible in this form and in each case the authors eventually got tired of reviewing amendments to their BIP. I would suggest that you instead pursue a model like BIP174 (PSBT), where only the registering of the new fields in collected centrally in an auxiliary file for this express purpose, but fields have to be described in their own BIPs. — Maybe separate BIPs are a bit too high of a hurdle in this specific case and there could instead be a description of the fields in the registry directly, but I would heavily recommend not putting the onus of frequently needing to review BIP amendments on your future self.

pythcoiner commented at 5:46 AM on August 20, 2026:

i've moved all optional fields to a separate registry

in bip-0139.md:68 in 94fdbc5e6b

  63 | +representing the backup structure.  
  64 | +This object includes wallet-level metadata, multiple accounts, and associated key data.  
  65 | +
  66 | +### version
  67 | +
  68 | +This BIP defines version 1 of this specification.

murchandamus commented at 6:09 PM on June 24, 2026:

Nit: BIPs themselves have now an optional version header, so this may be confusing in the future if the document gets updated.

I assume you are talking about "version 1 of the backup format", i.e. the value stored with the version key in the backup, maybe this could be stated a bit more explicitly, though.

pythcoiner commented at 5:49 AM on August 20, 2026:

dropped this section and added in the header

in bip-0139.md:103 in 94fdbc5e6b

  98 | +- `type`: Optional string describing the account type.  
  99 | +  Possible values include `bip_380` (output descriptor), `bip_388` (wallet policies),
 100 | +  `bip_392` (silent payments), or any arbitrary string representing metadata needed to
 101 | +  find and spend coins for an account.  
 102 | +- `output_type`: Optional string describing the output category of the account.  
 103 | +  Values used by bitcoin core are `legacy`, `p2sh-segwit`, `bech32`, and `bech32m`.

murchandamus commented at 6:13 PM on June 24, 2026:

Spelled with capital letters just below (and should be spelled capitalized).

  Values used by Bitcoin Core are `legacy`, `p2sh-segwit`, `bech32`, and `bech32m`.

pythcoiner commented at 5:51 AM on August 20, 2026:

done

in bip-0139.md:108 in 94fdbc5e6b

 103 | +  Values used by bitcoin core are `legacy`, `p2sh-segwit`, `bech32`, and `bech32m`.  
 104 | +- `descriptor`: Optional string or object representing the account structure as
 105 | +  defined by the value in `type`.  
 106 | +- `change_descriptor`: Optional string or object representing an explicit change-side
 107 | +  descriptor, paired with `descriptor`. Intended for wallets that do not use BIP-389
 108 | +  multipath descriptors (e.g. Bitcoin Core).

murchandamus commented at 6:14 PM on June 24, 2026:

Ambiguous whether Bitcoin Core is an example or counter-example:

- `change_descriptor`: Optional string or object representing an explicit change-side
  descriptor, paired with `descriptor`. Intended for wallets that do not use BIP-389
  multipath descriptors (as e.g. Bitcoin Core does).

pythcoiner commented at 5:52 AM on August 20, 2026:

done

in bip-0139.md:111 in 94fdbc5e6b

 106 | +- `change_descriptor`: Optional string or object representing an explicit change-side
 107 | +  descriptor, paired with `descriptor`. Intended for wallets that do not use BIP-389
 108 | +  multipath descriptors (e.g. Bitcoin Core).  
 109 | +- `descriptor_id`: Optional string containing a stable hexadecimal identifier for the
 110 | +  receive `descriptor`. Its construction is implementation-defined, but it MUST be stable
 111 | +  across exports of the same descriptor.

murchandamus commented at 6:15 PM on June 24, 2026:

If you have an idea how to standardize descriptor identifiers, I think that might be a good BIP in itself to write.

cc: @achow101

pythcoiner commented at 5:54 AM on August 20, 2026:

i've dropped the fields, it was a Bitcoin Core internal thing, and as it's deterministic from the descriptor it can be rebuild on import

in bip-0139.md:171 in 94fdbc5e6b

 166 | +  See [Key Types](#key-types).  
 167 | +- `key_status`: Optional string describing the status of the key.  
 168 | +  See [Key Status](#key-status).  
 169 | +- `bip85_derivation_path`: Optional string describing the
 170 | +  [BIP-0085](https://github.com/bitcoin/bips/blob/master/bip-0085.mediawiki) derivation
 171 | +  path used to derive this key from the master key.

murchandamus commented at 6:21 PM on June 24, 2026:

It strikes me as odd that all fields here are optional. Is that intended? Perhaps there should be at least an "A or B is required"?

ethicnology commented at 11:22 AM on June 29, 2026:

I agree, defining a standard requires having mandatory requirements. Take BIP329 as an example: it has many optional fields that some wallets may not support (like "unspendable"), but you can still count on anyone implementing the BIP to support at least the required fields. If everything is optional, then everyone will only implement what they personally care about, and we lose any ability to enforce consistency.

pythcoiner commented at 5:54 AM on August 20, 2026:

I've made the key mandatory, as it should have been

murchandamus commented at 6:26 PM on June 24, 2026: member

Thanks for the update. I gave this another read and have a few more comments. Where do you see this document regarding your planned work. It seems like it is getting close to publication, if that fits your plans.

If you have some specific people in mind that should perhaps review this document, I could try to help get their attention.

pythcoiner force-pushed on Aug 20, 2026

pythcoiner commented at 12:08 PM on August 21, 2026: contributor

For reviewers: I've addressed comments, then ran a survey over 13 potentials wallets condidates (not meaning they have shown interest, just I picked them) the survey shows interesting frictions points so I reworked heavily the structure, It's almost done but I'll re-review early next week.

jonatack commented at 8:15 PM on August 21, 2026: member

Not a blocker, but if you have to re-push this diff should appease the CI typo checker.

--- a/.typos.toml
+++ b/.typos.toml
@@ -34,6 +34,7 @@ Toom = "Toom"
 
 [files]
 extend-exclude = [
+    "bip-0139/wallet_field_usage.md",
     "/*/*.csv",
     "/*/*.d*",
     "/*/*.go",

murchandamus commented at 10:35 PM on August 21, 2026: member

@pythcoiner: Thanks for the update. I take it that we should hold-off for our review until you have done another pass. Please let us know when you’re ready for us.

murchandamus added the label PR Author action required on Aug 21, 2026

pythcoiner force-pushed on Aug 27, 2026

pythcoiner commented at 1:51 AM on August 27, 2026: contributor

@murchandamus I've done my pass. There is a typo false positive in CI, I'm not sure out to fix it (it's a ba in a quoted commit hash)

murchandamus removed the label PR Author action required on Sep 21, 2026

in bip-0139.md:17 in b1e085c2f3

  12 | +```
  13 | +
  14 | +## Abstract
  15 | +
  16 | +This document specifies a format for exporting the metadata of a wallet: its accounts,
  17 | +descriptors, keys, signers, labels, transactions, coins, and partially signed Bitcoin

murchandamus commented at 6:10 PM on September 24, 2026:

Should this explicitly exclude private key material?

descriptors, public keys, signers, labels, transactions, coins, and partially signed Bitcoin

pythcoiner commented at 6:12 AM on October 21, 2026:

I'll replace by key informations because it's not limited to private/public keys

rezakhosravi971-bit commented at 4:52 AM on October 23, 2026:

Rezakhosravi971@gmail.com

in bip-0139.md:92 in b1e085c2f3

  87 | +A registry pull request may add or change optional fields only. The mandatory fields
  88 | +are fixed by this BIP, and making a field mandatory is a change to this BIP.  
  89 | +Registration of a new field must state the field name, the object it belongs to,
  90 | +its type, and a short description, and should link a test vector or an implementation
  91 | +using it when available.  
  92 | +A field name must not conflict with an already registered field of the same object.

murchandamus commented at 6:14 PM on September 24, 2026:

The lines in this paragraph each end in a linebreak, I stumbled on this, because it looks visually odd.

I have the impression, that this is intended as a list of instructions. Please consider format it as a list, if so, otherwise, perhaps consider removing the linebreaks.

in bip-0139.md:85 in b1e085c2f3

  80 | +### Field Registry
  81 | +
  82 | +The fields of every object structure are defined in the
  83 | +[field registry](bip-0139/field-registry.md) rather than in this document, so new
  84 | +fields could be added without amending this BIP.  
  85 | +The registry record every field and objects definitions, marks the mandatory ones,

murchandamus commented at 6:15 PM on September 24, 2026:

The registry records every field and objects definitions, marks the mandatory ones,

in bip-0139.md:103 in b1e085c2f3

  98 | +Its fields are listed in the [field registry](bip-0139/field-registry.md).  
  99 | +
 100 | +- `version`: Mandatory string identifying the format and its version.  
 101 | +  Must be `BIP139-<version>`, where `<version>` is an integer.
 102 | +  The version is incremented only for changes that are not backward compatible, such
 103 | +  as adding a mandatory field.

murchandamus commented at 6:20 PM on September 24, 2026:

This is a bit ambiguous. A wallet could for example also track how often it has been exported, to ease comparison of several backups of the same wallet.

- `version`: Mandatory string identifying the version of the backup format.  
  Must be `BIP139-<version>`, where `<version>` is an integer.
  The backup format version is incremented only for changes that are not backward compatible, such
  as adding a mandatory field.

in bip-0139.md:108 in b1e085c2f3 outdated

 103 | +  as adding a mandatory field.  
 104 | +- `network`: Mandatory string naming the network the export covers.  
 105 | +  Must be one of `bitcoin` (mainnet), `testnet3`, `testnet4`, `signet`, `mutinynet`
 106 | +  or `regtest`.  
 107 | +  An export covers a single network. A wallet holding accounts on more than one
 108 | +  writes one export per network.

murchandamus commented at 6:21 PM on September 24, 2026:

This reads as if it is providing a comprehensive list. Given that there is an open proposal for testnet5, how would it work when more networks are introduced in the future?

pythcoiner commented at 6:22 AM on October 21, 2026:

I think each new variant must be added in the list

in bip-0139.md:138 in b1e085c2f3

 133 | +### Signer Object Structure
 134 | +
 135 | +Each entry in the `signers` array describes one holder of key material: a hardware
 136 | +device, a piece of software, or a remote service. A signer must contain the
 137 | +`fingerprints` field, and the field must not be empty.
 138 | +Its fields are listed in the [field registry](bip-0139/field-registry.md).

murchandamus commented at 6:25 PM on September 24, 2026:

“Its” is underdefined. Is it referring to the Signer Object Structure? Please avoid using pronouns and instead explicitly reuse the concept to avoid ambiguity.

The Signer Object Structure’s fields are listed in the [field registry](bip-0139/field-registry.md).

in bip-0139.md:177 in b1e085c2f3

 172 | +
 173 | +### Coin Object Structure
 174 | +
 175 | +Each entry in the `coins` array is a JSON object describing a single output owned by
 176 | +the account and must contain the `outpoint` field.  
 177 | +Its fields are listed in the [field registry](bip-0139/field-registry.md).

murchandamus commented at 6:27 PM on September 24, 2026:

See above

in bip-0139.md:224 in b1e085c2f3

 219 | +
 220 | +## Reference Implementation
 221 | +
 222 | +TBD
 223 | +
 224 | +## Annex

murchandamus commented at 6:29 PM on September 24, 2026:

This section came as a surprise. Shouldn’t this be part of the Specification section?

in bip-0139.md:185 in b1e085c2f3

 180 | +decided about it. Silent payment outputs are coins too, and carry a `tweak` alongside
 181 | +the rest.
 182 | +
 183 | +- `outpoint`: Mandatory string representing the outpoint in the form `<txid>:<vout>`.  
 184 | +
 185 | +## Importing

murchandamus commented at 6:30 PM on September 24, 2026:

Should this be part of the Specification?

in bip-0139/field-registry.md:214 in b1e085c2f3

 209 | +|-------------------|----------|-----------|------------------------------------------------------|
 210 | +| por               | optional | string    | Proof of registration generated by stateless devices |
 211 | +|                   |          |           | such as Ledger.                                      |
 212 | +|-------------------|----------|-----------|------------------------------------------------------|
 213 | +| last_health_check | optional | timestamp | Timestamp of the last health check processed on this |
 214 | +|                   |          |           | device.                                              |

murchandamus commented at 6:32 PM on September 24, 2026:

All fields in the Device object are optional. What is used as the key?

murchandamus commented at 6:35 PM on September 24, 2026: member

Thanks for the updates. I gave the main document another review and noticed a few minor issues.

I glanced at the companion fields, and have the impression that some of the field definition could use more comprehensive descriptions to better disambiguate fields and to ensure that they would be used in the same manner by different implementations. I would imagine that some of this standardization work might follow from other projects adopting this format, but perhaps the BIP could get ahead of some of the questions.

jonatack commented at 7:25 PM on September 24, 2026: member

There is a typo false positive in CI, I'm not sure out to fix it (it's a ba in a quoted commit hash) @pythcoiner I don't reproduce it locally on this branch; I think you can ignore it.

pythcoiner commented at 6:30 AM on October 21, 2026: contributor

@murchandamus thanks for the review, addressing the review now

pythcoiner commented at 6:33 AM on October 21, 2026: contributor

This section came as a surprise. Shouldn’t this be part of the Specification section? @murchandamus I'll withdraw the survey from the spec, it was informational about how/why I reworked the whole structure.

I put the link of the survey here for record https://github.com/pythcoiner/bips/blob/bip_wallet_backup/bip-0139/wallet_field_usage.md

pythcoiner commented at 6:38 AM on October 21, 2026: contributor

All fields in the Device object are optional. What is used as the key? @murchandamus the devices field is an array, not a map so there is no key

pythcoiner commented at 6:56 AM on October 21, 2026: contributor

and have the impression that some of the field definition could use more comprehensive descriptions to better disambiguate fields and to ensure that they would be used in the same manner by different implementations. I would imagine that some of this standardization work might follow from other projects adopting this format, but perhaps the BIP could get ahead of some of the questions. @murchandamus which one you feel shoud be disambiguated? I think there is some fields that can be used slightly differently between implementations, I'll add an exporter field so an importer could have more context.

bip139: wallet metadata format 855a7150cd

bip139: add the Version header to the preamble 8c7e64225c

bip139: keep a single psbts field and fix the spend status link 4c15068441

bip139: fold the version section and bip field into the version value 4e2a5da0d5

bip139: capitalize Bitcoin Core and clarify the change_descriptor note 82db40f9c2

bip139: replace the three account birth time fields with birth_block f9e297397c

bip139: drop descriptor_id and change_descriptor_id 478d0e98d6

bip139: drop field aliases, keeping name and labels 30eb8d95c3

bip139: restrict descriptor and change_descriptor to a string d04b924fba

bip139: make version, type, descriptor, key, txid, outpoint and tweak mandatory 5ac336c548

bip139: move field definitions to a companion registry 9032cc2fed

bip139: add the wallet survey behind these decisions 56e611323b

bip139: replace the wallet description field with a backup note 7d1eda5847

bip139: add the backup date field 6aa97c1671

bip139: add the account gap_limit field edefed9efa

bip139: add the multi_bip380 account type 791d922c68

bip139: give the bip352_labels range an explicit encoding a84f1e7247

bip139: add a general coin object c062e2042c

bip139: move signers above the account 20e3ea9c0a

bip139: add signer modality and device records 19ee5f5a70

bip139: add bip85 application and index c459f5f084

bip139: add Bitkey to the wallet survey 7622a44e3f

bip139: state how to derive birth_block from a creation date 5a6bcaafda

bip139: define the timestamp format once 2dd0e3787c

bip139: rename the transaction time field to block_time ddc294b068

bip139: keep last_height on the account only 79b11e4d61

bip139: state that type names the descriptor language f2d531f4aa

bip139: drop output_type, the descriptor already states it 1b58ead616

bip139: replace the account active flag with a status enum 84a3294a71

bip139: add mutinynet and scope a backup to one network f9e8f51f8e

bip139: record that the label gap belongs to BIP-329 d1f49bfe04

bip139: record that proprietary needs no change 6ef620d5fe

bip139: make the survey annex-ready f824bc7549

bip139: record that mainnet mnemonics stay out of scope 339fac9edc

bip139: reword the mnemonic evidence heading 46a4553e32

bip139: correct the birth_block evidence, Sparrow stores a height 3c7fc944ca

bip139: type and descriptor fit every surveyed wallet 4dafb16a0b

bip139: correct the addr descriptor solvability note 73fdb7f3d8

bip139: re-assess every partial score against fillability af456e9745

bip139: store psbts once at wallet level, reference them per account 63e6887134

bip139: store transactions once at wallet level, reference them per account 45752721f9

bip139: txid is the transaction map key, not a field 09e1ffc003

bip139: refresh the matrix after the fillability re-assessment 617e94ac20

bip139: electrum holds no bip39 mnemonic at all 0c4e23276d

bip139: sp_output.label has no constituency 392f9f81a1

bip139: collapse the survey to a two-value scale bf260a9cf4

bip139: drop the obsolete partial-score analysis feadd593c6

bip139: size the matrix field column from the data 06c0278206

bip139: cut the survey down to the table and its results 2d62acfe8e

bip139: recompute liana compat against the current draft 408715c0e8

bip139: correct the liana breaking-change count 9c23dd7e98

bip139: make network mandatory 5d992a5eec

bip139: network no longer breaks liana on import e28ae81cac

bip139: render wallet fields as a wrapped table ab02f091b1

bip139: render account fields as a wrapped table 2750670a53

bip139: render every field section as a wrapped table 68e40dc805

bip139: the registry is part of the bip, not a reference to it 425f90e672

bip139: drop the registration process from the registry intro c2f5091621

bip139: put field rationale in the cell, not below the table 01060d2a3a

bip139: keep code spans whole when wrapping cells 067ebe11dc

bip139: render field tables as preformatted blocks 6a3360e45f

bip139: drop link definitions the tables no longer use dcdf7d7dc4

bip139: use a bordered grid for the field tables a4fa09f2fa

bip139: give birth_block an estimation formula and drop the enum underscore 17ed733dbe

bip139: merge silent payment outputs into the coin object 7e7e6613a2

bip139: restore spend_status and give the sp label scalar a home adb28e3e12

bip139: register the transaction fee field ce2d97a16e

bip139: rebuild the survey matrix against the current field set 95cfe49cc0

bip139: drop survey findings the draft now addresses bcbe76bfc9

bip139: bar passphrase-protected seeds from bip39_mnemonic 7394f19c41

bip139: record the missing-field decisions in the survey 8a315884b9

bip139: cut the survey down to its revision list and matrix 0d26ff0173

bip139: reword the survey as a wallet to field mapping f29aa31d69

bip139: reference the wallet support annex from the spec 8bc5d277f0

bip139: list the mandatory fields in the registry tables 388a32f2ef

bip139: point the spec at the registry as the complete field list d5a0e09241

bip139: spell out mandatory and optional in the registry req column e6969ea52c

bip139: mark only the optional fields in the registry tables 2e5784a5bf

bip139: retitle and reframe the BIP around moving between wallets 8a3eecbe87

bip139: call the artefact an export throughout 6a24472892

bip139: scope the mnemonic advice to exports kept as backups c251738919

bip139: say that most metadata cannot be recovered from the chain 33d46937a8

bip139: clarify account and signer metadata fields 5ebe9df6f9

bip139: cut the registry cells back to the field description bfa8ab3478

bip139: reword the registry field descriptions d0d3df1224

bip139: give the device record its own registry table 9c724fe1cc

bip139: keep an unknown enum value from failing the import 8cb7761c33

bip139: define the device transports field 6b790b712d

bip139: point the devices row at the device object be1255554d

bip139: backup -> export in README 3682925f29

bip139: clarify export fields and remove survey annex 6f737f21da

pythcoiner force-pushed on Oct 21, 2026

pythcoiner commented at 9:46 AM on October 21, 2026: contributor

adressed comment + small changes + rebased

murchandamus commented at 11:33 PM on October 23, 2026: member

and have the impression that some of the field definition could use more comprehensive descriptions to better disambiguate fields and to ensure that they would be used in the same manner by different implementations. I would imagine that some of this standardization work might follow from other projects adopting this format, but perhaps the BIP could get ahead of some of the questions.

@murchandamus which one you feel shoud be disambiguated? I think there is some fields that can be used slightly differently between implementations, I'll add an exporter field so an importer could have more context.

Sorry, I just read over the field-registry.md again, and whatever made me write that didn’t jump out at me again.

murchandamus commented at 11:35 PM on October 23, 2026: member

I think this could be ready to be merged in Draft status. What do you think?

pythcoiner commented at 1:45 PM on October 24, 2026: contributor

@murchandamus I think so!

in bip-0139.md:11 in 6f737f21da

   6 | +  Status: Draft
   7 | +  Type: Specification
   8 | +  Assigned: 2026-05-11
   9 | +  License: BSD-2-Clause
  10 | +  Discussion: https://groups.google.com/g/bitcoindev/c/ylPeOnEIhO8
  11 | +  Version: 0.1.0

murchandamus commented at 3:00 PM on October 24, 2026:

The Version header records the latest version bump from the Changelog section, but this document doesn’t have a Changelog.

Drop Version header in absence of Changelog db5f8c8ad8

murchandamus merged this on Oct 24, 2026

murchandamus closed this on Oct 24, 2026

murchandamus commented at 3:13 PM on October 24, 2026: member

Alright, I dropped the Version header, because the document doesn’t have a Changelog and merged BIP139. Thanks for hanging in there!