User:Danpape/bip136

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

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 encoding as defined in 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 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 ":" added after '1'.
 * Hyphens "-" 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).

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.

Reference implementations
C Reference Implementation: https://github.com/jonasschnelli/bitcoin_txref_code

Go Reference Implementation: https://github.com/kulpreet/txref

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 hight 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
 * <tt>tx1qw508d6qejxtdg4y5r3zarvary0c5xw7kv8f3t5</tt>: 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)


 * <tt>tx1:rqqq-qqqq-qmhu-qk</tt>: <tt>(0x0, 0x0)</tt>
 * <tt>tx1:rqqq-qull-6v87-r7</tt>: <tt>(0x0, 0x1FFF)</tt>
 * <tt>tx1:r7ll-lrqq-vq5e-gg</tt>: <tt>(0x1FFFFF, 0x0)</tt>
 * <tt>tx1:r7ll-llll-khym-tq</tt>: <tt>(0x1FFFFF, 0x1FFF)</tt>

The following list give valid Bitcoin TxRef's and the values in hex. (block height, transaction index)
 * <tt>tx1:rjk0-u5ng-4jsf-mc</tt>: <tt>(0x71F69, 0x89D)</tt>
 * <tt>TX1RJK0U5NG4JSFMC</tt>: <tt>(0x71F69, 0x89D)</tt>
 * <tt>TX1R1JK0--U5bNG4JSbFMC</tt>: <tt>(0x71F69, 0x89D)</tt>
 * <tt>tx1 rjk0 u5ng 4jsfmc</tt>: <tt>(0x71F69, 0x89D)</tt>
 * <tt>tx1!rjk0\u5ng*4jsf^^mc</tt>: <tt>(0x71F69, 0x89D)</tt>

The following list gives invalid Bitcoin TxRef's and the reason for their invalidity.
 * <tt>tx1:t7ll-llll-gey7-ez</tt>: Magic 0xB instead of 0x3. <tt>(0x1FFFFF, 0x1FFF)</tt>
 * <tt>tx1:rlll-llll-cgqu-n2</tt>: Version 1 instead of 0. <tt>(0x1FFFFF, 0x1FFF)</tt>
 * <tt>tx1:rjk0-u5ng-gghq-fkg7</tt>: Valid Bech32, but 10x5bit packages instead of 8.
 * <tt>tx1:rjk0-u5qd-s43z</tt>: 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.