wayfinder-paths 0.1.1__py3-none-any.whl

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 Vaults 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/vault.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,183 @@
+import os
+import traceback
+from abc import ABC, abstractmethod
+from typing import Any, TypedDict
+
+from loguru import logger
+
+from wayfinder_paths.core.services.base import Web3Service
+
+
+class StatusDict(TypedDict):
+    portfolio_value: float
+    net_deposit: float
+    strategy_status: Any
+
+
+StatusTuple = tuple[bool, str]
+
+
+class Strategy(ABC):
+    name: str = None
+    description: str = None
+    summary: str = None
+
+    def __init__(
+        self,
+        config: dict[str, Any] | None = None,
+        *,
+        main_wallet: dict[str, Any] | None = None,
+        vault_wallet: dict[str, Any] | None = None,
+        simulation: bool = False,
+        web3_service: Web3Service = None,
+        api_key: str | None = None,
+    ):
+        self.adapters = {}
+        self.ledger = None
+        self.logger = logger.bind(strategy=self.__class__.__name__)
+        if api_key:
+            os.environ["WAYFINDER_API_KEY"] = api_key
+
+    async def setup(self):
+        """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 temp_ui_message(self, msg: str) -> None:
+        """Hook for temporary UI messages (e.g., progress) to the chat window."""
+        # No-op by default; strategies/hosts can override
+        return None
+
+    async def quote(self):
+        """Get quotes for potential trades - optional for strategies"""
+        pass
+
+    @abstractmethod
+    async def deposit(self, **kwargs) -> StatusTuple:
+        """
+        Deposit funds into the strategy
+        Returns: (success: bool, message: str)
+        """
+        pass
+
+    async def withdraw(self, **kwargs) -> StatusTuple:
+        """
+        Withdraw funds from the strategy
+        Default implementation unwinds all operations
+        Returns: (success: bool, message: str)
+        """
+        if hasattr(self, "ledger") and self.ledger:
+            while self.ledger.positions.operations:
+                node = self.ledger.positions.operations[-1]
+                adapter = self.adapters.get(node.adapter)
+                if adapter and hasattr(adapter, "unwind_op"):
+                    await adapter.unwind_op(node)
+                self.ledger.positions.operations.pop()
+
+            await self.ledger.save()
+
+        return (True, "Withdrawal complete")
+
+    @abstractmethod
+    async def update(self) -> StatusTuple:
+        """
+        Update strategy positions/rebalance
+        Returns: (success: bool, message: str)
+        """
+        pass
+
+    @staticmethod
+    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.
+        """
+        return await self._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):
+        """
+        Decorator to unwind operations on error
+        Useful for deposit operations that need cleanup on failure
+        """
+
+        async def wrapper(*args, **kwargs):
+            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") and self.ledger:
+                    await self.ledger.save()
+
+        return wrapper
+
+    @classmethod
+    def get_metadata(cls) -> dict[str, Any]:
+        """
+        Return metadata about this strategy
+        Can be overridden to provide discovery information
+        """
+        return {
+            "name": cls.name,
+            "description": cls.description,
+            "summary": cls.summary,
+        }
+
+    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) -> StatusTuple:
+        """
+        Partially liquidate strategy positions by USD value
+        Optional method that can be overridden by subclasses
+        Returns: (success: bool, message: str)
+        """
+        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",
+]

wayfinder_paths/core/utils/__init__.py

@@ -0,0 +1 @@
+"""Utility helpers for local functionality not tied to external APIs."""

wayfinder_paths/core/utils/evm_helpers.py

