Copyright	© 2017 Marko Bencun 2019-2020 IOHK
License	Apache-2.0
Safe Haskell	None
Language	Haskell2010

Codec.Binary.Bech32.Internal

Contents

Encoding & Decoding
Data Part
Human-Readable Part
Bit Manipulation
Character Manipulation

Description

Implementation of the Bech32 address format.

From an original implementation by Marko Bencun:

sipa/bech32

Synopsis

encode :: HumanReadablePart -> DataPart -> Either EncodingError Text
encodeLenient :: HumanReadablePart -> DataPart -> Text
data EncodingError = EncodedStringTooLong
decode :: Text -> Either DecodingError ( HumanReadablePart , DataPart )
decodeLenient :: Text -> Either DecodingError ( HumanReadablePart , DataPart )
data DecodingError
- = StringToDecodeTooLong
- | StringToDecodeTooShort
- | StringToDecodeHasMixedCase
- | StringToDecodeMissingSeparatorChar
- | StringToDecodeContainsInvalidChars [ CharPosition ]
checksumLength :: Int
encodedStringMaxLength :: Int
encodedStringMinLength :: Int
separatorChar :: Char
separatorLength :: Int
data DataPart
dataPartIsValid :: DataPart -> Bool
dataPartFromBytes :: ByteString -> DataPart
dataPartFromText :: Text -> Maybe DataPart
dataPartFromWords :: [ Word5 ] -> DataPart
dataPartToBytes :: DataPart -> Maybe ByteString
dataPartToText :: DataPart -> Text
dataPartToWords :: DataPart -> [ Word5 ]
dataCharToWord :: Char -> Maybe Word5
dataCharFromWord :: Word5 -> Char
dataCharList :: String
data HumanReadablePart
data HumanReadablePartError
- = HumanReadablePartTooShort
- | HumanReadablePartTooLong
- | HumanReadablePartContainsInvalidChars [ CharPosition ]
humanReadablePartFromText :: Text -> Either HumanReadablePartError HumanReadablePart
humanReadablePartToText :: HumanReadablePart -> Text
humanReadablePartToWords :: HumanReadablePart -> [ Word5 ]
humanReadablePartMinLength :: Int
humanReadablePartMaxLength :: Int
humanReadableCharIsValid :: Char -> Bool
humanReadableCharMinBound :: Char
humanReadableCharMaxBound :: Char
convertBits :: Functor f => [ Word ] -> Int -> Int -> Pad f -> f [ Word ]
data Word5
word5 :: Integral a => a -> Word5
getWord5 :: Word5 -> Word8
toBase256 :: [ Word5 ] -> Maybe [ Word8 ]
toBase32 :: [ Word8 ] -> [ Word5 ]
noPadding :: Pad Maybe
yesPadding :: Pad Identity
newtype CharPosition = CharPosition Int

Encoding & Decoding

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

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"

encodeLenient :: HumanReadablePart -> DataPart -> Text Source #

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)."

data EncodingError Source #

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

Instances details

Eq EncodingError Source #
Instance details Defined in Codec.Binary.Bech32.Internal Methods (==) :: EncodingError -> EncodingError -> Bool Source # (/=) :: EncodingError -> EncodingError -> Bool Source #
Show EncodingError Source #
Instance details Defined in Codec.Binary.Bech32.Internal Methods showsPrec :: Int -> EncodingError -> ShowS Source # show :: EncodingError -> String Source # showList :: [ EncodingError ] -> ShowS Source #

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

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!"

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

Like decode but does not enforce a maximum length.

Instances

Instances details

Eq DecodingError Source #
Instance details Defined in Codec.Binary.Bech32.Internal Methods (==) :: DecodingError -> DecodingError -> Bool Source # (/=) :: DecodingError -> DecodingError -> Bool Source #
Show DecodingError Source #
Instance details Defined in Codec.Binary.Bech32.Internal Methods showsPrec :: Int -> DecodingError -> ShowS Source # show :: DecodingError -> String Source # showList :: [ DecodingError ] -> ShowS Source #

checksumLength :: Int Source #

The length of the checksum portion of an encoded string, in bytes.

encodedStringMaxLength :: Int Source #

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 Source #

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 Source #

The separator character.

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

separatorLength :: Int Source #

The length of the separator portion of an encoded string, in bytes.

Data Part

data DataPart Source #

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

Instances

Instances details

