feat(key): add mnemonic generation and key derivation

Add support for generating mnemonics and deriving extended signing keys
from mnemonic sentences. Introduce KeyType and OutputFormat enums.
Refactor helpers for file reading. Update KeyGroup with new methods
for mnemonic and key derivation.

Author: mkoura

cardano_clusterlib/clusterlib.py

@@ -8,9 +8,11 @@
 from cardano_clusterlib.consts import CommandEras
 from cardano_clusterlib.consts import DEFAULT_COIN
 from cardano_clusterlib.consts import Eras
+from cardano_clusterlib.consts import KeyType
 from cardano_clusterlib.consts import MAINNET_MAGIC
 from cardano_clusterlib.consts import MultiSigTypeArgs
 from cardano_clusterlib.consts import MultiSlotTypeArgs
+from cardano_clusterlib.consts import OutputFormat
 from cardano_clusterlib.consts import ScriptTypes
 from cardano_clusterlib.consts import Votes
 from cardano_clusterlib.exceptions import CLIError

cardano_clusterlib/consts.py

@@ -53,3 +53,16 @@ class Votes(enum.Enum):
     YES = 1
     NO = 2
     ABSTAIN = 3
+
+
+class KeyType(enum.Enum):
+    PAYMENT = "payment"
+    STAKE = "stake"
+    DREP = "drep"
+    CC_COLD = "cc-cold"
+    CC_HOT = "cc-hot"
+
+
+class OutputFormat(enum.Enum):
+    TEXT_ENVELOPE = "text-envelope"
+    BECH32 = "bech32"

cardano_clusterlib/helpers.py

@@ -14,10 +14,15 @@ def get_rand_str(length: int = 8) -> str:
     return "".join(random.choice(string.ascii_lowercase) for i in range(length))
 
 
+def read_from_file(file: itp.FileType) -> str:
+    """Read file content."""
+    with open(pl.Path(file).expanduser(), encoding="utf-8") as in_file:
+        return in_file.read()
+
+
 def read_address_from_file(addr_file: itp.FileType) -> str:
     """Read address stored in file."""
-    with open(pl.Path(addr_file).expanduser(), encoding="utf-8") as in_file:
-        return in_file.read().strip()
+    return read_from_file(file=addr_file).strip()
 
 
 def _prepend_flag(flag: str, contents: itp.UnpackableSequence) -> list[str]:

cardano_clusterlib/key_group.py

@@ -2,8 +2,10 @@
 
 import logging
 import pathlib as pl
+import typing as tp
 
 from cardano_clusterlib import clusterlib_helpers
+from cardano_clusterlib import consts
 from cardano_clusterlib import helpers
 from cardano_clusterlib import types as itp
 
@@ -82,5 +84,113 @@ def gen_non_extended_verification_key(
         helpers._check_outfiles(out_file)
         return out_file
 
+    def gen_mnemonic(
+        self,
+        size: tp.Literal[12, 15, 18, 21, 24],
+        out_file: itp.FileType = "",
+    ) -> list[str]:
+        """Generate a mnemonic sentence that can be used for key derivation.
+
+        Args:
+            size: Number of words in the mnemonic (12, 15, 18, 21, or 24).
+            out_file: A path to a file where the mnemonic will be stored (optional).
+
+        Returns:
+            list[str]: A list of words in the generated mnemonic.
+        """
+        out_args = []
+        if out_file:
+            clusterlib_helpers._check_files_exist(out_file, clusterlib_obj=self._clusterlib_obj)
+            out_args = ["--out-file", str(out_file)]
+
+        out = (
+            self._clusterlib_obj.cli(
+                [
+                    "key",
+                    "generate-mnemonic",
+                    *out_args,
+                    "--size",
+                    str(size),
+                ]
+            )
+            .stdout.strip()
+            .decode("ascii")
+        )
+
+        if out_file:
+            helpers._check_outfiles(out_file)
+            words = helpers.read_from_file(file=out_file).strip().split()
+        else:
+            words = out.split()
+
+        return words
+
+    def derive_from_mnemonic(
+        self,
+        key_name: str,
+        key_type: consts.KeyType,
+        mnemonic_file: itp.FileType,
+        account_number: int = 0,
+        key_number: int | None = None,
+        out_format: consts.OutputFormat = consts.OutputFormat.TEXT_ENVELOPE,
+        destination_dir: itp.FileType = ".",
+    ) -> pl.Path:
+        """Derive an extended signing key from a mnemonic sentence.
+
+        Args:
+            key_name: A name of the key.
+            key_type: A type of the key.
+            mnemonic_file: A path to a file containing the mnemonic sentence.
+            account_number: An account number (default is 0).
+            key_number: A key number (optional, required for payment and stake keys).
+            out_format: An output format (default is text-envelope).
+            destination_dir: A path to directory for storing artifacts (optional).
+
+        Returns:
+            Path: A path to the generated extended signing key file.
+        """
+        destination_dir = pl.Path(destination_dir).expanduser()
+        out_file = destination_dir / f"{key_name}.skey"
+        clusterlib_helpers._check_files_exist(out_file, clusterlib_obj=self._clusterlib_obj)
+
+        key_args = []
+        if key_type == consts.KeyType.DREP:
+            key_args.append("--drep-key")
+        elif key_type == consts.KeyType.CC_COLD:
+            key_args.append("--cc-cold-key")
+        elif key_type == consts.KeyType.CC_HOT:
+            key_args.append("--cc-hot-key")
+        elif key_type == consts.KeyType.PAYMENT:
+            if key_number is None:
+                err = "`key_number` must be specified when key_type is 'payment'"
+                raise ValueError(err)
+            key_args.extend(["--payment-key-with-number", str(key_number)])
+        elif key_type == consts.KeyType.STAKE:
+            if key_number is None:
+                err = "`key_number` must be specified when key_type is 'stake'"
+                raise ValueError(err)
+            key_args.extend(["--stake-key-with-number", str(key_number)])
+        else:
+            err = f"Unsupported key_type: {key_type}"
+            raise ValueError(err)
+
+        self._clusterlib_obj.cli(
+            [
+                "key",
+                "derive-from-mnemonic",
+                f"--key-output-{out_format.value}",
+                *key_args,
+                "--account-number",
+                str(account_number),
+                "--mnemonic-from-file",
+                str(mnemonic_file),
+                "--signing-key-file",
+                str(out_file),
+            ]
+        )
+
+        helpers._check_outfiles(out_file)
+        return out_file
+
     def __repr__(self) -> str:
         return f"<{self.__class__.__name__}: clusterlib_obj={id(self._clusterlib_obj)}>"