refactor: strict integration tests + tx utils refactor

- Group: return tx_receipt in add_ips_to_group/remove_ips_from_group; add get_added_ip_to_group_events and get_removed_ip_from_group_events for chain verification
- Integration tests: verify on-chain state via AddedIpToGroup/RemovedIpFromGroup events and get_claimable_reward
- transaction_utils: refactor build_and_send_transaction (extract helpers, retry on replacement underpriced/nonce too low with same nonce + higher gas); add nonce validation in encodedTxDataOnly path

Author: chao-peng-story

src/story_protocol_python_sdk/resources/Group.py

@@ -492,7 +492,10 @@ def add_ips_to_group(
                 tx_options=tx_options,
             )
 
-            return {"tx_hash": response["tx_hash"]}
+            result = {"tx_hash": response["tx_hash"]}
+            if "tx_receipt" in response:
+                result["tx_receipt"] = response["tx_receipt"]
+            return result
 
         except Exception as e:
             raise ValueError(f"Failed to add IP to group: {str(e)}")
@@ -528,7 +531,10 @@ def remove_ips_from_group(
                 tx_options=tx_options,
             )
 
-            return {"tx_hash": response["tx_hash"]}
+            result = {"tx_hash": response["tx_hash"]}
+            if "tx_receipt" in response:
+                result["tx_receipt"] = response["tx_receipt"]
+            return result
 
         except Exception as e:
             raise ValueError(f"Failed to remove IPs from group: {str(e)}")
@@ -927,3 +933,57 @@ def _parse_tx_royalty_paid_event(self, tx_receipt: dict) -> list:
                 )
 
         return royalties_distributed
+
+    def get_added_ip_to_group_events(self, tx_receipt: dict) -> list:
+        """
+        Parse AddedIpToGroup events from a transaction receipt (for chain-state verification).
+
+        :param tx_receipt dict: The transaction receipt.
+        :return list: List of dicts with groupId and ipIds (checksum addresses).
+        """
+        events = []
+        for log in tx_receipt["logs"]:
+            try:
+                event_result = self.grouping_module_client.contract.events.AddedIpToGroup.process_log(
+                    log
+                )
+                args = event_result["args"]
+                events.append(
+                    {
+                        "groupId": self.web3.to_checksum_address(args["groupId"]),
+                        "ipIds": [
+                            self.web3.to_checksum_address(addr)
+                            for addr in args["ipIds"]
+                        ],
+                    }
+                )
+            except Exception:
+                continue
+        return events
+
+    def get_removed_ip_from_group_events(self, tx_receipt: dict) -> list:
+        """
+        Parse RemovedIpFromGroup events from a transaction receipt (for chain-state verification).
+
+        :param tx_receipt dict: The transaction receipt.
+        :return list: List of dicts with groupId and ipIds (checksum addresses).
+        """
+        events = []
+        for log in tx_receipt["logs"]:
+            try:
+                event_result = self.grouping_module_client.contract.events.RemovedIpFromGroup.process_log(
+                    log
+                )
+                args = event_result["args"]
+                events.append(
+                    {
+                        "groupId": self.web3.to_checksum_address(args["groupId"]),
+                        "ipIds": [
+                            self.web3.to_checksum_address(addr)
+                            for addr in args["ipIds"]
+                        ],
+                    }
+                )
+            except Exception:
+                continue
+        return events

src/story_protocol_python_sdk/utils/transaction_utils.py

@@ -1,6 +1,91 @@
+import time
+
 from web3 import Web3
 
 TRANSACTION_TIMEOUT = 300
