diff --git a/bip-wallet-backup.md b/bip-wallet-backup.md new file mode 100644 index 0000000000..f0ed2d1576 --- /dev/null +++ b/bip-wallet-backup.md @@ -0,0 +1,240 @@ +``` +BIP: ? +Layer: Applications. +Title: Wallet Backup Metadata Format. +Author: Pyth . +Status: Draft. +Type: Specification. +Created: 2025-01-23. +License: BSD-2-Clause. +Post-History: https://groups.google.com/g/bitcoindev/c/ylPeOnEIhO8 +``` + +## Abstract. + +This document specifies a format for exporting wallet backup data, including accounts, +descriptors, associated keys, labels, transactions, and partially signed Bitcoin +transactions (PSBTs). +The format aims to standardize wallet backup and restore operations across different +Bitcoin wallet implementations by providing a common structure and field naming +conventions. +All fields are optional except for the base structure, which must include at least one +account entry. + +## Copyright. + +This BIP is licensed under the BSD 2-clause license. + +## Motivation. + +Bitcoin software wallets store various forms of metadata beyond just private keys, +including account structures, descriptors, labels, and transaction history. +While [BIP-0039](https://github.com/bitcoin/bips/blob/master/bip-0039.mediawiki) +and [BIP-0032](https://github.com/bitcoin/bips/blob/master/bip-0032.mediawiki) provide +standardized mechanisms for key recovery, they do not preserve additional wallet-specific +metadata necessary for seamless migration between wallets. + +A standardized wallet backup format ensures that users can migrate wallets without losing +critical metadata, reducing vendor lock-in and enabling more robust recovery options. +This BIP serves as a central repository where wallet developers can document their usage +of the global format, improving interoperability without forcing a specific +implementation. + +## Rationale. + +Several wallet implementations store backup data in proprietary formats, making migration +difficult. +This proposal introduces a structured, human-readable format, leveraging JSON to store +wallet metadata in a portable way. +The format is flexible and extensible, allowing wallet developers to include as much or +as little information as they think necessary. + +By making all fields optional except for the base structure with at least one account, +this standard accommodates diverse use cases and preferences. +Wallet developers can include only the fields relevant to their application while +maintaining structural integrity. + +## Specification. + +A wallet backup is a UTF-8 encoded text file containing a single valid JSON object +representing the backup structure. +This object includes wallet-level metadata, multiple accounts, and associated key data. + +### version. + +This BIP defines version 1 of this specification. + +### Wallet Backup Structure. + +The top-level JSON object must contain at least one account in the `accounts` array. +All other fields are optional. + +- `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`. +- `description`: Optional string wallet description. +- `accounts`: Mandatory array of account objects. + Must contain at least one account. + See [Account Object Structure](#account-object-structure). +- `network`: Optional string network identifier. + Valid values are `bitcoin` (mainnet), `testnet3`, `testnet4`, `signet`, and `regtest`. +- `proprietary`: Optional JSON object storing application-specific metadata. + +### Account Object Structure. + +Each account object in the `accounts` array represents a single account within the wallet. +All fields are optional, allowing wallets to include only the metadata they support. + +- `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. +- `type`: Optional string describing the account type. + Possible values include `bip_380` (output descriptor), `bip_388` (wallet policies), + `bip_392` (silent payments), or any arbitrary string representing metadata needed to + find and spend coins for an account. +- `descriptor`: Optional string or object representing the account structure as + defined by the value in `type`. +- `receive_index`: Optional integer representing the maximum receive index for generated + receive addresses. +- `change_index`: Optional integer representing the maximum change index for generated + change addresses. +- `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. +- `last_height`: Optional integer representing the last seen block height. +- `bip352_labels`: Optional array of silent payments labels (`[0,1,2]`), or range (`{0-10}`). +- `keys`: Optional object mapping descriptor key fingerprints to key metadata objects. + See [Key Object Structure](#key-object-structure). +- `bip329_labels`: Optional array containing label structures for transactions, addresses, and + keys following [BIP-0329](https://github.com/bitcoin/bips/blob/master/bip-0329.mediawiki). + NOTE: `labels` is an alias of `bip329_labels`. +- `transactions`: Optional array containing transactions. + Wallets may include only transactions spending coins controlled by the account, only + transactions funding controlled coins, or only their corresponding outpoints. +- `bip352_outputs`: Optional array of + [Silent Payment Owned Output Object Structure](#silent-payment-owned-output-object-structure). +- `bip174_psbts`: Optional array containing unspent but partially signed transactions as defined + by [BIP-0174](https://github.com/bitcoin/bips/blob/master/bip-0174.mediawiki). +- `bip370_psbts`: Optional array containing unspent but partially signed transactions as defined + by [BIP-0370](https://github.com/bitcoin/bips/blob/master/bip-370.mediawiki). +- `psbts`: Optinnal array than can contains both BIP-0174 & BIP-0370 PSBTs. +- `bip39_mnemonic`: Optional string containing mnemonic words following BIP39. + Since backups may be stored online, storing mainnet mnemonics is strongly discouraged. +- `proprietary`: Optional JSON object storing account-specific metadata. + +### Key Object Structure. + +Keys in the `keys` dictionary are indexed by their +[BIP32 fingerprint](https://github.com/bitcoin/bips/blob/master/bip-0032.mediawiki#key-identifiers). +Each key object contains metadata about the key. + +- `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. + +### Key Roles. + +The `role` field may contain one of the following values. + +- `main`: Key used for normal spending conditions. +- `recovery`: Key designated for recovery scenarios. +- `inheritance`: Key to inherit funds if the primary user disappears. +- `cosigning`: Key designated for policy-enforcing cosigning. + +### Key Types. + +The `key_type` field may contain one of the following values. + +- `internal`: Main user-owned key. +- `external`: Key held by heirs or trusted individuals. +- `third_party`: Key held by a service provider. + +### Key Status. + +The `key_status` field may contain one of the following values. + +- `active`: The key is actively used. +- `inactive`: The key is not yet actively used. +- `revoked`: The key has been revoked and MUST NOT be used anymore. + +### Silent Payment Owned Output Object Structure. + +- `outpoint`: Optional string representing the outpoint in the form `:`. +- `block_height`: Optional integer representing the height of the block containing + the transaction. + NOTE: if `block_height` value is `null`, it means the outpoints belongs to an + unconfirmed transaction at the time of backup. +- `tweak`: Optional hexadecimal string representing the tweak. +- `amount`: Optional integer representing the output amount value in sats. +- `script`: Optional hexadecimal string representing the spending script for this + outpoint. +- `label`: Optional string representing a label attached to this output, similar to + BIP-0329 label. +- `spend_status`: Optional string describing the spend status of the output. + See [Spend status](#spend-status). + +### Spend Status. + +The `spend_status` field may contain one of the following values. + +- `unconfirmed`: The transaction is broadcast but not yet confirmed in a block. +- `replaced`: The transaction has been replaced by a transaction confirmed in a block. +- `unspent`: The transaction has been confirmed in a block and the output is unspent. +- `spent`: The transaction has been confirmed in a block and the output is spent. + +## Importing. + +When importing a wallet backup follow these guidelines. + +* Importing wallets should preserve all metadata they support and discard unsupported + fields. +* Wallets should warn users if essential data cannot be restored. +* Wallets should ensure that key roles and types are properly mapped to their internal + structures if used. +* Wallets may truncate labels or other string fields if necessary, but should warn users + when truncation occurs. +* Wallets should validate the structure and ensure at least one account is present before + attempting import. + +## Security Considerations. + +* The backup format should not include private keys to avoid unintended key exposure. +* Backups should be encrypted to prevent unauthorized access. +* Care should be taken to ensure that proprietary metadata does not contain sensitive + information. +* Since backups may be stored online or in cloud storage, storing mainnet mnemonics or + private keys is strongly discouraged. + +## Backwards Compatibility. + +This format is extensible and allows future additions without breaking compatibility. +Wallets may ignore fields they do not recognize while maintaining the structural +integrity of the backup. +Future revisions may add fields, and wallets should gracefully handle unknown entries by +ignoring them. + +## Reference Implementation. + +TBD. + +## References. + +* [BIP-0032: Hierarchical Deterministic Wallets](https://github.com/bitcoin/bips/blob/master/bip-0032.mediawiki). +* [BIP-0039: Mnemonic code for generating deterministic keys](https://github.com/bitcoin/bips/blob/master/bip-0039.mediawiki). +* [BIP-0174: Partially Signed Bitcoin Transaction Format](https://github.com/bitcoin/bips/blob/master/bip-0174.mediawiki). +* [BIP-0329: Wallet Labels Export Format](https://github.com/bitcoin/bips/blob/master/bip-0329.mediawiki). +* [BIP-0380: Output Script Descriptors](https://github.com/bitcoin/bips/blob/master/bip-0380.mediawiki). +* [BIP-0085: Deterministic Entropy From BIP32 Keychains](https://github.com/bitcoin/bips/blob/master/bip-0085.mediawiki).