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

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

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.

bip139: wallet metadata format 94fdbc5e6b

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