wayfinder-paths 0.1.23__py3-none-any.whl → 0.1.25__py3-none-any.whl

wayfinder_paths/core/constants/moonwell_abi.py

@@ -1,6 +1,4 @@
-# mToken (CErc20Delegator) ABI - for lending, borrowing, and position management
 MTOKEN_ABI = [
-    # Lend (supply) tokens by minting mTokens
     {
         "name": "mint",
         "type": "function",
@@ -8,7 +6,6 @@ MTOKEN_ABI = [
         "inputs": [{"name": "mintAmount", "type": "uint256"}],
         "outputs": [{"name": "", "type": "uint256"}],
     },
-    # Withdraw (redeem) underlying by burning mTokens
     {
         "name": "redeem",
         "type": "function",
@@ -16,7 +13,6 @@ MTOKEN_ABI = [
         "inputs": [{"name": "redeemTokens", "type": "uint256"}],
         "outputs": [{"name": "", "type": "uint256"}],
     },
-    # Withdraw exact underlying amount
     {
         "name": "redeemUnderlying",
         "type": "function",
@@ -24,7 +20,6 @@ MTOKEN_ABI = [
         "inputs": [{"name": "redeemAmount", "type": "uint256"}],
         "outputs": [{"name": "", "type": "uint256"}],
     },
-    # Borrow underlying tokens
     {
         "name": "borrow",
         "type": "function",
@@ -32,7 +27,6 @@ MTOKEN_ABI = [
         "inputs": [{"name": "borrowAmount", "type": "uint256"}],
         "outputs": [{"name": "", "type": "uint256"}],
     },
-    # Repay borrowed tokens
     {
         "name": "repayBorrow",
         "type": "function",
@@ -124,7 +118,6 @@ MTOKEN_ABI = [
         "inputs": [],
         "outputs": [{"name": "", "type": "uint256"}],
     },
-    # Accrue interest
     {
         "name": "accrueInterest",
         "type": "function",
@@ -141,9 +134,7 @@ MTOKEN_ABI = [
     },
 ]
 
-# Comptroller ABI - for collateral management and account liquidity
 COMPTROLLER_ABI = [
-    # Enable a market as collateral
     {
         "name": "enterMarkets",
         "type": "function",
@@ -151,7 +142,6 @@ COMPTROLLER_ABI = [
         "inputs": [{"name": "mTokens", "type": "address[]"}],
         "outputs": [{"name": "", "type": "uint256[]"}],
     },
-    # Disable a market as collateral
     {
         "name": "exitMarket",
         "type": "function",
@@ -234,7 +224,6 @@ COMPTROLLER_ABI = [
         "inputs": [],
         "outputs": [{"name": "", "type": "uint256"}],
     },
-    # Claim rewards for a user (called on comptroller in some versions)
     {
         "name": "claimReward",
         "type": "function",
@@ -244,9 +233,7 @@ COMPTROLLER_ABI = [
     },
 ]
 
-# Reward Distributor ABI - for claiming WELL rewards
 REWARD_DISTRIBUTOR_ABI = [
-    # Claim rewards for all markets
     {
         "name": "claimReward",
         "type": "function",
@@ -254,7 +241,6 @@ REWARD_DISTRIBUTOR_ABI = [
         "inputs": [],
         "outputs": [],
     },
-    # Claim rewards for specific holder and markets
     {
         "name": "claimReward",
         "type": "function",
@@ -350,7 +336,6 @@ REWARD_DISTRIBUTOR_ABI = [
     },
 ]
 
-# WETH ABI for wrapping/unwrapping ETH
 WETH_ABI = [
     {
         "name": "deposit",

wayfinder_paths/core/engine/manifest.py

@@ -0,0 +1,66 @@
+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 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_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'")

wayfinder_paths/core/strategies/Strategy.py

@@ -1,6 +1,5 @@
 from __future__ import annotations
 
-import traceback
 from abc import ABC, abstractmethod
 from collections.abc import Awaitable, Callable
 from typing import Any, TypedDict
@@ -56,7 +55,6 @@ class Strategy(ABC):
         strategy_wallet_signing_callback: Callable[[dict], Awaitable[str]]
         | None = None,
     ):
-        self.adapters = {}
         self.ledger_adapter = None
         self.logger = logger.bind(strategy=self.__class__.__name__)
         self.config = config
@@ -66,12 +64,6 @@ class Strategy(ABC):
     async def setup(self) -> None:
         pass
 
-    async def log(self, msg: str) -> None:
-        self.logger.info(msg)
-
-    async def quote(self) -> None:
-        pass
-
     def _get_strategy_wallet_address(self) -> str:
         strategy_wallet = self.config.get("strategy_wallet")
         if not strategy_wallet or not isinstance(strategy_wallet, dict):
@@ -122,59 +114,6 @@ class Strategy(ABC):
 
         return status
 
-    def register_adapters(self, adapters: list[Any]) -> None:
-        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]]:
-        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 {
-            "name": getattr(cls, "name", None),
-            "description": getattr(cls, "description", None),
-            "summary": getattr(cls, "summary", None),
-        }
-
-    async def health_check(self) -> dict[str, Any]:
-        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]:

wayfinder_paths/core/strategies/__init__.py

@@ -1,3 +1,12 @@
 from .base import StatusDict, StatusTuple, Strategy
+from .opa_loop import OPAConfig, OPALoopMixin, Plan, PlanStep
 
-__all__ = ["Strategy", "StatusDict", "StatusTuple"]
+__all__ = [
+    "Strategy",
+    "StatusDict",
+    "StatusTuple",
+    "OPALoopMixin",
+    "OPAConfig",
+    "Plan",
+    "PlanStep",
+]

wayfinder_paths/core/strategies/opa_loop.py

@@ -0,0 +1,167 @@
+from __future__ import annotations
+
+from abc import ABC, abstractmethod
+from dataclasses import dataclass, field
+from enum import Enum
+from typing import Any
+
+from loguru import logger
+
+
+@dataclass
+class OPAConfig:
+    max_iterations_per_tick: int = 4
+    max_steps_per_iteration: int = 5
+    max_total_steps_per_tick: int = 15
+
+
+@dataclass
+class PlanStep[TOp: Enum]:
+    op: TOp
+    priority: int
+    key: str
+    params: dict[str, Any] = field(default_factory=dict)
+    reason: str = ""
+
+    def __repr__(self) -> str:
+        return f"PlanStep({self.op.name}, priority={self.priority}, key={self.key!r})"
+
+
+@dataclass
+class Plan[TOp: Enum]:
+    steps: list[PlanStep[TOp]] = field(default_factory=list)
+    desired_state: dict[str, Any] = field(default_factory=dict)
+
+    def __bool__(self) -> bool:
+        return bool(self.steps)
+
+    def __len__(self) -> int:
+        return len(self.steps)
+
+
+class OPALoopMixin[TInventory, TOp: Enum](ABC):
+    @property
+    @abstractmethod
+    def opa_config(self) -> OPAConfig: ...
+
+    @abstractmethod
+    async def observe(self) -> TInventory: ...
+
+    @abstractmethod
+    def plan(self, inventory: TInventory) -> Plan[TOp]: ...
+
+    @abstractmethod
+    async def execute_step(
+        self, step: PlanStep[TOp], inventory: TInventory
+    ) -> tuple[bool, str]: ...
+
+    @abstractmethod
+    def get_inventory_changing_ops(self) -> set[TOp]: ...
+
+    async def on_loop_start(self) -> tuple[bool, str] | None:
+        return None
+
+    async def on_step_executed(
+        self, step: PlanStep[TOp], success: bool, message: str
+    ) -> None:
+        return None
+
+    def should_stop_early(
+        self, inventory: TInventory, iteration: int
+    ) -> tuple[bool, str] | None:
+        return None
+
+    async def on_loop_end(
+        self, success: bool, messages: list[str], total_steps: int
+    ) -> None:
+        return None
+
+    async def run_opa_loop(self) -> tuple[bool, str, bool]:
+        loop_logger = logger.bind(loop="opa")
+
+        setup_result = await self.on_loop_start()
+        if setup_result is not None:
+            return (*setup_result, False)
+
+        total_steps = 0
+        messages: list[str] = []
+        rotated = False
+        config = self.opa_config
+
+        try:
+            for iteration in range(config.max_iterations_per_tick):
+                loop_logger.debug(
+                    f"OPA iteration {iteration + 1}/{config.max_iterations_per_tick}"
+                )
+
+                # OBSERVE
+                try:
+                    inventory = await self.observe()
+                except Exception as e:
+                    loop_logger.error(f"Observe failed: {e}")
+                    return (False, f"Failed to observe: {e}", rotated)
+
+                stop_result = self.should_stop_early(inventory, iteration)
+                if stop_result is not None:
+                    await self.on_loop_end(stop_result[0], messages, total_steps)
+                    return (*stop_result, rotated)
+
+                # PLAN
+                try:
+                    plan = self.plan(inventory)
+                except Exception as e:
+                    loop_logger.error(f"Plan failed: {e}")
+                    return (False, f"Failed to plan: {e}", rotated)
+
+                if not plan.steps:
+                    loop_logger.debug("Plan is empty, nothing to do")
+                    break
+
+                loop_logger.debug(f"Plan has {len(plan.steps)} steps")
+
+                # ACT - execute steps up to limit
+                steps_this_iteration = 0
+                for step in plan.steps[: config.max_steps_per_iteration]:
+                    if total_steps >= config.max_total_steps_per_tick:
+                        loop_logger.warning(
+                            f"Hit max total steps ({config.max_total_steps_per_tick})"
+                        )
+                        break
+
+                    loop_logger.info(f"Executing step: {step.op.name} ({step.reason})")
+
+                    try:
+                        success, msg = await self.execute_step(step, inventory)
+                    except Exception as e:
+                        success = False
+                        msg = f"Step {step.op.name} raised exception: {e}"
+                        loop_logger.error(msg)
+
+                    await self.on_step_executed(step, success, msg)
+                    messages.append(f"{step.op.name}: {msg}")
+                    total_steps += 1
+                    steps_this_iteration += 1
+
+                    if step.params.get("is_rotation"):
+                        rotated = True
+
+                    # Re-observe after inventory-changing ops (failed steps likely didn't change anything)
+                    if success and step.op in self.get_inventory_changing_ops():
+                        loop_logger.debug(
+                            f"Step {step.op.name} changes inventory, re-observing"
+                        )
+                        break
+
+                if steps_this_iteration == 0:
+                    break
+
+        except Exception as e:
+            loop_logger.error(f"OPA loop failed: {e}")
+            await self.on_loop_end(False, messages, total_steps)
+            return (False, f"OPA loop error: {e}", rotated)
+
+        final_message = "; ".join(messages) if messages else "No action needed"
+        loop_logger.info(f"OPA loop complete: {total_steps} steps executed")
+
+        await self.on_loop_end(True, messages, total_steps)
+        return (True, final_message, rotated)