Imagine opening a restored Bitcoin wallet and seeing an old payment with no sign of the note you gave it. The wallet recognises the transaction. The label that said what it was for lived in the old app’s records.
What a Bitcoin wallet restore can recover
In a wallet that uses BIP 39, the recovery words and any original passphrase produce the seed used for deterministic keys. The wallet also needs to know which addresses or scripts to look for. The original derivation paths, script type or multisig configuration can matter. After finding those scripts, a compatible wallet can rediscover their on-chain activity. That history does not contain the nicknames you typed into the old app. BIP 39 explains the seed and BIP 380 explains why the script information matters.
An output descriptor describes the scripts a wallet should look for. A descriptor with only public keys can help recover a watch-only view. Spending still requires the relevant signing keys or devices. The difference between a seed phrase and a private key explains why these pieces serve different purposes.
What a BIP 329 label backup carries
BIP 329 is a draft informational proposal for a UTF-8 JSON Lines export. Each line is its own JSON object. The type says what kind of record it describes, and ref identifies the record. A label can add the human note. An optional origin can help distinguish labels from separate wallets or accounts. It is an abbreviated descriptor with key-origin information, without actual keys, child-path elements or a checksum.
These three lines use deliberately invalid placeholders for references. They illustrate the shape of the file and cannot be imported as a real backup.
{"type":"tx","ref":"DEMO-TX-A","label":"Workshop supplies"}
{"type":"addr","ref":"DEMO-ADDR-B","label":"Print fund"}
{"type":"output","ref":"DEMO-TX-A:1","label":"Change from supplies"}
A real tx reference is a hexadecimal transaction ID. An addr reference is an encoded Bitcoin address. An output reference combines a transaction ID and an output index. The first and third lines therefore describe different records, even though they refer to the same fictional transaction.
Before and after a label import
In this invented example, the restored wallet recognises the transaction and its output. It has no matching address record for the second line.
| Record | After wallet restore | After the illustrative label import |
|---|---|---|
Transaction DEMO-TX-A | Found, blank label | Workshop supplies |
Address DEMO-ADDR-B | No matching record | Line skipped |
Output DEMO-TX-A:1 | Found, blank label | Change from supplies |
The draft lets importers skip records they do not store, ignore unknown types and shorten labels if necessary. If label or spendable is omitted, the draft says the importer should leave that value alone. The optional spendable flag is local wallet metadata for an output. It cannot change Bitcoin’s on-chain rules.
Sparrow 2.5.5’s released source documents one implementation. Its importer matches transaction and address references against entries in the wallet and skips labels with a non-matching origin. The example above uses fictional records. It does not test Sparrow or promise that another app will reproduce the same result.
Why a label export is private
The draft defines no private-key record type, but a plain JSON Lines file can still reveal which public records belong together. A transaction labelled “Workshop supplies” and an address labelled “Print fund” might turn two unexplained entries into a recognisable spending history. A file can also carry extended public key references, which can help link activity across addresses. Keep a real export private and protect stored and transmitted copies with encryption. A seed backup and a label export protect different things, and each can be sensitive on its own.
Sources
- BIP 329: Wallet Labels Export Format — draft fields, import rules and privacy.
- BIP 39: Mnemonic code for generating deterministic keys — seed derivation.
- BIP 380: Output Script Descriptors General Operation — output scripts, key information and descriptor limits.
- Sparrow 2.5.5: released WalletLabels source — example of reference and origin matching.
See something wrong? Brokzi logs material changes. Prepare a correction note.




