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
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.
18
20
19
-
This document proposes a human useable format: '''"TxRef"''' as a standard way of referencing transaction positions within the Bitcoin Blockchain. The primary purpose of this format is to allow end-users an effective and convenient way of referencing transactions that have been confirmed within the blockchain.
20
-
21
-
''Please note: that a TxRef does not reference an actual transaction itself, rather it references a possible location within a blockchain for a transaction, that may or may not, point to an actual transaction and may change with reorganisations. We recommend that TxRef's should be not used for positions within the blockchain with 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 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.''
22
22
23
23
=== Copyright ===
24
24
@@ -32,24 +32,25 @@ However, for many use-cases they have practical limitations:
32
32
* TxIDs require third-party service for SPV wallets to lookup.
33
33
* TxIDs are very long HEX encoded values (64 characters long).
34
34
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. In this document, we propose a standard for doing this.
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.
36
36
37
37
=== Examples ===
38
38
These examples are for Bitcoin Transactions.
39
-
* Genesis Coinbase Transaction: <tt>tx1:rqqq-qqqq-qmhu-qk (need to update)</tt>
40
-
* Transaction #2205 of Block #466793: <tt>tx1:rjk0-u5ng-4jsf-mc (need to update)</tt>
* Transaction #2205 of Block #466793: <tt>tx1:rjk0-uqay-zsrw-hqe</tt>
41
41
42
42
== Specification ==
43
43
44
-
A '''confirmed transaction position reference''', or '''TxRef''' is reference to a particular location within the blockchain specified by the block height and a index within the block.
44
+
A '''confirmed transaction position reference''', or '''TxRef''', is a reference to a particular location within the blockchain, specified by the block height and a transaction index within the block, and optionally a outpoint index within the transaction.
45
45
46
46
''Please Note: All values in this specification are encoded in little-endian format.''
47
47
48
48
=== Transaction Position Reference Considerations ===
49
49
A TxRef may reference a location that doesn't exist because:
50
50
51
-
* The block height hasn't been mined. Or,
52
-
* The index is more than the total number of transactions included within the specified block.
51
+
* The specified block hasn't yet been mined. Or,
52
+
* The transaction index is greater than the total number of transactions included within the specified block.
53
+
* The optional outpoint index is greater than the total outpoints contained within the transaction.
53
54
54
55
Therefore, implementers must be careful not to display TxRef's to users prematurely:
55
56
@@ -62,21 +63,23 @@ Therefore, implementers must be careful not to display TxRef's to users prematur
62
63
TxRef uses standard Bech32<refname=":0">'''Why use Bech32 Encoding for Confirmed Transaction References?''' The error detection and correction properties of this encoding format make it very attractive. We expect that it will be reasonable for software to correct a maximum of two characters; however, we haven’t specified this yet.</ref> encoding as defined in [https://github.com/bitcoin/bips/blob/master/bip-0173.mediawiki BIP-173] and therefore consists of:
63
64
64
65
* Human-readable Part, or "HRP", that provides namespacing. We have chosen to distinguish between Main and Test Networks:
65
-
**For Any Mainnet Network: '''"tx"'''.
66
-
**For Any Testnet Network: '''"txtest"'''.
67
-
**Please see [https://github.com/satoshilabs/slips/blob/master/slip-0173.md SLIP-0173 : Registered human-readable parts for BIP-0173] for a full list of HRP's including these two and other relating to other projects.
66
+
**For Any Mainnet Network: '''"tx"'''.
67
+
**For Any Testnet Network: '''"txtest"'''.
68
+
**Please see [https://github.com/satoshilabs/slips/blob/master/slip-0173.md SLIP-0173 : Registered human-readable parts for BIP-0173] for a full list of HRP's including these two and others relating to other projects.
68
69
* Separator: '''"1"'''.
69
70
* Data Part.
70
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.
73
+
71
74
To increase portability and readability additional separators SHOULD be added:
72
75
73
76
* A Colon<ref>'''Why add a colon here?''' This allows it to conform better with W3C URN/URL standards.</ref> '''":"''' added after '1'.
74
-
* 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 loose their place so easily.</ref> '''"-"''' added after every 4 characters beyond the colon.
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.
75
78
76
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.
77
80
</ref>
78
81
{| class="wikitable"
79
-
|+TxRef String Format for Bitcoin Mainnet and Bitcoin Testnet:
82
+
|+Text Encoding of the TxRef
80
83
!
81
84
!Bit
82
85
!Character
@@ -112,39 +115,12 @@ All non-bech32-alphabet characters after the bech32 code separator MUST be ignor
112
115
|9
113
116
|1
114
117
|"'''-'''"
115
-
|-
116
-
|Data
117
-
|20 – 39
118
-
|10 – 13
119
-
|4
120
-
|
121
-
|-
122
-
|Hyphen
123
-
|
124
-
|14
125
-
|1
126
-
|"'''-'''"
127
-
|-
128
-
|Data
129
-
|40 – 59
130
-
|15 – 18
131
-
|4
132
-
|
133
-
|-
134
-
|Hyphen
135
-
|
136
-
|19
137
-
|1
138
-
|"'''-'''"
139
-
|-
140
-
|Data
141
-
|60 – 74
142
-
|20 – 22
143
-
|3
144
-
|
145
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).
120
+
=== Data ===
121
+
122
+
The 75 or 90 bits of data encoded in the string above are defined in this manner:
146
123
147
-
=== Data Part ===
148
124
{| class="wikitable"
149
125
|+TxRef Binary Format for Bitcoin Mainnet and Bitcoin Testnet:
150
126
!
@@ -158,7 +134,10 @@ All non-bech32-alphabet characters after the bech32 code separator MUST be ignor
158
134
|0 – 4
159
135
|5
160
136
|Chain Namespacing Code
161
-
|'''0x3''' for Bitcoin Mainnet, or '''0x6''' for Bitcoin Testnet
137
+
|'''0x3''' for Bitcoin Mainnet.
138
+
'''0x4''' for Bitcoin Mainnet with Outpoint.
139
+
'''0x6''' for Bitcoin Testnet.
140
+
'''0x7''' for Bitcoin Testnet with Outpoint.
162
141
|
163
142
|-
164
143
|Version
@@ -181,37 +160,71 @@ All non-bech32-alphabet characters after the bech32 code separator MUST be ignor
181
160
|The index of the Tx inside the block
182
161
|Tx 0 (coinbase) to Tx position 32767
183
162
|Max Tx's in block is 16665
163
+
|}
164
+
If the magic is '''0x4''' or '''0x7''', an optional outpoint is included in the encoding:
165
+
166
+
{| class="wikitable"
167
+
|+Optional Outpoint Index Encoding:
168
+
!
169
+
!'''Bit'''
170
+
!'''Bit(s)'''
171
+
!'''Type'''
172
+
!'''Values'''
173
+
!'''Notes'''
174
+
|-
175
+
|Outpoint Index
176
+
|45 – 59
177
+
|15
178
+
|The index of the Outpoint inside the Tx
179
+
|Outpoint 0 to Outpoint Position 32767
180
+
|
181
+
|}
182
+
183
+
We include the 30-bit checksum last:
184
+
{| class="wikitable"
185
+
|+Bech32 Checksum Encoding:
186
+
!
187
+
!'''Bit'''
188
+
!'''Bit(s)'''
189
+
!'''Type'''
190
+
!'''Values'''
191
+
!'''Notes'''
184
192
|-
185
193
|Checksum
186
-
|45 – 74
194
+
|45 – 74 or 60 – 89
187
195
|30
188
196
|Bech32 Checksum
189
197
|
190
198
|
191
199
|}
200
+
192
201
==== Magic Notes: ====
193
202
The magic code provides namespacing between chains. 5-bit magic codes are used for the Bitcoin Mainnet and the Bitcoin Testnet. (it may be significantly longer for other projects/chains):
194
203
195
-
* For Bitcoin Mainnet the magic code is: '''0x3''', leading to a '''"r"''' character.
196
-
* For Bitcoin Testnet the magic code is: '''0x6''', leading to a '''"x"''' character.
204
+
* For Bitcoin Mainnet the magic code is: '''0x3''', leading to an '''"r"''' character when encoded.
205
+
* For Bitcoin Mainnet with Outpoint Encoded the magic code is: '''0x4''', leading to an '''"y"''' character when encoded.
206
+
* For Bitcoin Testnet the magic code is: '''0x6''', leading to an '''"x"''' character when encoded.
207
+
* For Bitcoin Testnet with Outpoint Encoded the magic code is: '''0x7''', leading to an '''"8"''' character when encoded.
197
208
198
-
Codes '''0x0''', '''0x1''', '''0x2''' are also reserved for future use within the Bitcoin project.
209
+
Codes '''0x0''', '''0x1''', '''0x2''', '''0x5''', are also reserved for future use within the Bitcoin project.
199
210
200
-
''Any other chain MUST NOT start their magic code with any value between 0x0 and 0x6 inclusive.''
211
+
''Any other chain MUST NOT start their magic code with any value between 0x0 and 0x7 inclusive.''
201
212
202
213
Other magic codes will be specified in SLIP-XXXX "TxRef for Non-Bitcoin Chains and Networks".
203
214
204
-
===Compatibly===
215
+
===Compatibility===
205
216
There are no known compatibility issues.
206
217
207
218
== Rationale ==
208
219
209
220
<references />
210
221
211
222
== Reference implementations ==
212
-
C Reference Implementation: https://github.com/jonasschnelli/bitcoin_txref_code
223
+
C Reference Implementation (supports version 0): https://github.com/jonasschnelli/bitcoin_txref_code
213
224
214
-
Go Reference Implementation: https://github.com/kulpreet/txref
225
+
Go Reference Implementation (supports version 0): https://github.com/kulpreet/txref
226
+
227
+
C++ Reference Implementation (support versions 0 and 1): https://github.com/dcdpr/btcr-DID-method/blob/master/libtxref
215
228
216
229
== Appendices ==
217
230
@@ -234,24 +247,24 @@ The following list gives invalid TxRef's and the reason for their invalidity.
234
247
* <tt>bc1qw508d6qejxtdg4y5r3zarvary0c5xw7kg3g4ty</tt>: Invalid human-readable part
0 commit comments