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

wayfinder_paths/core/services/test_local_evm_txn.py

@@ -1,145 +0,0 @@
-from __future__ import annotations
-
-from unittest.mock import AsyncMock, MagicMock
-
-import pytest
-
-from wayfinder_paths.core.services.local_evm_txn import BASE_CHAIN_ID, LocalEvmTxn
-
-
-class _FakeTxHash:
-    def __init__(self, value: str):
-        self._value = value
-
-    def hex(self) -> str:
-        return self._value
-
-
-@pytest.mark.asyncio
-async def test_base_defaults_to_two_confirmations():
-    txn = LocalEvmTxn(config={})
-
-    fake_web3 = MagicMock()
-    fake_web3.eth = MagicMock()
-    fake_web3.eth.send_raw_transaction = AsyncMock(return_value=_FakeTxHash("0x1"))
-    fake_web3.eth.wait_for_transaction_receipt = AsyncMock(
-        return_value={
-            "status": 1,
-            "blockNumber": 100,
-            "transactionHash": "0x1",
-            "gasUsed": 21_000,
-            "logs": [],
-        }
-    )
-
-    txn.get_web3 = MagicMock(return_value=fake_web3)
-    txn._validate_transaction = MagicMock(side_effect=lambda tx: tx)
-    txn._nonce_transaction = AsyncMock(side_effect=lambda tx, _w3: tx)
-    txn._gas_limit_transaction = AsyncMock(side_effect=lambda tx, _w3: tx)
-    txn._gas_price_transaction = AsyncMock(side_effect=lambda tx, _chain_id, _w3: tx)
-    txn._sign_transaction = MagicMock(return_value=b"signed")
-    txn._close_web3 = AsyncMock()
-    txn._wait_for_confirmations = AsyncMock()
-
-    ok, result = await txn.broadcast_transaction(
-        {
-            "chainId": BASE_CHAIN_ID,
-            "from": "0x0000000000000000000000000000000000000001",
-            "to": "0x0000000000000000000000000000000000000002",
-            "value": 0,
-        },
-        wait_for_receipt=True,
-        timeout=1,
-    )
-
-    assert ok is True
-    txn._wait_for_confirmations.assert_awaited_once_with(fake_web3, 100, 2)
-    assert result["confirmations"] == 2
-    assert result["confirmed_block_number"] == 102
-
-
-@pytest.mark.asyncio
-async def test_non_base_defaults_to_zero_confirmations():
-    txn = LocalEvmTxn(config={})
-
-    fake_web3 = MagicMock()
-    fake_web3.eth = MagicMock()
-    fake_web3.eth.send_raw_transaction = AsyncMock(return_value=_FakeTxHash("0x1"))
-    fake_web3.eth.wait_for_transaction_receipt = AsyncMock(
-        return_value={
-            "status": 1,
-            "blockNumber": 100,
-            "transactionHash": "0x1",
-            "gasUsed": 21_000,
-            "logs": [],
-        }
-    )
-
-    txn.get_web3 = MagicMock(return_value=fake_web3)
-    txn._validate_transaction = MagicMock(side_effect=lambda tx: tx)
-    txn._nonce_transaction = AsyncMock(side_effect=lambda tx, _w3: tx)
-    txn._gas_limit_transaction = AsyncMock(side_effect=lambda tx, _w3: tx)
-    txn._gas_price_transaction = AsyncMock(side_effect=lambda tx, _chain_id, _w3: tx)
-    txn._sign_transaction = MagicMock(return_value=b"signed")
-    txn._close_web3 = AsyncMock()
-    txn._wait_for_confirmations = AsyncMock()
-
-    ok, result = await txn.broadcast_transaction(
-        {
-            "chainId": 1,
-            "from": "0x0000000000000000000000000000000000000001",
-            "to": "0x0000000000000000000000000000000000000002",
-            "value": 0,
-        },
-        wait_for_receipt=True,
-        timeout=1,
-    )
-
-    assert ok is True
-    txn._wait_for_confirmations.assert_not_awaited()
-    assert result["confirmations"] == 0
-    assert result["confirmed_block_number"] == 100
-
-
-@pytest.mark.asyncio
-async def test_explicit_confirmations_override_defaults():
-    txn = LocalEvmTxn(config={})
-
-    fake_web3 = MagicMock()
-    fake_web3.eth = MagicMock()
-    fake_web3.eth.send_raw_transaction = AsyncMock(return_value=_FakeTxHash("0x1"))
-    fake_web3.eth.wait_for_transaction_receipt = AsyncMock(
-        return_value={
-            "status": 1,
-            "blockNumber": 100,
-            "transactionHash": "0x1",
-            "gasUsed": 21_000,
-            "logs": [],
-        }
-    )
-
-    txn.get_web3 = MagicMock(return_value=fake_web3)
-    txn._validate_transaction = MagicMock(side_effect=lambda tx: tx)
-    txn._nonce_transaction = AsyncMock(side_effect=lambda tx, _w3: tx)
-    txn._gas_limit_transaction = AsyncMock(side_effect=lambda tx, _w3: tx)
-    txn._gas_price_transaction = AsyncMock(side_effect=lambda tx, _chain_id, _w3: tx)
-    txn._sign_transaction = MagicMock(return_value=b"signed")
-    txn._close_web3 = AsyncMock()
-    txn._wait_for_confirmations = AsyncMock()
-
-    ok, result = await txn.broadcast_transaction(
-        {
-            "chainId": BASE_CHAIN_ID,
-            "from": "0x0000000000000000000000000000000000000001",
-            "to": "0x0000000000000000000000000000000000000002",
-            "value": 0,
-        },
-        wait_for_receipt=True,
-        timeout=1,
-        confirmations=0,
-    )
-
-    assert ok is True
-    txn._wait_for_confirmations.assert_not_awaited()
-    assert result["confirmations"] == 0
-    assert result["confirmed_block_number"] == 100

