Skip to content

Latest commit

 

History

History
318 lines (249 loc) · 14.3 KB

BBQr.md

File metadata and controls

318 lines (249 loc) · 14.3 KB

BBQr - Better Bitcoin QR

Public Domain by Coinkite

Introduction

This protocol is for transmitting binary data over a series of QR codes. Sometimes these are called "animated QR codes".

We propose adding a 8-byte header to the QR codes, and encoding them with care, based on a good understanding of the QR standard and how it works under the covers.

The result can encode PSBT and signed transactions up to 500k long, and supports decoding the QR's in any order.

Binary to Text Encoding

Your QR MUST use the "alphanumeric" character encoding defined by the low-level QR standard.

Not all QR libraries will have a suitable API for this: they may always use "byte" mode. Such libraries could still be used with this standard, but they will always produce sub-optimal results. Other libraries lack an API, but will auto-detect the character set when optimizing the QR output.

The data inside the QR code (including our header) must use only the alnumeric character set: 0-9A-Z$%*+-./:. This includes only capital letters and not all symbols.

It's usually easiest if binary data is HEX encoded (capital letters only: 0-9 and A-F). This format has no packing/padding concerns and fits in alnum encoding of QR.

ECC Levels

QR codes support 4 levels of forward error correction. Since we are not printing these codes, and only showing them on a perfect LCD screen, we recommend always using level "L" (lowest) for error correction. Although that is not required, all the examples in this document assume this ECC level, and if you use more error correction, your QR's will hold less and you will need more of them.

Spliting the Data

Divide your data equally, and prepend the following header to each part. The header indicates where the (decoded) data belongs, and allows recovery in any order.

This seven-character header must be added inside the start of each QR:

B$                  fixed header for this protocol (2 chars)
H                   one char of data encoding: H=Hex
P                   one char file type: P=PSBT, T=TXN, etc
05                  Two digits of base 36: total number of QR codes (0-9A-Z)
00                  Two digits of base 36: which QR code this is in the sequence
(HEX or Base32 characters follow)

All blocks must be equal length, except for the last one. This allows the receiver to place received data into the correct place without receiving the entire series. If the final QR is received before any others, the "runt" packet will need to be held until at least one other block is seen. In any other case, meaning any block except the last is seen first, the (upper bounds) final file size can be determined immediately, and appropriately-sized buffers created. This consideration can be important in embedded applications such as hardware wallets.

Each blocks must decode to an integer number of bytes. This means there must be an even number of HEX digits in each block. For encodings that encode other than modulo 8 bits, no padding characters are needed because of this requirement.

We are assuming the length of a single, successfully-decoded QR code is known by the receiver. QR codes cannot be truncated in-flight due to their error correction codes.

All blocks must specify the same encoding, file type and number of blocks. This means the first 6 characters will be the same in all the QR codes.

If, for some reason, you want to add the header to some data that does not need to be split, you may use B$te0100. The length of the data will be the entire QR (after the header) and there is only one block. This is 8 characters of overhead to communicate the file type and encoding.

Example Headers

B$HP0300(2000 HEX digits) B$HP0301(2000 HEX digits) B$HP0302(300 HEX digits)

  • It's a PSBT file.
  • 2150 bytes when fully decoded back to binary.
  • All but final QR holds 1000 bytes when decoded, and will be 2007 characters in length.
  • Version 27 could be used (holding up to 2,132 characters), yielding 125x125 pixels.

Optimizations

Once you are commited to multiple QR codes, you have a few options for splitting.

You could go straight to the highest possible density for each QR, but scanning those QR's can be more difficult. Better would be to use a few more QR's that are easier to scan.

This protocol does not restrict your choice of QR size. The smallest size QR (version 1, 21x1 pixels, 25 chars payload) could be used for small files, but only a few bytes of useful data will be encoded in each QR.

Version 27 (125 x 125 pixels) offers up to 1062 bytes of useful payload per QR, so it is a good sweet spot to consider. A simple implementation would split file into 1k (1024) blocks, with one runt, and can be sure that verison 27 QR will hold all the blocks.

