Bip draft: Wallet Backup Metadata Format #2130

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

This is a bip for encrypted backup, an encryption scheme for bitcoin wallet related metadata.

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-wallet-backup.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-wallet-backup.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-wallet-backup.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-wallet-backup.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.

in bip-wallet-backup.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: none

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: none

Thanks for review @seedhammer, I'll reply inline

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

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: none

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: none

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

wallet metadata format aeee423e94

pythcoiner force-pushed on Apr 9, 2026

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

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