wayfinder-paths 0.1.19__py3-none-any.whl → 0.1.20__py3-none-any.whl

wayfinder_paths/templates/adapter/README.md

@@ -1,89 +1,150 @@
-# Adapter Template
+# Adapter Template
 
-Adapters expose protocol-specific capabilities to strategies. They should be thin, async wrappers around one or more clients from `wayfinder_paths.core.clients`.
+Adapters expose protocol-specific capabilities to strategies. They wrap one or more clients from `wayfinder_paths.core.clients`.
 
-## Quick start
+## Quick Start
 
 1. Copy the template:
-   ```
+   ```bash
    cp -r wayfinder_paths/templates/adapter wayfinder_paths/adapters/my_adapter
    ```
 2. Rename `MyAdapter` in `adapter.py` to match your adapter's purpose.
-3. Implement the public methods that provide your adapter's capabilities.
-4. Add tests in `test_adapter.py`.
+3. Set `adapter_type` to a unique identifier (e.g., `"MY_PROTOCOL"`).
+4. Implement your public methods.
+5. Add tests in `test_adapter.py`.
 
-## Layout
+## Directory Structure
 
 ```
 my_adapter/
 ├── adapter.py          # Adapter implementation
-├── examples.json       # Example payloads (optional but encouraged)
-├── test_adapter.py     # Pytest smoke tests
-└── README.md           # Adapter-specific notes
+├── examples.json       # Example payloads (optional)
+├── test_adapter.py     # Pytest tests
+└── README.md           # Adapter documentation
 ```
 
-## Skeleton adapter
+## Adapter Structure
 
 ```python
 from typing import Any
 
 from wayfinder_paths.core.adapters.BaseAdapter import BaseAdapter
-from wayfinder_paths.core.clients.PoolClient import PoolClient
+from wayfinder_paths.core.clients.SomeClient import SomeClient
 
 
 class MyAdapter(BaseAdapter):
-    adapter_type = "MY_ADAPTER"
+    """Adapter for MyProtocol operations."""
+
+    adapter_type = "MY_PROTOCOL"
 
     def __init__(self, config: dict[str, Any] | None = None):
         super().__init__("my_adapter", config)
-        self.pool_client = PoolClient()
+        self.client = SomeClient()
 
     async def connect(self) -> bool:
-        """Optional: prime caches / test connectivity."""
+        """Optional: Establish connectivity."""
         return True
 
-    async def get_pools(self, pool_ids: list[str]) -> tuple[bool, Any]:
-        """Example capability that proxies PoolClient."""
+    async def do_something(self, param: str) -> tuple[bool, Any]:
+        """
+        Execute an operation.
+
+        Args:
+            param: Operation parameter
+
+        Returns:
+            Tuple of (success, data) where data is result or error message
+        """
         try:
-            data = await self.pool_client.get_pools_by_ids(
-                pool_ids=pool_ids
-            )
-            return (True, data)
-        except Exception as exc:  # noqa: BLE001
-            self.logger.error(f"Failed to fetch pools: {exc}")
-            return (False, str(exc))
+            result = await self.client.call(param)
+            return (True, result)
+        except Exception as e:
+            self.logger.error(f"Operation failed: {e}")
+            return (False, str(e))
 ```
 
-Your adapter should return `(success, payload)` tuples for every operation, just like the built-in adapters do.
+## Key Conventions
+
+1. **Return tuples**: All methods return `(success: bool, data: Any)`
+2. **Adapter type**: Set `adapter_type` for registry lookups
+3. **Config access**: Use `self.config` for configuration
+4. **Logging**: Use `self.logger` for consistent logging
+5. **Error handling**: Catch exceptions and return `(False, error_message)`
+
+## BaseAdapter Interface
+
+```python
+class BaseAdapter(ABC):
+    adapter_type: str | None = None
+
+    def __init__(self, name: str, config: dict | None = None):
+        self.name = name
+        self.config = config or {}
+        self.logger = logger.bind(adapter=self.__class__.__name__)
+
+    async def connect(self) -> bool:
+        """Establish connectivity (default: True)."""
+        return True
+
+    async def get_balance(self, asset: str) -> dict:
+        """Get balance (raises NotImplementedError by default)."""
+        raise NotImplementedError
+
+    async def health_check(self) -> dict:
+        """Check adapter health."""
+        ...
+
+    async def close(self) -> None:
+        """Clean up resources."""
+        pass
+```
 
 ## Testing
 
-`test_adapter.py` should cover the public methods you expose. Patch out remote clients with `unittest.mock.AsyncMock` so tests run offline.
+Create `test_adapter.py`:
 
 ```python
 import pytest
 from unittest.mock import AsyncMock, patch
