Merge pull request #28 from chainxlab/itsm3abena/docs-ecc

Itsm3abena/docs ecc
talonlab · Jul 18, 2024 · 386af5f · 386af5f
2 parents 962547d + 94eaadb
commit 386af5f
Show file tree

Hide file tree

Showing 23 changed files with 458 additions and 664 deletions.
diff --git a/docs/ecc.rst b/docs/ecc.rst
@@ -7,72 +7,240 @@ Elliptic Curve Cryptography (ECC)
 
 .. autoclass:: hdwallet.ecc.kholaw.ed25519.point.KholawEd25519Point
     :members:
-    :inherited-members:
 
 .. autoclass:: hdwallet.ecc.kholaw.ed25519.private_key.KholawEd25519PrivateKey
     :members:
-    :inherited-members:
+
+>>> from hdwallet.ecc.kholaw.ed25519.private_key import KholawEd25519PrivateKey
+>>> from hdwallet.utils import get_bytes
+>>> KholawEd25519PrivateKey.name()
+'Kholaw-Ed25519'
+>>> KholawEd25519PrivateKey.length()
+64
+>>> private_key = KholawEd25519PrivateKey.from_bytes(
+...     get_bytes("8061879a8fc9e7c685cb89b7014c85a6c4a2a8f3b6fa4964381d0751baf8fb5ff97530b002426a6eb1308e01372905d4c19c2b52a939bccd24c99a5826b9f87c")
+... )
+>>> private_key.raw().hex()
+'8061879a8fc9e7c685cb89b7014c85a6c4a2a8f3b6fa4964381d0751baf8fb5ff97530b002426a6eb1308e01372905d4c19c2b52a939bccd24c99a5826b9f87c'
+>>> private_key.public_key().raw_compressed().hex()
+'00e55487c92c1913439f336b1b2dc316da6e88c02a157208f98781494b87f27eb8'
+>>> private_key.public_key().raw_uncompressed().hex()
+'00e55487c92c1913439f336b1b2dc316da6e88c02a157208f98781494b87f27eb8'
+
 
 .. autoclass:: hdwallet.ecc.kholaw.ed25519.public_key.KholawEd25519PublicKey
     :members:
-    :inherited-members:
+
+>>> from hdwallet.ecc.kholaw.ed25519 import KholawEd25519PublicKey
+>>> from hdwallet.utils import get_bytes
+>>> KholawEd25519PublicKey.name()
+'Kholaw-Ed25519'
+>>> public_key = KholawEd25519PublicKey.from_bytes(
+...     get_bytes("00e55487c92c1913439f336b1b2dc316da6e88c02a157208f98781494b87f27eb8")
+... )
+>>> public_key.raw_compressed().hex()
+'00e55487c92c1913439f336b1b2dc316da6e88c02a157208f98781494b87f27eb8'
+>>> public_key.point().raw_encoded().hex()
+'e55487c92c1913439f336b1b2dc316da6e88c02a157208f98781494b87f27eb8'
+>>> public_key.point().x()
+18529038270296824438026848489315401829943202020841826252456650783397010322849
+
 
 .. autoclass:: hdwallet.ecc.slip10.ed25519.blake2b.point.SLIP10Ed25519Blake2bPoint
     :members:
-    :inherited-members:
 
 .. autoclass:: hdwallet.ecc.slip10.ed25519.blake2b.private_key.SLIP10Ed25519Blake2bPrivateKey
     :members:
-    :inherited-members:
+
+>>> from hdwallet.ecc.slip10.ed25519.blake2b import SLIP10Ed25519Blake2bPrivateKey
+>>> from hdwallet.utils import get_bytes
+>>> SLIP10Ed25519Blake2bPrivateKey.name()
+'SLIP10-Ed25519-Blake2b'
+>>> SLIP10Ed25519Blake2bPrivateKey.length()
+32
+>>> private_key = SLIP10Ed25519Blake2bPrivateKey.from_bytes(
+...     get_bytes("bb37794073e5094ebbfcfa070e9254fe6094b56e7cccb094a2304c5eccccdc07")
+... )
+>>> private_key.raw().hex()
+'bb37794073e5094ebbfcfa070e9254fe6094b56e7cccb094a2304c5eccccdc07'
+>>> private_key.public_key().raw_compressed().hex()
+'006aea61eeed872052377ab16b0fc5d9b9f142be59ac1488e6610645dedb4da45c'
+>>> private_key.public_key().raw_uncompressed().hex()
+'006aea61eeed872052377ab16b0fc5d9b9f142be59ac1488e6610645dedb4da45c'
+
 
 .. autoclass:: hdwallet.ecc.slip10.ed25519.blake2b.public_key.SLIP10Ed25519Blake2bPublicKey
     :members:
