You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardExpand all lines: bip-0136.mediawiki
+58-38Lines changed: 58 additions & 38 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -16,27 +16,27 @@
16
16
== Introduction ==
17
17
18
18
=== Abstract ===
19
-
This document proposes a convenient human useable format, '''"TxRef"''', as a standard way to refer to a transaction position within the Bitcoin Blockchain, and optionally a particular outpoint index with the referred transaction. The primary purpose of this format is to allow users to refer to a confirmed transaction (and optionally an outpoint index within) in a standard reliable and concise way.
19
+
This document proposes a convenient human useable format, '''"TxRef"''', as a standard way to refer to a transaction position within the Bitcoin Blockchain, and optionally a particular outpoint index within the referred transaction. The primary purpose of this format is to allow users to refer to a confirmed transaction (and optionally an outpoint index within) in a standard, reliable, and concise way.
20
20
21
-
''Please note: Unlike TxID where there is strong cryptographic link between the ID and the actual transaction. TxRef only provide a weak link to a particular transaction. TxRef locates an offset within a blockchain for a transaction, that may - or may not - point to an actual transaction, which fact may change with reorganisations. We recommend that TxRef's should be not used for positions within the blockchain having a maturity less than 100 blocks.''
21
+
''Please note: Unlike TxID where there is strong cryptographic link between the ID and the actual transaction, TxRef only provides a weak link to a particular transaction. TxRef locates an offset within a blockchain for a transaction, that may - or may not - point to an actual transaction, which in fact may change with reorganisations. We recommend that TxRef's should be not used for positions within the blockchain having a maturity less than 100 blocks.''
22
22
23
23
=== Copyright ===
24
24
25
25
This BIP is licensed under the 2-clause BSD license.
26
26
27
27
=== Motivation ===
28
-
Since the first version of Bitcoin, TxID's (Transaction Identifiers) that are a core part of the consensus protocol, have been routinely used to identify individual transactions between users.
28
+
Since the first version of Bitcoin, TxID's (Transaction Identifiers) have been a core part of the consensus protocol and have been routinely used to identify individual transactions between users.
29
29
30
30
However, for many use-cases they have practical limitations:
31
31
* TxIDs are expensive for full nodes to lookup (requiring either a linear scan of the blockchain, or an expensive TxID index).
32
-
* TxIDs require third-party service for SPV wallets to lookup.
32
+
* TxIDs require third-party services for SPV wallets to lookup.
33
33
* TxIDs are very long HEX encoded values (64 characters long).
34
34
35
35
For transactions that have been embedded in the blockchain, it is possible to reference them not by their TxID, but by their location within the blockchain itself. The encoding can be made friendly for occasional human transcription. In this document, we propose a standard for doing this.
* Genesis Coinbase Transaction (Transaction #0 of Block #0): <tt>tx1:rqqq-qqqq-qmhu-qhp</tt>
40
40
* Transaction #2205 of Block #466793: <tt>tx1:rjk0-uqay-zsrw-hqe</tt>
41
41
42
42
== Specification ==
@@ -69,12 +69,12 @@ TxRef uses standard Bech32<ref name=":0">'''Why use Bech32 Encoding for Confirme
69
69
* Separator: '''"1"'''.
70
70
* Data Part.
71
71
72
-
Please node: other specifcations, such as [https://w3c-ccg.github.io/did-spec/ Decentralized Identifier syntax] , have implicitly encoded the information contained within the HRP elsewhere. In this case they may choose not include the HRP as specified here.
72
+
Please note: other specifications, such as [https://w3c-ccg.github.io/did-spec/ the Decentralized Identifiers spec], have implicitly encoded the information contained within the HRP elsewhere. In this case they may choose to not include the HRP as specified here.
73
73
74
74
To increase portability and readability additional separators SHOULD be added:
75
75
76
76
* A Colon<ref>'''Why add a colon here?''' This allows it to conform better with W3C URN/URL standards.</ref> '''":"''' added after '1'.
77
-
* Hyphens<ref>'''Why hyphens to the TxRef?''' As TxRef's are short, we expect that they will be quoted via voice or written by hand. The inclusion of hyphens every 4 characters breaks the string and means people don't lose their place so easily.</ref> '''"-"''' added after every 4 characters beyond the colon.
77
+
* Hyphens<ref>'''Why hyphens within the TxRef?''' As TxRef's are short, we expect that they will be quoted via voice or written by hand. The inclusion of hyphens every 4 characters breaks up the string and means people don't lose their place so easily.</ref> '''"-"''' added after every 4 characters beyond the colon.
78
78
79
79
All non-bech32-alphabet characters after the bech32 code separator MUST be ignored/removed when parsing (except for terminating characters).<ref>'''Why strip all non-bech32-alphabet characters?''' We do not wish to expect the users to keep their TxRef's in good unicode form (hyphens, colons, invisible spaces, random unicode characters, etc). We expect them to copy, paste, write by-hand, write in a mix of character sets, etc. Parsers should automatically correct for all sorts of these common errors.
80
80
</ref>
@@ -116,10 +116,10 @@ All non-bech32-alphabet characters after the bech32 code separator MUST be ignor
116
116
|1
117
117
|"'''-'''"
118
118
|}
119
-
The Data - Hyphen patten is repeated for the entire length of data, ( a hyphen is inserted after every encoded 20 bits or 4 data characters).
119
+
The Data - Hyphen pattern is repeated for the entire length of data, ( a hyphen is inserted after every encoded 20 bits or 4 data characters).
120
120
=== Data ===
121
121
122
-
The 75 or 90 bits of data encoded in the string above are defined in this manner:
122
+
Depending on if an optional transaction outpoint is included, there can be 75 or 90 bits of data encoded in the string above. These bits are defined in this manner:
123
123
124
124
{| class="wikitable"
125
125
|+TxRef Binary Format for Bitcoin Mainnet and Bitcoin Testnet:
@@ -130,7 +130,7 @@ The 75 or 90 bits of data encoded in the string above are defined in this manner
130
130
!'''Values'''
131
131
!'''Notes'''
132
132
|-
133
-
|Magic
133
+
|Magic Code
134
134
|0 – 4
135
135
|5
136
136
|Chain Namespacing Code
@@ -161,7 +161,7 @@ The 75 or 90 bits of data encoded in the string above are defined in this manner
161
161
|Tx 0 (coinbase) to Tx position 32767
162
162
|Max Tx's in block is 16665
163
163
|}
164
-
If the magic is '''0x4''' or '''0x7''', an optional outpoint is included in the encoding:
164
+
If the magic code is '''0x4''' or '''0x7''', an optional outpoint is included in the encoding:
165
165
166
166
{| class="wikitable"
167
167
|+Optional Outpoint Index Encoding:
@@ -176,7 +176,7 @@ If the magic is '''0x4''' or '''0x7''', an optional outpoint is included in the
176
176
|45 – 59
177
177
|15
178
178
|The index of the Outpoint inside the Tx
179
-
|Outpoint 0 to Outpoint Position 32767
179
+
|Outpoint 0 to Outpoint Position 32767
180
180
|
181
181
|}
182
182
@@ -220,19 +220,19 @@ There are no known compatibility issues.
220
220
<references />
221
221
222
222
== Reference implementations ==
223
-
C Reference Implementation (supports version 0): https://github.com/jonasschnelli/bitcoin_txref_code
223
+
C Reference Implementation (supports magic codes 0x3 and 0x6): https://github.com/jonasschnelli/bitcoin_txref_code
224
224
225
-
Go Reference Implementation (supports version 0): https://github.com/kulpreet/txref
225
+
Go Reference Implementation (supports magic codes 0x3 and 0x6): https://github.com/kulpreet/txref
226
226
227
-
C++ Reference Implementation (support versions 0 and 1): https://github.com/dcdpr/btcr-DID-method/blob/master/libtxref
* Bech32 Encoding Test Vectors. These are to test if a implementation accepts the encoding, with the correct human readable part, and separator.
235
-
* Bitcoin TxRef Test Vectors. These test the full specification, in particular correct values for block height and the transaction index.
235
+
* Bitcoin TxRef Test Vectors. These test the full specification, in particular, correct values for block height and the transaction index.
236
236
237
237
==== Bech32 Encoding (for TxRef). ====
238
238
''Please Note: All test vectors are shown to help test if a string is compliant or not. All real-life applications (such as for Bitcoin) should comply with the Bitcoin Test Vectors listed Below.''
@@ -247,15 +247,22 @@ The following list gives invalid TxRef's and the reason for their invalidity.
247
247
* <tt>bc1qw508d6qejxtdg4y5r3zarvary0c5xw7kg3g4ty</tt>: Invalid human-readable part
0 commit comments