Unit tests pass; major updates and improvements

Author: pjkundert

README.org

@@ -216,7 +216,7 @@
 
 On an secure (ideally air-gapped) computer, new seeds can /safely/ be generated (*without*
 trusting this program) and the PDF saved to a USB drive for printing (or directly printed without
-the file being saved to disk.).  Presently, =slip39= can output example ETH, BTC, LTC, DOGE, BNB,
+the file being saved to disk.).  Presently, =slip39= can output example ETH, BTC, LTC, DOGE, BSC,
 and XRP addresses derived from the seed, to /illustrate/ what accounts are associated with the
 backed-up seed.  Recovery of the seed to a [trezor-model-t][3] is simple, by entering the mnemonics
 right on the device.

README.pdf

@@ -33,12 +33,15 @@
 from typing		import Dict, List, Sequence, Tuple, Optional, Union, Callable
 
 from shamir_mnemonic	import generate_mnemonics
+from shamir_mnemonic.shamir import RANDOM_BYTES
 
 import hdwallet
 from hdwallet		import cryptocurrencies
 
-from .defaults		import BITS_DEFAULT, BITS, MNEM_ROWS_COLS, GROUP_REQUIRED_RATIO, CRYPTO_PATHS
-from .util		import ordinal, commas
+from .defaults		import (
+    BITS_DEFAULT, BITS, MNEM_ROWS_COLS, GROUPS, GROUP_REQUIRED_RATIO, GROUP_THRESHOLD_RATIO, CRYPTO_PATHS
+)
+from .util		import ordinal, commas, is_listlike, is_mapping
 from .recovery		import produce_bip39, recover_bip39, recover as recover_slip39
 
 __author__                      = "Perry Kundert"
@@ -48,6 +51,7 @@
 
 log				= logging.getLogger( __package__ )
 
+
 # Support for private key encryption via BIP-38 and Ethereum JSON wallet is optional; pip install slip39[wallet]
 paper_wallet_issues		= []
 try:
@@ -73,9 +77,6 @@
     paper_wallet_issues.append( message )
 
 
-RANDOM_BYTES			= secrets.token_bytes
-
-
 def paper_wallet_available():
     """Determine if encrypted BIP-38 and Ethereum JSON Paper Wallets are available."""
     available			= AES and scrypt and eth_account
