feat(Group): add contract-level validations for addIp and removeIp

- addIp: validate groupId/ipIds not disputed, ipIds not registered groups
  - DisputeModuleClient.isIpTagged, IPAssetRegistryClient.isRegisteredGroup
- removeIp: validate group not frozen (no derivative IPs, no minted license tokens)
  - LicenseRegistryClient.hasDerivativeIps, LicenseTokenClient.getTotalTokensByLicensor
- Add LicenseTokenClient and DisputeModuleClient to Group
- Unit tests for new validations

Author: chao-peng-story

src/story_protocol_python_sdk/abi/DisputeModule/DisputeModule_client.py

@@ -71,5 +71,8 @@ def build_tagIfRelatedIpInfringed_transaction(
             ipIdToTag, infringerDisputeId
         ).build_transaction(tx_params)
 
+    def isIpTagged(self, ipId):
+        return self.contract.functions.isIpTagged(ipId).call()
+
     def isWhitelistedDisputeTag(self, tag):
         return self.contract.functions.isWhitelistedDisputeTag(tag).call()

src/story_protocol_python_sdk/abi/IPAssetRegistry/IPAssetRegistry_client.py

@@ -51,3 +51,6 @@ def ipId(self, chainId, tokenContract, tokenId):
 
     def isRegistered(self, id):
         return self.contract.functions.isRegistered(id).call()
+
+    def isRegisteredGroup(self, groupId):
+        return self.contract.functions.isRegisteredGroup(groupId).call()

src/story_protocol_python_sdk/abi/LicenseRegistry/LicenseRegistry_client.py

@@ -49,6 +49,9 @@ def getRoyaltyPercent(self, ipId, licenseTemplate, licenseTermsId):
             ipId, licenseTemplate, licenseTermsId
         ).call()
 
