hive-nectar 0.2.9__py3-none-any.whl

nectarapi/node.py

@@ -0,0 +1,194 @@
+import logging
+import re
+import time
+from typing import Any, List, Optional, Union
+
+from .exceptions import CallRetriesReached, NumRetriesReached
+
+log = logging.getLogger(__name__)
+
+
+class Node:
+    def __init__(self, url: str) -> None:
+        self.url = url
+        self.error_cnt = 0
+        self.error_cnt_call = 0
+
+    def __repr__(self) -> str:
+        return self.url
+
+
+class Nodes(list[Node]):
+    """Stores Node URLs and error counts"""
+
+    def __init__(
+        self,
+        urls: Union[str, "Nodes", List[Any], tuple, set, None],
+        num_retries: int,
+        num_retries_call: int,
+    ) -> None:
+        self.set_node_urls(urls)
+        self.num_retries = num_retries
+        self.num_retries_call = num_retries_call
+
+    def set_node_urls(self, urls: Union[str, "Nodes", List[Any], tuple, set, None]) -> None:
+        if isinstance(urls, str):
+            url_list = re.split(r",|;", urls)
+            if url_list is None:
+                url_list = [urls]
+        elif isinstance(urls, Nodes):
+            url_list = [urls[i].url for i in range(len(urls))]
+        elif isinstance(urls, (list, tuple, set)):
+            url_list = urls
+        elif urls is not None:
+            url_list = [urls]
+        else:
+            url_list = []
+        super().__init__([Node(x) for x in url_list])
+        self.current_node_index = -1
+        self.freeze_current_node = False
+
+    def __iter__(self) -> "Nodes":  # type: ignore[override]
+        # Iterator with rotation handled by __next__
+        return self
+
+    def __next__(self) -> str:
+        next_node_count = 0
+        if self.freeze_current_node:
+            return self.url
+        while next_node_count == 0 and (
+            self.num_retries < 0 or self.node.error_cnt < self.num_retries
+        ):
+            self.current_node_index += 1
+            if self.current_node_index >= self.working_nodes_count:
+                self.current_node_index = 0
+            next_node_count += 1
+            if next_node_count > self.working_nodes_count + 1:
+                raise StopIteration
+        return self.url
+
+    next = __next__  # Python 2
+
+    def export_working_nodes(self) -> List[str]:
+        nodes_list = []
+        for i in range(len(self)):
+            if self.num_retries < 0 or self[i].error_cnt <= self.num_retries:
+                nodes_list.append(self[i].url)
+        return nodes_list
+
+    def get_nodes(self) -> List[str]:
+        """Return the list of configured node URLs (including those currently marked errored)."""
+        return [self[i].url for i in range(len(self))]
+
+    def __repr__(self) -> str:
+        nodes_list = self.export_working_nodes()
+        return str(nodes_list)
+
+    @property
+    def working_nodes_count(self) -> int:
+        n = 0
+        if self.freeze_current_node:
+            i = self.current_node_index
+            if self.current_node_index < 0:
+                i = 0
+            if self.num_retries < 0 or self[i].error_cnt <= self.num_retries:
+                n += 1
+            return n
+        for i in range(len(self)):
+            if self.num_retries < 0 or self[i].error_cnt <= self.num_retries:
+                n += 1
+        return n
+
+    @property
+    def url(self) -> str:
+        if self.node is None:
+            return ""
+        return self.node.url
+
+    @property
+    def node(self) -> Node:
+        if self.current_node_index < 0:
+            return self[0]
+        return self[self.current_node_index]
+
+    @property
+    def error_cnt(self) -> int:
+        if self.node is None:
+            return 0
+        return self.node.error_cnt
+
+    @property
+    def error_cnt_call(self) -> int:
+        if self.node is None:
+            return 0
+        return self.node.error_cnt_call
+
+    @property
+    def num_retries_call_reached(self) -> bool:
+        return self.error_cnt_call >= self.num_retries_call
+
+    def disable_node(self) -> None:
+        """Disable current node"""
+        if self.node is not None and self.num_retries_call >= 0:
+            self.node.error_cnt_call = self.num_retries_call
+
+    def increase_error_cnt(self) -> None:
+        """Increase node error count for current node"""
+        if self.node is not None:
+            self.node.error_cnt += 1
+
+    def increase_error_cnt_call(self) -> None:
+        """Increase call error count for current node"""
+        if self.node is not None:
+            self.node.error_cnt_call += 1
+
+    def reset_error_cnt_call(self) -> None:
+        """Set call error count for current node to zero"""
+        if self.node is not None:
+            self.node.error_cnt_call = 0
+
+    def reset_error_cnt(self) -> None:
+        """Set node error count for current node to zero"""
+        if self.node is not None:
+            self.node.error_cnt = 0
+
+    def sleep_and_check_retries(
+        self,
+        errorMsg: Optional[str] = None,
+        sleep: bool = True,
+        call_retry: bool = False,
+        showMsg: bool = True,
+    ) -> None:
+        """Sleep and check if num_retries is reached"""
+        if errorMsg:
+            log.warning("Error: {}".format(errorMsg))
+        if call_retry:
+            cnt = self.error_cnt_call
+            if self.num_retries_call >= 0 and self.error_cnt_call > self.num_retries_call:
+                raise CallRetriesReached()
+        else:
+            cnt = self.error_cnt
+            if self.num_retries >= 0 and self.error_cnt > self.num_retries:
+                raise NumRetriesReached()
+
+        if showMsg:
+            if call_retry:
+                log.warning(
+                    "Retry RPC Call on node: %s (%d/%d)" % (self.url, cnt, self.num_retries_call)
+                )
+            else:
+                log.warning(
+                    "Lost connection or internal error on node: %s (%d/%d)"
+                    % (self.url, cnt, self.num_retries)
+                )
+        if not sleep:
+            return
+        if cnt < 1:
+            sleeptime = 0
+        elif cnt < 10:
+            sleeptime = (cnt - 1) * 1.5 + 0.5
+        else:
+            sleeptime = 10
+        if sleeptime:
+            log.warning("Retrying in %d seconds" % sleeptime)
+            time.sleep(sleeptime)

