feat: add TextEnvelope class for JSON serialization and deserialization

Author: KINGH242

pycardano/serialization.py

@@ -2,6 +2,8 @@
 
 from __future__ import annotations
 
+import json
+import os
 import re
 import typing
 from collections import OrderedDict, UserList, defaultdict
@@ -45,7 +47,11 @@
 from frozenlist import FrozenList
 from pprintpp import pformat
 
-from pycardano.exception import DeserializeException, SerializeException
+from pycardano.exception import (
+    DeserializeException,
+    InvalidKeyTypeException,
+    SerializeException,
+)
 from pycardano.types import check_type, typechecked
 
 __all__ = [
@@ -63,6 +69,7 @@
     "OrderedSet",
     "NonEmptyOrderedSet",
     "CodedSerializable",
+    "TextEnvelope",
 ]
 
 T = TypeVar("T")
@@ -1142,3 +1149,98 @@ def from_primitive(
             raise DeserializeException(f"Invalid {cls.__name__} type {values[0]}")
         # Cast using Type[CodedSerializable] instead of cls directly
         return cast(Type[CodedSerializable], super()).from_primitive(values[1:])
+
+
+@dataclass(repr=False)
+class TextEnvelope(CBORSerializable):
+    """A base class for TextEnvelope types that can be saved and loaded as JSON."""
+
+    KEY_TYPE = ""
+    DESCRIPTION = ""
+
+    def __init__(
+        self,
+        payload: Optional[bytes] = None,
+        key_type: Optional[str] = None,
+        description: Optional[str] = None,
+    ):
+        self._payload = payload
+        self._key_type = key_type or self.KEY_TYPE
+        self._description = description or self.DESCRIPTION
+
+    @property
+    def payload(self) -> bytes:
+        if self._payload is None:
+            self._payload = self.to_cbor()
+        return self._payload
+
+    @property
+    def key_type(self) -> str:
+        return self._key_type
+
+    @property
+    def description(self) -> str:
+        return self._description
+
+    def to_json(self) -> str:
+        """Serialize the key to JSON.
+
+        The json output has three fields: "type", "description", and "cborHex".
+
+        Returns:
+            str: JSON representation of the key.
+        """
+        return json.dumps(
+            {
+                "type": self.key_type,
+                "description": self.description,
+                "cborHex": self.to_cbor_hex(),
+            }
+        )
+
+    @classmethod
+    def from_json(
+        cls: Type[TextEnvelope], data: str, validate_type=False
+    ) -> TextEnvelope:
+        """Restore a TextEnvelope from a JSON string.
+
+        Args:
+            data (str): JSON string.
+            validate_type (bool): Checks whether the type specified in json object is the same
+                as the class's default type.
+
+        Returns:
+            Key: The key restored from JSON.
+
+        Raises:
+            InvalidKeyTypeException: When `validate_type=True` and the type in json is not equal to the default type
+                of the Key class used.
+        """
+        obj = json.loads(data)
+
+        if validate_type and obj["type"] != cls.KEY_TYPE:
+            raise InvalidKeyTypeException(
+                f"Expect key type: {cls.KEY_TYPE}, got {obj['type']} instead."
+            )
+
+        k = cls.from_cbor(obj["cborHex"])
+
+        assert isinstance(k, cls)
+
+        k._key_type = obj["type"]
+        k._description = obj["description"]
+        k._payload = k.to_cbor()
+
+        return k
+
+    def save(self, path: str):
+        if os.path.isfile(path):
+            if os.stat(path).st_size > 0:
+                raise IOError(f"File {path} already exists!")
+        with open(path, "w") as f:
+            f.write(self.to_json())
+
+    @classmethod
+    def load(cls, path: str):
+        with open(path) as f:
+            return cls.from_json(f.read())

pycardano/transaction.py

@@ -39,6 +39,7 @@
     NonEmptyOrderedSet,
     OrderedSet,
     Primitive,
+    TextEnvelope,
     default_encoder,
     limit_primitive_type,
     list_hook,
@@ -685,7 +686,7 @@ def id(self) -> TransactionId:
 
 
 @dataclass(repr=False)
-class Transaction(ArrayCBORSerializable):
+class Transaction(ArrayCBORSerializable, TextEnvelope):
     transaction_body: TransactionBody
 
     transaction_witness_set: TransactionWitnessSet
@@ -694,6 +695,35 @@ class Transaction(ArrayCBORSerializable):
 
     auxiliary_data: Optional[AuxiliaryData] = None
 
+    def __init__(
+        self,
+        transaction_body: TransactionBody,
+        transaction_witness_set: TransactionWitnessSet,
+        valid: bool = True,
+        auxiliary_data: Optional[AuxiliaryData] = None,
+        payload: Optional[bytes] = None,
+        key_type: Optional[str] = None,
+        description: Optional[str] = None,
+    ):
+        self.transaction_body = transaction_body
+        self.transaction_witness_set = transaction_witness_set
+        self.valid = valid
+        self.auxiliary_data = auxiliary_data
+        ArrayCBORSerializable.__init__(self)
+        TextEnvelope.__init__(self, payload, key_type, description)
+
+    @property
+    def DESCRIPTION(self):
+        return "Ledger Cddl Format"
+
+    @property
+    def KEY_TYPE(self):
+        return (
+            "Unwitnessed Tx ConwayEra"
+            if self.transaction_witness_set.is_empty()
+            else "Signed Tx ConwayEra"
+        )
+
     @property
     def id(self) -> TransactionId:
         return self.transaction_body.id

pycardano/witness.py

@@ -18,6 +18,7 @@
     ArrayCBORSerializable,
     MapCBORSerializable,
     NonEmptyOrderedSet,
+    TextEnvelope,
     limit_primitive_type,
     list_hook,
 )
