wayfinder-paths 0.1.1__py3-none-any.whl

wayfinder_paths/vaults/adapters/token_adapter/README.md

@@ -0,0 +1,101 @@
+# Token Adapter
+
+A Wayfinder adapter that wraps the `_get_token_via_api` method for fetching token data via HeadlessAPIViewSet endpoints. This adapter supports both address and token_id lookups.
+
+## Capabilities
+
+- `token.read`: Retrieve token information by address or token ID
+
+## Configuration
+
+The adapter uses the TokenClient which automatically handles authentication and API configuration through the Wayfinder settings. No additional configuration is required.
+
+The TokenClient will automatically:
+- Use the WAYFINDER_API_URL from settings
+- Handle authentication via environment variables or config.json
+- Manage token refresh and retry logic
+
+## Usage
+
+### Initialize the Adapter
+
+```python
+from wayfinder_paths.vaults.adapters.token_adapter.adapter import TokenAdapter
+
+# No configuration needed - uses TokenClient with automatic settings
+adapter = TokenAdapter()
+```
+
+### Get Token Metadata
+
+Both contract addresses and token ids are supported with the same method. Pass whichever identifier you have:
+
+```python
+success, data = await adapter.get_token("0x1234...")        # by address
+# or
+success, data = await adapter.get_token("usd-coin-base")    # by token id
+
+if success:
+    print(data)
+else:
+    print(f"Error: {data}")
+```
+
+### Get Token Price
+
+```python
+success, data = await adapter.get_token_price("token-123")
+if success:
+    print(f"Price: ${data['current_price']}")
+    print(f"24h Change: {data['price_change_percentage_24h']}%")
+else:
+    print(f"Error: {data}")
+```
+
+### Get Gas Token
+
+```python
+success, data = await adapter.get_gas_token("base")
+if success:
+    print(f"Gas token: {data['symbol']} - {data['name']}")
+    print(f"Address: {data['address']}")
+else:
+    print(f"Error: {data}")
+```
+
+### Get Token (Flexible)
+
+```python
+# Try by address first, then by token_id
+success, data = await adapter.get_token(address="0x1234...", token_id="token-123")
+if success:
+    print(f"Token data: {data}")
+else:
+    print(f"Error: {data}")
+```
+
+## API Endpoints
+
+The adapter uses the following existing public API endpoints:
+
+1. **Token Details** (by address): `GET /public/tokens/detail/?query={address}&get_chart=false`
+2. **Token by ID**: `GET /public/tokens/lookup/?token_id={token_id}`
+
+## Error Handling
+
+All methods return a tuple of `(success: bool, data: Any)` where:
+- `success` indicates whether the operation was successful
+- `data` contains either the token information (on success) or an error message (on failure)
+
+## Health Check
+
+The adapter includes a health check that tests connectivity to the API:
+
+```python
+health = await adapter.health_check()
+print(f"Status: {health['status']}")
+```
+
+## Examples
+
+See `examples.json` for more detailed usage examples.

wayfinder_paths/vaults/adapters/token_adapter/__init__.py

@@ -0,0 +1,3 @@
+from .adapter import TokenAdapter
+
+__all__ = ["TokenAdapter"]

wayfinder_paths/vaults/adapters/token_adapter/adapter.py

