synapse-filecoin-sdk 0.1.0__py3-none-any.whl

pynapse/synapse.py

@@ -0,0 +1,191 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Optional
+
+from eth_account import Account
+from web3 import AsyncWeb3, Web3
+
+from pynapse.core.chains import CALIBRATION, MAINNET, Chain, as_chain
+from pynapse.evm import AsyncEVMClient, SyncEVMClient
+from pynapse.payments import AsyncPaymentsService, SyncPaymentsService
+from pynapse.filbeam import FilBeamService
+from pynapse.retriever import ChainRetriever, AsyncChainRetriever
+from pynapse.session import AsyncSessionKeyRegistry, SyncSessionKeyRegistry
+from pynapse.storage import StorageManager, AsyncStorageManager
+from pynapse.sp_registry import AsyncSPRegistryService, SyncSPRegistryService
+from pynapse.warm_storage import AsyncWarmStorageService, SyncWarmStorageService
+
+
+class Synapse:
+    def __init__(self, web3: Web3, chain: Chain, account_address: str, private_key: Optional[str] = None) -> None:
+        self._web3 = web3
+        self._chain = chain
+        self._account = account_address
+        self._private_key = private_key
+        self._payments = SyncPaymentsService(web3, chain, account_address, private_key)
+        self._providers = SyncSPRegistryService(web3, chain, private_key)
+        self._warm_storage = SyncWarmStorageService(web3, chain, private_key)
+        # Create retriever for SP-agnostic downloads
+        self._retriever = ChainRetriever(self._warm_storage, self._providers)
+        # Wire up storage manager with warm_storage, sp_registry, and retriever
+        self._storage = StorageManager(
+            chain=chain,
+            private_key=private_key,
+            sp_registry=self._providers,
+            warm_storage=self._warm_storage,
+            retriever=self._retriever,
+        )
+        self._session_registry = SyncSessionKeyRegistry(web3, chain, private_key)
+        self._filbeam = FilBeamService(chain)
+
+    @classmethod
+    def create(cls, rpc_url: str, chain: Chain | str | int = CALIBRATION, private_key: Optional[str] = None) -> "Synapse":
+        client = SyncEVMClient.from_rpc_url(rpc_url)
+        chain_obj = as_chain(chain)
+        if private_key is None:
+            raise ValueError("private_key required to create Synapse")
+        account = Account.from_key(private_key)
+        return cls(client.web3, chain_obj, account.address, private_key)
+
+    @property
+    def web3(self) -> Web3:
+        return self._web3
+
+    @property
+    def chain(self) -> Chain:
+        return self._chain
+
+    @property
+    def account(self) -> str:
+        return self._account
+
+    @property
+    def payments(self) -> SyncPaymentsService:
+        return self._payments
+
+    @property
+    def providers(self) -> SyncSPRegistryService:
+        return self._providers
+
+    @property
+    def warm_storage(self) -> SyncWarmStorageService:
+        return self._warm_storage
+
+    @property
+    def storage(self) -> StorageManager:
+        return self._storage
+
+    @property
+    def session_registry(self) -> SyncSessionKeyRegistry:
+        return self._session_registry
+
+    @property
+    def filbeam(self) -> FilBeamService:
+        return self._filbeam
+
+    @property
+    def retriever(self) -> ChainRetriever:
+        return self._retriever
+
+
+class AsyncSynapse:
+    """
+    Async Synapse client for Filecoin Onchain Cloud.
+    
+    Provides full async/await support for Python async applications.
+    
+    Example:
+        synapse = await AsyncSynapse.create(rpc_url, chain, private_key)
+        
+        # Upload data
+        result = await synapse.storage.upload(data)
+        
+        # Download data
+        data = await synapse.storage.download(piece_cid)
+    """
+    
+    def __init__(self, web3: AsyncWeb3, chain: Chain, account_address: str, private_key: Optional[str] = None) -> None:
+        self._web3 = web3
+        self._chain = chain
+        self._account = account_address
+        self._private_key = private_key
+        self._payments = AsyncPaymentsService(web3, chain, account_address, private_key)
+        self._providers = AsyncSPRegistryService(web3, chain, private_key)
+        self._warm_storage = AsyncWarmStorageService(web3, chain, private_key)
+        # Create async retriever for SP-agnostic downloads
+        self._retriever = AsyncChainRetriever(self._warm_storage, self._providers)
+        # Wire up async storage manager with warm_storage, sp_registry, and retriever
+        self._storage = AsyncStorageManager(
+            chain=chain,
+            private_key=private_key,
+            sp_registry=self._providers,
+            warm_storage=self._warm_storage,
+            retriever=self._retriever,
+        )
+        self._session_registry = AsyncSessionKeyRegistry(web3, chain, private_key)
+        self._filbeam = FilBeamService(chain)
+
+    @classmethod
+    async def create(
+        cls, rpc_url: str, chain: Chain | str | int = CALIBRATION, private_key: Optional[str] = None
+    ) -> "AsyncSynapse":
+        """
+        Create an async Synapse client.
+        
+        Args:
+            rpc_url: RPC URL for the Filecoin chain
+            chain: Chain configuration (CALIBRATION, MAINNET, or chain ID)
+            private_key: Private key for signing transactions
+            
+        Returns:
+            Configured AsyncSynapse instance
+        """
+        client = AsyncEVMClient.from_rpc_url(rpc_url)
+        chain_obj = as_chain(chain)
+        if private_key is None:
+            raise ValueError("private_key required to create AsyncSynapse")
+        account = Account.from_key(private_key)
+        return cls(client.web3, chain_obj, account.address, private_key)
+
+    @property
+    def web3(self) -> AsyncWeb3:
+        return self._web3
+
+    @property
+    def chain(self) -> Chain:
+        return self._chain
+
+    @property
+    def account(self) -> str:
+        return self._account
+
+    @property
+    def payments(self) -> AsyncPaymentsService:
+        return self._payments
+
+    @property
+    def providers(self) -> AsyncSPRegistryService:
+        return self._providers
+
+    @property
+    def warm_storage(self) -> AsyncWarmStorageService:
+        return self._warm_storage
+
+    @property
+    def storage(self) -> AsyncStorageManager:
+        """Get the async storage manager for upload/download operations."""
+        return self._storage
+
+    @property
+    def session_registry(self) -> AsyncSessionKeyRegistry:
+        return self._session_registry
+
+    @property
+    def filbeam(self) -> FilBeamService:
+        return self._filbeam
+
+    @property
+    def retriever(self) -> AsyncChainRetriever:
+        """Get the async retriever for SP-agnostic downloads."""
+        return self._retriever