-    :inherited-members:
+
+>>> from hdwallet.ecc.slip10.ed25519.blake2b import SLIP10Ed25519Blake2bPublicKey
+>>> from hdwallet.utils import get_bytes
+>>> SLIP10Ed25519Blake2bPublicKey.name()
+'SLIP10-Ed25519-Blake2b'
+>>> public_key = SLIP10Ed25519Blake2bPublicKey.from_bytes(
+...     get_bytes("00d14696583ee9144878635b557d515a502b04366818dfe7765737746b4f57978d")
+... )
+>>> public_key.raw_compressed().hex()
+'00d14696583ee9144878635b557d515a502b04366818dfe7765737746b4f57978d'
+>>> public_key.point().raw_encoded().hex()
+'d14696583ee9144878635b557d515a502b04366818dfe7765737746b4f57978d'
+>>> public_key.point().x()
+35008547582340824597639173221735807482318787407965447203743372716499096148063
+
 
 .. autoclass:: hdwallet.ecc.slip10.ed25519.monero.point.SLIP10Ed25519MoneroPoint
     :members:
-    :inherited-members:
 
 .. autoclass:: hdwallet.ecc.slip10.ed25519.monero.private_key.SLIP10Ed25519MoneroPrivateKey
     :members:
-    :inherited-members:
+
+>>> from hdwallet.ecc.slip10.ed25519.monero import SLIP10Ed25519MoneroPrivateKey
+>>> from hdwallet.utils import get_bytes
+>>> SLIP10Ed25519MoneroPrivateKey.name()
+'SLIP10-Ed25519-Monero'
+>>> SLIP10Ed25519MoneroPrivateKey.length()
+32
+>>> private_key = SLIP10Ed25519MoneroPrivateKey.from_bytes(
+...     get_bytes("bb37794073e5094ebbfcfa070e9254fe6094b56e7cccb094a2304c5eccccdc07")
+... )
+>>> private_key.raw().hex()
+'bb37794073e5094ebbfcfa070e9254fe6094b56e7cccb094a2304c5eccccdc07'
+>>> private_key.public_key().raw_compressed().hex()
+'628247d3de93857cdd360fee4aef9a67ecfebedfe8eaec9cf6be35eacc895ca7'
+>>> private_key.public_key().raw_uncompressed().hex()
+'628247d3de93857cdd360fee4aef9a67ecfebedfe8eaec9cf6be35eacc895ca7'
+
 
 .. autoclass:: hdwallet.ecc.slip10.ed25519.monero.public_key.SLIP10Ed25519MoneroPublicKey
     :members:
-    :inherited-members:
+
+>>> from hdwallet.ecc.slip10.ed25519.monero import SLIP10Ed25519MoneroPublicKey
+>>> from hdwallet.utils import get_bytes
+>>> SLIP10Ed25519MoneroPublicKey.name()
+'SLIP10-Ed25519-Monero'
+>>> public_key = SLIP10Ed25519MoneroPublicKey.from_bytes(
+...     get_bytes("628247d3de93857cdd360fee4aef9a67ecfebedfe8eaec9cf6be35eacc895ca7")
+... )
+>>> public_key.raw_compressed().hex()
+'628247d3de93857cdd360fee4aef9a67ecfebedfe8eaec9cf6be35eacc895ca7'
+>>> public_key.point().raw_encoded().hex()
+'628247d3de93857cdd360fee4aef9a67ecfebedfe8eaec9cf6be35eacc895ca7'
+>>> public_key.point().x()
+29078407399097928298542937704975150613766572636435642857509307729044618011935
+
 
 .. autoclass:: hdwallet.ecc.slip10.ed25519.point.SLIP10Ed25519Point
     :members:
