Codec.Binary.Bech32

Implementation of the Bech32 address format.

Based on an original implementation by Marko Bencun.

Basic Usage

Encoding

encode :: HumanReadablePart -> DataPart -> Either EncodingError Text

Encode a Bech32 string from a human-readable prefix and data payload.

Example

>>> import Prelude
>>> import Codec.Binary.Bech32
>>> import Data.Text.Encoding

First, prepare a human-readable prefix:

>>> Right prefix = humanReadablePartFromText "example"

Next, prepare a data payload:

>>> messageToEncode = "Lorem ipsum dolor sit amet!"
>>> dataPart = dataPartFromBytes $ encodeUtf8 messageToEncode

Finally, produce a Bech32 string:

>>> encode prefix dataPart
Right "example1f3hhyetdyp5hqum4d5sxgmmvdaezqumfwssxzmt9wsss9un3cx"

Decoding

decode :: Text -> Either DecodingError (HumanReadablePart, DataPart)

Decode a Bech32 string into a human-readable prefix and data payload.

Example

>>> import Prelude
>>> import Codec.Binary.Bech32
>>> import Data.Text.Encoding

First, decode the input:

>>> input = "example1f3hhyetdyp5hqum4d5sxgmmvdaezqumfwssxzmt9wsss9un3cx"
>>> Right (prefix, dataPart) = decode input

Next, examine the decoded human-readable prefix:

>>> humanReadablePartToText prefix
"example"

Finally, examine the decoded data payload:

>>> decodeUtf8 <$> dataPartToBytes dataPart
Just "Lorem ipsum dolor sit amet!"

Error Handling

Encoding

data EncodingError

Represents the set of error conditions that may occur while encoding a Bech32 string.

Constructors

EncodedStringTooLong

The resultant encoded string would be longer than encodedStringMaxLength.

Instances

Show EncodingError

Defined in Codec.Binary.Bech32.Internal

Methods

showsPrec :: Int -> EncodingError -> ShowS

show :: EncodingError -> String

showList :: [EncodingError] -> ShowS

Eq EncodingError

Defined in Codec.Binary.Bech32.Internal

Methods

(==) :: EncodingError -> EncodingError -> Bool

(/=) :: EncodingError -> EncodingError -> Bool

Decoding

data DecodingError

Represents the set of errors that may occur while decoding a Bech32 string with the decode function.

Constructors

StringToDecodeTooLong

The string to decode is longer than encodedStringMaxLength.

StringToDecodeTooShort

The string to decode is shorter than encodedStringMinLength.

StringToDecodeHasMixedCase

The string to decode contains both upper case and lower case characters.

StringToDecodeMissingSeparatorChar

The string to decode is missing the separator character, specified by separatorChar.

StringToDecodeContainsInvalidChars [CharPosition]

The string to decode contains one or more invalid characters.

In cases where it is possible to determine the exact locations of erroneous characters, this list will encode those locations. Clients can use this information to provide user feedback.

In cases where it isn't possible to reliably determine the locations of erroneous characters, this list will be empty.

Instances

Show DecodingError

Defined in Codec.Binary.Bech32.Internal

Methods

showsPrec :: Int -> DecodingError -> ShowS

show :: DecodingError -> String

showList :: [DecodingError] -> ShowS

Eq DecodingError

Defined in Codec.Binary.Bech32.Internal

Methods

(==) :: DecodingError -> DecodingError -> Bool

(/=) :: DecodingError -> DecodingError -> Bool

Core Types

Data Payloads

data DataPart

Represents the data part of a Bech32 string, as defined here: https://git.io/fj8FS

Instances

Monoid DataPart

Defined in Codec.Binary.Bech32.Internal

Methods

mempty :: DataPart

mappend :: DataPart -> DataPart -> DataPart

mconcat :: [DataPart] -> DataPart

Semigroup DataPart

Defined in Codec.Binary.Bech32.Internal

Methods

(<>) :: DataPart -> DataPart -> DataPart

sconcat :: NonEmpty DataPart -> DataPart

stimes :: Integral b => b -> DataPart -> DataPart

Show DataPart

Defined in Codec.Binary.Bech32.Internal

Methods

showsPrec :: Int -> DataPart -> ShowS

show :: DataPart -> String

showList :: [DataPart] -> ShowS

Eq DataPart

Defined in Codec.Binary.Bech32.Internal

Methods

(==) :: DataPart -> DataPart -> Bool

(/=) :: DataPart -> DataPart -> Bool

Conversion to and from Words

dataPartFromWords :: [Word5] -> DataPart

Construct a DataPart directly from a list of words.

This function guarantees to satisfy the following properties:

dataPartFromWords (dataPartToWords d) == d
dataPartToWords (dataPartFromWords w) == w