Eq DataPart Source #
Instance details Defined in Codec.Binary.Bech32.Internal Methods (==) :: DataPart -> DataPart -> Bool Source # (/=) :: DataPart -> DataPart -> Bool Source #
Show DataPart Source #
Instance details Defined in Codec.Binary.Bech32.Internal Methods showsPrec :: Int -> DataPart -> ShowS Source # show :: DataPart -> String Source # showList :: [ DataPart ] -> ShowS Source #
Semigroup DataPart Source #
Instance details Defined in Codec.Binary.Bech32.Internal Methods (<>) :: DataPart -> DataPart -> DataPart Source # sconcat :: NonEmpty DataPart -> DataPart Source # stimes :: Integral b => b -> DataPart -> DataPart Source #
Monoid DataPart Source #
Instance details Defined in Codec.Binary.Bech32.Internal Methods mempty :: DataPart Source # mappend :: DataPart -> DataPart -> DataPart Source # mconcat :: [ DataPart ] -> DataPart Source #

dataPartIsValid :: DataPart -> Bool Source #

Returns true iff. the specified DataPart is valid.

dataPartFromBytes :: ByteString -> DataPart Source #

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

dataPartFromText :: Text -> Maybe DataPart Source #

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

dataPartFromWords :: [ Word5 ] -> DataPart Source #

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

dataPartToBytes :: DataPart -> Maybe ByteString Source #

Attempts to extract a ByteString from a DataPart .

This function guarantees to satisfy the following property:

dataPartToBytes (dataPartFromBytes b) == Just b

dataPartToText :: DataPart -> Text Source #

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

dataPartToWords :: DataPart -> [ Word5 ] Source #

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

dataCharToWord :: Char -> Maybe Word5 Source #

If the specified character is permitted to appear within the data part of a Bech32 string, this function returns that character's corresponding Word5 value. If the specified character is not permitted, or if the specified character is upper-case, returns Nothing .

dataCharFromWord :: Word5 -> Char Source #

Maps the specified Word5 onto a character that is permitted to appear within the data part of a Bech32 string.

dataCharList :: String Source #

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 Part

data HumanReadablePart Source #

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

Instances

Instances details

Eq HumanReadablePart Source #
Instance details Defined in Codec.Binary.Bech32.Internal Methods (==) :: HumanReadablePart -> HumanReadablePart -> Bool Source # (/=) :: HumanReadablePart -> HumanReadablePart -> Bool Source #
Show HumanReadablePart Source #
Instance details Defined in Codec.Binary.Bech32.Internal Methods showsPrec :: Int -> HumanReadablePart -> ShowS Source # show :: HumanReadablePart -> String Source # showList :: [ HumanReadablePart ] -> ShowS Source #
Semigroup HumanReadablePart Source #
Instance details Defined in Codec.Binary.Bech32.Internal Methods (<>) :: HumanReadablePart -> HumanReadablePart -> HumanReadablePart Source # sconcat :: NonEmpty HumanReadablePart -> HumanReadablePart Source # stimes :: Integral b => b -> HumanReadablePart -> HumanReadablePart Source #
Monoid HumanReadablePart Source #
Instance details Defined in Codec.Binary.Bech32.Internal Methods mempty :: HumanReadablePart Source # mappend :: HumanReadablePart -> HumanReadablePart -> HumanReadablePart Source # mconcat :: [ HumanReadablePart ] -> HumanReadablePart Source #

data HumanReadablePartError Source #

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

Instances details

Eq HumanReadablePartError Source #
Instance details Defined in Codec.Binary.Bech32.Internal Methods (==) :: HumanReadablePartError -> HumanReadablePartError -> Bool Source # (/=) :: HumanReadablePartError -> HumanReadablePartError -> Bool Source #
Show HumanReadablePartError Source #
Instance details Defined in Codec.Binary.Bech32.Internal Methods showsPrec :: Int -> HumanReadablePartError -> ShowS Source # show :: HumanReadablePartError -> String Source # showList :: [ HumanReadablePartError ] -> ShowS Source #
Exception HumanReadablePartError Source #
Instance details Defined in Codec.Binary.Bech32.Internal Methods toException :: HumanReadablePartError -> SomeException Source # fromException :: SomeException -> Maybe HumanReadablePartError Source # displayException :: HumanReadablePartError -> String Source #

humanReadablePartFromText :: Text -> Either HumanReadablePartError HumanReadablePart Source #

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

humanReadablePartToText :: HumanReadablePart -> Text Source #

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

humanReadablePartToWords :: HumanReadablePart -> [ Word5 ] Source #

Convert the specified human-readable part to a list of words.

