btclib.mnemonic package

Submodules

btclib.mnemonic.bip39 module

BIP39 entropy / mnemonic / seed functions.

https://github.com/bitcoin/bips/blob/master/bip-0039.mediawiki.

Checksummed entropy (ENT+CS) is converted from/to mnemonic.

  • bits per word = bpw = 11

  • ENT = raw entropy

  • CS = checksum = ENT / 32

  • MS = words in the mnemonic sentence = (ENT+CS) / bpw

ENT

CS

ENT+CS

MS

128

4

132

12

160

5

165

15

192

6

198

18

224

7

231

21

256

8

264

24

btclib.mnemonic.bip39.entropy_from_mnemonic(mnemonic: str, lang: str = 'en') str

Return the entropy from the BIP39 checksummed mnemonic sentence.

btclib.mnemonic.bip39.mnemonic_from_entropy(entropy: Optional[Union[str, int, bytes]] = None, lang: str = 'en') str

Convert input entropy to BIP39 checksummed mnemonic sentence.

Input entropy can be expressed as binary 0/1 string, bytes-like, or integer; it must be 128, 160, 192, 224, or 256 bits.

In the case of binary 0/1 string and bytes-like, leading zeros are not considered redundant padding.

In the case of integer, where leading zeros cannot be represented, if the bit length is not an allowed value, then the binary 0/1 string is padded with leading zeros up to the next allowed bit length; if the integer bit length is longer than the maximum length, then only the leftmost bits are retained.

btclib.mnemonic.bip39.mxprv_from_mnemonic(mnemonic: str, passphrase: Optional[str] = None, network: str = 'mainnet', verify_checksum: bool = True) str

Return BIP32 root master extended private key from BIP39 mnemonic.

btclib.mnemonic.bip39.seed_from_mnemonic(mnemonic: str, passphrase: str, verify_checksum: bool = True) bytes

Return the seed from the provided BIP39 mnemonic sentence.

The mnemonic checksum verification can be skipped if needed.

btclib.mnemonic.electrum module

Electrum entropy / mnemonic / seed functions.

Electrum mnemonic is versioned, conveying BIP32 derivation rule too.

btclib.mnemonic.electrum.entropy_from_mnemonic(mnemonic: str, lang: str = 'en') str

Return the entropy from the Electrum versioned mnemonic sentence.

btclib.mnemonic.electrum.mnemonic_from_entropy(mnemonic_type: str = 'standard', entropy: Optional[Union[str, int, bytes]] = None, lang: str = 'en') str

Convert input entropy to Electrum versioned mnemonic sentence.

Input entropy can be expressed as binary 0/1 string, bytes-like, or integer.

In the case of binary 0/1 string and bytes-like, leading zeros are considered redundant padding.

btclib.mnemonic.electrum.mxprv_from_mnemonic(mnemonic: str, passphrase: Optional[str] = None, network: str = 'mainnet') str

Return BIP32 master extended private key from Electrum mnemonic.

Note that for a “standard” mnemonic the derivation path is “m”, for a “segwit” mnemonic it is “m/0h” instead.

btclib.mnemonic.electrum.version_from_mnemonic(mnemonic: str) Tuple[str, str]

Return the (Electrum version, clean mnemonic) tuple.

The clean mnemonic is free from spurious whitespace characters (extra spaces, tab, newline, return, formfeed, etc.)

btclib.mnemonic.entropy module

Entropy conversion functions.

Depending on the function, input entropy can be expressed as raw (i.e. binary 0/1 string), bytes, or integer and their equivalent representations.

Leading zeros in raw or bytes entropy are never considered redundant padding.

Output entropy is always raw.

btclib.mnemonic.entropy.bin_str_entropy_from_bytes(bytes_entropy: Union[bytes, str], bits: Union[int, Iterable[int]] = (128, 160, 192, 224, 256, 512)) str

Return raw entropy from the input Octets entropy.

Input entropy can be expressed as hex-string or bytes; it is never padded to satisfy the bit-size requirement.

If more bits than required are provided, the leftmost ones are retained.

Default bit-sizes are 128, 160, 192, 224, 256, or 512 bits.

btclib.mnemonic.entropy.bin_str_entropy_from_entropy(entr: Union[str, int, bytes], bits: Union[int, Iterable[int]] = (128, 160, 192, 224, 256, 512)) str

Return raw entropy from the input entropy.

Input entropy can be expressed as:

  • raw (i.e. binary 0/1 string) entropy

  • bytes (no hex-string, as they would conflict with raw entropy representation)

  • integer (int, no string starting with “0b”/”0x”)

