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

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:

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

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

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

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

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`

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

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 # (/=) :: MnemonicWordsError -> MnemonicWordsError -> Bool #
Eq DictionaryError Source #
Instance details Methods (==) :: DictionaryError -> DictionaryError -> Bool # (/=) :: DictionaryError -> DictionaryError -> Bool #
NFData MnemonicWordsError Source #
Instance details Methods rnf :: MnemonicWordsError -> () #
NFData DictionaryError Source #
Instance details Methods rnf :: DictionaryError -> () #
Eq (EntropyError czs) Source #
Instance details Methods (==) :: EntropyError czs -> EntropyError czs -> Bool # (/=) :: EntropyError czs -> EntropyError czs -> Bool #
NFData (EntropyError csz) Source #
Instance details Methods rnf :: EntropyError csz -> () #