wayfinder-paths 0.1.3__py3-none-any.whl → 0.1.5__py3-none-any.whl

wayfinder_paths/core/clients/LedgerClient.py

@@ -1,86 +1,244 @@
-from typing import Any
+from __future__ import annotations
 
-from wayfinder_paths.core.clients.AuthClient import AuthClient
-from wayfinder_paths.core.clients.WayfinderClient import WayfinderClient
-from wayfinder_paths.core.settings import settings
+import asyncio
+import json
+import uuid
+from datetime import UTC, datetime
+from pathlib import Path
+from typing import Any, NotRequired, Required, TypedDict
 
+from wayfinder_paths.core.adapters.models import Operation
 
-class LedgerClient(WayfinderClient):
+
+class StrategyTransaction(TypedDict):
+    """Individual strategy transaction structure"""
+
+    id: Required[str]
+    operation: Required[str]
+    timestamp: Required[str]
+    amount: Required[str]
+    token_address: Required[str]
+    usd_value: Required[str]
+    strategy_name: NotRequired[str | None]
+    chain_id: NotRequired[int | None]
+
+
+class StrategyTransactionList(TypedDict):
+    """Vault transaction list response structure"""
+
+    transactions: Required[list[StrategyTransaction]]
+    total: Required[int]
+    limit: Required[int]
+    offset: Required[int]
+
+
+class NetDeposit(TypedDict):
+    """Net deposit response structure"""
+
+    net_deposit: Required[str]
+    total_deposits: Required[str]
+    total_withdrawals: Required[str]
+    wallet_address: NotRequired[str | None]
+
+
+class TransactionRecord(TypedDict):
+    """Transaction record response structure"""
+
+    transaction_id: Required[str]
+    status: Required[str]
+    timestamp: Required[str]
+
+
+class LedgerClient:
     """
-    Client for vault transaction history and bookkeeping operations.
+    Client for strategy transaction history and bookkeeping operations using local JSON files.
 
     Supports:
-    - GET vault transactions
-    - GET vault net deposit
-    - GET vault last rotation time
+    - GET strategy transactions
+    - GET strategy net deposit
+    - GET strategy latest transactions
     - POST add deposit
     - POST add withdraw
     - POST add operation
-    - POST add cashflow
+    - POST record snapshot
     """
 
-    def __init__(self, api_key: str | None = None) -> None:
-        super().__init__(api_key=api_key)
-        self.api_base_url = f"{settings.WAYFINDER_API_URL}"
-        self._auth_client: AuthClient | None = AuthClient(api_key=api_key)
+    def __init__(
+        self, api_key: str | None = None, ledger_dir: Path | str | None = None
+    ) -> None:
+        """
+        Initialize the ledger client.
+
+        Args:
+            api_key: Unused, kept for backward compatibility
+            ledger_dir: Directory to store ledger JSON files. Defaults to .ledger in project root
+        """
+        if ledger_dir is None:
+            # Default to .ledger directory in project root
+            project_root = Path(__file__).parent.parent.parent.parent
+            ledger_dir = project_root / ".ledger"
+
+        self.ledger_dir = Path(ledger_dir)
+        self.ledger_dir.mkdir(parents=True, exist_ok=True)
+
+        self.transactions_file = self.ledger_dir / "transactions.json"
+        self.snapshots_file = self.ledger_dir / "snapshots.json"
+
+        # File locks for thread-safe operations
+        self._transactions_lock = asyncio.Lock()
+        self._snapshots_lock = asyncio.Lock()
+
+        # Initialize files if they don't exist
+        self._initialize_files()
+
+    def _initialize_files(self) -> None:
+        """Create initial JSON files if they don't exist."""
+        if not self.transactions_file.exists():
+            self.transactions_file.write_text(
+                json.dumps({"transactions": []}, indent=2)
+            )
+
+        if not self.snapshots_file.exists():
+            self.snapshots_file.write_text(json.dumps({"snapshots": []}, indent=2))
+
+    async def _read_transactions(self) -> dict[str, Any]:
+        """Read transactions from file with lock."""
+        async with self._transactions_lock:
+            if not self.transactions_file.exists():
+                return {"transactions": []}
+            try:
+                content = self.transactions_file.read_text()
+                return json.loads(content)
+            except json.JSONDecodeError:
+                return {"transactions": []}
+
+    async def _write_transactions(self, data: dict[str, Any]) -> None:
+        """Write transactions to file with lock."""
+        async with self._transactions_lock:
+            self.transactions_file.write_text(json.dumps(data, indent=2))
+
+    async def _read_snapshots(self) -> dict[str, Any]:
+        """Read snapshots from file with lock."""
+        async with self._snapshots_lock:
+            if not self.snapshots_file.exists():
+                return {"snapshots": []}
+            try:
+                content = self.snapshots_file.read_text()
+                return json.loads(content)
+            except json.JSONDecodeError:
+                return {"snapshots": []}
+
+    async def _write_snapshots(self, data: dict[str, Any]) -> None:
+        """Write snapshots to file with lock."""
+        async with self._snapshots_lock:
+            self.snapshots_file.write_text(json.dumps(data, indent=2))
 
     # ===================== Read Endpoints =====================
 
