wayfinder-paths 0.1.7__py3-none-any.whl

wayfinder_paths/core/constants/erc20_abi.py

@@ -0,0 +1,118 @@
+"""
+ERC20 ABI constants for consistent use across the codebase.
+This centralizes ABI definitions to avoid duplication and improve maintainability.
+"""
+
+# Standard ERC20 ABI - includes common functions needed for token operations
+ERC20_ABI = [
+    {
+        "constant": True,
+        "inputs": [
+            {"name": "_owner", "type": "address"},
+            {"name": "_spender", "type": "address"},
+        ],
+        "name": "allowance",
+        "outputs": [{"name": "", "type": "uint256"}],
+        "type": "function",
+    },
+    {
+        "constant": False,
+        "inputs": [
+            {"name": "_spender", "type": "address"},
+            {"name": "_value", "type": "uint256"},
+        ],
+        "name": "approve",
+        "outputs": [{"name": "", "type": "bool"}],
+        "type": "function",
+    },
+    {
+        "constant": True,
+        "inputs": [{"name": "account", "type": "address"}],
+        "name": "balanceOf",
+        "outputs": [{"name": "", "type": "uint256"}],
+        "type": "function",
+    },
+    {
+        "constant": True,
+        "inputs": [],
+        "name": "decimals",
+        "outputs": [{"name": "", "type": "uint8"}],
+        "type": "function",
+    },
+    {
+        "constant": True,
+        "inputs": [],
+        "name": "name",
+        "outputs": [{"name": "", "type": "string"}],
+        "type": "function",
+    },
+    {
+        "constant": True,
+        "inputs": [],
+        "name": "symbol",
+        "outputs": [{"name": "", "type": "string"}],
+        "type": "function",
+    },
+    {
+        "constant": True,
+        "inputs": [],
+        "name": "totalSupply",
+        "outputs": [{"name": "", "type": "uint256"}],
+        "type": "function",
+    },
+    {
+        "constant": False,
+        "inputs": [
+            {"name": "_to", "type": "address"},
+            {"name": "_value", "type": "uint256"},
+        ],
+        "name": "transfer",
+        "outputs": [{"name": "", "type": "bool"}],
+        "type": "function",
+    },
+    {
+        "constant": False,
+        "inputs": [
+            {"name": "_from", "type": "address"},
+            {"name": "_to", "type": "address"},
+            {"name": "_value", "type": "uint256"},
+        ],
+        "name": "transferFrom",
+        "outputs": [{"name": "", "type": "bool"}],
+        "type": "function",
+    },
+]
+
+# Minimal ABI for specific use cases (e.g., when you only need certain functions)
+ERC20_MINIMAL_ABI = [
+    {
+        "constant": True,
+        "inputs": [{"name": "account", "type": "address"}],
+        "name": "balanceOf",
+        "outputs": [{"name": "", "type": "uint256"}],
+        "type": "function",
+    }
+]
+
+ERC20_APPROVAL_ABI = [
+    {
+        "constant": True,
+        "inputs": [
+            {"name": "_owner", "type": "address"},
+            {"name": "_spender", "type": "address"},
+        ],
+        "name": "allowance",
+        "outputs": [{"name": "", "type": "uint256"}],
+        "type": "function",
+    },
+    {
+        "constant": False,
+        "inputs": [
+            {"name": "_spender", "type": "address"},
+            {"name": "_value", "type": "uint256"},
+        ],
+        "name": "approve",
+        "outputs": [{"name": "", "type": "bool"}],
+        "type": "function",
+    },
+]

wayfinder_paths/core/constants/hyperlend_abi.py

