wayfinder-paths 0.1.7__py3-none-any.whl

wayfinder_paths/scripts/create_strategy.py

@@ -0,0 +1,181 @@
+#!/usr/bin/env python3
+"""
+Create a new strategy from template and generate a dedicated wallet for it.
+
+This script:
+1. Copies the strategy template to a new directory
+2. Generates a wallet with label matching the strategy name
+3. Updates the manifest with the strategy name
+"""
+
+import argparse
+import re
+import shutil
+from pathlib import Path
+
+import yaml
+
+from wayfinder_paths.core.utils.wallets import make_random_wallet, write_wallet_to_json
+
+
+def sanitize_name(name: str) -> str:
+    """Convert a strategy name to a valid directory/identifier name."""
+    # Replace spaces and special chars with underscores, lowercase
+    name = re.sub(r"[^a-zA-Z0-9_-]", "_", name)
+    # Remove multiple underscores
+    name = re.sub(r"_+", "_", name)
+    # Remove leading/trailing underscores
+    name = name.strip("_")
+    return name.lower()
+
+
+def update_manifest(manifest_path: Path, strategy_name: str, entrypoint: str) -> None:
+    """Update manifest.yaml with strategy name and entrypoint."""
+    with open(manifest_path) as f:
+        manifest_data = yaml.safe_load(f)
+
+    manifest_data["name"] = strategy_name
+    manifest_data["entrypoint"] = entrypoint
+
+    with open(manifest_path, "w") as f:
+        yaml.dump(manifest_data, f, default_flow_style=False, sort_keys=False)
+
+
+def update_strategy_file(strategy_path: Path, class_name: str) -> None:
+    """Update strategy.py with new class name."""
+    content = strategy_path.read_text()
+    # Replace MyStrategy with the new class name
+    content = content.replace("MyStrategy", class_name)
+    # Replace my_strategy references in docstrings/comments
+    content = re.sub(
+        r"my_strategy", class_name.lower().replace("Strategy", ""), content
+    )
+    strategy_path.write_text(content)
+
+
+def main():
+    parser = argparse.ArgumentParser(
+        description="Create a new strategy from template with dedicated wallet"
+    )
+    parser.add_argument(
+        "name",
+        help="Strategy name (e.g., 'my_awesome_strategy' or 'My Awesome Strategy')",
+    )
+    parser.add_argument(
+        "--template-dir",
+        type=Path,
+        default=Path(__file__).parent.parent / "templates" / "strategy",
+        help="Path to strategy template directory",
+    )
+    parser.add_argument(
+        "--strategies-dir",
+        type=Path,
+        default=Path(__file__).parent.parent / "strategies",
+        help="Path to strategies directory",
+    )
+    parser.add_argument(
+        "--wallets-file",
+        type=Path,
+        default=Path(__file__).parent.parent.parent / "wallets.json",
+        help="Path to wallets.json file",
+    )
+    parser.add_argument(
+        "--override",
+        action="store_true",
+        help="Override existing strategy directory if it exists",
+    )
+    args = parser.parse_args()
+
+    # Sanitize name for directory
+    dir_name = sanitize_name(args.name)
+    strategy_dir = args.strategies_dir / dir_name
+
+    # Check if directory already exists
+    if strategy_dir.exists() and not args.override:
+        raise SystemExit(
+            f"Strategy directory already exists: {strategy_dir}\n"
+            "Use --override to replace it"
+        )
+
+    # Check template exists
+    if not args.template_dir.exists():
+        raise SystemExit(f"Template directory not found: {args.template_dir}")
+
+    # Create strategy directory
+    if strategy_dir.exists():
+        print(f"Removing existing directory: {strategy_dir}")
+        shutil.rmtree(strategy_dir)
+    strategy_dir.mkdir(parents=True, exist_ok=True)
+    print(f"Created strategy directory: {strategy_dir}")
+
+    # Copy template files
+    template_files = [
+        "strategy.py",
+        "manifest.yaml",
+        "test_strategy.py",
+        "examples.json",
+        "README.md",
+    ]
+    for filename in template_files:
+        src = args.template_dir / filename
+        if src.exists():
+            dst = strategy_dir / filename
+            shutil.copy2(src, dst)
+            print(f"  Copied {filename}")
+
+    # Generate class name from strategy name
+    # Convert "my_awesome_strategy" -> "MyAwesomeStrategy"
+    class_name = "".join(word.capitalize() for word in dir_name.split("_"))
+    if not class_name.endswith("Strategy"):
+        class_name += "Strategy"
+
+    # Update strategy.py with new class name
+    strategy_file = strategy_dir / "strategy.py"
+    if strategy_file.exists():
+        update_strategy_file(strategy_file, class_name)
+        print(f"  Updated strategy.py with class name: {class_name}")
+
+    # Generate entrypoint path
+    entrypoint = f"strategies.{dir_name}.strategy.{class_name}"
+
+    # Update manifest with name (using directory name) and entrypoint
+    manifest_path = strategy_dir / "manifest.yaml"
+    if manifest_path.exists():
+        update_manifest(manifest_path, dir_name, entrypoint)
+        print(f"  Updated manifest.yaml with name: {dir_name}")
+
+    # Generate wallet with label matching directory name (strategy identifier)
+    # If wallets.json doesn't exist, create it with a main wallet first
+    if not args.wallets_file.exists():
+        print("  Creating new wallets.json with main wallet...")
+        main_wallet = make_random_wallet()
+        main_wallet["label"] = "main"
+        write_wallet_to_json(
+            main_wallet,
+            out_dir=args.wallets_file.parent,
+            filename=args.wallets_file.name,
+        )
+        print(f"  Generated main wallet: {main_wallet['address']}")
+
+    # Generate strategy wallet (will append to existing wallets.json)
+    wallet = make_random_wallet()
+    wallet["label"] = dir_name
+    write_wallet_to_json(
+        wallet, out_dir=args.wallets_file.parent, filename=args.wallets_file.name
+    )
+    print(f"  Generated strategy wallet: {wallet['address']} (label: {dir_name})")
+
+    print("\n✅ Strategy created successfully!")
+    print(f"   Directory: {strategy_dir}")
+    print(f"   Name: {dir_name}")
+    print(f"   Class: {class_name}")
+    print(f"   Entrypoint: {entrypoint}")
+    print(f"   Wallet: {wallet['address']}")
+    print("\nNext steps:")
+    print(f"   1. Edit {strategy_dir / 'strategy.py'} to implement your strategy")
+    print(f"   2. Update {strategy_dir / 'manifest.yaml'} with required adapters")
+    print(f"   3. Test with: just test-strategy {dir_name}")
+
+
+if __name__ == "__main__":
+    main()