@@ -0,0 +1,165 @@
+"""
+EVM helper utilities for common blockchain operations.
+
+This module provides reusable functions for EVM-related operations that are shared
+across multiple adapters, extracted from evm_transaction_adapter.
+"""
+
+import os
+from typing import Any
+
+from loguru import logger
+from web3 import AsyncHTTPProvider, AsyncWeb3
+
+from wayfinder_paths.core.constants.base import CHAIN_CODE_TO_ID
+
+
+def chain_code_to_chain_id(chain_code: str | None) -> int | None:
+    """
+    Convert chain code to chain ID.
+
+    Args:
+        chain_code: Chain code string (e.g., "ethereum", "base")
+
+    Returns:
+        Chain ID as integer, or None if not found
+    """
+    if not chain_code:
+        return None
+    return CHAIN_CODE_TO_ID.get(chain_code.lower())
+
+
+def resolve_chain_id(token_info: dict[str, Any], logger_instance=None) -> int | None:
+    """
+    Extract chain ID from token_info dictionary.
+
+    Args:
+        token_info: Dictionary containing token information with 'chain' key
+        logger_instance: Optional logger instance for debug messages
+
+    Returns:
+        Chain ID as integer, or None if not found
+    """
+    log = logger_instance or logger
+    chain_meta = token_info.get("chain") or {}
+    chain_id = chain_meta.get("chain_id")
+    try:
+        if chain_id is not None:
+            return int(chain_id)
+    except (ValueError, TypeError):
+        log.debug("Invalid chain_id in token_info.chain_id: %s", chain_id)
+    return chain_code_to_chain_id(chain_meta.get("code"))
+
+
+def resolve_rpc_url(
+    chain_id: int | None,
+    config: dict[str, Any],
+    explicit_rpc_url: str | None = None,
+) -> str:
+    """
+    Resolve RPC URL from config or environment variables.
+
+    Args:
+        chain_id: Chain ID to look up RPC URL for
+        config: Configuration dictionary
+        explicit_rpc_url: Explicitly provided RPC URL (takes precedence)
+
+    Returns:
+        RPC URL string
+
+    Raises:
+        ValueError: If RPC URL cannot be resolved
+    """
+    if explicit_rpc_url:
+        return explicit_rpc_url
+    strategy_cfg = config.get("strategy") or {}
+    mapping = strategy_cfg.get("rpc_urls") if isinstance(strategy_cfg, dict) else None
+    if chain_id is not None and isinstance(mapping, dict):
+        by_int = mapping.get(chain_id)
+        if by_int:
+            return str(by_int)
+        by_str = mapping.get(str(chain_id))
+        if by_str:
+            return str(by_str)
+    env_rpc = os.getenv("RPC_URL")
+    if env_rpc:
+        return env_rpc
+    raise ValueError("RPC URL not provided. Set strategy.rpc_urls or env RPC_URL.")
+
+
+async def get_next_nonce(
+    from_address: str, rpc_url: str, use_latest: bool = False
+) -> int:
+    """
+    Get the next nonce for the given address.
+
+    Args:
+        from_address: Address to get nonce for
+        rpc_url: RPC URL to connect to
+        use_latest: If True, use 'latest' block instead of 'pending'
+
+    Returns:
+        Next nonce as integer
+    """
+    w3 = AsyncWeb3(AsyncHTTPProvider(rpc_url))
+    try:
+        if use_latest:
+            return await w3.eth.get_transaction_count(from_address, "latest")
+        return await w3.eth.get_transaction_count(from_address)
+    finally:
+        try:
+            await w3.provider.session.close()
+        except Exception:
+            pass
+
+
+def resolve_private_key_for_from_address(
+    from_address: str, config: dict[str, Any]
+) -> str | None:
+    """
+    Resolve private key for the given address from config or environment.
+
+    Args:
+        from_address: Address to resolve private key for
+        config: Configuration dictionary containing wallet information
+
+    Returns:
+        Private key string, or None if not found
+    """
+    from_addr_norm = (from_address or "").lower()
+    main_wallet = config.get("main_wallet")
+    vault_wallet = config.get("vault_wallet")
+
+    main_pk = None
+    vault_pk = None
+    try:
+        if isinstance(main_wallet, dict):
+            main_pk = main_wallet.get("private_key") or main_wallet.get(
+                "private_key_hex"
+            )
+        if isinstance(vault_wallet, dict):
+            vault_pk = vault_wallet.get("private_key") or vault_wallet.get(
+                "private_key_hex"
+            )
+    except (AttributeError, TypeError) as e:
+        logger.debug("Error resolving private keys from wallet config: %s", e)
+
+    main_addr = None
+    vault_addr = None
+    try:
+        main_addr = (main_wallet or {}).get("address") or (
+            (main_wallet or {}).get("evm") or {}
+        ).get("address")
+        vault_addr = (vault_wallet or {}).get("address") or (
+            (vault_wallet or {}).get("evm") or {}
+        ).get("address")
+    except (AttributeError, TypeError) as e:
+        logger.debug("Error resolving addresses from wallet config: %s", e)
+
+    if main_addr and from_addr_norm == (main_addr or "").lower():
+        return main_pk or os.getenv("PRIVATE_KEY")
+    if vault_addr and from_addr_norm == (vault_addr or "").lower():
+        return vault_pk or os.getenv("PRIVATE_KEY_VAULT") or os.getenv("PRIVATE_KEY")
+
+    # Fallback to environment variables
+    return os.getenv("PRIVATE_KEY_VAULT") or os.getenv("PRIVATE_KEY")