nectarapi/noderpc.py

@@ -0,0 +1,79 @@
+import logging
+from typing import Any, Dict, List, Union
+
+from . import exceptions
+from .graphenerpc import GrapheneRPC
+
+log = logging.getLogger(__name__)
+
+
+class NodeRPC(GrapheneRPC):
+    """This class allows to call API methods exposed by the witness node via
+    websockets / rpc-json.
+
+    :param str urls: Either a single Websocket/Http URL, or a list of URLs
+    :param str user: Username for Authentication
+    :param str password: Password for Authentication
+    :param int num_retries: Try x times to num_retries to a node on disconnect, -1 for indefinitely
+    :param int num_retries_call: Repeat num_retries_call times a rpc call on node error (default is 5)
+    :param int timeout: Timeout setting for https nodes (default is 60)
+    :param bool use_tor: When set to true, 'socks5h://localhost:9050' is set as proxy
+
+    """
+
+    def __init__(self, *args: Any, **kwargs: Any) -> None:
+        """Init NodeRPC
+
+        :param str urls: Either a single Websocket/Http URL, or a list of URLs
+        :param str user: Username for Authentication
+        :param str password: Password for Authentication
+        :param int num_retries: Try x times to num_retries to a node on disconnect, -1 for indefinitely
+        :param int num_retries_call: Repeat num_retries_call times a rpc call on node error (default is 5)
+        :param int timeout: Timeout setting for https nodes (default is 60)
+        :param bool use_tor: When set to true, 'socks5h://localhost:9050' is set as proxy
+
+        """
+        super().__init__(*args, **kwargs)
+        self.next_node_on_empty_reply = False
+
+    def set_next_node_on_empty_reply(self, next_node_on_empty_reply: bool = True) -> None:
+        """Switch to next node on empty reply for the next rpc call"""
+        self.next_node_on_empty_reply = next_node_on_empty_reply
+
+    def rpcexec(self, payload: Union[Dict[str, Any], List[Dict[str, Any]]]) -> Any:
+        """
+        Execute an RPC call with node-aware retry and Hive-specific error handling.
+
+        Sends the given JSON-RPC payload via the underlying GrapheneRPC implementation and handles node-level failures, automatic retries, and node switching when appropriate. If the instance flag `next_node_on_empty_reply` is set, an empty reply may trigger switching to the next node (when multiple nodes are available). Retries are governed by the node manager's retry policy.
+
+        Parameters:
+            payload (dict or list): JSON-RPC payload to send (method, params, id, etc.).
+
+        Raises:
+            RPCConnection: if no RPC URL is configured (connection not established).
+            CallRetriesReached: when the node-manager's retry budget is exhausted and no alternative node can be used.
+            RPCError: when the remote node returns an RPC error that is not recoverable by retries/switching.
+            Exception: any other unexpected exception raised by the underlying RPC call is propagated.
+        """
+        if self.url is None:
+            raise exceptions.RPCConnection("RPC is not connected!")
+        reply = super().rpcexec(payload)
+        if self.next_node_on_empty_reply and not bool(reply) and self.nodes.working_nodes_count > 1:
+            self.next_node_on_empty_reply = False
+            self._retry_on_next_node("Empty Reply")
+            return super().rpcexec(payload)
+        self.next_node_on_empty_reply = False
+        return reply
+
+    def _retry_on_next_node(self, error_msg: str) -> None:
+        self.nodes.increase_error_cnt()
+        self.nodes.sleep_and_check_retries(error_msg, sleep=False, call_retry=False)
+        self.next()
+
+    def get_account(self, name, **kwargs):
+        """Get full account details from account name
+
+        :param str name: Account name
+        """
+        if isinstance(name, str):
+            return self.get_accounts([name], **kwargs)