+from .adapter import MyAdapter
+
+
+class TestMyAdapter:
+    @pytest.fixture
+    def adapter(self):
+        return MyAdapter()
+
+    @pytest.mark.asyncio
+    async def test_do_something_success(self, adapter):
+        with patch.object(adapter, "client") as mock_client:
+            mock_client.call = AsyncMock(return_value={"result": "ok"})
+
+            success, data = await adapter.do_something(param="test")
+
+            assert success
+            assert data["result"] == "ok"
+
+    @pytest.mark.asyncio
+    async def test_do_something_failure(self, adapter):
+        with patch.object(adapter, "client") as mock_client:
+            mock_client.call = AsyncMock(side_effect=Exception("API error"))
+
+            success, data = await adapter.do_something(param="test")
+
+            assert not success
+            assert "error" in data.lower()
+```
+
+Run tests:
 
-from wayfinder_paths.adapters.my_adapter.adapter import MyAdapter
-
-
-@pytest.mark.asyncio
-async def test_get_pools():
-    with patch(
-        "wayfinder_paths.adapters.my_adapter.adapter.PoolClient",
-        return_value=AsyncMock(
-            get_pools_by_ids=AsyncMock(return_value={"pools": []})
-        ),
-    ):
-        adapter = MyAdapter(config={})
-        success, data = await adapter.get_pools(["pool-1"])
-        assert success
-        assert "pools" in data
+```bash
+poetry run pytest wayfinder_paths/adapters/my_adapter/ -v
 ```
 
-## Best practices
+## Best Practices
 
-- Keep adapters stateless and idempotent—strategies may reuse instances across operations.
-- Use `self.logger` for contextual logging (BaseAdapter has already bound the adapter name).
-- Return `(success, payload)` tuples consistently for all operations.
-- Raise `NotImplementedError` for capabilities you intentionally do not support yet.
+- Keep adapters thin - business logic belongs in strategies
+- Mock clients in tests, not adapters
+- Document each public method with Args/Returns docstrings
+- Use type hints for all parameters and return values
+- Log errors with context for debugging

wayfinder_paths/templates/adapter/adapter.py

@@ -4,22 +4,13 @@ from wayfinder_paths.core.adapters.BaseAdapter import BaseAdapter
 
 
 class MyAdapter(BaseAdapter):
-    """
-    Template adapter for a protocol/exchange integration.
-    Copy this folder, rename it (e.g., my_adapter), and implement your adapter methods.
-    """
-
     adapter_type: str = "MY_ADAPTER"
 
     def __init__(self, config: dict[str, Any] | None = None):
         super().__init__("my_adapter", config)
 
     async def connect(self) -> bool:
-        """Establish connectivity to remote service(s) if needed."""
         return True
 
     async def example_operation(self, **kwargs) -> tuple[bool, str]:
-        """
-        Example operation. Replace with your adapter's real API.
-        """
         return (True, "example.op executed")

wayfinder_paths/templates/adapter/test_adapter.py

@@ -1,49 +1,30 @@
-"""Test template for adapters.
-
-Quick setup:
-1. Replace MyAdapter with your actual adapter class name
-2. Implement test_basic_functionality with your adapter's core methods
-3. Add client mocking if your adapter uses external clients
-4. Run: pytest wayfinder_paths/adapters/your_adapter/ -v
-
-Note: examples.json is optional for adapters (not required).
-"""
-
 import pytest
 
 # TODO: Replace MyAdapter with your actual adapter class name
 from .adapter import MyAdapter
 
 # For mocking clients, uncomment when needed:
-# from unittest.mock import AsyncMock, patch
 
 
 class TestMyAdapter:
-    """Test cases for MyAdapter"""
-
     @pytest.fixture
     def adapter(self):
-        """Create adapter instance for testing."""
         return MyAdapter(config={})
 
     @pytest.mark.asyncio
     async def test_health_check(self, adapter):
-        """Test adapter health check"""
         health = await adapter.health_check()
         assert isinstance(health, dict)
         assert health.get("status") in {"healthy", "unhealthy", "error"}
 
     @pytest.mark.asyncio
     async def test_connect(self, adapter):
-        """Test adapter connection"""
         ok = await adapter.connect()
         assert isinstance(ok, bool)
 
     def test_capabilities(self, adapter):
-        """Test adapter capabilities"""
         assert hasattr(adapter, "adapter_type")
 
     @pytest.mark.asyncio
     async def test_basic_functionality(self, adapter):
-        """REQUIRED: Test your adapter's core functionality."""
         assert adapter is not None

wayfinder_paths/templates/strategy/README.md

@@ -1,48 +1,65 @@
 # Strategy Template
 
-This template provides the scaffolding for a new strategy. It mirrors the structure in `wayfinder_paths/strategies/...`.
+This template provides scaffolding for a new strategy.
 
 ## Quick Start
 
-1. Copy the template to a new folder:
-   ```
+1. Copy the template:
+   ```bash
    cp -r wayfinder_paths/templates/strategy wayfinder_paths/strategies/my_strategy
    ```
