Merge branch 'main' into Pylint

Signed-off-by: exploreriii <[email protected]>

Author: exploreriii

src/hiero_sdk_python/tokens/abstract_token_transfer_transaction.py

@@ -0,0 +1,87 @@
+from hiero_sdk_python.account.account_id import AccountId
+from hiero_sdk_python.hapi.services import basic_types_pb2
+from hiero_sdk_python.tokens.token_id import TokenId
+from hiero_sdk_python.tokens.token_nft_transfer import TokenNftTransfer
+from hiero_sdk_python.tokens.token_transfer import TokenTransfer
+from hiero_sdk_python.tokens.token_transfer_list import TokenTransferList
+from hiero_sdk_python.transaction.transaction import Transaction
+
+class AbstractTokenTransferTransaction(Transaction):
+    def __init__(self):
+        """
+        Initializes a new AbstractTokenTransferTransaction instance.
+        """
+        super().__init__()
+        self.token_transfers: list[TokenTransfer] = []
+        self.nft_transfers: list[TokenNftTransfer] = []
+        self._default_transaction_fee = 100_000_000
+
+    def _init_token_transfers(self, token_transfers: list[TokenTransfer]):
+        for transfer in token_transfers:
+            self._add_token_transfer(transfer.token_id, transfer.account_id, transfer.amount, transfer.expected_decimals, transfer.is_approved)
+
+    def _init_nft_transfers(self, nft_transfers: list[TokenNftTransfer]):
+        for transfer in nft_transfers:
+            self._add_nft_transfer(transfer.token_id, transfer.sender_id, transfer.receiver_id, transfer.serial_number, transfer.is_approved)
+
+    def _add_token_transfer(self, token_id: TokenId, account_id: AccountId, amount: int, expected_decimals: int=None, is_approved: bool=False):
+        """
+        Adds a token transfer to the transaction.
+        """
+        if amount == 0:
+            raise ValueError("Amount must be a non-zero integer.")
+        
+        self.token_transfers.append(
+            TokenTransfer(token_id, account_id, amount, expected_decimals, is_approved)
+        )
+
+    def _add_nft_transfer(self, token_id: TokenId, sender: AccountId, receiver: AccountId, serial_number: int, is_approved: bool=False):
+        """
+        Adds a nft transfer to the transaction.
+        """
+        self.nft_transfers.append(
+            TokenNftTransfer(token_id,sender, receiver, serial_number, is_approved)
+        )
+
+    def build_token_transfers(self) -> 'list[basic_types_pb2.TokenTransferList]':
+        """
+        Aggregates all individual fungible token transfers and NFT transfers into
+        a list of TokenTransferList objects, where each TokenTransferList groups
+        transfers for a specific token ID.
+
+        Returns:
+            list[basic_types_pb2.TokenTransferList]: A list of TokenTransferList objects,
+            each grouping transfers for a specific token ID.
+        """
+        transfer_list: dict[TokenId,TokenTransferList] = {}
+
+        for token_transfer in self.token_transfers:
+            if token_transfer.token_id not in transfer_list:
+                transfer_list[token_transfer.token_id] = TokenTransferList(
+                    token_transfer.token_id, 
+                    expected_decimals=token_transfer.expected_decimals
+                )            
+
+            transfer_list[token_transfer.token_id].add_token_transfer(token_transfer)
+
+        for nft_transfer in self.nft_transfers:
+            if nft_transfer.token_id not in transfer_list:
+                transfer_list[nft_transfer.token_id] = TokenTransferList(
+                    nft_transfer.token_id 
+                )
+
+            transfer_list[nft_transfer.token_id].add_nft_transfer(nft_transfer)
+
+        token_transfers: list[basic_types_pb2.TokenTransferList] = []
+
+        for transfer in list(transfer_list.values()):
+            net_amount = 0
+            for token_transfer in transfer.transfers:
+                net_amount += token_transfer.amount
+
+            if net_amount != 0:
+                raise ValueError("All fungible token transfers must be balanced, debits must equal credits.")
+            
+            token_transfers.append(transfer._to_proto())
+        
+        return token_transfers

