erpc-sdk 0.3.0__py3-none-any.whl

erpc_sdk/__init__.py

@@ -0,0 +1,108 @@
+"""Async Python SDK for ERPC."""
+
+from .client import (
+    ErpcClient,
+    ErpcCloudClient,
+    EthereumClient,
+    SolanaClient,
+    create_erpc_client,
+    create_erpc_cloud_client,
+)
+from .config import (
+    DEFAULT_ACCOUNT_ENDPOINT,
+    DEFAULT_ENDPOINT,
+    DEFAULT_TIMEOUT,
+    DEFAULT_USER_ENDPOINT,
+    ErpcClientConfig,
+    ErpcCloudClientConfig,
+)
+from .errors import (
+    ErpcAbortedError,
+    ErpcBatchPolicyError,
+    ErpcConfigError,
+    ErpcError,
+    ErpcErrorCode,
+    ErpcHttpError,
+    ErpcInvalidResponseError,
+    ErpcJsonRpcError,
+    ErpcTimeoutError,
+    ErpcTransportError,
+)
+from .rest import (
+    AccountClient,
+    CloudCatalogClient,
+    CloudCreditClient,
+    CloudResourcesClient,
+    PriceClient,
+    UsageClient,
+)
+from .rpc import (
+    ETHEREUM_RPC_METHODS,
+    ETHEREUM_SUBSCRIPTION_METHODS,
+    SOLANA_ANALYTICS_METHODS,
+    SOLANA_DAS_METHODS,
+    SOLANA_ENHANCED_SUBSCRIPTION_METHODS,
+    SOLANA_HISTORY_METHODS,
+    SOLANA_LEADER_METHODS,
+    SOLANA_RPC_METHODS,
+    PendingRpcBatchRequest,
+    PendingRpcRequest,
+    RpcNamespace,
+)
+from .subscriptions import (
+    EthereumSubscriptions,
+    RpcSubscription,
+    SolanaSubscriptions,
+    WebSocketJsonRpcTransport,
+)
+from .transport import HttpJsonRpcTransport
+from .types import *  # noqa: F403
+
+__version__ = "0.3.0"
+
+__all__ = [
+    "DEFAULT_ACCOUNT_ENDPOINT",
+    "DEFAULT_ENDPOINT",
+    "DEFAULT_TIMEOUT",
+    "DEFAULT_USER_ENDPOINT",
+    "ETHEREUM_RPC_METHODS",
+    "ETHEREUM_SUBSCRIPTION_METHODS",
+    "SOLANA_ANALYTICS_METHODS",
+    "SOLANA_DAS_METHODS",
+    "SOLANA_ENHANCED_SUBSCRIPTION_METHODS",
+    "SOLANA_HISTORY_METHODS",
+    "SOLANA_LEADER_METHODS",
+    "SOLANA_RPC_METHODS",
+    "AccountClient",
+    "CloudCatalogClient",
+    "CloudCreditClient",
+    "CloudResourcesClient",
+    "EthereumClient",
+    "EthereumSubscriptions",
+    "ErpcAbortedError",
+    "ErpcBatchPolicyError",
+    "ErpcClient",
+    "ErpcClientConfig",
+    "ErpcCloudClient",
+    "ErpcCloudClientConfig",
+    "ErpcConfigError",
+    "ErpcError",
+    "ErpcErrorCode",
+    "ErpcHttpError",
+    "ErpcInvalidResponseError",
+    "ErpcJsonRpcError",
+    "ErpcTimeoutError",
+    "ErpcTransportError",
+    "HttpJsonRpcTransport",
+    "PendingRpcBatchRequest",
+    "PendingRpcRequest",
+    "PriceClient",
+    "RpcNamespace",
+    "RpcSubscription",
+    "SolanaClient",
+    "SolanaSubscriptions",
+    "UsageClient",
+    "WebSocketJsonRpcTransport",
+    "create_erpc_client",
+    "create_erpc_cloud_client",
+]

erpc_sdk/client.py

