hiero-sdk-python 0.0.0.dev2__py3-none-any.whl

hiero_sdk_python/__init__.py

@@ -0,0 +1,93 @@
+# Client and Network
+from .client.client import Client
+from .client.network import Network
+
+# Account
+from .account.account_id import AccountId
+from .account.account_create_transaction import AccountCreateTransaction
+
+# Crypto
+from .crypto.private_key import PrivateKey
+from .crypto.public_key import PublicKey
+
+# Tokens
+from .tokens.token_create_transaction import TokenCreateTransaction
+from .tokens.token_associate_transaction import TokenAssociateTransaction
+from .tokens.token_dissociate_transaction import TokenDissociateTransaction
+from .tokens.token_delete_transaction import TokenDeleteTransaction
+from .tokens.token_mint_transaction import TokenMintTransaction
+from .tokens.token_id import TokenId
+
+# Transaction
+from .transaction.transfer_transaction import TransferTransaction
+from .transaction.transaction_id import TransactionId
+from .transaction.transaction_receipt import TransactionReceipt
+
+# Response / Codes
+from .response_code import ResponseCode
+
+# HBAR
+from .hbar import Hbar
+
+# Timestamp
+from .timestamp import Timestamp
+
+# Consensus
+from .consensus.topic_create_transaction import TopicCreateTransaction
+from .consensus.topic_message_submit_transaction import TopicMessageSubmitTransaction
+from .consensus.topic_update_transaction import TopicUpdateTransaction
+from .consensus.topic_delete_transaction import TopicDeleteTransaction
+from .consensus.topic_id import TopicId
+
+# Queries
+from .query.topic_info_query import TopicInfoQuery
+from .query.topic_message_query import TopicMessageQuery
+from .query.transaction_get_receipt_query import TransactionGetReceiptQuery
+from .query.account_balance_query import CryptoGetAccountBalanceQuery
+
+__all__ = [
+    # Client
+    "Client",
+    "Network",
+
+    # Account
+    "AccountId",
+    "AccountCreateTransaction",
+
+    # Crypto
+    "PrivateKey",
+    "PublicKey",
+
+    # Tokens
+    "TokenCreateTransaction",
+    "TokenAssociateTransaction",
+    "TokenDissociateTransaction",
+    "TokenDeleteTransaction",
+    "TokenMintTransaction",
+    "TokenId",
+
+    # Transaction
+    "TransferTransaction",
+    "TransactionId",
+    "TransactionReceipt",
+
+    # Response
+    "ResponseCode",
+
+    # Consensus
+    "TopicCreateTransaction",
+    "TopicMessageSubmitTransaction",
+    "TopicUpdateTransaction",
+    "TopicDeleteTransaction",
+    "TopicId",
+
+    # Queries
+    "TopicInfoQuery",
+    "TopicMessageQuery",
+    "TransactionGetReceiptQuery",
+    "CryptoGetAccountBalanceQuery",
+
+    "Hbar",
+    "ResponseCode",
+    "Timestamp"
+]

hiero_sdk_python/account/account_balance.py

@@ -0,0 +1,44 @@
+from hiero_sdk_python.tokens.token_id import TokenId
+from hiero_sdk_python.hbar import Hbar
+
+class AccountBalance:
+    """
+    Represents the balance of an account, including hbars and tokens.
+
+    Attributes:
+        hbars (Hbar): The balance in hbars.
+        token_balances (dict): A dictionary mapping TokenId to token balances.
+    """
+
+    def __init__(self, hbars, token_balances=None):
+        """
+        Initializes the AccountBalance with the given hbar balance and token balances.
+
+        Args:
+            hbars (Hbar): The balance in hbars.
+            token_balances (dict, optional): A dictionary mapping TokenId to token balances.
+        """
+        self.hbars = hbars
+        self.token_balances = token_balances or {}
+
+    @classmethod
+    def from_proto(cls, proto):
+        """
+        Creates an AccountBalance instance from a protobuf response.
+
+        Args:
+            proto: The protobuf CryptoGetAccountBalanceResponse.
+
+        Returns:
+            AccountBalance: The account balance instance.
+        """
+        hbars = Hbar.from_tinybars(proto.balance)
+
+        token_balances = {}
+        if proto.tokenBalances:
+            for token_balance in proto.tokenBalances:
+                token_id = TokenId.from_proto(token_balance.tokenId)
+                balance = token_balance.balance
+                token_balances[token_id] = balance
+
+        return cls(hbars=hbars, token_balances=token_balances)