@@ -0,0 +1,152 @@
+"""
+HyperLend ABI constants for smart contract interactions.
+
+This module contains ABI definitions for HyperLend protocol contracts,
+including Pool, Protocol Data Provider, Wrapped Token Gateway, and WETH contracts.
+"""
+
+# Minimal Pool ABI for supply and deposit operations
+POOL_ABI = [
+    {
+        "name": "supply",
+        "type": "function",
+        "stateMutability": "nonpayable",
+        "inputs": [
+            {"name": "asset", "type": "address"},
+            {"name": "amount", "type": "uint256"},
+            {"name": "onBehalfOf", "type": "address"},
+            {"name": "referralCode", "type": "uint16"},
+        ],
+        "outputs": [],
+    },
+    {
+        "name": "deposit",
+        "type": "function",
+        "stateMutability": "nonpayable",
+        "inputs": [
+            {"name": "asset", "type": "address"},
+            {"name": "amount", "type": "uint256"},
+            {"name": "onBehalfOf", "type": "address"},
+            {"name": "referralCode", "type": "uint16"},
+        ],
+        "outputs": [],
+    },
+    {
+        "name": "withdraw",
+        "type": "function",
+        "stateMutability": "nonpayable",
+        "inputs": [
+            {"name": "asset", "type": "address"},
+            {"name": "amount", "type": "uint256"},
+            {"name": "to", "type": "address"},
+        ],
+        "outputs": [],
+    },
+]
+
+# Protocol Data Provider ABI for reserve token addresses and user data
+PROTOCOL_DATA_PROVIDER_ABI = [
+    {
+        "type": "function",
+        "stateMutability": "view",
+        "name": "getReserveTokensAddresses",
+        "inputs": [{"name": "asset", "type": "address"}],
+        "outputs": [
+            {"name": "aTokenAddress", "type": "address"},
+            {"name": "stableDebtTokenAddress", "type": "address"},
+            {"name": "variableDebtTokenAddress", "type": "address"},
+        ],
+    },
+    {
+        "type": "function",
+        "stateMutability": "view",
+        "name": "getUserReserveData",
+        "inputs": [
+            {"name": "asset", "type": "address"},
+            {"name": "user", "type": "address"},
+        ],
+        "outputs": [
+            {"name": "currentATokenBalance", "type": "uint256"},
+            {"name": "currentStableDebt", "type": "uint256"},
+            {"name": "currentVariableDebt", "type": "uint256"},
+            {"name": "liquidityRate", "type": "uint256"},
+            {"name": "stableBorrowRate", "type": "uint256"},
+            {"name": "variableBorrowRate", "type": "uint256"},
+            {"name": "liquidityIndex", "type": "uint256"},
+            {"name": "healthFactor", "type": "uint256"},
+        ],
+    },
+]
+
+# Wrapped Token Gateway ABI for native token operations
+WRAPPED_TOKEN_GATEWAY_ABI = [
+    {
+        "type": "function",
+        "stateMutability": "view",
+        "name": "getWETHAddress",
+        "inputs": [],
+        "outputs": [{"type": "address"}],
+    },
+    {
+        "type": "function",
+        "stateMutability": "payable",
+        "name": "depositETH",
+        "inputs": [
+            {"type": "address"},
+            {"type": "address"},
+            {"type": "uint16"},
+        ],
+        "outputs": [],
+    },
+    {
+        "type": "function",
+        "stateMutability": "nonpayable",
+        "name": "withdrawETH",
+        "inputs": [
+            {"type": "address"},
+            {"type": "uint256"},
+            {"type": "address"},
+        ],
+        "outputs": [],
+    },
+    {
+        "type": "function",
+        "stateMutability": "payable",
+        "name": "repayETH",
+        "inputs": [
+            {"type": "address"},
+            {"type": "uint256"},
+            {"type": "address"},
+        ],
+        "outputs": [],
+    },
+    {
+        "type": "function",
+        "stateMutability": "nonpayable",
+        "name": "borrowETH",
+        "inputs": [
+            {"type": "address"},
+            {"type": "uint256"},
+            {"type": "uint16"},
+        ],
+        "outputs": [],
+    },
+]
+
+# WETH ABI for native token wrapping
+WETH_ABI = [
+    {
+        "inputs": [],
+        "name": "deposit",
+        "outputs": [],
+        "stateMutability": "payable",
+        "type": "function",
+    },
+    {
+        "inputs": [{"name": "wad", "type": "uint256"}],
+        "name": "withdraw",
+        "outputs": [],
+        "stateMutability": "nonpayable",
+        "type": "function",
+    },
+]

wayfinder_paths/core/engine/StrategyJob.py

