synapse-filecoin-sdk 0.1.1__tar.gz → 0.2.0__tar.gz

{synapse_filecoin_sdk-0.1.1 → synapse_filecoin_sdk-0.2.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: synapse-filecoin-sdk
-Version: 0.1.1
+Version: 0.2.0
 Summary: Python SDK for Filecoin Onchain Cloud (Synapse)
 Project-URL: Homepage, https://github.com/anjor/pynapse
 Project-URL: Repository, https://github.com/anjor/pynapse
@@ -18,6 +18,8 @@ Requires-Python: >=3.11
 Requires-Dist: httpx<0.28.0,>=0.25.0
 Requires-Dist: multiformats<0.4.0,>=0.3.1
 Requires-Dist: web3<7,>=6.0.0
+Provides-Extra: langchain
+Requires-Dist: langchain-core<0.4,>=0.1.0; extra == 'langchain'
 Provides-Extra: test
 Requires-Dist: pytest-asyncio<0.24,>=0.23.0; extra == 'test'
 Requires-Dist: pytest<9,>=8.0.0; extra == 'test'
@@ -49,6 +51,30 @@ Python import: `pynapse`
 pip install synapse-filecoin-sdk
 ```
 
+## Supported Networks
+
+Both **Filecoin Mainnet** and **Calibration testnet** are supported:
+
+```python
+from pynapse import AsyncSynapse
+
+# Mainnet
+synapse = await AsyncSynapse.create(
+    rpc_url="https://api.node.glif.io/rpc/v1",
+    chain="mainnet",
+    private_key=PRIVATE_KEY
+)
+
+# Calibration testnet (for testing)
+synapse = await AsyncSynapse.create(
+    rpc_url="https://api.calibration.node.glif.io/rpc/v1",
+    chain="calibration",
+    private_key=PRIVATE_KEY
+)
+```
+
+See [QUICKSTART.md](QUICKSTART.md) for a full tutorial using Calibration testnet.
+
 ## CommP / PieceCID
 
 `pynapse` uses `stream-commp` from `go-fil-commp-hashhash` for PieceCID calculation.
@@ -88,8 +114,8 @@ Publishing is automated via GitHub Actions in `.github/workflows/publish-pypi.ym
 3. Tag a release and push the tag:
 
 ```bash
-git tag v0.1.1
-git push origin v0.1.1
+git tag v0.2.0
+git push origin v0.2.0
 ```
 
 The workflow builds the package, runs `twine check`, and publishes to PyPI via OIDC (no API token required).

{synapse_filecoin_sdk-0.1.1 → synapse_filecoin_sdk-0.2.0}/README.md

@@ -24,6 +24,30 @@ Python import: `pynapse`
 pip install synapse-filecoin-sdk
 ```
 
+## Supported Networks
+
+Both **Filecoin Mainnet** and **Calibration testnet** are supported:
+
+```python
+from pynapse import AsyncSynapse
+
+# Mainnet
+synapse = await AsyncSynapse.create(
+    rpc_url="https://api.node.glif.io/rpc/v1",
+    chain="mainnet",
+    private_key=PRIVATE_KEY
+)
+
+# Calibration testnet (for testing)
+synapse = await AsyncSynapse.create(
+    rpc_url="https://api.calibration.node.glif.io/rpc/v1",
+    chain="calibration",
+    private_key=PRIVATE_KEY
+)
+```
+
+See [QUICKSTART.md](QUICKSTART.md) for a full tutorial using Calibration testnet.
+
 ## CommP / PieceCID
 
 `pynapse` uses `stream-commp` from `go-fil-commp-hashhash` for PieceCID calculation.
@@ -63,8 +87,8 @@ Publishing is automated via GitHub Actions in `.github/workflows/publish-pypi.ym
 3. Tag a release and push the tag:
 
 ```bash
-git tag v0.1.1
-git push origin v0.1.1
+git tag v0.2.0
+git push origin v0.2.0
 ```
 
 The workflow builds the package, runs `twine check`, and publishes to PyPI via OIDC (no API token required).

synapse_filecoin_sdk-0.2.0/full_demo.py

@@ -0,0 +1,224 @@
+#!/usr/bin/env python3
+"""
+pynapse Full Demo - Complete end-to-end test on Filecoin Calibration
+Handles all setup steps: deposit, service approval, then upload/download
+"""
+import asyncio
+import sys
+from web3 import AsyncWeb3
+from eth_account import Account
+
+# Demo wallet (Calibration testnet only)
+PRIVATE_KEY = "0x7666381bff20b2f0819c77d3846b1d22637be4996012aaaff25e8b93f73a6985"
+RPC_URL = "https://api.calibration.node.glif.io/rpc/v1"
+CHAIN_ID = 314159
+
+# Contract addresses (Calibration)
+USDFC = "0xb3042734b608a1B16e9e86B374A3f3e389B4cDf0"
+PAYMENTS = "0x09a0fDc2723fAd1A7b8e3e00eE5DF73841df55a0"  # FilecoinPay (updated by sub-agent)
+FWSS = "0x02925630df557F957f70E112bA06e50965417CA0"  # WarmStorage service
+
+# ABIs
+ERC20_ABI = [
+    {'inputs': [{'name': 'account', 'type': 'address'}], 'name': 'balanceOf', 'outputs': [{'name': '', 'type': 'uint256'}], 'stateMutability': 'view', 'type': 'function'},
+    {'inputs': [{'name': 'spender', 'type': 'address'}, {'name': 'amount', 'type': 'uint256'}], 'name': 'approve', 'outputs': [{'name': '', 'type': 'bool'}], 'stateMutability': 'nonpayable', 'type': 'function'},
+    {'inputs': [{'name': 'owner', 'type': 'address'}, {'name': 'spender', 'type': 'address'}], 'name': 'allowance', 'outputs': [{'name': '', 'type': 'uint256'}], 'stateMutability': 'view', 'type': 'function'},
+]
+
+PAYMENTS_ABI = [
+    # accounts(token, account) returns (funds, lockupCurrent, lockupRate, lockupLastSettledAt)
+    {'inputs': [{'name': 'token', 'type': 'address'}, {'name': 'account', 'type': 'address'}], 'name': 'accounts', 'outputs': [{'name': 'funds', 'type': 'uint256'}, {'name': 'lockupCurrent', 'type': 'uint256'}, {'name': 'lockupRate', 'type': 'uint256'}, {'name': 'lockupLastSettledAt', 'type': 'uint256'}], 'stateMutability': 'view', 'type': 'function'},
+    {'inputs': [{'name': 'token', 'type': 'address'}, {'name': 'to', 'type': 'address'}, {'name': 'amount', 'type': 'uint256'}], 'name': 'deposit', 'outputs': [], 'stateMutability': 'nonpayable', 'type': 'function'},
+    # operatorApprovals(token, client, operator) - note: 3 args not 2
+    {'inputs': [{'name': 'token', 'type': 'address'}, {'name': 'client', 'type': 'address'}, {'name': 'operator', 'type': 'address'}], 'name': 'operatorApprovals', 'outputs': [{'name': 'approved', 'type': 'bool'}, {'name': 'rateAllowance', 'type': 'uint256'}, {'name': 'lockupAllowance', 'type': 'uint256'}, {'name': 'rateUsage', 'type': 'uint256'}, {'name': 'lockupUsage', 'type': 'uint256'}, {'name': 'maxLockupPeriod', 'type': 'uint256'}], 'stateMutability': 'view', 'type': 'function'},
+    {'inputs': [{'name': 'token', 'type': 'address'}, {'name': 'operator', 'type': 'address'}, {'name': 'approved', 'type': 'bool'}, {'name': 'rateAllowance', 'type': 'uint256'}, {'name': 'lockupAllowance', 'type': 'uint256'}, {'name': 'maxLockupPeriod', 'type': 'uint256'}], 'name': 'setOperatorApproval', 'outputs': [], 'stateMutability': 'nonpayable', 'type': 'function'},
+]
+
+
+async def send_tx(w3, account, tx_data, description):
+    """Send a transaction with proper Filecoin gas handling"""
+    print(f"  → {description}...")
+    
+    nonce = await w3.eth.get_transaction_count(account.address)
+    
+    # Get gas estimate
+    try:
+        gas = await w3.eth.estimate_gas({**tx_data, 'from': account.address})
+        gas = int(gas * 1.2)  # 20% buffer
+    except Exception as e:
+        print(f"    Gas estimate failed: {e}")
+        gas = 30000000
+    
+    # Build transaction with EIP-1559 style fees for Filecoin
+    base_fee = await w3.eth.gas_price
+    
+    tx = {
+        **tx_data,
+        'from': account.address,
+        'nonce': nonce,
+        'gas': gas,
+        'maxFeePerGas': base_fee * 2,
+        'maxPriorityFeePerGas': base_fee,
+        'chainId': CHAIN_ID,
+    }
+    
+    signed = account.sign_transaction(tx)
+    tx_hash = await w3.eth.send_raw_transaction(signed.rawTransaction)
+    print(f"    Tx: {tx_hash.hex()[:20]}...")
+    
+    receipt = await w3.eth.wait_for_transaction_receipt(tx_hash, timeout=120)
+    if receipt.status == 1:
+        print(f"    ✅ Success (gas: {receipt.gasUsed:,})")
+        return True
+    else:
+        print(f"    ❌ Failed")
+        return False
+
+
+async def main():
+    print("=" * 60)
+    print("pynapse Full Demo - Filecoin Calibration Testnet")
+    print("=" * 60)
+    
+    # Connect
+    w3 = AsyncWeb3(AsyncWeb3.AsyncHTTPProvider(RPC_URL))
+    account = Account.from_key(PRIVATE_KEY)
+    print(f"\nWallet: {account.address}")
+    
+    usdfc = w3.eth.contract(address=USDFC, abi=ERC20_ABI)
+    payments = w3.eth.contract(address=PAYMENTS, abi=PAYMENTS_ABI)
+    
+    # Check balances
+    print("\n[1/5] Checking balances...")
+    fil_balance = await w3.eth.get_balance(account.address)
+    usdfc_balance = await usdfc.functions.balanceOf(account.address).call()
+    print(f"  FIL: {fil_balance / 1e18:.4f} tFIL")
+    print(f"  USDFC (wallet): {usdfc_balance / 1e18:.2f}")
+    
+    if fil_balance < 1e18:
+        print("\n❌ Need more tFIL for gas. Get from: https://faucet.calibnet.chainsafe-fil.io/")
+        return
+    
+    # Check payments contract balance using accounts(token, account)
+    try:
+        funds, _, _, _ = await payments.functions.accounts(USDFC, account.address).call()
+        payments_balance = int(funds)
+        print(f"  USDFC (payments): {payments_balance / 1e18:.2f}")
+    except Exception as e:
+        payments_balance = 0
+        print(f"  USDFC (payments): 0 (query failed: {e})")
+    
+    # Check if we have enough funds (either in wallet or already deposited)
+    total_usdfc = usdfc_balance + payments_balance
+    if total_usdfc < 10e18:
+        print(f"\n❌ Need more USDFC. Total: {total_usdfc / 1e18:.2f}, need at least 10")
+        print("   Mint at: https://stg.usdfc.net")
+        return
+    
+    # Step 2: Approve USDFC for payments contract (only if we have wallet USDFC)
+    print("\n[2/5] Checking USDFC allowance...")
+    if usdfc_balance > 0:
+        allowance = await usdfc.functions.allowance(account.address, PAYMENTS).call()
+        print(f"  Current allowance: {allowance / 1e18:.2f}")
+        
+        if allowance < usdfc_balance:
+            print("  Need to approve...")
+            tx_data = await usdfc.functions.approve(PAYMENTS, 2**256 - 1).build_transaction({'from': account.address})
+            if not await send_tx(w3, account, tx_data, "Approving USDFC"):
+                return
+        else:
+            print("  ✅ Already approved")
+    else:
+        print("  ✅ Skipped (no wallet USDFC to approve)")
+    
+    # Step 3: Deposit USDFC to payments (only if we need more and have wallet USDFC)
+    print("\n[3/5] Depositing USDFC to payments contract...")
+    min_required = int(10e18)  # Need at least 10 USDFC
+    
+    if payments_balance >= min_required:
+        print(f"  ✅ Already have {payments_balance/1e18:.2f} USDFC deposited")
+    elif usdfc_balance > 0:
+        deposit_amount = min(usdfc_balance, int(50e18))  # Deposit up to 50 USDFC
+        tx_data = await payments.functions.deposit(USDFC, account.address, deposit_amount).build_transaction({'from': account.address})
+        if not await send_tx(w3, account, tx_data, f"Depositing {deposit_amount/1e18:.0f} USDFC"):
+            print("  ⚠️ Deposit failed - may need different approach")
+        # Refresh payments balance
+        payments_balance = await payments.functions.balanceOf(USDFC).call({'from': account.address})
+    else:
+        print("  ⚠️ No wallet USDFC to deposit, hoping payments balance is sufficient")
+    
+    # Step 4: Approve FWSS service
+    print("\n[4/5] Checking FWSS operator approval...")
+    try:
+        # operatorApprovals(token, client, operator)
+        approval = await payments.functions.operatorApprovals(USDFC, account.address, FWSS).call()
+        is_approved = approval[0]
+        print(f"  Approved: {is_approved}")
+    except Exception as e:
+        is_approved = False
+        print(f"  Query failed: {e}")
+    
+    if not is_approved:
+        print("  Need to approve operator...")
+        # Approve with generous limits
+        rate_allowance = int(1e24)  # Large allowance
+        lockup_allowance = int(1e24)
+        max_lockup_period = 365 * 24 * 60 * 60  # 1 year in seconds
+        
+        tx_data = await payments.functions.setOperatorApproval(
+            USDFC, FWSS, True, rate_allowance, lockup_allowance, max_lockup_period
+        ).build_transaction({'from': account.address})
+        if not await send_tx(w3, account, tx_data, "Approving FWSS operator"):
+            print("  ⚠️ Operator approval failed")
+    else:
+        print("  ✅ Operator already approved")
+    
+    # Step 5: Try upload with pynapse
+    print("\n[5/5] Testing pynapse upload...")
+    try:
+        from pynapse import AsyncSynapse
+        
+        synapse = await AsyncSynapse.create(
+            rpc_url=RPC_URL,
+            chain='calibration',
+            private_key=PRIVATE_KEY
+        )
+        
+        print(f"  Connected as {synapse.account}")
+        
+        # Check storage providers
+        info = await synapse.storage.get_storage_info()
+        providers = getattr(info, 'providers', [])
+        print(f"  Found {len(providers)} storage providers")
+        
+        if not providers:
+            print("  ❌ No providers available")
+            return
+        
+        # Try to create context and upload
+        test_data = b"Hello from pynapse! " + bytes(range(256)) * 10
+        print(f"  Uploading {len(test_data)} bytes...")
+        
+        ctx = await synapse.storage.get_context()
+        piece_cid = await ctx.upload(test_data)
+        print(f"  ✅ Uploaded! PieceCID: {piece_cid}")
+        
+        # Download and verify
+        print("  Downloading...")
+        downloaded = await synapse.storage.download(piece_cid)
+        if downloaded == test_data:
+            print("  ✅ Download verified!")
+        else:
+            print(f"  ⚠️ Data mismatch")
+        
+        print("\n" + "=" * 60)
+        print("🎉 pynapse is working end-to-end!")
+        print("=" * 60)
+        
+    except Exception as e:
+        print(f"  ❌ Upload failed: {e}")
+        print("\n  This may need additional debugging.")
+
+
+if __name__ == "__main__":
+    asyncio.run(main())

{synapse_filecoin_sdk-0.1.1 → synapse_filecoin_sdk-0.2.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "synapse-filecoin-sdk"
-version = "0.1.1"
+version = "0.2.0"
 description = "Python SDK for Filecoin Onchain Cloud (Synapse)"
 readme = "README.md"
 requires-python = ">=3.11"
@@ -32,6 +32,9 @@ test = [
   "pytest>=8.0.0,<9",
   "pytest-asyncio>=0.23.0,<0.24"
 ]
+langchain = [
+  "langchain-core>=0.1.0,<0.4"
+]
 
 [build-system]
 requires = ["hatchling"]

synapse_filecoin_sdk-0.2.0/src/pynapse/_version.py

@@ -0,0 +1 @@
+__version__ = "0.2.0"

synapse_filecoin_sdk-0.2.0/src/pynapse/integrations/__init__.py

@@ -0,0 +1,4 @@
+"""Pynapse integrations with third-party libraries."""
+
+# LangChain integration is optional - import directly from langchain module
+# from pynapse.integrations.langchain import FilecoinDocumentLoader, FilecoinStorageTool

synapse_filecoin_sdk-0.2.0/src/pynapse/integrations/langchain.py

@@ -0,0 +1,214 @@
+"""
+LangChain integration for pynapse.
+
+This module provides LangChain-compatible components for storing and loading
+documents on Filecoin via the Synapse SDK.
+
+Installation:
+    pip install synapse-filecoin-sdk[langchain]
+
+Usage:
+    from pynapse.integrations.langchain import FilecoinDocumentLoader, FilecoinStorageTool
+    
+    # Load documents from Filecoin
+    loader = FilecoinDocumentLoader(
+        rpc_url="https://api.node.glif.io/rpc/v1",
+        chain="mainnet",
+        private_key=PRIVATE_KEY
+    )
+    docs = await loader.aload(piece_cid="baga6ea4seaq...")
+    
+    # Store documents on Filecoin (as a LangChain tool for agents)
+    tool = FilecoinStorageTool(
+        rpc_url="https://api.node.glif.io/rpc/v1",
+        chain="mainnet",
+        private_key=PRIVATE_KEY
+    )
+    result = await tool._arun(content="Hello, Filecoin!")
+"""
+
+from __future__ import annotations
+
+import asyncio
+from typing import Any, Dict, List, Optional, Type
+
+try:
+    from langchain_core.documents import Document
+    from langchain_core.document_loaders import BaseLoader
+    from langchain_core.tools import BaseTool
+    from pydantic import BaseModel, Field
+except ImportError as e:
+    raise ImportError(
+        "LangChain dependencies not installed. "
+        "Install with: pip install synapse-filecoin-sdk[langchain]"
+    ) from e
+
+from pynapse import AsyncSynapse
+
+
+class FilecoinDocumentLoader(BaseLoader):
+    """Load documents from Filecoin using pynapse.
+    
+    This loader retrieves data stored on Filecoin by Piece CID and converts
+    it into LangChain Document objects.
+    
+    Example:
+        loader = FilecoinDocumentLoader(
+            rpc_url="https://api.node.glif.io/rpc/v1",
+            chain="mainnet",
+            private_key="0x..."
+        )
+        docs = await loader.aload(piece_cid="baga6ea4seaq...")
+    """
+    
+    def __init__(
+        self,
+        rpc_url: str,
+        chain: str = "mainnet",
+        private_key: Optional[str] = None,
+    ):
+        """Initialize the Filecoin document loader.
+        
+        Args:
+            rpc_url: RPC URL for Filecoin node
+            chain: Network name ("mainnet" or "calibration")
+            private_key: Wallet private key (optional for read-only operations)
+        """
+        self.rpc_url = rpc_url
+        self.chain = chain
+        self.private_key = private_key
+        self._synapse: Optional[AsyncSynapse] = None
+    
+    async def _get_synapse(self) -> AsyncSynapse:
+        """Get or create AsyncSynapse instance."""
+        if self._synapse is None:
+            self._synapse = await AsyncSynapse.create(
+                rpc_url=self.rpc_url,
+                chain=self.chain,
+                private_key=self.private_key,
+            )
+        return self._synapse
+    
+    def load(self) -> List[Document]:
+        """Synchronous load - not supported, use aload instead."""
+        raise NotImplementedError(
+            "FilecoinDocumentLoader is async-only. Use aload() instead."
+        )
+    
+    async def aload(self, piece_cid: str) -> List[Document]:
+        """Load a document from Filecoin by Piece CID.
+        
+        Args:
+            piece_cid: The Piece CID of the stored data
+            
+        Returns:
+            List containing a single Document with the retrieved content
+        """
+        synapse = await self._get_synapse()
+        ctx = await synapse.storage.get_context()
+        
+        # Download the data
+        data = await ctx.download(piece_cid)
+        
+        # Try to decode as text, fall back to repr for binary
+        try:
+            content = data.decode("utf-8")
+        except UnicodeDecodeError:
+            content = repr(data)
+        
+        return [
+            Document(
+                page_content=content,
+                metadata={
+                    "source": f"filecoin://{piece_cid}",
+                    "piece_cid": piece_cid,
+                    "chain": self.chain,
+                    "size": len(data),
+                }
+            )
+        ]
+
+
+class FilecoinStorageInput(BaseModel):
+    """Input schema for FilecoinStorageTool."""
+    content: str = Field(description="The text content to store on Filecoin")
+
+
+class FilecoinStorageTool(BaseTool):
+    """LangChain tool for storing data on Filecoin.
+    
+    This tool allows LangChain agents to store arbitrary text content on
+    Filecoin and returns the Piece CID for later retrieval.
+    
+    Example:
+        tool = FilecoinStorageTool(
+            rpc_url="https://api.node.glif.io/rpc/v1",
+            chain="mainnet",
+            private_key="0x..."
+        )
+        # Use in an agent or call directly
+        result = await tool._arun(content="Store this on Filecoin!")
+    """
+    
+    name: str = "filecoin_storage"
+    description: str = (
+        "Store text content on Filecoin decentralized storage. "
+        "Returns the Piece CID which can be used to retrieve the content later. "
+        "Use this when you need to permanently store data on decentralized storage."
+    )
+    args_schema: Type[BaseModel] = FilecoinStorageInput
+    
+    rpc_url: str
+    chain: str = "mainnet"
+    private_key: str
+    _synapse: Optional[AsyncSynapse] = None
+    
+    class Config:
+        arbitrary_types_allowed = True
+    
+    async def _get_synapse(self) -> AsyncSynapse:
+        """Get or create AsyncSynapse instance."""
+        if self._synapse is None:
+            self._synapse = await AsyncSynapse.create(
+                rpc_url=self.rpc_url,
+                chain=self.chain,
+                private_key=self.private_key,
+            )
+        return self._synapse
+    
+    def _run(self, content: str) -> str:
+        """Synchronous run - wraps async implementation."""
+        return asyncio.run(self._arun(content=content))
+    
+    async def _arun(self, content: str) -> str:
+        """Store content on Filecoin and return the Piece CID.
+        
+        Args:
+            content: Text content to store
+            
+        Returns:
+            JSON string with piece_cid, size, and tx_hash
+        """
+        synapse = await self._get_synapse()
+        ctx = await synapse.storage.get_context()
+        
+        # Encode content and ensure minimum size (256 bytes)
+        data = content.encode("utf-8")
+        if len(data) < 256:
+            data = data + b'\x00' * (256 - len(data))
+        
+        # Upload to Filecoin
+        result = await ctx.upload(data)
+        
+        return (
+            f'{{"piece_cid": "{result.piece_cid}", '
+            f'"size": {result.size}, '
+            f'"tx_hash": "{result.tx_hash}"}}'
+        )
+
+
+__all__ = [
+    "FilecoinDocumentLoader",
+    "FilecoinStorageTool",
+    "FilecoinStorageInput",
+]