wayfinder-paths 0.1.7__py3-none-any.whl

wayfinder_paths/strategies/hyperlend_stable_yield_strategy/test_strategy.py

@@ -0,0 +1,352 @@
+import sys
+from pathlib import Path
+from unittest.mock import AsyncMock
+
+# 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.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
+
+from wayfinder_paths.strategies.hyperlend_stable_yield_strategy.strategy import (  # noqa: E402
+    HyperlendStableYieldStrategy,
+)
+
+
+@pytest.fixture
+def strategy():
+    """Create a strategy instance for testing with minimal config."""
+    mock_config = {
+        "main_wallet": {"address": "0x1234567890123456789012345678901234567890"},
+        "strategy_wallet": {"address": "0xabcdefabcdefabcdefabcdefabcdefabcdefabcd"},
+    }
+
+    s = HyperlendStableYieldStrategy(
+        config=mock_config,
+        main_wallet=mock_config["main_wallet"],
+        strategy_wallet=mock_config["strategy_wallet"],
+        simulation=True,
+    )
+
+    if hasattr(s, "balance_adapter") and s.balance_adapter:
+        # Mock balances: 1000 USDT0 (with 6 decimals) and 2 HYPE (with 18 decimals)
+        usdt0_balance_mock = AsyncMock(return_value=(True, 1000000000))
+        hype_balance_mock = AsyncMock(return_value=(True, 2000000000000000000))
+
+        def get_balance_side_effect(token_id, wallet_address, **kwargs):
+            if token_id == "usdt0-hyperevm" or token_id == "usdt0":
+                return usdt0_balance_mock.return_value
+            elif token_id == "hype-hyperevm" or token_id == "hype":
+                return hype_balance_mock.return_value
+            return (True, 1000000000)
+
+        s.balance_adapter.get_balance = AsyncMock(side_effect=get_balance_side_effect)
+
+    if hasattr(s, "token_adapter") and s.token_adapter:
+        default_usdt0 = {
+            "id": "usdt0-hyperevm",
+            "token_id": "usdt0-hyperevm",
+            "symbol": "USDT0",
+            "name": "USD Tether Zero",
+            "decimals": 6,
+            "address": "0x1234567890123456789012345678901234567890",
+            "chain": {"code": "hyperevm", "id": 9999, "name": "HyperEVM"},
+        }
+
+        default_hype = {
+            "id": "hype-hyperevm",
+            "token_id": "hype-hyperevm",
+            "symbol": "HYPE",
+            "name": "HyperEVM Gas Token",
+            "decimals": 18,
+            "address": "0xabcdefabcdefabcdefabcdefabcdefabcdefabcd",
+            "chain": {"code": "hyperevm", "id": 9999, "name": "HyperEVM"},
+        }
+
+        def get_token_side_effect(address=None, token_id=None, **kwargs):
+            if token_id == "usdt0-hyperevm" or token_id == "usdt0":
+                return (True, default_usdt0)
+            elif token_id == "hype-hyperevm" or token_id == "hype":
+                return (True, default_hype)
+            return (True, default_usdt0)
+
+        s.token_adapter.get_token = AsyncMock(side_effect=get_token_side_effect)
+        s.token_adapter.get_token = AsyncMock(side_effect=get_token_side_effect)
+        s.token_adapter.get_gas_token = AsyncMock(
+            return_value=(
+                True,
+                default_hype,
+            )
+        )
+
+    if hasattr(s, "balance_adapter") and s.balance_adapter:
+        s.balance_adapter.move_from_main_wallet_to_strategy_wallet = AsyncMock(
+            return_value=(True, "Transfer successful (simulated)")
+        )
+        s.balance_adapter.move_from_strategy_wallet_to_main_wallet = AsyncMock(
+            return_value=(True, "Transfer successful (simulated)")
+        )
+        if hasattr(s.balance_adapter, "wallet_provider"):
+            s.balance_adapter.wallet_provider.broadcast_transaction = AsyncMock(
+                return_value=(True, {"transaction_hash": "0xCAFEBABE"})
+            )
+
+    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": []})
+        )
+
+    if hasattr(s, "brap_adapter") and s.brap_adapter:
+        usdt0_address = "0x1234567890123456789012345678901234567890"
+
+        def get_swap_quote_side_effect(*args, **kwargs):
+            to_token_address = kwargs.get("to_token_address", "")
+            if to_token_address == usdt0_address:
+                return (
+                    True,
+                    {
+                        "quotes": {
+                            "best_quote": {
+                                "output_amount": "99900000",
+                            }
+                        }
+                    },
+                )
+            return (
+                True,
+                {
+                    "quotes": {
+                        "best_quote": {
+                            "output_amount": "105000000",
+                            "input_amount": "50000000000000",
+                            "toAmount": "105000000",
+                            "estimatedGas": "1000000000",
+                            "fromAmount": "100000000",
+                            "fromToken": {"symbol": "USDT0"},
+                            "toToken": {"symbol": "HYPE"},
+                        }
+                    }
+                },
+            )
+
+        s.brap_adapter.get_swap_quote = AsyncMock(
+            side_effect=get_swap_quote_side_effect
+        )
+
+    if (
+        hasattr(s, "brap_adapter")
+        and s.brap_adapter
+        and hasattr(s.brap_adapter, "swap_from_quote")
+    ):
+        s.brap_adapter.swap_from_quote = AsyncMock(return_value=None)
+    if hasattr(s, "brap_adapter") and hasattr(s.brap_adapter, "wallet_provider"):
+        s.brap_adapter.wallet_provider.broadcast_transaction = AsyncMock(
+            return_value=(True, {"transaction_hash": "0xF00D"})
+        )
+
+    if hasattr(s, "hyperlend_adapter") and s.hyperlend_adapter:
+        s.hyperlend_adapter.get_assets_view = AsyncMock(
+            return_value=(True, {"assets_view": {"assets": []}})
+        )
+        s.hyperlend_adapter.get_stable_markets = AsyncMock(
+            return_value=(
+                True,
+                {
+                    "markets": {
+                        "0x1234567890123456789012345678901234567890": {
+                            "symbol": "USDT0",
+                            "address": "0x1234567890123456789012345678901234567890",
+                            "apy": 5.0,
+                            "tvl": 1000000,
+                            "underlying_token": {
+                                "address": "0x1234567890123456789012345678901234567890",
+                                "symbol": "USDT0",
+                                "decimals": 6,
+                            },
+                        }
+                    },
+                    "notes": [],
+                },
+            )
+        )
+        s.hyperlend_adapter.get_lend_rate_history = AsyncMock(
+            return_value=(
+                True,
+                {
+                    "rates": [{"rate": 5.0, "timestamp": 1700000000}],
+                    "avg_rate": 5.0,
+                },
+            )
+        )
+
+    s.usdt_token_info = {
+        "id": "usdt0-hyperevm",
+        "symbol": "USDT0",
+        "name": "USD Tether Zero",
+        "decimals": 6,
+        "address": "0x1234567890123456789012345678901234567890",
+        "chain": {"code": "hyperevm", "id": 9999, "name": "HyperEVM"},
+    }
+    s.hype_token_info = {
+        "id": "hype-hyperevm",
+        "symbol": "HYPE",
+        "name": "HyperEVM Gas Token",
+        "decimals": 18,
+        "address": "0xabcdefabcdefabcdefabcdefabcdefabcdefabcd",
+        "chain": {"code": "hyperevm", "id": 9999, "name": "HyperEVM"},
+    }
+    s.current_token = None
+
+    if hasattr(s, "token_adapter") and s.token_adapter:
+        if not hasattr(s.token_adapter, "get_token_price"):
+            s.token_adapter.get_token_price = AsyncMock()
+
+        def get_token_price_side_effect(token_id):
+            if token_id == "hype-hyperevm":
+                return (True, {"current_price": 2000.0})
+            else:
+                return (True, {"current_price": 1.0})
+
+        s.token_adapter.get_token_price = AsyncMock(
+            side_effect=get_token_price_side_effect
+        )
+
+    async def mock_sweep_wallet(target_token):
+        pass
+
+    async def mock_refresh_current_pool_balance():
+        pass
+
+    async def mock_rebalance_gas(target_pool):
+        return (True, "Gas rebalanced")
+
+    async def mock_has_idle_assets(balances, target):
+        return True
+
+    if hasattr(s, "_sweep_wallet"):
+        s._sweep_wallet = mock_sweep_wallet
+    if hasattr(s, "_refresh_current_pool_balance"):
+        s._refresh_current_pool_balance = mock_refresh_current_pool_balance
+    if hasattr(s, "_rebalance_gas"):
+        s._rebalance_gas = mock_rebalance_gas
+    if hasattr(s, "_has_idle_assets"):
+        s._has_idle_assets = mock_has_idle_assets
+
+    s.current_symbol = getattr(s, "current_symbol", None) or "USDT0"
+    if not getattr(s, "current_token", None):
+        s.current_token = s.usdt_token_info
+    s.current_avg_apy = getattr(s, "current_avg_apy", 0.0)
+
+    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"]
+
+    await strategy.setup()
+
+    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)
+
+    result = await strategy.update(**smoke_data.get("update", {}))
+    # update() returns (ok, msg, should_notify) or (ok, msg)
+    ok = result[0]
+    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:
+            result = await strategy.update()
+            ok = result[0]
+            msg = result[1] if len(result) > 1 else ""
+            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/strategies/stablecoin_yield_strategy/README.md

