wayfinder-paths 0.1.7__py3-none-any.whl

wayfinder_paths/core/services/local_token_txn.py

@@ -0,0 +1,231 @@
+from __future__ import annotations
+
+from typing import Any
+
+from eth_utils import to_checksum_address
+from loguru import logger
+from web3 import AsyncWeb3
+
+from wayfinder_paths.core.clients.TokenClient import TokenClient
+from wayfinder_paths.core.clients.TransactionClient import TransactionClient
+from wayfinder_paths.core.constants import ZERO_ADDRESS
+from wayfinder_paths.core.constants.erc20_abi import ERC20_APPROVAL_ABI
+from wayfinder_paths.core.services.base import EvmTxn, TokenTxn
+from wayfinder_paths.core.utils.evm_helpers import resolve_chain_id
+
+
+class LocalTokenTxnService(TokenTxn):
+    """Default transaction builder used by adapters."""
+
+    def __init__(
+        self,
+        config: dict[str, Any] | None,
+        *,
+        wallet_provider: EvmTxn,
+        simulation: bool = False,
+    ) -> None:
+        del config, simulation
+        self.wallet_provider = wallet_provider
+        self.logger = logger.bind(service="DefaultEvmTransactionService")
+        self.token_client = TokenClient()
+        self.builder = _EvmTransactionBuilder()
+
+    async def build_send(
+        self,
+        *,
+        token_id: str,
+        amount: float,
+        from_address: str,
+        to_address: str,
+        token_info: dict[str, Any] | None = None,
+    ) -> tuple[bool, dict[str, Any] | str]:
+        """Build the transaction dict for sending tokens between wallets."""
+        token_meta = token_info
+        if token_meta is None:
+            token_meta = await self.token_client.get_token_details(token_id)
+            if not token_meta:
+                return False, f"Token not found: {token_id}"
+
+        chain_id = resolve_chain_id(token_meta, self.logger)
+        if chain_id is None:
+            return False, f"Token {token_id} is missing a chain id"
+
+        token_address = (token_meta or {}).get("address") or ZERO_ADDRESS
+
+        try:
+            tx = await self.builder.build_send_transaction(
+                from_address=from_address,
+                to_address=to_address,
+                token_address=token_address,
+                amount=amount,
+                chain_id=int(chain_id),
+            )
+        except Exception as exc:  # noqa: BLE001
+            return False, f"Failed to build send transaction: {exc}"
+
+        return True, tx
+
+    def build_erc20_approve(
+        self,
+        *,
+        chain_id: int,
+        token_address: str,
+        from_address: str,
+        spender: str,
+        amount: int,
+    ) -> tuple[bool, dict[str, Any] | str]:
+        """Build the transaction dictionary for an ERC20 approval."""
+        try:
+            web3 = self.wallet_provider.get_web3(chain_id)
+            token_checksum = to_checksum_address(token_address)
+            from_checksum = to_checksum_address(from_address)
+            spender_checksum = to_checksum_address(spender)
+            amount_int = int(amount)
+        except (TypeError, ValueError) as exc:
+            return False, str(exc)
+
+        approve_tx = self.builder.build_erc20_approval_transaction(
+            chain_id=chain_id,
+            token_address=token_checksum,
+            from_address=from_checksum,
+            spender=spender_checksum,
+            amount=amount_int,
+            web3=web3,
+        )
+        return True, approve_tx
+
+    async def read_erc20_allowance(
+        self, chain: Any, token_address: str, from_address: str, spender_address: str
+    ) -> dict[str, Any]:
+        try:
+            chain_id = self._chain_id(chain)
+        except (TypeError, ValueError) as exc:
+            return {"error": str(exc), "allowance": 0}
+
+        w3 = self.get_web3(chain_id)
+        try:
+            contract = w3.eth.contract(
+                address=to_checksum_address(token_address), abi=ERC20_APPROVAL_ABI
+            )
+            allowance = await contract.functions.allowance(
+                to_checksum_address(from_address),
+                to_checksum_address(spender_address),
+            ).call()
+            return (True, {"allowance": int(allowance)})
+        except Exception as exc:  # noqa: BLE001
+            self.logger.error(f"Failed to read allowance: {exc}")
+            return {"error": f"Allowance query failed: {exc}", "allowance": 0}
+        finally:
+            await self._close_web3(w3)
+
+    def _chain_id(self, chain: Any) -> int:
+        if isinstance(chain, dict):
+            chain_id = chain.get("id") or chain.get("chain_id")
+        else:
+            chain_id = getattr(chain, "id", None)
+        if chain_id is None:
+            raise ValueError("Chain ID is required")
+        return int(chain_id)
+
+
+class _EvmTransactionBuilder:
+    """Helpers that only build transaction dictionaries for sends and approvals."""
+
+    def __init__(self) -> None:
+        self.transaction_client = TransactionClient()
+
+    async def build_send_transaction(
+        self,
+        *,
+        from_address: str,
+        to_address: str,
+        token_address: str | None,
+        amount: float,
+        chain_id: int,
+    ) -> dict[str, Any]:
+        """Build the transaction dict for sending native or ERC20 tokens."""
+        payload = await self.transaction_client.build_send(
+            from_address=from_address,
+            to_address=to_address,
+            token_address=token_address or "",
+            amount=float(amount),
+            chain_id=int(chain_id),
+        )
+        return self._payload_to_tx(
+            payload=payload,
+            from_address=from_address,
+            is_native=not token_address or token_address.lower() == ZERO_ADDRESS,
+        )
+
+    def build_erc20_approval_transaction(
+        self,
+        *,
+        chain_id: int,
+        token_address: str,
+        from_address: str,
+        spender: str,
+        amount: int,
+        web3: AsyncWeb3,
+    ) -> dict[str, Any]:
+        """Build an ERC20 approval transaction dict."""
+        token_checksum = to_checksum_address(token_address)
+        spender_checksum = to_checksum_address(spender)
+        from_checksum = to_checksum_address(from_address)
+        amount_int = int(amount)
+
+        contract = web3.eth.contract(address=token_checksum, abi=ERC20_APPROVAL_ABI)
+        data = contract.encodeABI(
+            fn_name="approve", args=[spender_checksum, amount_int]
+        )
+
+        return {
+            "chainId": int(chain_id),
+            "from": from_checksum,
+            "to": token_checksum,
+            "data": data,
+            "value": 0,
+        }
+
+    def _payload_to_tx(
+        self, payload: dict[str, Any], from_address: str, is_native: bool
+    ) -> dict[str, Any]:
+        data_root = payload.get("data", payload)
+        tx_src = data_root.get("transaction") or data_root
+
+        chain_id = tx_src.get("chainId") or data_root.get("chain_id")
+        if chain_id is None:
+            raise ValueError("Transaction payload missing chainId")
+
+        tx: dict[str, Any] = {"chainId": int(chain_id)}
+        tx["from"] = to_checksum_address(from_address)
+
+        if tx_src.get("to"):
+            tx["to"] = to_checksum_address(tx_src["to"])
+        if tx_src.get("data"):
+            data = tx_src["data"]
+            tx["data"] = data if str(data).startswith("0x") else f"0x{data}"
+
+        val = tx_src.get("value", 0)
+        tx["value"] = self._normalize_value(val) if is_native else 0
+
+        if tx_src.get("gas"):
+            tx["gas"] = int(tx_src["gas"])
+        if tx_src.get("maxFeePerGas"):
+            tx["maxFeePerGas"] = int(tx_src["maxFeePerGas"])
+        if tx_src.get("maxPriorityFeePerGas"):
+            tx["maxPriorityFeePerGas"] = int(tx_src["maxPriorityFeePerGas"])
+        if tx_src.get("gasPrice"):
+            tx["gasPrice"] = int(tx_src["gasPrice"])
+        if tx_src.get("nonce") is not None:
+            tx["nonce"] = int(tx_src["nonce"])
+
+        return tx
+
+    def _normalize_value(self, value: Any) -> int:
+        if isinstance(value, str):
+            if value.startswith("0x"):
+                return int(value, 16)
+            return int(float(value))
+        if isinstance(value, (int, float)):
+            return int(value)
+        return 0

