Bech32 Encoded Tx Position References

  BIP: 136
  Layer: Applications
  Title: Bech32 Encoded Tx Position References
  Authors: Велеслав 
           Jonas Schnelli 
           Daniel Pape 
  Status: Draft
  Type: Informational
  Assigned: 2017-07-09
  License: BSD-2-Clause

Introduction

Abstract

This document proposes a convenient, human usable encoding to refer to a confirmed transaction position within the Bitcoin blockchain--known as "TxRef". The primary purpose of this encoding is to allow users to refer to a confirmed transaction (and optionally, a particular outpoint index within the transaction) in a standard, reliable, and concise way.

Please note: Unlike a transaction ID, "TxID", where there is a strong cryptographic link between the ID and the actual transaction, a TxRef only provides a weak link to a particular transaction. A 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 TxRefs should be not used for positions within the blockchain having a maturity less than 100 blocks.

The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in RFC 2119.

Copyright

This BIP is licensed under the 2-clause BSD license.

Motivation

Since the first version of Bitcoin, TxIDs have been a core part of the consensus protocol and are 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 services for SPV wallets to lookup.
• TxIDs are 64 character HEX encoded values.

It is possible to reference transactions not only by their TxID, but by their location within the blockchain itself. Rather than use the 64 character TxID, an encoding of the position coordinates can be made friendly for occasional human transcription. In this document, we propose a standard for doing this.

Examples

Block #	Transaction #	Outpoint #	TxRef	TxID
0	0	0	tx1:rqqq‑qqqq‑qwtv‑vjr	4a5e1e4baab89f3a32518a88c31bc87f618f76673e2cc77ab2127b7afdeda33b
170	1	0	tx1:r52q‑qqpq‑qpty‑cfg	f4184fc596403b9d638783cf57adfe4c75c605f6356fbc91338530e9831e9e16
456789	1234	1	tx1:y29u‑mqjx‑ppqq‑sfp2‑tt	6fb8960f70667dc9666329728a19917937896fc476dfc54a3e802e887ecb4e82

Specification

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, an outpoint index within the transaction.

Please Note: All values in this specification are encoded in little-endian format.

TxRef Considerations

It is possible for a TxRef to reference a transaction that doesn't really exist because:

• The specified block hasn't yet been mined.
• 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 TxRefs to users prematurely:

• Applications MUST NOT display TxRefs for transactions with less than 6 confirmations.
• Application MUST show a warning for TxRefs 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.

TxRef Format

TxRef MUST use the Bech32m encoding as defined in BIP-0173 and later refined in BIP-0350. The Bech32m encoding consists of:

Human-Readable Part

The HRP can be thought of as a label. We have chosen labels to distinguish between Main, Test, and Regtest networks:

• Mainnet: "tx".
• Testnet: "txtest".
• Regtest: "txrt".

Separator

The separator is the character "1".

Data Part

The data part for a TxRef consists of the transaction's block height, transaction index within the block, and optionally, an outpoint index. Specific encoding details for the data are given below.

Please note: other specifications, such as 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.

Readability

To increase portability and readability, additional separator characters SHOULD be added to the TxRef:

• A Colon ":" added after the separator character '1'.
• Hyphens "-" added after every 4 characters beyond the colon.

Encoding

Encoding a TxRef requires 4 or 5 pieces of data: a magic code denoting which network is being used; a version number (currently always 0); the block height of the block containing the transaction; the index of the transaction within the block; and optionally, the index of the outpoint within the transaction. Only a certain number of bits are supported for each of these values, see the following table for details.

	Description	Possible Data Type	# of Bits used	Values
