feat: Add transferCrypto method to TCK (hiero-ledger#2353)

Signed-off-by: aceppaluni <aceppaluni@gmail.com>

Author: aceppaluni

src/hiero_sdk_python/transaction/transfer_transaction.py

@@ -72,8 +72,6 @@ def _add_hbar_transfer(
             amount = amount.to_tinybars()
         elif not isinstance(amount, int):
             raise TypeError("amount must be an int or Hbar instance.")
-        if amount == 0:
-            raise ValueError("Amount must be a non-zero value.")
         if not isinstance(is_approved, bool):
             raise TypeError("is_approved must be a boolean.")
 

tck/handlers/__init__.py

@@ -9,6 +9,7 @@
     sdk,  # setup, reset
     token,
     topic,
+    transfer,
 )
 from .registry import (
     get_all_handlers,

tck/handlers/transfer.py

@@ -0,0 +1,88 @@
+from __future__ import annotations
+
+from hiero_sdk_python import (
+    AccountId,
+    NftId,
+    TokenId,
+    TransferTransaction,
+)
+from hiero_sdk_python.response_code import ResponseCode
+from tck.handlers.registry import rpc_method
+from tck.param.transfer import TransferCryptoParams
+from tck.response.transfer import TransferCryptoResponse
+from tck.util.client_utils import get_client
+from tck.util.constants import DEFAULT_GRPC_TIMEOUT
+
+
+def _build_transfer_transaction(params: TransferCryptoParams) -> TransferTransaction:
+    tx = TransferTransaction()
+
+    tx.set_grpc_deadline(DEFAULT_GRPC_TIMEOUT)
+
+    if params.transfers is None:
+        return tx
+
+    for entry in params.transfers:
+        ## HBAR Transfer
+        if entry.hbar is not None:
+            hbar = entry.hbar
+            account = AccountId.from_string(hbar.evmAddress if hbar.evmAddress else hbar.accountId)
+            amount = int(hbar.amount)
+
+            if entry.approved:
+                tx.add_approved_hbar_transfer(account, amount)
+            else:
+                tx.add_hbar_transfer(account, amount)
+
+        ## Token Transfer
+        elif entry.token is not None:
+            token = entry.token
+
+            token_id = TokenId.from_string(token.tokenId)
+            account = AccountId.from_string(token.accountId)
+
+            if token.decimals is not None:
+                decimals = int(token.decimals)
+
+                if entry.approved:
+                    tx.add_approved_token_transfer_with_decimals(token_id, account, int(token.amount), decimals)
+                else:
+                    tx.add_token_transfer_with_decimals(token_id, account, int(token.amount), decimals)
+            else:
+                if entry.approved:
+                    tx.add_approved_token_transfer(token_id, account, int(token.amount))
+                else:
+                    tx.add_token_transfer(token_id, account, int(token.amount))
+
+        ## NFT Transfer
+        elif entry.nft is not None:
+            nft = entry.nft
+
+            nft_id = NftId(TokenId.from_string(nft.tokenId), int(nft.serialNumber))
+
+            sender = AccountId.from_string(nft.senderAccountId)
+            receiver = AccountId.from_string(nft.receiverAccountId)
+
+            if entry.approved:
+                tx.add_approved_nft_transfer(nft_id, sender, receiver)
+            else:
+                tx.add_nft_transfer(nft_id, sender, receiver)
+
+    return tx
+
+
+@rpc_method("transferCrypto")
+def transfer_crypto(params: TransferCryptoParams) -> TransferCryptoResponse:
+    client = get_client(params.sessionId)
+
+    tx = _build_transfer_transaction(params)
+
+    if params.commonTransactionParams is not None:
+        params.commonTransactionParams.apply_common_params(tx, client)
+
+    receipt = tx.execute(client, wait_for_receipt=False).get_receipt(
+        client,
+        validate_status=True,
+    )
+
+    return TransferCryptoResponse(status=ResponseCode(receipt.status).name)

tck/param/transfer.py

@@ -0,0 +1,87 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+from tck.param.base import BaseTransactionParams
+from tck.util.param_utils import (
+    parse_common_transaction_params,
+    parse_session_id,
+    to_bool,
+)
+
+
+@dataclass
+class HbarTransferParams:
+    accountId: str | None = None
+    evmAddress: str | None = None
+    amount: str | None = None
+
+    @classmethod
+    def parse_json_params(cls, params: dict[str, object]) -> HbarTransferParams:
+        return cls(accountId=params.get("accountId"), evmAddress=params.get("evmAddress"), amount=params.get("amount"))
+
+
+@dataclass
+class TokenTransferParams:
+    tokenId: str | None = None
+    accountId: str | None = None
+    amount: str | None = None
+    decimals: str | None = None
+
+    @classmethod
+    def parse_json_params(cls, params: dict[str, object]) -> TokenTransferParams:
+        return cls(
+            tokenId=params.get("tokenId"),
+            accountId=params.get("accountId"),
+            amount=params.get("amount"),
+            decimals=params.get("decimals"),
+        )
+
+
+@dataclass
+class NftTransferParams:
+    tokenId: str | None = None
+    serialNumber: str | None = None
+    senderAccountId: str | None = None
+    receiverAccountId: str | None = None
+
+    @classmethod
+    def parse_json_params(cls, params: dict[str, object]) -> NftTransferParams:
+        return cls(
+            tokenId=params.get("tokenId"),
+            serialNumber=params.get("serialNumber"),
+            senderAccountId=params.get("senderAccountId"),
+            receiverAccountId=params.get("receiverAccountId"),
+        )
+
+
+@dataclass
+class TransferParams:
+    hbar: HbarTransferParams | None = None
+    token: TokenTransferParams | None = None
+    nft: NftTransferParams | None = None
+    approved: bool | None = None
+
+    @classmethod
+    def parse_json_params(cls, params: dict[str, object]) -> TransferParams:
+        return cls(
+            hbar=HbarTransferParams.parse_json_params(params["hbar"]) if params.get("hbar") is not None else None,
+            token=TokenTransferParams.parse_json_params(params["token"]) if params.get("token") is not None else None,
+            nft=NftTransferParams.parse_json_params(params["nft"]) if params.get("nft") is not None else None,
+            approved=to_bool(params.get("approved")) if "approved" in params else None,
+        )
+
+
+@dataclass
+class TransferCryptoParams(BaseTransactionParams):
+    transfers: list[TransferParams] | None = None
+
+    @classmethod
+    def parse_json_params(cls, params: dict) -> TransferCryptoParams:
+        transfers_raw = params.get("transfers")
+
+        return cls(
+            sessionId=parse_session_id(params),
+            commonTransactionParams=parse_common_transaction_params(params),
+            transfers=[TransferParams.parse_json_params(t) for t in transfers_raw] if transfers_raw else None,
+        )

tck/response/transfer.py

@@ -0,0 +1,8 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+
+@dataclass
+class TransferCryptoResponse:
+    status: str | None = None

tests/unit/transfer_transaction_test.py

@@ -119,9 +119,6 @@ def test_add_invalid_transfer(mock_account_ids):
     with pytest.raises(TypeError):
         transfer_tx.add_hbar_transfer(12345, -500)
 
-    with pytest.raises(ValueError):
-        transfer_tx.add_hbar_transfer(mock_account_ids[0], 0)
-
     with pytest.raises(TypeError):
         transfer_tx.add_token_transfer(12345, mock_account_ids[0], -100)
 
@@ -271,16 +268,19 @@ def test_edge_case_amounts(mock_account_ids):
     assert token1_amounts[account_id_1] == 2
 
 
-def test_zero_amount_validation(mock_account_ids):
-    """Test that zero amounts are properly rejected."""
+def test_zero_amount_handling(mock_account_ids):
+    """Test handling of zero transfer amounts."""
     account_id_1, _, _, token_id_1, _ = mock_account_ids
     transfer_tx = TransferTransaction()
 
-    # Test zero HBAR amount should raise ValueError with updated message
-    with pytest.raises(ValueError, match="Amount must be a non-zero value"):
-        transfer_tx.add_hbar_transfer(account_id_1, 0)
+    # Zero HBAR transfers are allowed
+    transfer_tx.add_hbar_transfer(account_id_1, 0)
+
+    assert len(transfer_tx.hbar_transfers) == 1
+    assert transfer_tx.hbar_transfers[0].account_id == account_id_1
+    assert transfer_tx.hbar_transfers[0].amount == 0
 
-    # Test zero token amount should raise ValueError
+    # Token transfers still reject zero amounts (if unchanged)
     with pytest.raises(ValueError, match="Amount must be a non-zero integer"):
         transfer_tx.add_token_transfer(token_id_1, account_id_1, 0)
 
@@ -555,16 +555,21 @@ def test_hbar_accumulation_with_mixed_int_and_hbar(mock_account_ids):
     assert transfer.amount == 100 + 100_000_000 - 50
 
 
-def test_zero_hbar_value_validation(mock_account_ids):
-    """Test that zero Hbar amounts are properly rejected."""
+def test_zero_hbar_value_handling(mock_account_ids):
+    """Test that zero Hbar amounts are accepted."""
     account_id_1, _, _, _, _ = mock_account_ids
+
     transfer_tx = TransferTransaction()
+    transfer_tx.add_hbar_transfer(account_id_1, Hbar(0))
 
-    with pytest.raises(ValueError, match="Amount must be a non-zero value"):
-        transfer_tx.add_hbar_transfer(account_id_1, Hbar(0))
+    assert len(transfer_tx.hbar_transfers) == 1
+    assert transfer_tx.hbar_transfers[0].amount == 0
+
+    transfer_tx = TransferTransaction()
+    transfer_tx.add_hbar_transfer(account_id_1, 0)
 
-    with pytest.raises(ValueError, match="Amount must be a non-zero value"):
-        transfer_tx.add_hbar_transfer(account_id_1, 0)
+    assert len(transfer_tx.hbar_transfers) == 1
+    assert transfer_tx.hbar_transfers[0].amount == 0
 
 
 def test_add_hbar_transfer_with_various_hbar_units(mock_account_ids):