@@ -0,0 +1,213 @@
+"""Top-level ERPC and Cloud client composition."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+import httpx
+
+from .config import (
+    ErpcClientConfig,
+    ErpcCloudClientConfig,
+    endpoint_with_path,
+    websocket_url,
+)
+from .rest import (
+    AccountClient,
+    CloudCatalogClient,
+    CloudCreditClient,
+    CloudResourcesClient,
+    PriceClient,
+    UsageClient,
+)
+from .rpc import (
+    ETHEREUM_RPC_METHODS,
+    SOLANA_ANALYTICS_METHODS,
+    SOLANA_DAS_METHODS,
+    SOLANA_HISTORY_METHODS,
+    SOLANA_LEADER_METHODS,
+    SOLANA_RPC_METHODS,
+    RpcNamespace,
+)
+from .subscriptions import (
+    EthereumSubscriptions,
+    SolanaSubscriptions,
+    WebSocketJsonRpcTransport,
+)
+from .transport import HttpJsonRpcTransport, RestTransport
+
+
+@dataclass(frozen=True, slots=True)
+class SolanaClient:
+    rpc: RpcNamespace
+    das: RpcNamespace
+    history: RpcNamespace
+    leaders: RpcNamespace
+    analytics: RpcNamespace
+    subscriptions: SolanaSubscriptions
+
+
+@dataclass(frozen=True, slots=True)
+class EthereumClient:
+    rpc: RpcNamespace
+    subscriptions: EthereumSubscriptions
+
+
+class ErpcClient:
+    """Async-first client for JSON-RPC, REST, streams, and subscriptions."""
+
+    def __init__(
+        self,
+        config: ErpcClientConfig,
+        *,
+        http_client: httpx.AsyncClient | None = None,
+    ) -> None:
+        client = http_client or httpx.AsyncClient(timeout=None, follow_redirects=False)
+        self._http_client = client
+        self._owns_http_client = http_client is None
+        solana_transport = HttpJsonRpcTransport(
+            api_key=config.api_key,
+            endpoint=config.endpoint,
+            headers=config.headers,
+            timeout=config.timeout,
+            client=client,
+        )
+        ethereum_transport = HttpJsonRpcTransport(
+            api_key=config.api_key,
+            endpoint=endpoint_with_path(config.endpoint, "/eth"),
+            headers=config.headers,
+            timeout=config.timeout,
+            client=client,
+        )
+        solana_ws = WebSocketJsonRpcTransport(
+            websocket_url(config.endpoint, config.api_key),
+            config.api_key,
+            config.timeout,
+        )
+        ethereum_ws = WebSocketJsonRpcTransport(
+            websocket_url(config.endpoint, config.api_key, "/eth"),
+            config.api_key,
+            config.timeout,
+        )
+        self.solana = SolanaClient(
+            rpc=RpcNamespace(
+                solana_transport,
+                SOLANA_RPC_METHODS,
+                parameter_mode="positional",
+                batch_policy="solana-standard",
+            ),
+            das=RpcNamespace(solana_transport, SOLANA_DAS_METHODS, parameter_mode="named"),
+            history=RpcNamespace(
+                solana_transport, SOLANA_HISTORY_METHODS, parameter_mode="positional"
+            ),
+            leaders=RpcNamespace(
+                solana_transport,
+                SOLANA_LEADER_METHODS,
+                parameter_mode="positional",
+                batch_policy="unsupported",
+            ),
+            analytics=RpcNamespace(
+                solana_transport,
+                SOLANA_ANALYTICS_METHODS,
+                parameter_mode="positional",
+            ),
+            subscriptions=SolanaSubscriptions(solana_ws),
+        )
+        self.ethereum = EthereumClient(
+            rpc=RpcNamespace(ethereum_transport, ETHEREUM_RPC_METHODS, parameter_mode="positional"),
+            subscriptions=EthereumSubscriptions(ethereum_ws),
+        )
+        self.price = PriceClient(
+            RestTransport(
+                credential=config.api_key,
+                endpoint=config.endpoint,
+                headers=config.headers,
+                timeout=config.timeout,
+                client=client,
+            )
+        )
+        self.account = AccountClient(
+            RestTransport(
+                credential=config.api_key,
+                endpoint=config.account_endpoint,
+                headers=config.headers,
+                timeout=config.timeout,
+                client=client,
+            )
+        )
+        self.usage = UsageClient(
+            RestTransport(
+                credential=config.api_key,
+                endpoint=config.user_endpoint,
+                headers=config.headers,
+                timeout=config.timeout,
+                client=client,
+            )
+        )
+        self._closed = False
+
+    async def close(self) -> None:
+        if self._closed:
+            return
+        self._closed = True
+        await self.solana.subscriptions.close()
+        await self.ethereum.subscriptions.close()
+        if self._owns_http_client:
+            await self._http_client.aclose()
+
+    async def __aenter__(self) -> ErpcClient:
+        return self
+
+    async def __aexit__(self, *_: object) -> None:
+        await self.close()
+
+
+class ErpcCloudClient:
+    """Scoped Cloud catalog, credit, resource, and usage reads."""
+
+    def __init__(
+        self,
+        config: ErpcCloudClientConfig,
+        *,
+        http_client: httpx.AsyncClient | None = None,
+    ) -> None:
+        client = http_client or httpx.AsyncClient(timeout=None, follow_redirects=False)
+        self._http_client = client
+        self._owns_http_client = http_client is None
+        transport = RestTransport(
+            credential=config.access_token,
+            endpoint=config.endpoint,
+            headers=config.headers,
+            timeout=config.timeout,
+            client=client,
+        )
+        self.catalog = CloudCatalogClient(transport)
+        self.credit = CloudCreditClient(transport)
+        self.resources = CloudResourcesClient(transport)
+        self.usage = UsageClient(transport)
+        self._closed = False
+
+    async def close(self) -> None:
+        if self._closed:
+            return
+        self._closed = True
+        if self._owns_http_client:
+            await self._http_client.aclose()
+
+    async def __aenter__(self) -> ErpcCloudClient:
+        return self
+
+    async def __aexit__(self, *_: object) -> None:
+        await self.close()
+
+
+def create_erpc_client(
+    config: ErpcClientConfig, *, http_client: httpx.AsyncClient | None = None
+) -> ErpcClient:
+    return ErpcClient(config, http_client=http_client)
+
+
+def create_erpc_cloud_client(
+    config: ErpcCloudClientConfig, *, http_client: httpx.AsyncClient | None = None
+) -> ErpcCloudClient:
+    return ErpcCloudClient(config, http_client=http_client)

erpc_sdk/config.py

@@ -0,0 +1,114 @@
+"""Configuration and URL handling."""
+
+from __future__ import annotations
+
+from collections.abc import Mapping
+from dataclasses import dataclass, field
+from urllib.parse import quote, urlencode, urlsplit, urlunsplit
+
+from .errors import ErpcConfigError
+
+DEFAULT_ENDPOINT = "https://edge.erpc.global"
+DEFAULT_ACCOUNT_ENDPOINT = "https://solana-rpc.erpc.global"
+DEFAULT_USER_ENDPOINT = "https://user-api.erpc.global"
+DEFAULT_TIMEOUT = 30.0
+
+
+def normalize_endpoint(value: str, *, local_http_only: bool = False) -> str:
+    try:
+        parsed = urlsplit(value)
+        _ = parsed.port
+    except ValueError as error:
+        raise ErpcConfigError("endpoint must be an absolute HTTP(S) URL") from error
+    if not parsed.scheme or not parsed.netloc:
+        raise ErpcConfigError("endpoint must be an absolute HTTP(S) URL")
+    local = parsed.hostname in {"127.0.0.1", "::1", "localhost"}
+    allowed = parsed.scheme == "https" or (
+        parsed.scheme == "http" and (not local_http_only or local)
+    )
+    if not allowed:
+        message = (
+            "endpoint must use HTTPS except on localhost"
+            if local_http_only
+            else "endpoint must use HTTP or HTTPS"
+        )
+        raise ErpcConfigError(message)
+    path = parsed.path.rstrip("/") or "/"
+    return urlunsplit((parsed.scheme, parsed.netloc, path, "", ""))
+
+
+def endpoint_with_path(endpoint: str, path: str) -> str:
+    parsed = urlsplit(endpoint)
+    base = parsed.path.rstrip("/")
+    joined = f"{base}/{path.lstrip('/')}"
+    return urlunsplit((parsed.scheme, parsed.netloc, joined, "", ""))
+
+
+def websocket_url(endpoint: str, api_key: str, path: str = "") -> str:
+    parsed = urlsplit(endpoint_with_path(endpoint, path))
+    scheme = "wss" if parsed.scheme == "https" else "ws"
+    query = urlencode({"api-key": api_key}, quote_via=quote)
+    return urlunsplit((scheme, parsed.netloc, parsed.path, query, ""))
+
+
+@dataclass(frozen=True, repr=False, slots=True)
+class ErpcClientConfig:
+    """Configuration for :class:`ErpcClient`; credentials are hidden in repr."""
+
+    api_key: str
+    endpoint: str = DEFAULT_ENDPOINT
+    account_endpoint: str = DEFAULT_ACCOUNT_ENDPOINT
+    user_endpoint: str = DEFAULT_USER_ENDPOINT
+    headers: Mapping[str, str] = field(default_factory=dict)
+    timeout: float = DEFAULT_TIMEOUT
+
+    def __post_init__(self) -> None:
+        key = self.api_key.strip()
+        if not key:
+            raise ErpcConfigError("api_key must not be empty")
+        if not isinstance(self.timeout, (int, float)) or self.timeout <= 0:
+            raise ErpcConfigError("timeout must be positive")
+        object.__setattr__(self, "api_key", key)
+        object.__setattr__(self, "endpoint", normalize_endpoint(self.endpoint))
+        object.__setattr__(self, "account_endpoint", normalize_endpoint(self.account_endpoint))
+        object.__setattr__(self, "user_endpoint", normalize_endpoint(self.user_endpoint))
+        object.__setattr__(self, "headers", dict(self.headers))
+        object.__setattr__(self, "timeout", float(self.timeout))
+
+    def __repr__(self) -> str:
+        return (
+            "ErpcClientConfig(api_key='[REDACTED]', "
+            f"endpoint={self.endpoint!r}, account_endpoint={self.account_endpoint!r}, "
+            f"user_endpoint={self.user_endpoint!r}, "
+            f"header_names={list(self.headers)!r}, timeout={self.timeout!r})"
+        )
+
+
+@dataclass(frozen=True, repr=False, slots=True)
+class ErpcCloudClientConfig:
+    """Configuration for scoped Cloud reads."""
+
+    access_token: str
+    endpoint: str = DEFAULT_USER_ENDPOINT
+    headers: Mapping[str, str] = field(default_factory=dict)
+    timeout: float = DEFAULT_TIMEOUT
+
+    def __post_init__(self) -> None:
+        token = self.access_token.strip()
+        if not token:
+            raise ErpcConfigError("access_token must not be empty")
+        if not isinstance(self.timeout, (int, float)) or self.timeout <= 0:
+            raise ErpcConfigError("timeout must be positive")
+        object.__setattr__(self, "access_token", token)
+        object.__setattr__(
+            self, "endpoint", normalize_endpoint(self.endpoint, local_http_only=True)
+        )
+        object.__setattr__(self, "headers", dict(self.headers))
+        object.__setattr__(self, "timeout", float(self.timeout))
+
+    def __repr__(self) -> str:
+        return (
+            "ErpcCloudClientConfig(access_token='[REDACTED]', "
+            f"endpoint={self.endpoint!r}, header_names={list(self.headers)!r}, "
+            f"timeout={self.timeout!r})"
+        )

erpc_sdk/errors.py

@@ -0,0 +1,110 @@
+"""Stable, credential-safe error types for the ERPC Python SDK."""
+
+from __future__ import annotations
+
+from enum import StrEnum
+from urllib.parse import quote, quote_plus
+
+
+class ErpcErrorCode(StrEnum):
+    """Stable machine-readable SDK error categories."""
+
+    ABORTED = "ERPC_ABORTED"
+    BATCH_POLICY = "ERPC_BATCH_POLICY"
+    CONFIG = "ERPC_CONFIG"
+    HTTP = "ERPC_HTTP"
+    INVALID_RESPONSE = "ERPC_INVALID_RESPONSE"
+    RPC = "ERPC_RPC"
+    TIMEOUT = "ERPC_TIMEOUT"
+    TRANSPORT = "ERPC_TRANSPORT"
+
+
+class ErpcError(Exception):
+    """Base class for all SDK errors."""
+
+    code: ErpcErrorCode
+
+    def __init__(self, code: ErpcErrorCode, message: str) -> None:
+        super().__init__(message)
+        self.code = code
+
+
+class ErpcConfigError(ErpcError):
+    def __init__(self, message: str) -> None:
+        super().__init__(ErpcErrorCode.CONFIG, message)
+
+
+class ErpcTransportError(ErpcError):
+    def __init__(self, message: str = "Unable to reach ERPC") -> None:
+        super().__init__(ErpcErrorCode.TRANSPORT, message)
+
+
+class ErpcHttpError(ErpcError):
+    status: int
+
+    def __init__(self, status: int) -> None:
+        self.status = status
+        super().__init__(ErpcErrorCode.HTTP, f"ERPC request failed with HTTP {status}")
+
+
+class ErpcTimeoutError(ErpcError):
+    timeout: float
+
+    def __init__(self, timeout: float) -> None:
+        self.timeout = timeout
+        super().__init__(
+            ErpcErrorCode.TIMEOUT,
+            f"ERPC request timed out after {round(timeout * 1000)}ms",
+        )
+
+
+class ErpcAbortedError(ErpcError):
+    def __init__(self) -> None:
+        super().__init__(ErpcErrorCode.ABORTED, "ERPC request was aborted")
+
+
+class ErpcInvalidResponseError(ErpcError):
+    def __init__(self, message: str = "ERPC returned an invalid response") -> None:
+        super().__init__(ErpcErrorCode.INVALID_RESPONSE, message)
+
+
+class ErpcBatchPolicyError(ErpcError):
+    def __init__(self, message: str) -> None:
+        super().__init__(ErpcErrorCode.BATCH_POLICY, message)
+
+
+class ErpcJsonRpcError(ErpcError):
+    """A JSON-RPC error with credential-redacted message and data."""
+
+    rpc_code: int
+    data: object | None
+
+    def __init__(self, rpc_code: int, message: str, data: object | None = None) -> None:
+        self.rpc_code = rpc_code
+        self.data = data
+        super().__init__(ErpcErrorCode.RPC, message)
+
+
+def credential_variants(credential: str) -> tuple[str, ...]:
+    values = {credential, quote(credential, safe="~()*!.'"), quote_plus(credential)}
+    return tuple(sorted((value for value in values if value), key=len, reverse=True))
+
+
+def redact_text(value: str, credential: str) -> str:
+    for variant in credential_variants(credential):
+        value = value.replace(variant, "[REDACTED]")
+    return value
+
+
+def redact_value(value: object, credential: str, depth: int = 0) -> object:
+    if depth >= 32:
+        return "[REDACTED]"
+    if isinstance(value, str):
+        return redact_text(value, credential)
+    if isinstance(value, list):
+        return [redact_value(item, credential, depth + 1) for item in value]
+    if isinstance(value, tuple):
+        return tuple(redact_value(item, credential, depth + 1) for item in value)
+    if isinstance(value, dict):
+        return {key: redact_value(item, credential, depth + 1) for key, item in value.items()}
+    return value

erpc_sdk/py.typed

@@ -0,0 +1 @@
+