Struct CheckedHrpstring

pub struct CheckedHrpstring<'s> { /* private fields */ }

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

This type does not treat the first byte of the data part in any special way i.e., as the witness version byte. If you are parsing Bitcoin segwit addresses consider using SegwitHrpstring.

We first describe the general checksummed base32 format called Bech32 and then define Segregated Witness addresses using it.

This type abstracts over the general checksummed base32 format called Bech32.

Examples

use bech32::{Bech32m, primitives::decode::CheckedHrpstring};

// Parse a general checksummed bech32 encoded string.
let s = "abcd14g08d6qejxtdg4y5r3zarvary0c5xw7knqc5r8";
let checked = CheckedHrpstring::new::<Bech32m>(s)
      .expect("valid bech32 string with a valid checksum according to the bech32m algorithm");

// Do something with the encoded data.
let _ = checked.byte_iter();

Implementations

impl<'s> CheckedHrpstring<'s>

pub fn new<Ck>( s: &'s str, ) -> Result<CheckedHrpstring<'s>, CheckedHrpstringError>

where Ck: Checksum,

Parses and validates an HRP string, without treating the first data character specially.

If you are validating the checksum multiple times consider using UncheckedHrpstring.

This is equivalent to UncheckedHrpstring::new().validate_and_remove_checksum::<CK>().

pub fn hrp(&self) -> Hrp

Returns the human-readable part.

pub fn data_part_ascii_no_checksum(&self) -> &'s [u8]

Returns a partial slice of the data part, as ASCII bytes, everything after the separator ‘1’ before the checksum.

The byte values are guaranteed to be valid bech32 characters.

Examples

use bech32::{Bech32, primitives::decode::CheckedHrpstring};

let addr = "bc1qar0srrr7xfkvy5l643lydnw9re59gtzzwf5mdq";
let ascii = "qar0srrr7xfkvy5l643lydnw9re59gtzz";

let checked = CheckedHrpstring::new::<Bech32>(&addr).unwrap();
assert!(checked.data_part_ascii_no_checksum().iter().eq(ascii.as_bytes().iter()))

pub fn remove_witness_version(&mut self) -> Option<Fe32>

Attempts to remove the first byte of the data part, treating it as a witness version.

If Self::witness_version succeeds this function removes the first character (witness version byte) from the internal ASCII data part buffer. Future calls to Self::data_part_ascii_no_checksum will no longer include it.

Examples

use bech32::{primitives::decode::CheckedHrpstring, Bech32, Fe32};

let addr = "bc1qar0srrr7xfkvy5l643lydnw9re59gtzzwf5mdq";
let ascii = "ar0srrr7xfkvy5l643lydnw9re59gtzz";

let mut checked = CheckedHrpstring::new::<Bech32>(&addr).unwrap();
let witness_version = checked.remove_witness_version().unwrap();
assert_eq!(witness_version, Fe32::Q);
assert!(checked.data_part_ascii_no_checksum().iter().eq(ascii.as_bytes().iter()))

pub fn witness_version(&self) -> Option<Fe32>

Returns the segwit witness version if there is one.

Attempts to convert the first character of the data part to a witness version. If this succeeds, and it is a valid version (0..16 inclusive) we return it, otherwise None.

Future calls to Self::data_part_ascii_no_checksum will still include the witness version, use Self::remove_witness_version to remove it.

This function makes no guarantees on the validity of the checksum.

Examples

use bech32::{primitives::decode::CheckedHrpstring, Bech32, Fe32};

let addr = "bc1qar0srrr7xfkvy5l643lydnw9re59gtzzwf5mdq";

let checked = CheckedHrpstring::new::<Bech32>(&addr).unwrap();
assert_eq!(checked.witness_version(), Some(Fe32::Q));

pub fn fe32_iter<I>(&self) -> AsciiToFe32Iter<'_>

where I: Iterator<Item = u8>,

Returns an iterator that yields the data part of the parsed bech32 encoded string as Fe32s.

Converts the ASCII bytes representing field elements to the respective field elements.

pub fn byte_iter(&self) -> ByteIter<'_>

Returns an iterator that yields the data part of the parsed bech32 encoded string.

Converts the ASCII bytes representing field elements to the respective field elements, then converts the stream of field elements to a stream of bytes.

pub fn validate_segwit( self, ) -> Result<SegwitHrpstring<'s>, SegwitHrpstringError>

Converts this type to a SegwitHrpstring after validating the witness and HRP.

pub fn validate_segwit_padding(&self) -> Result<(), PaddingError>

Validates the segwit padding rules.

Must be called after the witness version byte is removed from the data part.

From BIP-173:

Re-arrange those bits into groups of 8 bits. Any incomplete group at the end MUST be 4 bits or less, MUST be all zeroes, and is discarded.

pub fn validate_witness_program_length( &self, witness_version: Fe32, ) -> Result<(), WitnessLengthError>

Validates the segwit witness length rules.

Must be called after the witness version byte is removed from the data part.

Trait Implementations

impl<'s> Debug for CheckedHrpstring<'s>

fn fmt(&self, f: &mut Formatter<'_>) -> Result<(), Error>

Formats the value using the given formatter.