feat: add collect_royalties method in the group module (#135)

* feat: add claim rewards functionality to Group and GroupingModuleClient

* feat: add integration test for claiming rewards in Group functionality

* feat: add unit tests for Group.claim_rewards method with various scenarios

* feat: add claimReward function to GroupingModule in config.json

* feat: update imports in __init__.py to include ClaimReward and RegisterPILTermsAndAttachResponse

* refactor: remove debug print statements from Group and integration tests

* refactor: update claim_rewards method in Group to enhance response structure and remove unused parsing function

* refactor: improve claim_rewards method in Group to process logs directly and enhance error handling

* refactor: simplify test assertions in TestGroupClaimRewards for claim_rewards method

* feat: add collect_royalties functionality to Group and GroupingModuleClient

* chore: update .gitignore to include .cursor directory

* fix: improve royalty collection logic in Group by processing logs directly for event signatures

* refactor: restructure integration tests for Group functionality by introducing a helper class and enhancing test methods for royalty collection and reward claiming

* test: add unit tests for Group.collect_royalties method covering various scenarios including invalid inputs and successful transactions

* refactor: update type hint for mint_and_register_ip_asset_with_pil_terms method in GroupTestHelper to use 'Any' for improved clarity

Author: bonnie57

.gitignore

@@ -112,3 +112,4 @@ web3py.md
 
 # AI Assistant Configuration
 CLAUDE.md
+.cursor/

src/story_protocol_python_sdk/__init__.py

@@ -8,7 +8,11 @@
 from .resources.WIP import WIP
 from .story_client import StoryClient
 from .types.common import AccessPermission
-from .types.resource.Group import ClaimReward, ClaimRewardsResponse
+from .types.resource.Group import (
+    ClaimReward,
+    ClaimRewardsResponse,
+    CollectRoyaltiesResponse,
+)
 from .types.resource.IPAsset import (
     RegisterPILTermsAndAttachResponse,
     RegistrationResponse,
@@ -40,6 +44,7 @@
     "RegistrationResponse",
     "ClaimRewardsResponse",
     "ClaimReward",
+    "CollectRoyaltiesResponse",
     "RegisterPILTermsAndAttachResponse",
     # Constants
     "ZERO_ADDRESS",

src/story_protocol_python_sdk/abi/GroupingModule/GroupingModule_client.py

@@ -51,6 +51,14 @@ def build_claimReward_transaction(self, groupId, token, ipIds, tx_params):
             groupId, token, ipIds
         ).build_transaction(tx_params)
 
+    def collectRoyalties(self, groupId, token):
+        return self.contract.functions.collectRoyalties(groupId, token).transact()
+
+    def build_collectRoyalties_transaction(self, groupId, token, tx_params):
+        return self.contract.functions.collectRoyalties(
+            groupId, token
+        ).build_transaction(tx_params)
+
     def registerGroup(self, groupPool):
         return self.contract.functions.registerGroup(groupPool).transact()
 

src/story_protocol_python_sdk/resources/Group.py

@@ -29,6 +29,7 @@
 from story_protocol_python_sdk.types.resource.Group import (
     ClaimReward,
     ClaimRewardsResponse,
+    CollectRoyaltiesResponse,
 )
 from story_protocol_python_sdk.utils.constants import ZERO_ADDRESS, ZERO_HASH
 from story_protocol_python_sdk.utils.license_terms import LicenseTerms
@@ -597,6 +598,55 @@ def claim_rewards(
         except Exception as e:
             raise ValueError(f"Failed to claim rewards: {str(e)}")
 
+    def collect_royalties(
+        self,
+        group_ip_id: Address,
+        currency_token: Address,
+        tx_options: dict | None = None,
+    ) -> CollectRoyaltiesResponse:
+        """
+        Collects royalties into the pool, making them claimable by group member IPs.
+
+        :param group_ip_id Address: The ID of the group IP.
+        :param currency_token Address: The address of the currency (revenue) token to collect.
+        :param tx_options dict: [Optional] The transaction options.
+        :return CollectRoyaltiesResponse: A response object with the transaction hash and collected royalties.
+        """
+        try:
+            if not self.web3.is_address(group_ip_id):
+                raise ValueError(f"Invalid group IP ID: {group_ip_id}")
+            if not self.web3.is_address(currency_token):
+                raise ValueError(f"Invalid currency token: {currency_token}")
+
+            response = build_and_send_transaction(
+                self.web3,
+                self.account,
+                self.grouping_module_client.build_collectRoyalties_transaction,
+                group_ip_id,
+                currency_token,
+                tx_options=tx_options,
+            )
+
+            event_signature = self.web3.keccak(
+                text="CollectedRoyaltiesToGroupPool(address,address,address,uint256)"
+            ).hex()
+
+            collected_royalties = 0
+            for log in response["tx_receipt"]["logs"]:
+                if log["topics"][0].hex() == event_signature:
+                    event_results = self.grouping_module_client.contract.events.CollectedRoyaltiesToGroupPool.process_log(
+                        log
+                    )
+                    collected_royalties = event_results["args"]["amount"]
+                    break
+
+            return CollectRoyaltiesResponse(
+                tx_hash=response["tx_hash"],
+                collected_royalties=collected_royalties,
+            )
+        except Exception as e:
+            raise ValueError(f"Failed to collect royalties: {str(e)}")
+
     def _get_license_data(self, license_data: list) -> list:
         """
         Process license data into the format expected by the contracts.

src/story_protocol_python_sdk/scripts/config.json

@@ -183,7 +183,8 @@
         "registerGroup",
         "addIp",
         "IPGroupRegistered",
-        "claimReward"
+        "claimReward",
+        "collectRoyalties"
       ]
     },
     {

src/story_protocol_python_sdk/types/resource/Group.py

@@ -21,3 +21,12 @@ class ClaimRewardsResponse(TypedDict):
 
     tx_hash: HexBytes
     claimed_rewards: ClaimReward
+
+
+class CollectRoyaltiesResponse(TypedDict):
+    """
+    Response structure for Group.collect_royalties method.
+    """
+
+    tx_hash: HexBytes
+    collected_royalties: int