hiero_sdk_python/account/account_create_transaction.py

@@ -0,0 +1,173 @@
+from typing import Union
+
+from hiero_sdk_python.transaction.transaction import Transaction
+from hiero_sdk_python.hapi.services import crypto_create_pb2, duration_pb2
+from hiero_sdk_python.response_code import ResponseCode
+from hiero_sdk_python.crypto.public_key import PublicKey
+from hiero_sdk_python.hbar import Hbar
+
+
+class AccountCreateTransaction(Transaction):
+    """
+    Represents an account creation transaction on the Hedera network.
+    """
+
+    def __init__(
+        self,
+        key: PublicKey = None,
+        initial_balance: Union[Hbar, int] = 0,
+        receiver_signature_required: bool = False,
+        auto_renew_period: int = 7890000,  # 90 days in seconds
+        memo: str = ""
+    ):
+        """
+        Initializes a new AccountCreateTransaction instance with default values or specified keyword arguments.
+
+        Args:
+            key (PublicKey, optional): The public key for the new account.
+            initial_balance (Hbar or int, optional): Initial balance in Hbar or tinybars.
+            receiver_signature_required (bool, optional): Whether receiver signature is required.
+            auto_renew_period (int, optional): Auto-renew period in seconds (default is ~90 days).
+            memo (str, optional): Memo for the account.
+        """
+        super().__init__()
+        self.key = key
+        self.initial_balance = initial_balance
+        self.receiver_signature_required = receiver_signature_required
+        self.auto_renew_period = auto_renew_period
+        self.account_memo = memo
+        self._default_transaction_fee = 300_000_000
+
+    def set_key(self, key: PublicKey):
+        """
+        Sets the public key for the new account.
+
+        Args:
+            key (PublicKey): The public key to assign to the account.
+
+        Returns:
+            AccountCreateTransaction: The current transaction instance for method chaining.
+        """
+        self._require_not_frozen()
+        self.key = key
+        return self
+
+    def set_initial_balance(self, balance: Union[Hbar, int]):
+        """
+        Sets the initial balance for the new account.
+
+        Args:
+            balance (Hbar or int): The initial balance in Hbar or tinybars.
+
+        Returns:
+            AccountCreateTransaction: The current transaction instance for method chaining.
+        """
+        self._require_not_frozen()
+        if not isinstance(balance, (Hbar, int)):
+            raise TypeError(
+                "initial_balance must be either an instance of Hbar or an integer (tinybars)."
+            )
+        self.initial_balance = balance
+        return self
+
+    def set_receiver_signature_required(self, required: bool):
+        """
+        Sets whether a receiver signature is required.
+
+        Args:
+            required (bool): True if required, False otherwise.
+
+        Returns:
+            AccountCreateTransaction: The current transaction instance for method chaining.
+        """
+        self._require_not_frozen()
+        self.receiver_signature_required = required
+        return self
+
+    def set_auto_renew_period(self, seconds: int):
+        """
+        Sets the auto-renew period in seconds.
+
+        Args:
+            seconds (int): The auto-renew period.
+
+        Returns:
+            AccountCreateTransaction: The current transaction instance for method chaining.
+        """
+        self._require_not_frozen()
+        self.auto_renew_period = seconds
+        return self
+
+    def set_account_memo(self, memo: str):
+        """
+        Sets the memo for the new account.
+
+        Args:
+            memo (str): The memo to associate with the account.
+
+        Returns:
+            AccountCreateTransaction: The current transaction instance for method chaining.
+        """
+        self._require_not_frozen()
+        self.account_memo = memo
+        return self
+
+    def build_transaction_body(self):
+        """
+        Builds and returns the protobuf transaction body for account creation.
+
+        Returns:
+            TransactionBody: The protobuf transaction body containing the account creation details.
+
+        Raises:
+            ValueError: If required fields are missing.
+            TypeError: If initial_balance is an invalid type.
+        """
+        if not self.key:
+            raise ValueError("Key must be set before building the transaction.")
+
+        if isinstance(self.initial_balance, Hbar):
+            initial_balance_tinybars = self.initial_balance.to_tinybars()
+        elif isinstance(self.initial_balance, int):
+            initial_balance_tinybars = self.initial_balance
+        else:
+            raise TypeError("initial_balance must be Hbar or int (tinybars).")
+
+        crypto_create_body = crypto_create_pb2.CryptoCreateTransactionBody(
+            key=self.key.to_proto(),
+            initialBalance=initial_balance_tinybars,
+            receiverSigRequired=self.receiver_signature_required,
+            autoRenewPeriod=duration_pb2.Duration(seconds=self.auto_renew_period),
+            memo=self.account_memo
+        )
+
+        transaction_body = self.build_base_transaction_body()
+        transaction_body.cryptoCreateAccount.CopyFrom(crypto_create_body)
+
+        return transaction_body
+
+    def _execute_transaction(self, client, transaction_proto):
+        """
+        Executes the account creation transaction using the provided client.
+
+        Args:
+            client (Client): The client instance to use for execution.
+            transaction_proto (Transaction): The protobuf Transaction message.
+
+        Returns:
+            TransactionReceipt: The receipt from the network after transaction execution.
+
+        Raises:
+            Exception: If the transaction submission fails or receives an error response.
+        """
+        response = client.crypto_stub.createAccount(transaction_proto)
+
+        if response.nodeTransactionPrecheckCode != ResponseCode.OK:
+            error_code = response.nodeTransactionPrecheckCode
+            error_message = ResponseCode.get_name(error_code)
+            raise Exception(
+                f"Error during transaction submission: {error_code} ({error_message})"
+            )
+
+        receipt = self.get_receipt(client)
+        return receipt

