If the goal is solely to move labels between cooperating wallets, then previously defined values are the absolute minimum needed. However, wallet data exports can serve other purposes and many values associated with addresses, transactions and outputs are already on-hand for the wallet generating the export, and yet would be hard or impossible for importing tools to reconstruct.
This PR proposes a bunch of optional fields that could be useful to users of this data. All are optional.
ACK
If there was appetite would go even further with added WAC optional field and attempt to cover as much common accounting needs.
Below are my thoughts on specific fields and suggestions for improving the proposal while keeping it practical:
Block Height and Timestamps
Including the block height is very useful, especially for understanding transaction confirmation status. The timestamp, while useful in some cases, feels less critical. It can be derived if needed, and excluding it could simplify the format.
Transaction and Fees
Fees are a tricky field to standardize, especially for batched or multi-party ownership transactions. Shifting the focus to inputs and outputs rather than whole transactions and handling the fee on its own makes it a lot easier for me.
Fair Market Value and Rate
The FMV field is probably the attribute I wanted the most. The problem with exchange rate is, that there are many of them and I would stick to one (your own) value.
Keypath
Okay.
Value (in sats)
While value (in sats) can be looked up using tools like Electrum, having it as part of the format is still a helpful convenience.
Heights for Addresses
Nah. Address reuse is a bad practice.
While it’s tempting to include some additional fields (mainly confirmation block height, MFV and value in sats) for richer metadata, I believe the BIP should stick to the smallest common denominator for simplicity and broad compatibility. Generally, I’m okay to store and parse metadata from the text label field and delegating more advanced data aggregation, management, and lookups to external tools and services, like labelbase.space.
That said, if @craigraw is open to merging changes into BIP-329, I am happy to adapt the python-bip329 library to support these extensions and make them accessible on the Labelbase platform as well.
138 </pre>
139
140+==Additional Fields==
141+
142+If the goal is solely to move labels between cooperating wallets,
143+then above values are the minimum needed. However, wallet data
0then the above values are the minimum needed. However, wallet data
140+==Additional Fields==
141+
142+If the goal is solely to move labels between cooperating wallets,
143+then above values are the minimum needed. However, wallet data
144+exports can serve other purposes and many values associated with
145+addresses, transactions and outputs are already on-hand for the
0addresses, transactions and outputs are already on hand for the
139
140+==Additional Fields==
141+
142+If the goal is solely to move labels between cooperating wallets,
143+then above values are the minimum needed. However, wallet data
144+exports can serve other purposes and many values associated with
Hard to follow run-on sentence. Best to write separate sentences.
0exports can serve other purposes. Many values associated with
144+exports can serve other purposes and many values associated with
145+addresses, transactions and outputs are already on-hand for the
146+wallet generating the export, and yet would be hard or impossible
147+for importing tools to reconstruct.
148+
149+All of the following values are optional for exporter to provide,
0All of the following values are optional for the exporter to provide,
149+All of the following values are optional for exporter to provide,
150+but should be given if they are readily available.
151+
152+=== Transactions ===
153+
154+* <tt>height</tt>: An integer giving the block height where this fully-confirmed transaction can be found. Omit for transactions that are confirmed by less than 6 blocks, or use value zero.
0* <tt>height</tt>: An integer giving the block height where this fully confirmed transaction can be found. For transactions that are confirmed by less than 6 blocks, omit this field or provide a value of zero.
161+
162+* <tt>rate</tt>: Exchange rate at time of transaction. This is the fiat value of a Bitcoin at the time of the transaction, based on user preferences for data source. Example: <tt>"rate": { "USD": 105620.00 }</tt>
163+
164+=== Address, Inputs, and Outputs ===
165+
166+* <tt>keypath</tt>: The data needed to build full descriptor down to the specific address. This extends <tt>origin</tt> with the final two components are are unhardened (in the typical case, assuming BIP-84). Provide string <tt>/1/123</tt> for <tt>wpkh([d34db33f/84'/0'/0'/1/123])</tt>. If the first character is not <tt>/</tt>, then it should be interpreted as a full descriptor, independant of <tt>origin</tt> (if any).
163+
164+=== Address, Inputs, and Outputs ===
165+
166+* <tt>keypath</tt>: The data needed to build full descriptor down to the specific address. This extends <tt>origin</tt> with the final two components are are unhardened (in the typical case, assuming BIP-84). Provide string <tt>/1/123</tt> for <tt>wpkh([d34db33f/84'/0'/0'/1/123])</tt>. If the first character is not <tt>/</tt>, then it should be interpreted as a full descriptor, independant of <tt>origin</tt> (if any).
167+
168+=== Inputs, and Outputs ===
0=== Inputs and Outputs ===
151+
152+=== Transactions ===
153+
154+* <tt>height</tt>: An integer giving the block height where this fully-confirmed transaction can be found. Omit for transactions that are confirmed by less than 6 blocks, or use value zero.
155+
156+* <tt>time</tt>: ISO-8601 formatted timestamp of the block given by height, preferably in UTC, although ISO-8601 can represent local times. Example: <tt>2025-01-23T11:40:35-05:00</tt>.
It’s not clear that “height” here refers to a field name.
0* <tt>time</tt>: ISO-8601 formatted timestamp of the block given by the "height" field, preferably in UTC, although ISO-8601 can represent local times. Example: <tt>2025-01-23T11:40:35-05:00</tt>.
173+
174+* <tt>height</tt> and <tt>time</tt>: Same definition as defined in Transactions. To save space, if the time value is already shared in a transaction, only the height is required.
175+
176+=== Address ===
177+
178+* <tt>heights</tt>: a list of block heights which contain inputs which deposit to the address.
0* <tt>heights</tt>: a list of block heights that contain inputs that deposit to the address.
Co-authored-by: Jon Atack <jon@atack.com>
Co-authored-by: Jon Atack <jon@atack.com>
Co-authored-by: Jon Atack <jon@atack.com>
Co-authored-by: Jon Atack <jon@atack.com>
Co-authored-by: Jon Atack <jon@atack.com>
Co-authored-by: Jon Atack <jon@atack.com>
Co-authored-by: Jon Atack <jon@atack.com>
Co-authored-by: Jon Atack <jon@atack.com>
A few fixups and suggestions.
Thanks, all accepted and merged.
Latest push e63bfa45 indeed took all my feedback per git diff f91e5dcc e63bfa45
@xavierfiechter any specific changes/removals you would strongly request?
Pinging BIP author @craigraw for feedback.
149+All of the following values are optional for the exporter to provide,
150+but should be given if they are readily available.
151+
152+=== Transactions ===
153+
154+* <tt>height</tt>: An integer giving the block height where this fully confirmed transaction can be found. For transactions that are confirmed by less than 6 blocks, omit this field or provide a value of zero.
151+
152+=== Transactions ===
153+
154+* <tt>height</tt>: An integer giving the block height where this fully confirmed transaction can be found. For transactions that are confirmed by less than 6 blocks, omit this field or provide a value of zero.
155+
156+* <tt>time</tt>: ISO-8601 formatted timestamp of the block given by the "height" field, preferably in UTC, although ISO-8601 can represent local times. Example: <tt>2025-01-23T11:40:35-05:00</tt>.
2025-01-23T11:40:35Z.
153+
154+* <tt>height</tt>: An integer giving the block height where this fully confirmed transaction can be found. For transactions that are confirmed by less than 6 blocks, omit this field or provide a value of zero.
155+
156+* <tt>time</tt>: ISO-8601 formatted timestamp of the block given by the "height" field, preferably in UTC, although ISO-8601 can represent local times. Example: <tt>2025-01-23T11:40:35-05:00</tt>.
157+
158+* <tt>fee</tt>: Integer giving the number of Satoshis that went to the miner for this transaction.
155+
156+* <tt>time</tt>: ISO-8601 formatted timestamp of the block given by the "height" field, preferably in UTC, although ISO-8601 can represent local times. Example: <tt>2025-01-23T11:40:35-05:00</tt>.
157+
158+* <tt>fee</tt>: Integer giving the number of Satoshis that went to the miner for this transaction.
159+
160+* <tt>value</tt>: Signed integer giving the number of Satoshis that came into the wallet by this transaction. Will be negative when sats leave the wallet. Could be zero if it is a consolidation transaction that moves from old UTXO to new.
157+
158+* <tt>fee</tt>: Integer giving the number of Satoshis that went to the miner for this transaction.
159+
160+* <tt>value</tt>: Signed integer giving the number of Satoshis that came into the wallet by this transaction. Will be negative when sats leave the wallet. Could be zero if it is a consolidation transaction that moves from old UTXO to new.
161+
162+* <tt>rate</tt>: Exchange rate at time of transaction. This is the fiat value of a Bitcoin at the time of the transaction, based on user preferences for data source. Example: <tt>"rate": { "USD": 105620.00 }</tt>
169+
170+* <tt>value</tt>: Integer with the number of Satoshis (<tt>nValue</tt>) of the input or output.
171+
172+* <tt>fmv</tt>: Fair market value of the input/output relative to some other currency, typically fiat. The value should be a mapping, from currency code to decimal number. Example: <tt>"fmv": { "USD": 1233.45 }</tt>. Most situations will have only a single currency value, and it represents the real price of the goods/services expressed in some fiat currency. This is not an exchange *rate*, but an absolute value. By dividing by the <tt>value</tt> (above), it is possible to calculate an effective change rate for the transaction.
173+
174+* <tt>height</tt> and <tt>time</tt>: Same definition as defined in Transactions. To save space, if the time value is already shared in a transaction, only the height is required.
173+
174+* <tt>height</tt> and <tt>time</tt>: Same definition as defined in Transactions. To save space, if the time value is already shared in a transaction, only the height is required.
175+
176+=== Address ===
177+
178+* <tt>heights</tt>: a list of block heights that contain inputs that deposit to the address.
130@@ -131,14 +131,63 @@ The following fragment represents a wallet label export:
131 { "type": "addr", "ref": "bc1q34aq5drpuwy3wgl9lhup9892qp6svr8ldzyy7c", "label": "Address" }
132 { "type": "pubkey", "ref": "0283409659355b6d1cc3c32decd5d561abaac86c37a353b52895a5e6c196d6f448", "label": "Public Key" }
133 { "type": "input", "ref": "f91d0a8a78462bc59398f2c5d7a84fcff491c26ba54c4833478b202796c8aafd:0", "label": "Input" }
134-{ "type": "output", "ref": "f91d0a8a78462bc59398f2c5d7a84fcff491c26ba54c4833478b202796c8aafd:1", "label": "Output" , "spendable" : "false" }
135+{ "type": "output", "ref": "f91d0a8a78462bc59398f2c5d7a84fcff491c26ba54c4833478b202796c8aafd:1", "label": "Output", "spendable": false }
origin field, the line “The origin property should only appear where type is tx, and the spendable property only where type is output” should be amended to just “The spendable property should only appear where type is output” since origin can now be used on all types.
I’m generally ok with all the proposed fields, since they reference publicly available information, or at least information that should be publicly available.
A note on implementation: Historical fiat exchange rate information is becoming more difficult for open source wallet clients to retrieve, with Coingecko and Coinbase now requiring paid subscriptions for historical rate lookups. Only mempool.space provides an open API for historical rates, and then only for the last couple of years in a handful of major currencies. However, this presents an interesting opportunity for server-based implementations, which can add the exchange rate fields by processing this format as an event stream, and may have less need for historical rate access.
Regarding the
originfield, the line “The origin property should only appear where type is tx, and the spendable property only where type is output” should be amended to just “The spendable property should only appear where type is output” sinceorigincan now be used on all types.
I made this edit just now.
173+
174+* <tt>height</tt> and <tt>time</tt>: Same definition as defined in Transactions.
175+
176+=== Address ===
177+
178+* <tt>heights</tt>: a list of block heights that contain any activity related to this address, include outputs that deposit to the address, and transactions that spend UTXO of this address. An empty array indicates the address is unused.
Either “a UTXO” or “UTXOs” here…
0* <tt>heights</tt>: a list of block heights that contain any activity related to this address, include outputs that deposit to the address, and transactions that spend UTXOs of this address. An empty array indicates the address is unused.
180+== Comment on Types in JSON ==
181+
182+JSON can serialize a number of basic types, including string, integer
183+and boolean (true/false). Decimal values (<tt>123.45</tt>) can
184+also be serialized, but some parsing libraries may interpret them as floating
185+point values which is generally not what we want in financial applications.
0point values, which is generally not what we want in financial applications.
149+All of the following values are optional for the exporter to provide,
150+but should be given if they are readily available.
151+
152+=== Transactions ===
153+
154+* <tt>height</tt>: An integer giving the block height where this fully confirmed transaction can be found. For transactions that are confirmed by less than 6 blocks, omit this field or provide a value of zero. (Background: Until it is fully confirmed, the "height" of a transaction is in flux and may vary due to chain reorgs. However, the consumer of the labels, may not know the current block height, so it cannot know if the height is "real" (firm, fixed) or just transitory, so it's important not to include the height unless the generating wallet considers the transaction to be confirmed.)
0* <tt>height</tt>: An integer giving the block height where this fully confirmed transaction can be found. For transactions that are confirmed by less than 6 blocks, omit this field or provide a value of zero. (Background: Until it is fully confirmed, the "height" of a transaction is in flux and may vary due to chain reorgs. However, the consumer of the labels may not know the current block height, so it cannot know if the height is "real" (firm, fixed) or just transitory. Therefore, it is important to omit the height unless the generating wallet considers the transaction to be confirmed.)