+    def hasDerivativeIps(self, parentIpId):
+        return self.contract.functions.hasDerivativeIps(parentIpId).call()
+
     def hasIpAttachedLicenseTerms(self, ipId, licenseTemplate, licenseTermsId):
         return self.contract.functions.hasIpAttachedLicenseTerms(
             ipId, licenseTemplate, licenseTermsId

src/story_protocol_python_sdk/abi/LicenseToken/LicenseToken_client.py

@@ -31,5 +31,10 @@ def __init__(self, web3: Web3):
             abi = json.load(abi_file)
         self.contract = self.web3.eth.contract(address=contract_address, abi=abi)
 
+    def getTotalTokensByLicensor(self, licensorIpId):
+        return self.contract.functions.getTotalTokensByLicensor(
+            licensorIpId
+        ).call()
+
     def ownerOf(self, tokenId):
         return self.contract.functions.ownerOf(tokenId).call()

src/story_protocol_python_sdk/resources/Group.py

@@ -4,6 +4,9 @@
 from story_protocol_python_sdk.abi.CoreMetadataModule.CoreMetadataModule_client import (
     CoreMetadataModuleClient,
 )
+from story_protocol_python_sdk.abi.DisputeModule.DisputeModule_client import (
+    DisputeModuleClient,
+)
 from story_protocol_python_sdk.abi.GroupingModule.GroupingModule_client import (
     GroupingModuleClient,
 )
@@ -19,6 +22,9 @@
 from story_protocol_python_sdk.abi.LicenseRegistry.LicenseRegistry_client import (
     LicenseRegistryClient,
 )
+from story_protocol_python_sdk.abi.LicenseToken.LicenseToken_client import (
+    LicenseTokenClient,
+)
 from story_protocol_python_sdk.abi.LicensingModule.LicensingModule_client import (
     LicensingModuleClient,
 )
@@ -58,9 +64,11 @@ def __init__(self, web3: Web3, account, chain_id: int):
         self.grouping_module_client = GroupingModuleClient(web3)
         self.grouping_workflows_client = GroupingWorkflowsClient(web3)
         self.ip_asset_registry_client = IPAssetRegistryClient(web3)
+        self.dispute_module_client = DisputeModuleClient(web3)
         self.core_metadata_module_client = CoreMetadataModuleClient(web3)
         self.licensing_module_client = LicensingModuleClient(web3)
         self.license_registry_client = LicenseRegistryClient(web3)
+        self.license_token_client = LicenseTokenClient(web3)
         self.pi_license_template_client = PILicenseTemplateClient(web3)
         self.module_registry_client = ModuleRegistryClient(web3)
         self.sign_util = Sign(web3, self.chain_id, self.account)
@@ -477,6 +485,23 @@ def add_ips_to_group(
                 if not self.web3.is_address(ip_id):
                     raise ValueError(f'IP ID "{ip_id}" is invalid.')
 
+            # Contract-level validation: groupId must not be disputed
+            if self.dispute_module_client.isIpTagged(group_ip_id):
+                raise ValueError(
+                    f'Disputed group cannot add IP: group "{group_ip_id}" is tagged by dispute module.'
+                )
+
+            # Contract-level validation: ipIds must not contain disputed IPs or groups
+            for ip_id in ip_ids:
+                if self.dispute_module_client.isIpTagged(ip_id):
+                    raise ValueError(
+                        f'Cannot add disputed IP to group: IP "{ip_id}" is tagged by dispute module.'
+                    )
+                if self.ip_asset_registry_client.isRegisteredGroup(ip_id):
+                    raise ValueError(
+                        f'Cannot add group to group: IP "{ip_id}" is a registered group.'
+                    )
+
             max_allowed_reward_share = get_revenue_share(
                 max_allowed_reward_share_percentage,
                 type=RevShareType.MAX_ALLOWED_REWARD_SHARE,
@@ -522,6 +547,18 @@ def remove_ips_from_group(
                 if not self.web3.is_address(ip_id):
                     raise ValueError(f'IP ID "{ip_id}" is invalid.')
 
+            # Contract-level validation: group must not have derivative IPs
+            if self.license_registry_client.hasDerivativeIps(group_ip_id):
+                raise ValueError(
+                    f'Group frozen: group "{group_ip_id}" has derivative IPs and cannot remove members.'
+                )
+
+            # Contract-level validation: group must not have minted license tokens
+            if self.license_token_client.getTotalTokensByLicensor(group_ip_id) > 0:
+                raise ValueError(
+                    f'Group frozen: group "{group_ip_id}" has already minted license tokens and cannot remove members.'
+                )
+
             response = build_and_send_transaction(
                 self.web3,
                 self.account,

tests/unit/resources/test_group.py

@@ -456,14 +456,95 @@ def test_add_ips_to_group_invalid_ip_id(self, group: Group, mock_web3):
                     ip_ids=[invalid_ip_id],
                 )
 
+    def test_add_ips_to_group_max_reward_share_exceeds_100(
+        self, group: Group, mock_web3_is_address
+    ):
+        """Test add_ips_to_group rejects max_allowed_reward_share_percentage > 100 (via get_revenue_share)."""
+        with mock_web3_is_address():
+            with patch.object(
+                group.dispute_module_client, "isIpTagged", return_value=False
+            ), patch.object(
+                group.ip_asset_registry_client,
+                "isRegisteredGroup",
+                return_value=False,
+            ):
+                with pytest.raises(
+                    ValueError,
+                    match="must be between 0 and 100",
+                ):
+                    group.add_ips_to_group(
+                        group_ip_id=IP_ID,
+                        ip_ids=[IP_ID],
+                        max_allowed_reward_share_percentage=101,
+                    )
+
+    def test_add_ips_to_group_disputed_group(self, group: Group, mock_web3_is_address):
+        """Test add_ips_to_group rejects disputed group."""
+        with mock_web3_is_address():
+            with patch.object(
+                group.dispute_module_client, "isIpTagged", return_value=True
+            ):
+                with pytest.raises(
+                    ValueError,
+                    match="Disputed group cannot add IP",
+                ):
+                    group.add_ips_to_group(
+                        group_ip_id=IP_ID,
+                        ip_ids=[IP_ID],
+                    )
+
+    def test_add_ips_to_group_disputed_ip(self, group: Group, mock_web3_is_address):
+        """Test add_ips_to_group rejects disputed IP in ip_ids."""
+        with mock_web3_is_address():
+            with patch.object(
+                group.dispute_module_client,
+                "isIpTagged",
+                side_effect=[False, True],  # group ok, first ip disputed
+            ):
+                with pytest.raises(
+                    ValueError,
+                    match="Cannot add disputed IP to group",
+                ):
+                    group.add_ips_to_group(
+                        group_ip_id=IP_ID,
+                        ip_ids=[IP_ID, ADDRESS],
+                    )
+
+    def test_add_ips_to_group_ip_is_registered_group(
+        self, group: Group, mock_web3_is_address
+    ):
+        """Test add_ips_to_group rejects IP that is a registered group."""
+        with mock_web3_is_address():
+            with patch.object(
+                group.dispute_module_client, "isIpTagged", return_value=False
+            ), patch.object(
+                group.ip_asset_registry_client,
+                "isRegisteredGroup",
+                side_effect=[False, True],  # first ip ok, second ip is group
+            ):
+                with pytest.raises(
+                    ValueError,
+                    match="Cannot add group to group",
+                ):
+                    group.add_ips_to_group(
+                        group_ip_id=IP_ID,
+                        ip_ids=[IP_ID, ADDRESS],
+                    )
+
     def test_add_ips_to_group_success(
         self,
         group: Group,
         mock_web3_is_address,
     ):
         """Test successful add_ips_to_group operation."""
         with mock_web3_is_address():
-            with patch(
+            with patch.object(
+                group.dispute_module_client, "isIpTagged", return_value=False
+            ), patch.object(
+                group.ip_asset_registry_client,
+                "isRegisteredGroup",
+                return_value=False,
+            ), patch(
                 "story_protocol_python_sdk.resources.Group.build_and_send_transaction",
                 return_value={"tx_hash": TX_HASH, "tx_receipt": {}},
             ):
@@ -482,7 +563,13 @@ def test_add_ips_to_group_default_max_allowed_reward_share_percentage(
     ):
         """Test add_ips_to_group uses default max_allowed_reward_share_percentage 100."""
         with mock_web3_is_address():
-            with patch(
+            with patch.object(
+                group.dispute_module_client, "isIpTagged", return_value=False
+            ), patch.object(
+                group.ip_asset_registry_client,
+                "isRegisteredGroup",
+                return_value=False,
+            ), patch(
                 "story_protocol_python_sdk.resources.Group.build_and_send_transaction",
                 return_value={"tx_hash": TX_HASH, "tx_receipt": {}},
             ) as mock_build:
@@ -501,7 +588,13 @@ def test_add_ips_to_group_max_allowed_reward_share_percentage_zero(
     ):
         """Test add_ips_to_group with max_allowed_reward_share_percentage 0."""
         with mock_web3_is_address():
-            with patch(
+            with patch.object(
+                group.dispute_module_client, "isIpTagged", return_value=False
+            ), patch.object(
+                group.ip_asset_registry_client,
+                "isRegisteredGroup",
+                return_value=False,
+            ), patch(
                 "story_protocol_python_sdk.resources.Group.build_and_send_transaction",
                 return_value={"tx_hash": TX_HASH, "tx_receipt": {}},
             ) as mock_build:
@@ -518,7 +611,13 @@ def test_add_ips_to_group_transaction_fails(
     ):
         """Test add_ips_to_group when transaction build/send fails."""
         with mock_web3_is_address():
-            with patch(
+            with patch.object(
+                group.dispute_module_client, "isIpTagged", return_value=False
+            ), patch.object(
+                group.ip_asset_registry_client,
+                "isRegisteredGroup",
+                return_value=False,
+            ), patch(
                 "story_protocol_python_sdk.resources.Group.build_and_send_transaction",
                 side_effect=Exception("Transaction build failed"),
             ):
@@ -550,6 +649,48 @@ def test_remove_ips_from_group_invalid_group_ip_id(
                     ip_ids=[IP_ID],
                 )
 
+    def test_remove_ips_from_group_group_has_derivative_ips(
+        self, group: Group, mock_web3_is_address
+    ):
+        """Test remove_ips_from_group rejects when group has derivative IPs."""
+        with mock_web3_is_address():
+            with patch.object(
+                group.license_registry_client,
+                "hasDerivativeIps",
+                return_value=True,
+            ):
+                with pytest.raises(
+                    ValueError,
+                    match="Group frozen:.*has derivative IPs",
+                ):
+                    group.remove_ips_from_group(
+                        group_ip_id=IP_ID,
+                        ip_ids=[IP_ID],
+                    )
+
+    def test_remove_ips_from_group_group_has_minted_license_tokens(
+        self, group: Group, mock_web3_is_address
+    ):
+        """Test remove_ips_from_group rejects when group has minted license tokens."""
+        with mock_web3_is_address():
+            with patch.object(
+                group.license_registry_client,
+                "hasDerivativeIps",
+                return_value=False,
+            ), patch.object(
+                group.license_token_client,
+                "getTotalTokensByLicensor",
+                return_value=10,
+            ):
+                with pytest.raises(
+                    ValueError,
+                    match="Group frozen:.*has already minted license tokens",
+                ):
+                    group.remove_ips_from_group(
+                        group_ip_id=IP_ID,
+                        ip_ids=[IP_ID],
+                    )
+
     def test_remove_ips_from_group_invalid_ip_id(self, group: Group, mock_web3):
         """Test remove_ips_from_group with invalid IP ID."""
         invalid_ip_id = "invalid_ip_id"
@@ -571,7 +712,15 @@ def test_remove_ips_from_group_success(
     ):
         """Test successful remove_ips_from_group operation."""
         with mock_web3_is_address():
-            with patch(
+            with patch.object(
+                group.license_registry_client,
+                "hasDerivativeIps",
+                return_value=False,
+            ), patch.object(
+                group.license_token_client,
+                "getTotalTokensByLicensor",
+                return_value=0,
+            ), patch(
                 "story_protocol_python_sdk.resources.Group.build_and_send_transaction",
                 return_value={"tx_hash": TX_HASH, "tx_receipt": {}},
             ):
@@ -588,7 +737,15 @@ def test_remove_ips_from_group_transaction_fails(
     ):
         """Test remove_ips_from_group when transaction build/send fails."""
         with mock_web3_is_address():
-            with patch(
+            with patch.object(
+                group.license_registry_client,
+                "hasDerivativeIps",
+                return_value=False,
+            ), patch.object(
+                group.license_token_client,
+                "getTotalTokensByLicensor",
+                return_value=0,
+            ), patch(
                 "story_protocol_python_sdk.resources.Group.build_and_send_transaction",
                 side_effect=Exception("Transaction build failed"),
             ):