@@ -0,0 +1,96 @@
+# Stablecoin Yield Strategy
+
+- Entrypoint: `strategies.stablecoin_yield_strategy.strategy.StablecoinYieldStrategy`
+- Manifest: `manifest.yaml`
+- Examples: `examples.json`
+- Tests: `test_strategy.py`
+
+## What it does
+
+Actively manages Base USDC deposits. Deposits pull USDC (plus an ETH gas buffer) from the main wallet into the strategy wallet, then the strategy searches Base-native pools for the best USD-denominated APY. Updates monitor DeFi Llama feeds and Wayfinder pool analytics, respecting a rotation cooldown and minimum APY improvement before rebalancing via the BRAP router. Withdrawals unwind the current position, sweep residual tokens back into USDC, and return funds to the main wallet.
+
+## On-chain policy
+
+Transactions are scoped to the strategy wallet and Enso Router approval/swap calls:
+
+```
+(wallet.id == 'FORMAT_WALLET_ID') && ((eth.tx.data[0..10] == '0x095ea7b3' && eth.tx.data[34..74] == 'f75584ef6673ad213a685a1b58cc0330b8ea22cf') || (eth.tx.to == '0xF75584eF6673aD213a685a1B58Cc0330B8eA22Cf'))
+```
+
+## Key parameters (from `strategy.py`)
+
+- `MIN_AMOUNT_USDC = 2` → deposits smaller than 2 USDC are rejected.
+- `MIN_TVL = 1_000_000` → pools below $1M TVL are ignored.
+- `ROTATION_MIN_INTERVAL = 14 days` → once rotated, the strategy waits ~2 weeks unless the new candidate dramatically outperforms.
+- `DUST_APY = 0.01` (1%) → pools below this APY are treated as dust.
+- `SEARCH_DEPTH = 10` → how many pools to examine when selecting candidates.
+- `MIN_GAS = 0.001` and `GAS_MAXIMUM = 0.02` Base ETH → minimum buffer required in the strategy wallet plus the upper bound accepted per deposit.
+
+## Adapters used
+
+- `BalanceAdapter` for wallet/pool balances and orchestrating transfers between the main and strategy wallets (with ledger recording).
+- `PoolAdapter` for pool metadata, llama reports, and yield analytics.
+- `BRAPAdapter` to source swap quotes and execute rotations.
+- `TokenAdapter` for metadata (gas token, USDC info).
+- `LedgerAdapter` for net-deposit tracking and cooldown enforcement.
+- `LocalTokenTxnService` (via `DefaultWeb3Service`) for lower-level sends/approvals used by adapters.
+
+## Actions
+
+### Deposit
+
+- Validates `main_token_amount` ≥ `MIN_AMOUNT_USDC` and `gas_token_amount` ≤ `GAS_MAXIMUM`.
+- Confirms the main wallet holds enough USDC and Base ETH.
+- Moves Base ETH into the strategy wallet (when requested or when the strategy needs a top-up), then transfers the requested USDC amount via `BalanceAdapter.move_from_main_wallet_to_strategy_wallet`.
+- Hydrates the on-chain position snapshot so future updates know which pool is active.
+
+### Update
+
+- Fetches the latest strategy balances, idle assets, and current target pool.
+- Runs `_find_best_pool()` which uses `PoolAdapter` and DeFi Llama data to score up to `SEARCH_DEPTH` pools that satisfy the APY/TVL filters.
+- Checks `LedgerAdapter.get_strategy_latest_transactions()` to enforce the rotation cooldown, unless the new candidate clears the APY-improvement threshold.
+- If rotation is approved, requests a BRAP quote, ensures the strategy has enough gas, executes the swap via `BRAPAdapter.swap_from_quote`, and sweeps any idle balances back into the target token.
+- Records informative status messages when no better pool exists or when cooldown blocks a move.
+
+### Status
+
+`_status()` reports:
+
+- `portfolio_value`: refreshed pool balance (in base units) converted to float.
+- `net_deposit`: data pulled from `LedgerAdapter.get_strategy_net_deposit`.
+- `strategy_status`: dictionary exposing the active pool, APY estimates, and wallet balances.
+
+### Withdraw
+
+- Requires a prior deposit (the strategy tracks `self.DEPOSIT_USDC`).
+- Reads the pool balance via `BalanceAdapter.get_pool_balance`, unwinds via BRAP swaps back to USDC, and moves USDC from the strategy wallet to the main wallet via `BalanceAdapter.move_from_strategy_wallet_to_main_wallet`.
+- Updates the ledger and clears cached pool state.
+
+## Running locally
+
+```bash
+# Install dependencies
+poetry install
+
+# Generate main wallet (writes wallets.json)
+# 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 the example config and set credentials if needed
+cp wayfinder_paths/config.example.json config.json
+
+# Smoke test the strategy
+poetry run python wayfinder_paths/run_strategy.py stablecoin_yield_strategy --action status --config $(pwd)/config.json
+
+# Perform a funded deposit/update cycle
+poetry run python wayfinder_paths/run_strategy.py stablecoin_yield_strategy --action deposit --main-token-amount 60 --gas-token-amount 0.001 --config $(pwd)/config.json
+poetry run python wayfinder_paths/run_strategy.py stablecoin_yield_strategy --action update --config $(pwd)/config.json
+```
+
+You can also load the manifest explicitly:
+
+```bash
+poetry run python wayfinder_paths/run_strategy.py --manifest wayfinder_paths/strategies/stablecoin_yield_strategy/manifest.yaml --action status --config $(pwd)/config.json
+```
+
+Wallet addresses are auto-populated from `wallets.json` when you run `wayfinder_paths/scripts/make_wallets.py`. Set `NETWORK=testnet` in `config.json` to dry-run operations against mocked services.

