Merge pull request bitcoin#587 from mruddy/bip173

bip-0173: test vectors, HRP, and casing requirements updates

Author: luke-jr

bip-0173.mediawiki

@@ -76,7 +76,7 @@ increase, but that does not matter when copy-pasting addresses.</ref> format cal
 
 A Bech32<ref>'''Why call it Bech32?''' "Bech" contains the characters BCH (the error
 detection algorithm used) and sounds a bit like "base".</ref> string is at most 90 characters long and consists of:
-* The '''human-readable part''', which is intended to convey the type of data or anything else that is relevant for the reader. Its validity (including the used set of characters) is application specific, but restricted to ASCII characters with values in the range 33-126.
+* The '''human-readable part''', which is intended to convey the type of data, or anything else that is relevant to the reader. This part MUST contain 1 to 83 US-ASCII characters, with each character having a value in the range [33-126]. HRP validity may be further restricted by specific applications.
 * The '''separator''', which is always "1". In case "1" is allowed inside the human-readable part, the last one in the string is the separator<ref>'''Why include a separator in addresses?''' That way the human-readable
 part is unambiguously separated from the data part, avoiding potential
 collisions with other human-readable parts that share a prefix. It also
@@ -153,7 +153,7 @@ guarantees detection of '''any error affecting at most 4 characters'''
 and has less than a 1 in 10<sup>9</sup> chance of failing to detect more
 errors. More details about the properties can be found in the
 Checksum Design appendix. The human-readable part is processed by first
-feeding the higher bits of each character's ASCII value into the
+feeding the higher bits of each character's US-ASCII value into the
 checksum calculation followed by a zero and then the lower bits of each<ref>'''Why are the high bits of the human-readable part processed first?'''
 This results in the actually checksummed data being ''[high hrp] 0 [low hrp] [data]''. This means that under the assumption that errors to the
 human readable part only change the low 5 bits (like changing an alphabetical character into another), errors are restricted to the ''[low hrp] [data]''
@@ -182,11 +182,15 @@ to make.
 
 '''Uppercase/lowercase'''
 
-Decoders MUST accept both uppercase and lowercase strings, but
-not mixed case. The lowercase form is used when determining a character's
-value for checksum purposes. For presentation, lowercase is usually
-preferable, but inside QR codes uppercase SHOULD be used, as those permit
-the use of
+The lowercase form is used when determining a character's value for checksum purposes.
+
+Encoders MUST always output an all lowercase Bech32 string.
+If an uppercase version of the encoding result is desired, (e.g.- for presentation purposes, or QR code use),
+then an uppercasing procedure can be performed external to the encoding process.
+
+Decoders MUST NOT accept strings where some characters are uppercase and some are lowercase (such strings are referred to as mixed case strings).
+
+For presentation, lowercase is usually preferable, but inside QR codes uppercase SHOULD be used, as those permit the use of
 ''[http://www.thonky.com/qr-code-tutorial/alphanumeric-mode-encoding alphanumeric mode]'', which is 45% more compact than the normal
 ''[http://www.thonky.com/qr-code-tutorial/byte-mode-encoding byte mode]''.
 
@@ -262,22 +266,33 @@ P2PKH addresses can be used.
 
 ===Test vectors===
 
-The following strings have a valid Bech32 checksum.
+The following strings are valid Bech32:
 * <tt>A12UEL5L</tt>
+* <tt>a12uel5l</tt>
 * <tt>an83characterlonghumanreadablepartthatcontainsthenumber1andtheexcludedcharactersbio1tt5tgs</tt>
 * <tt>abcdef1qpzry9x8gf2tvdw0s3jn54khce6mua7lmqqqxw</tt>
 * <tt>11qqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqc8247j</tt>
 * <tt>split1checkupstagehandshakeupstreamerranterredcaperred2y9e3w</tt>
+* <tt>?1ezyfcl</tt> WARNING: During conversion to US-ASCII some encoders may set unmappable characters to a valid US-ASCII character, such as '?'. For example:
+
+<pre>
+>>> bech32_encode('\x80'.encode('ascii', 'replace').decode('ascii'), [])
+'?1ezyfcl'
+</pre>
 
-The following strings have an invalid Bech32 checksum (with reason for invalidity):
+The following string are not valid Bech32 (with reason for invalidity):
 * 0x20 + <tt>1nwldj5</tt>: HRP character out of range
 * 0x7F + <tt>1axkwrx</tt>: HRP character out of range
+* 0x80 + <tt>1eym55h</tt>: HRP character out of range
 * <tt>an84characterslonghumanreadablepartthatcontainsthenumber1andtheexcludedcharactersbio1569pvx</tt>: overall max length exceeded
 * <tt>pzry9x0s0muk</tt>: No separator character
 * <tt>1pzry9x0s0muk</tt>: Empty HRP
 * <tt>x1b4n0q5v</tt>: Invalid data character
 * <tt>li1dgmt3</tt>: Too short checksum
 * <tt>de1lg7wt</tt> + 0xFF: Invalid character in checksum
+* <tt>A1G7SGD8</tt>: checksum calculated with uppercase form of HRP
+* <tt>10a06t8</tt>: empty HRP
+* <tt>1qzzfhee</tt>: empty HRP
 
 The following list gives valid segwit addresses and the scriptPubKey that they
 translate to in hex.