nectarapi/openapi.py

@@ -0,0 +1,107 @@
+from typing import Dict, Optional
+
+# Static method→API mapping derived from the hived OpenAPI spec.
+# We intentionally embed a small, opinionated subset to avoid shipping the full
+# OpenAPI document with the package while still providing sensible defaults.
+METHOD_API_MAP: Dict[str, str] = {
+    # Broadcast
+    "broadcast_transaction": "network_broadcast_api",
+    "broadcast_transaction_synchronous": "network_broadcast_api",
+    # Accounts / database
+    "find_accounts": "database_api",
+    "get_accounts": "database_api",
+    "get_dynamic_global_properties": "database_api",
+    "get_reward_fund": "database_api",
+    "get_reward_funds": "database_api",
+    "get_feed_history": "database_api",
+    "get_hardfork_properties": "database_api",
+    "get_config": "database_api",
+    "find_owner_histories": "database_api",
+    "find_escrows": "database_api",
+    "find_recurrent_transfers": "database_api",
+    "get_owner_history": "database_api",
+    "get_withdraw_routes": "database_api",
+    "find_witness_schedule": "database_api",
+    "find_accounts_recovery_requests": "database_api",
+    "find_change_recovery_account_requests": "database_api",
+    "find_savings_withdrawals": "database_api",
+    "find_vesting_delegation_expirations": "database_api",
+    "find_conversion_requests": "database_api",
+    "find_hbd_conversion_requests": "database_api",
+    # Blocks
+    "get_block": "block_api",
+    "get_block_header": "block_api",
+    "get_block_range": "block_api",
+    "get_account_count": "condenser_api",
+    # Account history
+    "get_account_history": "account_history_api",
+    "get_transaction": "account_history_api",
+    "get_ops_in_block": "account_history_api",
+    "enum_virtual_ops": "account_history_api",
+    # Keys
+    "get_key_references": "account_by_key_api",
+    # Witnesses (some nodes do not expose witness_api; database_api supports these)
+    "get_witness_by_account": "condenser_api",
+    "find_witnesses": "database_api",
+    "get_witness_schedule": "database_api",
+    "get_witness_count": "database_api",
+    "get_active_witnesses": "database_api",
+    "get_witness": "database_api",
+    "get_witnesses": "database_api",
+    "list_witnesses": "database_api",
+    "list_witness_votes": "database_api",
+    # Bridge (hivemind)
+    "get_ranked_posts": "bridge",
+    "get_account_posts": "bridge",
+    "get_discussion": "bridge",
+    "get_replies_by_last_update": "bridge",
+    "get_follow_count": "condenser_api",
+    "get_followers": "condenser_api",
+    "get_following": "condenser_api",
+    "get_blog": "condenser_api",
+    "get_blog_entries": "condenser_api",
+    "get_blog_authors": "bridge",
+    "get_content": "bridge",
+    "get_post": "bridge",
+    "get_reblogged_by": "condenser_api",
+    "get_active_votes": "condenser_api",
+    "get_tags_used_by_author": "bridge",
+    "get_follow_list": "bridge",
+    "list_subscribers": "bridge",
+    "list_community_roles": "bridge",
+    "account_notifications": "bridge",
+    "unread_notifications": "bridge",
+    "list_all_subscriptions": "bridge",
+    "list_communities": "bridge",
+    # RC
+    "get_resource_params": "rc_api",
+    "get_resource_pool": "rc_api",
+    "find_rc_accounts": "rc_api",
+    # Market history
+    "get_ticker": "market_history_api",
+    "get_volume": "market_history_api",
+    "get_order_book": "market_history_api",
+    "get_recent_trades": "market_history_api",
+    "get_trade_history": "market_history_api",
+    "get_market_history": "market_history_api",
+    "get_market_history_buckets": "market_history_api",
+    # JSON-RPC meta
+    "get_methods": "jsonrpc",
+    # Proposals
+    "find_proposals": "condenser_api",
+    "get_trending_tags": "condenser_api",
+    "get_discussions_by_promoted": "condenser_api",
+}
+
+
+def get_default_api_for_method(method_name: str) -> Optional[str]:
+    """
+    Return the default API name for a method using the static map.
+
+    Args:
+        method_name: The RPC method (without API prefix), e.g., "get_account_history".
+
+    Returns:
+        The API name string (e.g., "account_history_api") or None if unknown.
+    """
+    return METHOD_API_MAP.get(method_name)