If you target the most dense version QR (version 40, 177 x 177 pixels) then each block should have 2144 bytes in it and the resulting series will be the shortest possible number of QR.

When to Not Split?

If you data is up to 2,144 bytes (binary) in size, then it could be sent as a single QR (version 40, level L ECC). Simply take the PSBT or transaction binary, encode as HEX and make a QR from it and your are done.

Since the typical Bitcoin wire transaction is less than 500 bytes, most finalized transactions will be encoded in a single QR with no header or other overhead needed.

Size Estimates

This is the exact number of bytes that can be encoded into the indicated QR version, given 2, 5 or 10 splits.

Vers Pixels Chars Payload 2-split 5-split 10-split 20-split
1 21x21 25 8 16 40 80 160
11 61x61 468 230 460 1150 2300 4600
23 109x109 1588 790 1580 3950 7900 15800
24 113x113 1704 848 1696 4240 8480 16960
25 117x117 1853 922 1844 4610 9220 18440
26 121x121 1990 991 1982 4955 9910 19820
27 125x125 2132 1062 2124 5310 10620 21240
28 129x129 2223 1107 2214 5535 11070 22140
29 133x133 2369 1180 2360 5900 11800 23600
30 137x137 2520 1256 2512 6280 12560 25120
31 141x141 2677 1334 2668 6670 13340 26680
32 145x145 2840 1416 2832 7080 14160 28320
33 149x149 3009 1500 3000 7500 15000 30000
34 153x153 3183 1587 3174 7935 15870 31740
35 157x157 3351 1671 3342 8355 16710 33420
36 161x161 3537 1764 3528 8820 17640 35280
37 165x165 3729 1860 3720 9300 18600 37200
38 169x169 3927 1959 3918 9795 19590 39180
39 173x173 4087 2039 4078 10195 20390 40780
40 177x177 4296 2144 4288 10720 21440 42880

"Chars" is the number of alphanumeric characters the QR can hold (including the B$ header)."Payload" is the number of bytes of useful data transfered per QR, if HEX encoding is used.

Notes

  • It's so simple that even a human could split or combine these codes!
  • This protocol produces QR codes that are text and have no spaces, so they are easy to "cut n paste" as a single block.
  • All "N" QR codes must be scanned, there is no way to "skip" one, but they do not have to be seen in any particular order.
  • Since a version 40 QR holds 4296 characters and we support up to 1295 (ZZ in base 36) parts, the largest possible (uncompressed) file is 2,776,480 for HEX, and 3,470,600 for Base32 encoding.
  • If you are doing 3 QR codes, best if all have about the same amount of data, don't just have a small runt QR at the end, because you are making the QR's harder to read.
  • It is visually jarring to have the final QR be a different version (resolution) than the other ones. You should force the QR version to be the same in the whole series.
  • Since QR codes themselves feature very robust error detection and recovery, there is no need for checksums or other such complexity at this level.
  • Be sure your hex is always capitalized, including the variable parts of the header.
  • Colons and slashes are avoided so it does not look like a URL.
  • Base64 is avoided because it's character set would require use of 8-bit encoding.

Additional Type Codes

We do not see the need for too many Bitcoin-specific "data types" inside QR data, since on the receiving side, it is usually clear what is needed by context. Your software would need to be pretty dumb to accept a PSBT file when it was expecting a list of seed words! Similarly, when a payment address is expected, a BIP-21 URL is trivial to pull apart and get the address needed. Bitcoin addresses have reasonable text encodings and internal checksums, plus Bech32 was designed for direct use inside QR codes.

That said, we will add more type codes if the community wants them.

If we need to move to 2-character codes, it could be done after the first 36 are consumed, but B$ prefix will be updated to some other symbols.

Code File Contents
P PSBT file
T Ready to send Bitcoin wire transaction
J JSON data (general purpose)
C CBOR data (general purpose)
U Unicode text (UTF-8 encoded, simple text)
B Binary data (generic octet stream)
X Executable data (platform dependant)