src/hiero_sdk_python/tokens/token_airdrop_transaction.py

@@ -0,0 +1,147 @@
+from hiero_sdk_python.channels import _Channel
+from hiero_sdk_python.executable import _Method
+from hiero_sdk_python.account.account_id import AccountId
+from hiero_sdk_python.tokens.nft_id import NftId
+from hiero_sdk_python.tokens.token_id import TokenId
+from hiero_sdk_python.tokens.token_nft_transfer import TokenNftTransfer
+from hiero_sdk_python.tokens.token_transfer import TokenTransfer
+from hiero_sdk_python.tokens.abstract_token_transfer_transaction import AbstractTokenTransferTransaction
+from hiero_sdk_python.hapi.services import token_airdrop_pb2
+
+class TokenAirdropTransaction(AbstractTokenTransferTransaction):
+    """
+    Represents a token airdrop transaction on the Hedera network.
+
+    The TokenAirdropTransaction allows users to transfer tokens to multiple accounts,
+    handling both fungible tokens and NFTs.
+    """
+    def __init__(self, token_transfers: list[TokenTransfer]|None=None, nft_transfers: list[TokenNftTransfer]|None=None):
+        """
+        Initializes a new TokenAirdropTransaction instance.
+
+        Args:
+            token_transfers (list[TokenTransfer], optional): Initial list of fungible token transfers.
+            nft_transfers (list[TokenNftTransfer], optional): Initial list of NFT transfers.
+        """
+        super().__init__()
+        if token_transfers:
+            self._init_token_transfers(token_transfers)
+        if nft_transfers:
+            self._init_nft_transfers(nft_transfers)
+
+    def add_token_transfer(self, token_id: TokenId, account_id: AccountId, amount: int) -> 'TokenAirdropTransaction':
+        """
+        Adds a tranfer to token_transfers list 
+        Args:
+            token_id (TokenId): The ID of the token being transferred.
+            account_id (AccountId): The accountId of sender/receiver.
+            amount (int): The amount of the fungible token to transfer.
+
+        Returns:
+            TokenAirdropTransaction: The current instance of the transaction for chaining.
+        """
+        self._require_not_frozen()
+        self._add_token_transfer(token_id, account_id, amount)
+        return self
+    
+    def add_token_transfer_with_decimals(self, token_id: TokenId, account_id: AccountId, amount: int, decimals: int) -> 'TokenAirdropTransaction':
+        """
+        Adds a tranfer with expected_decimals to token_transfers list
+        Args:
+            token_id (TokenId): The ID of the token being transferred.
+            account_id (AccountId): The accountId of sender/receiver.
+            amount (int): The amount of the fungible token to transfer.
+            decimals (int): The number specifying the amount in the smallest denomination.
+
+        Returns:
+            TokenAirdropTransaction: The current instance of the transaction for chaining.
+        """
+        self._require_not_frozen()
+        self._add_token_transfer(token_id, account_id, amount, expected_decimals=decimals)
+        return self
+    
+    def add_approved_token_transfer(self, token_id: TokenId, account_id: AccountId, amount: int) -> 'TokenAirdropTransaction':
+        """
+        Adds a tranfer with approve allowance to token_transfers list 
+        Args:
+            token_id (TokenId): The ID of the token being transferred.
+            account_id (AccountId): The accountId of sender/receiver.
+            amount (int): The amount of the fungible token to transfer.
+
+        Returns:
+            TokenAirdropTransaction: The current instance of the transaction for chaining.
+        """
+        self._require_not_frozen()
+        self._add_token_transfer(token_id, account_id, amount, is_approved=True)
+        return self
+    
+    def add_approved_token_transfer_with_decimals(self, token_id: TokenId, account_id: AccountId, amount: int, decimals: int) -> 'TokenAirdropTransaction':
+        """
+        Adds a tranfer with expected_decimals and approve allowance to token_transfers list
+        Args:
+            token_id (TokenId): The ID of the token being transferred.
+            account_id (AccountId): The accountId of sender/receiver.
+            amount (int): The amount of the fungible token to transfer.
+            decimals (int): The number specifying the amount in the smallest denomination.
+
+        Returns:
+            TokenAirdropTransaction: The current instance of the transaction for chaining.
+        """
+        self._require_not_frozen()
+        self._add_token_transfer(token_id, account_id, amount, decimals, True)
+        return self
+        
+    def add_nft_transfer(self, nft_id: NftId, sender: AccountId, receiver: AccountId) -> 'TokenAirdropTransaction':
+        """
+        Adds a transfer to the nft_transfers
+
+        Args:
+            nft_id (NftId): The ID of the NFT being transferred.
+            sender (AccountId): The sender's account ID.
+            receiver (AccountId): The receiver's account ID.
+
+        Returns:
+            TokenAirdropTransaction: The current instance of the transaction for chaining.
+        """
+        self._require_not_frozen()
+        self._add_nft_transfer(nft_id.tokenId, sender, receiver, nft_id.serialNumber)
+        return self
+    
+    def add_approved_nft_transfer(self, nft_id: NftId, sender: AccountId, receiver: AccountId) -> 'TokenAirdropTransaction':
+        """
+        Adds a transfer to the nft_transfers with approved allowance
+
+        Args:
+            nft_id (NftId): The ID of the NFT being transferred.
+            sender (AccountId): The sender's account ID.
+            receiver (AccountId): The receiver's account ID.
+
+        Returns:
+            TokenAirdropTransaction: The current instance of the transaction for chaining.
+        """
+        self._require_not_frozen()
+        self._add_nft_transfer(nft_id.tokenId, sender, receiver, nft_id.serialNumber,True)
+        return self
+    
+    def build_transaction_body(self):
+        """
+        Builds and returns the protobuf transaction body for token airdrop.
+        """
+        token_transfers = self.build_token_transfers()
+
+        if (len(token_transfers) < 1 or len(token_transfers) > 10):
+            raise ValueError("Airdrop transfer list must contain mininum 1 and maximum 10 transfers.") 
+
+        token_airdrop_body = token_airdrop_pb2.TokenAirdropTransactionBody(
+            token_transfers=token_transfers
+        )
+        transaction_body = self.build_base_transaction_body()
+        transaction_body.tokenAirdrop.CopyFrom(token_airdrop_body)
+
+        return transaction_body
+
+    def _get_method(self, channel: _Channel) -> _Method:
+        return _Method(
+            transaction_func=channel.token.airdropTokens,
+            query_func=None
+        )        

