Merge branch 'feature-xpub'; v10.0.0

Author: pjkundert

README.org

@@ -1,4 +1,5 @@
-base58		>=2.0.1, <3
+click
+base58		>=2.0.1,<3
 chacha20poly1305>=0.0.3
 fpdf2		>=2.5.7,<3
 hdwallet	>=2.1,	<3

README.pdf

@@ -148,6 +148,7 @@
     'slip39-recovery	= slip39.recovery.main:main',
     'slip39-generator	= slip39.generator.main:main',
     'slip39-gui		= slip39.gui.main:main',
+    'slip39-cli		= slip39.cli:cli',
 ]
 
 entry_points			= {
@@ -160,6 +161,7 @@
     "slip39.recovery":		"./slip39/recovery",
     "slip39.generator":		"./slip39/generator",
     "slip39.gui":		"./slip39/gui",
+    "slip39.cli":		"./slip39/cli",
 }
 
 package_data			= {

README.txt

@@ -24,6 +24,7 @@
 import math
 import re
 import secrets
+import string
 import warnings
 
 from functools		import wraps
@@ -442,18 +443,58 @@ def from_mnemonic( self, mnemonic: str, path: str = None ) -> "Account":
         self.from_path( path )
         return self
 
+    def from_xpubkey( self, xpubkey: str, path: str = None ) -> "Account":
+        """Derive the Account from the supplied xpubkey and (optionally) path; uses default
+        derivation path for the Account address format, if None provided.
+
+        Since this xpubkey may have been generated at an arbitrary path, eg.
+
+            m/44'/60'/0'
+
+        any subsequent path provided, such as "m/0/0" will give us the address at
+        effective path:
+
+            m/44'/60'/0'/0/0
+
+        However, if we ask for the path from this account, it will return:
+
+            m/0/0
+
+        It is impossible to correctly recover any "hardened" accounts from an xpubkey, such as
+        "m/1'/0".  These would need access to the private key material, which is missing.
+        Therefore, the original account (or an xprivkey) would be required to access the desired
+        path:
+
+            m/44'/60'/0'/1'/0
+
+        """
+        self.hdwallet.from_xpublic_key( xpubkey )
+        self.from_path( path )
+        return self
+
+    def from_xprvkey( self, xprvkey: str, path: str = None ) -> "Account":
+        self.hdwallet.from_xpublic_key( xprvkey )
+        self.from_path( path )
+        return self
+
     def from_path( self, path: str = None ) -> "Account":
         """Change the Account to derive from the provided path.
 
         If a partial path is provided (eg "...1'/0/3"), then use it to replace the given segments in
         current (or the default) account path, leaving the remainder alone.
 
+        If the derivation path is empty (only "m/") then leave the Account at clean_derivation state
+
         """
         from_path		= self.path or Account.path_default( self.crypto, self.format )
         if path:
             from_path		= path_edit( from_path, path )
         self.hdwallet.clean_derivation()
-        self.hdwallet.from_path( from_path )
+        # Valid HD wallet derivation paths always start with "m/"
+        if not ( from_path and len( from_path ) >= 2 and from_path.startswith( "m/" ) ):
+            raise ValueError( f"Unrecognized HD wallet derivation path: {from_path!r}" )
+        if len( from_path ) > 2:
+            self.hdwallet.from_path( from_path )
         return self
 
     @property
@@ -515,10 +556,12 @@ def path( self ):
     @property
     def key( self ):
         return self.hdwallet.private_key()
+    prvkey		= key
 
     @property
     def xkey( self ):
         return self.hdwallet.xprivate_key()
+    xprvkey		= xkey
 
     @property
     def pubkey( self ):
@@ -697,9 +740,39 @@ def path_sequence(
                 values[k]	= next( viters[k], None )
 
 
-def cryptopaths_parser( cryptocurrency, edit=None ):
+def path_hardened( path ):
+    """Remove any non-hardened components from the end of path, eg:
+
+    >>> path_hardened( "m/84'/0'/0'/1/2" )
+    ("m/84'/0'/0'", 'm/1/2')
+    >>> path_hardened( "m/1" )
+    ('m/', 'm/1')
+    >>> path_hardened( "m/1'" )
+    ("m/1'", 'm/')
+    >>> path_hardened( "m/" )
+    ('m/', 'm/')
+    >>> path_hardened( "m/1/2/3'/4" )
+    ("m/1/2/3'", 'm/4')
+
+    Returns  the two components as a tuple of two paths
+    """
+    segs			= path.split( '/' )
+    # Always leaves the m/ on the hard path
+    for hardened in range( 1, len( segs ) + 1 ):
+        if not any( "'" in s for s in segs[hardened:] ):
+            break
+    else:
+        log.debug( f"No non-hardened path segments in {path}" )
+
+    hard			= 'm/' + '/'.join( segs[1:hardened] )
+    soft			= 'm/' + '/'.join( segs[hardened:] )
+    return hard,soft
+
+
+def cryptopaths_parser( cryptocurrency, edit=None, hardened_defaults=False ):
     """Generate a standard cryptopaths list, from the given sequnce of (<crypto>,<paths>) or
-    "<crypto>[:<paths>]" cryptocurrencies (default: CRYPTO_PATHS).
+    "<crypto>[:<paths>]" cryptocurrencies (default: CRYPTO_PATHS, optionally w/ only the hardened
+    portion of the path, eg. omitting the trailing ../0/0).
 
     Adjusts the provided derivation paths by an optional eg. "../-" path adjustment.
 
@@ -716,6 +789,8 @@ def cryptopaths_parser( cryptocurrency, edit=None ):
         crypto			= Account.supported( crypto )
         if paths is None:
             paths		= Account.path_default( crypto )
+            if hardened_defaults:
+                paths,_		= path_hardened( paths )
         if edit:
             paths		= path_edit( paths, edit )
         cryptopaths.append( (crypto,paths) )
@@ -950,15 +1025,43 @@ def account(
     """Generate an HD wallet Account from the supplied master_secret seed, at the given HD derivation
     path, for the specified cryptocurrency.
 
+    If the master_secret is bytes, it is used as-is.  If a str, then we generally expect it to be
+    hex.  However, this is where we can detect alternatives like "{x,y,z}{pub,priv}key...".  These
+    are identifiable by their prefix, which is incompatible with hex, so there is no ambiguity.
+
     """
-    acct			= Account(
-        crypto		= crypto or 'ETH',
-        format		= format,
-    ).from_seed(
-        seed		= master_secret,
-        path		= path,
-    )
-    log.debug( f"Created {acct} from {len(master_secret)*8}-bit seed, at derivation path {path}" )
+    if isinstance( master_secret, bytes ) or all( c in string.hexdigits for c in master_secret ):
+        acct			= Account(
+            crypto	= crypto or 'ETH',
+            format	= format,
+        )
+        acct.from_seed(
+            seed	= master_secret,
+            path	= path,
+        )
+        log.debug( f"Created {acct} from {len(master_secret)*8}-bit seed, at derivation path {path}" )
+    else:
+        # See if we recognize the prefix as a {x,y,z}pub... or .prv...  Get the bound function for
+        # initializing the seed.  Also, deduce the default format from the x/y/z+pub/prv.
+        default_fmt,from_method	= {
+            'xpub': ('legacy', Account.from_xpubkey),
+            'xprv': ('legacy', Account.from_xprvkey),
+            'ypub': ('segwit', Account.from_xpubkey),
+            'yprv': ('segwit', Account.from_xprvkey),
+            'zpub': ('bech32', Account.from_xpubkey),
+            'zprv': ('bech32', Account.from_xprvkey),
+        }.get( master_secret[:4], (None,None) )
+        if from_method is None:
+            raise ValueError(
+                f"Only x/y/z + pub/prv prefixes supported; {master_secret[:8]+'...'!r} prefix supplied" )
+        if format is None:
+            format		= default_fmt
+        acct			= Account(
+            crypto	= crypto or 'ETH',
+            format	= format
+        )
+        from_method( acct, master_secret, path )  # It's an unbound method, so pass the instance
+
     return acct
 
 

requirements.txt

@@ -0,0 +1,79 @@
+
+#
+# Python-slip39 -- Ethereum SLIP-39 Account Generation and Recovery
+#
+# Copyright (c) 2022, Dominion Research & Development Corp.
+#
+# Python-slip39 is free software: you can redistribute it and/or modify it under
+# the terms of the GNU General Public License as published by the Free Software
+# Foundation, either version 3 of the License, or (at your option) any later
+# version.  It is also available under alternative (eg. Commercial) licenses, at
+# your option.  See the LICENSE file at the top of the source tree.
+#
+# Python-slip39 is distributed in the hope that it will be useful, but WITHOUT
+# ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS
+# FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.
+#
+
+import click
+import json
+import logging
+
+from ..			import addresses as slip39_addresses
+from ..util		import log_cfg, log_level
+
+"""
+Provide basic CLI access to the slip39 API.
+
+Output generally defaults to JSON.  Use -v for more details, and --no-json to emit standard text output instead.
+"""
+
+
+@click.group()
+@click.option('-v', '--verbose', count=True)
+@click.option('-q', '--quiet', count=True)
+@click.option( '--json/--no-json', default=True, help="Output JSON (the default)")
+def cli( verbose, quiet, json ):
+    cli.verbosity		= verbose - quiet
+    log_cfg['level']		= log_level( cli.verbosity )
+    logging.basicConfig( **log_cfg )
+    if verbose or quiet:
+        logging.getLogger().setLevel( log_cfg['level'] )
+    cli.json			= json
+cli.verbosity			= 0  # noqa: E305
+cli.json			= False
+
+
+@click.command()
+@click.option( "--crypto", help="The cryptocurrency address to generate (default: BTC)" )
+@click.option( "--paths", help="The HD wallet derivation path (default: the standard path for the cryptocurrency; if xpub, omits leading hardened segments by default)" )
+@click.option( "--secret", help="A seed or '{x,y,z}{pub,prv}...' x-public/private key to derive HD wallet addresses from" )
+@click.option( "--format", help="legacy, segwit, bech32 (default: standard for cryptocurrency or '{x,y,z}{pub/prv}...' key)" )
+@click.option( '--unbounded/--no-unbounded', default=False, help="Allow unbounded sequences of addresses")
+def addresses( crypto, paths, secret, format, unbounded ):
+    if cli.json:
+        click.echo( "[" )
+    for i,(cry,pth,adr) in enumerate( slip39_addresses(
+            master_secret	= secret,
+            crypto		= crypto,
+            paths		= paths,
+            format		= format,
+            allow_unbounded	= unbounded
+    )):
+        if cli.json:
+            if i:
+                click.echo( "," )
+            if cli.verbosity > 0:
+                click.echo( f"    [{json.dumps( cry )+',':6} {json.dumps( pth )+',':21} {json.dumps( adr )}]", nl=False )
+            else:
+                click.echo( f"    {json.dumps( adr )}", nl=False )
+        else:
+            if cli.verbosity > 0:
+                click.echo( f"{cry:5} {pth:20} {adr}" )
+            else:
+                click.echo( f"{adr}" )
+    if cli.json:
+        click.echo( "\n]" )
+
+
+cli.add_command( addresses )

setup.py

@@ -0,0 +1,3 @@
+from .			import cli
+
+cli()

slip39/api.py

@@ -196,6 +196,7 @@ def file_outputline(
 
 def accountgroups_output(
     group,
+    xpub	= False,
     index	= None,
     cipher	= None,
     nonce	= None,
@@ -241,7 +242,7 @@ def accountgroups_output(
 
     # Emit the (optionally encrypted and indexed) accountgroup record.
     payload			= json.dumps([
-        (acct.crypto, acct.path, acct.address) if isinstance( acct, Account ) else acct
+        (acct.crypto, acct.path, (acct.xpubkey if xpub else acct.address )) if isinstance( acct, Account ) else acct
         for acct in group
     ])
     if cipher:

slip39/cli/__init__.py

@@ -9,7 +9,7 @@
 
 from .			import chacha20poly1305, accountgroups_output, accountgroups_input
 from ..util		import log_cfg, log_level, input_secure
-from ..defaults		import BITS, BAUDRATE
+from ..defaults		import BITS, BAUDRATE, CRYPTO_PATHS
 from ..			import Account, cryptopaths_parser
 from ..api		import accountgroups, RANDOM_BYTES
 
@@ -87,6 +87,9 @@ def main( argv=None ):
                      help=f"Specify crypto address formats: {', '.join( Account.FORMATS )}; default: " + ', '.join(
                          f"{c}:{Account.address_format(c)}" for c in Account.CRYPTO_NAMES.values()
                      ))
+    ap.add_argument( '--xpub', default=False, action='store_true',
+                     help="Output xpub... instead of cryptocurrency wallet address (and trim non-hardened default path segments)" )
+    ap.add_argument( '--no-xpub', dest='xpub', action='store_false', help="Inhibit output of xpub (compatible w/ pre-v10.0.0)" )
     ap.add_argument( '-c', '--cryptocurrency', action='append',
                      default=[],
                      help="A crypto name and optional derivation path (default: \"ETH:{Account.path_default('ETH')}\"), optionally w/ ranges, eg: ETH:../0/-" )
@@ -135,10 +138,16 @@ def main( argv=None ):
         assert args.path.startswith( 'm/' ) or ( args.path.startswith( '..' ) and args.path.lstrip( '.' ).startswith( '/' )), \
             "A --path must start with 'm/', or '../', indicating intent to replace 1 or more trailing components of each cryptocurrency's derivation path"
 
-    # If any --format <crypto>:<format> address formats provided
+    # If any --format <crypto>:<format> address formats provided.  If not represented in
+    # --cryptocurrency, add it; specifying a format implies interest in that cryptocurrency.
+    if not args.cryptocurrency:
+        args.cryptocurrency	= list( CRYPTO_PATHS )  # the defaults, if none provided
     for cf in args.format:
         try:
-            Account.address_format( *cf.split( ':' ) )
+            crypto,format	= cf.split( ':' )
+            Account.address_format( crypto, format=format )
+            if not any( k.startswith( crypto ) for k in args.cryptocurrency ):
+                args.cryptocurrency.append( crypto )
         except Exception as exc:
             log.error( f"Invalid address format: {cf}: {exc}" )
             raise
@@ -252,7 +261,22 @@ def healthy_reset( file ):
 
     # ...else...
     # Transmitting.
-    cryptopaths			= cryptopaths_parser( args.cryptocurrency, edit=args.path )
+
+    # What cryptocurrency addresses are requested?  If --xpub, then for those with "default" paths,
+    # trim off the non-hardened components.  In other words, if
+    #
+    #     --crypto BTC
+    #
+    # is specified, emit BTC "bc1..." bech32 addresses at m/84'/0'/0'/0/0, m/84'/0'/0'/0/1, ...
+    #
+    # However, if
+    #
+    #     --xpub --crypto BTC
+    #
+    # is specified, emit BTC "zpub..." xpubkeys at m/84'/0'/0', m/84'/0'/1', ...
+    cryptopaths			= cryptopaths_parser(
+        args.cryptocurrency, edit=args.path, hardened_defaults=args.xpub
+    )
 
     #
     # Set up serial device, if desired.  We will attempt to send each record using hardware flow
@@ -343,6 +367,7 @@ def healthy_waiter( file ):
 
         while not accountgroups_output(
             group	= group,
+            xpub	= args.xpub,
             index	= index if args.enumerated else None,
             cipher	= cipher,
             nonce	= nonce,