+   Or use the convenience command:
+   ```bash
+   just create-strategy "My Strategy Name"
+   ```
 2. Rename the class in `strategy.py` to match your strategy name.
-3. Fill out `examples.json` with sample CLI invocations and `test_strategy.py` with at least one smoke test.
-4. Implement the required strategy methods (`deposit`, `update`, `_status`, optionally override `withdraw`).
+3. Implement the required methods (`deposit`, `update`, `exit`, `_status`).
+4. Add tests in `test_strategy.py`.
+5. Fill out `examples.json` with sample CLI invocations.
 
-## Layout
+## Directory Structure
 
 ```
 my_strategy/
 ├── strategy.py          # Strategy implementation
 ├── examples.json        # Example CLI payloads
-├── test_strategy.py     # Pytest-based smoke tests
-└── README.md            # Strategy-specific documentation
+├── test_strategy.py     # Pytest tests
+└── README.md            # Strategy documentation
 ```
 
-## Required methods
+## Required Methods
 
 ```python
 async def deposit(self, main_token_amount: float, gas_token_amount: float) -> StatusTuple:
-    """Move funds from the main wallet into the strategy wallet and prepare on-chain positions."""
+    """Move funds from main wallet into strategy wallet and deploy capital."""
 
 async def update(self) -> StatusTuple:
-    """Periodic rebalance/update loop."""
+    """Periodic rebalance/optimization loop."""
+
+async def exit(self, **kwargs) -> StatusTuple:
+    """Transfer funds from strategy wallet back to main wallet."""
 
 async def _status(self) -> StatusDict:
-    """Return portfolio_value, net_deposit, and strategy_status payloads."""
+    """Return portfolio_value, net_deposit, and strategy_status."""
 ```
 
-`Strategy.withdraw` already unwinds ledger operations. Override it only if you need custom exit logic.
+## Optional Methods
 