src/hiero_sdk_python/tokens/token_nft_transfer.py

@@ -7,6 +7,7 @@
 """
 from hiero_sdk_python.account.account_id import AccountId
 from hiero_sdk_python.hapi.services import basic_types_pb2
+from hiero_sdk_python.tokens.token_id import TokenId
 
 class TokenNftTransfer:
     """
@@ -16,8 +17,10 @@ class TokenNftTransfer:
     receiver, serial number of the NFT, and whether the transfer is approved.
     """
 
+
     def __init__(
         self,
+        token_id: TokenId,
         sender_id: AccountId,
         receiver_id: AccountId,
         serial_number: int,
@@ -27,16 +30,18 @@ def __init__(
         Initializes a new TokenNftTransfer instance.
         
         Args:
+            token_id (TokenId): The ID of the token being transferred.
             sender_id (AccountId): The account ID of the sender.
             receiver_id (AccountId): The account ID of the receiver.
             serial_number (int): The serial number of the NFT being transferred.
             is_approved (bool, optional): Whether the transfer is approved. Defaults to False.
         """
-        self.sender_id: AccountId = sender_id
-        self.receiver_id: AccountId = receiver_id
-        self.serial_number: int = serial_number
-        self.is_approved: bool = is_approved
-
+        self.token_id: TokenId = token_id
+        self.sender_id : AccountId = sender_id
+        self.receiver_id : AccountId = receiver_id
+        self.serial_number : int = serial_number
+        self.is_approved : bool = is_approved
+        
     def _to_proto(self) -> basic_types_pb2.NftTransfer:
         """
         Converts this TokenNftTransfer instance to its protobuf representation.
@@ -52,16 +57,25 @@ def _to_proto(self) -> basic_types_pb2.NftTransfer:
         )
 
     @classmethod
-    def _from_proto(cls, proto: basic_types_pb2.NftTransfer):
+    def _from_proto(cls, proto: basic_types_pb2.TokenTransferList):
         """
         Creates a TokenNftTransfer from a protobuf representation.
         """
-        return cls(
-            sender_id=AccountId._from_proto(proto.senderAccountID),
-            receiver_id=AccountId._from_proto(proto.receiverAccountID),
-            serial_number=proto.serialNumber,
-            is_approved=proto.is_approval
-        )
+        nftTransfers: list[TokenNftTransfer] = []
+
+        token_id = TokenId._from_proto(proto.token)
+        for nftTransfer in proto.nftTransfers:
+            nftTransfers.append(
+                cls(
+                    token_id = token_id,
+                    sender_id=AccountId._from_proto(nftTransfer.senderAccountID),
+                    receiver_id=AccountId._from_proto(nftTransfer.receiverAccountID),
+                    serial_number=nftTransfer.serialNumber,
+                    is_approved=nftTransfer.is_approval
+                )
+            )
+            
+        return nftTransfers
 
     def __str__(self):
         """