wayfinder_paths/core/utils/wallets.py

@@ -0,0 +1,77 @@
+import json
+from pathlib import Path
+from typing import Any
+
+from eth_account import Account
+
+
+def make_random_wallet() -> dict[str, str]:
+    """Generate a new random wallet.
+
+    Returns a mapping with keys: "address" and "private_key_hex" (0x-prefixed).
+    """
+    acct = Account.create()  # uses os.urandom
+    return {
+        "address": acct.address,
+        "private_key_hex": acct.key.hex(),
+    }
+
+
+def _load_existing_wallets(file_path: Path) -> list[dict[str, Any]]:
+    if not file_path.exists():
+        return []
+    try:
+        parsed = json.loads(file_path.read_text())
+        if isinstance(parsed, list):
+            return parsed
+        if isinstance(parsed, dict):
+            wallets = parsed.get("wallets")
+            if isinstance(wallets, list):
+                return wallets
+        return []
+    except Exception:
+        # If the file is malformed, start fresh rather than raising.
+        return []
+
+
+def _save_wallets(file_path: Path, wallets: list[dict[str, Any]]) -> None:
+    # Ensure stable ordering by address for readability
+    sorted_wallets = sorted(wallets, key=lambda w: w.get("address", ""))
+    file_path.write_text(json.dumps(sorted_wallets, indent=2))
+
+
+def write_wallet_to_json(
+    wallet: dict[str, str], out_dir: str | Path = ".", filename: str = "wallets.json"
+) -> Path:
+    """Create or update a wallets.json with the provided wallet.
+
+    - Ensures the output directory exists.
+    - Merges with existing entries keyed by address (updates if present, appends otherwise).
+    - Writes a pretty-printed JSON list of wallet objects.
+    """
+    out_dir_path = Path(out_dir)
+    out_dir_path.mkdir(parents=True, exist_ok=True)
+    file_path = out_dir_path / filename
+
+    existing = _load_existing_wallets(file_path)
+    index_by_address: dict[str, int] = {}
+    for i, w in enumerate(existing):
+        addr = w.get("address")
+        if isinstance(addr, str):
+            index_by_address[addr.lower()] = i
+
+    addr_key = wallet["address"].lower()
+    if addr_key in index_by_address:
+        existing[index_by_address[addr_key]] = wallet
+    else:
+        existing.append(wallet)
+
+    _save_wallets(file_path, existing)
+    return file_path
+
+
+def load_wallets(
+    out_dir: str | Path = ".", filename: str = "wallets.json"
+) -> list[dict[str, Any]]:
+    """Public helper to read wallets.json as a list of wallet dicts."""
+    return _load_existing_wallets(Path(out_dir) / filename)

wayfinder_paths/core/wallets/README.md