-## Wiring adapters
+```python
+async def withdraw(self, **kwargs) -> StatusTuple:
+    """Unwind positions. Default implementation unwinds ledger operations."""
+
+async def partial_liquidate(self, usd_value: float) -> tuple[bool, LiquidationResult]:
+    """Liquidate a portion of the position by USD value."""
 
-Strategies typically:
+async def setup(self) -> None:
+    """Post-construction initialization."""
 
-2. Instantiate adapters (balance, ledger, protocol specific, etc.).
-3. Register adapters via `self.register_adapters([...])` and keep references as attributes.
+async def health_check(self) -> dict:
+    """Check strategy and adapter health."""
+```
+
+## Strategy Structure
 
 ```python
 from wayfinder_paths.core.strategies.Strategy import StatusDict, StatusTuple, Strategy
@@ -50,83 +67,120 @@ from wayfinder_paths.adapters.balance_adapter.adapter import BalanceAdapter
 
 
 class MyStrategy(Strategy):
-    name = "Demo Strategy"
+    name = "My Strategy"
 
-    def __init__(self, config: dict | None = None):
-        super().__init__()
+    def __init__(self, config: dict | None = None, **kwargs):
+        super().__init__(config, **kwargs)
         self.config = config or {}
-        balance_adapter = BalanceAdapter(self.config)
+
+        # Initialize and register adapters
+        balance_adapter = BalanceAdapter(
+            self.config,
+            main_wallet_signing_callback=kwargs.get("main_wallet_signing_callback"),
+            strategy_wallet_signing_callback=kwargs.get("strategy_wallet_signing_callback"),
+        )
         self.register_adapters([balance_adapter])
         self.balance_adapter = balance_adapter
 
     async def deposit(
         self, main_token_amount: float = 0.0, gas_token_amount: float = 0.0
     ) -> StatusTuple:
-        """Perform validation, move funds, and optionally deploy capital."""
         if main_token_amount <= 0:
             return (False, "Nothing to deposit")
 
-        success, _ = await self.balance_adapter.get_balance(
-            query=self.config.get("token_id"),
-            wallet_address=self.config.get("main_wallet", {}).get("address"),
-        )
-        if not success:
-            return (False, "Unable to fetch balances")
-
-        self.last_deposit = main_token_amount
+        # Implement deposit logic
         return (True, f"Deposited {main_token_amount} tokens")
 
     async def update(self) -> StatusTuple:
-        """Execute your strategy logic periodically."""
-        return (True, "No-op update")
+        # Implement rebalancing logic
+        return (True, "Update complete")
+
+    async def exit(self, **kwargs) -> StatusTuple:
+        # Implement exit logic
+        return (True, "Exit complete")
 
     async def _status(self) -> StatusDict:
-        """Surface state back to run_strategy.py."""
-        success, balance = await self.balance_adapter.get_balance(
-            query=self.config.get("token_id"),
-            wallet_address=self.config.get("strategy_wallet", {}).get("address"),
-        )
         return {
-            "portfolio_value": float(balance or 0),
-            "net_deposit": float(getattr(self, "last_deposit", 0.0)),
-            "strategy_status": {"message": "healthy" if success else "unknown"},
+            "portfolio_value": 0.0,
+            "net_deposit": 0.0,
+            "strategy_status": {"message": "healthy"},
+            "gas_available": 0.0,
+            "gassed_up": True,
         }
 ```
 
 ## Testing
 
-`test_strategy.py` should cover at least deposit/update/status. Use `pytest.mark.asyncio` and patch adapters or services as needed.
+Create `test_strategy.py` using `examples.json`:
 
 ```python
 import pytest
-from wayfinder_paths.strategies.my_strategy.strategy import MyStrategy
+from pathlib import Path
+from tests.test_utils import load_strategy_examples
+from .strategy import MyStrategy
 
 
 @pytest.mark.asyncio
-async def test_status_shape():
-    strat = MyStrategy(config={})
-    status = await strat._status()
-    assert set(status) == {"portfolio_value", "net_deposit", "strategy_status"}
+async def test_smoke():
+    """Basic strategy lifecycle test."""
+    examples = load_strategy_examples(Path(__file__))
+    smoke_example = examples["smoke"]
+
+    s = MyStrategy()
+
+    # Deposit
+    deposit_params = smoke_example.get("deposit", {})
+    ok, _ = await s.deposit(**deposit_params)
+    assert ok
+
+    # Update
+    ok, _ = await s.update()
+    assert ok
+
+    # Status
+    st = await s._status()
+    assert "portfolio_value" in st
+    assert "net_deposit" in st
+    assert "strategy_status" in st
+```
+
+Run tests:
+
+```bash
+poetry run pytest wayfinder_paths/strategies/my_strategy/ -v
 ```
 
