erpc-sdk 0.3.0__tar.gz

erpc_sdk-0.3.0/.gitignore

@@ -0,0 +1,17 @@
+node_modules/
+dist/
+target/
+coverage/
+*.tsbuildinfo
+*.log
+.DS_Store
+.mypy_cache/
+.pytest_cache/
+.ruff_cache/
+.venv/
+*.egg-info/
+*.py[cod]
+__pycache__/
+.env
+.env.*
+!.env.example

erpc_sdk-0.3.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 ELSOUL LABO B.V.
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

erpc_sdk-0.3.0/PKG-INFO

@@ -0,0 +1,152 @@
+Metadata-Version: 2.4
+Name: erpc-sdk
+Version: 0.3.0
+Summary: Async Python SDK for ERPC
+Project-URL: Documentation, https://github.com/elsoul/erpc-sdk/tree/main/packages/python
+Project-URL: Homepage, https://erpc.global
+Project-URL: Repository, https://github.com/elsoul/erpc-sdk
+Author: ELSOUL LABO B.V.
+License: MIT License
+        
+        Copyright (c) 2026 ELSOUL LABO B.V.
+        
+        Permission is hereby granted, free of charge, to any person obtaining a copy
+        of this software and associated documentation files (the "Software"), to deal
+        in the Software without restriction, including without limitation the rights
+        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+        copies of the Software, and to permit persons to whom the Software is
+        furnished to do so, subject to the following conditions:
+        
+        The above copyright notice and this permission notice shall be included in all
+        copies or substantial portions of the Software.
+        
+        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+        SOFTWARE.
+License-File: LICENSE
+Keywords: erpc,ethereum,json-rpc,rpc,solana
+Classifier: Development Status :: 4 - Beta
+Classifier: Framework :: AsyncIO
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Typing :: Typed
+Requires-Python: >=3.11
+Requires-Dist: httpx<1,>=0.27
+Requires-Dist: websockets<17,>=13
+Provides-Extra: dev
+Requires-Dist: build<2,>=1.2; extra == 'dev'
+Requires-Dist: mypy<2,>=1.11; extra == 'dev'
+Requires-Dist: pytest-asyncio<2,>=0.24; extra == 'dev'
+Requires-Dist: pytest<10,>=8; extra == 'dev'
+Requires-Dist: ruff<1,>=0.8; extra == 'dev'
+Requires-Dist: twine<7,>=5; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# ERPC SDK for Python
+
+Async Python client for ERPC. It covers standard Solana and Ethereum JSON-RPC,
+indexed assets, history, leader and analytics RPC, WebSocket subscriptions,
+price REST and server-sent events, account usage, and scoped Cloud reads.
+
+```bash
+python -m pip install erpc-sdk
+```
+
+Python 3.11 or newer is required.
+
+## Quick start
+
+```python
+import asyncio
+import os
+
+from erpc_sdk import ErpcClient, ErpcClientConfig
+
+
+async def main() -> None:
+    async with ErpcClient(ErpcClientConfig(os.environ["ERPC_API_KEY"])) as erpc:
+        slot = await erpc.solana.rpc.get_slot().send()
+        chain_id = await erpc.ethereum.rpc.eth_chain_id().send()
+        print(slot, chain_id)
+
+
+asyncio.run(main())
+```
+
+Both exact wire names (`getSlot`, `eth_chainId`) and Python snake-case aliases
+(`get_slot`, `eth_chain_id`) create inert requests. Network I/O starts only
+when `send()` is awaited. `request()` restricts calls to the namespace catalog;
+`raw()` is the forward-compatible escape hatch.
+
+## Namespaces
+
+| Namespace | Purpose |
+| --- | --- |
+| `erpc.solana.rpc` | Standard Solana JSON-RPC |
+| `erpc.solana.das` | Indexed assets and tokens |
+| `erpc.solana.history` | Address transactions and transfers |
+| `erpc.solana.leaders` | Leader slots and validator information |
+| `erpc.solana.analytics` | Epoch, slot, program, and TPS analytics |
+| `erpc.solana.subscriptions` | Enhanced WebSocket subscriptions |
+| `erpc.ethereum.rpc` | Standard Ethereum JSON-RPC |
+| `erpc.ethereum.subscriptions` | Ethereum WebSocket subscriptions |
+| `erpc.price` | Price metadata, updates, and SSE streams |
+| `erpc.account` | Token balance |
+| `erpc.usage` | Masked monthly API-key usage |
+
+## Intact batches
+
+```python
+results = await erpc.solana.rpc.batch([
+    {"method": "getSlot", "params": []},
+    {"method": "getBlockHeight", "params": []},
+]).send()
+```
+
+The SDK sends one caller batch as one server batch, restores caller order,
+accepts at most 256 calls, and rejects invalid mixed or unsupported batches
+locally. It never silently splits a batch.
+
+## Subscriptions
+
+```python
+subscription = await erpc.ethereum.subscriptions.subscribe("newHeads")
+async for header in subscription:
+    print(header)
+    await subscription.unsubscribe()
+    break
+```
+
+Solana exposes `account_subscribe`, `transaction_subscribe`, and
+`raw_subscribe`. HTTP requests accept a `RequestOptions(cancel_event=...)`;
+normal asyncio task cancellation is also preserved.
+
+## Cloud reads
+
+```python
+from erpc_sdk import ErpcCloudClient, ErpcCloudClientConfig
+
+async with ErpcCloudClient(ErpcCloudClientConfig(access_token)) as cloud:
+    offerings = await cloud.catalog.list()
+    resources = await cloud.resources.list()
+```
+
+Cloud configuration accepts HTTPS endpoints and localhost HTTP endpoints for
+testing. It retains only the access token supplied by the caller and does not
+implement interactive authorization or refresh-credential storage.
+
+## Safety boundaries
+
+- Credentials are redacted from configuration representations, public
+  endpoints, transport errors, and JSON-RPC error data.
+- State-changing calls, including transaction submission, are never retried.
+- REST, JSON-RPC, and caller batch boundaries remain explicit.
+- Unknown methods remain available through `raw()` without being included in
+  the typed compatibility catalog.