-    async def get_vault_transactions(
+    async def get_strategy_transactions(
         self,
         *,
         wallet_address: str,
-        limit: int = 50,
+        limit: int = 100,
         offset: int = 0,
-    ) -> dict[str, Any]:
+    ) -> StrategyTransactionList:
         """
-        Fetch a paginated list of transactions for a given vault wallet and address.
+        Fetch a paginated list of transactions for a given strategy wallet address.
 
-        GET /api/v1/public/vaults/transactions/?wallet_address=...&limit=...&offset=...
+        Args:
+            wallet_address: The strategy wallet address to filter by
+            limit: Maximum number of transactions to return
+            offset: Number of transactions to skip
+
+        Returns:
+            StrategyTransactionList with transactions, total, limit, and offset
         """
-        url = f"{self.api_base_url}/public/vaults/transactions/"
-        params = {
-            "wallet_address": wallet_address,
-            "limit": str(limit),
-            "offset": str(offset),
+        data = await self._read_transactions()
+        all_transactions = data.get("transactions", [])
+
+        # Filter by wallet_address
+        filtered = [
+            tx
+            for tx in all_transactions
+            if tx.get("wallet_address", "").lower() == wallet_address.lower()
+        ]
+
+        # Sort by timestamp descending (most recent first)
+        filtered.sort(key=lambda x: x.get("timestamp", ""), reverse=True)
+
+        total = len(filtered)
+        paginated = filtered[offset : offset + limit]
+
+        return {
+            "transactions": paginated,
+            "total": total,
+            "limit": limit,
+            "offset": offset,
         }
-        response = await self._authed_request("GET", url, params=params)
-        data = response.json()
-        return data.get("data", data)
 
-    async def get_vault_net_deposit(self, *, wallet_address: str) -> dict[str, Any]:
+    async def get_strategy_net_deposit(self, *, wallet_address: str) -> NetDeposit:
         """
-        Fetch the net deposit (deposits - withdrawals) for a vault and address.
+        Calculate the net deposit (deposits - withdrawals) for a strategy wallet.
 
-        GET /api/v1/public/vaults/net-deposit/?wallet_address=...
+        Args:
+            wallet_address: The strategy wallet address
+
+        Returns:
+            NetDeposit with net_deposit, total_deposits, total_withdrawals
         """
-        url = f"{self.api_base_url}/public/vaults/net-deposit/"
-        params = {
+        data = await self._read_transactions()
+        all_transactions = data.get("transactions", [])
+
+        # Filter by wallet_address
+        filtered = [
+            tx
+            for tx in all_transactions
+            if tx.get("wallet_address", "").lower() == wallet_address.lower()
+        ]
+
+        total_deposits = 0.0
+        total_withdrawals = 0.0
+
+        for tx in filtered:
+            operation = tx.get("operation", "").upper()
+            usd_value = float(tx.get("usd_value", 0))
+
+            if operation == "DEPOSIT":
+                total_deposits += usd_value
+            elif operation == "WITHDRAW":
+                total_withdrawals += usd_value
+
+        net_deposit = total_deposits - total_withdrawals
+
+        return {
+            "net_deposit": str(net_deposit),
+            "total_deposits": str(total_deposits),
+            "total_withdrawals": str(total_withdrawals),
             "wallet_address": wallet_address,
         }
-        response = await self._authed_request("GET", url, params=params)
-        data = response.json()
-        return data.get("data", data)
 
-    async def get_vault_latest_transactions(
-        self, *, wallet_address: str
-    ) -> dict[str, Any]:
+    async def get_strategy_latest_transactions(
+        self, *, wallet_address: str, limit: int = 10
+    ) -> StrategyTransactionList:
         """
-        Fetch the last rotation time for a vault and address.
+        Fetch the most recent transactions for a strategy wallet.
+
+        Args:
+            wallet_address: The strategy wallet address
+            limit: Maximum number of transactions to return (default 10)
 
-        GET /api/v1/public/vaults/last-rotation-time/?wallet_address=...
+        Returns:
+            StrategyTransactionList with the latest transactions
         """
-        url = f"{self.api_base_url}/public/vaults/latest-transactions/"
-        params = {
-            "wallet_address": wallet_address,
-        }
-        response = await self._authed_request("GET", url, params=params)
-        data = response.json()
-        return data.get("data", data)
+        return await self.get_strategy_transactions(
+            wallet_address=wallet_address,
+            limit=limit,
+            offset=0,
+        )
 
     # ===================== Write Endpoints =====================
 
-    async def add_vault_deposit(
+    async def add_strategy_deposit(
         self,
         *,
         wallet_address: str,
@@ -90,28 +248,53 @@ class LedgerClient(WayfinderClient):
         usd_value: str | float,
         data: dict[str, Any] | None = None,
         strategy_name: str | None = None,
-    ) -> dict[str, Any]:
+    ) -> TransactionRecord:
         """
-        Record a deposit for a vault.
+        Record a deposit for a strategy.
+
+        Args:
+            wallet_address: The strategy wallet address
+            chain_id: The blockchain chain ID
+            token_address: The token contract address
+            token_amount: Amount of tokens deposited
+            usd_value: USD value of the deposit
+            data: Additional metadata
+            strategy_name: Name of the strategy
 
-        POST /api/v1/public/vaults/deposits/
+        Returns:
+            TransactionRecord with transaction_id, status, and timestamp
         """
-        url = f"{self.api_base_url}/public/vaults/deposits/"
-        payload: dict[str, Any] = {
+        transaction_id = str(uuid.uuid4())
+        timestamp = datetime.now(UTC).isoformat()
+
+        transaction = {
+            "id": transaction_id,
             "wallet_address": wallet_address,
+            "operation": "DEPOSIT",
+            "timestamp": timestamp,
             "chain_id": chain_id,
             "token_address": token_address,
             "token_amount": str(token_amount),
+            "amount": str(token_amount),  # For backward compatibility
             "usd_value": str(usd_value),
             "data": data or {},
         }
+
         if strategy_name is not None:
-            payload["strategy_name"] = strategy_name
-        response = await self._authed_request("POST", url, json=payload)
-        data_resp = response.json()
-        return data_resp.get("data", data_resp)
+            transaction["strategy_name"] = strategy_name
 
-    async def add_vault_withdraw(
+        # Add to transactions
+        file_data = await self._read_transactions()
+        file_data["transactions"].append(transaction)
+        await self._write_transactions(file_data)
+
+        return {
+            "transaction_id": transaction_id,
+            "status": "success",
+            "timestamp": timestamp,
+        }
+
+    async def add_strategy_withdraw(
         self,
         *,
         wallet_address: str,
@@ -121,102 +304,145 @@ class LedgerClient(WayfinderClient):
         usd_value: str | float,
         data: dict[str, Any] | None = None,
         strategy_name: str | None = None,
-    ) -> dict[str, Any]:
+    ) -> TransactionRecord:
         """
-        Record a withdrawal for a vault.
+        Record a withdrawal for a strategy.
 
-        POST /api/v1/public/vaults/withdrawals/
+        Args:
+            wallet_address: The strategy wallet address
+            chain_id: The blockchain chain ID
+            token_address: The token contract address
+            token_amount: Amount of tokens withdrawn
+            usd_value: USD value of the withdrawal
+            data: Additional metadata
+            strategy_name: Name of the strategy
+
+        Returns:
+            TransactionRecord with transaction_id, status, and timestamp
         """
-        url = f"{self.api_base_url}/public/vaults/withdrawals/"
-        payload: dict[str, Any] = {
+        transaction_id = str(uuid.uuid4())
+        timestamp = datetime.now(UTC).isoformat()
+
+        transaction = {
+            "id": transaction_id,
             "wallet_address": wallet_address,
+            "operation": "WITHDRAW",
+            "timestamp": timestamp,
             "chain_id": chain_id,
             "token_address": token_address,
             "token_amount": str(token_amount),
+            "amount": str(token_amount),  # For backward compatibility
             "usd_value": str(usd_value),
             "data": data or {},
         }
+
         if strategy_name is not None:
-            payload["strategy_name"] = strategy_name
-        response = await self._authed_request("POST", url, json=payload)
-        data_resp = response.json()
-        return data_resp.get("data", data_resp)
+            transaction["strategy_name"] = strategy_name
+
+        # Add to transactions
+        file_data = await self._read_transactions()
+        file_data["transactions"].append(transaction)
+        await self._write_transactions(file_data)
+
+        return {
+            "transaction_id": transaction_id,
+            "status": "success",
+            "timestamp": timestamp,
+        }
 
-    async def add_vault_operation(
+    async def add_strategy_operation(
         self,
         *,
         wallet_address: str,
-        operation_data: dict[str, Any],
+        operation_data: Operation,
         usd_value: str | float,
         strategy_name: str | None = None,
-    ) -> dict[str, Any]:
+    ) -> TransactionRecord:
         """
-        Record a vault operation (e.g., swaps, rebalances) for bookkeeping.
+        Record a strategy operation (e.g., swaps, rebalances) for bookkeeping.
 
-        POST /api/v1/public/vaults/operations/
+        Args:
+            wallet_address: Strategy wallet address
+            operation_data: Operation model (SWAP, LEND, UNLEND, etc.)
+            usd_value: USD value of the operation
+            strategy_name: Optional strategy name
+
+        Returns:
+            TransactionRecord with transaction_id, status, and timestamp
         """
-        url = f"{self.api_base_url}/public/vaults/operations/"
-        payload: dict[str, Any] = {
+        transaction_id = str(uuid.uuid4())
+        timestamp = datetime.now(UTC).isoformat()
+
+        op_dict = operation_data.model_dump(mode="json")
+        operation_type = op_dict.get("type", "OPERATION")
+
+        transaction = {
+            "id": transaction_id,
             "wallet_address": wallet_address,
-            "operation_data": operation_data,
+            "operation": operation_type,
+            "timestamp": timestamp,
             "usd_value": str(usd_value),
+            "op_data": op_dict,
+            "data": {},
         }
+
+        # Extract relevant fields from operation data for easier querying
+        if operation_type == "SWAP":
+            transaction["token_address"] = op_dict.get("to_token_id", "")
+            transaction["amount"] = op_dict.get("to_amount", "0")
+        elif operation_type in ("LEND", "UNLEND"):
+            transaction["token_address"] = op_dict.get("contract", "")
+            transaction["amount"] = str(op_dict.get("amount", 0))
+
         if strategy_name is not None:
-            payload["strategy_name"] = strategy_name
-        response = await self._authed_request("POST", url, json=payload)
-        data_resp = response.json()
-        return data_resp.get("data", data_resp)
+            transaction["strategy_name"] = strategy_name
+
+        # Add to transactions
+        file_data = await self._read_transactions()
+        file_data["transactions"].append(transaction)
+        await self._write_transactions(file_data)
+
+        return {
+            "transaction_id": transaction_id,
+            "status": "success",
+            "timestamp": timestamp,
+        }
 
-    async def add_vault_cashflow(
+    async def strategy_snapshot(
         self,
-        *,
         wallet_address: str,
-        block_timestamp: int,
-        token_addr: str,
-        amount: str | int | float,
-        description: str,
-        strategy_name: str | None = None,
-    ) -> dict[str, Any]:
+        strat_portfolio_value: float,
+        net_deposit: float,
+        strategy_status: dict,
+        gas_available: float,
+        gassed_up: bool,
+    ) -> None:
         """
-        Record a cashflow for a vault (interest, funding, reward, or fee).
-
-        POST /api/v1/public/vaults/cashflows/
+        Record a periodic snapshot of strategy state.
 
         Args:
-            wallet_address: Vault wallet address
-            block_timestamp: Block timestamp (Unix timestamp)
-            token_addr: Token contract address
-            amount: Cashflow amount (in token units)
-            description: Cashflow type - must be one of: "interest", "funding", "reward", "fee", "lend", "unlend", "borrow"
-            strategy_name: Optional strategy name
-
-        Returns:
-            Dict containing the cashflow record or error details
-        """
-        valid_descriptions = [
-            "interest",
-            "funding",
-            "reward",
-            "fee",
-            "lend",
-            "unlend",
-            "borrow",
-        ]
-        if description not in valid_descriptions:
-            raise ValueError(
-                f"Invalid description '{description}'. Must be one of: {valid_descriptions}"
-            )
+            wallet_address: Strategy wallet address
+            strat_portfolio_value: Total portfolio value in USD
+            net_deposit: Net deposit amount in USD
+            strategy_status: Arbitrary strategy status data
+            gas_available: Available gas tokens
+            gassed_up: Whether strategy has sufficient gas
+        """
+        snapshot_id = str(uuid.uuid4())
+        timestamp = datetime.now(UTC).isoformat()
 
-        url = f"{self.api_base_url}/public/vaults/cashflows/"
-        payload: dict[str, Any] = {
+        snapshot = {
+            "id": snapshot_id,
             "wallet_address": wallet_address,
-            "block_timestamp": block_timestamp,
-            "token_addr": token_addr,
-            "amount": str(amount),
-            "description": description,
+            "timestamp": timestamp,
+            "portfolio_value": strat_portfolio_value,
+            "net_deposit": net_deposit,
+            "gas_available": gas_available,
+            "gassed_up": gassed_up,
+            "strategy_status": strategy_status,
         }
-        if strategy_name is not None:
-            payload["strategy_name"] = strategy_name
-        response = await self._authed_request("POST", url, json=payload)
-        data_resp = response.json()
-        return data_resp.get("data", data_resp)
+
+        # Add to snapshots
+        file_data = await self._read_snapshots()
+        file_data["snapshots"].append(snapshot)
+        await self._write_snapshots(file_data)

wayfinder_paths/core/clients/PoolClient.py

@@ -3,13 +3,59 @@ Pool Client
 Provides read-only access to pool metadata and analytics via public endpoints.
 """
 
-from typing import Any
+from __future__ import annotations
+
+from typing import Any, NotRequired, Required, TypedDict
 
 from wayfinder_paths.core.clients.AuthClient import AuthClient
 from wayfinder_paths.core.clients.WayfinderClient import WayfinderClient
 from wayfinder_paths.core.settings import settings
 
 
+class PoolData(TypedDict):
+    """Individual pool data structure"""
+
+    id: Required[str]
+    name: Required[str]
+    symbol: Required[str]
+    address: Required[str]
+    chain_id: Required[int]
+    chain_code: Required[str]
+    apy: NotRequired[float]
+    tvl: NotRequired[float]
+    llama_apy_pct: NotRequired[float | None]
+    llama_tvl_usd: NotRequired[float | None]
+    llama_stablecoin: NotRequired[bool | None]
+    llama_il_risk: NotRequired[str | None]
+    network: NotRequired[str | None]
+
+
+class PoolList(TypedDict):
+    """Pool list response structure"""
+
+    pools: Required[list[PoolData]]
+    total: NotRequired[int | None]
+
+
+class LlamaMatch(TypedDict):
+    """Llama match data structure"""
+
+    id: Required[str]
+    llama_apy_pct: Required[float]
+    llama_tvl_usd: Required[float]
+    llama_stablecoin: Required[bool]
+    llama_il_risk: Required[str]
+    network: Required[str]
+
+
+class LlamaReport(TypedDict):
+    """Llama report data structure"""
+
+    identifier: Required[str]
+    apy: NotRequired[float | None]
+    tvl: NotRequired[float | None]
+
+
 class PoolClient(WayfinderClient):
     """Client for pool-related read operations"""
 
@@ -23,7 +69,7 @@ class PoolClient(WayfinderClient):
         *,
         pool_ids: str,
         merge_external: bool | None = None,
-    ) -> dict[str, Any]:
+    ) -> PoolList:
         """
         Fetch pools by comma-separated pool ids.
 
@@ -39,9 +85,7 @@ class PoolClient(WayfinderClient):
         data = response.json()
         return data.get("data", data)
 
-    async def get_all_pools(
-        self, *, merge_external: bool | None = None
-    ) -> dict[str, Any]:
+    async def get_all_pools(self, *, merge_external: bool | None = None) -> PoolList:
         """
         Fetch all pools.
 
@@ -57,19 +101,7 @@ class PoolClient(WayfinderClient):
         data = response.json()
         return data.get("data", data)
 
-    async def get_combined_pool_reports(self) -> dict[str, Any]:
-        """
-        Fetch combined pool reports.
-
-        GET /api/v1/public/pools/combined/
-        """
-        url = f"{self.api_base_url}/public/pools/combined/"
-        response = await self._request("GET", url, headers={})
-        response.raise_for_status()
-        data = response.json()
-        return data.get("data", data)
-
-    async def get_llama_matches(self) -> dict[str, Any]:
+    async def get_llama_matches(self) -> dict[str, LlamaMatch]:
         """
         Fetch Llama matches for pools.
 
@@ -81,7 +113,7 @@ class PoolClient(WayfinderClient):
         data = response.json()
         return data.get("data", data)
 
-    async def get_llama_reports(self, *, identifiers: str) -> dict[str, Any]:
+    async def get_llama_reports(self, *, identifiers: str) -> dict[str, LlamaReport]:
         """
         Fetch Llama reports using identifiers (token ids, address_network, or pool ids).