wayfinder_paths/core/services/web3_service.py

@@ -0,0 +1,45 @@
+from __future__ import annotations
+
+from wayfinder_paths.core.services.base import EvmTxn, TokenTxn, Web3Service
+from wayfinder_paths.core.services.local_evm_txn import LocalEvmTxn
+from wayfinder_paths.core.services.local_token_txn import (
+    LocalTokenTxnService,
+)
+
+
+class DefaultWeb3Service(Web3Service):
+    """Default implementation that simply wires the provided dependencies together."""
+
+    def __init__(
+        self,
+        config: dict | None = None,
+        *,
+        wallet_provider: EvmTxn | None = None,
+        evm_transactions: TokenTxn | None = None,
+        simulation: bool = False,
+    ) -> None:
+        """
+        Initialize the service with optional dependency injection.
+
+        Strategies that already constructed wallet providers or transaction helpers
+        can pass them in directly. Otherwise we fall back to the legacy behavior of
+        building a LocalWalletProvider + DefaultEvmTransactionService from config.
+        """
+        cfg = config or {}
+        self._wallet_provider = wallet_provider or LocalEvmTxn(cfg)
+        if evm_transactions is not None:
+            self._evm_transactions = evm_transactions
+        else:
+            self._evm_transactions = LocalTokenTxnService(
+                config=cfg,
+                wallet_provider=self._wallet_provider,
+                simulation=simulation,
+            )
+
+    @property
+    def evm_transactions(self) -> EvmTxn:
+        return self._wallet_provider
+
+    @property
+    def token_transactions(self) -> TokenTxn:
+        return self._evm_transactions