wayfinder_paths/templates/adapter/README.md

@@ -1,150 +0,0 @@
-# Adapter Template
-
-Adapters expose protocol-specific capabilities to strategies. They wrap one or more clients from `wayfinder_paths.core.clients`.
-
-## 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. Set `adapter_type` to a unique identifier (e.g., `"MY_PROTOCOL"`).
-4. Implement your public methods.
-5. Add tests in `test_adapter.py`.
-
-## Directory Structure
-
-```
-my_adapter/
-├── adapter.py          # Adapter implementation
-├── examples.json       # Example payloads (optional)
-├── test_adapter.py     # Pytest tests
-└── README.md           # Adapter documentation
-```
-
-## Adapter Structure
-
-```python
-from typing import Any
-
-from wayfinder_paths.core.adapters.BaseAdapter import BaseAdapter
-from wayfinder_paths.core.clients.SomeClient import SomeClient
-
-
-class MyAdapter(BaseAdapter):
-    """Adapter for MyProtocol operations."""
-
-    adapter_type = "MY_PROTOCOL"
-
-    def __init__(self, config: dict[str, Any] | None = None):
-        super().__init__("my_adapter", config)
-        self.client = SomeClient()
-
-    async def connect(self) -> bool:
-        """Optional: Establish connectivity."""
-        return True
-
-    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:
-            result = await self.client.call(param)
-            return (True, result)
-        except Exception as e:
-            self.logger.error(f"Operation failed: {e}")
-            return (False, str(e))
-```
-
-## 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
-
-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:
-
-```bash
-poetry run pytest wayfinder_paths/adapters/my_adapter/ -v
-```
-
-## Best Practices
-
-- 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

@@ -1,16 +0,0 @@
-from typing import Any
-
-from wayfinder_paths.core.adapters.BaseAdapter import BaseAdapter
-
-
-class MyAdapter(BaseAdapter):
-    adapter_type: str = "MY_ADAPTER"
-
-    def __init__(self, config: dict[str, Any] | None = None):
-        super().__init__("my_adapter", config)
-
-    async def connect(self) -> bool:
-        return True
-
-    async def example_operation(self, **kwargs) -> tuple[bool, str]:
-        return (True, "example.op executed")

wayfinder_paths/templates/adapter/examples.json

@@ -1,8 +0,0 @@
-{
-  "connect": {},
-  "example_operation": {
-    "args": {"foo": "bar"}
-  }
-}
-
-

wayfinder_paths/templates/adapter/test_adapter.py

