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

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

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.

murchandamus

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.

murchandamus · 2026-06-24T18:03:45Z

+This BIP also acts as a central repository where a wallet implementer can register its
+usage of a field and share that usage through a test vector.


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.

murchandamus · 2026-06-24T18:09:58Z

+### version
+
+This BIP defines version 1 of this specification.  


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.

murchandamus · 2026-06-24T18:13:31Z

+  `bip_392` (silent payments), or any arbitrary string representing metadata needed to
+  find and spend coins for an account.  
+- `output_type`: Optional string describing the output category of the account.  
+  Values used by bitcoin core are `legacy`, `p2sh-segwit`, `bech32`, and `bech32m`.  


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

Suggested change

Values used by bitcoin core are `legacy`, `p2sh-segwit`, `bech32`, and `bech32m`.

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

murchandamus · 2026-06-24T18:14:34Z

+- `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 (e.g. Bitcoin Core).  


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

Suggested change

- `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 (e.g. Bitcoin Core).

- `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).

murchandamus · 2026-06-24T18:15:28Z

+- `descriptor_id`: Optional string containing a stable hexadecimal identifier for the
+  receive `descriptor`. Its construction is implementation-defined, but it MUST be stable
+  across exports of the same descriptor.  


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

cc: @achow101

murchandamus · 2026-06-24T18:18:56Z

+- `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.  


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

murchandamus · 2026-06-24T18:21:02Z

+- `key`: Optional string representing the public key fingerprint in hexadecimal form.  
+- `alias`: Optional string user-defined alias for the key.  
+- `role`: Optional string role of the key in wallet operations.  
+  See [Key Roles](#key-roles).  
+- `key_type`: Optional string describing ownership of the key.  
+  See [Key Types](#key-types).  
+- `key_status`: Optional string describing the status of the key.  
+  See [Key Status](#key-status).  
+- `bip85_derivation_path`: Optional string describing the
+  [BIP-0085](https://github.com/bitcoin/bips/blob/master/bip-0085.mediawiki) derivation
+  path used to derive this key from the master key.  


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"?

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

murchandamus reviewed Jun 24, 2026

View reviewed changes

		- `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).

		This BIP also acts as a central repository where a wallet implementer can register its
		usage of a field and share that usage through a test vector.

		### version

		This BIP defines version 1 of this specification.

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

Uh oh!

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!

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!

murchandamus left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

pythcoiner commented Mar 27, 2026 •

edited

Loading

murchandamus commented Apr 7, 2026 •

edited

Loading

pythcoiner commented Apr 9, 2026 •

edited

Loading