@@ -0,0 +1,92 @@
+from typing import Any
+
+from wayfinder_paths.core.adapters.BaseAdapter import BaseAdapter
+from wayfinder_paths.core.clients.TokenClient import TokenClient
+
+
+class TokenAdapter(BaseAdapter):
+    """
+    Token adapter that wraps the _get_token_via_api method for fetching token data
+    via HeadlessAPIViewSet endpoints. Supports both address and token_id lookups.
+    """
+
+    adapter_type: str = "TOKEN"
+
+    def __init__(
+        self,
+        config: dict[str, Any] | None = None,
+        token_client: TokenClient | None = None,
+    ):
+        super().__init__("token_adapter", config)
+        self.token_client = token_client or TokenClient()
+
+    async def get_token(self, query: str) -> tuple[bool, Any]:
+        """
+        Get token data by address using the token-details endpoint.
+
+        Args:
+            address: Token contract address
+
+        Returns:
+            Tuple of (success, data) where data is the token information or error message
+        """
+        try:
+            data = await self.token_client.get_token_details(query)
+            if not data:
+                return (False, f"No token found for: {query}")
+            return (True, data)
+        except Exception as e:
+            self.logger.error(f"Error getting token by query {query}: {e}")
+            return (False, str(e))
+
+    async def get_token_price(self, token_id: str) -> tuple[bool, Any]:
+        """
+        Get token price by token ID or address using the token-details endpoint.
+
+        Args:
+            token_id: Token identifier or address
+
+        Returns:
+            Tuple of (success, data) where data is the price information or error message
+        """
+        try:
+            data = await self.token_client.get_token_details(token_id)
+            if not data:
+                return (False, f"No token found for: {token_id}")
+
+            # Extract just the price information
+            price_data = {
+                "current_price": data.get("current_price", 0.0),
+                "price_change_24h": data.get("price_change_24h", 0.0),
+                "price_change_percentage_24h": data.get(
+                    "price_change_percentage_24h", 0.0
+                ),
+                "market_cap": data.get("market_cap", 0),
+                "total_volume": data.get("total_volume", 0),
+                "symbol": data.get("symbol", ""),
+                "name": data.get("name", ""),
+                "address": data.get("address", ""),
+            }
+            return (True, price_data)
+        except Exception as e:
+            self.logger.error(f"Error getting token price for {token_id}: {e}")
+            return (False, str(e))
+
+    async def get_gas_token(self, chain_code: str) -> tuple[bool, Any]:
+        """
+        Get gas token for a given chain code.
+
+        Args:
+            chain_code: Chain code (e.g., "base", "ethereum")
+
+        Returns:
+            Tuple of (success, data) where data is the gas token information or error message
+        """
+        try:
+            data = await self.token_client.get_gas_token(chain_code)
+            if not data:
+                return (False, f"No gas token found for chain: {chain_code}")
+            return (True, data)
+        except Exception as e:
+            self.logger.error(f"Error getting gas token for chain {chain_code}: {e}")
+            return (False, str(e))

wayfinder_paths/vaults/adapters/token_adapter/examples.json

@@ -0,0 +1,26 @@
+{
+  "basic_usage": {
+    "description": "Basic usage of TokenAdapter to get token information",
+    "code": "from vaults.adapters.token_adapter.adapter import TokenAdapter\n\n# Initialize adapter (no config needed)\nadapter = TokenAdapter()\n\n# Get token by address\nsuccess, data = await adapter.get_token_by_address(\"0x1234567890abcdef1234567890abcdef12345678\")\nif success:\n    print(f\"Token symbol: {data.get('symbol')}\")\n    print(f\"Token name: {data.get('name')}\")\n    print(f\"Decimals: {data.get('decimals')}\")\nelse:\n    print(f\"Error: {data}\")"
+  },
+  "get_by_token_id": {
+    "description": "Get token information using token ID",
+    "code": "from vaults.adapters.token_adapter.adapter import TokenAdapter\n\n# Initialize adapter (no config needed)\nadapter = TokenAdapter()\n\n# Get token by ID\nsuccess, data = await adapter.get_token_by_id(\"token-12345\")\nif success:\n    print(f\"Token data: {data}\")\nelse:\n    print(f\"Error: {data}\")"
+  },
+  "flexible_lookup": {
+    "description": "Use flexible get_token method that tries both address and token_id",
+    "code": "from vaults.adapters.token_adapter.adapter import TokenAdapter\n\n# Initialize adapter (no config needed)\nadapter = TokenAdapter()\n\n# Try both address and token_id\nsuccess, data = await adapter.get_token(\n    address=\"0x1234567890abcdef1234567890abcdef12345678\",\n    token_id=\"token-12345\"\n)\nif success:\n    print(f\"Found token: {data}\")\nelse:\n    print(f\"Token not found: {data}\")"
+  },
+  "error_handling": {
+    "description": "Proper error handling for various scenarios",
+    "code": "from vaults.adapters.token_adapter.adapter import TokenAdapter\n\n# Initialize adapter (no config needed)\nadapter = TokenAdapter()\n\n# Handle missing parameters\ntry:\n    success, data = await adapter.get_token()\n    if not success:\n        print(f\"Error: {data}\")\nexcept Exception as e:\n    print(f\"Unexpected error: {e}\")\n\n# Handle API errors\nsuccess, data = await adapter.get_token_by_address(\"invalid-address\")\nif not success:\n    print(f\"API error: {data}\")\nelse:\n    print(f\"Token found: {data}\")"
+  },
+  "health_check": {
+    "description": "Check adapter health and connectivity",
+    "code": "from vaults.adapters.token_adapter.adapter import TokenAdapter\n\n# Initialize adapter (no config needed)\nadapter = TokenAdapter()\n\n# Check health\nhealth = await adapter.health_check()\nprint(f\"Adapter status: {health['status']}\")\nprint(f\"Connected: {health['connected']}\")\nprint(f\"Adapter type: {health['adapter']}\")\n\nif health['status'] == 'healthy':\n    print(\"Adapter is ready to use\")\nelse:\n    print(f\"Adapter has issues: {health.get('error', 'Unknown error')}\")"
+  },
+  "batch_operations": {
+    "description": "Perform multiple token lookups efficiently",
+    "code": "from vaults.adapters.token_adapter.adapter import TokenAdapter\nimport asyncio\n\n# Initialize adapter (no config needed)\nadapter = TokenAdapter()\n\n# List of token addresses to lookup\ntoken_addresses = [\n    \"0x1234567890abcdef1234567890abcdef12345678\",\n    \"0xabcdef1234567890abcdef1234567890abcdef12\",\n    \"0x9876543210fedcba9876543210fedcba98765432\"\n]\n\n# Batch lookup\ntoken_data = {}\nfor address in token_addresses:\n    success, data = await adapter.get_token_by_address(address)\n    if success:\n        token_data[address] = data\n    else:\n        print(f\"Failed to get token for {address}: {data}\")\n\nprint(f\"Successfully retrieved {len(token_data)} tokens\")\nfor address, data in token_data.items():\n    print(f\"{address}: {data.get('symbol', 'Unknown')} - {data.get('name', 'Unknown')}\")"
+  }
+}