nectarapi/rpcutils.py

@@ -0,0 +1,98 @@
+import json
+import logging
+from typing import Any, Dict, Iterable, List, Union
+
+log = logging.getLogger(__name__)
+
+
+def get_query(
+    request_id: int,
+    api_name: str,
+    name: str,
+    args: Union[Dict[str, Any], Iterable[Any], Any],
+) -> Union[Dict[str, Any], List[Dict[str, Any]]]:
+    """
+    Build an appbase-style JSON-RPC request payload.
+
+    Always emits the `api.method` form (no condenser `call` indirection). Supports:
+    - Single dict params
+    - Positional params passed as an iterable
+    - Batch creation when provided a list of dicts inside an iterable
+    """
+    normalized_args: Any
+    # Convert tuples to lists for easier inspection
+    if isinstance(args, tuple):
+        normalized_args = list(args)
+    else:
+        normalized_args = args
+
+    # Pass through plain dict
+    if isinstance(normalized_args, dict):
+        params: Union[Dict[str, Any], List[Any]] = json.loads(json.dumps(normalized_args))
+        return {
+            "method": f"{api_name}.{name}",
+            "params": params,
+            "jsonrpc": "2.0",
+            "id": request_id,
+        }
+
+    if isinstance(normalized_args, list) and normalized_args:
+        # Batch: list of dicts directly
+        if len(normalized_args) > 1 and all(isinstance(item, dict) for item in normalized_args):
+            queries: List[Dict[str, Any]] = []
+            for entry in normalized_args:
+                queries.append(
+                    {
+                        "method": f"{api_name}.{name}",
+                        "params": json.loads(json.dumps(entry)),
+                        "jsonrpc": "2.0",
+                        "id": request_id,
+                    }
+                )
+                request_id += 1
+            return queries
+
+        # Batch: list of dicts nested inside a single element
+        if (
+            len(normalized_args) == 1
+            and isinstance(normalized_args[0], list)
+            and normalized_args[0]
+            and all(isinstance(item, dict) for item in normalized_args[0])
+        ):
+            queries: List[Dict[str, Any]] = []
+            for entry in normalized_args[0]:
+                queries.append(
+                    {
+                        "method": f"{api_name}.{name}",
+                        "params": json.loads(json.dumps(entry)),
+                        "jsonrpc": "2.0",
+                        "id": request_id,
+                    }
+                )
+                request_id += 1
+            return queries
+
+        # Single dict wrapped in a list
+        if len(normalized_args) == 1 and isinstance(normalized_args[0], dict):
+            return {
+                "method": f"{api_name}.{name}",
+                "params": json.loads(json.dumps(normalized_args[0])),
+                "jsonrpc": "2.0",
+                "id": request_id,
+            }
+
+        # Generic positional args
+        return {
+            "method": f"{api_name}.{name}",
+            "params": json.loads(json.dumps(normalized_args)),
+            "jsonrpc": "2.0",
+            "id": request_id,
+        }
+
+    # Fallback: empty params (use list to satisfy condenser/appbase empty-arg methods)
+    return {
+        "method": f"{api_name}.{name}",
+        "jsonrpc": "2.0",
+        "params": [] if api_name == "condenser_api" else {},
+        "id": request_id,
+    }

nectarapi/version.py

@@ -0,0 +1,3 @@
+"""THIS FILE IS GENERATED FROM nectar PYPROJECT.TOML."""
+
+version = "0.2.9"

nectarbase/__init__.py