@@ -0,0 +1,188 @@
+import asyncio
+import os
+from typing import Any
+
+from loguru import logger
+
+from wayfinder_paths.core.clients.ClientManager import ClientManager
+from wayfinder_paths.core.config import StrategyJobConfig
+from wayfinder_paths.core.strategies.Strategy import Strategy
+
+
+class StrategyJob:
+    def __init__(
+        self,
+        strategy: Strategy,
+        config: StrategyJobConfig,
+        clients: dict[str, Any] | None = None,
+        skip_auth: bool = False,
+        api_key: str | None = None,
+    ):
+        """
+        Initialize a StrategyJob.
+
+        Args:
+            strategy: The strategy to execute.
+            config: Strategy job configuration.
+            clients: Optional dict of pre-instantiated clients to inject directly.
+            skip_auth: If True, skips authentication (for SDK usage).
+            api_key: Optional API key for service account authentication.
+                If provided, will be passed to ClientManager and strategy.
+        """
+        self.strategy = strategy
+        self.config = config
+
+        self.job_id = strategy.name or "unknown"
+        self.clients = ClientManager(
+            clients=clients, skip_auth=skip_auth, api_key=api_key
+        )
+
+    def _setup_strategy(self):
+        """Setup the strategy instance"""
+        if not self.strategy:
+            raise ValueError("No strategy provided to StrategyJob")
+
+        self.strategy.log = self.log
+
+    def _is_using_api_key(self) -> bool:
+        """Check if API key authentication is being used."""
+        if self.clients._api_key:
+            return True
+
+        if self.clients.auth:
+            try:
+                creds = self.clients.auth._load_config_credentials()
+                if creds.get("api_key"):
+                    return True
+                if os.getenv("WAYFINDER_API_KEY"):
+                    return True
+            except Exception:
+                pass
+
+        return False
+
+    async def setup(self):
+        """
+        Initialize the strategy job and strategy.
+
+        Sets up authentication and initializes the strategy with merged configuration.
+        """
+        self._setup_strategy()
+
+        # Ensure auth token is set for API calls
+        if not self.clients._skip_auth:
+            is_api_key_auth = self._is_using_api_key()
+
+            if is_api_key_auth:
+                logger.debug("Using API key authentication")
+                if self.clients.auth:
+                    await self.clients.auth._ensure_bearer_token()
+            else:
+                # Try to ensure bearer token is set, authenticate if needed
+                try:
+                    if self.clients.auth:
+                        await self.clients.auth._ensure_bearer_token()
+                except (PermissionError, Exception) as e:
+                    if not isinstance(e, PermissionError):
+                        logger.warning(
+                            f"Authentication failed: {e}, trying OAuth fallback"
+                        )
+                    username = self.config.user.username
+                    password = self.config.user.password
+                    refresh_token = self.config.user.refresh_token
+                    if refresh_token or (username and password):
+                        await self.clients.authenticate(
+                            username=username,
+                            password=password,
+                            refresh_token=refresh_token,
+                        )
+                    else:
+                        raise ValueError(
+                            "Authentication required: provide api_key parameter for service account auth, "
+                            "or username+password/refresh_token in config.json for personal access"
+                        ) from e
+
+        existing_cfg = dict(getattr(self.strategy, "config", {}) or {})
+        strategy_cfg = dict(self.config.strategy_config or {})
+        merged_cfg = {**strategy_cfg, **existing_cfg}
+        self.strategy.config = merged_cfg
+        self.strategy.clients = self.clients
+        await self.strategy.setup()
+
+    async def execute_strategy(self, action: str, **kwargs) -> dict[str, Any]:
+        """Execute a strategy action (deposit, withdraw, update, status, partial_liquidate)"""
+        try:
+            if action == "deposit":
+                result = await self.strategy.deposit(**kwargs)
+            elif action == "withdraw":
+                result = await self.strategy.withdraw(**kwargs)
+            elif action == "update":
+                result = await self.strategy.update()
+            elif action == "status":
+                result = await self.strategy.status()
+            elif action == "partial_liquidate":
+                usd_value = kwargs.get("usd_value")
+                if usd_value is None:
+                    result = (
+                        False,
+                        "usd_value parameter is required for partial_liquidate",
+                    )
+                else:
+                    result = await self.strategy.partial_liquidate(usd_value)
+            else:
+                result = {"success": False, "message": f"Unknown action: {action}"}
+
+            await self.log(f"Strategy action '{action}' completed: {result}")
+            return result
+
+        except Exception as e:
+            error_msg = f"Strategy action '{action}' failed: {str(e)}"
+            await self.log(error_msg)
+            await self.handle_error({"error": str(e), "action": action})
+            return {"success": False, "error": str(e)}
+
+    async def run_continuous(self, interval_seconds: int | None = None):
+        """Run the strategy continuously at specified intervals"""
+        interval = interval_seconds or self.config.system.update_interval
+        logger.info(
+            f"Starting continuous execution for strategy: {self.strategy.name} with interval {interval}s"
+        )
+
+        while True:
+            try:
+                await self.execute_strategy("update")
+                await asyncio.sleep(interval)
+
+            except asyncio.CancelledError:
+                logger.info("Continuous execution cancelled")
+                break
+            except Exception as e:
+                logger.error(f"Error in continuous execution: {str(e)}")
+                await asyncio.sleep(interval)
+
+    async def log(self, msg: str):
+        """Log messages for the job"""
+        logger.info(f"Job {self.job_id}: {msg}")
+
+    async def handle_error(self, error_data: dict[str, Any]) -> None:
+        """
+        Handle errors that occur during strategy execution.
+
+        Args:
+            error_data: Dictionary containing error information. Expected keys:
+                - error: Error message or exception string
+                - action: Strategy action that failed (e.g., "deposit", "update")
+
+        Note:
+            Base implementation is a no-op. Subclasses or external systems
+            can override this method to implement custom error handling,
+            logging, alerting, or recovery logic.
+        """
+        pass
+
+    async def stop(self):
+        """Stop the strategy job and cleanup"""
+        if hasattr(self.strategy, "stop"):
+            await self.strategy.stop()
+
+        logger.info(f"Strategy job {self.job_id} stopped")