style="background: #99DDFF; color: black; text-align : center;" | Magic Code	Chain Namespacing Code	uint8	style="background: #99DDFF; color: black; text-align : center;" | 5	3: Mainnet 4: Mainnet with Outpoint 6: Testnet 7: Testnet with Outpoint 0: Regtest 1: Regtest with Outpoint
style="background: #DDDDDD; color: black; text-align : center;" | Version	For Future Use	uint8	style="background: #DDDDDD; color: black; text-align : center;" | 1	Must be 0
style="background: #EEDD88; color: black; text-align : center;" | Block Height	The Block Height of the Tx	uint32	style="background: #EEDD88; color: black; text-align : center;" | 24	Block 0 to Block 16777215
style="background: #FFAABB; color: black; text-align : center;" | Transaction Index	The index of the Tx inside the block	uint16, uint32	style="background: #FFAABB; color: black; text-align : center;" | 15	Tx 0 to Tx 32767
style="background: #BBCC33; color: black; text-align : center;" | Outpoint Index	The index of the Outpoint inside the Tx	uint16, uint32	style="background: #BBCC33; color: black; text-align : center;" | 15	Outpoint 0 to Outpoint 32767

Magic Notes

The magic code provides namespacing between chains:

• For Mainnet the magic code is: 0x3, leading to an "r" character when encoded.
• For Mainnet with Outpoint Encoded the magic code is: 0x4, leading to a "y" character when encoded.
• For Testnet the magic code is: 0x6, leading to an "x" character when encoded.
• For Testnet with Outpoint Encoded the magic code is: 0x7, leading to an "8" character when encoded.
• For Regtest the magic code is: 0x0, leading to a "q" character when encoded.
• For Regtest with Outpoint Encoded the magic code is: 0x1, leading to a "p" character when encoded.

Encoding Example

We want to encode a TxRef that refers to Transaction #1234 of Block #456789 on the Mainnet chain. We use this data in preparation for the Bech32 encoding algorithm:

	Decimal Value	Binary Value	# of Bits used	Bit Indexes and Values
style="background: #99DDFF; color: black; text-align : center;" | Magic Code	style="background: #99DDFF; color: black; text-align : center;" | 3	00000011	style="background: #99DDFF; color: black; text-align : center;" | 5	(mc04, mc03, mc02, mc01, mc00) = (0, 0, 0, 1, 1)
style="background: #DDDDDD; color: black; text-align : center;" | Version	style="background: #DDDDDD; color: black; text-align : center;" | 0	00000000	style="background: #DDDDDD; color: black; text-align : center;" | 1	(v0) = (0)
style="background: #EEDD88; color: black; text-align : center;" | Block Height	style="background: #EEDD88; color: black; text-align : center;" | 456789	00000110 11111000 01010101	style="background: #EEDD88; color: black; text-align : center;" | 24	(bh23, bh22, bh21, bh20, bh19, bh18, bh17, bh16) = (0, 0, 0, 0, 0, 1, 1, 0) (bh15, bh14, bh13, bh12, bh11, bh10, bh09, bh08) = (1, 1, 1, 1, 1, 0, 0, 0) (bh07, bh06, bh05, bh04, bh03, bh02, bh01, bh00) = (0, 1, 0, 1, 0, 1, 0, 1)
style="background: #FFAABB; color: black; text-align : center;" | Transaction Index	style="background: #FFAABB; color: black; text-align : center;" | 1234	00000100 11010010	style="background: #FFAABB; color: black; text-align : center;" | 15	(ti14, ti13, ti12, ti11, ti10, ti09, ti08) = (0, 0, 0, 0, 1, 0, 0) (ti07, ti06, ti05, ti04, ti03, ti02, ti01, ti00) = (1, 1, 0, 1, 0, 0, 1, 0)

As shown in the last column, we take the necessary bits of each binary value and copy them into nine unsigned chars illustrated in the next table. We only set the lower five bits of each unsigned char as the bech32 algorithm only uses those bits.

