solinpy 0.1.3__py3-none-any.whl

solinpy/client/client.py

@@ -0,0 +1,190 @@
+import json
+import random
+import time
+import urllib.request
+import urllib.error
+from typing import Optional, Dict, Any
+from solinpy.client.entities import RPCConfig
+from solinpy.client.execptions import RPCError
+
+class SolanaRPCClient:
+    def __init__(self, config: Optional[RPCConfig | str] = None):
+        if isinstance(config, str):
+            self.cfg = RPCConfig(custom_endpoint=config)
+        else:
+            self.cfg = config or RPCConfig()
+            
+        self.endpoint = self.cfg.custom_endpoint or self._resolve_cluster_url()
+        self._request_id = 0
+
+    def _resolve_cluster_url(self) -> str:
+        urls = {
+            "devnet": "https://api.devnet.solana.com",
+            "testnet": "https://api.testnet.solana.com",
+            "mainnet": "https://api.mainnet-beta.solana.com",
+        }
+        return urls.get(self.cfg.cluster, urls["devnet"])
+
+    def _calc_backoff(self, attempt: int) -> float:
+        delay = min(self.cfg.base_delay * (2**attempt), self.cfg.max_delay)
+        jitter = random.uniform(0, delay * 0.5)
+        return delay + jitter
+
+    def _is_retryable(self, exc: Exception, rpc_error: Optional[dict] = None) -> bool:
+        if isinstance(exc, urllib.error.HTTPError):
+            return exc.code in self.cfg.retryable_http_codes
+        if isinstance(exc, (urllib.error.URLError, ConnectionError, OSError, TimeoutError)):
+            return True
+        if rpc_error and rpc_error.get("code") in self.cfg.retryable_rpc_codes:
+            return True
+        return False
+
+    def _raise_rpc_error(self, method: str, rpc_error: dict, context: Optional[Dict[str, Any]] = None) -> None:
+        raise RPCError.from_rpc_error(method, rpc_error, context=context)
+
+    def _call(
+        self,
+        method: str,
+        params: Optional[list] = None,
+        context: Optional[Dict[str, Any]] = None,
+    ) -> Dict[str, Any]:
+        self._request_id += 1
+        payload = {
+            "jsonrpc": "2.0",
+            "id": self._request_id,
+            "method": method,
+            "params": params or [],
+        }
+        data = json.dumps(payload).encode("utf-8")
+
+        req = urllib.request.Request(
+            self.endpoint, data=data, headers={"Content-Type": "application/json"}, method="POST"
+        )
+
+        last_exc = None
+        for attempt in range(self.cfg.max_retries + 1):
+            try:
+                with urllib.request.urlopen(req, timeout=self.cfg.timeout) as resp:
+                    body = json.loads(resp.read())
+                    if "error" in body:
+                        err = body["error"]
+                        if self._is_retryable(None, rpc_error=err):
+                            if attempt < self.cfg.max_retries:
+                                time.sleep(self._calc_backoff(attempt))
+                                continue
+                        self._raise_rpc_error(method, err, context=context)
+                    return body
+
+            except urllib.error.HTTPError as e:
+                last_exc = e
+                if self._is_retryable(e) and attempt < self.cfg.max_retries:
+                    time.sleep(self._calc_backoff(attempt))
+                    continue
+                raise RPCError.from_transport_error(
+                    method,
+                    e,
+                    context={**(context or {}), "endpoint": self.endpoint},
+                    message=f"Falha HTTP ao executar {method}. Verifique o endpoint configurado.",
+                ) from e
+            except (urllib.error.URLError, ConnectionError, OSError, TimeoutError) as e:
+                last_exc = e
+                if self._is_retryable(e) and attempt < self.cfg.max_retries:
+                    time.sleep(self._calc_backoff(attempt))
+                    continue
+                break
+            except Exception as e:
+                last_exc = e
+                raise RPCError.from_transport_error(
+                    method,
+                    e,
+                    context={**(context or {}), "endpoint": self.endpoint},
+                    message=f"Falha inesperada ao executar {method}.",
+                ) from e
+        raise RPCError(
+            f"Falha de comunicação ao executar {method} após {self.cfg.max_retries + 1} tentativas.",
+            method=method,
+            context={**(context or {}), "endpoint": self.endpoint},
+            cause=last_exc,
+        ) from last_exc
+
+    def get_health(self) -> str:
+        return self._call("getHealth")["result"]
+
+    def get_latest_blockhash(self, commitment: str = "confirmed") -> str:
+        resp = self._call("getLatestBlockhash", [{"commitment": commitment}], {"commitment": commitment})
+        return resp["result"]["value"]["blockhash"]
+
+    def send_transaction(self, tx_base64: str, max_retries: int = 5) -> str:
+        resp = self._call(
+            "sendTransaction",
+            [tx_base64, {
+                "encoding": "base64",
+                "maxRetries": max_retries
+            }],
+            {"tx_size": len(tx_base64), "max_retries": max_retries},
+        )
+        return resp["result"]
+    
+    def get_balance(self, address: str) -> int:
+        """
+        Returns the account balance in Lamports.
+        
+        Args:
+            address: The base58-encoded public key of the account.
+            
+        Returns:
+            int: The balance in Lamports.
+        """
+        sanitized_address = address.strip()
+        resp = self._call("getBalance", [sanitized_address], {"address": sanitized_address})
+        return resp["result"]["value"]
+
+    def get_token_accounts_by_owner(self, address: str) -> list[Dict[str, Any]]:
+        """
+        Returns the list of SPL token accounts associated with an address.
+        """
+        TOKEN_PROGRAM_ID = "TokenkegQfeZyiNwAJbNbGKPFXCWuBvf9Ss623VQ5DA"
+        
+        sanitized_address = address.strip()
+        
+        params = [
+            sanitized_address,
+            {"programId": TOKEN_PROGRAM_ID},
+            {"encoding": "jsonParsed", "commitment": "confirmed"} # Adicionado o commitment
+        ]
+        
+        resp = self._call("getTokenAccountsByOwner", params, {"address": sanitized_address})
+        return resp["result"]["value"]
+    
+    def get_sol_balance(self, address: str) -> float:
+        """
+        Returns the account balance converted to SOL (user-friendly unit).
+
+        Args:
+            address: The base58-encoded public key of the account.
+
+        Returns:
+            float: The balance in SOL.
+        """
+        lamports = self.get_balance(address)
+        # 1 SOL is equivalent to 1,000,000,000 Lamports
+        return lamports / 1_000_000_000
+    
+    def get_token_balances(self, address: str) -> list[dict]:
+        """
+        Retrieves a simplified list of token balances for a given address.
+        """
+        raw_accounts = self.get_token_accounts_by_owner(address)
+        balances = []
+        
+        for account in raw_accounts:
+            info = account["account"]["data"]["parsed"]["info"]
+            token_amount = info["tokenAmount"]
+            
+            balances.append({
+                "mint": info["mint"],
+                "amount": token_amount["uiAmount"],
+                "decimals": token_amount["decimals"]
+            })
+            
+        return balances