dataPartToWords :: DataPart -> [Word5]

Unpack a DataPart into a list of its constituent words.

This function guarantees to satisfy the following properties:

dataPartFromWords (dataPartToWords d) == d
dataPartToWords (dataPartFromWords w) == w

Conversion to and from Bytes

dataPartFromBytes :: ByteString -> DataPart

Constructs a DataPart from a ByteString.

This function encodes a ByteString in such a way that guarantees it can be successfully decoded with the dataPartToBytes function:

dataPartToBytes (dataPartFromBytes b) == Just b

dataPartToBytes :: DataPart -> Maybe ByteString

Attempts to extract a ByteString from a DataPart.

This function guarantees to satisfy the following property:

dataPartToBytes (dataPartFromBytes b) == Just b

Conversion to and from Text

dataPartFromText :: Text -> Maybe DataPart

Constructs a DataPart from textual input.

All characters in the input must be a member of dataCharList, the set of characters permitted to appear within the data part of a Bech32 string.

Returns Nothing if any character in the input is not a member of dataCharList.

This function guarantees to satisfy the following property:

dataPartFromText (dataPartToText d) == Just d

dataPartToText :: DataPart -> Text

Converts a DataPart to Text, using the Bech32 character set to render the data.

This function guarantees to satisfy the following property:

dataPartFromText (dataPartToText d) == Just d

Human-Readable Prefixes

data HumanReadablePart

Represents the human-readable part of a Bech32 string, as defined here: https://git.io/fj8FS

Instances

Monoid HumanReadablePart

Defined in Codec.Binary.Bech32.Internal

Methods

mempty :: HumanReadablePart

mappend :: HumanReadablePart -> HumanReadablePart -> HumanReadablePart

mconcat :: [HumanReadablePart] -> HumanReadablePart

Semigroup HumanReadablePart

Defined in Codec.Binary.Bech32.Internal

Methods

(<>) :: HumanReadablePart -> HumanReadablePart -> HumanReadablePart

sconcat :: NonEmpty HumanReadablePart -> HumanReadablePart

stimes :: Integral b => b -> HumanReadablePart -> HumanReadablePart

Show HumanReadablePart

Defined in Codec.Binary.Bech32.Internal

Methods

showsPrec :: Int -> HumanReadablePart -> ShowS

show :: HumanReadablePart -> String

showList :: [HumanReadablePart] -> ShowS

Eq HumanReadablePart

Defined in Codec.Binary.Bech32.Internal

Methods

(==) :: HumanReadablePart -> HumanReadablePart -> Bool

(/=) :: HumanReadablePart -> HumanReadablePart -> Bool

Conversion to and from Text

humanReadablePartFromText :: Text -> Either HumanReadablePartError HumanReadablePart

Parses the human-readable part of a Bech32 string, as defined here: https://git.io/fj8FS

humanReadablePartToText :: HumanReadablePart -> Text

Get the raw text of the human-readable part of a Bech32 string.

Error Handling

data HumanReadablePartError

Represents the set of error conditions that may occur while parsing the human-readable part of a Bech32 string.

Constructors

HumanReadablePartTooShort

The human-readable part is shorter than humanReadablePartMinLength.

HumanReadablePartTooLong

The human-readable part is longer than humanReadablePartMaxLength.

HumanReadablePartContainsInvalidChars [CharPosition]

The human-readable part contains one or more characters whose values are less than humanReadableCharMinBound or greater than humanReadableCharMaxBound.

Instances

Exception HumanReadablePartError

Defined in Codec.Binary.Bech32.Internal

Methods

toException :: HumanReadablePartError -> SomeException

fromException :: SomeException -> Maybe HumanReadablePartError

displayException :: HumanReadablePartError -> String

Show HumanReadablePartError

Defined in Codec.Binary.Bech32.Internal

Methods

showsPrec :: Int -> HumanReadablePartError -> ShowS

show :: HumanReadablePartError -> String

showList :: [HumanReadablePartError] -> ShowS

Eq HumanReadablePartError

Defined in Codec.Binary.Bech32.Internal

Methods

(==) :: HumanReadablePartError -> HumanReadablePartError -> Bool

(/=) :: HumanReadablePartError -> HumanReadablePartError -> Bool

Additional Types

Character Positions

newtype CharPosition

The zero-based position of a character in a string, counting from the left.

Values of this type are typically used to reflect the positions of errors.

See DecodingError.

Constructors

CharPosition Int

Instances

Show CharPosition

Defined in Codec.Binary.Bech32.Internal

Methods

showsPrec :: Int -> CharPosition -> ShowS

show :: CharPosition -> String

showList :: [CharPosition] -> ShowS

Eq CharPosition