@@ -26,10 +27,26 @@
 
 
 @dataclass(repr=False)
-class VerificationKeyWitness(ArrayCBORSerializable):
+class VerificationKeyWitness(ArrayCBORSerializable, TextEnvelope):
     vkey: Union[VerificationKey, ExtendedVerificationKey]
     signature: bytes
 
+    KEY_TYPE = "TxWitness ConwayEra"
+    DESCRIPTION = "Key Witness ShelleyEra"
+
+    def __init__(
+        self,
+        vkey: Union[VerificationKey, ExtendedVerificationKey],
+        signature: bytes,
+        payload: Optional[bytes] = None,
+        key_type: Optional[str] = None,
+        description: Optional[str] = None,
+    ):
+        self.vkey = vkey
+        self.signature = signature
+        ArrayCBORSerializable.__init__(self)
+        TextEnvelope.__init__(self, payload, key_type, description)
+
     def __post_init__(self):
         # When vkey is in extended format, we need to convert it to non-extended, so it can match the
         # key hash of the input address we are trying to spend.
@@ -46,6 +63,19 @@ def from_primitive(
             signature=values[1],
         )
 
+    def to_shallow_primitive(self) -> Union[list, tuple]:
+        """Convert to a shallow primitive representation."""
+        return [self.vkey.to_primitive(), self.signature]
+
+    def __eq__(self, other):
+        if not isinstance(other, VerificationKeyWitness):
+            return False
+        else:
+            return (
+                self.vkey.payload == other.vkey.payload
+                and self.signature == other.signature
+            )
+
 
 @dataclass(repr=False)
 class TransactionWitnessSet(MapCBORSerializable):
@@ -126,3 +156,16 @@ def __post_init__(self):
             self.plutus_v2_script = NonEmptyOrderedSet(self.plutus_v2_script)
         if isinstance(self.plutus_v3_script, list):
             self.plutus_v3_script = NonEmptyOrderedSet(self.plutus_v3_script)
+
+    def is_empty(self) -> bool:
+        """Check if the witness set is empty."""
+        return (
+            not self.vkey_witnesses
+            and not self.native_scripts
+            and not self.bootstrap_witness
+            and not self.plutus_v1_script
+            and not self.plutus_data
+            and not self.redeemer
+            and not self.plutus_v2_script
+            and not self.plutus_v3_script
+        )