solinpy/client/entities.py

@@ -0,0 +1,37 @@
+from dataclasses import dataclass, field
+from typing import Optional
+
+
+@dataclass
+class RPCConfig:
+    """Configuração para o cliente RPC Solana."""
+    cluster: str = "devnet"
+    custom_endpoint: Optional[str] = None
+    timeout: float = 10.0
+    max_retries: int = 3
+    base_delay: float = 1.0
+    max_delay: float = 30.0
+    retryable_http_codes: tuple[int, ...] = field(
+        default_factory=lambda: (429, 500, 502, 503, 504)
+    )
+    retryable_rpc_codes: tuple[int, ...] = field(default_factory=lambda: (-32004, -32005))
+    retries: Optional[int] = None
+    backoff_factor: Optional[float] = None
+
+    def __post_init__(self) -> None:
+        if self.retries is not None:
+            self.max_retries = self.retries
+        else:
+            self.retries = self.max_retries
+
+        if self.backoff_factor is not None:
+            self.base_delay = self.backoff_factor
+        else:
+            self.backoff_factor = self.base_delay
+
+@dataclass
+class TokenBalance:
+    mint: str
+    amount: float
+    decimals: int
+    ui_amount: str

solinpy/client/execptions.py

@@ -0,0 +1,130 @@
+from __future__ import annotations
+
+from typing import Any, Mapping, Optional
+
+
+def _format_context(context: Mapping[str, Any] | None) -> str:
+    if not context:
+        return ""
+
+    parts = [f"{key}={value}" for key, value in context.items() if value is not None]
+    return ", ".join(parts)
+
+
+def _friendly_rpc_message(method: str, code: Optional[int], message: str) -> str:
+    normalized = message.lower()
+
+    if code == -32600 or "invalid request" in normalized:
+        return "Requisição RPC inválida. Verifique os parâmetros enviados."
+
+    if code == -32601 or "method not found" in normalized:
+        return f"Método RPC desconhecido em {method}. Verifique o nome da operação."
+
+    if code == -32602 or any(
+        term in normalized for term in ("invalid params", "invalid parameter", "invalid argument")
+    ):
+        return f"Parâmetros inválidos ao executar {method}. Revise os valores enviados."
+
+    if any(term in normalized for term in ("insufficient funds", "insufficient balance")):
+        return (
+            f"Saldo insuficiente ao executar {method}. "
+            "Verifique se a conta tem SOL suficiente para taxas e valor da operação."
+        )
+
+    if any(
+        term in normalized
+        for term in (
+            "account not found",
+            "invalid account",
+            "could not find account",
+            "failed to get account info",
+            "account does not exist",
+        )
+    ):
+        return f"Conta inválida ou inexistente ao executar {method}. Verifique o endereço informado."
+
+    if any(term in normalized for term in ("blockhash not found", "blockhash expired")):
+        return f"Blockhash expirado ou inválido ao executar {method}. Busque um blockhash novo e tente novamente."
+
+    if code in (-32004, -32005):
+        return f"Serviço RPC temporariamente indisponível ao executar {method}. Tente novamente em instantes."
+
+    if message:
+        return f"Erro RPC ao executar {method}: {message}"
+
+    return f"Erro RPC ao executar {method}."
+
+
+class RPCError(Exception):
+    """Erro de RPC com mensagem amigável e contexto estruturado."""
+
+    def __init__(
+        self,
+        message: str,
+        *,
+        code: Optional[int] = None,
+        method: Optional[str] = None,
+        context: Optional[Mapping[str, Any]] = None,
+        cause: Optional[BaseException] = None,
+    ) -> None:
+        super().__init__(message)
+        self.message = message
+        self.code = code
+        self.method = method
+        self.context = dict(context or {})
+        self.cause = cause
+
+    def __str__(self) -> str:
+        details: list[str] = []
+        if self.code is not None:
+            details.append(f"código RPC={self.code}")
+        if self.method is not None:
+            details.append(f"método={self.method}")
+
+        context_text = _format_context(self.context)
+        if context_text:
+            details.append(f"contexto={context_text}")
+
+        if self.cause is not None:
+            details.append(f"causa={self.cause}")
+
+        if not details:
+            return self.message
+
+        return f"{self.message} [{' | '.join(details)}]"
+
+    @classmethod
+    def from_rpc_error(
+        cls,
+        method: str,
+        rpc_error: Mapping[str, Any],
+        *,
+        context: Optional[Mapping[str, Any]] = None,
+    ) -> "RPCError":
+        code = rpc_error.get("code")
+        raw_message = str(rpc_error.get("message") or "")
+        friendly_message = _friendly_rpc_message(method, code if isinstance(code, int) else None, raw_message)
+
+        extra_details = rpc_error.get("data")
+        merged_context: dict[str, Any] = dict(context or {})
+        if extra_details is not None:
+            merged_context["rpc_data"] = extra_details
+
+        return cls(
+            friendly_message,
+            code=code if isinstance(code, int) else None,
+            method=method,
+            context=merged_context,
+        )
+
+    @classmethod
+    def from_transport_error(
+        cls,
+        method: str,
+        error: BaseException,
+        *,
+        context: Optional[Mapping[str, Any]] = None,
+        message: Optional[str] = None,
+    ) -> "RPCError":
+        friendly_message = message or f"Falha de comunicação ao executar {method}. Verifique o endpoint e tente novamente."
+        return cls(friendly_message, method=method, context=context, cause=error)