wayfinder_paths/scripts/make_wallets.py

@@ -0,0 +1,169 @@
+import argparse
+import json
+from pathlib import Path
+
+from eth_account import Account
+
+from wayfinder_paths.core.utils.wallets import (
+    load_wallets,
+    make_random_wallet,
+    write_wallet_to_json,
+)
+
+
+def to_keystore_json(private_key_hex: str, password: str):
+    return Account.encrypt(private_key_hex, password)
+
+
+def write_env(rows: list[dict[str, str]], out_dir: Path) -> None:
+    with open(out_dir / ".env.example", "w") as f:
+        if rows:
+            label_to_wallet = {r.get("label"): r for r in rows if r.get("label")}
+            main_w = (
+                label_to_wallet.get("main") or label_to_wallet.get("default") or rows[0]
+            )
+            strategy_w = label_to_wallet.get("strategy")
+
+            f.write("RPC_URL=https://rpc.ankr.com/eth\n")
+            # Back-compat defaults
+            f.write(f"PRIVATE_KEY={main_w['private_key_hex']}\n")
+            f.write(f"FROM_ADDRESS={main_w['address']}\n")
+            # Explicit main/strategy variables
+            f.write(f"MAIN_WALLET_ADDRESS={main_w['address']}\n")
+            if strategy_w:
+                f.write(f"STRATEGY_WALLET_ADDRESS={strategy_w['address']}\n")
+                # Optional: expose strategy private key for local dev only
+                f.write(f"PRIVATE_KEY_STRATEGY={strategy_w['private_key_hex']}\n")
+
+
+def main():
+    parser = argparse.ArgumentParser(description="Generate local dev wallets")
+    parser.add_argument(
+        "-n",
+        type=int,
+        default=0,
+        help="Number of wallets to create (ignored if --label is used)",
+    )
+    parser.add_argument(
+        "--out-dir",
+        type=Path,
+        default=Path("."),
+        help="Output directory for wallets.json (and .env/keystore)",
+    )
+    parser.add_argument(
+        "--keystore-password",
+        type=str,
+        default=None,
+        help="Optional password to write geth-compatible keystores",
+    )
+    parser.add_argument(
+        "--label",
+        type=str,
+        default=None,
+        help="Create a wallet with a custom label (e.g., strategy name). If not provided, auto-generates labels.",
+    )
+    parser.add_argument(
+        "--default",
+        action="store_true",
+        help="Create a default 'main' wallet if none exists (used by CI)",
+    )
+    args = parser.parse_args()
+
+    # --default is equivalent to -n 1 (create main wallet if needed)
+    if args.default and args.n == 0 and not args.label:
+        args.n = 1
+
+    args.out_dir.mkdir(parents=True, exist_ok=True)
+
+    # Load existing wallets
+    existing = load_wallets(args.out_dir, "wallets.json")
+    has_main = any(w.get("label") in ("main", "default") for w in existing)
+
+    rows: list[dict[str, str]] = []
+    index = 0
+
+    # Custom labeled wallet (e.g., for strategy name)
+    if args.label:
+        # Check if label already exists - if so, skip (don't create duplicate)
+        if any(w.get("label") == args.label for w in existing):
+            print(f"Wallet with label '{args.label}' already exists, skipping...")
+        else:
+            # Create wallet with specified label
+            w = make_random_wallet()
+            w["label"] = args.label
+            rows.append(w)
+            print(f"[{index}] {w['address']}  (label: {args.label})")
+            write_wallet_to_json(w, out_dir=args.out_dir, filename="wallets.json")
+            if args.keystore_password:
+                ks = to_keystore_json(w["private_key_hex"], args.keystore_password)
+                ks_path = args.out_dir / f"keystore_{w['address']}.json"
+                ks_path.write_text(json.dumps(ks))
+            index += 1
+
+            # If no wallets existed before, also create a "main" wallet
+            if not existing:
+                main_w = make_random_wallet()
+                main_w["label"] = "main"
+                rows.append(main_w)
+                print(f"[{index}] {main_w['address']}  (main)")
+                write_wallet_to_json(
+                    main_w, out_dir=args.out_dir, filename="wallets.json"
+                )
+                if args.keystore_password:
+                    ks = to_keystore_json(
+                        main_w["private_key_hex"], args.keystore_password
+                    )
+                    ks_path = args.out_dir / f"keystore_{main_w['address']}.json"
+                    ks_path.write_text(json.dumps(ks))
+                index += 1
+    else:
+        # Create wallets with auto-generated labels: first one is "main" if main doesn't exist, others are "temporary_N"
+        if args.n == 0:
+            args.n = 1  # Default to 1 wallet if neither -n nor --label specified
+
+        # Find next temporary number
+        existing_labels = {
+            w.get("label", "")
+            for w in existing
+            if w.get("label", "").startswith("temporary_")
+        }
+        temp_numbers = set()
+        for label in existing_labels:
+            try:
+                num = int(label.replace("temporary_", ""))
+                temp_numbers.add(num)
+            except ValueError:
+                pass
+        next_temp_num = 1
+        if temp_numbers:
+            next_temp_num = max(temp_numbers) + 1
+
+        for i in range(args.n):
+            w = make_random_wallet()
+            # Label first wallet as "main" if main doesn't exist, otherwise use temporary_N
+            if i == 0 and not has_main:
+                w["label"] = "main"
+                rows.append(w)
+                print(f"[{index}] {w['address']}  (main)")
+            else:
+                # Find next available temporary number
+                while next_temp_num in temp_numbers:
+                    next_temp_num += 1
+                w["label"] = f"temporary_{next_temp_num}"
+                temp_numbers.add(next_temp_num)
+                rows.append(w)
+                print(f"[{index}] {w['address']}  (label: temporary_{next_temp_num})")
+
+            write_wallet_to_json(w, out_dir=args.out_dir, filename="wallets.json")
+            if args.keystore_password:
+                ks = to_keystore_json(w["private_key_hex"], args.keystore_password)
+                ks_path = args.out_dir / f"keystore_{w['address']}.json"
+                ks_path.write_text(json.dumps(ks))
+            index += 1
+
+    # Convenience outputs
+    write_env(rows, args.out_dir)
+
+
+if __name__ == "__main__":
+    main()

