Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

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

Open
wants to merge 14 commits into
base: master
Choose a base branch
from
Open

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

Changes from 5 commits
Commits
Show all changes
14 commits
Select commit Hold shift + click to select a range
58d1ef5
Correct type error in sample JSON
doc-hex Jan 23, 2025
71ac992
first pass: moar data
doc-hex Jan 23, 2025
e712e99
more fiat and edits
doc-hex Jan 23, 2025
c90d2ac
more edits
doc-hex Jan 23, 2025
f91e5dc
add per-txn value
doc-hex Jan 27, 2025
ecc1634
Update bip-0329.mediawiki
doc-hex Jan 29, 2025
26cc309
Update bip-0329.mediawiki
doc-hex Jan 29, 2025
599c83a
Update bip-0329.mediawiki
doc-hex Jan 29, 2025
99fca36
Update bip-0329.mediawiki
doc-hex Jan 29, 2025
10420c6
Update bip-0329.mediawiki
doc-hex Jan 29, 2025
a1b98d4
Update bip-0329.mediawiki
doc-hex Jan 29, 2025
9872825
Update bip-0329.mediawiki
doc-hex Jan 29, 2025
2263a4b
Update bip-0329.mediawiki
doc-hex Jan 29, 2025
e63bfa4
edit
doc-hex Jan 29, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
55 changes: 52 additions & 3 deletions bip-0329.mediawiki
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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==

Expand All @@ -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 }
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@sethforprivacy Note the type correction here.

{ "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 above values are the minimum needed. However, wallet data
doc-hex marked this conversation as resolved.
Show resolved Hide resolved
exports can serve other purposes and many values associated with
doc-hex marked this conversation as resolved.
Show resolved Hide resolved
addresses, transactions and outputs are already on-hand for the
doc-hex marked this conversation as resolved.
Show resolved Hide resolved
wallet generating the export, and yet would be hard or impossible
for importing tools to reconstruct.

All of the following values are optional for exporter to provide,
doc-hex marked this conversation as resolved.
Show resolved Hide resolved
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. Omit for transactions that are confirmed by less than 6 blocks, or use value zero.
doc-hex marked this conversation as resolved.
Show resolved Hide resolved

* <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>.
doc-hex marked this conversation as resolved.
Show resolved Hide resolved

* <tt>fee</tt>: Integer giving the number of Satoshis that went to the miner for this transaction.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

No change needed here, but just noting this is generally only known for outgoing transactions, where all the inputs are from the wallet.


* <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.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Referring to the second sentence - in the case of a consolidation transaction this will reflect the transaction fee, which is unlikely to be zero, so this should be amended to be clearer.


* <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>
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I don't think this needs to be restricted to fiat currencies, but can be "the equivalent value of a Bitcoin in another currency at the time of the transaction". It should be noted in the BIP that multiple currencies can be specified in the mapping, and ISO 4217 currency codes should be preferred as keys where possible.


=== 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 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).
doc-hex marked this conversation as resolved.
Show resolved Hide resolved

=== Inputs, and Outputs ===
doc-hex marked this conversation as resolved.
Show resolved Hide resolved

* <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. To save space, if the time value is already shared in a transaction, only the height is required.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Regarding the second sentence: neither field is required, so this is confusing. Besides, if you are expecting the receiver to do a lookup based on received transactions for the time field, why not the height as well? I think it would be better to omit this sentence altogether, since BIP329 can be used in an event stream in which case previous events should not be relied upon.


=== Address ===

* <tt>heights</tt>: a list of block heights which contain inputs which deposit to the address.
doc-hex marked this conversation as resolved.
Show resolved Hide resolved

== 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==

Expand Down
Loading