wayfinder-paths 0.1.1__py3-none-any.whl

wayfinder_paths/vaults/templates/strategy/README.md

@@ -0,0 +1,152 @@
+# Strategy Template
+
+This template provides the scaffolding for a new vault strategy. It mirrors the structure in `wayfinder_paths/vaults/strategies/...` and wires into the runner via a manifest.
+
+## Quick Start
+
+1. Copy the template to a new folder:
+   ```
+   cp -r wayfinder_paths/vaults/templates/strategy wayfinder_paths/vaults/strategies/my_strategy
+   ```
+2. Rename the class in `strategy.py` and update `manifest.yaml` so `entrypoint` points to your new module (for example `vaults.strategies.my_strategy.strategy.MyStrategy`).
+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`).
+
+## Layout
+
+```
+my_strategy/
+├── strategy.py          # Strategy implementation
+├── manifest.yaml        # Entrypoint + adapter requirements + policy
+├── examples.json        # Example CLI payloads
+├── test_strategy.py     # Pytest-based smoke tests
+└── README.md            # Strategy-specific documentation
+```
+
+## Required methods
+
+```python
+async def deposit(self, main_token_amount: float, gas_token_amount: float) -> StatusTuple:
+    """Move funds from the main wallet into the vault wallet and prepare on-chain positions."""
+
+async def update(self) -> StatusTuple:
+    """Periodic rebalance/update loop."""
+
+async def _status(self) -> StatusDict:
+    """Return portfolio_value, net_deposit, and strategy_status payloads."""
+```
+
+`Strategy.withdraw` already unwinds ledger operations. Override it only if you need custom exit logic.
+
+## Wiring adapters
+
+Strategies typically:
+
+1. Build a `DefaultWeb3Service` so every adapter shares a wallet provider.
+2. Instantiate adapters (balance, ledger, protocol specific, etc.).
+3. Register adapters via `self.register_adapters([...])` and keep references as attributes.
+
+```python
+from wayfinder_paths.core.services.web3_service import DefaultWeb3Service
+from wayfinder_paths.core.strategies.Strategy import StatusDict, StatusTuple, Strategy
+from wayfinder_paths.vaults.adapters.balance_adapter.adapter import BalanceAdapter
+
+
+class MyStrategy(Strategy):
+    name = "Demo Strategy"
+
+    def __init__(self, config: dict | None = None):
+        super().__init__()
+        self.config = config or {}
+        web3_service = DefaultWeb3Service(self.config)
+        balance_adapter = BalanceAdapter(self.config, web3_service=web3_service)
+        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(
+            token_id=self.config.get("token_id"),
+            wallet_address=self.config.get("main_wallet", {}).get("address"),
+        )
+        if not success:
+            return (False, "Unable to fetch balances")
+
+        # Use BalanceAdapter (which leverages LocalTokenTxnService builders) for transfers.
+        self.last_deposit = main_token_amount
+        return (True, f"Deposited {main_token_amount} tokens")
+
+    async def update(self) -> StatusTuple:
+        """Execute your strategy logic periodically."""
+        return (True, "No-op update")
+
+    async def _status(self) -> StatusDict:
+        """Surface state back to run_strategy.py."""
+        success, balance = await self.balance_adapter.get_balance(
+            token_id=self.config.get("token_id"),
+            wallet_address=self.config.get("vault_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"},
+        }
+```
+
+## Manifest configuration
+
+Your `manifest.yaml` should define:
+
+```yaml
+schema_version: "0.1"
+entrypoint: "vaults.strategies.my_strategy.strategy.MyStrategy"
+permissions:
+  policy: "(wallet.id == 'FORMAT_WALLET_ID') && (eth.tx.to == '0x...')"
+adapters:
+  - name: "BALANCE"
+    capabilities: ["wallet_read", "wallet_transfer"]
+  - name: "POOL"
+    capabilities: ["pool.read", "pool.analytics"]
+```
+
+## Testing
+
+`test_strategy.py` should cover at least deposit/update/status. Use `pytest.mark.asyncio` and patch adapters or services as needed.
+
+```python
+import pytest
+from wayfinder_paths.vaults.strategies.my_strategy.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"}
+```
+
+## Running the strategy locally
+
+```bash
+# Install dependencies & create wallets first
+poetry install
+poetry run python wayfinder_paths/scripts/make_wallets.py --default --vault
+
+# Copy config and edit credentials
+cp wayfinder_paths/config.example.json config.json
+
+# Run your strategy
+poetry run python wayfinder_paths/run_strategy.py my_strategy --action status --config $(pwd)/config.json
+```
+
+## Best practices
+
+- Return `(success: bool, message: str)` tuples from `deposit`/`update`.
+- Always populate `portfolio_value`, `net_deposit`, and `strategy_status` keys in `_status`.
+- Use the adapters declared in `manifest.yaml`—they are injected via `register_adapters`.
+- Keep on-chain permissions tight by scoping the manifest policy to the strategy wallet and expected contracts.

wayfinder_paths/vaults/templates/strategy/examples.json

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

wayfinder_paths/vaults/templates/strategy/manifest.yaml

@@ -0,0 +1,8 @@
+schema_version: "0.1"
+entrypoint: "vaults.strategies.my_strategy.strategy.MyStrategy"
+name: "my_strategy"  # Unique name for this strategy instance (used for wallet lookup)
+permissions:
+  policy: "(wallet.id == 'FORMAT_WALLET_ID')"
+adapters:
+  - name: "BALANCE"
+    capabilities: ["wallet_read"]

wayfinder_paths/vaults/templates/strategy/strategy.py

@@ -0,0 +1,57 @@
+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):
+        """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,
+            "strategy_status": {},
+        }
+
+    @staticmethod
+    def policies() -> list[str]:
+        """Return policy strings used to scope on-chain permissions."""
+        return []

wayfinder_paths/vaults/templates/strategy/test_strategy.py

@@ -0,0 +1,197 @@
+"""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 vaults/strategies/your_strategy/ -v
+"""
+
+import sys
+from pathlib import Path
+
+# TODO: Replace MyStrategy with your actual strategy class name
+from wayfinder_paths.vaults.strategies.your_strategy.strategy import (
+    MyStrategy,  # noqa: E402
+)
+
+# Ensure wayfinder-paths is on path for tests.test_utils import
+# This is a workaround until conftest loading order is resolved
+_wayfinder_path_dir = Path(__file__).parent.parent.parent.parent.resolve()
+_wayfinder_path_str = str(_wayfinder_path_dir)
+if _wayfinder_path_str not in sys.path:
+    sys.path.insert(0, _wayfinder_path_str)
+elif sys.path.index(_wayfinder_path_str) > 0:
+    # Move to front to take precedence
+    sys.path.remove(_wayfinder_path_str)
+    sys.path.insert(0, _wayfinder_path_str)
+
+import pytest  # noqa: E402
+
+# Import test utilities
+try:
+    from tests.test_utils import get_canonical_examples, load_strategy_examples
+except ImportError:
+    # Fallback if path setup didn't work
+    import importlib.util
+
+    test_utils_path = Path(_wayfinder_path_dir) / "tests" / "test_utils.py"
+    spec = importlib.util.spec_from_file_location("tests.test_utils", test_utils_path)
+    test_utils = importlib.util.module_from_spec(spec)
+    spec.loader.exec_module(test_utils)
+    get_canonical_examples = test_utils.get_canonical_examples
+    load_strategy_examples = test_utils.load_strategy_examples
+
+
+@pytest.fixture
+def strategy():
+    """Create a strategy instance for testing with minimal config."""
+    mock_config = {
+        "main_wallet": {"address": "0x1234567890123456789012345678901234567890"},
+        "vault_wallet": {"address": "0xabcdefabcdefabcdefabcdefabcdefabcdefabcd"},
+    }
+
+    s = MyStrategy(
+        config=mock_config,
+        main_wallet=mock_config["main_wallet"],
+        vault_wallet=mock_config["vault_wallet"],
+        simulation=True,
+    )
+
+    # TODO: Add mocking for your adapters here if needed
+    # Example for balance_adapter:
+    # if hasattr(s, "balance_adapter") and s.balance_adapter:
+    #     usdc_balance_mock = AsyncMock(return_value=(True, 60000000))
+    #     gas_balance_mock = AsyncMock(return_value=(True, 2000000000000000))
+    #
+    #     def get_balance_side_effect(token_id, wallet_address, **kwargs):
+    #         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_token_balance_for_wallet = AsyncMock(
+    #         side_effect=get_balance_side_effect
+    #     )
+    #     s.balance_adapter.get_all_enriched_token_balances_for_wallet = AsyncMock(
+    #         return_value=(True, {"balances": []})
+    #     )
+
+    # Example for token_adapter:
+    # if hasattr(s, "token_adapter") and s.token_adapter:
+    #     default_token = {
+    #         "id": "usd-coin-base",
+    #         "symbol": "USDC",
+    #         "name": "USD Coin",
+    #         "decimals": 6,
+    #         "address": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913",
+    #         "chain": {"code": "base", "id": 8453, "name": "Base"},
+    #     }
+    #     s.token_adapter.get_token = AsyncMock(return_value=(True, default_token))
+    #     s.token_adapter.get_gas_token = AsyncMock(return_value=(True, default_token))
+
+    # Example for transaction adapters:
+    # if hasattr(s, "tx_adapter") and s.tx_adapter:
+    #     s.tx_adapter.move_from_main_wallet_to_vault_wallet = AsyncMock(
+    #         return_value=(True, "Transfer successful (simulated)")
+    #     )
+    #     s.tx_adapter.move_from_vault_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_vault_net_deposit = AsyncMock(
+    #         return_value=(True, {"net_deposit": 0})
+    #     )
+    #     s.ledger_adapter.get_vault_transactions = AsyncMock(
+    #         return_value=(True, {"transactions": []})
+    #     )
+
+    return s
+
+
+@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"]
+
+    st = await strategy.status()
+    assert isinstance(st, dict)
+    assert "portfolio_value" in st or "net_deposit" in st or "strategy_status" in st
+
+    deposit_params = smoke_data.get("deposit", {})
+    ok, msg = await strategy.deposit(**deposit_params)
+    assert isinstance(ok, bool)
+    assert isinstance(msg, str)
+
+    ok, msg = await strategy.update(**smoke_data.get("update", {}))
+    assert isinstance(ok, bool)
+
+    ok, msg = await strategy.withdraw(**smoke_data.get("withdraw", {}))
+    assert isinstance(ok, bool)
+
+
+@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)
+
+    for example_name, example_data in canonical.items():
+        if "deposit" in example_data:
+            deposit_params = example_data.get("deposit", {})
+            ok, _ = await strategy.deposit(**deposit_params)
+            assert ok, f"Canonical example '{example_name}' deposit failed"
+
+        if "update" in example_data:
+            ok, msg = await strategy.update()
+            assert ok, f"Canonical example '{example_name}' update failed: {msg}"
+
+        if "status" in example_data:
+            st = await strategy.status()
+            assert isinstance(st, dict), (
+                f"Canonical example '{example_name}' status failed"
+            )
+
+
+@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():
+        if isinstance(example_data, dict) and "expect" in example_data:
+            expect = example_data.get("expect", {})
+
+            if "deposit" in example_data:
+                deposit_params = example_data.get("deposit", {})
+                ok, _ = await strategy.deposit(**deposit_params)
+
+                if expect.get("success") is False:
+                    assert ok is False, (
+                        f"Expected {example_name} deposit to fail but it succeeded"
+                    )
+                elif expect.get("success") is True:
+                    assert ok is True, (
+                        f"Expected {example_name} deposit to succeed but it failed"
+                    )
+
+            if "update" in example_data:
+                ok, _ = await strategy.update()
+                if "success" in expect:
+                    expected_success = expect.get("success")
+                    assert ok == expected_success, (
+                        f"Expected {example_name} update to "
+                        f"{'succeed' if expected_success else 'fail'} but got opposite"
+                    )

wayfinder_paths-0.1.1.dist-info/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 Wayfinder
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.