docs: added documentation for CIP-67 and CIP-68

Author: Cat-Treat

pycardano/cip/cip67.py

@@ -10,6 +10,17 @@ class InvalidCIP67Token(Exception):
 
 
 class CIP67TokenName(AssetName):
+    """Implementation of CIP67 token naming scheme.
+
+    This class enforces the CIP67 token naming format for Cardano native assets, requiring
+    a 4-byte token label with CRC8 checksum and brackets.
+
+    For more information:
+    https://github.com/cardano-foundation/CIPs/tree/master/CIP-0067
+
+    Args:
+        data: The token name as 'bytes', 'str', or 'AssetName'
+    """
     def __repr__(self):
         return f"{self.__class__.__name__}({self.payload})"
 

pycardano/cip/cip68.py

@@ -13,6 +13,17 @@ class InvalidCIP68ReferenceNFT(Exception):
 
 
 class CIP68TokenName(CIP67TokenName):
+    """Generates a CIP-68 reference token name from an input asset name.
+
+    The reference_token property generates a reference token name by slicing off the label
+    portion of the asset name and assigning the (100) label hex value.
+
+    For more information on CIP-68 labels:
+    https://github.com/cardano-foundation/CIPs/tree/master/CIP-0068
+
+    Args:
+        data: The token name as bytes, str, or AssetName
+    """
     @property
     def reference_token(self) -> "CIP68ReferenceNFTName":
         ref_token = self.payload.hex()[0] + "00643b" + self.payload.hex()[7:]
@@ -21,6 +32,7 @@ def reference_token(self) -> "CIP68ReferenceNFTName":
 
 
 class CIP68ReferenceNFTName(CIP68TokenName):
+    """Validates that an asset name has the 100 label for reference NFTs."""
     def __init__(self, data: Union[bytes, str, AssetName]):
         super().__init__(data)
 
@@ -29,6 +41,7 @@ def __init__(self, data: Union[bytes, str, AssetName]):
 
 
 class CIP68UserNFTName(CIP68TokenName):
+    """Validates that an asset name has the 222 label for NFTs."""
     def __init__(self, data: Union[bytes, str, AssetName]):
         super().__init__(data)
 
@@ -37,6 +50,10 @@ def __init__(self, data: Union[bytes, str, AssetName]):
 
 
 class CIP68UserNFTFiles(TypedDict, total=False):
+    """Multiple files may be included in metadata by using a list of dictionaries.
+    
+    Example:    files: [file_dict_1, file_dict_2]
+    """
     name: bytes
     mediaType: Required[bytes]
     src: Required[bytes]
@@ -50,6 +67,7 @@ class CIP68UserNFTMetadata(TypedDict, total=False):
 
 
 class CIP68UserFTName(CIP68TokenName):
+    """Validates that an asset name has the 333 label for FTs."""
     def __init__(self, data: Union[bytes, str, AssetName]):
         super().__init__(data)
 
@@ -67,6 +85,7 @@ class CIP68UserFTMetadata(TypedDict, total=False):
 
 
 class CIP68UserRFTName(CIP68TokenName):
+    """Validates that an asset name has the 444 label for RFTs."""
     def __init__(self, data: Union[bytes, str, AssetName]):
         super().__init__(data)
 
@@ -82,36 +101,54 @@ class CIP68UserRFTMetadata(TypedDict, total=False):
 
 @dataclass
 class CIP68Datum(PlutusData):
-    """Wrapper class for CIP-68 metadata to be used as inline datum"""
+    """Wrapper class for CIP-68 metadata to be used as inline datum.
+    
+    For detailed information on CIP-68 metadata structure and token types:
+    https://github.com/cardano-foundation/CIPs/tree/master/CIP-0068
+
+    This class wraps metadata dictionaries in a PlutusData class for attaching to a
+    reference NFT transaction as an inline datum.
+
+    Args:
+        metadata: A metadata dictionary. TypedDict classes are provided to define required
+            fields for each token type.
+        version: Metadata version number as 'int'
+        extra: Required - must be a PlutusData, or Unit() for empty PlutusData.
+
+    Example:
+        metadata = {
+            b"name": b"My NFT",
+            b"image": b"ipfs://...",
+            b"files": [{"mediaType": b"image/png", "src": b"ipfs://..."}]
+        }
+        datum = CIP68Datum(metadata=metadata, version=1, extra=Unit())
+    """
     CONSTR_ID = 0
 
     metadata: Dict[bytes, Any]
     version: int
     extra: Any      # This should be PlutusData or Unit() for empty PlutusData
 
     def __post_init__(self):