erpc_sdk-0.3.0/README.md

@@ -0,0 +1,101 @@
+# ERPC SDK for Python
+
+Async Python client for ERPC. It covers standard Solana and Ethereum JSON-RPC,
+indexed assets, history, leader and analytics RPC, WebSocket subscriptions,
+price REST and server-sent events, account usage, and scoped Cloud reads.
+
+```bash
+python -m pip install erpc-sdk
+```
+
+Python 3.11 or newer is required.
+
+## Quick start
+
+```python
+import asyncio
+import os
+
+from erpc_sdk import ErpcClient, ErpcClientConfig
+
+
+async def main() -> None:
+    async with ErpcClient(ErpcClientConfig(os.environ["ERPC_API_KEY"])) as erpc:
+        slot = await erpc.solana.rpc.get_slot().send()
+        chain_id = await erpc.ethereum.rpc.eth_chain_id().send()
+        print(slot, chain_id)
+
+
+asyncio.run(main())
+```
+
+Both exact wire names (`getSlot`, `eth_chainId`) and Python snake-case aliases
+(`get_slot`, `eth_chain_id`) create inert requests. Network I/O starts only
+when `send()` is awaited. `request()` restricts calls to the namespace catalog;
+`raw()` is the forward-compatible escape hatch.
+
+## Namespaces
+
+| Namespace | Purpose |
+| --- | --- |
+| `erpc.solana.rpc` | Standard Solana JSON-RPC |
+| `erpc.solana.das` | Indexed assets and tokens |
+| `erpc.solana.history` | Address transactions and transfers |
+| `erpc.solana.leaders` | Leader slots and validator information |
+| `erpc.solana.analytics` | Epoch, slot, program, and TPS analytics |
+| `erpc.solana.subscriptions` | Enhanced WebSocket subscriptions |
+| `erpc.ethereum.rpc` | Standard Ethereum JSON-RPC |
+| `erpc.ethereum.subscriptions` | Ethereum WebSocket subscriptions |
+| `erpc.price` | Price metadata, updates, and SSE streams |
+| `erpc.account` | Token balance |
+| `erpc.usage` | Masked monthly API-key usage |
+
+## Intact batches
+
+```python
+results = await erpc.solana.rpc.batch([
+    {"method": "getSlot", "params": []},
+    {"method": "getBlockHeight", "params": []},
+]).send()
+```
+
+The SDK sends one caller batch as one server batch, restores caller order,
+accepts at most 256 calls, and rejects invalid mixed or unsupported batches
+locally. It never silently splits a batch.
+
+## Subscriptions
+
+```python
+subscription = await erpc.ethereum.subscriptions.subscribe("newHeads")
+async for header in subscription:
+    print(header)
+    await subscription.unsubscribe()
+    break
+```
+
+Solana exposes `account_subscribe`, `transaction_subscribe`, and
+`raw_subscribe`. HTTP requests accept a `RequestOptions(cancel_event=...)`;
+normal asyncio task cancellation is also preserved.
+
+## Cloud reads
+
+```python
+from erpc_sdk import ErpcCloudClient, ErpcCloudClientConfig
+
+async with ErpcCloudClient(ErpcCloudClientConfig(access_token)) as cloud:
+    offerings = await cloud.catalog.list()
+    resources = await cloud.resources.list()
+```
+
+Cloud configuration accepts HTTPS endpoints and localhost HTTP endpoints for
+testing. It retains only the access token supplied by the caller and does not
+implement interactive authorization or refresh-credential storage.
+
+## Safety boundaries
+
+- Credentials are redacted from configuration representations, public
+  endpoints, transport errors, and JSON-RPC error data.
+- State-changing calls, including transaction submission, are never retried.
+- REST, JSON-RPC, and caller batch boundaries remain explicit.
+- Unknown methods remain available through `raw()` without being included in
+  the typed compatibility catalog.

