Skip to content

Commit 41490b7

Browse files
craigrawcraigraw
authored
Wallet Labels Export Format (bitcoin#1383)
* initial commit * fix formatting * add importing section * clarify csv preference * tabs to spaces * add rationale and references, require that rfc4180 is followed * fix reference links * show reference links as list * use self describing json lines format instead of csv * add bip number and accommodate 65 byte pubkeys * fix comments uri
1 parent 2361582 commit 41490b7

File tree

1 file changed

+131
-0
lines changed

1 file changed

+131
-0
lines changed

‎bip-0329.mediawiki

Lines changed: 131 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,131 @@
1+
<pre>
2+
BIP: 329
3+
Layer: Applications
4+
Title: Wallet Labels Export Format
5+
Author: Craig Raw <[email protected]>
6+
Comments-Summary: No comments yet.
7+
Comments-URI: https://github.com/bitcoin/bips/wiki/Comments:BIP-0329
8+
Status: Draft
9+
Type: Informational
10+
Created: 2022-08-23
11+
License: BSD-2-Clause
12+
</pre>
13+
14+
==Abstract==
15+
16+
This document specifies a format for the export of labels that may be attached to various common types of records in a wallet.
17+
18+
==Copyright==
19+
20+
This BIP is licensed under the BSD 2-clause license.
21+
22+
==Motivation==
23+
24+
The export and import of funds across different Bitcoin wallet applications is well defined through standards such as BIP39, BIP32, BIP44 etc.
25+
These standards are well supported and allow users to move easily between different wallets.
26+
There is, however, no defined standard to transfer any labels the user may have applied to the transactions, addresses, public keys, inputs, outputs or xpubs in their wallet.
27+
The UTXO model that Bitcoin uses makes these labels particularly valuable as they may indicate the source of funds, whether received externally or as a result of change from a prior transaction.
28+
In both cases, care must be taken when spending to avoid undesirable leaks of private information.
29+
Labels provide valuable guidance in this regard, and have even become mandatory when spending in several Bitcoin wallets.
30+
Allowing users to import and export their labels in a standardized way ensures that they do not experience lock-in to a particular wallet application.
31+
32+
==Rationale==
33+
34+
While there is currently no widely accepted format for exporting and importing labels, there are existing formats in use.
35+
SLIP-0015<ref>[https://github.com/satoshilabs/slips/blob/master/slip-0015.md SLIP-0015]</ref> defines a format for exporting address and output labels, but requires encryption using a private key associated with the wallet seed, and thus cannot be used independently by coordinator wallets which cannot access private keys.
36+
The Electrum wallet imports and exports address and transaction labels in a JSON format which could be used with other record types, but the format used is not self describing making record type identification difficult.
37+
38+
==Specification==
39+
40+
In order to be lightweight, human readable and well structured, this BIP uses a JSON format.
41+
Further, the JSON Lines format is used (also called newline-delimited JSON)<ref>[https://jsonlines.org/ jsonlines.org]</ref>.
42+
This allows a document to be split, streamed, or incrementally added to, and limits the potential for formatting errors to invalidate an entire import.
43+
It is also a convenient format for command-line processing, which is often line-oriented.
44+
45+
Further to the JSON Lines specification, an export of labels from a wallet must be a UTF-8 encoded text file, containing one record per line consisting of a valid JSON object.
46+
Lines are separated by <tt>\n</tt>. Multiline values are not permitted.
47+
Each JSON object must contain 3 key/value pairs, defined as follows:
48+
49+
{| class="wikitable"
50+
|-
51+
! Key
52+
! Description
53+
|-
54+
| <tt>type</tt>
55+
| One of <tt>tx</tt>, <tt>addr</tt>, <tt>pubkey</tt>, <tt>input</tt>, <tt>output</tt> or <tt>xpub</tt>
56+
|-
57+
| <tt>ref</tt>
58+
| Reference to the transaction, address, public key, input, output or extended public key
59+
|-
60+
| <tt>label</tt>
61+
| The label applied to the reference
62+
|}
63+
64+
The reference is defined for each <tt>type</tt> as follows:
65+
66+
{| class="wikitable"
67+
|-
68+
! Type
69+
! Description
70+
! Example
71+
|-
72+
| <tt>tx</tt>
73+
| Transaction id in hexadecimal format
74+
| <tt>f91d0a8a78462bc59398f2c5d7a84fcff491c26ba54c4833478b202796c8aafd</tt>
75+
|-
76+
| <tt>addr</tt>
77+
| Address in base58 or bech32 format
78+
| <tt>bc1q34aq5drpuwy3wgl9lhup9892qp6svr8ldzyy7c</tt>
79+
|-
80+
| <tt>pubkey</tt>
81+
| 32, 33 or 65 byte public key in hexadecimal format
82+
| <tt>0283409659355b6d1cc3c32decd5d561abaac86c37a353b52895a5e6c196d6f448</tt>
83+
|-
84+
| <tt>input</tt>
85+
| Transaction id and input index separated by a colon
86+
| <tt>f91d0a8a78462bc59398f2c5d7a84fcff491c26ba54c4833478b202796c8aafd:0</tt>
87+
|-
88+
| <tt>output</tt>
89+
| Transaction id and output index separated by a colon
90+
| <tt>f91d0a8a78462bc59398f2c5d7a84fcff491c26ba54c4833478b202796c8aafd:1</tt>
91+
|-
92+
| <tt>xpub</tt>
93+
| Extended public key as defined by BIP32
94+
| <tt>xpub661MyMwAqRbcFtXgS5sYJABqqG9YLmC4Q1Rdap9gSE8Nq...</tt>
95+
|}
96+
97+
Care should be taken when exporting due to the privacy sensitive nature of the data.
98+
Encryption in transit over untrusted networks is highly recommended, and encryption at rest should also be considered.
99+
Unencrypted exports should be deleted as soon as possible.
100+
For security reasons no private key types are defined.
101+
102+
==Importing==
103+
104+
* An importing wallet may ignore records it does not store, and truncate labels if necessary.
105+
* Wallets importing public key records may derive addresses from them to match against known wallet addresses.
106+
* Wallets importing extended public keys may match them against signers, for example in a multisig setup.
107+
108+
==Backwards Compatibility==
109+
110+
The nature of this format makes it naturally extensible to handle other record types.
111+
However, importing wallets complying to this specification may ignore types not defined here.
112+
113+
==Test Vectors==
114+
115+
The following fragment represents a wallet label export:
116+
<pre>
117+
{ "type": "tx", "ref": "f91d0a8a78462bc59398f2c5d7a84fcff491c26ba54c4833478b202796c8aafd", "label": "Transaction" }
118+
{ "type": "addr", "ref": "bc1q34aq5drpuwy3wgl9lhup9892qp6svr8ldzyy7c", "label": "Address" }
119+
{ "type": "pubkey", "ref": "0283409659355b6d1cc3c32decd5d561abaac86c37a353b52895a5e6c196d6f448", "label": "Public Key" }
120+
{ "type": "input", "ref": "f91d0a8a78462bc59398f2c5d7a84fcff491c26ba54c4833478b202796c8aafd:0", "label": "Input" }
121+
{ "type": "output", "ref": "f91d0a8a78462bc59398f2c5d7a84fcff491c26ba54c4833478b202796c8aafd:1", "label": "Output" }
122+
{ "type": "xpub", "ref": "xpub661MyMwAqRbcFtXgS5sYJABqqG9YLmC4Q1Rdap9gSE8NqtwybGhePY2gZ29ESFjqJoCu1Rupje8YtGqsefD265TMg7usUDFdp6W1EGMcet8", "label": "Extended Public Key" }
123+
</pre>
124+
125+
==Reference Implementation==
126+
127+
TBD
128+
129+
==References==
130+
131+
<references />

0 commit comments

Comments
 (0)