This document specifies a format for exporting the metadata of a wallet: its accounts,\ndescriptors, key information, signers, labels, transactions, coins, and partially signed\nBitcoin transactions (PSBTs).\nThe format gives these records a common structure and common field names, so that\nwhat one wallet application writes another can read.\nEach object structure defines a few mandatory fields; all other fields are optional.\nThe base structure must include at least one account entry.
\nThe fields of the format are collected in a companion\nfield registry, which acts as a central repository where\na wallet implementer can register their usage of a field and share that usage through a\ntest vector.
\nThis BIP is licensed under the BSD 2-clause license.
\nBIP-0032 and\nBIP-0039 let a\nuser carry keys from one application to another, and\nBIP-0329 does the\nsame for the labels attached to a wallet's records.
There is no specification targeting the entire set of metadata a wallet can carry:
A big part of this metadata cannot be recovered from the chain, so a user willing to\nmigrate from one wallet to another has to re-enter it by hand or do without it.\nA format that two applications can both write and read removes that cost, and the\nlock-in that follows from it.
\nSeveral wallet applications already export their whole state, each in a form only they\ncan read.\nBecause each format is specific to one application, moving between any two of them\nmeans writing a converter for that pair.
This proposal introduces a structured format, leveraging JSON to store wallet\nmetadata in a portable way.
The format is flexible and extensible, allowing wallet developers to include as much\nor as little information as they think necessary.
By keeping the mandatory set of metadata small and keeping every other field\noptional, this spec accommodates diverse use cases and preferences.
Wallet developers can include only the fields relevant to their software while\nmaintaining structural integrity.
A wallet export is a UTF-8 encoded text file containing a single valid JSON object\nrepresenting the wallet.
This object includes wallet-level metadata, multiple accounts, and associated key\ndata.
Every timestamp in this format and its registry is an integer representing a Unix\ntimestamp in seconds.
Block heights are integers and are never interchangeable with timestamps.
The fields of every object structure are defined in the\nfield registry rather than in this document, so new\nfields could be added without amending this BIP.\nThe registry records field and object definitions and marks mandatory fields, so each\nobject's structure can be read from its table.\nA registry pull request may add or change optional fields only. The mandatory fields\nare fixed by this BIP, and making a field mandatory is a change to this BIP.\nRegistration of a new field must state the field name, the object it belongs to,\nits type, and a short description, and should link a test vector or an implementation\nusing it when available.\nA field name must not conflict with an already registered field of the same object.
\nThe top-level JSON object must contain the version and network fields and at\nleast one account in the accounts array.
Its fields are listed in the field registry.
version: Mandatory string identifying the version of the export format.\nMust be BIP139-<version>, where <version> is an integer.\nThe export format version is incremented only for changes that are not backward\ncompatible, such as adding a mandatory field.network: Mandatory string naming the network the export covers.bitcoin (mainnet), testnet3, testnet4, signet, mutinynet\nor regtest.accounts: Mandatory array of account objects.The optional signers array holds information about devices that hold key material\npresent in at least one account's descriptor. See Signer Object Structure.
Each account object in the accounts array represents a single account within the\nwallet and must contain the type and descriptor fields.\nIts fields are listed in the field registry.
type: Mandatory string naming the account descriptor type.bip380 (output descriptor), multi_bip380 (a set of BIP-0380\noutput descriptors), bip388 (wallet policies), or bip392 (silent payments). descriptor: Mandatory value representing the account descriptor, with structure\ndefined by type.multi_bip380, which uses an array of\nstrings.A multi_bip380 account groups several BIP380 descriptors without further restriction.\nThis can be needed for wallets such as Electrum.
Each entry in the signers array describes one holder of key material: a hardware\ndevice, a piece of software, or a remote service. A signer must contain the\nfingerprints field, and the field must not be empty.\nThe signer object's fields are listed in the field registry.
fingerprints: Mandatory array of BIP32 fingerprints held by this signer, in\nhexadecimal form.The field is a list because one signer can hold several master keys, as with a device\nthat has more than one mnemonic loaded, or several keys generated using the BIP-0039\npassphrase mechanism.
The relation is many-to-many: a key restored onto two devices appears in the\nfingerprints of two signers.
Signers are listed in the wallet object rather than inside each accounts object because\na signer can be related to several accounts and none of its metadata should change\nbetween accounts. A signer used by three accounts is written once, so the copies\ncannot drift.
Keys in the keys dictionary are indexed by their\nBIP32 fingerprint.\nEach key object records how this account uses the key and must contain the key\nfield. Its fields are listed in the field registry.
What the key is, independent of any account, belongs in the wallet-level signers\narray instead. The fingerprint is the shared key that reconciles the two.
key: Mandatory string representing the public key fingerprint in hexadecimal\nform.Values of the wallet's transactions map are JSON objects, each describing a single\ntransaction. Each is keyed by its transaction id, so the object itself carries no\nidentifier. Its fields are listed in the field registry.
Each entry in the coins array is a JSON object describing a single output owned by\nthe account and must contain the outpoint field.
The coin object's fields are listed in the field registry.
A coin object records wallet state: what the account owns and what the user has\ndecided about it. Silent payment outputs are coins too, and carry a tweak alongside\nthe rest.
outpoint: Mandatory string representing the outpoint in the form <txid>:<vout>.When importing a file defined by this specification, software should follow these\nguidelines:
\nThis format can be encrypted following BIP-138.
\nThis format is extensible and allows future additions without breaking compatibility.
New fields are added through the field registry, and\nwallets should gracefully handle unknown entries by ignoring them.
For all enum types, if the field is optional and the enum type is unknown, the field\nmust not be imported, but import of the file SHOULD NOT fail.
\nTBD
\n