wayfinder_paths/scripts/run_strategy.py

@@ -0,0 +1,124 @@
+from __future__ import annotations
+
+import argparse
+import asyncio
+import json
+from pathlib import Path
+from typing import Any
+
+
+def _load_wallets(path: Path) -> list[dict[str, Any]]:
+    data = json.loads(path.read_text(encoding="utf-8"))
+    if not isinstance(data, list):
+        raise ValueError(f"Expected a list in {path}")
+    return [w for w in data if isinstance(w, dict)]
+
+
+def _find_wallet(wallets: list[dict[str, Any]], label: str) -> dict[str, Any]:
+    for w in wallets:
+        if w.get("label") == label:
+            return w
+    raise ValueError(f"Wallet label not found in wallets.json: {label}")
+
+
+def _get_strategy_class(strategy: str):
+    if strategy == "basis_trading_strategy":
+        from wayfinder_paths.strategies.basis_trading_strategy.strategy import (
+            BasisTradingStrategy,
+        )
+
+        return BasisTradingStrategy
+
+    if strategy == "hyperlend_stable_yield_strategy":
+        from wayfinder_paths.strategies.hyperlend_stable_yield_strategy.strategy import (
+            HyperlendStableYieldStrategy,
+        )
+
+        return HyperlendStableYieldStrategy
+
+    raise ValueError(f"Unknown strategy: {strategy}")
+
+
+async def _run(args: argparse.Namespace) -> int:
+    repo_root = Path(__file__).resolve().parents[2]
+    wallets_path = (
+        Path(args.wallets).resolve() if args.wallets else repo_root / "wallets.json"
+    )
+    wallets = _load_wallets(wallets_path)
+
+    main_wallet = _find_wallet(wallets, args.main_wallet_label)
+    strategy_wallet = _find_wallet(wallets, args.strategy_wallet_label)
+
+    strategy_class = _get_strategy_class(args.strategy)
+    s = strategy_class(
+        {
+            "main_wallet": main_wallet,
+            "strategy_wallet": strategy_wallet,
+        },
+        simulation=args.simulation,
+    )
+
+    await s.setup()
+
+    if args.command == "deposit":
+        ok, msg = await s.deposit(
+            main_token_amount=float(args.usdc), gas_token_amount=float(args.eth)
+        )
+        print(msg)
+        return 0 if ok else 1
+
+    if args.command == "update":
+        ok, msg = await s.update()
+        print(msg)
+        return 0 if ok else 1
+
+    if args.command == "withdraw":
+        ok, msg = await s.withdraw(
+            amount=float(args.amount) if args.amount is not None else None
+        )
+        print(msg)
+        return 0 if ok else 1
+
+    if args.command == "status":
+        st = await s.status()
+        print(json.dumps(st, indent=2, sort_keys=True))
+        return 0
+
+    raise ValueError(f"Unknown command: {args.command}")
+
+
+def main() -> int:
+    p = argparse.ArgumentParser(
+        description="Run a strategy locally (deposit/update/withdraw/status)."
+    )
+    p.add_argument(
+        "--strategy",
+        default="basis_trading_strategy",
+        choices=["basis_trading_strategy", "hyperlend_stable_yield_strategy"],
+    )
+    p.add_argument(
+        "--wallets", default=None, help="Path to wallets.json (default: repo root)"
+    )
+    p.add_argument("--main-wallet-label", default="main")
+    p.add_argument("--strategy-wallet-label", default="basis_trading_strategy")
+    p.add_argument("--simulation", action="store_true")
+
+    sub = p.add_subparsers(dest="command", required=True)
+
+    dep = sub.add_parser("deposit")
+    dep.add_argument("--usdc", required=True, type=float)
+    dep.add_argument("--eth", default=0.0, type=float)
+
+    sub.add_parser("update")
+
+    wd = sub.add_parser("withdraw")
+    wd.add_argument("--amount", default=None, type=float)
+
+    sub.add_parser("status")
+
+    args = p.parse_args()
+    return asyncio.run(_run(args))
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