wayfinder_paths/vaults/adapters/token_adapter/manifest.yaml

@@ -0,0 +1,6 @@
+schema_version: "0.1"
+entrypoint: "vaults.adapters.token_adapter.adapter.TokenAdapter"
+capabilities:
+  - "token.read"
+dependencies:
+  - "TokenClient"

wayfinder_paths/vaults/adapters/token_adapter/test_adapter.py

@@ -0,0 +1,135 @@
+from unittest.mock import patch
+
+import pytest
+
+from wayfinder_paths.vaults.adapters.token_adapter.adapter import TokenAdapter
+
+
+class TestTokenAdapter:
+    """Test cases for TokenAdapter"""
+
+    @pytest.fixture
+    def adapter(self):
+        return TokenAdapter()
+
+    def test_init_with_default_config(self):
+        """Test adapter initialization with default config"""
+        adapter = TokenAdapter()
+        assert adapter.adapter_type == "TOKEN"
+        assert adapter.token_client is not None
+
+    @pytest.mark.asyncio
+    async def test_get_token_success(self, adapter):
+        """Test successful token retrieval by address"""
+        mock_token_data = {
+            "address": "0x1234...",
+            "symbol": "TEST",
+            "name": "Test Token",
+            "decimals": 18,
+        }
+
+        with patch.object(
+            adapter.token_client, "get_token_details", return_value=mock_token_data
+        ):
+            success, data = await adapter.get_token("0x1234...")
+
+            assert success is True
+            assert data == mock_token_data
+
+    @pytest.mark.asyncio
+    async def test_get_token_not_found(self, adapter):
+        """Test token not found by address"""
+        with patch.object(adapter.token_client, "get_token_details", return_value=None):
+            success, data = await adapter.get_token("0x1234...")
+
+            assert success is False
+            assert "No token found for address" in data
+
+    @pytest.mark.asyncio
+    async def test_get_token_flexible_success(self, adapter):
+        """Test flexible token retrieval with both address and token_id"""
+        mock_token_data = {"address": "0x1234...", "symbol": "TEST"}
+
+        with patch.object(
+            adapter.token_client, "get_token_details", return_value=mock_token_data
+        ):
+            success, data = await adapter.get_token(
+                address="0x1234...", token_id="token-123"
+            )
+
+            assert success is True
+            assert data == mock_token_data
+
+    @pytest.mark.asyncio
+    async def test_get_token_no_parameters(self, adapter):
+        """Test get_token with no parameters raises error"""
+        success, data = await adapter.get_token()
+
+        assert success is False
+        assert "Either address or token_id must be provided" in data
+
+    def test_adapter_type(self, adapter):
+        """Test adapter has adapter_type"""
+        assert adapter.adapter_type == "TOKEN"
+
+    @pytest.mark.asyncio
+    async def test_get_token_price_success(self, adapter):
+        """Test successful token price retrieval"""
+        mock_token_data = {
+            "current_price": 1.50,
+            "price_change_24h": 0.05,
+            "price_change_percentage_24h": 3.45,
+            "market_cap": 1000000,
+            "total_volume": 50000,
+            "symbol": "TEST",
+            "name": "Test Token",
+            "address": "0x1234...",
+        }
+
+        with patch.object(
+            adapter.token_client, "get_token_details", return_value=mock_token_data
+        ):
+            success, data = await adapter.get_token_price("test-token")
+
+            assert success is True
+            assert data["current_price"] == 1.50
+            assert data["symbol"] == "TEST"
+            assert data["name"] == "Test Token"
+
+    @pytest.mark.asyncio
+    async def test_get_token_price_not_found(self, adapter):
+        """Test token price not found"""
+        with patch.object(adapter.token_client, "get_token_details", return_value=None):
+            success, data = await adapter.get_token_price("invalid-token")
+
+            assert success is False
+            assert "No token found for" in data
+
+    @pytest.mark.asyncio
+    async def test_get_gas_token_success(self, adapter):
+        """Test successful gas token retrieval"""
+        mock_gas_token_data = {
+            "id": "ethereum-base",
+            "symbol": "ETH",
+            "name": "Ethereum",
+            "address": "0x0000000000000000000000000000000000000000",
+            "decimals": 18,
+        }
+
+        with patch.object(
+            adapter.token_client, "get_gas_token", return_value=mock_gas_token_data
+        ):
+            success, data = await adapter.get_gas_token("base")
+
+            assert success is True
+            assert data["symbol"] == "ETH"
+            assert data["name"] == "Ethereum"
+
+    @pytest.mark.asyncio
+    async def test_get_gas_token_not_found(self, adapter):
+        """Test gas token not found"""
+        with patch.object(adapter.token_client, "get_gas_token", return_value=None):
+            success, data = await adapter.get_gas_token("invalid-chain")
+
+            assert success is False
+            assert "No gas token found for chain" in data

