The Perl Toolchain Summit needs more sponsors. If your company depends on Perl, please support this very important event.

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 Bitcoin::Crypto::Segwit.

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 = translate_5to8(decode_bech32($data));

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

SEE ALSO

Bitcoin::Crypto::Base58

Bitcoin::Crypto::Segwit