humanReadablePartMinLength :: Int Source #

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

humanReadablePartMaxLength :: Int Source #

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

humanReadableCharIsValid :: Char -> Bool Source #

Returns true iff. the specified character is permitted to appear within the human-readable part of a Bech32 string.

humanReadableCharMinBound :: Char Source #

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

humanReadableCharMaxBound :: Char Source #

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

Bit Manipulation

convertBits :: Functor f => [ Word ] -> Int -> Int -> Pad f -> f [ Word ] Source #

Big-endian conversion of a word string from base '2^frombits' to base '2^tobits'. The frombits and twobits parameters must be positive, while '2^frombits' and '2^tobits' must be smaller than the size of Word . Every value in dat must be strictly smaller than '2^frombits'.

data Word5 Source #

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

Instances details

Bounded Word5 Source #
Instance details Defined in Codec.Binary.Bech32.Internal Methods minBound :: Word5 Source # maxBound :: Word5 Source #
Enum Word5 Source #
Instance details Defined in Codec.Binary.Bech32.Internal Methods succ :: Word5 -> Word5 Source # pred :: Word5 -> Word5 Source # toEnum :: Int -> Word5 Source # fromEnum :: Word5 -> Int Source # enumFrom :: Word5 -> [ Word5 ] Source # enumFromThen :: Word5 -> Word5 -> [ Word5 ] Source # enumFromTo :: Word5 -> Word5 -> [ Word5 ] Source # enumFromThenTo :: Word5 -> Word5 -> Word5 -> [ Word5 ] Source #
Eq Word5 Source #
Instance details Defined in Codec.Binary.Bech32.Internal Methods (==) :: Word5 -> Word5 -> Bool Source # (/=) :: Word5 -> Word5 -> Bool Source #
Ord Word5 Source #
Instance details Defined in Codec.Binary.Bech32.Internal Methods compare :: Word5 -> Word5 -> Ordering Source # (<) :: Word5 -> Word5 -> Bool Source # (<=) :: Word5 -> Word5 -> Bool Source # (>) :: Word5 -> Word5 -> Bool Source # (>=) :: Word5 -> Word5 -> Bool Source # max :: Word5 -> Word5 -> Word5 Source # min :: Word5 -> Word5 -> Word5 Source #
Show Word5 Source #
Instance details Defined in Codec.Binary.Bech32.Internal Methods showsPrec :: Int -> Word5 -> ShowS Source # show :: Word5 -> String Source # showList :: [ Word5 ] -> ShowS Source #
Ix Word5 Source #
Instance details Defined in Codec.Binary.Bech32.Internal Methods range :: ( Word5 , Word5 ) -> [ Word5 ] Source # index :: ( Word5 , Word5 ) -> Word5 -> Int Source # unsafeIndex :: ( Word5 , Word5 ) -> Word5 -> Int Source # inRange :: ( Word5 , Word5 ) -> Word5 -> Bool Source # rangeSize :: ( Word5 , Word5 ) -> Int Source # unsafeRangeSize :: ( Word5 , Word5 ) -> Int Source #

word5 :: Integral a => a -> Word5 Source #

getWord5 :: Word5 -> Word8 Source #

toBase256 :: [ Word5 ] -> Maybe [ Word8 ] Source #

toBase32 :: [ Word8 ] -> [ Word5 ] Source #

noPadding :: Pad Maybe Source #

yesPadding :: Pad Identity Source #

Character Manipulation

newtype CharPosition Source #

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

Instances details

Eq CharPosition Source #
Instance details Defined in Codec.Binary.Bech32.Internal Methods (==) :: CharPosition -> CharPosition -> Bool Source # (/=) :: CharPosition -> CharPosition -> Bool Source #
Ord CharPosition Source #
Instance details Defined in Codec.Binary.Bech32.Internal Methods compare :: CharPosition -> CharPosition -> Ordering Source # (<) :: CharPosition -> CharPosition -> Bool Source # (<=) :: CharPosition -> CharPosition -> Bool Source # (>) :: CharPosition -> CharPosition -> Bool Source # (>=) :: CharPosition -> CharPosition -> Bool Source # max :: CharPosition -> CharPosition -> CharPosition Source # min :: CharPosition -> CharPosition -> CharPosition Source #
Show CharPosition Source #
Instance details Defined in Codec.Binary.Bech32.Internal Methods showsPrec :: Int -> CharPosition -> ShowS Source # show :: CharPosition -> String Source # showList :: [ CharPosition ] -> ShowS Source #

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.