From e78c384755f2bd6bf233d585a0ffd70b57eb43db Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=D0=92=D0=B5=D0=BB=D0=B5=D1=81=D0=BB=D0=B0=D0=B2?= Date: Wed, 12 Sep 2018 20:17:33 +1000 Subject: BIP-136: Bech32 Encoded Tx Position References --- bip-0136.mediawiki | 276 +++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 276 insertions(+) create mode 100644 bip-0136.mediawiki (limited to 'bip-0136.mediawiki') diff --git a/bip-0136.mediawiki b/bip-0136.mediawiki new file mode 100644 index 0000000..e8b107d --- /dev/null +++ b/bip-0136.mediawiki @@ -0,0 +1,276 @@ +
+  BIP: 136
+  Layer: Applications
+  Title: Bech32 Encoded Tx Position References
+  Author: Велеслав 
+          Jonas Schnelli 
+  Comments-Summary: No comments yet.
+  Comments-URI: https://github.com/bitcoin/bips/wiki/Comments:BIP-0136
+  Status: Draft
+  Type: Informational
+  Created: 2017-07-09
+  License: BSD-2-Clause
+
+ +== Introduction == + +=== Abstract === + +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. + +''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.'' + +=== Copyright === + +This BIP is licensed under the 2-clause BSD license. + +=== Motivation === +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. + +However, for many use-cases they have practical limitations: +* TxIDs are expensive for full nodes to lookup (requiring either a linear scan of the blockchain, or an expensive TxID index). +* TxIDs require third-party service for SPV wallets to lookup. +* TxIDs are very long HEX encoded values (64 characters long). + +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. + +=== Examples === +These examples are for Bitcoin Transactions. +* Genesis Coinbase Transaction: tx1:rqqq-qqqq-qmhu-qk (need to update) +* Transaction #2205 of Block #466793: tx1:rjk0-u5ng-4jsf-mc (need to update) + +== Specification == + +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. + +''Please Note: All values in this specification are encoded in little-endian format.'' + +=== Transaction Position Reference Considerations === +A TxRef may reference a location that doesn't exist because: + +* The block height hasn't been mined. Or, +* The index is more than the total number of transactions included within the specified block. + +Therefore, implementers must be careful not to display TxRef's to users prematurely: + +* Applications MUST NOT display TxRef's for transactions with less than 6 confirmations. +* Application MUST show a warning for TxRef's for transactions with less than 100 confirmations. +** This warning SHOULD state that in the case of a large reorganisation, the TxRefs Displayed may point to a different transaction, or to no transaction at all. + +=== Encoding === + +TxRef uses standard Bech32'''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. encoding as defined in [https://github.com/bitcoin/bips/blob/master/bip-0173.mediawiki BIP-173] and therefore consists of: + +* Human-readable Part, or "HRP", that provides namespacing. We have chosen to distinguish between Main and Test Networks: +**For Any Mainnet Network: '''"tx"'''. +**For Any Testnet Network: '''"txtest"'''. +**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. +* Separator: '''"1"'''. +* Data Part. + +To increase portability and readability additional separators SHOULD be added: + +* A Colon'''Why add a colon here?''' This allows it to conform better with W3C URN/URL standards. '''":"''' added after '1'. +* Hyphens'''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. '''"-"''' added after every 4 characters beyond the colon. + +All non-bech32-alphabet characters after the bech32 code separator MUST be ignored/removed when parsing (except for terminating characters).'''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. + +{| class="wikitable" +|+TxRef String Format for Bitcoin Mainnet and Bitcoin Testnet: +! +!Bit +!Character +!Characters +!Value +|- +|Human Readable Part +| +|1 – 2 +|2 +|Bitcoin Mainnet: "'''tx'''", Bitcoin Testnet: "'''txtest'''" +|- +|Separator +| +|3 +|1 +|"'''1'''" +|- +|Colon +| +|4 +|1 +|"''':'''" +|- +|Data +|0 – 19 +|5 – 8 +|4 +| +|- +|Hyphen +| +|9 +|1 +|"'''-'''" +|- +|Data +|20 – 39 +|10 – 13 +|4 +| +|- +|Hyphen +| +|14 +|1 +|"'''-'''" +|- +|Data +|40 – 59 +|15 – 18 +|4 +| +|- +|Hyphen +| +|19 +|1 +|"'''-'''" +|- +|Data +|60 – 74 +|20 – 22 +|3 +| +|} + +=== Data Part === +{| class="wikitable" +|+TxRef Binary Format for Bitcoin Mainnet and Bitcoin Testnet: +! +!'''Bit''' +!'''Bit(s)''' +!'''Type''' +!'''Values''' +!'''Notes''' +|- +|Magic +|0 – 4 +|5 +|Chain Namespacing Code +|'''0x3''' for Bitcoin Mainnet, or '''0x6''' for Bitcoin Testnet +| +|- +|Version +|5 +|1 +|For Future Use +|Must be '''0x0''' +| +|- +|Block Height +|6 – 29 +|24 +|The Block Height of the Tx +|Block 0 (genesis) to block 16777215 +|Until Year ~2328 +|- +|Transaction Index +|30 – 44 +|15 +|The index of the Tx inside the block +|Tx 0 (coinbase) to Tx position 32767 +|Max Tx's in block is 16665 +|- +|Checksum +|45 – 74 +|30 +|Bech32 Checksum +| +| +|} +==== Magic Notes: ==== +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): + +* For Bitcoin Mainnet the magic code is: '''0x3''', leading to a '''"r"''' character. +* For Bitcoin Testnet the magic code is: '''0x6''', leading to a '''"x"''' character. + +Codes '''0x0''', '''0x1''', '''0x2''' are also reserved for future use within the Bitcoin project. + +''Any other chain MUST NOT start their magic code with any value between 0x0 and 0x6 inclusive.'' + +Other magic codes will be specified in SLIP-XXXX "TxRef for Non-Bitcoin Chains and Networks". + +=== Compatibly === +There are no known compatibility issues. + +== Rationale == + + + +== Reference implementations == +C Reference Implementation: https://github.com/jonasschnelli/bitcoin_txref_code + +Go Reference Implementation: https://github.com/kulpreet/txref + +== Appendices == + +=== Test Vectors === +There are two sets of Test Vectors included here: + +* Bech32 Encoding Test Vectors. These are to test if a implementation accepts the encoding, with the correct human readable part, and separator. +* Bitcoin TxRef Test Vectors. These test the full specification, in particular correct values for block height and the transaction index. + +==== Bech32 Encoding (for TxRef). ==== +''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.'' + +The following strings have a valid Human Readable Part and Bech32 Checksum. +* TX1A12UEL5L +* tx1an83characterlonghumanreadablepartthatcontainsthenumber1andtheexcludedcharactersbio1tt5tgs +* tx1abcdef1qpzry9x8gf2tvdw0s3jn54khce6mua7lmqqqxw +* tx11qqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqc8247j + +The following list gives invalid TxRef's and the reason for their invalidity. +* bc1qw508d6qejxtdg4y5r3zarvary0c5xw7kg3g4ty: Invalid human-readable part +* tx1qw508d6qejxtdg4y5r3zarvary0c5xw7kv8f3t5: Invalid checksum + +==== Bitcoin TxRef (out of date, need to be amended). ==== +The following list gives properly encoded Bitcoin TxRef's and the values in hex. (block height, transaction index) + +* tx1:rqqq-qqqq-qmhu-qk: (0x0, 0x0) +* tx1:rqqq-qull-6v87-r7: (0x0, 0x1FFF) +* tx1:r7ll-lrqq-vq5e-gg: (0x1FFFFF, 0x0) +* tx1:r7ll-llll-khym-tq: (0x1FFFFF, 0x1FFF) + +The following list give valid Bitcoin TxRef's and the values in hex. (block height, transaction index) +* tx1:rjk0-u5ng-4jsf-mc: (0x71F69, 0x89D) +* TX1RJK0U5NG4JSFMC: (0x71F69, 0x89D) +* TX1R1JK0--U5bNG4JSb----FMC: (0x71F69, 0x89D) +* tx1 rjk0 u5ng 4jsfmc: (0x71F69, 0x89D) +* tx1!rjk0\u5ng*4jsf^^mc: (0x71F69, 0x89D) + +The following list gives invalid Bitcoin TxRef's and the reason for their invalidity. +* tx1:t7ll-llll-gey7-ez: Magic 0xB instead of 0x3. (0x1FFFFF, 0x1FFF) +* tx1:rlll-llll-cgqu-n2: Version 1 instead of 0. (0x1FFFFF, 0x1FFF) +* tx1:rjk0-u5ng-gghq-fkg7: Valid Bech32, but 10x5bit packages instead of 8. +* tx1:rjk0-u5qd-s43z: Valid Bech32, but 6x5bit packages instead of 8. + +=== Bitcoin TxRef Payload Value Choice: === +Some calculations showing why we chose these particular bit-length of the block height and transaction index. + +==== Block Height Value: ==== +24-bit: between 0, and 0xFFFFFF (16,777,216 blocks). + +*There are ~52,500 blocks every year, leading to ~319 years of blocks addressable. +*Therefore before year 2328 this specification should be extended. (We think that we have plenty of time). + +==== Tx Position Value: ==== +15-bit: between 0x0, and 0x7FFF. (32,768 transactions). + +*The ''realistic'' smallest Tx is 83 Bytes: Max 12047 tx in a block. +**4B version + 1B tx_in count + 36B previous_output + 1B script length + 0B signature script + 4B sequence + 1B tx_out count + 8B amount + 1B script length + 23B pubkey script + 4B lock_time = 83B +*The ''extreme'' smallest Tx is 60 Byte's: Max 16665 tx in a block. +**4B version + 1B tx_in count + 36B previous_output + 1B script length + 0B signature script + 4B sequence + 1B tx_out count + 8B amount + 1B script length + 0B pubkey script + 4B lock_time = 60B + +== Acknowledgements == +Special Thanks to Pieter Wuille and Greg Maxwell for Bech32, a wonderful user-facing data encoding. -- cgit v1.2.3 From a8bb0a4e39a9eefa419d2f83f40b6af97699016f Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=D0=92=D0=B5=D0=BB=D0=B5=D1=81=D0=BB=D0=B0=D0=B2?= Date: Tue, 6 Nov 2018 15:35:44 +0800 Subject: Include Optional Encoded Outpoints With thanks to Daniel Pape for the work behind this idea. Please not that the test-vectors still need to be updated (again). --- bip-0136.mediawiki | 166 ++++++++++++++++++++++++++++++++--------------------- 1 file changed, 99 insertions(+), 67 deletions(-) (limited to 'bip-0136.mediawiki') diff --git a/bip-0136.mediawiki b/bip-0136.mediawiki index e8b107d..15bc29a 100644 --- a/bip-0136.mediawiki +++ b/bip-0136.mediawiki @@ -4,6 +4,7 @@ Title: Bech32 Encoded Tx Position References Author: Велеслав Jonas Schnelli + Daniel Pape Comments-Summary: No comments yet. Comments-URI: https://github.com/bitcoin/bips/wiki/Comments:BIP-0136 Status: Draft @@ -15,10 +16,9 @@ == Introduction == === Abstract === +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. -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. - -''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.'' +''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.'' === Copyright === @@ -32,24 +32,25 @@ However, for many use-cases they have practical limitations: * TxIDs require third-party service for SPV wallets to lookup. * TxIDs are very long HEX encoded values (64 characters long). -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. +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. === Examples === These examples are for Bitcoin Transactions. -* Genesis Coinbase Transaction: tx1:rqqq-qqqq-qmhu-qk (need to update) -* Transaction #2205 of Block #466793: tx1:rjk0-u5ng-4jsf-mc (need to update) +* Genesis Coinbase Transaction: tx1:rqqq-qqqq-qmhu-qhp +* Transaction #2205 of Block #466793: tx1:rjk0-uqay-zsrw-hqe == Specification == -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. +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. ''Please Note: All values in this specification are encoded in little-endian format.'' === Transaction Position Reference Considerations === A TxRef may reference a location that doesn't exist because: -* The block height hasn't been mined. Or, -* The index is more than the total number of transactions included within the specified block. +* The specified block hasn't yet been mined. Or, +* The transaction index is greater than the total number of transactions included within the specified block. +* The optional outpoint index is greater than the total outpoints contained within the transaction. Therefore, implementers must be careful not to display TxRef's to users prematurely: @@ -62,21 +63,23 @@ Therefore, implementers must be careful not to display TxRef's to users prematur TxRef uses standard Bech32'''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. encoding as defined in [https://github.com/bitcoin/bips/blob/master/bip-0173.mediawiki BIP-173] and therefore consists of: * Human-readable Part, or "HRP", that provides namespacing. We have chosen to distinguish between Main and Test Networks: -**For Any Mainnet Network: '''"tx"'''. -**For Any Testnet Network: '''"txtest"'''. -**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. +** For Any Mainnet Network: '''"tx"'''. +** For Any Testnet Network: '''"txtest"'''. +** 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. * Separator: '''"1"'''. * Data Part. +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. + To increase portability and readability additional separators SHOULD be added: * A Colon'''Why add a colon here?''' This allows it to conform better with W3C URN/URL standards. '''":"''' added after '1'. -* Hyphens'''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. '''"-"''' added after every 4 characters beyond the colon. +* Hyphens'''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. '''"-"''' added after every 4 characters beyond the colon. All non-bech32-alphabet characters after the bech32 code separator MUST be ignored/removed when parsing (except for terminating characters).'''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. {| class="wikitable" -|+TxRef String Format for Bitcoin Mainnet and Bitcoin Testnet: +|+Text Encoding of the TxRef ! !Bit !Character @@ -112,39 +115,12 @@ All non-bech32-alphabet characters after the bech32 code separator MUST be ignor |9 |1 |"'''-'''" -|- -|Data -|20 – 39 -|10 – 13 -|4 -| -|- -|Hyphen -| -|14 -|1 -|"'''-'''" -|- -|Data -|40 – 59 -|15 – 18 -|4 -| -|- -|Hyphen -| -|19 -|1 -|"'''-'''" -|- -|Data -|60 – 74 -|20 – 22 -|3 -| |} +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). +=== Data === + +The 75 or 90 bits of data encoded in the string above are defined in this manner: -=== Data Part === {| class="wikitable" |+TxRef Binary Format for Bitcoin Mainnet and Bitcoin Testnet: ! @@ -158,7 +134,10 @@ All non-bech32-alphabet characters after the bech32 code separator MUST be ignor |0 – 4 |5 |Chain Namespacing Code -|'''0x3''' for Bitcoin Mainnet, or '''0x6''' for Bitcoin Testnet +|'''0x3''' for Bitcoin Mainnet. +'''0x4''' for Bitcoin Mainnet with Outpoint. +'''0x6''' for Bitcoin Testnet. +'''0x7''' for Bitcoin Testnet with Outpoint. | |- |Version @@ -181,27 +160,59 @@ All non-bech32-alphabet characters after the bech32 code separator MUST be ignor |The index of the Tx inside the block |Tx 0 (coinbase) to Tx position 32767 |Max Tx's in block is 16665 +|} +If the magic is '''0x4''' or '''0x7''', an optional outpoint is included in the encoding: + +{| class="wikitable" +|+Optional Outpoint Index Encoding: +! +!'''Bit''' +!'''Bit(s)''' +!'''Type''' +!'''Values''' +!'''Notes''' +|- +|Outpoint Index +|45 – 59 +|15 +|The index of the Outpoint inside the Tx +|Outpoint 0 to Outpoint Position 32767 +| +|} + +We include the 30-bit checksum last: +{| class="wikitable" +|+Bech32 Checksum Encoding: +! +!'''Bit''' +!'''Bit(s)''' +!'''Type''' +!'''Values''' +!'''Notes''' |- |Checksum -|45 – 74 +|45 – 74 or 60 – 89 |30 |Bech32 Checksum | | |} + ==== Magic Notes: ==== 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): -* For Bitcoin Mainnet the magic code is: '''0x3''', leading to a '''"r"''' character. -* For Bitcoin Testnet the magic code is: '''0x6''', leading to a '''"x"''' character. +* For Bitcoin Mainnet the magic code is: '''0x3''', leading to an '''"r"''' character when encoded. +* For Bitcoin Mainnet with Outpoint Encoded the magic code is: '''0x4''', leading to an '''"y"''' character when encoded. +* For Bitcoin Testnet the magic code is: '''0x6''', leading to an '''"x"''' character when encoded. +* For Bitcoin Testnet with Outpoint Encoded the magic code is: '''0x7''', leading to an '''"8"''' character when encoded. -Codes '''0x0''', '''0x1''', '''0x2''' are also reserved for future use within the Bitcoin project. +Codes '''0x0''', '''0x1''', '''0x2''', '''0x5''', are also reserved for future use within the Bitcoin project. -''Any other chain MUST NOT start their magic code with any value between 0x0 and 0x6 inclusive.'' +''Any other chain MUST NOT start their magic code with any value between 0x0 and 0x7 inclusive.'' Other magic codes will be specified in SLIP-XXXX "TxRef for Non-Bitcoin Chains and Networks". -=== Compatibly === +=== Compatibility === There are no known compatibility issues. == Rationale == @@ -209,9 +220,11 @@ There are no known compatibility issues. == Reference implementations == -C Reference Implementation: https://github.com/jonasschnelli/bitcoin_txref_code +C Reference Implementation (supports version 0): https://github.com/jonasschnelli/bitcoin_txref_code -Go Reference Implementation: https://github.com/kulpreet/txref +Go Reference Implementation (supports version 0): https://github.com/kulpreet/txref + +C++ Reference Implementation (support versions 0 and 1): https://github.com/dcdpr/btcr-DID-method/blob/master/libtxref == Appendices == @@ -234,24 +247,24 @@ The following list gives invalid TxRef's and the reason for their invalidity. * bc1qw508d6qejxtdg4y5r3zarvary0c5xw7kg3g4ty: Invalid human-readable part * tx1qw508d6qejxtdg4y5r3zarvary0c5xw7kv8f3t5: Invalid checksum -==== Bitcoin TxRef (out of date, need to be amended). ==== +==== Bitcoin TxRef ==== The following list gives properly encoded Bitcoin TxRef's and the values in hex. (block height, transaction index) -* tx1:rqqq-qqqq-qmhu-qk: (0x0, 0x0) -* tx1:rqqq-qull-6v87-r7: (0x0, 0x1FFF) -* tx1:r7ll-lrqq-vq5e-gg: (0x1FFFFF, 0x0) -* tx1:r7ll-llll-khym-tq: (0x1FFFFF, 0x1FFF) +* tx1:rqqq-qqqq-qmhu-qhp: (0x0, 0x0) +* tx1:rqqq-qqll-l8xh-jkg: (0x0, 0x7FFF) +* tx1:r7ll-llqq-qghq-qr8: (0xFFFFFF, 0x0) +* tx1:r7ll-llll-l5xt-jzw: (0xFFFFFF, 0x7FFF) -The following list give valid Bitcoin TxRef's and the values in hex. (block height, transaction index) -* tx1:rjk0-u5ng-4jsf-mc: (0x71F69, 0x89D) -* TX1RJK0U5NG4JSFMC: (0x71F69, 0x89D) -* TX1R1JK0--U5bNG4JSb----FMC: (0x71F69, 0x89D) -* tx1 rjk0 u5ng 4jsfmc: (0x71F69, 0x89D) -* tx1!rjk0\u5ng*4jsf^^mc: (0x71F69, 0x89D) +The following list gives valid Bitcoin TxRef's and the values in hex. (block height, transaction index) +* tx1:rjk0-uqay-zsrw-hqe: (0x71F69, 0x89D) +* TX1RJK0UQAYZSRWHQE: (0x71F69, 0x89D) +* TX1RJK0--UQaYZSRw----HQE: (0x71F69, 0x89D) +* tx1 rjk0 uqay zsrw hqe: (0x71F69, 0x89D) +* tx1!rjk0\uqay*zsrw^^hqe: (0x71F69, 0x89D) The following list gives invalid Bitcoin TxRef's and the reason for their invalidity. -* tx1:t7ll-llll-gey7-ez: Magic 0xB instead of 0x3. (0x1FFFFF, 0x1FFF) -* tx1:rlll-llll-cgqu-n2: Version 1 instead of 0. (0x1FFFFF, 0x1FFF) +* tx1:t7ll-llll-ldup-3hh: Magic 0xB instead of 0x3. (0xFFFFFF, 0x7FFF) +* tx1:rlll-llll-lfet-r2y: Version 1 instead of 0. (0xFFFFFF, 0x7FFF) * tx1:rjk0-u5ng-gghq-fkg7: Valid Bech32, but 10x5bit packages instead of 8. * tx1:rjk0-u5qd-s43z: Valid Bech32, but 6x5bit packages instead of 8. @@ -272,5 +285,24 @@ Some calculations showing why we chose these particular bit-length of the block *The ''extreme'' smallest Tx is 60 Byte's: Max 16665 tx in a block. **4B version + 1B tx_in count + 36B previous_output + 1B script length + 0B signature script + 4B sequence + 1B tx_out count + 8B amount + 1B script length + 0B pubkey script + 4B lock_time = 60B +=== Test Vectors (version 1) === +These test vectors are extended TxRefs (version 1): + +==== Bitcoin Extended TxRef ==== +The following list gives properly encoded Bitcoin Extended TxRef's and the values in hex. (block height, transaction index, TXO index) + +* tx1:rpqq-qqqq-qqqq-q2ge-ahz: (0x0, 0x0, 0x0) +* tx1:rpqq-qqql-llqq-qshz-qhw: (0x0, 0x7FFF, 0x0) +* tx1:rp7l-lllq-qqqq-qpvh-wkq: (0xFFFFFF, 0x0, 0x0) +* tx1:rp7l-llll-llqq-qmnv-nkv: (0xFFFFFF, 0x7FFF, 0x0) + +* tx1:rpqq-qqqq-qqpq-qg2s-2w6: (0x0, 0x0, 0x1) +* tx1:rpqq-qqql-llpq-qj4t-hwk: (0x0, 0x7FFF, 0x1) +* tx1:rp7l-lllq-qqpq-qrw7-e0c: (0xFFFFFF, 0x0, 0x1) +* tx1:rp7l-llll-llpq-qe39-y05: (0xFFFFFF, 0x7FFF, 0x1) + +* tx1:rpjk-0uqa-yzu4-x0w0-kuq: (0x71F69, 0x89D, 0x1ABC) +* txtest1:xpjk-0uqa-yzu4-xgrl-pue: (0x71F69, 0x89D, 0x1ABC) (testnet, magic number = 0x6) + == Acknowledgements == Special Thanks to Pieter Wuille and Greg Maxwell for Bech32, a wonderful user-facing data encoding. -- cgit v1.2.3 From 4e2bb34d04cb2fdbb5a52fdc6a606f0dfa91adc8 Mon Sep 17 00:00:00 2001 From: "Daniel X. Pape" Date: Wed, 28 Nov 2018 22:30:09 -0800 Subject: add examples for TxRefs with Outpoints; fix some typos and wording --- bip-0136.mediawiki | 96 +++++++++++++++++++++++++++++++++--------------------- 1 file changed, 58 insertions(+), 38 deletions(-) (limited to 'bip-0136.mediawiki') diff --git a/bip-0136.mediawiki b/bip-0136.mediawiki index 15bc29a..f94171d 100644 --- a/bip-0136.mediawiki +++ b/bip-0136.mediawiki @@ -16,27 +16,27 @@ == Introduction == === Abstract === -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. +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. -''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.'' +''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.'' === Copyright === This BIP is licensed under the 2-clause BSD license. === Motivation === -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. +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. However, for many use-cases they have practical limitations: * TxIDs are expensive for full nodes to lookup (requiring either a linear scan of the blockchain, or an expensive TxID index). -* TxIDs require third-party service for SPV wallets to lookup. +* TxIDs require third-party services for SPV wallets to lookup. * TxIDs are very long HEX encoded values (64 characters long). 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. === Examples === These examples are for Bitcoin Transactions. -* Genesis Coinbase Transaction: tx1:rqqq-qqqq-qmhu-qhp +* Genesis Coinbase Transaction (Transaction #0 of Block #0): tx1:rqqq-qqqq-qmhu-qhp * Transaction #2205 of Block #466793: tx1:rjk0-uqay-zsrw-hqe == Specification == @@ -69,12 +69,12 @@ TxRef uses standard Bech32'''Why use Bech32 Encoding for Confirme * Separator: '''"1"'''. * Data Part. -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. +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. To increase portability and readability additional separators SHOULD be added: * A Colon'''Why add a colon here?''' This allows it to conform better with W3C URN/URL standards. '''":"''' added after '1'. -* Hyphens'''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. '''"-"''' added after every 4 characters beyond the colon. +* Hyphens'''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. '''"-"''' added after every 4 characters beyond the colon. All non-bech32-alphabet characters after the bech32 code separator MUST be ignored/removed when parsing (except for terminating characters).'''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. @@ -116,10 +116,10 @@ All non-bech32-alphabet characters after the bech32 code separator MUST be ignor |1 |"'''-'''" |} -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). +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). === Data === -The 75 or 90 bits of data encoded in the string above are defined in this manner: +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: {| class="wikitable" |+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 !'''Values''' !'''Notes''' |- -|Magic +|Magic Code |0 – 4 |5 |Chain Namespacing Code @@ -161,7 +161,7 @@ The 75 or 90 bits of data encoded in the string above are defined in this manner |Tx 0 (coinbase) to Tx position 32767 |Max Tx's in block is 16665 |} -If the magic is '''0x4''' or '''0x7''', an optional outpoint is included in the encoding: +If the magic code is '''0x4''' or '''0x7''', an optional outpoint is included in the encoding: {| class="wikitable" |+Optional Outpoint Index Encoding: @@ -176,7 +176,7 @@ If the magic is '''0x4''' or '''0x7''', an optional outpoint is included in the |45 – 59 |15 |The index of the Outpoint inside the Tx -|Outpoint 0 to Outpoint Position 32767 +|Outpoint 0 to Outpoint Position 32767 | |} @@ -220,11 +220,11 @@ There are no known compatibility issues. == Reference implementations == -C Reference Implementation (supports version 0): https://github.com/jonasschnelli/bitcoin_txref_code +C Reference Implementation (supports magic codes 0x3 and 0x6): https://github.com/jonasschnelli/bitcoin_txref_code -Go Reference Implementation (supports version 0): https://github.com/kulpreet/txref +Go Reference Implementation (supports magic codes 0x3 and 0x6): https://github.com/kulpreet/txref -C++ Reference Implementation (support versions 0 and 1): https://github.com/dcdpr/btcr-DID-method/blob/master/libtxref +C++ Reference Implementation (support magic codes 0x3, 0x4, 0x6, 0x7): https://github.com/dcdpr/btcr-DID-method/ == Appendices == @@ -232,7 +232,7 @@ C++ Reference Implementation (support versions 0 and 1): https://github.com/dcdp There are two sets of Test Vectors included here: * Bech32 Encoding Test Vectors. These are to test if a implementation accepts the encoding, with the correct human readable part, and separator. -* Bitcoin TxRef Test Vectors. These test the full specification, in particular correct values for block height and the transaction index. +* Bitcoin TxRef Test Vectors. These test the full specification, in particular, correct values for block height and the transaction index. ==== Bech32 Encoding (for TxRef). ==== ''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. * bc1qw508d6qejxtdg4y5r3zarvary0c5xw7kg3g4ty: Invalid human-readable part * tx1qw508d6qejxtdg4y5r3zarvary0c5xw7kv8f3t5: Invalid checksum -==== Bitcoin TxRef ==== -The following list gives properly encoded Bitcoin TxRef's and the values in hex. (block height, transaction index) +==== Bitcoin TxRef (mainnet and testnet) ==== +The following list gives properly encoded Bitcoin mainnet TxRef's and the values in hex. (block height, transaction index) * tx1:rqqq-qqqq-qmhu-qhp: (0x0, 0x0) * tx1:rqqq-qqll-l8xh-jkg: (0x0, 0x7FFF) * tx1:r7ll-llqq-qghq-qr8: (0xFFFFFF, 0x0) * tx1:r7ll-llll-l5xt-jzw: (0xFFFFFF, 0x7FFF) -The following list gives valid Bitcoin TxRef's and the values in hex. (block height, transaction index) +The following list gives properly encoded Bitcoin testnet TxRef's and the values in hex. (block height, transaction index) + +* txtest1:xqqq-qqqq-qkla-64l: (0x0, 0x0) +* txtest1:xqqq-qqll-l2wk-g5k: (0x0, 0x7FFF) +* txtest1:x7ll-llqq-q9lp-6pe: (0xFFFFFF, 0x0) +* txtest1:x7ll-llll-lew2-gqs: (0xFFFFFF, 0x7FFF) + +The following list gives valid (though strangely formatted) Bitcoin TxRef's and the values in hex. (block height, transaction index) * tx1:rjk0-uqay-zsrw-hqe: (0x71F69, 0x89D) * TX1RJK0UQAYZSRWHQE: (0x71F69, 0x89D) * TX1RJK0--UQaYZSRw----HQE: (0x71F69, 0x89D) @@ -268,6 +275,38 @@ The following list gives invalid Bitcoin TxRef's and the reason for their invali * tx1:rjk0-u5ng-gghq-fkg7: Valid Bech32, but 10x5bit packages instead of 8. * tx1:rjk0-u5qd-s43z: Valid Bech32, but 6x5bit packages instead of 8. +==== Bitcoin TxRef with Outpoints (mainnet and testnet) ==== +The following list gives properly encoded Bitcoin mainnet TxRef's with Outpoints and the values in hex. (block height, transaction index, TXO index) + +* tx1:yqqq-qqqq-qqqq-ksvh-26: (0x0, 0x0, 0x0) +* tx1:yqqq-qqll-lqqq-v0h2-2k: (0x0, 0x7FFF, 0x0) +* tx1:y7ll-llqq-qqqq-a5zy-tc: (0xFFFFFF, 0x0, 0x0) +* tx1:y7ll-llll-lqqq-8tee-t5: (0xFFFFFF, 0x7FFF, 0x0) + +* tx1:yqqq-qqqq-qpqq-5j9q-nz: (0x0, 0x0, 0x1) +* tx1:yqqq-qqll-lpqq-wd7a-nw: (0x0, 0x7FFF, 0x1) +* tx1:y7ll-llqq-qpqq-lktn-jq: (0xFFFFFF, 0x0, 0x1) +* tx1:y7ll-llll-lpqq-9fsw-jv: (0xFFFFFF, 0x7FFF, 0x1) + +* tx1:yjk0-uqay-zrfq-g2cg-t8: (0x71F69, 0x89D, 0x123) +* tx1:yjk0-uqay-zu4x-nk6u-pc: (0x71F69, 0x89D, 0x1ABC) + +The following list gives properly encoded Bitcoin testnet TxRef's with Outpoints and the values in hex. (block height, transaction index, TXO index) + +* txtest1:8qqq-qqqq-qqqq-cgru-fa: (0x0, 0x0, 0x0) +* txtest1:8qqq-qqll-lqqq-zhcp-f3: (0x0, 0x7FFF, 0x0) +* txtest1:87ll-llqq-qqqq-nvd0-gl: (0xFFFFFF, 0x0, 0x0) +* txtest1:87ll-llll-lqqq-fnkj-gn: (0xFFFFFF, 0x7FFF, 0x0) + +* txtest1:8qqq-qqqq-qpqq-622t-s9: (0x0, 0x0, 0x1) +* txtest1:8qqq-qqll-lpqq-q43k-sf: (0x0, 0x7FFF, 0x1) +* txtest1:87ll-llqq-qpqq-3wyc-38: (0xFFFFFF, 0x0, 0x1) +* txtest1:87ll-llll-lpqq-t3l9-3t: (0xFFFFFF, 0x7FFF, 0x1) + +* txtest1:8jk0-uqay-zrfq-xjhr-gq: (0x71F69, 0x89D, 0x123) +* txtest1:8jk0-uqay-zu4x-aw4h-zl: (0x71F69, 0x89D, 0x1ABC) + + === Bitcoin TxRef Payload Value Choice: === Some calculations showing why we chose these particular bit-length of the block height and transaction index. @@ -285,24 +324,5 @@ Some calculations showing why we chose these particular bit-length of the block *The ''extreme'' smallest Tx is 60 Byte's: Max 16665 tx in a block. **4B version + 1B tx_in count + 36B previous_output + 1B script length + 0B signature script + 4B sequence + 1B tx_out count + 8B amount + 1B script length + 0B pubkey script + 4B lock_time = 60B -=== Test Vectors (version 1) === -These test vectors are extended TxRefs (version 1): - -==== Bitcoin Extended TxRef ==== -The following list gives properly encoded Bitcoin Extended TxRef's and the values in hex. (block height, transaction index, TXO index) - -* tx1:rpqq-qqqq-qqqq-q2ge-ahz: (0x0, 0x0, 0x0) -* tx1:rpqq-qqql-llqq-qshz-qhw: (0x0, 0x7FFF, 0x0) -* tx1:rp7l-lllq-qqqq-qpvh-wkq: (0xFFFFFF, 0x0, 0x0) -* tx1:rp7l-llll-llqq-qmnv-nkv: (0xFFFFFF, 0x7FFF, 0x0) - -* tx1:rpqq-qqqq-qqpq-qg2s-2w6: (0x0, 0x0, 0x1) -* tx1:rpqq-qqql-llpq-qj4t-hwk: (0x0, 0x7FFF, 0x1) -* tx1:rp7l-lllq-qqpq-qrw7-e0c: (0xFFFFFF, 0x0, 0x1) -* tx1:rp7l-llll-llpq-qe39-y05: (0xFFFFFF, 0x7FFF, 0x1) - -* tx1:rpjk-0uqa-yzu4-x0w0-kuq: (0x71F69, 0x89D, 0x1ABC) -* txtest1:xpjk-0uqa-yzu4-xgrl-pue: (0x71F69, 0x89D, 0x1ABC) (testnet, magic number = 0x6) - == Acknowledgements == Special Thanks to Pieter Wuille and Greg Maxwell for Bech32, a wonderful user-facing data encoding. -- cgit v1.2.3