Skip to content

Commit aa3b808

Browse files
pythcoinerpythcoiner
committed
wallet metadata format
1 parent 9a30c28 commit aa3b808

1 file changed

Lines changed: 240 additions & 0 deletions

File tree

‎bip-wallet-backup.md‎

Lines changed: 240 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,240 @@
1+
```
2+
BIP: ?
3+
Layer: Applications.
4+
Title: Wallet Backup Metadata Format.
5+
Author: Pyth <pyth@pythcoiner.dev>.
6+
Status: Draft.
7+
Type: Standards Track.
8+
Created: 2025-01-23.
9+
License: BSD-2-Clause.
10+
Post-History: https://groups.google.com/g/bitcoindev/c/ylPeOnEIhO8
11+
```
12+
13+
## Abstract.
14+
15+
This document specifies a format for exporting wallet backup data, including accounts,
16+
descriptors, associated keys, labels, transactions, and partially signed Bitcoin
17+
transactions (PSBTs).
18+
The format aims to standardize wallet backup and restore operations across different
19+
Bitcoin wallet implementations by providing a common structure and field naming
20+
conventions.
21+
All fields are optional except for the base structure, which must include at least one
22+
account entry.
23+
24+
## Copyright.
25+
26+
This BIP is licensed under the BSD 2-clause license.
27+
28+
## Motivation.
29+
30+
Bitcoin software wallets store various forms of metadata beyond just private keys,
31+
including account structures, descriptors, labels, and transaction history.
32+
While [BIP-0039](https://github.com/bitcoin/bips/blob/master/bip-0039.mediawiki)
33+
and [BIP-0032](https://github.com/bitcoin/bips/blob/master/bip-0032.mediawiki) provide
34+
standardized mechanisms for key recovery, they do not preserve additional wallet-specific
35+
metadata necessary for seamless migration between wallets.
36+
37+
A standardized wallet backup format ensures that users can migrate wallets without losing
38+
critical metadata, reducing vendor lock-in and enabling more robust recovery options.
39+
This BIP serves as a central repository where wallet developers can document their usage
40+
of the global format, improving interoperability without forcing a specific
41+
implementation.
42+
43+
## Rationale.
44+
45+
Several wallet implementations store backup data in proprietary formats, making migration
46+
difficult.
47+
This proposal introduces a structured, human-readable format, leveraging JSON to store
48+
wallet metadata in a portable way.
49+
The format is flexible and extensible, allowing wallet developers to include as much or
50+
as little information as they think necessary.
51+
52+
By making all fields optional except for the base structure with at least one account,
53+
this standard accommodates diverse use cases and preferences.
54+
Wallet developers can include only the fields relevant to their application while
55+
maintaining structural integrity.
56+
57+
## Specification.
58+
59+
A wallet backup is a UTF-8 encoded text file containing a single valid JSON object
60+
representing the backup structure.
61+
This object includes wallet-level metadata, multiple accounts, and associated key data.
62+
63+
### version.
64+
65+
This BIP defines version 1 of this specification.
66+
67+
### Wallet Backup Structure.
68+
69+
The top-level JSON object must contain at least one account in the `accounts` array.
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`.
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`.
82+
- `proprietary`: Optional JSON object storing application-specific metadata.
83+
84+
### Account Object Structure.
85+
86+
Each account object in the `accounts` array represents a single account within the wallet.
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.
93+
- `type`: Optional string describing the account type.
94+
Possible values include `bip_380` (output descriptor), `bip_388` (wallet policies),
95+
`bip_392` (silent payments), or any arbitrary string representing metadata needed to
96+
find and spend coins for an account.
97+
- `descriptor`: Optional string or object representing the account structure as
98+
defined by the value in `type`.
99+
- `receive_index`: Optional integer representing the maximum receive index for generated
100+
receive addresses.
101+
- `change_index`: Optional integer representing the maximum change index for generated
102+
change addresses.
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.
109+
- `last_height`: Optional integer representing the last seen block height.
110+
- `bip352_labels`: Optional array of silent payments labels (`[0,1,2]`), or range (`{0-10}`).
111+
- `keys`: Optional object mapping descriptor key fingerprints to key metadata objects.
112+
See [Key Object Structure](#key-object-structure).
113+
- `bip329_labels`: Optional array containing label structures for transactions, addresses, and
114+
keys following [BIP-0329](https://github.com/bitcoin/bips/blob/master/bip-0329.mediawiki).
115+
NOTE: `labels` is an alias of `bip329_labels`.
116+
- `transactions`: Optional array containing transactions.
117+
Wallets may include only transactions spending coins controlled by the account, only
118+
transactions funding controlled coins, or only their corresponding outpoints.
119+
- `bip352_outputs`: Optional array of
120+
[Silent Payment Owned Output Object Structure](#silent-payment-owned-output-object-structure).
121+
- `bip174_psbts`: Optional array containing unspent but partially signed transactions as defined
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.
128+
- `proprietary`: Optional JSON object storing account-specific metadata.
129+
130+
### Key Object Structure.
131+
132+
Keys in the `keys` dictionary are indexed by their
133+
[BIP32 fingerprint](https://github.com/bitcoin/bips/blob/master/bip-0032.mediawiki#key-identifiers).
134+
Each key object contains metadata about the key.
135+
136+
- `key`: Optional string representing the public key fingerprint in hexadecimal form.
137+
- `alias`: Optional string user-defined alias for the key.
138+
- `role`: Optional string role of the key in wallet operations.
139+
See [Key Roles](#key-roles).
140+
- `key_type`: Optional string describing ownership of the key.
141+
See [Key Types](#key-types).
142+
- `key_status`: Optional string describing the status of the key.
143+
See [Key Status](#key-status).
144+
- `bip85_derivation_path`: Optional string describing the
145+
[BIP-0085](https://github.com/bitcoin/bips/blob/master/bip-0085.mediawiki) derivation
146+
path used to derive this key from the master key.
147+
148+
### Key Roles.
149+
150+
The `role` field may contain one of the following values.
151+
152+
- `main`: Key used for normal spending conditions.
153+
- `recovery`: Key designated for recovery scenarios.
154+
- `inheritance`: Key to inherit funds if the primary user disappears.
155+
- `cosigning`: Key designated for policy-enforcing cosigning.
156+
157+
### Key Types.
158+
159+
The `key_type` field may contain one of the following values.
160+
161+
- `internal`: Main user-owned key.
162+
- `external`: Key held by heirs or trusted individuals.
163+
- `third_party`: Key held by a service provider.
164+
165+
### Key Status.
166+
167+
The `key_status` field may contain one of the following values.
168+
169+
- `active`: The key is actively used.
170+
- `inactive`: The key is not yet actively used.
171+
- `revoked`: The key has been revoked and MUST NOT be used anymore.
172+
173+
### Silent Payment Owned Output Object Structure.
174+
175+
- `outpoint`: Optional string representing the outpoint in the form `<txid>:<vout>`.
176+
- `block_height`: Optional integer representing the height of the block containing
177+
the transaction.
178+
NOTE: if `block_height` value is `null`, it means the outpoints belongs to an
179+
unconfirmed transaction at the time of backup.
180+
- `tweak`: Optional hexadecimal string representing the tweak.
181+
- `amount`: Optional integer representing the output amount value in sats.
182+
- `script`: Optional hexadecimal string representing the spending script for this
183+
outpoint.
184+
- `label`: Optional string representing a label attached to this output, similar to
185+
BIP-0329 label.
186+
- `spend_status`: Optional string describing the spend status of the output.
187+
See [Spend status](#spend-status).
188+
189+
### Spend Status.
190+
191+
The `spend_status` field may contain one of the following values.
192+
193+
- `unconfirmed`: The transaction is broadcast but not yet confirmed in a block.
194+
- `replaced`: The transaction has been replaced by a transaction confirmed in a block.
195+
- `unspent`: The transaction has been confirmed in a block and the output is unspent.
196+
- `spent`: The transaction has been confirmed in a block and the output is spent.
197+
198+
## Importing.
199+
200+
When importing a wallet backup follow these guidelines.
201+
202+
* Importing wallets should preserve all metadata they support and discard unsupported
203+
fields.
204+
* Wallets should warn users if essential data cannot be restored.
205+
* Wallets should ensure that key roles and types are properly mapped to their internal
206+
structures if used.
207+
* Wallets may truncate labels or other string fields if necessary, but should warn users
208+
when truncation occurs.
209+
* Wallets should validate the structure and ensure at least one account is present before
210+
attempting import.
211+
212+
## Security Considerations.
213+
214+
* The backup format should not include private keys to avoid unintended key exposure.
215+
* Backups should be encrypted to prevent unauthorized access.
216+
* Care should be taken to ensure that proprietary metadata does not contain sensitive
217+
information.
218+
* Since backups may be stored online or in cloud storage, storing mainnet mnemonics or
219+
private keys is strongly discouraged.
220+
221+
## Backwards Compatibility.
222+
223+
This format is extensible and allows future additions without breaking compatibility.
224+
Wallets may ignore fields they do not recognize while maintaining the structural
225+
integrity of the backup.
226+
Future revisions may add fields, and wallets should gracefully handle unknown entries by
227+
ignoring them.
228+
229+
## Reference Implementation.
230+
231+
TBD.
232+
233+
## References.
234+
235+
* [BIP-0032: Hierarchical Deterministic Wallets](https://github.com/bitcoin/bips/blob/master/bip-0032.mediawiki).
236+
* [BIP-0039: Mnemonic code for generating deterministic keys](https://github.com/bitcoin/bips/blob/master/bip-0039.mediawiki).
237+
* [BIP-0174: Partially Signed Bitcoin Transaction Format](https://github.com/bitcoin/bips/blob/master/bip-0174.mediawiki).
238+
* [BIP-0329: Wallet Labels Export Format](https://github.com/bitcoin/bips/blob/master/bip-0329.mediawiki).
239+
* [BIP-0380: Output Script Descriptors](https://github.com/bitcoin/bips/blob/master/bip-0380.mediawiki).
240+
* [BIP-0085: Deterministic Entropy From BIP32 Keychains](https://github.com/bitcoin/bips/blob/master/bip-0085.mediawiki).

0 commit comments

Comments
 (0)