Add generation of mnemonic from dice rolls

Author: tdb3

buidl/mnemonic.py

@@ -1,6 +1,7 @@
 from os import path
 from secrets import randbits
 from time import time
+from math import ceil
 
 from buidl.helper import big_endian_to_int, int_to_big_endian, sha256
 
@@ -98,6 +99,40 @@ def bytes_to_mnemonic(b, num_bits):
     return " ".join(mnemonic)
 
 
+def dice_rolls_to_mnemonic(dice_rolls, num_words=24, allow_low_entropy=False):
+    """
+    returns a mnemonic from a string of 6-sided dice rolls
+    (>=100 rolls for 24 words recommended)
+    (>=50 rolls for 12 words recommended)
+    """
+    # check that the number of words provided is 12, 15, 18, 21, or 24
+    if num_words not in (12, 15, 18, 21, 24):
+        raise InvalidBIP39Length(
+            f"{num_words} words requested (must be 12, 15, 18, 21, or 24 words)"
+        )
+    # check that valid dice rolls have been provided
+    if not isinstance(dice_rolls, str):
+        raise ValueError("Dice rolls must be provided as a string")
+    if (
+        len([roll for roll in dice_rolls if roll not in ("1", "2", "3", "4", "5", "6")])
+        > 0
+    ):
+        raise ValueError("Dice roll string contained invalid dice numbers")
+    # entropy (in bits) per 6-sided dice roll (i.e. log2(6)=2.585)
+    entropy_per_roll = 2.585
+    mnemonic_entropy = {12: 128, 15: 160, 18: 192, 21: 224, 24: 256}
+    # check that the appropriate amount of entropy had been provided
+    min_rolls_needed = ceil(mnemonic_entropy[num_words] / entropy_per_roll)
+    if not allow_low_entropy and (len(dice_rolls) < min_rolls_needed):
+        raise ValueError(
+            f"Received {len(dice_rolls)} rolls but need at least {min_rolls_needed}"
+            f" rolls (for {mnemonic_entropy[num_words]} bits of entropy)"
+        )
+    kept_bytes = mnemonic_entropy[num_words] // 8
+    rolls_hash = sha256(dice_rolls.encode())[:kept_bytes]
+    return bytes_to_mnemonic(rolls_hash, kept_bytes * 8)
+
+
 class WordList:
     def __init__(self, filename, num_words):
         word_file = path.join(path.dirname(__file__), filename)

buidl/test/test_mnemonic.py

@@ -1,6 +1,10 @@
 from unittest import TestCase
 
-from buidl.mnemonic import secure_mnemonic
+from buidl.mnemonic import (
+    secure_mnemonic,
+    dice_rolls_to_mnemonic,
+    InvalidBIP39Length,
+)
 from buidl.hd import HDPrivateKey
 
 
@@ -45,3 +49,128 @@ def test_secure_mnemonic_extra_entropy(self):
             secure_mnemonic(extra_entropy="not an int")
         with self.assertRaises(ValueError):
             secure_mnemonic(extra_entropy=-1)
+
+    def test_dice_to_mnemonic(self):
+        tests = [  # dice_rolls, num_words, allow_low_entropy, expected_mnemonic, expected_exception
+            [
+                "",
+                24,
+                True,
+                "together mail awful cradle scrub apart hip leader silk slice unusual embark kit can muscle nature nation gown century cram resource citizen throw produce",
+                None,
+            ],
+            [
+                "123456",
+                24,
+                True,
+                "mirror reject rookie talk pudding throw happy era myth already payment own sentence push head sting video explain letter bomb casual hotel rather garment",
+                None,
+            ],
+            [
+                "123456123456123456123456123456123456123456123456123456123456123456123456123456123456123456123456123456",
+                24,
+                False,
+                "more matter caught bind tip twin indicate visa rifle angle defense lizard stock cave cradle injury always mule photo horse range opinion affair garlic",
+                None,
+            ],
+            [
+                "523365252662366",
+                24,
+                True,
+                "dilemma rural physical exhaust divorce escape nut umbrella lawn midnight prosper prevent employ caught mercy student arctic umbrella feed super mad magic crawl fiscal",
+                None,
+            ],
+            [
+                "",
+                12,
+                True,
+                "together mail awful cradle scrub apart hip leader silk slice unusual embark",
+                None,
+            ],
+            [
+                "123456",
+                12,
+                True,
+                "mirror reject rookie talk pudding throw happy era myth already payment owner",
+                None,
+            ],
+            [
+                "12345612345612345612345612345612345612345612345612",
+                12,
+                False,
+                "unveil nice picture region tragic fault cream strike tourist control recipe tourist",
+                None,
+            ],
+            [
+                "12345612345612345612345612345612345612345612345612345612345612",
+                15,
+                False,
+                "end spider topple cliff tomorrow process dismiss produce athlete film monster team vacant ill silk",
+                None,
+            ],
+            [
+                "123456123456123456123456123456123456123456123456123456123456123456123456123",
+                18,
+                False,
+                "melt churn alley retreat flip once enough gather project prosper cannon nasty furnace isolate cost laundry lottery slice",
+                None,
+            ],
+            [
+                "123456123456123456123456123456123456123456123456123456123456123456123456123456123456123",
+                21,
+                False,
+                "start insane amazing fall kite punch owner refuse bone trigger spirit luggage slide sound reopen broom remember nose limb swallow kitten",
+                None,
+            ],
+            [  # low entropy not allowed
+                "123456",
+                24,
+                False,
+                "",
+                ValueError(
+                    "Received 6 rolls but need at least 100 rolls (for 256 bits of entropy)"
+                ),
+            ],
+            [  # Invalid num_words
+                "123456",
+                23,
+                False,
+                "",
+                InvalidBIP39Length(
+                    "23 words requested (must be 12, 15, 18, 21, or 24 words)"
+                ),
+            ],
+            [  # non-string dice rolls
+                b"123456",
+                24,
+                False,
+                "",
+                ValueError("Dice rolls must be provided as a string"),
+            ],
+            [  # string containing non-dice values
+                "1234567",
+                24,
+                False,
+                "",
+                ValueError("Dice roll string contained invalid dice numbers"),
+            ],
+        ]
+
+        for (
+            dice_rolls,
+            num_words,
+            allow_low_entropy,
+            expected_mnemonic,
+            expected_exception,
+        ) in tests:
+            if expected_exception is None:
+                received_mnemonic = dice_rolls_to_mnemonic(
+                    dice_rolls, num_words, allow_low_entropy
+                )
+                self.assertEqual(received_mnemonic, expected_mnemonic)
+            else:
+                with self.assertRaises(type(expected_exception)) as exception_context:
+                    dice_rolls_to_mnemonic(dice_rolls, num_words, allow_low_entropy)
+                self.assertEqual(
+                    str(exception_context.exception), str(expected_exception)
+                )