-## Running the strategy locally
+## Running the Strategy
 
 ```bash
-# Install dependencies & create wallets first
+# Install dependencies
 poetry install
-# Creates a main wallet (or use 'just create-strategy' which auto-creates wallets)
-poetry run python wayfinder_paths/scripts/make_wallets.py -n 1
 
-# Copy config and edit credentials
-cp wayfinder_paths/config.example.json config.json
+# Generate wallets
+just create-wallets
+just create-wallet my_strategy
+
+# Configure API key in config.json
+
+# Check status
+poetry run python wayfinder_paths/run_strategy.py my_strategy --action status --config config.json
+
+# Deposit
+poetry run python wayfinder_paths/run_strategy.py my_strategy \
+    --action deposit --main-token-amount 100 --gas-token-amount 0.01 --config config.json
+
+# Run update
+poetry run python wayfinder_paths/run_strategy.py my_strategy --action update --config config.json
 
-# Run your strategy
-poetry run python wayfinder_paths/run_strategy.py my_strategy --action status --config $(pwd)/config.json
+# Withdraw
+poetry run python wayfinder_paths/run_strategy.py my_strategy --action withdraw --config config.json
 ```
 
-## Best practices
+## Best Practices
 
-- Return `(success: bool, message: str)` tuples from `deposit`/`update`.
-- Always populate `portfolio_value`, `net_deposit`, and `strategy_status` keys in `_status`.
-- Register adapters via `register_adapters` in your `__init__` method.
-- Keep strategy logic clear and well-documented.
+- Return `(success: bool, message: str)` tuples from all action methods
+- Always populate `portfolio_value`, `net_deposit`, and `strategy_status` in `_status`
+- Register adapters via `register_adapters()` in `__init__`
+- Use adapters for external operations, not clients directly
+- Keep strategy logic clear and well-documented
+- Add error handling with informative messages

wayfinder_paths/templates/strategy/strategy.py

@@ -10,41 +10,20 @@ class MyStrategy(Strategy):
         super().__init__()
 
     async def setup(self):
-        """Optional initialization logic."""
         return None
 
     async def deposit(
         self, main_token_amount: float, gas_token_amount: float
     ) -> StatusTuple:
-        """Deposit funds into the strategy.
-
-        Args:
-            main_token_amount: Amount of the main token to deposit (e.g., USDC, USDT0)
-            gas_token_amount: Amount of gas token to deposit (e.g., ETH, HYPE)
-        """
         return (True, "Deposit successful")
 
     async def withdraw(self, amount: float | None = None) -> StatusTuple:
-        """Withdraw funds from the strategy.
-
-        This method is required. The base Strategy class provides a default
-        implementation that unwinds all ledger operations. You can either:
-        1. Call the parent implementation (as shown here, recommended for most cases)
-        2. Override this method for custom withdrawal logic (e.g., unwinding specific positions,
-           converting tokens, handling partial withdrawals)
-
-        Args:
-            amount: Optional amount to withdraw. If None, withdraws all funds.
-        """
-        # Call parent implementation which unwinds all ledger operations
         return await super().withdraw(amount=amount)
 
     async def update(self) -> StatusTuple:
-        """Rebalance or update positions."""
         return (True, "Update successful")
 
     async def _status(self) -> StatusDict:
