The Perl and Raku Conference 2025: Greenville, South Carolina - June 27-29 Learn more

 / 
Bitcoin-Crypto-3.001
River stage one • 3 direct dependents • 5 total dependents
/ Bitcoin::Crypto::Bech32

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

SEE ALSO

Bitcoin::Crypto::Base58