NAME
Bitcoin::Crypto::Bech32 - Bech32 implementation
SYNOPSIS
# none exported by default
use Bitcoin::Crypto::Bech32 qw(
translate_5to8
translate_8to5
encode_bech32
decode_bech32
encode_segwit
decode_segwit
get_hrp
);
# witness version - a number from 0 to 16, packed into a byte
my $version = pack 'C', 0;
# human readable part of the address - a string
my $network_hrp = Bitcoin::Crypto::Network->get->segwit_hrp;
# handles Bitcoin SegWit adresses
my $segwit_address = encode_segwit($network_hrp, $version . $pubkeyhash);
my $data_with_version = decode_segwit($segwit_address);
# handles custom Bech32 encoding
# should start with hello1
my $bech32str = encode_bech32('hello', [28, 25, 31, 0, 5], 'bech32');
my ($hrp, $data_aref, $type) = decode_bech32($bech32str);DESCRIPTION
Implementation of Bech32 algorithm (BIP-173 and BIP-350 compatible)
The module has a couple of layers of encoding, namely:
5-to-8 and 8-to-5 bits transformation
bech32, which handles checksums and human-readable (HRP) parts
segwit, which handles segwit program numbering and validation
For Bech32-encoded SegWit addresses, use "encode_segwit" and "decode_segwit". For custom uses of Bech32 (not in context of Bitcoin SegWit addresses), use "encode_bech32" and "decode_bech32".
If in doubt, use segwit functions, not bech32 functions!
FUNCTIONS
This module is based on Exporter. None of the functions are exported by default. Use :all tag to import all the functions at once.
encode_segwit
decode_segwit
my $encoded_address = encode_segwit($hrp, $segwit_program);
my $segwit_program = decode_segwit($encoded_address);Bech32 encoding / decoding valid for SegWit addresses. Human readable part validation is not included.
These functions also perform segwit program validation, see "validate_segwit" in Bitcoin::Crypto::Util.
Encoding takes two arguments which are a human readable part and a bytestring (segwit program).
Decoding takes bech32-encoded string. Returns the entire encoded data (bytestring) along with the segwit program version byte.
Encoding scheme (bech32 or bech32m) is chosen based on version included in the segwit program.
encode_bech32
decode_bech32
my $encoded_bech32 = encode_bech32($hrp, \@data, $type = 'bech32m');
my ($hrp, $data_aref, $type) = decode_bech32($encoded_bech32);Basic bech32 encoding / decoding.
Encoding takes up to three arguments which are:
a human readable part
an array reference of integer values to be encoded in bech32 (each must be between 0 and 31)
optional type, which may be
'bech32'or'bech32m'(also available in constant values Bitcoin::Crypto::Bech32::BECH32 and Bitcoin::Crypto::Bech32::BECH32M)
If omitted, the type will be equal to 'bech32m', which has more robust checksum.
Decoding takes a single parameter: a bech32-encoded string and returns a list which has the same values as arguments to encode_bech32 function, including $type. This means you can feed both bech32 and bech32m encodings to decode_bech32 and the function will identify and return the type for you.
These methods are not meant to work with Bitcoin SegWit addresses, use encode_segwit and decode_segwit for that instead.
translate_5to8
translate_8to5
my $bytestr = translate_5to8(\@int_array);
my $int_aref = translate_8to5($bytestr);These are helper functions that implement 5-bit to 8-bit encoding used in bech32 segwit addresses. translate_8to5 is used during encoding, and translate_5to8 during decoding. They are used as means to store full byte data in bech32 strings, like so:
my $data = encode_bech32('hrp', translate_8to5($bytes));
my @decoded_parts = decode_bech32($data);
my $decoded = translate_5to8($decoded_parts[1]);get_hrp
$hrp = get_hrp($address)Returns the human readable part encoded in the bech32 address.
EXCEPTIONS
This module throws an instance of Bitcoin::Crypto::Exception::Bech32 if it encounters an error. It can produce the following error types from the Bitcoin::Crypto::Exception namespace:
Bech32InputFormat - input was not suitable for bech32 operations due to invalid format
Bech32InputData - input was parsed with bech32 operations but contained invalid data
Bech32InputChecksum - checksum validation has failed