pynapse/utils/__init__.py

@@ -0,0 +1,25 @@
+from .constants import METADATA_KEYS, SIZE_CONSTANTS, TIME_CONSTANTS, TIMING_CONSTANTS, TOKENS
+from .errors import SynapseError, create_error
+from .metadata import (
+    combine_metadata,
+    metadata_array_to_object,
+    metadata_matches,
+    metadata_object_to_entries,
+)
+from .piece_url import create_piece_url, create_piece_url_pdp
+
+__all__ = [
+    "METADATA_KEYS",
+    "SIZE_CONSTANTS",
+    "TIME_CONSTANTS",
+    "TIMING_CONSTANTS",
+    "TOKENS",
+    "SynapseError",
+    "create_error",
+    "combine_metadata",
+    "metadata_matches",
+    "metadata_array_to_object",
+    "metadata_object_to_entries",
+    "create_piece_url",
+    "create_piece_url_pdp",
+]

pynapse/utils/constants.py

@@ -0,0 +1,25 @@
+from pynapse.core.constants import SIZE_CONSTANTS, TIME_CONSTANTS
+
+TOKENS = {
+    "USDFC": "USDFC",
+    "FIL": "FIL",
+}
+
+METADATA_KEYS = {
+    "WITH_CDN": "withCDN",
+    "WITH_IPFS_INDEXING": "withIPFSIndexing",
+    "IPFS_ROOT_CID": "ipfsRootCID",
+}
+
+TIMING_CONSTANTS = {
+    "TRANSACTION_PROPAGATION_TIMEOUT_MS": 180000,
+    "TRANSACTION_PROPAGATION_POLL_INTERVAL_MS": 2000,
+    "DATA_SET_CREATION_TIMEOUT_MS": 7 * 60 * 1000,
+    "DATA_SET_CREATION_POLL_INTERVAL_MS": 2000,
+    "PIECE_PARKING_TIMEOUT_MS": 7 * 60 * 1000,
+    "PIECE_PARKING_POLL_INTERVAL_MS": 5000,
+    "TRANSACTION_CONFIRMATIONS": 1,
+    "PERMIT_DEADLINE_DURATION": 3600,
+    "PIECE_ADDITION_TIMEOUT_MS": 7 * 60 * 1000,
+    "PIECE_ADDITION_POLL_INTERVAL_MS": 1000,
+}

