nectarapi.graphenerpc module
- class nectarapi.graphenerpc.GrapheneRPC(urls: str | List[str], user: str | None = None, password: str | None = None, **kwargs: Any)
Bases:
objectThis class allows calling API methods synchronously, without callbacks.
It logs warnings and errors.
- Parameters:
urls (str) – Either a single HTTP URL, or a list of HTTP URLs
user (str) – Username for Authentication
password (str) – Password for Authentication
num_retries (int) – Number of retries for node connection (default is 100)
num_retries_call (int) – Number of retries for RPC calls on node error (default is 5)
timeout (int) – Timeout setting for HTTP nodes (default is 60)
autoconnect (bool) – Automatically connect on initialization (default is True)
use_tor (bool) – Use Tor proxy for connections
custom_chains (dict) – Custom chains to add to known chains
- property error_cnt: int
- property error_cnt_call: int
- get_network(props: Dict[str, Any] | None = None) Dict[str, Any]
Detects and returns the network/chain configuration for the connected node.
If props is not provided, this call fetches node configuration via get_config(api=”database_api”) and inspects property keys to determine the chain identifier, address prefix, network/version, and core asset definitions. It builds a chain configuration dict with keys: - chain_id: canonical chain identifier string - prefix: account/address prefix for the network - min_version: reported chain version string - chain_assets: list of asset dicts (each with keys “asset” (NAI), “precision”, “symbol”, and “id”)
If the detected chain matches an entry in self.known_chains (preferring the highest compatible known min_version), that known_chains entry is returned instead of the freshly built config.
Special behaviors: - When props is None, get_config(api=”database_api”) is called. - If detection finds conflicting blockchain prefixes, the most frequent prefix is used. - A legacy fallback removes STEEM_CHAIN_ID from props if no blockchain name is inferred, logging a warning to prefer HIVE. - Test-network asset NAIs are mapped to “TBD” or “TESTS” symbols when appropriate. - Asset entries are assigned stable incremental ids based on sorted NAI order.
- Returns:
dict: A chain configuration (either a matching entry from self.known_chains or a freshly constructed chain_config) with keys described above.
- Raises:
RPCError: If chain_id cannot be determined or no compatible known chain is found.
- get_request_id() int
Get request id.
- next() None
Advance to the next available RPC node and attempt to (re)connect.
- property num_retries: int
- property num_retries_call: int
- request_send(payload: bytes) Response
Send the prepared RPC payload to the currently connected node via HTTP POST.
Sends payload to the client’s active URL using the shared HTTP session. If username and password were provided to the client, HTTP basic auth is applied. Raises UnauthorizedError when the node responds with HTTP 401.
- Parameters:
payload (str | bytes): The JSON-RPC payload (string or bytes) to send in the POST body.
- Returns:
httpx.Response: The raw HTTP response object from the node.
- Raises:
UnauthorizedError: If the HTTP response status code is 401 (Unauthorized).
- rpcconnect(next_url: bool = True) None
Selects and establishes connection to an available RPC node.
Attempts to connect to the next available node (or reuse the current one) and initializes per-instance HTTP session state needed for subsequent RPC calls. On a successful connection this method sets: self.url, self.session (shared session reused), self._proxies (Tor proxies when configured), and self.headers.
- Parameters:
next_url (bool): If True, advance to the next node before attempting connection; if False, retry the current node.
- Raises:
RPCError: When a get_config probe returns no properties (connection reached but no config received). KeyboardInterrupt: Propagated if the operation is interrupted by the user.
- rpcexec(payload: Dict[str, Any] | List[Dict[str, Any]]) Any
Execute the given JSON-RPC payload against the currently selected node and return the RPC result.
Sends an HTTP POST with payload to the connected node, handling empty responses, retries, node rotation, and JSON parsing. On success returns either the result field for single-response RPC calls or a list of results when the server returns a JSON-RPC batch/array. Resets per-call error counters on successful responses.
- Parameters:
payload (dict or list): JSON-serializable RPC request object or a list of request objects (batch).
- Returns:
The RPC result (any) for a single request, or a list of results for a batch response.
- Raises:
WorkingNodeMissing: if no working nodes are available. RPCConnection: if the client is not connected to any node. RPCError: for server-reported errors or unexpected / non-JSON responses that indicate an RPC failure. KeyboardInterrupt: if execution is interrupted by the user.
- version_string_to_int(network_version: str) int
Convert a dotted version string “MAJOR.MINOR.PATCH” into a single integer for easy comparison.
The integer is computed as: major * 10^8 + minor * 10^4 + patch. For example, “2.3.15” -> 200030015.
- Parameters:
network_version (str): Version string in the form “major.minor.patch”.
- Returns:
int: Integer representation suitable for numeric comparisons.
- Raises:
ValueError: If any version component is not an integer. IndexError: If the version string does not contain three components.
Return a process-wide httpx client with connection pooling.
The client is constructed lazily and reused for all RPC calls to avoid repeatedly creating TCP/TLS handshakes.