@@ -72,6 +86,7 @@ def __str__(self):
         """
         return (
             "TokenNftTransfer("
+            f"token={self.token_id}, "
             f"sender_id={self.sender_id}, "
             f"receiver_id={self.receiver_id}, "
             f"serial_number={self.serial_number}, "

src/hiero_sdk_python/tokens/token_transfer.py

@@ -0,0 +1,47 @@
+from hiero_sdk_python.account.account_id import AccountId
+from hiero_sdk_python.hapi.services import basic_types_pb2
+from hiero_sdk_python.tokens.token_id import TokenId
+
+class TokenTransfer:
+    """
+    Represents a single fungible token transfer, detailing the token, the account involved,
+    the amount, and optional approval status and decimal expectations.
+    """
+    def __init__(self, token_id: TokenId, account_id: AccountId, amount: int, expected_decimals: int=None, is_approved: bool=False):
+        """
+        Initializes a new TokenTransfer instance.
+
+        Args:
+            token_id (TokenId): The ID of the token being transferred.
+            account_id (AccountId): The account ID of the sender or receiver.
+            amount (int): The amount of the token to send or receive.
+            expected_decimals (optional, int): The number specifying the amount in the smallest denomination.
+            is_approved (optional, bool): Indicates whether this transfer is an approved allowance.
+        """
+        self.token_id: TokenId = token_id
+        self.account_id: AccountId = account_id
+        self.amount: int = amount
+        self.expected_decimals: int = expected_decimals
+        self.is_approved: bool = is_approved
+
+    def _to_proto(self) -> basic_types_pb2.AccountAmount:
+        """
+        Converts this TokenTransfer instance to its protobuf representation, AccountAmount.
+
+        Returns:
+            AccountAmount: The protobuf representation of this TokenTransfer.
+        """
+        return basic_types_pb2.AccountAmount(
+            accountID=self.account_id._to_proto(),
+            amount=self.amount,
+            is_approval=self.is_approved
+        )
+
+    def __str__(self) -> str:
+        """
+        Returns a string representation of this TokenTransfer instance.
+
+        Returns:
+            str: A string representation of this TokenTransfer.
+        """
+        return f"TokenTransfer(token_id={self.token_id}, account_id={self.account_id}, amount={self.amount}, expected_decimals={self.expected_decimals}, is_approved={self.is_approved})"