hiero_sdk_python/account/account_id.py

@@ -0,0 +1,62 @@
+from hiero_sdk_python.hapi.services import basic_types_pb2
+
+class AccountId:
+    def __init__(self, shard=0, realm=0, num=0):
+        self.shard = shard
+        self.realm = realm
+        self.num = num
+
+    @classmethod
+    def from_string(cls, account_id_str):
+        """
+        Creates an AccountId instance from a string in the format 'shard.realm.num'.
+        """
+        parts = account_id_str.strip().split('.')
+        if len(parts) != 3:
+            raise ValueError("Invalid account ID string format. Expected 'shard.realm.num'")
+        shard, realm, num = map(int, parts)
+        return cls(shard, realm, num)
+
+    @classmethod
+    def from_proto(cls, account_id_proto):
+        """
+        Creates an AccountId instance from a protobuf AccountID object.
+
+        Args:
+            account_id_proto (AccountID): The protobuf AccountID object.
+
+        Returns:
+            AccountId: An instance of AccountId.
+        """
+        return cls(
+            shard=account_id_proto.shardNum,
+            realm=account_id_proto.realmNum,
+            num=account_id_proto.accountNum
+        )
+
+    def to_proto(self):
+        """
+        Converts the AccountId instance to a protobuf AccountID object.
+
+        Returns:
+            AccountID: The protobuf AccountID object.
+        """
+        return basic_types_pb2.AccountID(
+            shardNum=self.shard,
+            realmNum=self.realm,
+            accountNum=self.num
+        )
+
+    def __str__(self):
+        """
+        Returns the string representation of the AccountId in 'shard.realm.num' format.
+        """
+        return f"{self.shard}.{self.realm}.{self.num}"
+
+    def __eq__(self, other):
+            if not isinstance(other, AccountId):
+                return False
+            return (self.shard, self.realm, self.num) == (other.shard, other.realm, other.num)
+
+    def __hash__(self):
+        return hash((self.shard, self.realm, self.num))

