Safe Haskell	None
Language	Haskell2010

Cardano.Mnemonic

Contents

Introduction
SomeMnemonic
Mnemonic
Entropy
Troubleshooting
Orphan instances

Synopsis

data SomeMnemonic where
- SomeMnemonic :: forall mw. KnownNat mw => Mnemonic mw -> SomeMnemonic
class MkSomeMnemonic (sz :: [ Nat ]) where
- mkSomeMnemonic :: [ Text ] -> Either ( MkSomeMnemonicError sz) SomeMnemonic
newtype MkSomeMnemonicError (sz :: [ Nat ]) = MkSomeMnemonicError {
- getMkSomeMnemonicError :: String
}
someMnemonicToBytes :: SomeMnemonic -> ScrubbedBytes
class NatVals (ns :: [ Nat ]) where
- natVals :: Proxy ns -> [ Integer ]
mkMnemonic :: forall (mw :: Nat ) (ent :: Nat ) csz. ( ConsistentEntropy ent mw csz, EntropySize mw ~ ent) => [ Text ] -> Either ( MkMnemonicError csz) ( Mnemonic mw)
data MkMnemonicError csz
- = ErrMnemonicWords MnemonicWordsError
- | ErrEntropy ( EntropyError csz)
- | ErrDictionary DictionaryError
mnemonicToText :: Mnemonic mw -> [ Text ]
mnemonicToEntropy :: Mnemonic mw -> Entropy ( EntropySize mw)
data Entropy (n :: Nat )
genEntropy :: forall (ent :: Nat ) csz. ( ValidEntropySize ent, ValidChecksumSize ent csz) => IO ( Entropy ent)
mkEntropy :: forall (ent :: Nat ) csz. ( ValidEntropySize ent, ValidChecksumSize ent csz) => ScrubbedBytes -> Either ( EntropyError csz) ( Entropy ent)
entropyToBytes :: Entropy n -> ScrubbedBytes
entropyToMnemonic :: forall mw ent csz. ( ValidMnemonicSentence mw, ValidEntropySize ent, ValidChecksumSize ent csz, ent ~ EntropySize mw, mw ~ MnemonicWords ent) => Entropy ent -> Mnemonic mw
type ValidEntropySize (n :: Nat ) = ( KnownNat n, NatWithinBound Int n, Elem n '[96, 128, 160, 192, 224, 256])
type ValidMnemonicSentence (mw :: Nat ) = ( KnownNat mw, NatWithinBound Int mw, Elem mw '[9, 12, 15, 18, 21, 24])
type ConsistentEntropy (ent :: Nat ) (mw :: Nat ) (csz :: Nat ) = ( ValidEntropySize ent, ValidChecksumSize ent csz, ValidMnemonicSentence mw, MnemonicWords ent ~ mw)
type family CheckSumBits (n :: Nat ) :: Nat where ...
type family EntropySize (n :: Nat ) :: Nat where ...
type family MnemonicWords (n :: Nat ) :: Nat where ...

Introduction

We call Entropy an arbitrary sequence of bytes that has been generated through high quality randomness methods . The allowed size of an Entropy is 96-256 bits and is necessarily a multiple of 32 bits (4 bytes).

We call Mnemonic an Entropy with an appended checksum calculated by taking the first ent / 32 bits of the SHA256 hash of it, where ent designates the Entropy size in bits.

The concatenated result is split into groups of 11 bits, each encoding a number from 0 to 2047 serving as an index into a known dictionary . This makes for a human-readable sentence of English words.

Entropy Size	Checksum Size	Sentence Length	Example
96 bits (12 bytes)	3 bits	9 words	test child burst immense armed parrot company walk dog
128 bits (16 bytes)	4 bits	12 words	test walk nut penalty hip pave soap entry language right filter choice
160 bits (20 bytes)	5 bits	15 words	art forum devote street sure rather head chuckle guard poverty release quote oak craft enemy
192 bits (24 bytes)	6 bits	18 words	churn shaft spoon second erode useless thrive burst group seed element sign scrub buffalo jelly grace neck useless
224 bits (28 bytes)	7 bits	21 words	draft ability female child jump maid roof hurt below live topple paper exclude ordinary coach churn sunset emerge blame ketchup much
256 bits (32 bytes)	8 bits	24 words	excess behave track soul table wear ocean cash stay nature item turtle palm soccer lunch horror start stumble month panic right must lock dress

`SomeMnemonic`

data SomeMnemonic where Source #

Ease the manipulation of Mnemonic by encapsulating the type constraints inside a constructor. This is particularly useful for functions which do not require anything but a valid Mnemonic without any particular pre-condition on the size of the Mnemonic itself.

Since: 1.0.0

Constructors

SomeMnemonic :: forall mw. KnownNat mw => Mnemonic mw -> SomeMnemonic

Instances

Instances details

Eq SomeMnemonic Source #
Instance details Defined in Cardano.Mnemonic Methods (==) :: SomeMnemonic -> SomeMnemonic -> Bool Source # (/=) :: SomeMnemonic -> SomeMnemonic -> Bool Source #
Show SomeMnemonic Source #
Instance details Defined in Cardano.Mnemonic Methods showsPrec :: Int -> SomeMnemonic -> ShowS Source # show :: SomeMnemonic -> String Source # showList :: [ SomeMnemonic ] -> ShowS Source #
NFData SomeMnemonic Source #
Instance details Defined in Cardano.Mnemonic Methods rnf :: SomeMnemonic -> () Source #

class MkSomeMnemonic (sz :: [ Nat ]) where Source #

This class enables caller to parse text list of variable length into mnemonic sentences.

Note that the given Nat s **have** to be valid mnemonic sizes, otherwise the underlying code won't even compile, with not-so-friendly error messages.

Methods

mkSomeMnemonic :: [ Text ] -> Either ( MkSomeMnemonicError sz) SomeMnemonic Source #

Construct a mnemonic from a list of words. This function is particularly useful when the number of words is not necessarily known at runtime. The function is however ambiguous and requires thereby a type application.

examples:

>>> mkSomeMnemonic @'[ 12 ] [ "test", "child", "burst", "immense", "armed", "parrot", "company", "walk", "dog" ]
Left "Invalid number of words: 12 words are expected."

>>> mkSomeMnemonic @'[ 9, 12, 15 ] [ "test", "child", "burst", "immense", "armed", "parrot", "company", "walk", "dog" ]
Right (SomeMnemonic ...)

Since: 1.0.0

Instances

Instances details

(n ~ EntropySize mw, csz ~ CheckSumBits n, ConsistentEntropy n mw csz) => MkSomeMnemonic '[mw] Source #
Instance details Defined in Cardano.Mnemonic Methods mkSomeMnemonic :: [ Text ] -> Either ( MkSomeMnemonicError '[mw]) SomeMnemonic Source #
(n ~ EntropySize mw, csz ~ CheckSumBits n, ConsistentEntropy n mw csz, MkSomeMnemonic rest, NatVals rest) => MkSomeMnemonic (mw ': rest) Source #
Instance details Defined in Cardano.Mnemonic Methods mkSomeMnemonic :: [ Text ] -> Either ( MkSomeMnemonicError (mw ': rest)) SomeMnemonic Source #

newtype MkSomeMnemonicError (sz :: [ Nat ]) Source #

Error reported from trying to create a passphrase from a given mnemonic

Since: 1.0.0

Constructors

MkSomeMnemonicError
Fields getMkSomeMnemonicError :: String

Instances

Instances details

Eq ( MkSomeMnemonicError sz) Source #
Instance details Defined in Cardano.Mnemonic Methods (==) :: MkSomeMnemonicError sz -> MkSomeMnemonicError sz -> Bool Source # (/=) :: MkSomeMnemonicError sz -> MkSomeMnemonicError sz -> Bool Source #
Show ( MkSomeMnemonicError sz) Source #
Instance details Defined in Cardano.Mnemonic Methods showsPrec :: Int -> MkSomeMnemonicError sz -> ShowS Source # show :: MkSomeMnemonicError sz -> String Source # showList :: [ MkSomeMnemonicError sz] -> ShowS Source #

someMnemonicToBytes :: SomeMnemonic -> ScrubbedBytes Source #

Convert a SomeMnemonic to bytes.

Since: 1.0.1

class NatVals (ns :: [ Nat ]) where Source #

Small helper to collect Nat values from a type-level list

Methods

natVals :: Proxy ns -> [ Integer ] Source #

Instances

Instances details

NatVals ('[] :: [ Nat ]) Source #
Instance details Defined in Cardano.Mnemonic Methods natVals :: Proxy '[] -> [ Integer ] Source #
( KnownNat n, NatVals rest) => NatVals (n ': rest) Source #
Instance details Defined in Cardano.Mnemonic Methods natVals :: Proxy (n ': rest) -> [ Integer ] Source #

`Mnemonic`

mkMnemonic :: forall (mw :: Nat ) (ent :: Nat ) csz. ( ConsistentEntropy ent mw csz, EntropySize mw ~ ent) => [ Text ] -> Either ( MkMnemonicError csz) ( Mnemonic mw) Source #

Smart-constructor for Mnemonic . Requires a type application to disambiguate the mnemonic size.

example :

>>> mkMnemonic @15 sentence
Mnemonic {} :: Mnemonic 15

property :

mkMnemonic (mnemonicToText mnemonic) == Right mnemonic

Since: 1.0.0

data MkMnemonicError csz Source #

This wraps errors from Cardano.Encoding.BIP39

Constructors

ErrMnemonicWords MnemonicWordsError	Wrong number of words in mnemonic.
ErrEntropy ( EntropyError csz)	Invalid entropy length or checksum.
ErrDictionary DictionaryError	Invalid word in mnemonic.

Instances

Instances details

Eq ( MkMnemonicError csz) Source #
Instance details Defined in Cardano.Mnemonic Methods (==) :: MkMnemonicError csz -> MkMnemonicError csz -> Bool Source # (/=) :: MkMnemonicError csz -> MkMnemonicError csz -> Bool Source #
Show ( MkMnemonicError csz) Source #
Instance details Defined in Cardano.Mnemonic Methods showsPrec :: Int -> MkMnemonicError csz -> ShowS Source # show :: MkMnemonicError csz -> String Source # showList :: [ MkMnemonicError csz] -> ShowS Source #
NFData ( MkMnemonicError csz) Source #
Instance details Defined in Cardano.Mnemonic Methods rnf :: MkMnemonicError csz -> () Source #

mnemonicToText :: Mnemonic mw -> [ Text ] Source #

Convert a Mnemonic to a sentence of English mnemonic words.

Since: 1.0.0

mnemonicToEntropy :: Mnemonic mw -> Entropy ( EntropySize mw) Source #

Convert a Mnemonic back to an Entropy .

Since: 1.0.0

`Entropy`

data Entropy (n :: Nat ) Source #

BIP39's entropy is a byte array of a given size (in bits, see ValidEntropySize for the valid size).

To it is associated

Instances

Instances details

Eq ( Entropy n)
Instance details Defined in Crypto.Encoding.BIP39 Methods (==) :: Entropy n -> Entropy n -> Bool Source # (/=) :: Entropy n -> Entropy n -> Bool Source #
Show ( Entropy n)
Instance details Defined in Crypto.Encoding.BIP39 Methods showsPrec :: Int -> Entropy n -> ShowS Source # show :: Entropy n -> String Source # showList :: [ Entropy n] -> ShowS Source #
NormalForm ( Entropy n)
Instance details Defined in Crypto.Encoding.BIP39 Methods toNormalForm :: Entropy n -> () Source #
Arbitrary ( Entropy 96)
Instance details Defined in Crypto.Encoding.BIP39 Methods arbitrary :: Gen ( Entropy 96) Source #
Arbitrary ( Entropy 128)
Instance details Defined in Crypto.Encoding.BIP39 Methods arbitrary :: Gen ( Entropy 128) Source #
Arbitrary ( Entropy 160)
Instance details Defined in Crypto.Encoding.BIP39 Methods arbitrary :: Gen ( Entropy 160) Source #
Arbitrary ( Entropy 192)
Instance details Defined in Crypto.Encoding.BIP39 Methods arbitrary :: Gen ( Entropy 192) Source #
Arbitrary ( Entropy 224)
Instance details Defined in Crypto.Encoding.BIP39 Methods arbitrary :: Gen ( Entropy 224) Source #
Arbitrary ( Entropy 256)
Instance details Defined in Crypto.Encoding.BIP39 Methods arbitrary :: Gen ( Entropy 256) Source #

genEntropy :: forall (ent :: Nat ) csz. ( ValidEntropySize ent, ValidChecksumSize ent csz) => IO ( Entropy ent) Source #

Generate Entropy of a given size using a cryptographically secure random seed.

example:

>>> genEntropy @128
Entropy {} :: Entropy 128

Since: 1.0.0

mkEntropy :: forall (ent :: Nat ) csz. ( ValidEntropySize ent, ValidChecksumSize ent csz) => ScrubbedBytes -> Either ( EntropyError csz) ( Entropy ent) Source #

Smart-constructor for the Entropy . Make sure the ByteString comes from a highly random source or use genEntropy .

example :

>>> mkEntropy @160 bytes
Entropy {} :: Entropy 160

property :

mkEntropy (entropyToBytes ent) == Right ent

Since: 1.0.0

entropyToBytes :: Entropy n -> ScrubbedBytes Source #

Convert Entropy to plain bytes.

Since: 1.0.0

entropyToMnemonic :: forall mw ent csz. ( ValidMnemonicSentence mw, ValidEntropySize ent, ValidChecksumSize ent csz, ent ~ EntropySize mw, mw ~ MnemonicWords ent) => Entropy ent -> Mnemonic mw Source #

Convert an Entropy to a corresponding Mnemonic Sentence. Since Entropy and Mnemonic can only be created through smart-constructors, this function cannot fail and is total.

Since: 1.0.0

type ValidEntropySize (n :: Nat ) = ( KnownNat n, NatWithinBound Int n, Elem n '[96, 128, 160, 192, 224, 256]) Source #

Type Constraint Alias to check a given Nat is valid for an entropy size

i.e. it must be one of the following: 96, 128, 160, 192, 224, 256.

type ValidMnemonicSentence (mw :: Nat ) = ( KnownNat mw, NatWithinBound Int mw, Elem mw '[9, 12, 15, 18, 21, 24]) Source #

Type Constraint to validate the given Nat is valid for the supported MnemonicSentence

type ConsistentEntropy (ent :: Nat ) (mw :: Nat ) (csz :: Nat ) = ( ValidEntropySize ent, ValidChecksumSize ent csz, ValidMnemonicSentence mw, MnemonicWords ent ~ mw) Source #

Type Constraint Alias to check the entropy size, the number of mnemonic words and the checksum size is consistent. i.e. that the following is true:

| entropysize | checksumsize | entropysize + checksumsize | mnemonicsize | +---------------+--------------+----------------------------+--------------+ | 96 | 3 | 99 | 9 | | 128 | 4 | 132 | 12 | | 160 | 5 | 165 | 15 | | 192 | 6 | 198 | 18 | | 224 | 7 | 231 | 21 | | 256 | 8 | 264 | 24 |

This type constraint alias also perform all the GHC's cumbersome type level literal handling.

type family CheckSumBits (n :: Nat ) :: Nat where ... Source #

Number of bits of checksum related to a specific entropy size in bits

Equations

CheckSumBits 96 = 3
CheckSumBits 128 = 4
CheckSumBits 160 = 5
CheckSumBits 192 = 6
CheckSumBits 224 = 7
CheckSumBits 256 = 8

type family EntropySize (n :: Nat ) :: Nat where ... Source #

Corresponding entropy size in bits for a given number of words

Equations

EntropySize 9 = 96
EntropySize 12 = 128
EntropySize 15 = 160
EntropySize 18 = 192
EntropySize 21 = 224
EntropySize 24 = 256

type family MnemonicWords (n :: Nat ) :: Nat where ... Source #

Number of Words related to a specific entropy size in bits

Equations

MnemonicWords 96 = 9
MnemonicWords 128 = 12
MnemonicWords 160 = 15
MnemonicWords 192 = 18
MnemonicWords 224 = 21
MnemonicWords 256 = 24

Troubleshooting

Natural XX is out of bounds for Int : This usually occurs when ones is trying to specify an invalid size for an Entropy or Mnemonic . For example:

>>> genEntropy @42
error:
  • Natural CheckSumBits 42 is out of bounds for Int

This could be the case as well when forgetting to use an adequate type application:

>>> mkEntropy mempty
error:
  • Natural ent is out of bounds for Int

Orphan instances

Eq MnemonicWordsError Source #
Instance details Methods (==) :: MnemonicWordsError -> MnemonicWordsError -> Bool Source # (/=) :: MnemonicWordsError -> MnemonicWordsError -> Bool Source #
Eq DictionaryError Source #
Instance details Methods (==) :: DictionaryError -> DictionaryError -> Bool Source # (/=) :: DictionaryError -> DictionaryError -> Bool Source #
NFData MnemonicWordsError Source #
Instance details Methods rnf :: MnemonicWordsError -> () Source #
NFData DictionaryError Source #
Instance details Methods rnf :: DictionaryError -> () Source #
Eq ( EntropyError czs) Source #
Instance details Methods (==) :: EntropyError czs -> EntropyError czs -> Bool Source # (/=) :: EntropyError czs -> EntropyError czs -> Bool Source #
NFData ( EntropyError csz) Source #
Instance details Methods rnf :: EntropyError csz -> () Source #