BIP: XXXX Layer: Applications Title: Bech32 Encoded Transaction Position References Author: Велеслав <veleslav.bips@protonmail.com>, Jonas Schnelli <dev@jonasschnelli.ch> Comments-Summary: No comments yet. Comments-URI: https://github.com/bitcoin/bips/wiki/Comments:BIP-XXXX Status: Draft Type: Informational Created: License: BSD-2-Clause
This document proposes a Bech32 encoded transaction position reference, "TxRef", and a standard for referencing the positions of confirmed transactions using it.
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.
This BIP is licensed under the 2-clause BSD license.
Bitcoin uses regularly use TxID (Transaction Identifiers) for referencing individual transactions. TxID's are a core part of the consensus protocol and were naturally exported to the user-space since the first release of Bitcoin.
However, for many use-cases they have practical limitations:
- TxID's are expensive for full nodes to lookup.
- TxID's require third-party service for SPV wallets to lookup.
- TxID's are very long HEX encoded values (64 characters long).
- TxID's are without checksums.
All examples use the Bitcoin Display Format 0 described in Bitcoin Display Formats appendix.
- Genesis Coinbase Transaction: tx1:rqqq-qqqq-qmhu-qk
- Transaction #2205 of Block #466793: tx1:rjk0-u5ng-4jsf-mc
A confirmed transaction position reference, or TxRef is reference to a particular location within the blockchain specified by the block height and the transaction position.
Please Note: All values in this specification are encoded in little-endian format.
A TxRef may reference a location that doesn't exist because:
- The block height hasn't been minded yet.
- The Transaction Position is more than the total transaction within the referenced block.
- 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 reorganization, the TxRefs Displayed may point to a different transaction, or to no transaction at all.
This specification provides standardisation of encoding and namespacing for application display formats.
If a display format doesn't comply with this standard, it MUST be called a non-standard application display format.
- All display formats MUST be encoded with standard Bech32[1] encoding as defined within the BIP 0173 specification.
- The Human Readable Part of the Bech32 encoding MUST be "tx"[2].
- All Non Bech32 alphabet characters after the Bech32 code separator MUST be ignored when phasing, (except for terminating characters).[3]
- Every non-compatible system MUST use a different magic code.
- The magic code MUST be prefixed to the data payload, and included in the Bech32 encoding.
- Applications MUST reject codes with unknown magic codes.
- Applications MUST display an error for known, but unsupported magic codes.
- Magic codes are either 5, 10, 15, or 20-bits long.
- The length of the magic code is set by the first 5 bits:
- 0x0 to 0x7: 5-bit long. (All Reserved[4] for Bitcoin-Related Use, we have the special exception for Litecoin, that is also assigned a 5-bit code.)
- 0x8 to 0x15: 10-bit long.
- 0x16 to 0x23: 15-bit long.
- 0x24 to 0x31: 20-bit long.
There are no known compatibility issues.
- ^ 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.
- ^ Why use the same Human Readable Part for different systems or blockchains? The ‘tx1’ prefix is to namespace the Bech32 encoding to this specification. We use Magic Values internally to namespace between projects.
- ^ Why Strip all Non-Bech32 Alphabet Characters? We do not wish to expect the users to keep their TxRef's in good unicode form. We expect them to copy, paste, write by-hand, write in a mix of character sets, etc. Parsers should automaticity correct for all of these sorts of errors. However, we only specify the removal of non-bech32-alphabet characters.
- ^ Why reserve all single character Magic Codes? The authors of this specification see many potential Bitcoin Related uses for additional magic codes, such as with Sidechains and other Special User Facing Projects.
C Reference Implementation: https://github.com/jonasschnelli/bitcoin_txref_code
This appendix contains test vectors for TxRef Standard Application Display Formats.
Please Note: All test vectors are shown to help test if a Standard Display Client is compliant or not. All real-life applications should comply with the Display Format's own Test Vectors
The following strings have a valid Human Readable Part and Bech32 Checksum.
- TX1A12UEL5L
- tx1an83characterlonghumanreadablepartthatcontainsthenumber1andtheexcludedcharactersbio1tt5tgs
- tx1abcdef1qpzry9x8gf2tvdw0s3jn54khce6mua7lmqqqxw
- tx11qqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqc8247j
- bc1qw508d6qejxtdg4y5r3zarvary0c5xw7kg3g4ty: Invalid human-readable part
- tx1qw508d6qejxtdg4y5r3zarvary0c5xw7kv8f3t5: Invalid checksum
This appendix contains a table of the allocated or reserved magic codes.
- If you wish to claim a magic code, please open a pull request adding the code to this list.
- If this list becomes too popular, we will move it to another location.
Magic Values 5-bit long:
| Magic Value | Starting Value(s) | Display | Description |
| 0x0 | ‘q’ | Reserved | |
| 0x1 | ‘p’ | Reserved | |
| 0x2 | ‘z’ | Reserved | |
| Bitcoin | 0x3 | ‘r’ | Bitcoin Main Chain |
| Litecoin | 0x4 | ‘y’ | Litecoin Main Chain |
| 0x5 | ‘9’ | Reserved | |
| Testnet | 0x6 | ‘x’ | Any Test Network |
| 0x7 | ‘8’ | Reserved |
Magic Values 10-bit long: (none allocated).
Magic Values 15-bit long: (none allocated).
Magic Values 20-bit long: (none allocated);
For non-bitcoin related display formats please reference the external SLIP-XXXX "TxRef Non-Bitcoin Display Formats".
This appendix contains the specifications for Bitcoin Related Application Display Formats.
- If you wish to contribute a new display-format, please open a pull request adding to this appendix.
- We have considered various encoding schemes, and have found that variable-length schemes have a too-high overhead.
- In the case there is a Hard-Fork that extends Bitcoin's Block Transaction Capacity over the 8191 of the provided display format, we will simply define a `Bitcoin Display Format 1`. Considering the considerable disruption a Hard Fork causes; the creation of a secondary Display Format should not be of significant concern.
- In the case there is a Drive-Chain style extension or other indirect extension to Bitcoin's transactional capacity; it makes no sense to try and define for an undefined format now. We will simply use a new Magic Value and create a tailored Display Format for the new system.
- In the case that it is nearing Year 2048, we think that we will be in a far-better position to define a new format that suits the needs of the Bitcoin users than now.
This application display format is defined for all Bitcoin main-network transactions that have:
- Block Height
- Between 0, and 0x1FFFFF.
- Transaction Position
- Between 0, and 0x1FFF.
- Separators MUST be added as shown: tx1:rXXX-XXXX-XXXX-XX.
| Format ‘0’ | Bit | Bit(s) | 14 Character Encoding = 40bit + 30bit checksum |
| Magic | 0 – 4 | 5 | 0x3 |
| Version | 5 | 1 | Must be set to 0x0 |
| Block Height | 6 – 26 | 21 | From the Genesis Block to about Year 2048 |
| Tx Position | 27 – 39 | 13 | 8191 transactions. (A full Bitcoin Block without Hard Fork). |
The following list gives properly encoded Display Format 0 TxRef's and the values in hex. (Block Height, Tx Position)
- 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: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)
- 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.
This appendix contains the specifications for Special Display formats that should not be used in production use.
This non-standard application display format is defined for all test-network transactions that have:
- Block Height
- Between 0, and 0x3FFFFFF.
- Transaction Position
- Between 0, and 0x3FFFF
This application display format produces a 16-character data part starting with the character ‘x’.
- Separators MUST be added as shown: testtx1:xXXX-XXXX-XXXX-XXXX.
| Format ‘A’ | Bit | Bit(s) | 16 Character Encoding = 50bit + 30bit checksum |
| Magic | 0 – 4 | 5 | 0x6 |
| Version | 5 | 1 | Must be set to 0x0 |
| Block Height | 6 – 31 | 26 | |
| Tx Position | 32 – 49 | 18 |
Special Thanks to Pieter Wuille and Greg Maxwell for Bech32, a wonderful user-facing data encoding.