wayfinder_paths/core/settings.py

@@ -0,0 +1,61 @@
+import json
+import os
+
+from pydantic import Field
+from pydantic_settings import BaseSettings, SettingsConfigDict
+
+
+class CoreSettings(BaseSettings):
+    """
+    Core settings for Wayfinder Paths Engine
+    These are minimal settings required by the core engine
+    """
+
+    model_config = SettingsConfigDict(
+        env_file=".env",
+        env_file_encoding="utf-8",
+        case_sensitive=False,
+        extra="ignore",  # Ignore extra environment variables (e.g., from Django)
+    )
+
+    # Core API Configuration
+    API_ENV: str = Field("development", env="API_ENV")
+
+    def _compute_default_api_url() -> str:
+        """
+        Determine default API base URL from config.json if present, otherwise fallback.
+        Do not mutate the value (consistent with rpc_urls resolution).
+        """
+        cfg_path = os.getenv("WAYFINDER_CONFIG_PATH", "config.json")
+        base = None
+        try:
+            with open(cfg_path) as f:
+                cfg = json.load(f)
+            system = cfg.get("system", {}) if isinstance(cfg, dict) else {}
+            candidate = system.get("api_base_url")
+            if isinstance(candidate, str) and candidate.strip():
+                base = candidate.strip()
+        except Exception:
+            # Config is optional; ignore errors and use fallback
+            pass
+
+        if not base:
+            # Provide a sensible default that includes the full API root
+            base = "https://wayfinder.ai/api/v1"
+        return base
+
+    WAYFINDER_API_URL: str = Field(_compute_default_api_url(), env="WAYFINDER_API_URL")
+
+    # Network Configuration
+    NETWORK: str = Field("testnet", env="NETWORK")  # mainnet, testnet, devnet
+
+    # Logging
+    LOG_LEVEL: str = Field("INFO", env="LOG_LEVEL")
+    LOG_FILE: str = Field("logs/strategy.log", env="LOG_FILE")
+
+    # Safety
+    DRY_RUN: bool = Field(False, env="DRY_RUN")
+
+
+# Core settings instance
+settings = CoreSettings()

wayfinder_paths/core/strategies/Strategy.py