Defined in Codec.Binary.Bech32.Internal

Methods

(==) :: CharPosition -> CharPosition -> Bool

(/=) :: CharPosition -> CharPosition -> Bool

Ord CharPosition

Defined in Codec.Binary.Bech32.Internal

Methods

compare :: CharPosition -> CharPosition -> Ordering

(<) :: CharPosition -> CharPosition -> Bool

(<=) :: CharPosition -> CharPosition -> Bool

(>) :: CharPosition -> CharPosition -> Bool

(>=) :: CharPosition -> CharPosition -> Bool

max :: CharPosition -> CharPosition -> CharPosition

min :: CharPosition -> CharPosition -> CharPosition

Data Words

data Word5

Represents a data word of 5 bits in width.

Each character in the data portion of a Bech32 string encodes exactly 5 bits of data.

Construction and Deconstruction

Use the toEnum and fromEnum functions to construct and deconstruct Word5 values.

Packing Words into Data Payloads

Use the dataPartFromWords and dataPartToWords functions to pack and unpack Word5 values into and out of data payloads.

Instances

Bounded Word5

Defined in Codec.Binary.Bech32.Internal

Methods

minBound :: Word5

maxBound :: Word5

Enum Word5

Defined in Codec.Binary.Bech32.Internal

Methods

succ :: Word5 -> Word5

pred :: Word5 -> Word5

toEnum :: Int -> Word5

fromEnum :: Word5 -> Int

enumFrom :: Word5 -> [Word5]

enumFromThen :: Word5 -> Word5 -> [Word5]

enumFromTo :: Word5 -> Word5 -> [Word5]

enumFromThenTo :: Word5 -> Word5 -> Word5 -> [Word5]

Ix Word5

Defined in Codec.Binary.Bech32.Internal

Methods

range :: (Word5, Word5) -> [Word5]

index :: (Word5, Word5) -> Word5 -> Int

unsafeIndex :: (Word5, Word5) -> Word5 -> Int

inRange :: (Word5, Word5) -> Word5 -> Bool

rangeSize :: (Word5, Word5) -> Int

unsafeRangeSize :: (Word5, Word5) -> Int

Show Word5

Defined in Codec.Binary.Bech32.Internal

Methods

showsPrec :: Int -> Word5 -> ShowS

show :: Word5 -> String

showList :: [Word5] -> ShowS

Eq Word5

Defined in Codec.Binary.Bech32.Internal

Methods

(==) :: Word5 -> Word5 -> Bool

(/=) :: Word5 -> Word5 -> Bool

Ord Word5

Defined in Codec.Binary.Bech32.Internal

Methods

compare :: Word5 -> Word5 -> Ordering

(<) :: Word5 -> Word5 -> Bool

(<=) :: Word5 -> Word5 -> Bool

(>) :: Word5 -> Word5 -> Bool

(>=) :: Word5 -> Word5 -> Bool

max :: Word5 -> Word5 -> Word5

min :: Word5 -> Word5 -> Word5

Advanced Usage

Encoding and Decoding with Greater Leniency

encodeLenient :: HumanReadablePart -> DataPart -> Text

Like encode but allows output to be longer than 90 characters.

This isn't ideal, as Bech32 error detection becomes worse as strings get longer, but it may be useful in certain circumstances.

From BIP-0173:

"Even though the chosen code performs reasonably well up to 1023 characters, other designs are preferable for lengths above 89 characters (excluding the separator)."

decodeLenient :: Text -> Either DecodingError (HumanReadablePart, DataPart)

Like decode but does not enforce a maximum length.

See also encodeLenient for details.

Fundamental Constants

Data Payloads

dataCharList :: String

A list of all characters that are permitted to appear within the data part of a Bech32 string.

See here for more details: https://git.io/fj8FS

Human-Readable Prefixes

humanReadablePartMinLength :: Int

The shortest length permitted for the human-readable part of a Bech32 string.

humanReadablePartMaxLength :: Int

The longest length permitted for the human-readable part of a Bech32 string.

humanReadableCharMinBound :: Char

The lower bound of the set of characters permitted to appear within the human-readable part of a Bech32 string.

humanReadableCharMaxBound :: Char

The upper bound of the set of characters permitted to appear within the human-readable part of a Bech32 string.

Encoded Strings

encodedStringMaxLength :: Int

The maximum length of an encoded string, in bytes.

This length includes the human-readable part, the separator character, the encoded data portion, and the checksum.

encodedStringMinLength :: Int

The minimum length of an encoded string, in bytes.

This length includes the human-readable part, the separator character, the encoded data portion, and the checksum.

separatorChar :: Char

The separator character.

This character appears immediately after the human-readable part and before the data part in an encoded string.