wayfinder_paths/strategies/stablecoin_yield_strategy/examples.json

@@ -0,0 +1,17 @@
+{
+  "smoke": {
+    "deposit": {"main_token_amount": 60, "gas_token_amount": 0.001},
+    "update": {},
+    "status": {},
+    "withdraw": {}
+  },
+  "min_deposit_fail": {
+    "deposit": {"main_token_amount": 1, "gas_token_amount": 0.0},
+    "expect": {"success": false, "message_contains": "Minimum deposit"}
+  },
+  "tvl_filter": {
+    "deposit": {"main_token_amount": 100, "gas_token_amount": 0.001},
+    "update": {}
+  }
+}
+

wayfinder_paths/strategies/stablecoin_yield_strategy/manifest.yaml

@@ -0,0 +1,17 @@
+schema_version: "0.1"
+entrypoint: "strategies.stablecoin_yield_strategy.strategy.StablecoinYieldStrategy"
+permissions:
+  policy: "(wallet.id == 'FORMAT_WALLET_ID') && ((eth.tx.data[0..10] == '0x095ea7b3' && eth.tx.data[34..74] == 'f75584ef6673ad213a685a1b58cc0330b8ea22cf') || (eth.tx.to == '0xF75584eF6673aD213a685a1B58Cc0330B8eA22Cf'))"
+adapters:
+  - name: "BALANCE"
+    capabilities: ["wallet_read", "wallet_transfer"]
+  - name: "POOL"
+    capabilities: ["pool.read", "pool.analytics"]
+  - name: "BRAP"
+    capabilities: ["swap.quote", "swap.execute"]
+  - name: "TOKEN"
+    capabilities: ["token.read"]
+  - name: "LEDGER"
+    capabilities: ["ledger.read", "strategy.transactions"]
+  - name: "EVM_TRANSACTION"
+    capabilities: ["wallet_transfer"]