pynapse/utils/errors.py

@@ -0,0 +1,3 @@
+from pynapse.core.errors import SynapseError, create_error
+
+__all__ = ["SynapseError", "create_error"]

pynapse/utils/metadata.py

@@ -0,0 +1,35 @@
+from __future__ import annotations
+
+from typing import Dict
+
+from .constants import METADATA_KEYS
+
+
+def metadata_matches(data_set_metadata: Dict[str, str], requested_metadata: Dict[str, str]) -> bool:
+    if len(data_set_metadata) != len(requested_metadata):
+        return False
+    if not requested_metadata:
+        return True
+    for key, value in requested_metadata.items():
+        if data_set_metadata.get(key) != value:
+            return False
+    return True
+
+
+def combine_metadata(metadata: Dict[str, str] | None = None, with_cdn: bool | None = None) -> Dict[str, str]:
+    metadata = metadata or {}
+    if with_cdn is None or METADATA_KEYS["WITH_CDN"] in metadata:
+        return metadata
+    if with_cdn:
+        combined = dict(metadata)
+        combined[METADATA_KEYS["WITH_CDN"]] = ""
+        return combined
+    return metadata
+
+
+def metadata_array_to_object(entries: list[tuple[str, str]]) -> Dict[str, str]:
+    return {key: value for key, value in entries}
+
+
+def metadata_object_to_entries(metadata: Dict[str, str]) -> list[dict[str, str]]:
+    return [{"key": key, "value": value} for key, value in metadata.items()]

pynapse/utils/piece_url.py

@@ -0,0 +1,16 @@
+from __future__ import annotations
+
+from urllib.parse import urljoin
+
+from pynapse.core.chains import Chain
+
+
+def create_piece_url_pdp(cid: str, pdp_url: str) -> str:
+    return urljoin(pdp_url.rstrip("/") + "/", f"piece/{cid}")
+
+
+def create_piece_url(cid: str, cdn: bool, address: str, chain: Chain, pdp_url: str) -> str:
+    if cdn and chain.filbeam_domain:
+        endpoint = f"https://{address}.{chain.filbeam_domain}"
+        return urljoin(endpoint + "/", cid)
+    return create_piece_url_pdp(cid, pdp_url)

pynapse/warm_storage/__init__.py

@@ -0,0 +1,13 @@
+from .service import (
+    AsyncWarmStorageService,
+    DataSetInfo,
+    EnhancedDataSetInfo,
+    SyncWarmStorageService,
+)
+
+__all__ = [
+    "AsyncWarmStorageService",
+    "SyncWarmStorageService",
+    "DataSetInfo",
+    "EnhancedDataSetInfo",
+]