In the case of raw entropy and bytes, entropy is never padded to satisfy the bit-size requirement; instead, integer entropy is front-padded with zeros digits as much as necessary to satisfy the bit-size requirement.

In all cases if more bits than required are provided, the leftmost ones are retained.

Default bit-sizes are 128, 160, 192, 224, 256, or 512 bits.

btclib.mnemonic.entropy.bin_str_entropy_from_int(int_entropy: Union[int, str], bits: Union[int, Iterable[int]] = (128, 160, 192, 224, 256, 512)) str

Return raw entropy from the input integer entropy.

Input entropy can be expressed as int or string starting with “0x”/”0b”; it is front-padded with zeros digits as much as necessary to satisfy the bit-size requirement.

If more bits than required are provided, the leftmost ones are retained.

Default bit-sizes are 128, 160, 192, 224, 256, or 512 bits.

btclib.mnemonic.entropy.bin_str_entropy_from_random(bits: int, entropy: Optional[str] = None, to_be_hashed: bool = True) str

Return CSPRNG raw entropy XOR-ed with input raw entropy.

The input raw entropy is used as initialization value; if not provided, then entropy is generated with the system cryptographically strong pseudo-random number generator (CSPRNG).

Then, this entropy is:

  • XOR-ed with CSPRNG system entropy

  • possibly hashed (if requested)

btclib.mnemonic.entropy.bin_str_entropy_from_rolls(bits: int, dice_sides: int, rolls: List[int], shuffle: bool = True) str

Return raw entropy from the input dice rolls.

Dice rolls are represented by integers in the [1-dice_sides] range; there must be enough rolls to satisfy the bit-size requirement.

Only rolls having value in the [1-base] range are used, with base being the highest power of 2 that is lower than the dice_sides (e.g. for a traditional D6 dice, only rolls having value in [1-4] are used; for a D20 dice, only rolls having value in [1-16] are used; etc.). Rolls can also be shuffled.

If more bits than required are provided, the leftmost ones are retained.

btclib.mnemonic.entropy.bin_str_entropy_from_str(str_entropy: str, bits: Union[int, Iterable[int]] = (128, 160, 192, 224, 256, 512)) str

Return raw entropy from the input raw entropy.

Input entropy must be expressed as raw entropy; it is never padded to satisfy the bit-size requirement.

If more bits than required are provided, the leftmost ones are retained.

Default bit-sizes are 128, 160, 192, 224, 256, or 512 bits.

btclib.mnemonic.entropy.bin_str_entropy_from_wordlist_indexes(indexes: List[int], base: int) str

Return the raw entropy from a list of word-list indexes.

Return the raw (i.e. binary 0/1 string) entropy from the provided list of integer indexes into a given language word-list.

btclib.mnemonic.entropy.bytes_entropy_from_str(bin_str_entropy: str) bytes
btclib.mnemonic.entropy.collect_rolls(bits: int) Tuple[int, List[int]]
btclib.mnemonic.entropy.wordlist_indexes_from_bin_str_entropy(entropy: str, base: int) List[int]

Return the digit indexes for the provided raw entropy.

Return the list of integer indexes into a digit set, usually a language word-list, for the provided raw (i.e. binary 0/1 string) entropy; leading zeros are not considered redundant padding.

btclib.mnemonic.mnemonic module

Mnemonic word-list sentence conversion from/to sequence of integer indexes.

class btclib.mnemonic.mnemonic.WordLists

Bases: object

Class for word-lists to be used in entropy/mnemonic conversions.

Word-lists are from:

More word-lists can be added using the load_lang method.

Word-lists are loaded only if needed and read only once from disk.

language_length(lang: str) int

Return the number of words in the language word-list.

load_lang(lang: str, filename: Optional[str] = None) None

Load/add a language word-list if not loaded/added yet.

The language file has to be provided for adding new languages beyond those already provided.

wordlist(lang: str) List[str]

Return the language word-list.

btclib.mnemonic.mnemonic.indexes_from_mnemonic(mnemonic: str, lang: str) List[int]

Return the word-list integer indexes for a given mnemonic.

Return the list of integer indexes into a language word-list for a given mnemonic.

btclib.mnemonic.mnemonic.mnemonic_from_indexes(indexes: Sequence[int], lang: str) str

Return the mnemonic from a list of word-list integer indexes.

Return the mnemonic from a list of integer indexes into a given language word-list.

Module contents

btclib.mnemonic submodule.