@@ -0,0 +1,91 @@
+# Wallet Abstraction Layer
+
+Wayfinder strategies interact with blockchains through a single abstraction: the `EvmTxn` interface defined in `wayfinder_paths/core/services/base.py`. The default implementation (`LocalEvmTxn`) signs transactions with private keys pulled from config/environment variables, while `WalletManager` resolves which provider to use at runtime.
+
+## Pieces
+
+1. **`EvmTxn` (interface)** – describes balance lookups, ERC-20 approvals, raw transaction broadcasting, and AsyncWeb3 access.
+2. **`LocalEvmTxn`** – the built-in provider that signs transactions locally via `eth_account`. It handles RPC resolution, nonce management, gas estimation, and status checks.
+3. **`WalletManager`** – light factory that reads `wallet_type` from strategy config and returns the appropriate `EvmTxn`. Today it always returns `LocalEvmTxn` unless you inject your own provider.
+4. **`DefaultWeb3Service`** – convenience wrapper that bundles an `EvmTxn` (wallet provider) with a `LocalTokenTxnService` (transaction builders used by adapters).
+
+## Using the defaults
+
+```python
+from wayfinder_paths.core.services.web3_service import DefaultWeb3Service
+from wayfinder_paths.core.wallets.WalletManager import WalletManager
+
+config = {...}  # contains main_wallet / vault_wallet entries
+wallet_provider = WalletManager.get_provider(config)
+web3_service = DefaultWeb3Service(config, wallet_provider=wallet_provider)
+
+# Strategies typically pass web3_service.evm_transactions into adapters that require wallet access.
+balance_adapter = BalanceAdapter(config, web3_service=web3_service)
+```
+
+If you want to provide a custom wallet provider (e.g., Privy, Turnkey, Fireblocks), implement the `EvmTxn` interface and hand it to `DefaultWeb3Service`/adapters directly—`WalletManager` is purely a helper.
+
+## Implementing a custom provider
+
+Subclass `EvmTxn` and implement every abstract method:
+
+```python
+from typing import Any
+from web3 import AsyncWeb3
+
+from wayfinder_paths.core.services.base import EvmTxn
+
+
+class PrivyWallet(EvmTxn):
+    def __init__(self, privy_client):
+        self._client = privy_client
+
+    async def get_balance(self, address: str, token_address: str | None, chain_id: int) -> tuple[bool, Any]:
+        ...
+
+    async def read_erc20_allowance(self, chain_id: int, token_address: str, owner_address: str, spender_address: str) -> tuple[bool, Any]:
+        ...
+
+    async def approve_token(...):
+        ...
+
+    async def broadcast_transaction(...):
+        ...
+
+    async def transaction_succeeded(self, tx_hash: str, chain_id: int, timeout: int = 120) -> bool:
+        ...
+
+    def get_web3(self, chain_id: int) -> AsyncWeb3:
+        ...
+```
+
+Methods should mirror `LocalEvmTxn`’s behavior: return `(True, payload)` on success, `(False, "reason")` on failure, and expose AsyncWeb3 instances tied to the requested chain.
+
+Once implemented:
+
+```python
+custom_wallet = PrivyWallet(privy_client)
+web3_service = DefaultWeb3Service(config, wallet_provider=custom_wallet)
+```
+
+## Configuration hints
+
+`WalletManager.get_provider` looks for `wallet_type` on the top-level config, `main_wallet`, and `vault_wallet`. Example:
+
+```json
+{
+  "strategy": {
+    "wallet_type": "local",
+    "main_wallet": {"address": "0x...", "wallet_type": "local"},
+    "vault_wallet": {"address": "0x..."}
+  }
+}
+```
+
+Currently only `"local"` is supported through configuration—the custom path is injection.
+
+## Why this layer?
+
+- Strategies never touch raw `AsyncWeb3`; they call adapters, which call clients, which call a wallet provider.
+- Alternate signing backends can be plugged in without modifying strategy code.
+- Tests can patch `WalletManager.get_provider` or inject stub `EvmTxn` implementations to avoid real RPC calls.