@@ -118,7 +119,7 @@ def path_edit(
 
 class BinanceMainnet( cryptocurrencies.Cryptocurrency ):
     NAME = "Binance"
-    SYMBOL = "BNB"
+    SYMBOL = "BSC"
     NETWORK = "mainnet"
     SOURCE_CODE = "https://github.com/bnb-chain/bsc"
     COIN_TYPE = cryptocurrencies.CoinType({
@@ -249,7 +250,7 @@ class Account:
     | Crypto | Semantic | Path              | Address | Support |
     |--------+----------+-------------------+---------+---------|
     | ETH    | Legacy   | m/44'/ 60'/0'/0/0 | 0x...   |         |
-    | BNB    | Legacy   | m/44'/ 60'/0'/0/0 | 0x...   | Beta    |
+    | BSC    | Legacy   | m/44'/ 60'/0'/0/0 | 0x...   | Beta    |
     | BTC    | Legacy   | m/44'/  0'/0'/0/0 | 1...    |         |
     |        | SegWit   | m/49'/  0'/0'/0/0 | 3...    |         |
     |        | Bech32   | m/84'/  0'/0'/0/0 | bc1...  |         |
@@ -267,7 +268,7 @@ class Account:
         BTC		= 'Bitcoin',
         LTC		= 'Litecoin',
         DOGE		= 'Dogecoin',
-        BNB		= 'Binance',
+        BSC		= 'Binance',
         XRP		= 'Ripple',
     )
     CRYPTO_DECIMALS		= dict(
@@ -283,7 +284,7 @@ class Account:
         BTC		= 24,
         LTC		= 24,
         DOGE		= 24,
-        BNB		= 18,
+        BSC		= 18,
         XRP		= 6,
     )
     CRYPTO_NAMES		= dict(
@@ -293,21 +294,21 @@ class Account:
         bitcoin		= 'BTC',
         litecoin	= 'LTC',
         dogecoin	= 'DOGE',
-        binance		= 'BNB',
+        binance		= 'BSC',
         ripple		= 'XRP',
     )
     CRYPTOCURRENCIES		= set( CRYPTO_NAMES.values() )
-    CRYPTOCURRENCIES_BETA	= set( ('BNB', 'XRP') )
+    CRYPTOCURRENCIES_BETA	= set( ('BSC', 'XRP') )
 
-    ETHJS_ENCRYPT		= set( ('ETH', 'BNB') )			# Can be encrypted w/ Ethereum JSON wallet
+    ETHJS_ENCRYPT		= set( ('ETH', 'BSC') )			# Can be encrypted w/ Ethereum JSON wallet
     BIP38_ENCRYPT		= CRYPTOCURRENCIES - ETHJS_ENCRYPT      # Can be encrypted w/ BIP-38
 
     CRYPTO_FORMAT		= dict(
         ETH		= "legacy",
         BTC		= "bech32",
         LTC		= "bech32",
         DOGE		= "legacy",
-        BNB		= "legacy",
+        BSC		= "legacy",
         XRP		= "legacy",
     )
 
@@ -317,11 +318,11 @@ class Account:
         XRP		= XRPHDWallet,
     )
     CRYPTO_LOCAL		= dict(
-        BNB		= BinanceMainnet,
+        BSC		= BinanceMainnet,
         XRP		= RippleMainnet,
     )
     CRYPTO_LOCAL_SYMBOL		= dict(
-        BNB		= "ETH"
+        BSC		= "ETH"
     )
 
     # The available address formats and default derivation paths.
@@ -331,7 +332,7 @@ class Account:
         ETH		= dict(
             legacy	= "m/44'/60'/0'/0/0",
         ),
-        BNB		= dict(
+        BSC		= dict(
             legacy	= "m/44'/60'/0'/0/0",
         ),
         BTC		= dict(
@@ -356,7 +357,7 @@ class Account:
         ETH		= dict(
             legacy	= "p2pkh",
         ),
-        BNB		= dict(
+        BSC		= dict(
             legacy	= "p2pkh",
         ),
         BTC		= dict(
@@ -444,12 +445,6 @@ def __init__( self, crypto, format=None ):
         self.format		= format.lower() if format else Account.address_format( crypto )
         semantic		= self.CRYPTO_FORMAT_SEMANTIC[crypto][self.format]
         hdwallet_cls		= self.CRYPTO_WALLET_CLS.get( crypto, hdwallet.HDWallet )
-        # if hdwallet_cls is None and self.format in ("legacy",):
-        #     hdwallet_cls	= hdwallet.HDWallet  # hdwallet.BIP44HDWallet
-        # if hdwallet_cls is None and self.format in ("segwit",):
-        #     hdwallet_cls	= hdwallet.HDWALLET  # hdwallet.BIP49HDWallet
-        # if hdwallet_cls is None and self.format in ("bech32",):
-        #     hdwallet_cls	= hdwallet.BIP84HDWallet
         if hdwallet_cls is None:
             raise ValueError( f"{crypto} does not support address format {self.format}" )
         self.hdwallet		= hdwallet_cls( symbol=crypto, cryptocurrency=cryptocurrency, semantic=semantic )
@@ -894,11 +889,11 @@ def cryptopaths_parser(
 
         cry,*pth		= crypto
         pth,*fmt		= pth or (None,)
-        fmt,			= fmt or (None,)
+        fmt,			= fmt or (format,)
 
         cry			= Account.supported( cry )
         if not pth:
-            pth			= Account.path_default( cry, fmt or format )
+            pth			= Account.path_default( cry, fmt )
             if hardened_defaults:
                 pth,_		= path_hardened( pth )
         if edit:
@@ -907,7 +902,7 @@ def cryptopaths_parser(
 
 
 def random_secret(
-    seed_length			= BITS_DEFAULT // 8
+    seed_length: Optional[int]
 ) -> bytes:
     """Generates a new random secret.
 
@@ -930,6 +925,8 @@ def random_secret(
     2**128 / 1e9 / 7e9 / (60*60*24*365) == 1,541,469,010,115.145
 
     """
+    assert seed_length, \
+        f"Must supply a non-zero length in bytes, not {seed_length}"
     return RANDOM_BYTES( seed_length )
 
 
@@ -1002,21 +999,32 @@ def group_parser( group_spec ):
 
 def create(
     name: str,
-    group_threshold: int,
-    groups: Dict[str,Tuple[int, int]],
-    master_secret: Optional[bytes] = None,      # Default: generate 128-bit Seed Entropy
+    group_threshold: Optional[Union[int,float]] = None,		# Default: 1/2 of groups, rounded up
+    groups: Optional[Union[List[str],Dict[str,Tuple[int, int]]]] = None,  # Default: 4 groups (see defaults.py)
+    master_secret: Optional[Union[str,bytes]] = None,		# Default: generate 128-bit Seed Entropy
     passphrase: Optional[Union[bytes,str]] = None,
-    using_bip39: bool		= False,        # Produce wallet Seed from master_secret Entropy using BIP-39 generation
+    using_bip39: Optional[bool]	= None,  # Produce wallet Seed from master_secret Entropy using BIP-39 generation
     iteration_exponent: int	= 1,
     cryptopaths: Optional[Sequence[Union[str,Tuple[str,str],Tuple[str,str,str]]]] = None,  # default: ETH, BTC at default path, format
-    strength: int		= 128,
+    strength: Optional[int]	= None,		# Default: 128
 ) -> Tuple[str,int,Dict[str,Tuple[int,List[str]]], Sequence[Sequence[Account]], bool]:
     """Creates a SLIP-39 encoding for supplied master_secret Entropy, and 1 or more Cryptocurrency
     accounts.  Returns the Details, in a form directly compatible with the layout.produce_pdf API.
 
     The master_secret Seed Entropy is discarded (because it is, of course, always recoverable from
     the SLIP-39 mnemonics).
 
+    We strive to default to "do the right thing", here.  If you supply BIP-39 Mnemonics, we'll
+    round-trip them via SLIP-39, and produce compatible crypto account addresses.  This should be
+    the "typical" case, as most people already have BIP-39 Mnemonics.  If you don't have a BIP-39
+    Mnemonic, make sure you set using_bip39 = True; this *also* implies that you *MUST* have already
+    converted your entropy to BIP-39 (or are going to recover it and do so, later), so we'll warn
+    you to do that.  If a passphrase is provided, it is assumed to be a BIP-39 passphrase, and is used
+    to generate the crypto account addresses -- it will *not* be used to "encrypt" the SLIP-39!
+
+    If you supply raw entropy, we'll assume you have SLIP-39 compatible wallet and want to use it
+    directly.
+
     Creates accountgroups derived from the Seed Entropy.  By default, this is done in the SLIP-39
     standard, using the master_secret Entropy directly.  If a passphrase is supplied, this is also
     used in the SLIP-39 standard fashion (not recommended -- not Trezor "Model T" compatible).
@@ -1027,16 +1035,33 @@ def create(
 
     """
     if master_secret is None:
-        assert strength in BITS, f"Invalid {strength}-bit secret length specified"
+        if not strength:
+            strength		= BITS_DEFAULT
         master_secret		= random_secret( strength // 8 )
-
-    g_names,g_dims		= list( zip( *groups.items() ))
+    if isinstance( master_secret, bytes ) and not ( 128 <= len( master_secret ) * 8 <= 512 ):
+        log.warning( f"Strangely sized {len(master_secret) * 8}-bit entropy provided; may be weak" )
+
+    # If a non-hex str is passed as entropy, assume it is a BIP-39 Mnemonic, and that we want to use
+    # SLIP-39 to round-trip the underlying BIP-39 entropy AND derive compatible wallets.
+    if isinstance( master_secret, str ) and all( c in '0123456789abcdef' for c in master_secret.lower() ):
+        master_secret		= codecs.decode( master_secret, 'hex_codec' )
+    if using_bip39 is None and isinstance( master_secret, str ):
+	# Assume it must be a BIP-39 Mnemonic
+        using_bip39		= True
+    else:
+        # Assume caller knows; default False (use SLIP-39 directly)
+        using_bip39		= bool( using_bip39 )
 
     # Derive the desired account(s) at the specified derivation paths, or the default, using either
     # BIP-39 Seed generation, or directly from Entropy for SLIP-39.
     if using_bip39:
         # For BIP-39, the passphrase is consumed here, and Cryptocurrency accounts are generated
-        # using the BIP-39 Seed generated from entropy + passphrase
+        # using the BIP-39 Seed generated from entropy + passphrase.  This should be the "typical"
+        # use-case, where someone already has a BIP-39 Mnemonic and/or wants to use a "standard"
+        # BIP-39 compatible hardware wallet.
+        log.warning( f"Assuming BIP-39 seed entropy: Ensure you recover and use via a BIP-39 Mnemonic" )
+        if isinstance( master_secret, str ):
+            master_secret	= recover_bip39( mnemonic=master_secret, as_entropy=True )
         bip39_mnem		= produce_bip39( entropy=master_secret )
         bip39_seed		= recover_bip39(
             mnemonic	= bip39_mnem,
@@ -1053,8 +1078,10 @@ def create(
         passphrase		= None  # Consumed by BIP-39; not used for SLIP-39 Mnemonics "backup"!
     else:
         # For SLIP-39, accounts are generated directly from supplied Entropy, and passphrase
-        # encrypts the SLIP-39 Mnemonics, below.
-        log.info(
+        # encrypts the SLIP-39 Mnemonics, below.  Using a SLIP-39 with a passphrase is so unlikely
+        # to be correct that we will warn about it!  You almost *always* want to use SLIP-39
+        # *without* a passphase; use eg. Trezor "hidden wallets" instead.
+        (log.warning if passphrase else log.info)(
             f"SLIP-39 for {name} from {len(master_secret)*8}-bit Entropy directly{' w/ SLIP-39 Passphrase' if passphrase else ''}"
         )
         accts			= list( accountgroups(
@@ -1063,6 +1090,15 @@ def create(
             allow_unbounded	= False,
         ))
 
+    # Deduce groups, using defaults
+    if not groups:
+        groups			= GROUPS
+    if not is_mapping( groups ):
+        if isinstance( groups, str ):
+            groups		= groups.split( "," )
+        groups			= dict( map( group_parser, groups ))
+    g_names,g_dims		= list( zip( *groups.items() ))
+
     # Generate the SLIP-39 Mnemonics representing the supplied master_secret Seed Entropy.  This
     # always recovers the Seed Entropy; if not using_bip39, this is also the wallet derivation Seed;
     # if using_bip39, the wallet derivation Seed was produced from the BIP-39 Seed generation
@@ -1094,7 +1130,7 @@ def create(
 
 
 def mnemonics(
-    group_threshold: int,
+    group_threshold: Optional[int],  # Default: 1/2 of groups, rounded up
     groups: Sequence[Tuple[int, int]],
     master_secret: Optional[Union[str,bytes]] = None,
     passphrase: Optional[Union[bytes,str]] = None,
@@ -1120,6 +1156,10 @@ def mnemonics(
             f"Only {commas( BITS, final='and' )}-bit seeds supported; {len(master_secret)*8}-bit seed supplied" )
     if isinstance( passphrase, str ):
         passphrase		= passphrase.encode( 'UTF-8' )
+
+    groups			= list( groups )
+    if not group_threshold:
+        group_threshold		= math.ceil( len( groups ) * GROUP_THRESHOLD_RATIO )
     return generate_mnemonics(
         group_threshold	= group_threshold,
         groups		= groups,

README.txt

@@ -124,6 +124,7 @@ def test_account_format():
         crypto		= 'Bitcoin',
         format		= "legacy",
     )
+    assert acct.format == 'legacy'
     assert acct.hdwallet.seed() == "5eb00bbddcf069084889a8ab9155568165f5c453ccb85e70811aaed6f6da5fc19a5ac40b389cd370d086206dec8aa6c43daea6690f20ad3d8d48b2d2ce9e38e4"
     assert acct.path == "m/44'/0'/0'/0/0"
     assert acct.address == '1LqBGSKuX5yYUonjxT5qGfpUsXKYYWeabA'
@@ -232,9 +233,9 @@ def test_account_format():
 
 def test_account_from_mnemonic():
     """Test all the ways the entropy 0xffff...ffff can be encoded and HD Wallets derived."""
-    # Raw 0xffff...ffff entropy as Seed.  Not BIP-39 decoded (hashed) via mnemonic to produce Seed.  This is
-    # how SLIP-39 encodes and decodes entropy.  The rot HD Wallet Seed directly uses the entropy,
-    # un-molested.
+    # Raw 0xffff...ffff entropy as Seed.  Not BIP-39 decoded (hashed) via mnemonic to produce Seed.
+    # This is how SLIP-39 encodes and decodes entropy.  The raw HD Wallet Seed directly uses the
+    # entropy, un-molested.
     acct_ones			= account( SEED_ONES, crypto='Bitcoin' )
     assert acct_ones.path == "m/84'/0'/0'/0/0"  # Default, BTC
     assert acct_ones.address == 'bc1q9yscq3l2yfxlvnlk3cszpqefparrv7tk24u6pl'
@@ -288,6 +289,14 @@ def test_account_from_mnemonic():
     assert acct.path == "m/44'/144'/0'/0/0"  # Default
     assert acct.address == 'rUPzi4ZwoYxi7peKCqUkzqEuSrzSRyLguV'
 
+    # And straight from BIP-39 Mnemonics
+    details_zoos_using_bip39		= create(
+        "SLIP39 Wallet: From zoo ... BIP-39",
+        master_secret	= BIP39_ZOO,
+    )
+    [(eth_zoo,btc_zoo)]	= details_zoos_using_bip39.accounts
+    btc_zoo.address == 'bc1qk0a9hr7wjfxeenz9nwenw9flhq0tmsf6vsgnn2'
+
 
 @pytest.mark.skipif( not scrypt or not eth_account,
                      reason="pip install slip39[wallet] to support private key encryption" )
@@ -550,31 +559,31 @@ def test_addressgroups():
             ('Ripple',	".../-3"),
         ],
     )))
-    print( repr( addrgrps ))
+    # print( repr( addrgrps ))
     assert addrgrps == [								# Verified
         (0,(('ETH', "m/44'/60'/0'/0/0", '0xfc2077CA7F403cBECA41B1B0F62D91B5EA631B5E'),	# Ledger
             ('BTC', "m/84'/0'/0'/0/0", 'bc1qk0a9hr7wjfxeenz9nwenw9flhq0tmsf6vsgnn2'),	# Ledger
             ('LTC', "m/84'/2'/0'/0/0", 'ltc1qnreu4d88p5tvh33anptujvcvn3xmfhh43yg0am'),	# Ledger
             ('DOGE', "m/44'/3'/0'/0/0", 'DTMaJd8wqye1fymnjxZ5Cc5QkN1w4pMgXT'),		# Ledger
-            ('BNB', "m/44'/60'/0'/0/0", '0xfc2077CA7F403cBECA41B1B0F62D91B5EA631B5E'),	# Ledger
+            ('BSC', "m/44'/60'/0'/0/0", '0xfc2077CA7F403cBECA41B1B0F62D91B5EA631B5E'),	# Ledger
             ('XRP', "m/44'/144'/0'/0/0", 'rUPzi4ZwoYxi7peKCqUkzqEuSrzSRyLguV'))),	# Ledger 
         (1, (('ETH', "m/44'/60'/0'/0/1", '0xd1a7451beB6FE0326b4B78e3909310880B781d66'),
              ('BTC', "m/84'/0'/0'/0/1", 'bc1qkd33yck74lg0kaq4tdcmu3hk4yruhjayxpe9ug'),
              ('LTC', "m/84'/2'/0'/0/1", 'ltc1qm4yc8vgxyv0xeu8p4vtq2wls245y2ueqpfrp4d'),
              ('DOGE', "m/44'/3'/0'/0/1", 'DGkL2LD5FfccAaKtx8G7TST5iZwrNkecTY'),
-             ('BNB', "m/44'/60'/0'/0/1", '0xd1a7451beB6FE0326b4B78e3909310880B781d66'),
+             ('BSC', "m/44'/60'/0'/0/1", '0xd1a7451beB6FE0326b4B78e3909310880B781d66'),
              ('XRP', "m/44'/144'/0'/0/1", 'ravkJwvQBuW4P5TG1qK5WDAgBxbPhdyPh1'))),
         (2, (('ETH', "m/44'/60'/0'/0/2", '0x578270B5E5B53336baC354756b763b309eCA90Ef'),
              ('BTC', "m/84'/0'/0'/0/2", 'bc1qvr7e5aytd0hpmtaz2d443k364hprvqpm3lxr8w'),
              ('LTC', "m/84'/2'/0'/0/2", 'ltc1qstkxz076qdyg0r08eszf0rrxsmfcgj62lkqaj2'),
              ('DOGE', "m/44'/3'/0'/0/2", 'DQa3SpFZH3fFpEFAJHTXZjam4hWiv9muJX'),
-             ('BNB', "m/44'/60'/0'/0/2", '0x578270B5E5B53336baC354756b763b309eCA90Ef'),
+             ('BSC', "m/44'/60'/0'/0/2", '0x578270B5E5B53336baC354756b763b309eCA90Ef'),
              ('XRP', "m/44'/144'/0'/0/2", 'rpzdHCsqVLppnUAUvgYDd6ADZFeKE6QoHR'))),
         (3, (('ETH', "m/44'/60'/0'/0/3", '0x909f59835A5a120EafE1c60742485b7ff0e305da'),
              ('BTC', "m/84'/0'/0'/0/3", 'bc1q6t9vhestkcfgw4nutnm8y2z49n30uhc0kyjl0d'),
              ('LTC', "m/84'/2'/0'/0/3", 'ltc1qts5sde8st3x6qt2t0xhtf9uactg7nnztamuehk'),
              ('DOGE', "m/44'/3'/0'/0/3", 'DTW5tqLwspMY3NpW3RrgMfjWs5gnpXtfwe'),
-             ('BNB', "m/44'/60'/0'/0/3", '0x909f59835A5a120EafE1c60742485b7ff0e305da'),
+             ('BSC', "m/44'/60'/0'/0/3", '0x909f59835A5a120EafE1c60742485b7ff0e305da'),
              ('XRP', "m/44'/144'/0'/0/3", 'r9czvGVozoKTAnP1G17RG9DfWK272ZExvX')))
     ]