@@ -0,0 +1,280 @@
+from __future__ import annotations
+
+import os
+import traceback
+from abc import ABC, abstractmethod
+from collections.abc import Awaitable, Callable
+from typing import Any, TypedDict
+
+from loguru import logger
+
+from wayfinder_paths.core.clients.TokenClient import TokenDetails
+from wayfinder_paths.core.services.base import Web3Service
+from wayfinder_paths.core.strategies.descriptors import StratDescriptor
+
+
+class StatusDict(TypedDict):
+    portfolio_value: float
+    net_deposit: float
+    strategy_status: Any
+    gas_available: float
+    gassed_up: bool
+
+
+StatusTuple = tuple[bool, str]
+
+
+class WalletConfig(TypedDict, total=False):
+    """Wallet configuration structure - allows additional fields for flexibility"""
+
+    address: str
+    private_key: str | None
+    private_key_hex: str | None
+    wallet_type: str | None
+
+
+class StrategyConfig(TypedDict, total=False):
+    """Base strategy configuration structure - allows additional fields for flexibility"""
+
+    main_wallet: WalletConfig | None
+    strategy_wallet: WalletConfig | None
+    wallet_type: str | None
+
+
+class LiquidationResult(TypedDict):
+    usd_value: float
+    token: TokenDetails
+    amt: int
+
+
+class Strategy(ABC):
+    name: str | None = None
+    INFO: StratDescriptor | None = None
+
+    def __init__(
+        self,
+        config: StrategyConfig | dict[str, Any] | None = None,
+        *,
+        main_wallet: WalletConfig | dict[str, Any] | None = None,
+        strategy_wallet: WalletConfig | dict[str, Any] | None = None,
+        simulation: bool = False,
+        web3_service: Web3Service | None = None,
+        api_key: str | None = None,
+    ):
+        self.adapters = {}
+        self.ledger_adapter = None
+        self.logger = logger.bind(strategy=self.__class__.__name__)
+        if api_key:
+            os.environ["WAYFINDER_API_KEY"] = api_key
+
+        self.config = config
+
+    async def setup(self) -> None:
+        """Initialize strategy-specific setup after construction"""
+        pass
+
+    async def log(self, msg: str) -> None:
+        """Log messages - can be overridden by subclasses"""
+        self.logger.info(msg)
+
+    async def quote(self) -> None:
+        """Get quotes for potential trades - optional for strategies"""
+        pass
+
+    def _get_strategy_wallet_address(self) -> str:
+        """Get strategy wallet address with validation."""
+        strategy_wallet = self.config.get("strategy_wallet")
+        if not strategy_wallet or not isinstance(strategy_wallet, dict):
+            raise ValueError("strategy_wallet not configured in strategy config")
+        address = strategy_wallet.get("address")
+        if not address:
+            raise ValueError("strategy_wallet address not found in config")
+        return str(address)
+
+    def _get_main_wallet_address(self) -> str:
+        """Get main wallet address with validation."""
+        main_wallet = self.config.get("main_wallet")
+        if not main_wallet or not isinstance(main_wallet, dict):
+            raise ValueError("main_wallet not configured in strategy config")
+        address = main_wallet.get("address")
+        if not address:
+            raise ValueError("main_wallet address not found in config")
+        return str(address)
+
+    @abstractmethod
+    async def deposit(self, **kwargs) -> StatusTuple:
+        """
+        Deposit funds into the strategy.
+
+        Args:
+            **kwargs: Strategy-specific deposit parameters. Common parameters include:
+                - main_token_amount: Amount of main token to deposit (float)
+                - gas_token_amount: Amount of gas token to deposit (float)
+
+        Returns:
+            Tuple of (success: bool, message: str)
+
+        Raises:
+            ValueError: If required parameters are missing or invalid.
+        """
+        pass
+
+    async def withdraw(self, **kwargs) -> StatusTuple:
+        """
+        Withdraw funds from the strategy.
+        Default implementation unwinds all operations.
+
+        Args:
+            **kwargs: Strategy-specific withdrawal parameters (optional).
+
+        Returns:
+            Tuple of (success: bool, message: str)
+
+        Note:
+            Subclasses may override this method to add validation or custom
+            withdrawal logic. The base implementation unwinds all ledger operations.
+        """
+        if hasattr(self, "ledger_adapter") and self.ledger_adapter:
+            while self.ledger_adapter.positions.operations:
+                node = self.ledger_adapter.positions.operations[-1]
+                adapter = self.adapters.get(node.adapter)
+                if adapter and hasattr(adapter, "unwind_op"):
+                    await adapter.unwind_op(node)
+                self.ledger_adapter.positions.operations.pop()
+
+            await self.ledger_adapter.save()
+
+        return (True, "Withdrawal complete")
+
+    @abstractmethod
+    async def update(self) -> StatusTuple:
+        """
+        Update strategy positions/rebalance
+        Returns: (success: bool, message: str)
+        """
+        pass
+
+    @staticmethod
+    async def policies() -> list[str]:
+        """Return policy strings for this strategy (Django-compatible)."""
+        raise NotImplementedError
+
+    @abstractmethod
+    async def _status(self) -> StatusDict:
+        """
+        Return status payload. Subclasses should implement this.
+        Should include Django-compatible keys (portfolio_value, net_deposit, strategy_status).
+        Backward-compatible keys (active_amount, total_earned) may also be included.
+        """
+        pass
+
+    async def status(self) -> StatusDict:
+        """
+        Wrapper to compute and return strategy status. In Django, this also snapshots.
+        Here we simply delegate to _status for compatibility.
+        """
+
+        status = await self._status()
+        await self.ledger_adapter.record_strategy_snapshot(
+            wallet_address=self._get_strategy_wallet_address(),
+            strategy_status=status,
+        )
+
+        return status
+
+    def register_adapters(self, adapters: list[Any]) -> None:
+        """Register adapters for use by the strategy"""
+        self.adapters = {}
+        for adapter in adapters:
+            if hasattr(adapter, "adapter_type"):
+                self.adapters[adapter.adapter_type] = adapter
+            elif hasattr(adapter, "__class__"):
+                self.adapters[adapter.__class__.__name__] = adapter
+
+    def unwind_on_error(
+        self, func: Callable[..., Awaitable[StatusTuple]]
+    ) -> Callable[..., Awaitable[StatusTuple]]:
+        """
+        Decorator to unwind operations on error
+        Useful for deposit operations that need cleanup on failure
+        """
+
+        async def wrapper(*args: Any, **kwargs: Any) -> StatusTuple:
+            try:
+                return await func(*args, **kwargs)
+            except Exception:
+                trace = traceback.format_exc()
+                try:
+                    await self.withdraw()
+                    return (
+                        False,
+                        f"Strategy failed during operation and was unwound. Failure: {trace}",
+                    )
+                except Exception:
+                    trace2 = traceback.format_exc()
+                    return (
+                        False,
+                        f"Strategy failed and unwinding also failed. Operation error: {trace}. Unwind error: {trace2}",
+                    )
+            finally:
+                if hasattr(self, "ledger_adapter") and self.ledger_adapter:
+                    await self.ledger_adapter.save()
+
+        return wrapper
+
+    @classmethod
+    def get_metadata(cls) -> dict[str, Any]:
+        """
+        Return metadata about this strategy.
+        Can be overridden to provide discovery information.
+
+        Returns:
+            Dictionary containing strategy metadata. The following keys are optional
+            and will be None if not defined on the class:
+            - name: Strategy name
+            - description: Strategy description
+            - summary: Strategy summary
+        """
+        return {
+            "name": getattr(cls, "name", None),
+            "description": getattr(cls, "description", None),
+            "summary": getattr(cls, "summary", None),
+        }
+
+    async def health_check(self) -> dict[str, Any]:
+        """
+        Check strategy health and dependencies
+        """
+        health = {"status": "healthy", "strategy": self.name, "adapters": {}}
+
+        for name, adapter in self.adapters.items():
+            if hasattr(adapter, "health_check"):
+                health["adapters"][name] = await adapter.health_check()
+            else:
+                health["adapters"][name] = {"status": "unknown"}
+
+        return health
+
+    async def partial_liquidate(
+        self, usd_value: float
+    ) -> tuple[bool, LiquidationResult]:
+        """
+        Partially liquidate strategy positions by USD value.
+        Optional method that can be overridden by subclasses.
+
+        Args:
+            usd_value: USD value to liquidate (must be positive).
+
+        Returns:
+            Tuple of (success: bool, message: str)
+
+        Raises:
+            ValueError: If usd_value is not positive.
+
+        Note:
+            Base implementation returns failure. Subclasses should override
+            to implement partial liquidation logic.
+        """
+        if usd_value <= 0:
+            raise ValueError(f"usd_value must be positive, got {usd_value}")
+        return (False, "Partial liquidation not implemented for this strategy")

wayfinder_paths/core/strategies/__init__.py

@@ -0,0 +1,5 @@
+"""Core Strategy Module - SDK surface re-export"""
+
+from .base import StatusDict, StatusTuple, Strategy
+
+__all__ = ["Strategy", "StatusDict", "StatusTuple"]

wayfinder_paths/core/strategies/base.py

@@ -0,0 +1,7 @@
+from wayfinder_paths.core.strategies.Strategy import StatusDict, StatusTuple, Strategy
+
+__all__ = [
+    "Strategy",
+    "StatusDict",
+    "StatusTuple",
+]