@@ -1,30 +0,0 @@
-import pytest
-
-# TODO: Replace MyAdapter with your actual adapter class name
-from .adapter import MyAdapter
-
-# For mocking clients, uncomment when needed:
-
-
-class TestMyAdapter:
-    @pytest.fixture
-    def adapter(self):
-        return MyAdapter(config={})
-
-    @pytest.mark.asyncio
-    async def test_health_check(self, adapter):
-        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):
-        ok = await adapter.connect()
-        assert isinstance(ok, bool)
-
-    def test_capabilities(self, adapter):
-        assert hasattr(adapter, "adapter_type")
-
-    @pytest.mark.asyncio
-    async def test_basic_functionality(self, adapter):
-        assert adapter is not None

wayfinder_paths/templates/strategy/README.md

@@ -1,186 +0,0 @@
-# Strategy Template
-
-This template provides scaffolding for a new strategy.
-
-## Quick Start
-
-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. Implement the required methods (`deposit`, `update`, `exit`, `_status`).
-4. Add tests in `test_strategy.py`.
-5. Fill out `examples.json` with sample CLI invocations.
-
-## Directory Structure
-
-```
-my_strategy/
-├── strategy.py          # Strategy implementation
-├── examples.json        # Example CLI payloads
-├── test_strategy.py     # Pytest tests
-└── README.md            # Strategy documentation
-```
-
-## Required Methods
-
-```python
-async def deposit(self, main_token_amount: float, gas_token_amount: float) -> StatusTuple:
-    """Move funds from main wallet into strategy wallet and deploy capital."""
-
-async def update(self) -> StatusTuple:
-    """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."""
-```
-
-## Optional Methods
-
-```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."""
-
-async def setup(self) -> None:
-    """Post-construction initialization."""
-
-async def health_check(self) -> dict:
-    """Check strategy and adapter health."""
-```
-
-## Strategy Structure
-
-```python
-from wayfinder_paths.core.strategies.Strategy import StatusDict, StatusTuple, Strategy
-from wayfinder_paths.adapters.balance_adapter.adapter import BalanceAdapter
-
-
-class MyStrategy(Strategy):
-    name = "My Strategy"
-
-    def __init__(self, config: dict | None = None, **kwargs):
-        super().__init__(config, **kwargs)
-        self.config = config or {}
-
-        # 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:
-        if main_token_amount <= 0:
-            return (False, "Nothing to deposit")
-
-        # Implement deposit logic
-        return (True, f"Deposited {main_token_amount} tokens")
-
-    async def update(self) -> StatusTuple:
-        # 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:
-        return {
-            "portfolio_value": 0.0,
-            "net_deposit": 0.0,
-            "strategy_status": {"message": "healthy"},
-            "gas_available": 0.0,
-            "gassed_up": True,
-        }
-```
-
-## Testing
-
-Create `test_strategy.py` using `examples.json`:
-
-```python
-import pytest
-from pathlib import Path
-from tests.test_utils import load_strategy_examples
-from .strategy import MyStrategy
-
-
-@pytest.mark.asyncio
-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
-
-```bash
-# Install dependencies
-poetry install
-
-# 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
-
-# Withdraw
-poetry run python wayfinder_paths/run_strategy.py my_strategy --action withdraw --config config.json
-```
-
-## Best Practices
-
-- 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/examples.json

@@ -1,11 +0,0 @@
-{
-  "deposit": {
-    "main_token_amount": 100,
-    "gas_token_amount": 0.001
-  },
-  "update": {},
-  "status": {},
-  "withdraw": {}
-}
-
-

wayfinder_paths/templates/strategy/strategy.py

@@ -1,35 +0,0 @@
-from wayfinder_paths.core.strategies.Strategy import StatusDict, StatusTuple, Strategy
-
-
-class MyStrategy(Strategy):
-    name = "My Strategy"
-    description = "Short description of what the strategy does."
-    summary = "One-line summary for discovery."
-
-    def __init__(self):
-        super().__init__()
-
-    async def setup(self):
-        return None
-
-    async def deposit(
-        self, main_token_amount: float, gas_token_amount: float
-    ) -> StatusTuple:
-        return (True, "Deposit successful")
-
-    async def withdraw(self, amount: float | None = None) -> StatusTuple:
-        return await super().withdraw(amount=amount)
-
-    async def update(self) -> StatusTuple:
-        return (True, "Update successful")
-
-    async def _status(self) -> StatusDict:
-        return {
-            "portfolio_value": 0.0,
-            "net_deposit": 0.0,
-            "strategy_status": {},
-        }
-
-    @staticmethod
-    def policies() -> list[str]:
-        return []