wayfinder_paths/vaults/strategies/config.py

@@ -0,0 +1,85 @@
+"""
+Configuration for community strategies
+Each strategy can define its own configuration parameters
+"""
+
+from typing import Any
+
+# Funding Rate Strategy Configuration
+FUNDING_RATE_CONFIG = {
+    "min_deposit": 30,  # USDC
+    "lookback_days": 90,
+    "confidence": 0.9999,
+    "min_open_interest": 50_000,
+    "min_daily_volume": 100_000,
+    "max_leverage": 3,
+    "liquidation_threshold": 0.75,
+    "rebalance_threshold": 0.05,
+    "hyperliquid_system_address": "0x2Df1c51E09aECF9cacB7bc98cB1742757f163dF7",
+    "supported_chains": ["arbitrum"],
+}
+
+
+# Stablecoin Yield Strategy Configuration
+STABLECOIN_YIELD_CONFIG = {
+    "min_deposit": 50,  # USDC
+    "min_tvl": 1_000_000,  # $1M minimum TVL for safety
+    "min_apy": 0.01,  # 1% minimum APY
+    "rebalance_days": 7,  # Days until rebalance is profitable
+    "search_depth": 10,  # Number of pools to evaluate
+    "gas_buffer": 0.001,  # ETH for gas
+    "supported_chains": ["base", "arbitrum"],
+    "supported_tokens": ["USDC", "DAI", "USDT"],
+    "excluded_protocols": [],  # Protocols to avoid
+}
+
+
+# Moonwell wstETH Loop Strategy Configuration (example for advanced strategies)
+MOONWELL_LOOP_CONFIG = {
+    "min_deposit": 200,  # USDC
+    "max_loops": 30,
+    "leverage_limit": 10,
+    "contracts": {
+        "m_usdc": "0xedc817a28e8b93b03976fbd4a3ddbc9f7d176c22",
+        "m_weth": "0x628ff693426583D9a7FB391E54366292F509D457",
+        "m_wsteth": "0x627fe393bc6edda28e99ae648fd6ff362514304b",
+        "reward_distributor": "0xe9005b078701e2a0948d2eac43010d35870ad9d2",
+        "comptroller": "0xfbb21d0380bee3312b33c4353c8936a0f13ef26c",
+    },
+    "supported_chains": ["base"],
+}
+
+
+# Global adapter configurations
+ADAPTER_CONFIGS = {
+    "hyperliquid": {
+        "api_url": "https://api.hyperliquid.xyz",
+        "testnet_url": "https://api.hyperliquid-testnet.xyz",
+        "rate_limit": 10,  # requests per second
+        "timeout": 30,  # seconds
+        "slippage": 0.05,  # 5% default slippage for market orders
+    },
+    "enso": {
+        "router_address": "0xF75584eF6673aD213a685a1B58Cc0330B8eA22Cf",
+        "supported_chains": ["ethereum", "base", "arbitrum", "polygon"],
+    },
+    "moonwell": {
+        "supported_chains": ["base"],
+        "protocol_fee": 0.001,  # 0.1%
+    },
+}
+
+
+def get_strategy_config(strategy_name: str) -> dict[str, Any]:
+    """Get configuration for a specific strategy"""
+    configs = {
+        "funding_rate": FUNDING_RATE_CONFIG,
+        "stablecoin_yield": STABLECOIN_YIELD_CONFIG,
+        "moonwell_loop": MOONWELL_LOOP_CONFIG,
+    }
+    return configs.get(strategy_name.lower(), {})
+
+
+def get_adapter_config(adapter_name: str) -> dict[str, Any]:
+    """Get configuration for a specific adapter"""
+    return ADAPTER_CONFIGS.get(adapter_name.lower(), {})