erpc_sdk-0.3.0/pyproject.toml

@@ -0,0 +1,65 @@
+[build-system]
+requires = ["hatchling>=1.25,<1.28"]
+build-backend = "hatchling.build"
+
+[project]
+name = "erpc-sdk"
+version = "0.3.0"
+description = "Async Python SDK for ERPC"
+readme = "README.md"
+requires-python = ">=3.11"
+license = { file = "LICENSE" }
+authors = [{ name = "ELSOUL LABO B.V." }]
+keywords = ["erpc", "ethereum", "json-rpc", "rpc", "solana"]
+classifiers = [
+  "Development Status :: 4 - Beta",
+  "Framework :: AsyncIO",
+  "License :: OSI Approved :: MIT License",
+  "Programming Language :: Python :: 3 :: Only",
+  "Programming Language :: Python :: 3.11",
+  "Programming Language :: Python :: 3.12",
+  "Programming Language :: Python :: 3.13",
+  "Typing :: Typed",
+]
+dependencies = [
+  "httpx>=0.27,<1",
+  "websockets>=13,<17",
+]
+
+[project.optional-dependencies]
+dev = [
+  "build>=1.2,<2",
+  "mypy>=1.11,<2",
+  "pytest>=8,<10",
+  "pytest-asyncio>=0.24,<2",
+  "ruff>=0.8,<1",
+  "twine>=5,<7",
+]
+
+[project.urls]
+Documentation = "https://github.com/elsoul/erpc-sdk/tree/main/packages/python"
+Homepage = "https://erpc.global"
+Repository = "https://github.com/elsoul/erpc-sdk"
+
+[tool.hatch.build.targets.sdist]
+include = ["/src", "/tests", "/LICENSE", "/README.md", "/pyproject.toml"]
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/erpc_sdk"]
+
+[tool.mypy]
+python_version = "3.11"
+strict = true
+packages = ["erpc_sdk"]
+mypy_path = "src"
+
+[tool.pytest.ini_options]
+asyncio_mode = "auto"
+testpaths = ["tests"]
+
+[tool.ruff]
+line-length = 100
+target-version = "py311"
+
+[tool.ruff.lint]
+select = ["B", "E", "F", "I", "UP"]

erpc_sdk-0.3.0/src/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-0.3.0/src/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)