wayfinder_paths/core/engine/__init__.py

@@ -0,0 +1,5 @@
+"""Core Engine Module"""
+
+from .StrategyJob import StrategyJob
+
+__all__ = ["StrategyJob", "GLOBAL_IMPORTS"]

wayfinder_paths/core/engine/manifest.py

@@ -0,0 +1,97 @@
+from typing import Any
+
+import yaml
+from pydantic import BaseModel, Field, validator
+
+
+class AdapterRequirement(BaseModel):
+    name: str = Field(
+        ..., description="Adapter symbolic name (e.g., BALANCE, HYPERLIQUID)"
+    )
+    capabilities: list[str] = Field(default_factory=list)
+
+
+class AdapterManifest(BaseModel):
+    schema_version: str = Field(default="0.1")
+    entrypoint: str
+    capabilities: list[str] = Field(default_factory=list)
+    dependencies: list[str] = Field(default_factory=list)
+
+    @validator("entrypoint")
+    def validate_entrypoint(cls, v: str) -> str:
+        if "." not in v:
+            raise ValueError("entrypoint must be a full import path")
+        return v
+
+    @validator("capabilities")
+    def validate_capabilities(cls, v: list[str]) -> list[str]:
+        if not v:
+            raise ValueError("capabilities cannot be empty")
+        return v
+
+    @validator("dependencies")
+    def validate_dependencies(cls, v: list[str]) -> list[str]:
+        if not v:
+            raise ValueError("dependencies cannot be empty")
+        return v
+
+
+class StrategyManifest(BaseModel):
+    schema_version: str = Field(default="0.1")
+    entrypoint: str = Field(
+        ...,
+        description="Python path to class, e.g. strategies.funding_rate_strategy.FundingRateStrategy",
+    )
+    name: str | None = Field(
+        default=None,
+        description="Unique name identifier for this strategy instance. Used to look up dedicated wallet in wallets.json by label.",
+    )
+    permissions: dict[str, Any] = Field(default_factory=dict)
+    adapters: list[AdapterRequirement] = Field(default_factory=list)
+
+    @validator("entrypoint")
+    def validate_entrypoint(cls, v: str) -> str:
+        if "." not in v:
+            raise ValueError(
+                "entrypoint must be a full import path to a Strategy class"
+            )
+        return v
+
+    @validator("permissions")
+    def validate_permissions(cls, v: dict) -> dict:
+        if "policy" not in v:
+            raise ValueError("permissions.policy is required")
+        if not v["policy"]:
+            raise ValueError("permissions.policy cannot be empty")
+        return v
+
+    @validator("adapters")
+    def validate_adapters(cls, v: list) -> list:
+        if not v:
+            raise ValueError("adapters cannot be empty")
+        return v
+
+
+def load_adapter_manifest(path: str) -> AdapterManifest:
+    with open(path) as f:
+        data = yaml.safe_load(f)
+    return AdapterManifest(**data)
+
+
+def load_strategy_manifest(path: str) -> StrategyManifest:
+    with open(path) as f:
+        data = yaml.safe_load(f)
+    return StrategyManifest(**data)
+
+
+def load_manifest(path: str) -> StrategyManifest:
+    """Legacy function for backward compatibility."""
+    return load_strategy_manifest(path)
+
+
+def validate_manifest(manifest: StrategyManifest) -> None:
+    # Simple v0.1 rules: require at least one adapter and permissions.policy
+    if not manifest.adapters:
+        raise ValueError("Manifest must declare at least one adapter")
+    if "policy" not in manifest.permissions:
+        raise ValueError("Manifest.permissions must include 'policy'")