Bech32 Class

Definition

Namespace

Bodu.Text.Encoding

Assembly

Bodu.Text.Encoding.dll

Package

Bodu.Text.Encoding 1.0.0

Source

Bech32.Decode.cs

Provides Bech32 (BIP-173) and Bech32m (BIP-350) encoding and decoding - a checksummed base-32 format consisting of a human-readable part (HRP), the 1 separator, a data part of 5-bit groups, and a six-symbol error-detecting checksum.

public static class Bech32

Inheritance

object

Bech32

Inherited Members

object.Equals(object)

object.Equals(object, object)

object.GetHashCode()

object.GetType()

object.MemberwiseClone()

object.ReferenceEquals(object, object)

object.ToString()

Examples

// Encode 5-bit data groups under a human-readable prefix.
byte[] data = { 0x00, 0x01, 0x02 };                 // already 5-bit values
string encoded = Bech32.Encode("abc", data);        // "abc1..." with a Bech32 checksum

// Decode and recover the parts.
Bech32.Decode(encoded, out string hrp, out byte[] groups, out Bech32Encoding scheme);

Remarks

Bech32 is not a plain binary-to-text encoding: every encoded string carries an HRP prefix and a checksum, so the type is modelled on Base58Check rather than the IBinaryEncoding family. The core surface operates on 5-bit data groups (each value 0-31); use ConvertBits(ReadOnlySpan<byte>, int, int, bool) - or the FromBytes / ToBytes convenience members - to translate between 8-bit bytes and 5-bit groups.

Encoded output is always lower case (the canonical form). Decoding accepts an all-lower-case or all-upper-case string and rejects mixed case per BIP-173; the returned HRP is normalized to lower case. The decoder reports which scheme validated the checksum through the Bech32Encoding out-parameter.

Methods

ConvertBits(ReadOnlySpan<byte>, int, int, bool)

Converts a sequence of integers between bit widths, as defined by the BIP-173 reference convertbits routine - the operation that packs 8-bit bytes into 5-bit Bech32 groups and back.

public static byte[]? ConvertBits(ReadOnlySpan<byte> data, int fromBits, int toBits, bool pad)

Parameters

data ReadOnlySpan<byte>

The input values, each fitting within fromBits bits.

fromBits int

The bit width of each input value.

toBits int

The bit width of each output value.

pad bool

When true, the final group is zero-padded; when false, a non-zero residue or an over-wide residue causes failure.

Returns

byte[]

The converted values, or null when an input value exceeds fromBits bits, or when pad is false and the trailing bits are not a clean zero residue.

Exceptions

ArgumentOutOfRangeException

Thrown when fromBits or toBits is not in the range 1 to 8.

Decode(ReadOnlySpan<char>, out string, out byte[], out Bech32Encoding)

Decodes a Bech32 or Bech32m character span into its human-readable part and 5-bit data groups, verifying the checksum.

public static void Decode(ReadOnlySpan<char> source, out string hrp, out byte[] data, out Bech32Encoding encoding)

Parameters

source ReadOnlySpan<char>

The encoded character span.

hrp string

When this method returns, the lower-case human-readable part.

data byte[]

When this method returns, the 5-bit data groups with the checksum stripped.

encoding Bech32Encoding

When this method returns, the scheme whose checksum constant validated the input.

Exceptions

FormatException

Thrown when the input is not a valid Bech32 or Bech32m string.

Decode(string, out string, out byte[], out Bech32Encoding)

Decodes a Bech32 or Bech32m string into its human-readable part and 5-bit data groups, verifying the checksum.

public static void Decode(string source, out string hrp, out byte[] data, out Bech32Encoding encoding)

Parameters

source string

The encoded string.

hrp string

When this method returns, the lower-case human-readable part.

data byte[]

When this method returns, the 5-bit data groups with the checksum stripped.

encoding Bech32Encoding

When this method returns, the scheme whose checksum constant validated the input.

Exceptions

ArgumentNullException

Thrown when source is null.

FormatException

Thrown when the input mixes case, exceeds the 90-character maximum, lacks the 1 separator, has an empty human-readable part, is too short to contain a checksum, contains an out-of-range character, or fails checksum verification.

DecodeToBytes(string, out string, out byte[], out Bech32Encoding)

Decodes a Bech32 or Bech32m string and repacks its 5-bit data groups into 8-bit bytes - the inverse of EncodeFromBytes(string, ReadOnlySpan<byte>, Bech32Encoding).

public static void DecodeToBytes(string source, out string hrp, out byte[] data, out Bech32Encoding encoding)

Parameters

source string

The encoded string.

hrp string

When this method returns, the lower-case human-readable part.

data byte[]

When this method returns, the decoded 8-bit bytes.

encoding Bech32Encoding

When this method returns, the scheme whose checksum constant validated the input.

Exceptions

ArgumentNullException

Thrown when source is null.

FormatException

Thrown when the input is not a valid Bech32 or Bech32m string, or when its 5-bit groups do not repack cleanly into bytes.

