Module decode

Decoding of bech32 encoded strings as specified by BIP-173 and BIP-350.

You should only need to use this module directly if you want control over exactly what is checked and when it is checked (correct bech32 characters, valid checksum, valid checksum for specific checksum algorithm, etc). If you are parsing/validating modern (post BIP-350) bitcoin segwit addresses consider using the crate::segwit API.

If you do find yourself using this module directly then consider using the most general type that serves your purposes, each type can be created by parsing an address string to new. You likely do not want to arbitrarily transition from one type to the next even though possible. And be prepared to spend some time with the bips - you have been warned :)

Details

A Bech32 string is at most 90 characters long and consists of:

• The human-readable part, which is intended to convey the type of data, or anything else that is relevant to the reader. This part MUST contain 1 to 83 US-ASCII characters.
• The separator, which is always “1”.
• The data part, which is at least 6 characters long and only consists of alphanumeric characters excluding “1”, “b”, “i”, and “o”.

The types in this module heavily lean on the wording in BIP-173: We first describe the general checksummed base32 format called Bech32 and then define Segregated Witness addresses using it.

• UncheckedHrpstring: Parses the general checksummed base32 format and provides checksum validation.
• CheckedHrpstring: Provides access to the data encoded by a general checksummed base32 string and segwit checks.
• SegwitHrpstring: Provides access to the data encoded by a segwit address.

Examples

use bech32::{Bech32, Bech32m, Fe32, Hrp};
use bech32::primitives::decode::{CheckedHrpstring, SegwitHrpstring, UncheckedHrpstring};
use bech32::segwit::VERSION_1;

// An arbitrary HRP and a string of valid bech32 characters.
let s = "abcd143hj65vxw49rts6kcw35u6r6tgzguyr03vvveeewjqpn05efzq444444";
assert!(UncheckedHrpstring::new(s).is_ok());
// But it has an invalid checksum.
assert!(CheckedHrpstring::new::<Bech32>(s).is_err());
assert!(CheckedHrpstring::new::<Bech32m>(s).is_err());
assert!(SegwitHrpstring::new(s).is_err());

// An arbitrary HRP, a string of valid bech32 characters, and a valid bech32 checksum.
let s = "abcd14g08d6qejxtdg4y5r3zarvary0c5xw7kxugcx9";
assert!(UncheckedHrpstring::new(s).is_ok());
assert!(CheckedHrpstring::new::<Bech32>(s).is_ok());
// But not a valid segwit address.
assert!(SegwitHrpstring::new(s).is_err());
// And not a valid bech32m checksum.
assert!(CheckedHrpstring::new::<Bech32m>(s).is_err());

// A valid Bitcoin taproot address.
let s = "bc1pdp43hj65vxw49rts6kcw35u6r6tgzguyr03vvveeewjqpn05efzq7un9w0";
assert!(UncheckedHrpstring::new(s).is_ok());
assert!(CheckedHrpstring::new::<Bech32m>(s).is_ok());
assert!(SegwitHrpstring::new(s).is_ok());
// But not a valid segwit v0 checksum.
assert!(CheckedHrpstring::new::<Bech32>(s).is_err());

// Get the HRP, witness version, and encoded data.
let address = "bc1pdp43hj65vxw49rts6kcw35u6r6tgzguyr03vvveeewjqpn05efzq7un9w0";
let segwit = SegwitHrpstring::new(address).expect("valid segwit address");
let _encoded_data = segwit.byte_iter();
assert_eq!(segwit.hrp(), Hrp::parse("bc").unwrap());
assert_eq!(segwit.witness_version(), VERSION_1);

Structs

AsciiToFe32Iter

Iterator adaptor that maps an iterator of valid bech32 character ASCII bytes to an iterator of field elements.

ByteIter

An iterator over a parsed HRP string data as bytes.

CheckedHrpstring

An HRP string that has been parsed and had the checksum validated.

CodeLengthError

Encoding HRP and data into a bech32 string exceeds the checksum code length.

Fe32Iter

An iterator over a parsed HRP string data as field elements.

SegwitCodeLengthError

Encoding HRP, witver, and program into an address exceeds maximum allowed.

SegwitHrpstring

An valid length HRP string that has been parsed, had the checksum validated, had the witness version validated, had the witness data length checked, and the had witness version and checksum removed.

UncheckedHrpstring

An HRP string that has been parsed but not yet had the checksum checked.

Enums

CharError

Character errors in a bech32 encoded string.

CheckedHrpstringError

An error while constructing a CheckedHrpstring type.

ChecksumError

Errors in the checksum of a bech32 encoded string.

PaddingError

Error validating the padding bits on the witness data.

SegwitHrpstringError

An error while constructing a SegwitHrpstring type.

UncheckedHrpstringError

Errors when parsing a bech32 encoded string.