NAME

Bitcoin::Crypto::Bech32 - Bitcoin's Bech32 implementation in Perl

SYNOPSIS

        # none exported by default
        use Bitcoin::Crypto::Bech32 qw(
                translate_5to8
                translate_8to5
                encode_bech32
                decode_bech32
                encode_segwit
                decode_segwit
        );

        # 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
        my $bech32str = encode_bech32("hello", [28, 25, 31, 0, 5], Bitcoin::Crypto::Bech32->BECH32); # should start with hello1
        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. :all tag exists that exports all the functions at once.

encode_segwit

        my $encoded_address = encode_segwit($hrp, $segwit_program);

decode_segwit

        my $segwit_program = decode_segwit($encoded_address);

Bech32 encoding / decoding valid for SegWit addresses. Does not validate the human readable part.

These functions also perform segwit program validation, see Bitcoin::Crypto::Segwit.

Encoding takes two arguments which are a human readable part and a bytestring.

Decoding takes bech32-encoded string. Returns the entire encoded data (bytestring) along with the segwit program version byte.

encode_bech32

        my $encoded_bech32 = encode_bech32($hrp, \@data, Bitcoin::Crypto::Bech32->BECH32 || Bitcoin::Crypto::Bech32->BECH32M);

decode_bech32

        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' (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 elements as arguments to encode_bech32 function.

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

        my $bytestr = translate_5to8(\@int_array);

translate_8to5

        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 can be used as means to store full byte data in bech32 strings, like so:

        my $data = encode_bech32('hrp', translate_8to5($bytes));
        my $decoded = translate_5to8(decode_bech32($data));

EXCEPTIONS

This module throws an instance of Bitcoin::Crypto::Exception 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

• Bech32Type - invalid type was passed to bech32_encode function

SEE ALSO

Bitcoin::Crypto::Base58

Bitcoin::Crypto::Segwit

Bitcoin::Crypto::Key::Public

cpanm Bitcoin::Crypto

perl -MCPAN -e shell
install Bitcoin::Crypto