wayfinder_paths/vaults/strategies/hyperlend_stable_yield_strategy/README.md

@@ -0,0 +1,99 @@
+# Hyperlend Stable Yield Strategy
+
+- Entrypoint: `vaults.strategies.hyperlend_stable_yield_strategy.strategy.HyperlendStableYieldStrategy`
+- Manifest: `manifest.yaml`
+- Examples: `examples.json`
+- Tests: `test_strategy.py`
+
+## What it does
+
+Allocates USDT0 on HyperEVM across HyperLend stablecoin markets. The strategy:
+
+1. Pulls USDT0 (plus a configurable HYPE gas buffer) from the main wallet into the vault wallet.
+2. Samples HyperLend hourly rate history, applies a bootstrap tournament (horizon = 6h, blocks = 6h, 4,000 trials, 7-day half-life) to estimate which stablecoin should outperform.
+3. Tops up the small HYPE gas buffer if needed, swaps USDT0 into the target stablecoin, and supplies it to HyperLend.
+4. Enforces a hysteresis rotation policy so minor APY noise does not churn capital.
+
+## Policy
+
+The manifest policy simply locks transactions to the vault wallet ID:
+
+```
+(wallet.id == 'FORMAT_WALLET_ID')
+```
+
+## Key parameters
+
+- `MIN_USDT0_DEPOSIT_AMOUNT = 1`
+- `GAS_MAXIMUM = 0.1` HYPE (max accepted per deposit)
+- `HORIZON_HOURS = 6`, `BLOCK_LEN = 6`, `TRIALS = 4000`
+- `HYSTERESIS_DWELL_HOURS = 168`, `HYSTERESIS_Z = 1.15`
+- `ROTATION_COOLDOWN = 168 hours`
+- `APY_REBALANCE_THRESHOLD = 0.0035` (35 bps edge required to rotate when not short-circuiting)
+- `MIN_STABLE_SWAP_TOKENS = 1e-3` → dust threshold when sweeping balances
+
+## Adapters used
+
+- `BalanceAdapter` for token/pool balances and orchestrating wallet transfers with ledger tracking.
+- `TokenAdapter` for metadata (USDT0, HYPE, wrapping info).
+- `LedgerAdapter` for net deposit + rotation history.
+- `BRAPAdapter` to source quotes/swap stablecoins.
+- `HyperlendAdapter` for asset views, lend/withdraw ops, supply caps.
+- `LocalTokenTxnService` via `DefaultWeb3Service` for low-level sends/approvals leveraged by the adapters.
+
+## Actions
+
+### Deposit
+
+- Validates USDT0 and HYPE balances in the main wallet.
+- Transfers HYPE into the vault wallet when a top-up is required, ensuring the vault maintains the configured buffer.
+- Moves USDT0 from the main wallet into the vault wallet through `BalanceAdapter.move_from_main_wallet_to_vault_wallet`.
+- Clears cached asset snapshots so the next update starts from on-chain reality.
+
+### Update
+
+- Refreshes HyperLend asset snapshots, calculates tournament winners, and filters markets that respect supply caps + buffer requirements.
+- Reads rotation history through `LedgerAdapter.get_vault_latest_transactions` to enforce the cooldown (unless the short-circuit policy is triggered).
+- If a new asset wins the tournament and passes hysteresis checks, BRAP quotes are fetched and executed to rotate into the better performer.
+- Sweeps residual stable balances, lends via `HyperlendAdapter`, and records ledger operations.
+
+### Status
+
+`_status()` returns:
+
+- `portfolio_value`: active lend balance (converted to float),
+- `net_deposit`: fetched from `LedgerAdapter`,
+- `strategy_status`: includes current lent asset, APY, idle balances, and tournament projections.
+
+### Withdraw
+
+- Unwinds existing HyperLend positions, swaps back to USDT0 when necessary, returns USDT0 and residual HYPE to the main wallet via `BalanceAdapter`, and clears cached state.
+
+## Running locally
+
+```bash
+# Install dependencies
+poetry install
+
+# Generate default + vault wallets (writes wallets.json)
+poetry run python wayfinder_paths/scripts/make_wallets.py --default --vault
+
+# Copy config and edit credentials (or rely on env vars)
+cp wayfinder_paths/config.example.json config.json
+
+# Check status / health
+poetry run python wayfinder_paths/run_strategy.py hyperlend_stable_yield_strategy --action status --config $(pwd)/config.json
+
+# Perform a deposit/update/withdraw cycle
+poetry run python wayfinder_paths/run_strategy.py hyperlend_stable_yield_strategy --action deposit --main-token-amount 25 --gas-token-amount 0.02 --config $(pwd)/config.json
+poetry run python wayfinder_paths/run_strategy.py hyperlend_stable_yield_strategy --action update --config $(pwd)/config.json
+poetry run python wayfinder_paths/run_strategy.py hyperlend_stable_yield_strategy --action withdraw --config $(pwd)/config.json
+```
+
+Use the manifest directly if you prefer:
+
+```bash
+poetry run python wayfinder_paths/run_strategy.py --manifest wayfinder_paths/vaults/strategies/hyperlend_stable_yield_strategy/manifest.yaml --action status --config $(pwd)/config.json
+```
+
+Wallet addresses/labels are auto-resolved from `wallets.json`. Set `NETWORK=testnet` in your config to run the orchestration without touching live HyperEVM endpoints.

wayfinder_paths/vaults/strategies/hyperlend_stable_yield_strategy/examples.json

@@ -0,0 +1,16 @@
+{
+  "smoke": {
+    "deposit": {"main_token_amount": 100.0, "gas_token_amount": 0.001},
+    "update": {},
+    "status": {},
+    "withdraw": {}
+  },
+  "min_deposit_fail": {
+    "deposit": {"main_token_amount": 0.5, "gas_token_amount": 0.0},
+    "expect": {"success": false}
+  },
+  "gas_exceeds_maximum": {
+    "deposit": {"main_token_amount": 100.0, "gas_token_amount": 0.2},
+    "expect": {"success": false}
+  }
+}

wayfinder_paths/vaults/strategies/hyperlend_stable_yield_strategy/manifest.yaml

@@ -0,0 +1,7 @@
+schema_version: "0.1"
+entrypoint: "vaults.strategies.hyperlend_stable_yield_strategy.strategy.HyperlendStableYieldStrategy"
+permissions:
+  policy: "(wallet.id == 'FORMAT_WALLET_ID')"
+adapters:
+  - name: "BALANCE"
+    capabilities: ["wallet_read"]