-    :inherited-members:
 
 .. autoclass:: hdwallet.ecc.slip10.ed25519.private_key.SLIP10Ed25519PrivateKey
     :members:
-    :inherited-members:
+
+>>> from hdwallet.ecc.slip10.ed25519.private_key import SLIP10Ed25519PrivateKey
+>>> from hdwallet.utils import get_bytes
+>>> SLIP10Ed25519PrivateKey.name()
+'SLIP10-Ed25519'
+>>> SLIP10Ed25519PrivateKey.length()
+32
+>>> private_key = SLIP10Ed25519PrivateKey.from_bytes(
+...     get_bytes("bb37794073e5094ebbfcfa070e9254fe6094b56e7cccb094a2304c5eccccdc07")
+... )
+>>> private_key.raw().hex()
+'bb37794073e5094ebbfcfa070e9254fe6094b56e7cccb094a2304c5eccccdc07'
+>>> private_key.public_key().raw_compressed().hex()
+'00d14696583ee9144878635b557d515a502b04366818dfe7765737746b4f57978d'
+>>> private_key.public_key().raw_uncompressed().hex()
+'00d14696583ee9144878635b557d515a502b04366818dfe7765737746b4f57978d'
 
 .. autoclass:: hdwallet.ecc.slip10.ed25519.public_key.SLIP10Ed25519PublicKey
     :members:
-    :inherited-members:
+
+>>> from hdwallet.ecc.slip10.ed25519.public_key import SLIP10Ed25519PublicKey
+>>> from hdwallet.utils import get_bytes
+>>> SLIP10Ed25519PublicKey.name()
+'SLIP10-Ed25519'
+>>> public_key = SLIP10Ed25519PublicKey.from_bytes(
+...     get_bytes("00d14696583ee9144878635b557d515a502b04366818dfe7765737746b4f57978d")
+... )
+>>> public_key.raw_compressed().hex()
+'00d14696583ee9144878635b557d515a502b04366818dfe7765737746b4f57978d'
+>>> public_key.point().raw_encoded().hex()
+'d14696583ee9144878635b557d515a502b04366818dfe7765737746b4f57978d'
+>>> public_key.point().x()
+35008547582340824597639173221735807482318787407965447203743372716499096148063
 
 .. autoclass:: hdwallet.ecc.slip10.nist256p1.point.SLIP10Nist256p1Point
     :members:
-    :inherited-members:
 
 .. autoclass:: hdwallet.ecc.slip10.nist256p1.private_key.SLIP10Nist256p1PrivateKey
     :members:
-    :inherited-members:
+
+>>> from hdwallet.ecc.slip10.nist256p1.private_key import SLIP10Nist256p1PrivateKey
+>>> from hdwallet.utils import get_bytes
+>>> SLIP10Nist256p1PrivateKey.name()
+'SLIP10-Nist256p1'
+>>> SLIP10Nist256p1PrivateKey.length()
+32
+>>> private_key = SLIP10Nist256p1PrivateKey.from_bytes(
+...     get_bytes("f79495fda777197ce73551bcd8e162ceca19167575760d3cc2bced4bf2a213dc")
+... )
+>>> private_key.raw().hex()
+'f79495fda777197ce73551bcd8e162ceca19167575760d3cc2bced4bf2a213dc'
+>>> private_key.public_key().raw_compressed().hex()
+'02e4bd97a82a8f3e575a9a35b7cca19cd730addd499a2bd4e9a9811df8bfc35e51'
+>>> private_key.public_key().raw_uncompressed().hex()
+'04e4bd97a82a8f3e575a9a35b7cca19cd730addd499a2bd4e9a9811df8bfc35e51c68c3bed41d47d4d05ae880250e4432cc6480b417597f1cffc5ed7d28991d164'
 
 .. autoclass:: hdwallet.ecc.slip10.nist256p1.public_key.SLIP10Nist256p1PublicKey
     :members:
