repo: bech32
action: blob
revision: 
path_from: bech32.1.html
revision_from: refs/heads/master:
path_to: 
revision_to: 

blob of:

/ bech32.1.html

refs/heads/master:/bech32.1.html

 
 
 
   
   
   
 
 
 

   

     
BECH32(1)
     
General Commands Manual
     
BECH32(1)
   
 
 

 
NAME
 bech32 — Encode
   and decode Bech32 strings and Bitcoin Segwit addresses
 
SYNOPSIS
 General-purpose encoding and decoding:
 

 

 

   

     
bech32
     
-e -h
       hrp
       hexdata
   
 
 

 

   

     
bech32
     
-e -5
       -h hrp
       base32data
   
 
 

 

   

     
bech32
     
-d
       [-5]
       [-u]
       bech32string
     

     For Bitcoin Bravo Charlie addresses
       (“bc1”):
   
 
 

 

 

   

     
bech32
     
-s witver
       hexdata
   
 
 

 

   

     
bech32
     
-S bc1addr
     

     For .onion domains:
   
 
 

 

 

   

     
bech32
     
-e
       base32domain.onion
   
 
 

 

   

     
bech32
     
-d
       onion1bech32
   
 
 
DESCRIPTION
 The bech32 utility is a powerful general-purpose
   tool for encoding and decoding of BIP 173 standard Bech32 strings and Bitcoin
   Bech32 addresses.
 

 Hexadecimal data may be input with or without a leading “0x”
   prefix. It is output with such a prefix, to prevent ambiguity.
 

 It has the following modes, some of which overlap:
 

   
-e
   
Encoder mode. Output is a Bech32 string.
   
-d
   
Decoder mode. Output is the input string's human-readable
       part (HRP), followed by a delimiting colon (“:”), followed
       by the “data part” data in hexadecimal with a
       “0x” prefix.
   
-s
     witver
   
Encode a Bitcoin Segwit address with witness version
       witver.
   
-S
   
Decode a Bitcoin Segwit address. Output its witness version
       in decimal (0–16 inclusive), followed
       by a delimiting colon (“:”), followed by the address data in
       hexadecimal with a “0x”
     prefix.
   
(.onion autodetect)
   
Dot-onion mode. When encoding,
       bech32 will automatically detect a dot-onion
       domain and read its second level as RFC 4648 Base32 data. When decoding,
       bech32 will detect a “onion”
       HRP, and output a dot-onion domain.
 
 

 The options are as follows:
 

   
-h
     hrp
   
General encoding only, and required therefor. Provide the
       Human-Readable Portion (HRP) for the Bech32 string.
   
-5
   
Read RFC 4648 Base32 data when encoding, or write RFC 4648
       Base32 data when decoding.
   
-u
   
(Decoding only.) Output hexadecimal characters in
       uppercase.
 
 
EXIT
   STATUS
 The bech32 utility exits 0 on success,
   and >0 if an error occurs.
 
EXAMPLES
 Extract the witness version and Hash160 from the
   bech32 utility author's Bech32 tip address:
 

 
bech32 -S
   bc1qcash96s5jqppzsp8hy8swkggf7f6agex98an7h
 
0:0xc76172ea149002114027b90f0759084f93aea326
 

 Get a “hello, world” introduction to Bech32:
 

 
bech32 -e -h hello_world
   48656c6c6f2c20776f726c6421
 
hello_world1fpjkcmr09ss8wmmjd3jzzwhs4ff
 

 Generate a “burn address” with a Hash160 of all zeroes, which
   would be spendable by the same unknown private keys as the infamous
   1111111111111111111114oLvT2. Warning: Do NOT send
   coins here:
 

 
bech32 -s 0
   0x0000000000000000000000000000000000000000
 
bc1qqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqq9e75rs
 

 Bech32-encode the address for Wikileaks, to add error-correcting codes:
 

 
bech32 -e wlupld3ptjvsgwqw.onion
 
onion1kt50trm0nf4jxkskpcjy74
 

 Now, decode the address someone gave you:
 

 
bech32 -d
   onion1kt50trm0nf4jxkskpcjy74
 
wlupld3ptjvsgwqw.onion
 
STANDARDS
 The bech32 utility conforms to:
 

   
The Bech32 standard: P. Wuille, G. Maxwell,
       “Base32 address format for native v0–16 witness
       outputs”, 2016-03-20, Bitcoin
       BIP
       173.
   
S. Josefsson, “The Base16, Base32, and Base64
       Data Encodings”, 2006-10,
       RFC
       4648. (For transcoding RFC standard Base32 input data and .onion
       domains.)
   
J. Appelbaum, A. Muffett, “The
       ‘.onion’ Special-Use Domain Name”, 2015-10,
       RFC
       7686.
 
 

 The term “Bravo Charlie Address” and
   the motto “Bravo Charlie One means
   money” are from a
   proposal
   by this author.
 
AUTHORS
 The bech32 utility was written by
   nullius
   <nullius@nym.zone>.
 

 PGP: 0xC2E91CD74A4C57A105F6C21B5A00591B2F307E0C
 

 Tips:
   3NULL3ZCUXr7RDLxXeLPDMZDZYxuaYkCnG,
   bc1qcash96s5jqppzsp8hy8swkggf7f6agex98an7h.
 

 The internal Bech32 encoding and decoding is done by the open-source
   Bech32
   reference code written by Pieter Wuille (sipa) (no affiliation with this
   author).
 
BUGS
 This code started as a quickly-made utility for personal use, and kept growing
   as such things are wont to do. The user interface is reasonably logical, given
   the tool's flexibility. However, the source code needs some substantial
   refactoring.
 

 This manpage could use more and better examples, plus some other general
   editing.
 

 Test cases are needed. Unfortunately, the Bech32 standard does not currently
   provide full roundtrip test vectors for arbitrary Bech32 strings.
 

 Special support is planned for a concept which this author calls
   “PGP Descriptors”. However, a spec
   must be drawn before releasing such a thing into the wild.
 
SECURITY
   CONSIDERATIONS
 This is an early release, which should be considered alpha-quality software. It
   should not be used on untrusted inputs, such as
   anything blindly accepted by a webserver. High on the author's TODO list is to
   beef up input validation. At this time, aside from a few simple checks, the
   utility will happily pass the buck to the Bech32 reference functions.
 

   

     
December 31, 2017
     
Bitcoin