BIP139: Wallet Metadata Backup Format by pythcoiner · Pull Request #2130 · bitcoin/bips

pythcoiner · 2026-03-27T10:39:35Z

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

murchandamus · 2026-03-27T13:34:15Z

Could you perhaps expound the relationship to #1951?

seedhammer

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

seedhammer · 2026-04-03T11:26:48Z

+- `timestamp`: Optional integer Unix timestamp representing account creation time in
+  seconds.  
+- `iso_8601_datetime`: optional string representing account creation time in ISO 8601
+  format.  
+- `block_height`: Optional integer representing account creation time in bitcoin block
+  height unit.  


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.

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

seedhammer · 2026-04-03T11:33:52Z

+- `version`: Optional integer version of the backup format.  
+- `bip`: Optional integer value representing the number of this BIP.  
+- `name`: Optional string wallet name.  
+  NOTE: `alias` is an alias of `name`.  


Why mention alias in a new BIP?

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

seedhammer · 2026-04-03T11:35:10Z

+- `name`: Optional string account name.  
+  NOTE: `alias` is an alias of `name`.  
+- `description`: Optional string account description.  
+- `active`: Optional boolean field indicating if the account is active.  


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.

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

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

seedhammer · 2026-04-03T11:36:04Z

+- `bip39_mnemonic`: Optional string containing mnemonic words following BIP39.  
+  Since backups may be stored online, storing mainnet mnemonics is strongly discouraged.  


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

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.

seedhammer · 2026-04-03T11:37:17Z

+- `network`: Optional string network identifier.  
+  Valid values are `bitcoin` (mainnet), `testnet3`, `testnet4`, `signet`, and `regtest`.  


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

cf previous message for rationale

murchandamus · 2026-04-06T18:51:13Z

Thanks for reviewing related work, @seedhammer!

pythcoiner · 2026-04-07T07:36:42Z

Thanks for review @seedhammer, I'll reply inline

pythcoiner · 2026-04-07T08:23:11Z

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 BIP393: Output Script Descriptor Annotations #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 · 2026-04-07T08:34:30Z

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 · 2026-04-07T16:03:41Z

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

pythcoiner · 2026-04-09T08:56:17Z

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

pythcoiner · 2026-04-09T09:38:20Z

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

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.

pythcoiner · 2026-04-29T06:53:50Z

@murchandamus thanks for your review, comments addressed.

murchandamus · 2026-05-11T19:45:40Z

Assigned BIP139

murchandamus · 2026-05-11T20:08:07Z

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

murchandamus · 2026-05-11T20:14:44Z

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


Suggested change

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

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

Sjors · 2026-05-26T12:08:28Z

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 · 2026-06-12T18:09:27Z

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 · 2026-06-15T00:57:28Z

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 · 2026-06-15T00:59:22Z

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.

pythcoiner force-pushed the bip_wallet_backup branch 3 times, most recently from aa3b808 to 45b4a5b Compare March 27, 2026 12:54

seedhammer reviewed Apr 3, 2026

View reviewed changes

pythcoiner force-pushed the bip_wallet_backup branch from 45b4a5b to 4b692ac Compare April 8, 2026 07:10

johnny9 mentioned this pull request Apr 8, 2026

Socratic Seminar #51 TriangleBitDevs/TriangleBitDevs.github.io#52

Closed

pythcoiner force-pushed the bip_wallet_backup branch from 4b692ac to 761dd17 Compare April 9, 2026 08:53

pythcoiner force-pushed the bip_wallet_backup branch from 761dd17 to aeee423 Compare April 9, 2026 09:36

murchandamus added the New BIP label Apr 14, 2026

pythcoiner force-pushed the bip_wallet_backup branch from aeee423 to 32a6893 Compare April 24, 2026 06:43

pythcoiner marked this pull request as ready for review April 24, 2026 07:29

murchandamus reviewed Apr 28, 2026

View reviewed changes

Comment thread bip-wallet-backup.md Outdated

Comment thread bip-wallet-backup.md Outdated

Comment thread bip-wallet-backup.md Outdated

murchandamus reviewed Apr 28, 2026

View reviewed changes

Comment thread bip-wallet-backup.md Outdated

pythcoiner force-pushed the bip_wallet_backup branch 2 times, most recently from 3d74fd1 to 1fc70c4 Compare April 29, 2026 06:51

murchandamus force-pushed the bip_wallet_backup branch from 1fc70c4 to 087708d Compare May 11, 2026 19:44

murchandamus changed the title ~~Bip draft: Wallet Backup Metadata Format~~ BIP139: Wallet Backup Metadata Format May 11, 2026

murchandamus force-pushed the bip_wallet_backup branch 2 times, most recently from b0b0667 to b17c8a5 Compare May 11, 2026 20:06

murchandamus changed the title ~~BIP139: Wallet Backup Metadata Format~~ BIP139: Wallet Metadata Backup Format May 11, 2026

murchandamus reviewed May 11, 2026

View reviewed changes

murchandamus added the PR Author action required Needs updates, has unaddressed review comments, or is otherwise waiting for PR author label May 19, 2026

murchandamus mentioned this pull request May 20, 2026

BIP Draft: Standard Encrypted Wallet Payload #1981

Open

Sjors mentioned this pull request May 26, 2026

BIP138: Compact Encryption Scheme for Non-seed Wallet Data #1951

Open

bip139: wallet metadata format

94fdbc5

pythcoiner force-pushed the bip_wallet_backup branch from b17c8a5 to 94fdbc5 Compare June 15, 2026 00:25

murchandamus removed the PR Author action required Needs updates, has unaddressed review comments, or is otherwise waiting for PR author label Jun 16, 2026

		- `bip39_mnemonic`: Optional string containing mnemonic words following BIP39.
		Since backups may be stored online, storing mainnet mnemonics is strongly discouraged.

		- `network`: Optional string network identifier.
		Valid values are `bitcoin` (mainnet), `testnet3`, `testnet4`, `signet`, and `regtest`.


		## Encryption

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

Conversation

pythcoiner commented Mar 27, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

murchandamus commented Mar 27, 2026

Uh oh!

seedhammer left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

murchandamus commented Apr 6, 2026

Uh oh!

pythcoiner commented Apr 7, 2026

Uh oh!

pythcoiner commented Apr 7, 2026

Uh oh!

pythcoiner commented Apr 7, 2026

Uh oh!

murchandamus commented Apr 7, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

pythcoiner commented Apr 9, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

pythcoiner commented Apr 9, 2026

Uh oh!

murchandamus left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

pythcoiner commented Apr 29, 2026

Uh oh!

murchandamus commented May 11, 2026

Uh oh!

murchandamus commented May 11, 2026

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Sjors commented May 26, 2026

Uh oh!

murchandamus commented Jun 12, 2026

Uh oh!

pythcoiner commented Jun 15, 2026

Uh oh!

pythcoiner commented Jun 15, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

pythcoiner commented Mar 27, 2026 •

edited

Loading

murchandamus commented Apr 7, 2026 •

edited

Loading

pythcoiner commented Apr 9, 2026 •

edited

Loading