Copyright	2020 Input Output (Hong Kong) Ltd. 2021-2022 Input Output Global Inc. (IOG) 2023-2025 Intersect
License	Apache-2.0
Safe Haskell	None
Language	Haskell2010

Cardano.Mnemonic

Contents

Introduction
SomeMnemonic
Mnemonic
Entropy
Dictionary
Internals & Re-export from Crypto.Encoding.BIP39
Troubleshooting
Orphan instances

Description

Synopsis

data SomeMnemonic where
- SomeMnemonic :: forall (mw :: Nat). 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]
data Mnemonic (mw :: Nat)
mkMnemonicWithDict :: forall (mw :: Nat) (ent :: Nat) (csz :: Nat). (ConsistentEntropy ent mw csz, EntropySize mw ~ ent) => [Text] -> Dictionary -> Either (MkMnemonicError csz) (Mnemonic mw)
mkMnemonic :: forall (mw :: Nat) (ent :: Nat) (csz :: Nat). (ConsistentEntropy ent mw csz, EntropySize mw ~ ent) => [Text] -> Either (MkMnemonicError csz) (Mnemonic mw)
data MkMnemonicError (csz :: Nat)
- = ErrMnemonicWords MnemonicWordsError
- | ErrEntropy (EntropyError csz)
- | ErrDictionary DictionaryError
mnemonicToTextWithDict :: forall (mw :: Nat). Mnemonic mw -> Dictionary -> [Text]
mnemonicToText :: forall (mw :: Nat). Mnemonic mw -> [Text]
mnemonicToEntropy :: Mnemonic mw -> Entropy (EntropySize mw)
genEntropy :: forall (ent :: Nat) (csz :: Nat). (ValidEntropySize ent, ValidChecksumSize ent csz) => IO (Entropy ent)
mkEntropy :: forall (ent :: Nat) (csz :: Nat). (ValidEntropySize ent, ValidChecksumSize ent csz) => ScrubbedBytes -> Either (EntropyError csz) (Entropy ent)
entropyToBytes :: forall (n :: Nat). Entropy n -> ScrubbedBytes
entropyToMnemonic :: forall (mw :: Nat) (ent :: Nat) (csz :: Nat). (ValidMnemonicSentence mw, ValidEntropySize ent, ValidChecksumSize ent csz, ent ~ EntropySize mw, mw ~ MnemonicWords ent) => Entropy ent -> Mnemonic mw
data Dictionary
newtype DictionaryError = ErrInvalidDictionaryWord Text
newtype MnemonicException (csz :: Nat) = UnexpectedEntropyError (EntropyError csz)

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

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`

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

Since: 1.0.0

Constructors

SomeMnemonic :: forall (mw :: Nat). KnownNat mw => Mnemonic mw -> SomeMnemonic

Instances

Instances details

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

class 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:

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

newtype MkSomeMnemonicError (sz :: [Nat]) #

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

Since: 1.0.0

Constructors

MkSomeMnemonicError
Fields getMkSomeMnemonicError :: String

Instances

Instances details

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

someMnemonicToBytes :: SomeMnemonic -> ScrubbedBytes #

Convert a SomeMnemonic to bytes.

Since: 1.0.1

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

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

Methods

natVals :: Proxy ns -> [Integer] #

Instances

Instances details

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

`Mnemonic`

data Mnemonic (mw :: Nat) #

A opaque Mnemonic type.

Instances

Instances details

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

mkMnemonicWithDict :: forall (mw :: Nat) (ent :: Nat) (csz :: Nat). (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:

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

Property:

mkMnemonicWithDict (mnemonicToTextWithDict mnemonic dictionary) dictionary == Right mnemonic

Since: 4.0.1

mkMnemonic :: forall (mw :: Nat) (ent :: Nat) (csz :: Nat). (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:

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

Property:

mkMnemonic (mnemonicToText mnemonic) == Right mnemonic

Since: 1.0.0

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

Instances

Instances details

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

mnemonicToTextWithDict :: forall (mw :: Nat). Mnemonic mw -> Dictionary -> [Text] #

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

Since: 4.0.1

mnemonicToText :: forall (mw :: Nat). Mnemonic mw -> [Text] #

Convert a Mnemonic to a sentence of English mnemonic words.

Since: 1.0.0

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

Convert a Mnemonic back to an Entropy.

Since: 1.0.0

`Entropy`

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

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 :: Nat). (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:

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

Property:

mkEntropy (entropyToBytes ent) == Right ent

Since: 1.0.0

entropyToBytes :: forall (n :: Nat). Entropy n -> ScrubbedBytes #

Convert Entropy to plain bytes.

Since: 1.0.0

entropyToMnemonic :: forall (mw :: Nat) (ent :: Nat) (csz :: Nat). (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.

Since: 1.0.0

`Dictionary`

data Dictionary #

Describes the properties of a BIP39 word dictionary.

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

newtype DictionaryError #

Errors from dictionary lookup.

Constructors

ErrInvalidDictionaryWord Text

Instances

Instances details

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

newtype MnemonicException (csz :: Nat) #

This wraps EntropyError of Cardano.Encoding.BIP39

Constructors

UnexpectedEntropyError (EntropyError csz)

Invalid entropy length or checksum

Instances

Instances details

NFData (MnemonicException csz) #
Instance details Defined in Cardano.Mnemonic Methods rnf :: MnemonicException csz -> () #
KnownNat csz => Exception (MnemonicException csz) #
Instance details Defined in Cardano.Mnemonic Methods toException :: MnemonicException csz -> SomeException # fromException :: SomeException -> Maybe (MnemonicException csz) # displayException :: MnemonicException csz -> String # backtraceDesired :: MnemonicException csz -> Bool #
Show (MnemonicException csz) #
Instance details Defined in Cardano.Mnemonic Methods showsPrec :: Int -> MnemonicException csz -> ShowS # show :: MnemonicException csz -> String # showList :: [MnemonicException csz] -> ShowS #

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

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

Introduction

SomeMnemonic

Instances

Instances

Instances

Instances

Mnemonic

Instances

Instances

Entropy

Dictionary

Internals & Re-export from Crypto.Encoding.BIP39

Instances

Instances

Troubleshooting

Orphan instances

`SomeMnemonic`

`Mnemonic`

`Entropy`

`Dictionary`

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