From 58d1ef568c7cde56f499e2c6f351306b40da6ddc Mon Sep 17 00:00:00 2001 From: "Peter D. Gray" Date: Thu, 23 Jan 2025 10:47:41 -0500 Subject: [PATCH 01/14] Correct type error in sample JSON --- bip-0329.mediawiki | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/bip-0329.mediawiki b/bip-0329.mediawiki index 13b332b0cc..075f4dae79 100644 --- a/bip-0329.mediawiki +++ b/bip-0329.mediawiki @@ -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,7 +131,7 @@ 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'])" } From 71ac9922a47c05d5492065303a1e96c5f1e29ac2 Mon Sep 17 00:00:00 2001 From: "Peter D. Gray" Date: Thu, 23 Jan 2025 13:16:52 -0500 Subject: [PATCH 02/14] first pass: moar data --- bip-0329.mediawiki | 39 +++++++++++++++++++++++++++++++++++++++ 1 file changed, 39 insertions(+) diff --git a/bip-0329.mediawiki b/bip-0329.mediawiki index 075f4dae79..1374f6d5c9 100644 --- a/bip-0329.mediawiki +++ b/bip-0329.mediawiki @@ -136,6 +136,45 @@ The following fragment represents a wallet label export: { "type": "tx", "ref": "f546156d9044844e02b181026a1a407abfca62e7ea1159f87bbeaa77b4286c74", "label": "Account #1 Transaction", "origin": "wpkh([d34db33f/84'/0'/1'])" } +==Additional Fields== + +If the goal is solely to move labels between cooperating wallets, +then above values are the 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. + +All of the following values are optional for exporter to provide, +but should be given if they are readily on-hand. + +=== Transactions === + +* `height`: 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. + +* `time`: ISO-8601 formated timestamp of the block given by height, preferably in UTC. + Example: `2025-01-23T11:40:35-05:00`. + +* `fee`: integer giving the number of Satoshis that went to the miner for this transaction. + +=== Address, Inputs, and Outputs === + +* `keypath`: the data needed to build full descriptor down to the specific address. + This extends `origin` with the final two components are are unhardened (in the typical case, + assuming BIP-84). Provide string `/1/123` for `wpkh([d34db33f/84'/0'/0'/1/123])`. If + the first character is not `/`, then it should be interpreted as a full descriptior, + independant of `origin` (if any). + +=== Inputs, and Outputs === + +* `value`: integer with the number of Satoshis (`nValue`) of the input or output. + +=== Address === + +* `heights`: a list of block heights which contain inputs which deposit to the address. + + ==Reference Implementation== TBD From e712e991c15c5b7263ddccf0b518bce0c5cb9bf3 Mon Sep 17 00:00:00 2001 From: "Peter D. Gray" Date: Thu, 23 Jan 2025 13:47:06 -0500 Subject: [PATCH 03/14] more fiat and edits --- bip-0329.mediawiki | 35 +++++++++++++++++++++-------------- 1 file changed, 21 insertions(+), 14 deletions(-) diff --git a/bip-0329.mediawiki b/bip-0329.mediawiki index 1374f6d5c9..316228017b 100644 --- a/bip-0329.mediawiki +++ b/bip-0329.mediawiki @@ -146,38 +146,45 @@ 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, -but should be given if they are readily on-hand. +but should be given if they are readily available. === Transactions === -* `height`: 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. +* height: 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. -* `time`: ISO-8601 formated timestamp of the block given by height, preferably in UTC. - Example: `2025-01-23T11:40:35-05:00`. +* time: ISO-8601 formatted timestamp of the block given by height, preferably in UTC, although ISO-8601 can represent local times. Example: 2025-01-23T11:40:35-05:00. -* `fee`: integer giving the number of Satoshis that went to the miner for this transaction. +* fee: Integer giving the number of Satoshis that went to the miner for this transaction. + +* rate: 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: "rate": { "USD": 105620.00 } === Address, Inputs, and Outputs === -* `keypath`: the data needed to build full descriptor down to the specific address. - This extends `origin` with the final two components are are unhardened (in the typical case, - assuming BIP-84). Provide string `/1/123` for `wpkh([d34db33f/84'/0'/0'/1/123])`. If - the first character is not `/`, then it should be interpreted as a full descriptior, - independant of `origin` (if any). +* keypath: The data needed to build full descriptor down to the specific address. This extends origin with the final two components are are unhardened (in the typical case, assuming BIP-84). Provide string /1/123 for wpkh([d34db33f/84'/0'/0'/1/123]). If the first character is not /, then it should be interpreted as a full descriptor, independant of origin (if any). === Inputs, and Outputs === -* `value`: integer with the number of Satoshis (`nValue`) of the input or output. +* value: Integer with the number of Satoshis (nValue) of the input or output. + +* fmv: 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: "fmv": { "USD": 1233.45 }. 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 value (above), it is possible to calculate an effective change rate for the transaction. + === Address === -* `heights`: a list of block heights which contain inputs which deposit to the address. +* heights: a list of block heights which contain inputs which deposit to the address. + +== Comment on Types in JSON == +JSON can serialize a number of basic types, including string, integer +and boolean (true/false). Decimal values (123.45) 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 "false" (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== From c90d2acd0de2225f98020334210cf4f98d6d7abc Mon Sep 17 00:00:00 2001 From: "Peter D. Gray" Date: Thu, 23 Jan 2025 13:52:37 -0500 Subject: [PATCH 04/14] more edits --- bip-0329.mediawiki | 1 + 1 file changed, 1 insertion(+) diff --git a/bip-0329.mediawiki b/bip-0329.mediawiki index 316228017b..65c65c043c 100644 --- a/bip-0329.mediawiki +++ b/bip-0329.mediawiki @@ -168,6 +168,7 @@ but should be given if they are readily available. * fmv: 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: "fmv": { "USD": 1233.45 }. 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 value (above), it is possible to calculate an effective change rate for the transaction. +* height and time: Same definition as defined in Transactions. To save space, if the time value is already shared in a transaction, only the height is required. === Address === From f91e5dccb004e9948e429f9e24ec046a3ceca472 Mon Sep 17 00:00:00 2001 From: "Peter D. Gray" Date: Mon, 27 Jan 2025 09:49:39 -0500 Subject: [PATCH 05/14] add per-txn value --- bip-0329.mediawiki | 2 ++ 1 file changed, 2 insertions(+) diff --git a/bip-0329.mediawiki b/bip-0329.mediawiki index 65c65c043c..d21953b652 100644 --- a/bip-0329.mediawiki +++ b/bip-0329.mediawiki @@ -156,6 +156,8 @@ but should be given if they are readily available. * fee: Integer giving the number of Satoshis that went to the miner for this transaction. +* value: 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. + * rate: 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: "rate": { "USD": 105620.00 } === Address, Inputs, and Outputs === From ecc1634fe21348dad2fdcf8ab3b5f72c170df0cc Mon Sep 17 00:00:00 2001 From: doc-hex <1482781+doc-hex@users.noreply.github.com> Date: Wed, 29 Jan 2025 13:15:46 -0500 Subject: [PATCH 06/14] Update bip-0329.mediawiki Co-authored-by: Jon Atack --- bip-0329.mediawiki | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/bip-0329.mediawiki b/bip-0329.mediawiki index d21953b652..582452ba13 100644 --- a/bip-0329.mediawiki +++ b/bip-0329.mediawiki @@ -139,7 +139,7 @@ The following fragment represents a wallet label export: ==Additional Fields== If the goal is solely to move labels between cooperating wallets, -then above values are the minimum needed. However, wallet data +then the above values are the 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 From 26cc309bd8a6af9d808dffadfe6ac93620bc3c72 Mon Sep 17 00:00:00 2001 From: doc-hex <1482781+doc-hex@users.noreply.github.com> Date: Wed, 29 Jan 2025 13:15:59 -0500 Subject: [PATCH 07/14] Update bip-0329.mediawiki Co-authored-by: Jon Atack --- bip-0329.mediawiki | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/bip-0329.mediawiki b/bip-0329.mediawiki index 582452ba13..ae7e947209 100644 --- a/bip-0329.mediawiki +++ b/bip-0329.mediawiki @@ -141,7 +141,7 @@ The following fragment represents a wallet label export: 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 and many values associated with -addresses, transactions and outputs are already on-hand for the +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. From 599c83ad14cfb5d66871e4f564ee1e4c77e597fc Mon Sep 17 00:00:00 2001 From: doc-hex <1482781+doc-hex@users.noreply.github.com> Date: Wed, 29 Jan 2025 13:16:08 -0500 Subject: [PATCH 08/14] Update bip-0329.mediawiki Co-authored-by: Jon Atack --- bip-0329.mediawiki | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/bip-0329.mediawiki b/bip-0329.mediawiki index ae7e947209..931a8ea94d 100644 --- a/bip-0329.mediawiki +++ b/bip-0329.mediawiki @@ -140,7 +140,7 @@ The following fragment represents a wallet label export: 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 and many values associated with +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. From 99fca361611e103bdc0be44c1266c02430cdb603 Mon Sep 17 00:00:00 2001 From: doc-hex <1482781+doc-hex@users.noreply.github.com> Date: Wed, 29 Jan 2025 13:16:17 -0500 Subject: [PATCH 09/14] Update bip-0329.mediawiki Co-authored-by: Jon Atack --- bip-0329.mediawiki | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/bip-0329.mediawiki b/bip-0329.mediawiki index 931a8ea94d..81eb8d0ab5 100644 --- a/bip-0329.mediawiki +++ b/bip-0329.mediawiki @@ -145,7 +145,7 @@ 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 exporter to provide, +All of the following values are optional for the exporter to provide, but should be given if they are readily available. === Transactions === From 10420c6adbf46580f7317bdc50269ff108d4fd37 Mon Sep 17 00:00:00 2001 From: doc-hex <1482781+doc-hex@users.noreply.github.com> Date: Wed, 29 Jan 2025 13:16:35 -0500 Subject: [PATCH 10/14] Update bip-0329.mediawiki Co-authored-by: Jon Atack --- bip-0329.mediawiki | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/bip-0329.mediawiki b/bip-0329.mediawiki index 81eb8d0ab5..035af29a87 100644 --- a/bip-0329.mediawiki +++ b/bip-0329.mediawiki @@ -150,7 +150,7 @@ but should be given if they are readily available. === Transactions === -* height: 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. +* height: 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. * time: ISO-8601 formatted timestamp of the block given by height, preferably in UTC, although ISO-8601 can represent local times. Example: 2025-01-23T11:40:35-05:00. From a1b98d47fffa6af82891194c6de064c7b9c68cad Mon Sep 17 00:00:00 2001 From: doc-hex <1482781+doc-hex@users.noreply.github.com> Date: Wed, 29 Jan 2025 13:17:04 -0500 Subject: [PATCH 11/14] Update bip-0329.mediawiki Co-authored-by: Jon Atack --- bip-0329.mediawiki | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/bip-0329.mediawiki b/bip-0329.mediawiki index 035af29a87..5769fc3bbd 100644 --- a/bip-0329.mediawiki +++ b/bip-0329.mediawiki @@ -164,7 +164,7 @@ but should be given if they are readily available. * keypath: The data needed to build full descriptor down to the specific address. This extends origin with the final two components are are unhardened (in the typical case, assuming BIP-84). Provide string /1/123 for wpkh([d34db33f/84'/0'/0'/1/123]). If the first character is not /, then it should be interpreted as a full descriptor, independant of origin (if any). -=== Inputs, and Outputs === +=== Inputs and Outputs === * value: Integer with the number of Satoshis (nValue) of the input or output. From 98728255490793bd3547aee864d04999d26819b1 Mon Sep 17 00:00:00 2001 From: doc-hex <1482781+doc-hex@users.noreply.github.com> Date: Wed, 29 Jan 2025 13:17:31 -0500 Subject: [PATCH 12/14] Update bip-0329.mediawiki Co-authored-by: Jon Atack --- bip-0329.mediawiki | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/bip-0329.mediawiki b/bip-0329.mediawiki index 5769fc3bbd..63495eba91 100644 --- a/bip-0329.mediawiki +++ b/bip-0329.mediawiki @@ -152,7 +152,7 @@ but should be given if they are readily available. * height: 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. -* time: ISO-8601 formatted timestamp of the block given by height, preferably in UTC, although ISO-8601 can represent local times. Example: 2025-01-23T11:40:35-05:00. +* time: ISO-8601 formatted timestamp of the block given by the "height" field, preferably in UTC, although ISO-8601 can represent local times. Example: 2025-01-23T11:40:35-05:00. * fee: Integer giving the number of Satoshis that went to the miner for this transaction. From 2263a4bb4a237591745deadfa9aa901501e35e00 Mon Sep 17 00:00:00 2001 From: doc-hex <1482781+doc-hex@users.noreply.github.com> Date: Wed, 29 Jan 2025 13:17:44 -0500 Subject: [PATCH 13/14] Update bip-0329.mediawiki Co-authored-by: Jon Atack --- bip-0329.mediawiki | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/bip-0329.mediawiki b/bip-0329.mediawiki index 63495eba91..bc1e705616 100644 --- a/bip-0329.mediawiki +++ b/bip-0329.mediawiki @@ -174,7 +174,7 @@ but should be given if they are readily available. === Address === -* heights: a list of block heights which contain inputs which deposit to the address. +* heights: a list of block heights that contain inputs that deposit to the address. == Comment on Types in JSON == From e63bfa45acc35e30230e57d4b76dfc1f4aa19797 Mon Sep 17 00:00:00 2001 From: "Peter D. Gray" Date: Wed, 29 Jan 2025 13:18:38 -0500 Subject: [PATCH 14/14] edit --- bip-0329.mediawiki | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/bip-0329.mediawiki b/bip-0329.mediawiki index bc1e705616..845820e1c5 100644 --- a/bip-0329.mediawiki +++ b/bip-0329.mediawiki @@ -162,7 +162,7 @@ but should be given if they are readily available. === Address, Inputs, and Outputs === -* keypath: The data needed to build full descriptor down to the specific address. This extends origin with the final two components are are unhardened (in the typical case, assuming BIP-84). Provide string /1/123 for wpkh([d34db33f/84'/0'/0'/1/123]). If the first character is not /, then it should be interpreted as a full descriptor, independant of origin (if any). +* keypath: The data needed to build full descriptor down to the specific address. This extends origin with the final two components that are unhardened (in the typical case, assuming BIP-84). Provide string /1/123 for wpkh([d34db33f/84'/0'/0'/1/123]). If the first character is not /, then it should be interpreted as a full descriptor, independant of origin (if any). === Inputs and Outputs ===