-        # Convert string keys to bytes in metadata
         converted_metadata: Dict[bytes, Any] = {}
         for k, v in self.metadata.items():
             key = k.encode() if isinstance(k, str) else k
-            # Handle nested dictionaries (like in files)
             if isinstance(v, dict):
                 v = dict((k.encode() if isinstance(k, str) else k, v) for k, v in v.items())
-            # Handle lists of dictionaries (allows multiple files)
             elif isinstance(v, list):
                 v = IndefiniteList([dict((k.encode() if isinstance(k, str) else k, v) for k, v in item.items())
                      if isinstance(item, dict) else item for item in v])
             converted_metadata[key] = v
         self.metadata = converted_metadata
 
     def to_shallow_primitive(self) -> CBORTag:
+        """Wraps PlutusData in 'extra' field in an indefinite list when converted to a CBOR primitive."""
         primitives: Primitive = super().to_shallow_primitive()
         if isinstance(primitives, CBORTag):
             value = primitives.value
             if value:
                 extra = value[2]
                 if isinstance(extra, Unit):
-                    # Convert Unit to CBORTag with IndefiniteList([])
                     extra = CBORTag(121, IndefiniteList([]))
                 elif isinstance(extra, CBORTag):
                     extra = CBORTag(extra.tag, IndefiniteList(extra.value))

test/pycardano/test_cip67.py

@@ -5,14 +5,14 @@
 
 
 @pytest.mark.parametrize("valid_token", [
-    ("000643b0617273656372797074", 100),  # Reference NFT with label 100
-    ("000643b04d7943617264", 100),        # Another reference NFT with label 100
-    ("000de1404d794e4654", 222),           # User NFT with label 222
-    ("000de140556e697175654e4654", 222),   # Another user NFT with label 222
-    ("0014df10546f6b656e31", 333),         # User FT with label 333
+    ("000643b0617273656372797074", 100),  # Reference NFTs with label 100
+    ("000643b04d7943617264", 100),
+    ("000de1404d794e4654", 222),           # NFTs with label 222
+    ("000de140556e697175654e4654", 222),
+    ("0014df10546f6b656e31", 333),         # FTs with label 333
     ("0014df10436f696e31", 333),
-    ('001bc280546f6b656e31', 444),          # RFT with label 444
-    ('001bc2804d7943617264', 444),          # User RFT with label 444
+    ('001bc280546f6b656e31', 444),          # RFTs with label 444
+    ('001bc2804d7943617264', 444),
 ])
 
 def test_CIP67_token_name_format(valid_token):
@@ -29,11 +29,11 @@ def test_CIP67_token_name_format(valid_token):
     "000643b0617273656372797074a", # Too long
 ])
 
-def test_invalid_token_name_format(invalid_token):
+def test_cip67_invalid_token_name_format(invalid_token):
     with pytest.raises((InvalidCIP67Token, IndexError, ValueError)):
         CIP67TokenName(invalid_token)
 
-def test_input_types():
+def test_cip67_input_types():
     token_str = "000643b0617273656372797074"
     CIP67TokenName(token_str)  # string input
     CIP67TokenName(bytes.fromhex(token_str))  # bytes input

test/pycardano/test_cip68.py

@@ -1,5 +1,4 @@
 import pytest
-from cbor2 import CBORTag
 from dataclasses import dataclass
 
 from pycardano.cip.cip68 import (
@@ -96,6 +95,9 @@ def test_cip68_multiple_files():
     assert b"mediaType" in datum.metadata[b"files"][1]
     assert b"src" in datum.metadata[b"files"][1]
     assert_roundtrip(datum)
+    restored = datum.from_cbor(datum.to_cbor_hex())
+    print(restored)
+    print(datum)
 
 
 def test_cip68_with_extra():
@@ -111,7 +113,7 @@ class CustomData(PlutusData):
         count: int
 
     extra_data = CustomData(value=b"test value", count=42)
-    
+
     datum_with_extra = CIP68Datum(
         metadata=metadata,
         version=1,