Transaction Labeling

You open your wallet history and find an old payment. Was it a deposit for work, a gift or a transfer to another account you own? A label such as “bicycle repair deposit” can make the record meaningful long afterward. Renaming it changes an application note, not the transaction or its identifier, txid. Nothing new needs to be written to the blockchain, the public history of confirmed transactions, for that change. The same distinction matters in recovery: a Seed Phrase, the recovery words for wallet keys, does not itself contain your personal notes. Recovering spending access and recovering payment context are separate tasks. [1] [3] [5]

A useful note describes what you know: an invoice number, a payment’s purpose or where funds came from. Your own note is not the same as an application-generated association or a claim copied from an analyst. BTCPay Server uses invoice for payments through invoices and payout for payouts or refunds, for example, and allows custom labels. Receipt context helps with Coin Control, manually selecting UTXOs, which are outputs not yet spent. Each output records an amount and the conditions for spending it. But a label saying “do not combine” does nothing by itself. The actual input selection determines which receipts you link in the next payment. [1] [2]

Some wallets can freeze an output so the application does not select it for spending. BIP 329 transfers this local state through spendable, only for the output type. The notation spendable:false uses the Boolean value false; the text string "false" means something different. The practical distinction is simple: freezing guards against unintended selection in that application, not every possible spend. It is not a Timelock, a time condition enforced by Bitcoin’s rules. Another wallet with the right keys can spend the output if its actual conditions are satisfied. [1] [3]

When moving to another application, consider a separate export of your notes. The file can connect names, invoices and payment history with addresses or an XPUB, an extended public key. It lets someone calculate further addresses for the corresponding part of a wallet, but an XPUB alone cannot sign payments. If an export includes a record of type spscan, that record contains a private scan key for finding incoming Silent Payments. That key alone does not authorize spending, but exposing it harms privacy. A file is therefore not harmless merely because it lacks a private spending key. Protect both stored copies and transfers with encryption, and test recovery in the correct account. [1] [4] [5]

BIP 329 distinguishes tx, addr, pubkey, input, output, xpub and spscan. These represent a transaction, address, public key, input, output, extended public key and Silent Payments scanning expression respectively. The type determines how to read ref. For input, it identifies the transaction and its input index; for output, it identifies the creating transaction and its output index. Thus txid:1 is not enough without a type. It could identify an input or an output, which are different objects. Treating every such reference as a “payment address” is unsafe. [1] [4]

BIP 329 uses JSON Lines for exchange: a UTF-8 text file containing one structured record per line. You need not write it by hand; both applications need to understand it. Required fields type and ref identify the record’s subject. Fields label, origin and spendable are optional. An omitted label or spendable should not overwrite an existing value on import. A conforming importer should ignore unknown types. Successfully opening a file therefore does not mean the new wallet retained every note and setting. [1]

One transaction can appear in several accounts or wallets with a different label in each. The origin field helps distinguish these perspectives. It contains an abbreviated Output Descriptor, a machine-readable wallet description, with key-origin information but without actual keys, child derivation paths or a checksum. It indicates which wallet the label concerns. It is not a signature on the file or confirmation that the author truthfully described the payment. Identifying the correct account and trusting the note’s content are different matters. [1]

Before abandoning the old application, try the transfer on a separate test copy. Choose familiar payments and compare the object and ref, the text and any spendable freeze setting. Check accents, multiple accounts, unknown types and omitted optional fields. The importer may skip unsupported records or truncate labels. The suggested 255 characters are a default limit, not a guarantee across applications. Keep the original backup until you have verified important context. A message saying “import complete” does not establish that by itself. [1]