@@ -0,0 +1,15 @@
+"""nectarbase."""
+
+from .version import version as __version__
+
+__all__ = [
+    "__version__",
+    "memo",
+    "objects",
+    "objecttypes",
+    "operationids",
+    "operations",
+    "signedtransactions",
+    "ledgertransactions",
+    "transactions",
+]

nectarbase/ledgertransactions.py

@@ -0,0 +1,106 @@
+import logging
+from typing import Any, Dict, Mapping
+
+from nectargraphenebase.account import PublicKey
+from nectargraphenebase.chains import known_chains
+from nectargraphenebase.types import (
+    Array,
+    Signature,
+)
+from nectargraphenebase.unsignedtransactions import (
+    Unsigned_Transaction as GrapheneUnsigned_Transaction,
+)
+
+from .operations import Operation
+
+log = logging.getLogger(__name__)
+
+
+class Ledger_Transaction(GrapheneUnsigned_Transaction):
+    """Create an unsigned transaction and offer method to send it to a ledger device for signing
+
+    :param num ref_block_num:
+    :param num ref_block_prefix:
+    :param str expiration: expiration date
+    :param array operations:  array of operations
+    :param dict custom_chains: custom chain which should be added to the known chains
+    """
+
+    def __init__(self, *args: Any, **kwargs: Any) -> None:
+        self.known_chains = known_chains
+        custom_chain = kwargs.get("custom_chains", {})
+        if len(custom_chain) > 0:
+            for c in custom_chain:
+                if c not in self.known_chains:
+                    self.known_chains[c] = custom_chain[c]
+        super().__init__(*args, **kwargs)
+
+    def add_custom_chains(self, custom_chain: Mapping[str, Any]) -> None:
+        if len(custom_chain) > 0:
+            for c in custom_chain:
+                if c not in self.known_chains:
+                    self.known_chains[c] = custom_chain[c]
+
+    def getOperationKlass(self) -> type[Operation]:
+        return Operation
+
+    def getKnownChains(self) -> Dict[str, Any]:
+        """
+        Return the mapping of known blockchain chains available to this transaction.
+
+        Returns:
+            dict: A mapping where keys are chain identifiers (e.g., "HIVE", "STEEM" or custom names)
+            and values are the chain metadata/configuration that was registered with this transaction.
+        """
+        return self.known_chains
+
+    def sign(self, path: str = "48'/13'/0'/0'/0'", chain: str = "HIVE") -> "Ledger_Transaction":
+        """
+        Sign the transaction using a Ledger device and attach the resulting signature to this transaction.
+
+        Builds APDUs for the given BIP32 path and blockchain chain identifier, sends them to a connected Ledger dongle, collects the final signature returned by the device, and stores it as the transaction's "signatures" entry.
+
+        Parameters:
+            path (str): BIP32 derivation path to use on the Ledger (default "48'/13'/0'/0'/0'").
+            chain (str): Chain identifier used when building APDUs (e.g., "HIVE" or "STEEM").
+
+        Returns:
+            Ledger_Transaction: self with `self.data["signatures"]` set to an Array containing the Ledger-produced Signature.
+
+        Notes:
+            - This method opens a connection to the Ledger device and closes it before returning.
+            - Any exceptions raised by the Ledger communication layer are not handled here and will propagate to the caller.
+        """
+        from ledgerblue.comm import getDongle  # type: ignore[import-not-found]
+
+        dongle = getDongle(True)
+        try:
+            apdu_list = self.build_apdu(path, chain)
+            for apdu in apdu_list:
+                result = dongle.exchange(bytes(apdu))
+            sigs = []
+            signature = result
+            sigs.append(Signature(signature))
+            self.data["signatures"] = Array(sigs)
+            return self
+        finally:
+            dongle.close()
+
+    def get_pubkey(
+        self,
+        path: str = "48'/13'/0'/0'/0'",
+        request_screen_approval: bool = False,
+        prefix: str = "STM",
+    ) -> PublicKey:
+        from ledgerblue.comm import getDongle  # type: ignore[import-not-found]
+
+        dongle = getDongle(True)
+        try:
+            apdu = self.build_apdu_pubkey(path, request_screen_approval)
+            result = dongle.exchange(bytes(apdu))
+            offset = 1 + result[0]
+            address = result[offset + 1 : offset + 1 + result[offset]]
+            # public_key = result[1: 1 + result[0]]
+            return PublicKey(address.decode(), prefix=prefix)
+        finally:
+            dongle.close()