-    :inherited-members:
+
+>>> from hdwallet.ecc.slip10.nist256p1.public_key import SLIP10Nist256p1PublicKey
+>>> from hdwallet.utils import get_bytes
+>>> SLIP10Nist256p1PublicKey.name()
+'SLIP10-Nist256p1'
+>>> public_key = SLIP10Nist256p1PublicKey.from_bytes(
+...     get_bytes("02e4bd97a82a8f3e575a9a35b7cca19cd730addd499a2bd4e9a9811df8bfc35e51")
+... )
+>>> public_key.raw_compressed().hex()
+'02e4bd97a82a8f3e575a9a35b7cca19cd730addd499a2bd4e9a9811df8bfc35e51'
+>>> public_key.point().raw_encoded().hex()
+'02e4bd97a82a8f3e575a9a35b7cca19cd730addd499a2bd4e9a9811df8bfc35e51'
+>>> public_key.point().x()
+103462310269679299860340333843259692621316029910306332627414876684344367472209
 
 .. autoclass:: hdwallet.ecc.slip10.secp256k1.point.SLIP10Secp256k1PointCoincurve
     :members:
-    :inherited-members:
 
 .. autoclass:: hdwallet.ecc.slip10.secp256k1.private_key.SLIP10Secp256k1PrivateKeyCoincurve
     :members:
-    :inherited-members:
+
+>>> from hdwallet.ecc.slip10.secp256k1.private_key import SLIP10Secp256k1PrivateKeyCoincurve
+>>> from hdwallet.utils import get_bytes
+>>> SLIP10Secp256k1PrivateKeyCoincurve.name()
+'SLIP10-Secp256k1'
+>>> SLIP10Secp256k1PrivateKeyCoincurve.length()
+32
+>>> private_key = SLIP10Secp256k1PrivateKeyCoincurve.from_bytes(
+...     get_bytes("b66022fff8b6322f8b8fa444d6d097457b6b9e7bb05add5b75f9c827df7bd3b6")
+... )
+>>> private_key.raw().hex()
+'b66022fff8b6322f8b8fa444d6d097457b6b9e7bb05add5b75f9c827df7bd3b6'
+>>> private_key.public_key().raw_compressed().hex()
+'0374a436044b4904bbd7a074b098d65fad39fc5b66f28da8440f10dbcf86568429'
+>>> private_key.public_key().raw_uncompressed().hex()
+'0474a436044b4904bbd7a074b098d65fad39fc5b66f28da8440f10dbcf86568429aae5b09b4de9cee5d2f9f98044f688aa98f910134a8e87eff28ec5ba35ddf273'
 
 .. autoclass:: hdwallet.ecc.slip10.secp256k1.public_key.SLIP10Secp256k1PublicKeyCoincurve
     :members:
-    :inherited-members:
+
+>>> from hdwallet.ecc.slip10.secp256k1.public_key import SLIP10Secp256k1PublicKeyCoincurve
+>>> from hdwallet.utils import get_bytes
+>>> SLIP10Secp256k1PublicKeyCoincurve.name()
+'SLIP10-Secp256k1'
+>>> public_key = SLIP10Secp256k1PublicKeyCoincurve.from_bytes(
+...     get_bytes("0374a436044b4904bbd7a074b098d65fad39fc5b66f28da8440f10dbcf86568429")
+... )
+>>> public_key.raw_compressed().hex()
+'0374a436044b4904bbd7a074b098d65fad39fc5b66f28da8440f10dbcf86568429'
+>>> public_key.point().raw_encoded().hex()
+'0374a436044b4904bbd7a074b098d65fad39fc5b66f28da8440f10dbcf86568429'
+>>> public_key.point().x()
+52758426164353529380574599868388529660378638078403259786555024244882051335209
diff --git a/hdwallet/ecc/__init__.py b/hdwallet/ecc/__init__.py
@@ -26,6 +26,29 @@
 
 
 class ECCS:
