BIP329 — Wallet Labels

Wallets maintain user-supplied labels: "Coffee shop", "Friend Alice", "Cold storage 1". Pre-BIP329, labels were proprietary per wallet and lost on migration. BIP329 standardizes a portable JSON Lines format.

Format

One JSON object per line (NDJSON / JSONL):

{"type":"tx","ref":"f91d0a8a78462bc59398f2c5d7a84fcff491c26ba54c4833478b202796c8aafd","label":"Coffee shop"}
{"type":"addr","ref":"bc1qxy2kgdygjrsqtzq2n0yrf2493p83kkfjhx0wlh","label":"Friend Alice"}
{"type":"output","ref":"f91d0a8a...:0","label":"Sent to Alice"}
{"type":"input","ref":"a32f...:1","label":"Spent from cold storage"}
{"type":"xpub","ref":"xpub6CV2...","label":"Account 1"}
{"type":"pubkey","ref":"02f7e2...","label":"Cosigner Bob"}

Type field values

Type	`ref` semantics
`tx`	txid
`addr`	address
`pubkey`	hex-encoded pubkey
`xpub`	xpub serialization
`input`	`<txid>:<vin>`
`output`	`<txid>:<vout>`

Optional fields

{
  "type":"addr",
  "ref":"bc1q...",
  "label":"Customer 123",
  "origin":"vendor-X",       // optional source identifier
  "spendable":true            // for output: still spendable hint
}

Spendability hint

For UTXOs that are part of a multi-step protocol (vault unvault, LN HTLC, frozen for CoinJoin), the wallet may mark them "spendable":false. Importing wallet sees this and excludes them from coin selection by default.

Filename convention

<wallet_name>-labels.jsonl typical extension.

Import flow

for line in file:
    obj = json.loads(line)
    if obj.type == "tx":   wallet.set_tx_label(obj.ref, obj.label)
    if obj.type == "addr": wallet.set_addr_label(obj.ref, obj.label)
    ...

Conflict resolution: import options:

Replace: overwrite existing labels.
Merge: keep existing if conflict, add new ones.
Skip duplicates: do nothing for conflicts.

Encryption

BIP329 doesn't define encryption. Common practice:

Encrypt the JSONL file with age, GPG, or wallet-derived key.
Some wallets export .aes or .gpg versions natively.

Implementations

Sparrow — full BIP329 import/export.
Specter Desktop — supports import/export.
BlueWallet — partial support (tx labels only).
Bitcoin Core — labels stored internally; export via JSON RPC (listlabels, getaddressesbylabel) but not BIP329-formatted yet.

Use cases

Migration — moving from one wallet to another without losing the human-readable annotations.
Multi-wallet — same UTXO set viewed in two wallets, both see the same labels.
Audit / compliance — exchanges export labels for accounting.
Backup — labels alongside seed backup for full wallet restore.

Common bugs

Mixing address labels with xpub labels semantically — an xpub's label applies to the account, not individual addresses.
Stripping non-ASCII chars on import → labels with emojis / non-Latin scripts truncated.
Exporting internal change addresses as labeled-by-default → noise in import.
Unicode normalization (NFC vs NFD) inconsistency between exporter / importer.

bitcoin-wallet-labels