hiero_sdk_python/client/client.py

@@ -0,0 +1,139 @@
+import grpc
+import time
+from collections import namedtuple
+
+from hiero_sdk_python.hapi.services import (
+    consensus_service_pb2_grpc,
+    token_service_pb2_grpc,
+    crypto_service_pb2_grpc
+)
+
+from hiero_sdk_python.hapi.mirror import (
+    consensus_service_pb2_grpc as mirror_consensus_grpc,
+    mirror_network_service_pb2_grpc as mirror_network_grpc
+)
+
+from .network import Network
+from hiero_sdk_python.response_code import ResponseCode
+from hiero_sdk_python.query.transaction_get_receipt_query import TransactionGetReceiptQuery
+from hiero_sdk_python.transaction.transaction_id import TransactionId
+
+Operator = namedtuple('Operator', ['account_id', 'private_key'])
+
+class Client:
+    """
+    Represents a client to interact with the Hedera network.
+    """
+
+    def __init__(self, network=None):
+        self.operator_account_id = None
+        self.operator_private_key = None
+
+        if network is None:
+            network = Network()
+        self.network = network
+        
+        self.channel = None
+        self.token_stub = None
+        self.crypto_stub = None
+        self.topic_stub = None
+        self.mirror_channel = None
+        self.mirror_stub = None
+
+        self.max_attempts = 10
+
+        node_account_ids = self.get_node_account_ids()
+        if not node_account_ids:
+            raise ValueError("No nodes available in the network configuration.")
+
+        initial_node_id = node_account_ids[0] 
+        self._switch_node(initial_node_id)
+
+        self._init_mirror_stub()
+
+    def _init_mirror_stub(self):
+        """
+        Connect to a mirror node for topic message subscriptions.
+        We now use self.network.get_mirror_address() for a configurable mirror address.
+        """
+        mirror_address = self.network.get_mirror_address()
+        self.mirror_channel = grpc.insecure_channel(mirror_address)
+        self.mirror_stub = mirror_consensus_grpc.ConsensusServiceStub(self.mirror_channel)
+
+    def set_operator(self, account_id, private_key):
+        self.operator_account_id = account_id
+        self.operator_private_key = private_key
+
+    @property
+    def operator(self):
+        if self.operator_account_id and self.operator_private_key:
+            return Operator(account_id=self.operator_account_id, private_key=self.operator_private_key)
+        return None
+
+    def generate_transaction_id(self):
+        if self.operator_account_id is None:
+            raise ValueError("Operator account ID must be set to generate transaction ID.")
+        return TransactionId.generate(self.operator_account_id)
+
+    def get_node_account_ids(self):
+        """
+        Returns a list of node AccountIds that the client can use to send queries and transactions.
+        """
+        if self.network and self.network.nodes:
+            return [account_id for (address, account_id) in self.network.nodes]
+        else:
+            raise ValueError("No nodes available in the network configuration.")
+
+    def get_transaction_receipt(self, transaction_id, max_attempts=10, sleep_seconds=2):
+        for attempt in range(max_attempts):
+            receipt_query = TransactionGetReceiptQuery()
+            receipt_query.set_transaction_id(transaction_id)
+            receipt = receipt_query.execute(self)
+            status = receipt.status
+
+            if status == ResponseCode.SUCCESS:
+                return receipt
+            elif status in (ResponseCode.UNKNOWN, ResponseCode.BUSY, ResponseCode.RECEIPT_NOT_FOUND, ResponseCode.RECORD_NOT_FOUND, ResponseCode.PLATFORM_NOT_ACTIVE):
+                time.sleep(sleep_seconds)
+                continue
+            else:
+                status_message = ResponseCode.get_name(status)
+                raise Exception(f"Error retrieving transaction receipt: {status_message}")
+        raise Exception("Exceeded maximum attempts to fetch transaction receipt.")
+
+    def send_query(self, query, node_account_id, timeout=60):
+        """
+        Sends a query to the specified node and returns the response.
+        """
+        self._switch_node(node_account_id)
+
+        try:
+            request = query._make_request()
+
+            if hasattr(request, 'cryptogetAccountBalance'):
+                response = self.crypto_stub.cryptoGetBalance(request, timeout=timeout)
+            elif hasattr(request, 'transactionGetReceipt'):
+                response = self.crypto_stub.getTransactionReceipts(request, timeout=timeout)
+            elif hasattr(request, 'consensusGetTopicInfo'):
+                response = self.topic_stub.getTopicInfo(request, timeout=timeout)
+            else:
+                raise Exception("Unsupported query type.")
+            return response
+
+        except grpc.RpcError as e:
+            print(f"gRPC error during query execution: {e}")
+            return None
+
+    def _switch_node(self, node_account_id):
+        """
+        Switches to the specified node in the network and updates the gRPC stubs.
+        """
+        node_address = self.network.get_node_address(node_account_id)
+        if node_address is None:
+            raise ValueError(f"No node address found for account ID {node_account_id}")
+
+        self.channel = grpc.insecure_channel(node_address)
+        self.token_stub = token_service_pb2_grpc.TokenServiceStub(self.channel)
+        self.crypto_stub = crypto_service_pb2_grpc.CryptoServiceStub(self.channel)
+        self.topic_stub = consensus_service_pb2_grpc.ConsensusServiceStub(self.channel)
+        self.node_account_id = node_account_id