+    """
+    A class that manages a dictionary of ecc classes.
+
+    This class provides methods to retrieve names and classes of various entropy implementations,
+    as well as methods to validate and access specific ecc classes by name.
+
+    Here are available ecc names and classes:
+    +--------------------------+--------------------------------------------------------------------------+
+    | Name                     | Class                                                                    |
+    +==========================+==========================================================================+
+    | KholawEd25519ECC         | <class 'hdwallet.ecc.kholaw.ed25519.KholawEd25519ECC'>                   |
+    +--------------------------+--------------------------------------------------------------------------+
+    | SLIP10Ed25519ECC         |  <class 'hdwallet.ecc.slip10.ed25519.SLIP10Ed25519ECC'>                  |
+    +--------------------------+--------------------------------------------------------------------------+
+    | SLIP10Ed25519Blake2bECC  |  <class 'hdwallet.ecc.slip10.ed25519.blake2b.SLIP10Ed25519Blake2bECC'>   |
+    +--------------------------+--------------------------------------------------------------------------+
+    | SLIP10Ed25519MoneroECC   | <class 'hdwallet.ecc.slip10.ed25519.monero.SLIP10Ed25519MoneroECC'>      |
+    +--------------------------+--------------------------------------------------------------------------+
+    | SLIP10Nist256p1ECC       | <class 'hdwallet.ecc.slip10.nist256p1.SLIP10Nist256p1ECC'>               |
+    +--------------------------+--------------------------------------------------------------------------+
+    | SLIP10Secp256k1ECC       | <class 'hdwallet.ecc.slip10.secp256k1.SLIP10Secp256k1ECCCoincurve'>      |
+    +--------------------------+--------------------------------------------------------------------------+
+    """
 
     dictionary: Dict[str, Type[IEllipticCurveCryptography]] = {
         KholawEd25519ECC.NAME: KholawEd25519ECC,
@@ -38,14 +61,37 @@ class ECCS:
 
     @classmethod
     def names(cls) -> List[str]:
+        """
+        Get the names from the class's dictionary.
+
+        :return: A list of names stored as keys in the `dictionary`.
+        :rtype: List[str]
+        """
+
         return list(cls.dictionary.keys())
 
     @classmethod
     def classes(cls) -> List[Type[IEllipticCurveCryptography]]:
+        """
+        Get the list of elliptic curve cryptography (ECC) classes from the class's dictionary.
+
+        :return: A list of ECC classes stored as values in the `dictionary`.
+        :rtype: List[Type[IEllipticCurveCryptography]]
+        """
+
         return list(cls.dictionary.values())
 
     @classmethod
     def ecc(cls, name: str) -> Type[IEllipticCurveCryptography]:
+        """
+        Retrieve an elliptic curve cryptography (ECC) class by name.
+
+        :param name: The name of the ECC class to retrieve.
+        :type name: str
+
+        :return: The ECC class corresponding to the given name.
+        :rtype: Type[IEllipticCurveCryptography]
+        """
 
         if not cls.is_ecc(name=name):
             raise ECCError(
@@ -56,12 +102,33 @@ def ecc(cls, name: str) -> Type[IEllipticCurveCryptography]:
 
     @classmethod
     def is_ecc(cls, name: str) -> bool:
+        """
+        Check if the given name is a valid ECC class name.
+
+        :param name: The name to check.
+        :type name: str
+
+        :return: True if the name is a valid ECC class name, False otherwise.
+        :rtype: bool
+        """
+
         return name in cls.names()
 
 
 def validate_and_get_public_key(
     public_key: Union[bytes, str, IPublicKey], public_key_cls: Type[IPublicKey]
 ) -> IPublicKey:
+    """
+    Validate and convert the input to an IPublicKey instance.
+
+    :param public_key: The public key to validate and convert. It can be of type bytes, str, or IPublicKey.
+    :type public_key: Union[bytes, str, IPublicKey]
+    :param public_key_cls: The class to use for creating an IPublicKey instance from bytes.
+    :type public_key_cls: Type[IPublicKey]
+
+    :return: A valid IPublicKey instance.
+    :rtype: IPublicKey
+    """
     if isinstance(public_key, bytes):
         public_key: IPublicKey = public_key_cls.from_bytes(public_key)
     elif isinstance(public_key, str):