{| class="wikitable" style="text-align: center" ! ! !style="width:2em"|7 !style="width:2em"|6 !style="width:2em"|5 !style="width:2em"|4 !style="width:2em"|3 !style="width:2em"|2 !style="width:2em"|1 !style="width:2em"|0 ! !Decimal
Value !Bech32
Character |- | || || || || || || || || || || || || |- | rowspan="2" | data[0] || Index |na |na |na | style="background: #99DDFF; color: black; text-align : center;" | mc04 | style="background: #99DDFF; color: black; text-align : center;" | mc03 | style="background: #99DDFF; color: black; text-align : center;" | mc02 | style="background: #99DDFF; color: black; text-align : center;" | mc01 | style="background: #99DDFF; color: black; text-align : center;" | mc00 | | | |- |Value |0 |0 |0 |0 |0 |0 |1 |1 | |3 |r |- | || || || || || || || || || || || |- | rowspan="2" | data[1] || Index |na |na |na | style="background: #EEDD88; color: black; text-align : center;" | bh03 | style="background: #EEDD88; color: black; text-align : center;" | bh02 | style="background: #EEDD88; color: black; text-align : center;" | bh01 | style="background: #EEDD88; color: black; text-align : center;" | bh00 | style="background: #DDDDDD; color: black; text-align : center;" | v0 | | | |- |Value |0 |0 |0 |0 |1 |0 |1 |0 | |10 |2 |- | || || || || || || || || || || || |- | rowspan="2" | data[2] || Index |na |na |na | style="background: #EEDD88; color: black; text-align : center;" | bh08 | style="background: #EEDD88; color: black; text-align : center;" | bh07 | style="background: #EEDD88; color: black; text-align : center;" | bh06 | style="background: #EEDD88; color: black; text-align : center;" | bh05 | style="background: #EEDD88; color: black; text-align : center;" | bh04 | | | |- |Value |0 |0 |0 |0 |0 |1 |0 |1 | |5 |9 |- | || || || || || || || || || || || |- | rowspan="2" | data[3] || Index |na |na |na | style="background: #EEDD88; color: black; text-align : center;" | bh13 | style="background: #EEDD88; color: black; text-align : center;" | bh12 | style="background: #EEDD88; color: black; text-align : center;" | bh11 | style="background: #EEDD88; color: black; text-align : center;" | bh10 | style="background: #EEDD88; color: black; text-align : center;" | bh09 | | | |- |Value |0 |0 |0 |1 |1 |1 |0 |0 | |28 |u |- | || || || || || || || || || || || |- | rowspan="2" | data[4] || Index |na |na |na | style="background: #EEDD88; color: black; text-align : center;" | bh18 | style="background: #EEDD88; color: black; text-align : center;" | bh17 | style="background: #EEDD88; color: black; text-align : center;" | bh16 | style="background: #EEDD88; color: black; text-align : center;" | bh15 | style="background: #EEDD88; color: black; text-align : center;" | bh14 | | | |- |Value |0 |0 |0 |1 |1 |0 |1 |1 | |27 |m |- | || || || || || || || || || || || |- | rowspan="2" | data[5] || Index |na |na |na | style="background: #EEDD88; color: black; text-align : center;" | bh23 | style="background: #EEDD88; color: black; text-align : center;" | bh22 | style="background: #EEDD88; color: black; text-align : center;" | bh21 | style="background: #EEDD88; color: black; text-align : center;" | bh20 | style="background: #EEDD88; color: black; text-align : center;" | bh19 | | | |- |Value |0 |0 |0 |0 |0 |0 |0 |0 | |0 |q |- | || || || || || || || || || || || |- | rowspan="2" | data[6] || Index |na |na |na | style="background: #FFAABB; color: black; text-align : center;" | ti04 | style="background: #FFAABB; color: black; text-align : center;" | ti03 | style="background: #FFAABB; color: black; text-align : center;" | ti02 | style="background: #FFAABB; color: black; text-align : center;" | ti01 | style="background: #FFAABB; color: black; text-align : center;" | ti00 | | | |- |Value |0 |0 |0 |1 |0 |0 |1 |0 | |18 |j |- | || || || || || || || || || || || |- | rowspan="2" | data[7] || Index |na |na |na | style="background: #FFAABB; color: black; text-align : center;" | ti09 | style="background: #FFAABB; color: black; text-align : center;" | ti08 | style="background: #FFAABB; color: black; text-align : center;" | ti07 | style="background: #FFAABB; color: black; text-align : center;" | ti06 | style="background: #FFAABB; color: black; text-align : center;" | ti05 | | | |- |Value |0 |0 |0 |0 |0 |1 |1 |0 | |6 |x |- | || || || || || || || || || || || |- | rowspan="2" | data[8] || Index |na |na |na | style="background: #FFAABB; color: black; text-align : center;" | ti14 | style="background: #FFAABB; color: black