Encode(string, ReadOnlySpan<byte>, Bech32Encoding)

Encodes 5-bit data groups under hrp into a Bech32 or Bech32m string with an appended six-symbol checksum.

public static string Encode(string hrp, ReadOnlySpan<byte> data, Bech32Encoding encoding = Bech32Encoding.Bech32)

Parameters

hrp string

The human-readable part. Lower-cased to produce canonical output.

data ReadOnlySpan<byte>

The data groups, each a 5-bit value in the range 0 to 31.

encoding Bech32Encoding

The scheme selecting the checksum constant.

Returns

string

The lower-case encoded string.

Remarks

This method does not impose the BIP-173 90-character maximum, so it can serve longer non-address schemes (for example Lightning BOLT11 invoices). The decoder enforces the 90-character limit by default.

Exceptions

ArgumentNullException

Thrown when hrp is null.

ArgumentException

Thrown when hrp is empty or contains a character outside the US-ASCII range 33 to 126, or when any element of data exceeds 31.

ArgumentOutOfRangeException

Thrown when encoding is undefined.

EncodeFromBytes(string, ReadOnlySpan<byte>, Bech32Encoding)

Encodes 8-bit data bytes under hrp by first repacking them into 5-bit groups (with zero padding) and then encoding.

public static string EncodeFromBytes(string hrp, ReadOnlySpan<byte> data, Bech32Encoding encoding = Bech32Encoding.Bech32)

Parameters

hrp string

The human-readable part. Lower-cased to produce canonical output.

data ReadOnlySpan<byte>

The raw bytes to encode.

encoding Bech32Encoding

The scheme selecting the checksum constant.

Returns

string

The lower-case encoded string.

Exceptions

ArgumentNullException

Thrown when hrp is null.

ArgumentException

Thrown when hrp is empty or contains a character outside the US-ASCII range 33 to 126.

ArgumentOutOfRangeException

Thrown when encoding is undefined.

GetEncodedLength(int, int)

Returns the overall encoded length for a Bech32 string with the supplied part lengths.

public static int GetEncodedLength(int hrpLength, int dataLength)

Parameters

hrpLength int

The number of characters in the human-readable part.

dataLength int

The number of 5-bit data groups, excluding the checksum.

Returns

int

The total character count: hrpLength + 1 separator + dataLength + 6 checksum symbols.

Exceptions

ArgumentOutOfRangeException

Thrown when hrpLength or dataLength is negative.

IsValid(ReadOnlySpan<char>)

Indicates whether source is a structurally valid Bech32 or Bech32m string with a verifying checksum.

public static bool IsValid(ReadOnlySpan<char> source)

Parameters

source ReadOnlySpan<char>

The candidate string.

Returns

bool

true when source decodes without error; otherwise false.

TryDecode(ReadOnlySpan<char>, out string?, out byte[]?, out Bech32Encoding)

Attempts to decode a Bech32 or Bech32m character span without throwing.

public static bool TryDecode(ReadOnlySpan<char> source, out string? hrp, out byte[]? data, out Bech32Encoding encoding)

Parameters

source ReadOnlySpan<char>

The encoded character span.

hrp string

When this method returns true, the lower-case human-readable part.

data byte[]

When this method returns true, the 5-bit data groups with the checksum stripped.

encoding Bech32Encoding

When this method returns true, the scheme whose checksum constant validated the input.

Returns

bool

true when the input is a valid Bech32 or Bech32m string; otherwise false.

TryDecodeToBytes(ReadOnlySpan<char>, out string?, out byte[]?, out Bech32Encoding)

Attempts to decode a Bech32 or Bech32m character span and repack its 5-bit data groups into 8-bit bytes without throwing.

public static bool TryDecodeToBytes(ReadOnlySpan<char> source, out string? hrp, out byte[]? data, out Bech32Encoding encoding)

Parameters

source ReadOnlySpan<char>

The encoded character span.

hrp string

When this method returns true, the lower-case human-readable part.

data byte[]

When this method returns true, the decoded 8-bit bytes.

encoding Bech32Encoding

When this method returns true, the scheme whose checksum constant validated the input.

Returns

bool

true when the input is valid and its groups repack cleanly into bytes; otherwise false.

TryEncode(string, ReadOnlySpan<byte>, Bech32Encoding, out string?)

Attempts to encode 5-bit data groups under hrp without throwing.

public static bool TryEncode(string hrp, ReadOnlySpan<byte> data, Bech32Encoding encoding, out string? result)

Parameters

hrp string

The human-readable part.

data ReadOnlySpan<byte>

The data groups, each a 5-bit value in the range 0 to 31.

encoding Bech32Encoding

The scheme selecting the checksum constant.

result string

When this method returns true, the encoded string; otherwise null.

Returns

bool

true when the parts are valid and encoding succeeds; otherwise false.

Exceptions

ArgumentOutOfRangeException

Thrown when encoding is undefined.

Applies to

Product	Versions
.NET	8, 10