wayfinder_paths/scripts/validate_manifests.py

@@ -0,0 +1,213 @@
+#!/usr/bin/env python3
+"""
+Manifest Validator
+
+Validates all adapter and strategy manifests in the repository.
+"""
+
+import sys
+from pathlib import Path
+
+from loguru import logger
+
+# Add parent to path for imports
+sys.path.insert(0, str(Path(__file__).parent.parent))
+
+from wayfinder_paths.core.adapters.BaseAdapter import BaseAdapter
+from wayfinder_paths.core.engine.manifest import (
+    load_adapter_manifest,
+    load_strategy_manifest,
+)
+from wayfinder_paths.core.strategies.Strategy import Strategy
+
+
+def verify_entrypoint(entrypoint: str) -> tuple[bool, str | None]:
+    """Verify entrypoint is importable. Returns (success, error_message)."""
+    try:
+        module_path, class_name = entrypoint.rsplit(".", 1)
+        module = __import__(module_path, fromlist=[class_name], level=0)
+        getattr(module, class_name)  # Verify class exists
+        return True, None
+    except ImportError as e:
+        return False, f"Import error: {str(e)}"
+    except AttributeError as e:
+        return False, f"Class not found: {str(e)}"
+    except Exception as e:
+        return False, f"Unexpected error: {str(e)}"
+
+
+def verify_adapter_class(entrypoint: str) -> tuple[bool, str | None]:
+    """Verify entrypoint is an adapter class."""
+    valid, error = verify_entrypoint(entrypoint)
+    if not valid:
+        return False, error
+
+    try:
+        module_path, class_name = entrypoint.rsplit(".", 1)
+        module = __import__(module_path, fromlist=[class_name], level=0)
+        adapter_class = getattr(module, class_name)
+
+        if not issubclass(adapter_class, BaseAdapter):
+            return False, f"{class_name} is not a BaseAdapter"
+        return True, None
+    except Exception as e:
+        return False, f"Error verifying adapter: {str(e)}"
+
+
+def verify_strategy_class(entrypoint: str) -> tuple[bool, str | None]:
+    """Verify entrypoint is a strategy class."""
+    valid, error = verify_entrypoint(entrypoint)
+    if not valid:
+        return False, error
+
+    try:
+        module_path, class_name = entrypoint.rsplit(".", 1)
+        module = __import__(module_path, fromlist=[class_name], level=0)
+        strategy_class = getattr(module, class_name)
+
+        if not issubclass(strategy_class, Strategy):
+            return False, f"{class_name} is not a Strategy"
+        return True, None
+    except Exception as e:
+        return False, f"Error verifying strategy: {str(e)}"
+
+
+# Capabilities are only declared in manifest - no code validation needed
+# Manifest is the single source of truth for capabilities
+
+
+def verify_dependencies(dependencies: list[str]) -> tuple[bool, list[str]]:
+    """Verify dependencies are importable. Returns (valid, error_messages)."""
+    errors = []
+
+    for dep in dependencies:
+        # Try to import from core.clients
+        try:
+            __import__(f"core.clients.{dep}", fromlist=[dep], level=0)
+        except ImportError:
+            errors.append(f"Dependency '{dep}' not found in core.clients")
+        except Exception as e:
+            errors.append(f"Error importing dependency '{dep}': {str(e)}")
+
+    return len(errors) == 0, errors
+
+
+def validate_adapter_manifest(manifest_path: str) -> tuple[bool, list[str]]:
+    """Validate adapter manifest. Returns (valid, error_messages)."""
+    errors = []
+
+    try:
+        manifest = load_adapter_manifest(manifest_path)
+    except Exception as e:
+        return False, [f"Schema error: {str(e)}"]
+
+    # Verify entrypoint
+    valid, error = verify_adapter_class(manifest.entrypoint)
+    if not valid:
+        errors.append(f"Entrypoint validation failed: {error}")
+        return False, errors
+
+    # Verify dependencies
+    valid, dep_errors = verify_dependencies(manifest.dependencies)
+    if not valid:
+        errors.extend(dep_errors)
+
+    return len(errors) == 0, errors
+
+
+def validate_strategy_manifest(manifest_path: str) -> tuple[bool, list[str]]:
+    """Validate strategy manifest. Returns (valid, error_messages)."""
+    errors = []
+
+    try:
+        manifest = load_strategy_manifest(manifest_path)
+    except Exception as e:
+        return False, [f"Schema error: {str(e)}"]
+
+    # Verify entrypoint
+    valid, error = verify_strategy_class(manifest.entrypoint)
+    if not valid:
+        errors.append(f"Entrypoint validation failed: {error}")
+        return False, errors
+
+    # Permissions are already validated by Pydantic model
+
+    return len(errors) == 0, errors
+
+
+def find_adapter_manifests() -> list[Path]:
+    """Find all adapter manifest files."""
+    manifests = []
+    adapter_dir = Path(__file__).parent.parent / "adapters"
+    if adapter_dir.exists():
+        for adapter_path in adapter_dir.iterdir():
+            manifest_path = adapter_path / "manifest.yaml"
+            if manifest_path.exists():
+                manifests.append(manifest_path)
+    return manifests
+
+
+def find_strategy_manifests() -> list[Path]:
+    """Find all strategy manifest files."""
+    manifests = []
+    strategy_dir = Path(__file__).parent.parent / "strategies"
+    if strategy_dir.exists():
+        for strategy_path in strategy_dir.iterdir():
+            manifest_path = strategy_path / "manifest.yaml"
+            if manifest_path.exists():
+                manifests.append(manifest_path)
+    return manifests
+
+
+def main() -> int:
+    """Main validation function. Returns 0 on success, 1 on failure."""
+    logger.info("Validating all manifests...")
+
+    all_valid = True
+    error_count = 0
+
+    # Validate adapter manifests
+    logger.info("\n=== Validating Adapter Manifests ===")
+    adapter_manifests = find_adapter_manifests()
+    for manifest_path in sorted(adapter_manifests):
+        logger.info(f"Validating {manifest_path}...")
+        valid, errors = validate_adapter_manifest(str(manifest_path))
+        if valid:
+            logger.success(f"✅ {manifest_path.name} - Valid")
+        else:
+            logger.error(f"❌ {manifest_path.name} - Invalid")
+            for error in errors:
+                logger.error(f"   {error}")
+            all_valid = False
+            error_count += len(errors)
+
+    # Validate strategy manifests
+    logger.info("\n=== Validating Strategy Manifests ===")
+    strategy_manifests = find_strategy_manifests()
+    for manifest_path in sorted(strategy_manifests):
+        logger.info(f"Validating {manifest_path}...")
+        valid, errors = validate_strategy_manifest(str(manifest_path))
+        if valid:
+            logger.success(f"✅ {manifest_path.name} - Valid")
+        else:
+            logger.error(f"❌ {manifest_path.name} - Invalid")
+            for error in errors:
+                logger.error(f"   {error}")
+            all_valid = False
+            error_count += len(errors)
+
+    # Summary
+    logger.info("\n=== Summary ===")
+    if all_valid:
+        logger.success(
+            f"✅ All manifests valid! ({len(adapter_manifests)} adapters, "
+            f"{len(strategy_manifests)} strategies)"
+        )
+        return 0
+    else:
+        logger.error(f"❌ Validation failed with {error_count} error(s)")
+        return 1
+
+
+if __name__ == "__main__":
+    sys.exit(main())