All other codes are reserved. Please submit a PR to this repo to add your new types. If you are experimenting, please use "B" until your letter is assigned.

Note that J (JSON) and U (unicode) still require the data to be treated as binary and encoded in Hex or Base32.

Other file types will not be added unless there is a single well-accepted standard for how to parse the data. Typically this means a BIP number, or community-driven web site and implementations in multiple languages.

Advanced Encodings

The easier encoding for the data of the QR's is HEX, and the 3rd character in the header selects that format if it is H.

Using HEX encoding inside alphanumeric encoding of the QR yields data transfer rate comparable to the QR code's native binary rate, since we are sending 4 bits (one hex digit) as 5.5 low-level QR bits.

But we can do better, and transfer more bits in the same space.

Encoding Meaning
H HEX (capitalized hex digits, 4-bits each)
2 Base32 using RFC 4648 alphabet
Z Zlib compressed (wbits=10, no header) then Base32
(others) All other codes are reserved.

Base32 puts 5.0 bits into 5.5 bits of QR data and is closer to optimium in terms of packing. Just as it is an error to send an odd number of hex digits in a QR block, for Base32 you must send complete bytes. In practise, this means all but the last QR will be mod8 in length of characters. The Base32 padding character must be omitted, and the = character should never be used (and it's not part of the legal alnum charset anyway).

Mode "Z" involves compressing the binary data and then sending as Base32. Because the target for this data is embedded systems and we are trying to save every last byte, the details of the compression are fixed: You must use zlib and provide a wbits value of 10. No Gzip nor Zlib file header should be included, and they are not needed since the wbits value is fixed. The compression level should typically be set to maximum compression effort (9) but the fixed wbits value limits this somewhat. We restrict wbits to this value because it defines the amount of memory the decoder will need to decompress the data. The entire file must be compressed as a whole before splitting and encoding into the individual QR codes. Receivers will need to receive all parts of the QR series before starting decompression, so the memory needs are higher than the other encodings.

The above encodings must be implemented by receivers, and are not optional. For QR creators, they are free to pick the encoding they prefer.

Keep in mind that some Bitcoin data is very high entropy (addresses, UTXO, etc) so zlib compression does not always help. You should fall back to Base32 encoding rather than send a QR that is larger than needed.

Here are some compression numbers, using wbits=10 as required (all bytes here, no encoding).

File (see testing/data) Before After Compression Ratio
1in1000out.psbt 35644 22095 38.0%
1in100out.psbt 4142 2654 35.9%
1in10out.psbt 992 670 32.5%
1in20out.psbt 1342 897 33.2%
1in2out.psbt 675 458 32.1%
devils-txn.txn 666 356 46.5%
finalized-by-ckcc.txn 1932 807 58.2%
last.txn 553 530 4.2%
nfc-result.txn 376 362 3.7%
signed.txn 100757 77090 23.5%

Coldcard Q Suggestions

Encoding

  • 250ms frame rate is recommended. Coldcard Q is fine-tuned for this data rate.
  • Avoid very high versions (too dense). Better to have a more lower-rez QR codes, when sending.
  • Always use the Zlib encoding to save space, but if you don't want to implement it... don't.
  • If you want to KISS, take hex encoded PSBT and split it evenly, then just add 8 character heading to each one: B$HP0n0x where n (number of parts) and x (which part) is single character: 0-9/A-Z for up to 36 parts.

Decoding

  • Coldcard Q will favour bare QR codes (not BBQr encoded) when it can be made to fit. For signed transactions, that will be HEX encoded bytes.
  • Because modern cellphones are so good at scanning very high version QR codes, the Coldcard Q will produce up to verison 40 in order to avoid animating.
  • To better suit cellphones capabilties, the animated BBQr's the Coldcard generates will be shown rather slowly.
  • Be prepared to decode Zlib encoded QR codes.

Public Service Announcement

Never put your bitcoin-related data into a public website in order to render a QR code. You should expect all such websites to be scams.