+REPLACEMENT_UNDERPRICED_RETRY_DELAY = 5
+REPLACEMENT_GAS_BUMP_RATIO = 1.2
+
+
+def _validate_nonce(nonce) -> int:
+    """Validate and return nonce. Raises ValueError if invalid."""
+    if not isinstance(nonce, int) or nonce < 0:
+        raise ValueError(
+            f"Invalid nonce value: {nonce}. Nonce must be a non-negative integer."
+        )
+    return nonce
+
+
+def _get_transaction_options(
+    web3: Web3,
+    account,
+    tx_options: dict,
+    *,
+    nonce_override: int | None = None,
+    bump_gas: bool = False,
+) -> dict:
+    """
+    Build the transaction options dict (from, nonce, value, gas).
+    Used for both encodedTxDataOnly and send path.
+    """
+    opts = {"from": account.address}
+
+    # Nonce: use override (retry), explicit from tx_options, or fetch from chain
+    if nonce_override is not None:
+        opts["nonce"] = nonce_override
+    elif "nonce" in tx_options:
+        opts["nonce"] = _validate_nonce(tx_options["nonce"])
+    else:
+        opts["nonce"] = web3.eth.get_transaction_count(account.address)
+
+    if "value" in tx_options:
+        opts["value"] = tx_options["value"]
+
+    # Gas: bump for replacement, or use tx_options
+    if bump_gas:
+        try:
+            opts["gasPrice"] = int(
+                web3.eth.gas_price * REPLACEMENT_GAS_BUMP_RATIO
+            )
+        except Exception:
+            opts["gasPrice"] = web3.to_wei(2, "gwei")
+    else:
+        if "gasPrice" in tx_options:
+            opts["gasPrice"] = web3.to_wei(tx_options["gasPrice"], "gwei")
+        if "maxFeePerGas" in tx_options:
+            opts["maxFeePerGas"] = tx_options["maxFeePerGas"]
+
+    return opts
+
+
+def _is_retryable_send_error(exc: Exception) -> bool:
+    """True if we should retry send (same nonce, higher gas)."""
+    msg = str(exc).lower()
+    return (
+        "replacement transaction underpriced" in msg
+        or "nonce too low" in msg
+    )
+
+
+def _send_one(
+    web3: Web3,
+    account,
+    client_function,
+    client_args: tuple,
+    tx_options: dict,
+    transaction_options: dict,
+) -> dict:
+    """Build, sign, send one transaction. No retry."""
+    transaction = client_function(*client_args, transaction_options)
+    signed_txn = account.sign_transaction(transaction)
+    tx_hash = web3.eth.send_raw_transaction(signed_txn.raw_transaction)
+
+    if not tx_options.get("wait_for_receipt", True):
+        return {"tx_hash": tx_hash.hex()}
+
+    timeout = tx_options.get("timeout", TRANSACTION_TIMEOUT)
+    tx_receipt = web3.eth.wait_for_transaction_receipt(tx_hash, timeout=timeout)
+    return {"tx_hash": tx_hash.hex(), "tx_receipt": tx_receipt}
 
 
 def build_and_send_transaction(
@@ -13,6 +98,9 @@ def build_and_send_transaction(
     """
     Builds and sends a transaction using the provided client function and arguments.
 
+    On "replacement transaction underpriced" or "nonce too low", retries once
+    after a short delay with the same nonce and higher gas.
+
     :param web3 Web3: An instance of Web3.
     :param account: The account to use for signing the transaction.
     :param client_function: The client function to build the transaction.
@@ -29,51 +117,44 @@ def build_and_send_transaction(
                   or encoded data if encodedTxDataOnly is True.
     :raises Exception: If there is an error during the transaction process.
     """
-    try:
-        tx_options = tx_options or {}
-
-        transaction_options = {
-            "from": account.address,
-        }
-
-        if "nonce" in tx_options:
-            nonce = tx_options["nonce"]
-            if not isinstance(nonce, int) or nonce < 0:
-                raise ValueError(
-                    f"Invalid nonce value: {nonce}. Nonce must be a non-negative integer."
-                )
-            transaction_options["nonce"] = nonce
-        else:
-            transaction_options["nonce"] = web3.eth.get_transaction_count(
-                account.address
-            )
+    tx_options = tx_options or {}
+    client_args = tuple(client_args)
 
-        if "value" in tx_options:
-            transaction_options["value"] = tx_options["value"]
+    # Encode-only path: build options and return encoded data, no send
+    if tx_options.get("encodedTxDataOnly"):
+        opts = _get_transaction_options(web3, account, tx_options)
+        encoded = client_function(*client_args, opts)
+        return {"encodedTxData": encoded}
 
-        if "gasPrice" in tx_options:
-            transaction_options["gasPrice"] = web3.to_wei(
-                tx_options["gasPrice"], "gwei"
-            )
-        if "maxFeePerGas" in tx_options:
-            transaction_options["maxFeePerGas"] = tx_options["maxFeePerGas"]
+    # Send path: optionally retry once with same nonce + higher gas
+    used_nonce = None
+    last_error = None
 
-        transaction = client_function(*client_args, transaction_options)
+    for attempt in range(2):
+        opts = _get_transaction_options(
+            web3,
+            account,
+            tx_options,
+            nonce_override=used_nonce,
+            bump_gas=(attempt == 1),
+        )
+        if used_nonce is None:
+            used_nonce = opts["nonce"]
 
-        if tx_options.get("encodedTxDataOnly"):
-            return {"encodedTxData": transaction}
-
-        signed_txn = account.sign_transaction(transaction)
-        tx_hash = web3.eth.send_raw_transaction(signed_txn.raw_transaction)
-
-        wait_for_receipt = tx_options.get("wait_for_receipt", True)
-
-        if wait_for_receipt:
-            timeout = tx_options.get("timeout", TRANSACTION_TIMEOUT)
-            tx_receipt = web3.eth.wait_for_transaction_receipt(tx_hash, timeout=timeout)
-            return {"tx_hash": tx_hash.hex(), "tx_receipt": tx_receipt}
-        else:
-            return {"tx_hash": tx_hash.hex()}
+        try:
+            return _send_one(
+                web3,
+                account,
+                client_function,
+                client_args,
+                tx_options,
+                opts,
+            )
+        except Exception as e:
+            last_error = e
+            if not _is_retryable_send_error(e):
+                raise
+            if attempt == 0:
+                time.sleep(REPLACEMENT_UNDERPRICED_RETRY_DELAY)
 
-    except Exception as e:
-        raise e
+    raise last_error