hiero_sdk_python/client/network.py

@@ -0,0 +1,143 @@
+import random
+import requests
+from hiero_sdk_python.account.account_id import AccountId
+
+class Network:
+    """
+    Manages the network configuration for connecting to the Hedera network.
+    """
+
+    MIRROR_ADDRESS_DEFAULT = {
+        'mainnet': 'hcs.mainnet.mirrornode.hedera.com:5600',
+        'testnet': 'hcs.testnet.mirrornode.hedera.com:5600',
+        'previewnet': 'hcs.previewnet.mirrornode.hedera.com:5600',
+        'solo': 'localhost:5600'
+    }
+
+    MIRROR_NODE_URLS = {
+        'mainnet': 'https://mainnet-public.mirrornode.hedera.com',
+        'testnet': 'https://testnet.mirrornode.hedera.com',
+        'previewnet': 'https://previewnet.mirrornode.hedera.com',
+        'solo': 'http://localhost:8080'  
+    }
+
+    DEFAULT_NODES = {
+        'mainnet': [
+            ("35.237.200.180:50211", AccountId(0, 0, 3)),
+            ("35.186.191.247:50211", AccountId(0, 0, 4)),
+            ("35.192.2.25:50211", AccountId(0, 0, 5)),
+            ("35.199.161.108:50211", AccountId(0, 0, 6)),
+            ("35.203.82.240:50211", AccountId(0, 0, 7)),
+            ("35.236.5.219:50211", AccountId(0, 0, 8)),
+            ("35.197.192.225:50211", AccountId(0, 0, 9)),
+            ("35.242.233.154:50211", AccountId(0, 0, 10)),
+            ("35.240.118.96:50211", AccountId(0, 0, 11)),
+            ("35.204.86.32:50211", AccountId(0, 0, 12)),
+            ("35.234.132.107:50211", AccountId(0, 0, 13)),
+            ("35.236.2.27:50211", AccountId(0, 0, 14)),
+        ],
+        'testnet': [
+            ("0.testnet.hedera.com:50211", AccountId(0, 0, 3)),
+            ("1.testnet.hedera.com:50211", AccountId(0, 0, 4)),
+            ("2.testnet.hedera.com:50211", AccountId(0, 0, 5)),
+            ("3.testnet.hedera.com:50211", AccountId(0, 0, 6)),
+        ],
+        'previewnet': [
+            ("0.previewnet.hedera.com:50211", AccountId(0, 0, 3)),
+            ("1.previewnet.hedera.com:50211", AccountId(0, 0, 4)),
+            ("2.previewnet.hedera.com:50211", AccountId(0, 0, 5)),
+            ("3.previewnet.hedera.com:50211", AccountId(0, 0, 6)),
+        ],
+        'solo': [
+            ("localhost:50211", AccountId(0, 0, 3))
+        ],
+    }
+
+    def __init__(
+        self,
+        network: str = 'testnet',
+        nodes: list = None,
+        mirror_address: str = None,
+    ):
+        """
+        Initializes the Network with the specified network name or custom config.
+
+        Args:
+            network (str): One of 'mainnet', 'testnet', 'previewnet', 'solo', or a custom name if you prefer.
+            nodes (list, optional): A list of (node_address, AccountId) pairs. If provided, we skip fetching from the mirror.
+            mirror_address (str, optional): A mirror node address (host:port) for topic queries.
+                                            If not provided, we'll use a default from MIRROR_ADDRESS_DEFAULT[network].
+        """
+        self.network = network
+        self.mirror_address = mirror_address or self.MIRROR_ADDRESS_DEFAULT.get(network, 'localhost:5600')
+
+        if nodes is not None:
+            self.nodes = nodes
+        else:
+            self.nodes = self._fetch_nodes_from_mirror_node()
+            if not self.nodes:
+                if self.network in self.DEFAULT_NODES:
+                    self.nodes = self.DEFAULT_NODES[self.network]
+                else:
+                    raise ValueError(f"No default nodes for network='{self.network}'")
+
+        self._select_node()
+
+    def _fetch_nodes_from_mirror_node(self):
+        """
+        Fetches the list of nodes from the Hedera Mirror Node REST API.
+        Returns:
+            list: A list of tuples [(node_address, AccountId), ...].
+        """
+        base_url = self.MIRROR_NODE_URLS.get(self.network)
+        if not base_url:
+            print(f"No known mirror node URL for network='{self.network}'. Skipping fetch.")
+            return []
+
+        url = f"{base_url}/api/v1/network/nodes?limit=100&order=desc"
+
+        try:
+            response = requests.get(url)
+            response.raise_for_status()
+            data = response.json()
+
+            nodes = []
+            for node in data.get('nodes', []):
+                service_endpoints = node.get('service_endpoints', [])
+                for endpoint in service_endpoints:
+                    if endpoint.get('port') == 50211 and endpoint.get('protocol') == 'PROTOBUF':
+                        ip_address = endpoint.get('ip_address_v4')
+                        if ip_address:
+                            address = f"{ip_address}:{endpoint['port']}"
+                            account_id_str = node['node_account_id']
+                            account_id = AccountId.from_string(account_id_str)
+                            nodes.append((address, account_id))
+            return nodes
+        except requests.RequestException as e:
+            print(f"Error fetching nodes from mirror node API: {e}")
+            return []
+
+    def _select_node(self):
+        """
+        Select a random node from self.nodes and store it if you want to track a 'current' node.
+        This is optional. The client can still pick or switch nodes as needed.
+        """
+        if not self.nodes:
+            raise ValueError("No nodes available to select.")
+        self.node_address, self.node_account_id = random.choice(self.nodes)
+        # print(f"Selected node: {self.node_address} (Account ID: {self.node_account_id})")
+
+    def get_node_address(self, node_account_id):
+        """
+        Return the gRPC address (host:port) for the given node_account_id, or None if not found.
+        """
+        for address, acct_id in self.nodes:
+            if acct_id == node_account_id:
+                return address
+        return None
+
+    def get_mirror_address(self) -> str:
+        """
+        Return the configured mirror node address used for mirror queries.
+        """
+        return self.mirror_address