WIP: CIP67 and CIP68 Support

pycardano/cip/cip67.py

@@ -0,0 +1,53 @@
+from typing import Union
+
+from crc8 import crc8
+
+from pycardano.transaction import AssetName
+
+
+class InvalidCIP67Token(Exception):
+    pass
+
+
+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})"
+
+    def __init__(self, data: Union[bytes, str, AssetName]):
+        if isinstance(data, AssetName):
+            data = data.payload
+
+        if isinstance(data, bytes):
+            data = data.hex()
+
+        if data[0] != "0" or data[7] != "0":
+            raise InvalidCIP67Token(
+                "The first and eighth hex values must be 0. Instead found:\n"
+                + f"first={data[0]}\n"
+                + f"eigth={data[7]}"
+            )
+
+        checksum = crc8(bytes.fromhex(data[1:5])).hexdigest()
+        if data[5:7] != checksum:
+            raise InvalidCIP67Token(
+                f"Token label {data[1:5]} does not match token checksum.\n"
+                + f"expected={checksum}\n"
+                + f"received={data[5:7]}"
+            )
+
+        super().__init__(bytes.fromhex(data))
+
+    @property
+    def label(self) -> int:
+        return int.from_bytes(self.payload[:3], "big") >> 4

pycardano/cip/cip68.py

@@ -0,0 +1,159 @@
+from typing import Union, Dict, List, Any, TypedDict, Required
+from dataclasses import dataclass
+from cbor2 import CBORTag
+
+from pycardano.cip.cip67 import CIP67TokenName
+from pycardano.plutus import PlutusData, Unit, Primitive
+from pycardano.transaction import AssetName
+from pycardano.serialization import IndefiniteList
+
+
+class InvalidCIP68ReferenceNFT(Exception):
+    pass
+
+
+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:]
+
+        return CIP68ReferenceNFTName(ref_token)
+
+
+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)
+
+        if self.label != 100:
+            raise InvalidCIP68ReferenceNFT("Reference NFT must have label 100.")
+
+
+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)
+
+        if self.label != 222:
+            raise InvalidCIP68ReferenceNFT("User NFT must have label 222.")
+
+
+class CIP68UserNFTFile(TypedDict, total=False):
+    """Metadata for a single file in NFT metadata."""
+    name: bytes
+    mediaType: Required[bytes]
+    src: Required[bytes]
+
+
+class CIP68UserNFTMetadata(TypedDict, total=False):
+    """Metadata for a user NFT.
+
+    Multiple files can be included as a list of dictionaries or CIP68UserNFTFile objects.
+    """
+    name: Required[bytes]
+    image: Required[bytes]
+    description: bytes
+    files: Union[List[CIP68UserNFTFile], None]
+
+
+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)
+
+        if self.label != 333:
+            raise InvalidCIP68ReferenceNFT("User NFT must have label 333.")
+
+
+class CIP68UserFTMetadata(TypedDict, total=False):
+    name: Required[bytes]
+    description: Required[bytes]
+    ticker: bytes
+    url: bytes
+    logo: bytes
+    decimals: int
+
+
+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)
+
+        if self.label != 444:
+            raise InvalidCIP68ReferenceNFT("User NFT must have label 444.")
+
+
+class CIP68UserRFTMetadata(TypedDict, total=False):
+    name: Required[bytes]
+    image: Required[bytes]
+    description: bytes
+
+
+@dataclass
+class CIP68Datum(PlutusData):
+    """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):
+        converted_metadata: Dict[bytes, Any] = {}
+        for k, v in self.metadata.items():
+            key = k.encode() if isinstance(k, str) else k
+            if isinstance(v, dict):
+                v = dict((k.encode() if isinstance(k, str) else k, v) for k, v in v.items())
+            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):
+                    extra = CBORTag(121, IndefiniteList([]))
+                elif isinstance(extra, CBORTag):
+                    extra = CBORTag(extra.tag, IndefiniteList(extra.value))
+                value = [value[0], value[1], extra]
+        return CBORTag(121, value)
+
+

test/pycardano/test_cip67.py

@@ -0,0 +1,63 @@
+import pytest
+
+from pycardano.cip.cip67 import CIP67TokenName, InvalidCIP67Token
+from pycardano.transaction import AssetName, Value, MultiAsset, Asset
+from pycardano.hash import ScriptHash
+
+
+@pytest.mark.parametrize("token_data", [
+    # Valid tokens
+    ("000643b0617273656372797074", 100),  # Reference NFT with label 100
+    ("000de1404d794e4654", 222),  # NFT with label 222
+    ("0014df10546f6b656e31", 333),  # FT with label 333
+    ("001bc280546f6b656e31", 444),  # RFT with label 444
+    # Invalid tokens
+    pytest.param(
+        ("100643b0617273656372797074", None),  # Invalid first hex
+        marks=pytest.mark.xfail(raises=InvalidCIP67Token),
+        id="invalid_first_hex"
+    ),
+    pytest.param(
+        ("000643b1617273656372797074", None),  # Invalid last hex
+        marks=pytest.mark.xfail(raises=InvalidCIP67Token),
+        id="invalid_last_hex"
+    ),
+    pytest.param(
+        ("00064300617273656372797074", None),  # Invalid checksum
+        marks=pytest.mark.xfail(raises=InvalidCIP67Token),
+        id="invalid_checksum"
+    ),
+    pytest.param(
+        ("000643b", None),  # Too short
+        marks=pytest.mark.xfail(raises=(InvalidCIP67Token, IndexError)),
+        id="too_short"
+    ),
+])
+def test_cip67_token_name_format(token_data):
+    token_str, expected_label = token_data
+    # Create a Value object with asset names and dummy policyID
+    policy = ScriptHash.from_primitive("00000000000000000000000000000000000000000000000000000000")
+    asset = Asset()
+    asset[AssetName(token_str)] = 1
+    multi_asset = MultiAsset()
+    multi_asset[policy] = asset
+    value = Value(0, multi_asset)
+    # Extract the AssetName from the Value object and create CIP67TokenName
+    token_name = next(iter(next(iter(value.multi_asset.values())).keys()))
+    token = CIP67TokenName(token_name)
+
+    if expected_label is not None:
+        assert token.label == expected_label
+
+
+def test_cip67_input_types():
+    token_str = "000643b0617273656372797074"
+    CIP67TokenName(token_str)  # string input
+    CIP67TokenName(bytes.fromhex(token_str))  # bytes input
+    CIP67TokenName(AssetName(bytes.fromhex(token_str)))  # AssetName input
+
+    with pytest.raises(TypeError):
+        CIP67TokenName(123)  # int input should fail
+    with pytest.raises(TypeError):
+        CIP67TokenName(None)
+