Modulecardano-addresses-4.0.2Haskell2010

Cardano.Mnemonic

14 types
2 classes
12 values

Packagecardano-addresses-4.0.2
Exports31
LanguageHaskell2010
LicenceApache-2.0
SourceMnemonic.hs

Introduction

0 declarations

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

Mnemonic is 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:

https://github.com/cardano-foundation/cardano-wallet/tree/master/specifications/mnemonic/english.txt

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`

5 declarations

datadata SomeMnemonic where

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.

Constructors

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

Instances3Eq, Show, NFData

Eq SomeMnemonicDefined in cardano-addresses-4.0.2 · Cardano.Mnemonic
Show SomeMnemonicDefined in cardano-addresses-4.0.2 · Cardano.Mnemonic
NFData SomeMnemonicDefined in cardano-addresses-4.0.2 · Cardano.Mnemonic

classclass MkSomeMnemonic (sz :: [Nat]) where

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

Note that the given Nats 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
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:
Example1 expression
```
>>> mkSomeMnemonic @'[ 12 ] [ "test", "child", "burst", "immense", "armed", "parrot", "company", "walk", "dog" ]Left "Invalid number of words: 12 words are expected."
```
Example1 expression
```
>>> mkSomeMnemonic @'[ 9, 12, 15 ] [ "test", "child", "burst", "immense", "armed", "parrot", "company", "walk", "dog" ]Right (SomeMnemonic ...)
```

Instances2MkSomeMnemonic

(n ~ EntropySize mw, csz ~ CheckSumBits n, ConsistentEntropy n mw csz) => MkSomeMnemonic '[mw]Defined in cardano-addresses-4.0.2 · Cardano.Mnemonic
(n ~ EntropySize mw, csz ~ CheckSumBits n, ConsistentEntropy n mw csz, MkSomeMnemonic rest, NatVals rest) => MkSomeMnemonic (mw ': rest)Defined in cardano-addresses-4.0.2 · Cardano.Mnemonic

newtypenewtype MkSomeMnemonicError (sz :: [Nat])

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

Constructors

MkSomeMnemonicError
- getMkSomeMnemonicError :: String

Instances2Eq, Show

Eq (MkSomeMnemonicError sz)Defined in cardano-addresses-4.0.2 · Cardano.Mnemonic
Show (MkSomeMnemonicError sz)Defined in cardano-addresses-4.0.2 · Cardano.Mnemonic

valuesomeMnemonicToBytes :: SomeMnemonic -> ScrubbedBytes

Convert a SomeMnemonic to bytes.

classclass NatVals (ns :: [Nat]) where

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

Methods

natVals :: Proxy ns -> [Integer]

Instances2NatVals

NatVals '[]Defined in cardano-addresses-4.0.2 · Cardano.Mnemonic
(KnownNat n, NatVals rest) => NatVals (n ': rest)Defined in cardano-addresses-4.0.2 · Cardano.Mnemonic

`Mnemonic`

7 declarations

datadata Mnemonic (mw :: Nat)

A opaque Mnemonic type.

Instances3Eq, Show, NFData

Eq (Mnemonic mw)Defined in cardano-addresses-4.0.2 · Cardano.Mnemonic
Show (Mnemonic mw)Defined in cardano-addresses-4.0.2 · Cardano.Mnemonic
NFData (Mnemonic mw)Defined in cardano-addresses-4.0.2 · Cardano.Mnemonic
NFData instances

valuemkMnemonicWithDict

:: (ConsistentEntropy ent mw csz, EntropySize mw ~ ent)
=> [Text]
-> Dictionary
-> Either (MkMnemonicError csz) (Mnemonic mw)

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

Example:

Example1 expression

>>> mkMnemonicWithDict @15 sentence dictionaryMnemonic {} :: Mnemonic 15

Property:

Property

prop> mkMnemonicWithDict (mnemonicToTextWithDict mnemonic dictionary) dictionary == Right mnemonic

valuemkMnemonic

:: (ConsistentEntropy ent mw csz, EntropySize mw ~ ent)
=> [Text]
-> Either (MkMnemonicError csz) (Mnemonic mw)

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

Example:

Example1 expression

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

Property:

Property

prop> mkMnemonic (mnemonicToText mnemonic) == Right mnemonic

datadata MkMnemonicError (csz :: Nat)

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.

Instances3Eq, Show, NFData

Eq (MkMnemonicError csz)Defined in cardano-addresses-4.0.2 · Cardano.Mnemonic
Show (MkMnemonicError csz)Defined in cardano-addresses-4.0.2 · Cardano.Mnemonic
NFData (MkMnemonicError csz)Defined in cardano-addresses-4.0.2 · Cardano.Mnemonic

valuemnemonicToTextWithDict :: Mnemonic mw -> Dictionary -> [Text]

Convert a Mnemonic to a sentence of a specified dictionary mnemonic words.

valuemnemonicToText :: Mnemonic mw -> [Text]

Convert a Mnemonic to a sentence of English mnemonic words.

valuemnemonicToEntropy :: Mnemonic mw -> Entropy (EntropySize mw)

Convert a Mnemonic back to an Entropy.

`Entropy`

5 declarations

datadata Entropy (n :: Nat)

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

To it is associated

Instances9Eq, Show, NormalForm, Arbitrary, …

Eq (Entropy n)Defined in cardano-crypto-1.3.0 · Crypto.Encoding.BIP39
Show (Entropy n)Defined in cardano-crypto-1.3.0 · Crypto.Encoding.BIP39
NormalForm (Entropy n)Defined in cardano-crypto-1.3.0 · Crypto.Encoding.BIP39
Arbitrary (Entropy 128)Defined in cardano-crypto-1.3.0 · Crypto.Encoding.BIP39
Arbitrary (Entropy 160)Defined in cardano-crypto-1.3.0 · Crypto.Encoding.BIP39
Arbitrary (Entropy 192)Defined in cardano-crypto-1.3.0 · Crypto.Encoding.BIP39
Arbitrary (Entropy 224)Defined in cardano-crypto-1.3.0 · Crypto.Encoding.BIP39
Arbitrary (Entropy 256)Defined in cardano-crypto-1.3.0 · Crypto.Encoding.BIP39
Arbitrary (Entropy 96)Defined in cardano-crypto-1.3.0 · Crypto.Encoding.BIP39

valuegenEntropy :: (ValidEntropySize ent, ValidChecksumSize ent csz) => IO (Entropy ent)

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

Example:

Example1 expression

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

valuemkEntropy

:: (ValidEntropySize ent, ValidChecksumSize ent csz)
=> ScrubbedBytes
-> Either (EntropyError csz) (Entropy ent)

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

Example:

Example1 expression

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

Property:

Property

prop> mkEntropy (entropyToBytes ent) == Right ent

valueentropyToBytes :: Entropy n -> ScrubbedBytes

Convert Entropy to plain bytes.

valueentropyToMnemonic

:: (ValidMnemonicSentence mw, ValidEntropySize ent, ValidChecksumSize ent csz, ent ~ EntropySize mw, mw ~ MnemonicWords ent)
=> Entropy ent
-> Mnemonic mw

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.

`Dictionary`

3 declarations

datadata Dictionary

this discribe the property of the Dictionary and will alllow to convert from a mnemonic phrase to MnemonicSentence

This is especially needed to build the BIP39 Seed

valueenglish :: Dictionary

valueitalian :: Dictionary

Internals & Re-export from `Crypto.Encoding.BIP39`

11 declarations

datadata EntropyError (csz :: Nat)

Constructors

ErrInvalidEntropyLength Int Int
ErrInvalidEntropyChecksum (Checksum csz) (Checksum csz)

Instances3Eq, Show, NFData

Eq (EntropyError czs)Defined in cardano-addresses-4.0.2 · Cardano.Mnemonic · orphan
Show (EntropyError csz)Defined in cardano-crypto-1.3.0 · Crypto.Encoding.BIP39
NFData (EntropyError csz)Defined in cardano-addresses-4.0.2 · Cardano.Mnemonic · orphan

datadata DictionaryError

Constructors

ErrInvalidDictionaryWord String

Instances3Eq, Show, NFData

Eq DictionaryErrorDefined in cardano-addresses-4.0.2 · Cardano.Mnemonic · orphan
Show DictionaryErrorDefined in cardano-crypto-1.3.0 · Crypto.Encoding.BIP39.Dictionary
NFData DictionaryErrorDefined in cardano-addresses-4.0.2 · Cardano.Mnemonic · orphan

datadata MnemonicWordsError

Constructors

ErrWrongNumberOfWords Int Int

Instances3Eq, Show, NFData

Eq MnemonicWordsErrorDefined in cardano-addresses-4.0.2 · Cardano.Mnemonic · orphan
Show MnemonicWordsErrorDefined in cardano-crypto-1.3.0 · Crypto.Encoding.BIP39
NFData MnemonicWordsErrorDefined in cardano-addresses-4.0.2 · Cardano.Mnemonic · orphan

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

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

type ValidChecksumSize (ent :: Nat) (csz :: Nat) = (KnownNat csz, NatWithinBound Int csz, Elem csz '[3, 4, 5, 6, 7, 8], CheckSumBits ent ~ csz)

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

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

type

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

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.

familytype family CheckSumBits (n :: Nat) :: Nat where

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

familytype family EntropySize (n :: Nat) :: Nat where

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

familytype family MnemonicWords (n :: Nat) :: Nat where

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

newtypenewtype MnemonicException (csz :: Nat)

This wraps EntropyError of Cardano.Encoding.BIP39

Constructors

UnexpectedEntropyError (EntropyError csz)
Invalid entropy length or checksum

Instances3Show, Exception, NFData

Show (MnemonicException csz)Defined in cardano-addresses-4.0.2 · Cardano.Mnemonic
KnownNat csz => Exception (MnemonicException csz)Defined in cardano-addresses-4.0.2 · Cardano.Mnemonic
NFData (MnemonicException csz)Defined in cardano-addresses-4.0.2 · Cardano.Mnemonic

Troubleshooting

0 declarations

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:

Example1 expression

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

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

Example1 expression

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

Orphan instances

6 instances

Eq MnemonicWordsError
Eq DictionaryError
NFData MnemonicWordsError
NFData DictionaryError
Eq (EntropyError czs)
NFData (EntropyError csz)

Introduction

SomeMnemonic

Constructors

Methods

Constructors

Methods

Mnemonic

Constructors

Entropy

Dictionary

Internals & Re-export from Crypto.Encoding.BIP39

Constructors

Constructors

Constructors

Equations

Equations

Equations

Constructors

Troubleshooting

Orphan instances

`SomeMnemonic`

`Mnemonic`

`Entropy`

`Dictionary`

Internals & Re-export from `Crypto.Encoding.BIP39`