solinpy 0.1.3__tar.gz

solinpy-0.1.3/PKG-INFO

@@ -0,0 +1,9 @@
+Metadata-Version: 2.4
+Name: solinpy
+Version: 0.1.3
+Summary: High-performance Python SDK for Solana
+Author: Equipe Carcaras
+Requires-Python: >=3.10
+Requires-Dist: solders>=0.27.1
+Requires-Dist: mnemonic>=0.21
+Requires-Dist: requests>=2.31.0

solinpy-0.1.3/README.md

@@ -0,0 +1,144 @@
+# 🤝 Contributing Guide — SolInPy
+
+Python Framework for Solana focused on developer experience and simplicity.
+
+---
+
+## 📌 Features (MVP)
+
+- RPC client
+- Wallet management
+- Transactions
+
+---
+
+## 📦 Development Setup
+
+```bash
+git clone https://github.com/your-org/solinpy.git
+cd solinpy
+
+python -m venv .venv
+source .venv/bin/activate  # Windows: .venv\Scripts\activate
+
+pip install -U pip
+pip install -r requirements.txt
+```
+
+---
+
+## 🧹 Code Quality Rules
+
+This project enforces strict quality standards:
+
+- Type checking: `mypy`
+- Linting: `ruff`
+- Testing: `pytest`
+
+All contributions must pass CI before merge.
+
+---
+
+## 🚀 Running Checks Locally
+
+### Lint
+
+```bash
+python -m ruff check .
+```
+
+### Format
+
+```bash
+python -m ruff format .
+```
+
+### Type Check
+
+```bash
+python -m mypy solinpy
+```
+
+### Tests
+
+```bash
+pytest
+```
+
+---
+
+## 🔁 Recommended Workflow
+
+```bash
+git checkout -b feature/my-feature
+```
+
+Make changes, then:
+
+```bash
+git add .
+git commit -m "feat: add new feature"
+git push origin feature/my-feature
+```
+
+Open a Pull Request.
+
+---
+
+## ⚠️ Pull Request Requirements
+
+A PR will only be merged if:
+
+- [ ] Ruff passes
+- [ ] MyPy passes
+- [ ] Tests pass
+- [ ] Code is documented where necessary
+- [ ] No untyped functions introduced
+- [ ] No breaking changes without discussion
+
+---
+
+## 🧪 Testing Philosophy
+
+- Unit tests for core logic
+- Integration tests for RPC interactions
+- Avoid mainnet dependency in tests
+- Use devnet only for integration tests
+
+---
+
+## 📂 Project Structure
+
+```
+solinpy/
+├── solinpy/
+│   ├── client/
+│   ├── wallet/
+│   ├── transaction/
+│   └── utils/
+├── tests/
+├── examples/
+└── docs/
+```
+
+---
+
+## 🧠 Engineering Philosophy
+
+SolInPy is built on:
+
+- Simplicity over complexity
+- Developer experience first
+- Predictable APIs
+- Strong typing
+- Reliability by design
+
+---
+
+## 🚀 Next Steps (Roadmap)
+
+- RPC abstraction improvements
+- Transaction builder expansion
+- SPL token support
+- Better error mapping
+- CLI tooling (future)

solinpy-0.1.3/pyproject.toml

@@ -0,0 +1,29 @@
+[project]
+name = "solinpy"
+version = "0.1.3"
+description = "High-performance Python SDK for Solana"
+authors = [{ name = "Equipe Carcaras" }]
+requires-python = ">=3.10"
+dependencies = [
+    "solders>=0.27.1",
+    "mnemonic>=0.21",
+    "requests>=2.31.0"
+]
+
+[tool.setuptools]
+packages = { find = { include = ["solinpy*"] } }
+
+[tool.mypy]
+ignore_missing_imports = true
+check_untyped_defs = false
+disallow_untyped_defs = false
+warn_return_any = false
+no_implicit_optional = true
+
+[[tool.mypy.overrides]]
+module = "solders.*"
+ignore_missing_imports = true
+
+[[tool.mypy.overrides]]
+module = "mnemonic.*"
+ignore_missing_imports = true

solinpy-0.1.3/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

solinpy-0.1.3/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-0.1.3/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-0.1.3/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)