-        """Report strategy status."""
         return {
             "portfolio_value": 0.0,
             "net_deposit": 0.0,
@@ -53,5 +32,4 @@ class MyStrategy(Strategy):
 
     @staticmethod
     def policies() -> list[str]:
-        """Return policy strings used to scope on-chain permissions."""
         return []

wayfinder_paths/templates/strategy/test_strategy.py

@@ -1,15 +1,3 @@
-"""Test template for strategies.
-
-REQUIRED: This template uses examples.json for all test data.
-Replace 'MyStrategy' with your actual strategy class name.
-
-Quick setup:
-1. Replace MyStrategy with your strategy class name
-2. Create examples.json with a 'smoke' example (see TESTING.md)
-3. Add mocking if your strategy uses adapters
-4. Run: pytest wayfinder_paths/strategies/your_strategy/ -v
-"""
-
 import sys
 from pathlib import Path
 
@@ -31,7 +19,6 @@ elif sys.path.index(_wayfinder_path_str) > 0:
 
 import pytest  # noqa: E402
 
-# Import test utilities
 try:
     from tests.test_utils import get_canonical_examples, load_strategy_examples
 except ImportError:
@@ -48,7 +35,6 @@ except ImportError:
 
 @pytest.fixture
 def strategy():
-    """Create a strategy instance for testing with minimal config."""
     mock_config = {
         "main_wallet": {"address": "0x1234567890123456789012345678901234567890"},
         "strategy_wallet": {"address": "0xabcdefabcdefabcdefabcdefabcdefabcdefabcd"},
@@ -69,10 +55,7 @@ def strategy():
     #     def get_balance_side_effect(query, wallet_address, **kwargs):
     #         token_id = query if isinstance(query, str) else (query or {}).get("token_id")
     #         if token_id == "usd-coin-base" or token_id == "usd-coin":
-    #             return usdc_balance_mock.return_value
     #         elif token_id == "ethereum-base" or token_id == "ethereum":
-    #             return gas_balance_mock.return_value
-    #         return (True, 1000000000)
     #
     #     s.balance_adapter.get_balance = AsyncMock(
     #         side_effect=get_balance_side_effect
@@ -94,19 +77,15 @@ def strategy():
     # Example for transaction adapters:
     # if hasattr(s, "tx_adapter") and s.tx_adapter:
     #     s.tx_adapter.move_from_main_wallet_to_strategy_wallet = AsyncMock(
-    #         return_value=(True, "Transfer successful (simulated)")
     #     )
     #     s.tx_adapter.move_from_strategy_wallet_to_main_wallet = AsyncMock(
-    #         return_value=(True, "Transfer successful (simulated)")
     #     )
 
     # Example for ledger_adapter:
     # if hasattr(s, "ledger_adapter") and s.ledger_adapter:
     #     s.ledger_adapter.get_strategy_net_deposit = AsyncMock(
-    #         return_value=(True, {"net_deposit": 0})
     #     )
     #     s.ledger_adapter.get_strategy_transactions = AsyncMock(
-    #         return_value=(True, {"transactions": []})
     #     )
 
     return s
@@ -115,7 +94,6 @@ def strategy():
 @pytest.mark.asyncio
 @pytest.mark.smoke
 async def test_smoke(strategy):
-    """REQUIRED: Basic smoke test - verifies strategy lifecycle."""
     examples = load_strategy_examples(Path(__file__))
     smoke_data = examples["smoke"]
 
@@ -137,11 +115,6 @@ async def test_smoke(strategy):
 
 @pytest.mark.asyncio
 async def test_canonical_usage(strategy):
-    """REQUIRED: Test canonical usage examples from examples.json (minimum).
-
-    Canonical usage = all positive usage examples (excluding error cases).
-    This is the MINIMUM requirement - feel free to add more test cases here.
-    """
     examples = load_strategy_examples(Path(__file__))
     canonical = get_canonical_examples(examples)
 
@@ -164,7 +137,6 @@ async def test_canonical_usage(strategy):
 
 @pytest.mark.asyncio
 async def test_error_cases(strategy):
-    """OPTIONAL: Test error scenarios from examples.json."""
     examples = load_strategy_examples(Path(__file__))
 
     for example_name, example_data in examples.items():