solinpy/client/test_client.py

@@ -0,0 +1,164 @@
+import unittest
+from unittest.mock import patch, MagicMock
+import json
+import urllib.error
+from .client import SolanaRPCClient
+from .execptions import RPCError
+from .entities import RPCConfig
+
+
+class TestSolanaRPCClient(unittest.TestCase):
+    def setUp(self):
+        # max_retries=1 para testes rápidos (1 chamada inicial + 1 retry = 2 total)
+        self.config = RPCConfig(cluster="devnet", max_retries=1, timeout=1.0)
+
+    def _mock_urlopen_response(self, data: dict):
+        """Helper para criar um mock compatível com context manager"""
+        mock_resp = MagicMock()
+        mock_resp.read.return_value = json.dumps(data).encode()
+        mock_resp.__enter__ = MagicMock(return_value=mock_resp)
+        mock_resp.__exit__ = MagicMock(return_value=False)
+        return mock_resp
+
+    #  1. Resolução de endpoints
+    def test_endpoint_resolution(self):
+        c1 = SolanaRPCClient(RPCConfig(cluster="mainnet"))
+        self.assertEqual(c1.endpoint, "https://api.mainnet-beta.solana.com")
+
+        c2 = SolanaRPCClient(RPCConfig(custom_endpoint="https://meu-rpc.com"))
+        self.assertEqual(c2.endpoint, "https://meu-rpc.com")
+
+    #  2. Sucesso básico
+    @patch("urllib.request.urlopen")
+    def test_get_health_success(self, mock_urlopen):
+        mock_urlopen.return_value = self._mock_urlopen_response({"result": "ok"})
+        client = SolanaRPCClient(self.config)
+        self.assertEqual(client.get_health(), "ok")
+
+    @patch("urllib.request.urlopen")
+    def test_get_latest_blockhash(self, mock_urlopen):
+        mock_urlopen.return_value = self._mock_urlopen_response(
+            {"result": {"value": {"blockhash": "8xYz...abc"}}}
+        )
+        client = SolanaRPCClient(self.config)
+        self.assertEqual(client.get_latest_blockhash(), "8xYz...abc")
+
+    #  3. Retry em falhas de rede
+    @patch("urllib.request.urlopen")
+    def test_retry_on_network_error(self, mock_urlopen):
+        mock_urlopen.side_effect = urllib.error.URLError("connection refused")
+        client = SolanaRPCClient(self.config)
+        with self.assertRaises(RPCError):
+            client.get_health()
+        # 1 tentativa inicial + 1 retry = 2 chamadas
+        self.assertEqual(mock_urlopen.call_count, 2)
+
+    #  4. Tratamento de erro RPC
+    @patch("urllib.request.urlopen")
+    def test_rpc_error_response(self, mock_urlopen):
+        mock_urlopen.return_value = self._mock_urlopen_response(
+            {"error": {"code": -32600, "message": "Invalid Request"}}
+        )
+        client = SolanaRPCClient(self.config)
+        with self.assertRaises(RPCError) as ctx:
+            client.get_health()
+        self.assertIn("Requisição RPC inválida", str(ctx.exception))
+
+    #  5. Validação do payload de sendTransaction
+    @patch("urllib.request.urlopen")
+    def test_send_transaction_payload(self, mock_urlopen):
+        mock_urlopen.return_value = self._mock_urlopen_response({"result": "5sig..."})
+        client = SolanaRPCClient(self.config)
+        sig = client.send_transaction("base64payload==")
+        self.assertEqual(sig, "5sig...")
+
+        # Verifica se o JSON-RPC foi montado corretamente
+        call_args = mock_urlopen.call_args[0][0]
+        payload = json.loads(call_args.data)
+        self.assertEqual(payload["method"], "sendTransaction")
+        self.assertEqual(payload["params"][0], "base64payload==")
+        self.assertEqual(payload["params"][1]["encoding"], "base64")
+        self.assertEqual(payload["params"][1]["maxRetries"], 5)
+
+class TestRPCRetryAndTimeout(unittest.TestCase):
+    def setUp(self):
+        self.config = RPCConfig(
+            cluster="devnet", max_retries=2, base_delay=0.01, max_delay=0.1, timeout=1.0
+        )
+
+    def _mock_resp(self, data: dict) -> MagicMock:
+        mock: MagicMock = MagicMock()
+        mock.read.return_value = json.dumps(data).encode()
+        mock.__enter__ = MagicMock(return_value=mock)
+        mock.__exit__ = MagicMock(return_value=False)
+        return mock
+
+    @patch("urllib.request.urlopen")
+    @patch("time.sleep")
+    def test_retry_on_http_429(self, mock_sleep, mock_urlopen):
+        # Falha 2x, sucesso na 3ª
+        mock_urlopen.side_effect = [
+            urllib.error.HTTPError("url", 429, "Too Many", {}, MagicMock()),
+            urllib.error.HTTPError("url", 429, "Too Many", {}, MagicMock()),
+            self._mock_resp({"result": "ok"}),
+        ]
+        client = SolanaRPCClient(self.config)
+        self.assertEqual(client.get_health(), "ok")
+        self.assertEqual(mock_urlopen.call_count, 3)
+        self.assertEqual(mock_sleep.call_count, 2)
+
+    @patch("urllib.request.urlopen")
+    @patch("time.sleep")
+    def test_no_retry_on_fatal_rpc_error(self, mock_sleep, mock_urlopen):
+        mock_urlopen.return_value = self._mock_resp(
+            {"error": {"code": -32600, "message": "Invalid Request"}}
+        )
+        client = SolanaRPCClient(self.config)
+        with self.assertRaises(RPCError) as ctx:
+            client.get_health()
+        self.assertIn("Requisição RPC inválida", str(ctx.exception))
+        mock_sleep.assert_not_called()
+
+    @patch("urllib.request.urlopen")
+    @patch("time.sleep")
+    def test_retry_exhausted_on_network_error(self, mock_sleep, mock_urlopen):
+        mock_urlopen.side_effect = ConnectionError("refused")
+        client = SolanaRPCClient(self.config)
+        with self.assertRaises(RPCError):
+            client.get_health()
+        self.assertEqual(mock_urlopen.call_count, 3)
+        self.assertEqual(mock_sleep.call_count, 2)
+
+    def test_timeout_applied_to_config(self):
+        client = SolanaRPCClient(RPCConfig(timeout=5.0))
+        self.assertEqual(client.cfg.timeout, 5.0)
+
+    @patch("urllib.request.urlopen")
+    def test_invalid_account_error_is_friendly(self, mock_urlopen):
+        mock_urlopen.return_value = self._mock_resp(
+            {"error": {"code": -32602, "message": "Invalid params"}}
+        )
+        client = SolanaRPCClient(self.config)
+        with self.assertRaises(RPCError) as ctx:
+            client.get_balance("   bad-account   ")
+
+        error_text = str(ctx.exception)
+        self.assertIn("Parâmetros inválidos", error_text)
+        self.assertIn("address=bad-account", error_text)
+
+    @patch("urllib.request.urlopen")
+    def test_insufficient_funds_error_is_friendly(self, mock_urlopen):
+        mock_urlopen.return_value = self._mock_resp(
+            {"error": {"code": -32000, "message": "insufficient funds for rent"}}
+        )
+        client = SolanaRPCClient(self.config)
+
+        with self.assertRaises(RPCError) as ctx:
+            client.send_transaction("base64payload==")
+
+        error_text = str(ctx.exception)
+        self.assertIn("Saldo insuficiente", error_text)
+        self.assertIn("método=sendTransaction", error_text)
+
+if __name__ == "__main__":
+    unittest.main()