highperfocused/bips
1
0
Fork 0
mirror of https://github.com/bitcoin/bips.git synced 2025-03-17 13:22:51 +01:00
Code Issues Packages Projects Releases Wiki Activity

BIP329: add optional data fields, fix a JSON type (#1750)

Browse Source 
* Correct type error in sample JSON

* first pass: moar data

* more fiat and edits

* more edits

* add per-txn value

* Update bip-0329.mediawiki

Co-authored-by: Jon Atack <jon@atack.com>

* Update bip-0329.mediawiki

Co-authored-by: Jon Atack <jon@atack.com>

* Update bip-0329.mediawiki

Co-authored-by: Jon Atack <jon@atack.com>

* Update bip-0329.mediawiki

Co-authored-by: Jon Atack <jon@atack.com>

* Update bip-0329.mediawiki

Co-authored-by: Jon Atack <jon@atack.com>

* Update bip-0329.mediawiki

Co-authored-by: Jon Atack <jon@atack.com>

* Update bip-0329.mediawiki

Co-authored-by: Jon Atack <jon@atack.com>

* Update bip-0329.mediawiki

Co-authored-by: Jon Atack <jon@atack.com>

* edit

* include @craigraw feedback

* typo fix

* add comment

* further edits

* broaden uses for address.heights

---------

Co-authored-by: Jon Atack <jon@atack.com>
This commit is contained in:
doc-hex 2025-02-25 15:26:27 -05:00 committed by GitHub
parent c84af0bf29
commit c8e208fb6c
No known key found for this signature in database
GPG Key ID: B5690EEEBB952194
1 changed files with 53 additions and 4 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

57
bip-0329.mediawiki
View File

@ -102,7 +102,7 @@ The reference is defined for each <tt>type</tt> as follows:
| <tt>xpub661MyMwAqRbcFtXgS5sYJABqqG9YLmC4Q1Rdap9gSE8Nq...</tt>
|}
Each JSON object must contain both <tt>type</tt> and <tt>ref</tt> properties. The <tt>label</tt>, <tt>origin</tt> and <tt>spendable</tt> properties are optional. If the <tt>label</tt> or <tt>spendable</tt> properties are omitted, the importing wallet should not alter these values. The <tt>origin</tt> property should only appear where type is <tt>tx</tt>, and the <tt>spendable</tt> property only where type is <tt>output</tt>.
Each JSON object must contain both <tt>type</tt> and <tt>ref</tt> properties. The <tt>label</tt>, <tt>origin</tt> and <tt>spendable</tt> properties are optional. If the <tt>label</tt> or <tt>spendable</tt> properties are omitted, the importing wallet should not alter these values. The <tt>spendable</tt> property should only appear where type is <tt>output</tt>.
If present, the optional <tt>origin</tt> property must contain an abbreviated output descriptor (as defined by BIP380<ref>[https://github.com/bitcoin/bips/blob/master/bip-0380.mediawiki BIP-0380]</ref>) describing a BIP32 compatible originating wallet, including all key origin information but excluding any actual keys, any child path elements, or a checksum.
This property should be used to disambiguate transaction labels from different wallets contained in the same export, particularly when exporting multiple accounts derived from the same seed.
@ -121,7 +121,7 @@ For security reasons no private key types are defined.
==Backwards Compatibility==
The nature of this format makes it naturally extensible to handle other record types.
However, importing wallets complying to this specification may ignore types not defined here.
However, importing wallets complying to this specification should ignore types not defined here.
==Test Vectors==
@ -131,14 +131,63 @@ The following fragment represents a wallet label export:
{ "type": "addr", "ref": "bc1q34aq5drpuwy3wgl9lhup9892qp6svr8ldzyy7c", "label": "Address" }
{ "type": "pubkey", "ref": "0283409659355b6d1cc3c32decd5d561abaac86c37a353b52895a5e6c196d6f448", "label": "Public Key" }
{ "type": "input", "ref": "f91d0a8a78462bc59398f2c5d7a84fcff491c26ba54c4833478b202796c8aafd:0", "label": "Input" }
{ "type": "output", "ref": "f91d0a8a78462bc59398f2c5d7a84fcff491c26ba54c4833478b202796c8aafd:1", "label": "Output" , "spendable" : "false" }
{ "type": "output", "ref": "f91d0a8a78462bc59398f2c5d7a84fcff491c26ba54c4833478b202796c8aafd:1", "label": "Output", "spendable": false }
{ "type": "xpub", "ref": "xpub661MyMwAqRbcFtXgS5sYJABqqG9YLmC4Q1Rdap9gSE8NqtwybGhePY2gZ29ESFjqJoCu1Rupje8YtGqsefD265TMg7usUDFdp6W1EGMcet8", "label": "Extended Public Key" }
{ "type": "tx", "ref": "f546156d9044844e02b181026a1a407abfca62e7ea1159f87bbeaa77b4286c74", "label": "Account #1 Transaction", "origin": "wpkh([d34db33f/84'/0'/1'])" }
</pre>
==Additional Fields==
If the goal is solely to move labels between cooperating wallets,
then the above values are the minimum needed. However, wallet data
exports can serve other purposes. 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.
All of the following values are optional for the exporter to provide,
but should be given if they are readily available.
=== Transactions ===
* <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.)
* <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:35Z</tt>.
* <tt>fee</tt>: Integer giving the number of Satoshis that went to the miner for this transaction.
* <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.
* <tt>rate</tt>: Exchange rate at time of transaction. This is the value of a Bitcoin, expressed in another currency, at the time of the transaction, based on user preferences for data source. Multiple currencies can be given. Keys are ISO 4217 currency codes where possible. Example: <tt>"rate": { "USD": 105620.00 }</tt>
=== Address, Inputs, and Outputs ===
* <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 that 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).
=== Inputs and Outputs ===
* <tt>value</tt>: Integer with the number of Satoshis (<tt>nValue</tt>) of the input or output.
* <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.
* <tt>height</tt> and <tt>time</tt>: Same definition as defined in Transactions.
=== Address ===
* <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.
== Comment on Types in JSON ==
JSON can serialize a number of basic types, including string, integer
and boolean (true/false). Decimal values (<tt>123.45</tt>) can
also be serialized, but some parsing libraries may interpret them as floating
point values which is generally not what we want in financial applications.
When hand-crafting JSON data, be careful not to write <tt>"false"</tt> (with quotes),
since that is a string with 5 characters and not a boolean.
==Reference Implementation==
TBD
* [https://github.com/Labelbase/python-bip329 Python-BIP329 package]
==References==