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

wayfinder_paths/scripts/create_strategy.py

@@ -1,139 +0,0 @@
-#!/usr/bin/env python3
-
-import argparse
-import re
-import shutil
-from pathlib import Path
-
-from wayfinder_paths.core.utils.wallets import make_random_wallet, write_wallet_to_json
-
-
-def sanitize_name(name: str) -> str:
-    # Replace spaces and special chars with underscores, lowercase
-    name = re.sub(r"[^a-zA-Z0-9_-]", "_", name)
-    name = re.sub(r"_+", "_", name)
-    name = name.strip("_")
-    return name.lower()
-
-
-def update_strategy_file(strategy_path: Path, class_name: str) -> None:
-    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 / "config.json",
-        help="Path to config.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
-
-    if strategy_dir.exists() and not args.override:
-        raise SystemExit(
-            f"Strategy directory already exists: {strategy_dir}\n"
-            "Use --override to replace it"
-        )
-
-    if not args.template_dir.exists():
-        raise SystemExit(f"Template directory not found: {args.template_dir}")
-
-    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",
-        "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
-    class_name = "".join(word.capitalize() for word in dir_name.split("_"))
-    if not class_name.endswith("Strategy"):
-        class_name += "Strategy"
-
-    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 wallet with label matching directory name (strategy identifier)
-    # If config.json doesn't exist, create it with a main wallet first
-    if not args.wallets_file.exists():
-        print("  Creating new config.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 config.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"   Wallet: {wallet['address']}")
-    print("\nNext steps:")
-    print(f"   1. Edit {strategy_dir / 'strategy.py'} to implement your strategy")
-    print("   2. Add required adapters in __init__")
-    print(f"   3. Test with: just test-strategy {dir_name}")
-
-
-if __name__ == "__main__":
-    main()

wayfinder_paths/scripts/make_wallets.py

@@ -1,142 +0,0 @@
-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 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 config.json (and keystore files)",
-    )
-    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)
-
-    existing = load_wallets(args.out_dir, "config.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:
-            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="config.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="config.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:
-        if args.n == 0:
-            args.n = 1
-
-        # 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="config.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 __name__ == "__main__":
-    main()

wayfinder_paths-0.1.23.dist-info/METADATA

@@ -1,354 +0,0 @@
-Metadata-Version: 2.1
-Name: wayfinder-paths
-Version: 0.1.23
-Summary: Wayfinder Path: strategies and adapters
-Author: Wayfinder
-Author-email: dev@wayfinder.ai
-Requires-Python: >=3.12,<4.0
-Classifier: Programming Language :: Python :: 3
-Classifier: Programming Language :: Python :: 3.12
-Requires-Dist: aiohttp (>=3.13.0,<4.0.0)
-Requires-Dist: eth-account (>=0.13.7,<0.14.0)
-Requires-Dist: httpx (>=0.28.1,<0.29.0)
-Requires-Dist: hyperliquid-felix
-Requires-Dist: loguru (>=0.7.3,<0.8.0)
-Requires-Dist: numpy (>=1.26.0,<2.0.0)
-Requires-Dist: pandas (>=2.2.0,<3.0.0)
-Requires-Dist: pydantic (>=2.11.9,<3.0.0)
-Requires-Dist: pyyaml (>=6.0.1,<7.0.0)
-Requires-Dist: web3 (>=7.13.0,<8.0.0)
-Description-Content-Type: text/markdown
-
-# Wayfinder Paths
-
-[![Python 3.12](https://img.shields.io/badge/python-3.12-blue.svg)](https://www.python.org/downloads/)
-[![PyPI](https://img.shields.io/pypi/v/wayfinder-paths.svg)](https://pypi.org/project/wayfinder-paths/)
-[![Discord](https://img.shields.io/badge/discord-join-7289da.svg)](https://discord.gg/fUVwGMXjm3)
-
-Open-source framework for building automated crypto trading strategies and protocol integrations. Develop, test, and deploy strategies with direct wallet integration across multiple chains.
-
-## Quick Start
-
-```bash
-# Clone the repository
-git clone https://github.com/WayfinderFoundation/wayfinder-paths.git
-cd wayfinder-paths
-
-# Install Poetry if needed
-curl -sSL https://install.python-poetry.org | python3 -
-
-# Install dependencies
-poetry install
-
-# Generate test wallets (creates config.json with main wallet)
-just create-wallets
-# Or: poetry run python wayfinder_paths/scripts/make_wallets.py -n 1
-
-# Create a strategy-specific wallet
-just create-wallet stablecoin_yield_strategy
-# Or: poetry run python wayfinder_paths/scripts/make_wallets.py --label stablecoin_yield_strategy
-
-# Add your API key to config.json under system.api_key
-
-# Run a strategy
-poetry run python wayfinder_paths/run_strategy.py stablecoin_yield_strategy --action status --config config.json
-```
-
-## Repository Structure
-
-```
-wayfinder-paths/
-├── wayfinder_paths/
-│   ├── core/                     # Core framework (maintained by team)
-│   │   ├── adapters/             # BaseAdapter class
-│   │   ├── clients/              # API clients (Token, Wallet, Pool, BRAP, Ledger, etc.)
-│   │   ├── engine/               # StrategyJob execution engine
-│   │   ├── strategies/           # Strategy base class and descriptors
-│   │   ├── utils/                # Web3, EVM helpers, transaction utilities
-│   │   └── config.py             # Configuration system
-│   ├── adapters/                 # Protocol integrations (community contributions)
-│   │   ├── balance_adapter/      # Wallet/token balances and transfers
-│   │   ├── brap_adapter/         # Cross-chain swaps and bridges
-│   │   ├── ledger_adapter/       # Transaction recording
-│   │   ├── moonwell_adapter/     # Moonwell lending protocol
-│   │   ├── pool_adapter/         # DeFi pool data
-│   │   └── token_adapter/        # Token metadata and prices
-│   ├── strategies/               # Trading strategies (community contributions)
-│   │   ├── basis_trading_strategy/
-│   │   ├── hyperlend_stable_yield_strategy/
-│   │   ├── moonwell_wsteth_loop_strategy/
-│   │   └── stablecoin_yield_strategy/
-│   ├── templates/                # Starter templates
-│   │   ├── adapter/
-│   │   └── strategy/
-│   ├── scripts/                  # Utility scripts
-│   └── run_strategy.py           # CLI entry point
-├── config.json                   # Local config (not committed)
-├── pyproject.toml                # Project dependencies
-└── README.md
-```
-
-## Architecture
-
-### Layered Design
-
-```
-Strategy Layer       - Trading logic (deposit, update, withdraw, exit)
-       ↓
-Adapter Layer        - Protocol integrations (BalanceAdapter, PoolAdapter, etc.)
-       ↓
-Client Layer         - API wrappers (TokenClient, PoolClient, LedgerClient, etc.)
-       ↓
-Network              - RPCs, Wayfinder API, external services
-```
-
-**Key principle**: Strategies call adapters, adapters compose clients, clients handle network communication.
-
-### Strategies
-
-Strategies implement trading logic by extending the `Strategy` base class:
-
-```python
-from wayfinder_paths.core.strategies.Strategy import Strategy, StatusDict, StatusTuple
-
-class MyStrategy(Strategy):
-    name = "My Strategy"
-
-    def __init__(self, config=None, **kwargs):
-        super().__init__(config, **kwargs)
-        # Register adapters
-        balance_adapter = BalanceAdapter(config, **kwargs)
-        self.register_adapters([balance_adapter])
-        self.balance_adapter = balance_adapter
-
-    async def deposit(self, main_token_amount=0.0, gas_token_amount=0.0) -> StatusTuple:
-        """Move funds from main wallet into strategy wallet."""
-        return (True, "Deposited successfully")
-
-    async def update(self) -> StatusTuple:
-        """Rebalance or optimize positions."""
-        return (True, "Updated successfully")
-
-    async def exit(self, **kwargs) -> StatusTuple:
-        """Transfer funds from strategy wallet back to main wallet."""
-        return (True, "Exited successfully")
-
-    async def _status(self) -> StatusDict:
-        """Report current state."""
-        return {
-            "portfolio_value": 0.0,
-            "net_deposit": 0.0,
-            "strategy_status": {"message": "healthy"},
-            "gas_available": 0.0,
-            "gassed_up": True,
-        }
-```
-
-**Required methods**: `deposit`, `update`, `exit`, `_status`
-
-**Optional methods**: `withdraw` (has default implementation), `partial_liquidate`, `setup`, `health_check`
-
-### Adapters
-
-Adapters wrap protocol-specific logic and expose capabilities to strategies:
-
-```python
-from wayfinder_paths.core.adapters.BaseAdapter import BaseAdapter
-
-class MyAdapter(BaseAdapter):
-    adapter_type = "MY_ADAPTER"
-
-    def __init__(self, config=None):
-        super().__init__("my_adapter", config)
-        self.client = SomeClient()
-
-    async def connect(self) -> bool:
-        return True
-
-    async def do_something(self, param: str) -> tuple[bool, Any]:
-        try:
-            result = await self.client.call(param)
-            return (True, result)
-        except Exception as e:
-            return (False, str(e))
-```
-
-All adapter methods return `(success: bool, data: Any)` tuples.
-
-### Built-in Adapters
-
-| Adapter | Type | Purpose |
-|---------|------|---------|
-| BalanceAdapter | BALANCE | Wallet/token balances, cross-wallet transfers with ledger tracking |
-| PoolAdapter | POOL | DeFi pool metadata and yield analytics |
-| BRAPAdapter | BRAP | Cross-chain swap quotes and execution |
-| LedgerAdapter | LEDGER | Transaction recording and net deposit tracking |
-| TokenAdapter | TOKEN | Token metadata and price feeds |
-| MoonwellAdapter | MOONWELL | Moonwell lending/borrowing on Base |
-
-### Built-in Strategies
-
-| Strategy | Description | Chain |
-|----------|-------------|-------|
-| stablecoin_yield_strategy | USDC yield optimization on Base | Base |
-| hyperlend_stable_yield_strategy | Stablecoin yield on HyperLend | HyperEVM |
-| moonwell_wsteth_loop_strategy | Leveraged wstETH carry trade | Base |
-| basis_trading_strategy | Delta-neutral funding rate capture | Hyperliquid |
-
-## Configuration
-
-Configuration lives in `config.json`:
-
-```json
-{
-  "system": {
-    "api_base_url": "https://api.wayfinder.ai",
-    "api_key": "sk_live_..."
-  },
-  "strategy": {
-    "rpc_urls": {
-      "1": "https://eth.llamarpc.com",
-      "8453": "https://mainnet.base.org",
-      "42161": "https://arb1.arbitrum.io/rpc"
-    }
-  },
-  "wallets": [
-    {
-      "label": "main",
-      "address": "0x...",
-      "private_key_hex": "0x..."
-    },
-    {
-      "label": "stablecoin_yield_strategy",
-      "address": "0x...",
-      "private_key_hex": "0x..."
-    }
-  ]
-}
-```
-
-- **system.api_key**: Required for Wayfinder API authentication (sent as `X-API-KEY` header)
-- **wallets**: Array of wallets with labels; strategies look up wallets by label matching their directory name
-- **strategy.rpc_urls**: Custom RPC endpoints by chain ID
-
-See [CONFIG_GUIDE.md](CONFIG_GUIDE.md) for detailed configuration documentation.
-
-## CLI Usage
-
-```bash
-# Check strategy status
-poetry run python wayfinder_paths/run_strategy.py <strategy_name> --action status --config config.json
-
-# Deposit funds
-poetry run python wayfinder_paths/run_strategy.py <strategy_name> --action deposit \
-    --main-token-amount 100 --gas-token-amount 0.01 --config config.json
-
-# Run update cycle
-poetry run python wayfinder_paths/run_strategy.py <strategy_name> --action update --config config.json
-
-# Withdraw funds
-poetry run python wayfinder_paths/run_strategy.py <strategy_name> --action withdraw --config config.json
-
-# Exit (return funds to main wallet)
-poetry run python wayfinder_paths/run_strategy.py <strategy_name> --action exit --config config.json
-
-# Run continuously
-poetry run python wayfinder_paths/run_strategy.py <strategy_name> --action run --config config.json
-
-# Partial liquidation
-poetry run python wayfinder_paths/run_strategy.py <strategy_name> --action partial-liquidate \
-    --amount 50 --config config.json
-```
-
-**Available actions**: `status`, `deposit`, `update`, `withdraw`, `exit`, `run`, `partial-liquidate`, `policy`, `script`
-
-## Testing
-
-```bash
-# Generate test wallets first
-just create-wallets
-
-# Run all smoke tests
-poetry run pytest -k smoke -v
-
-# Test specific strategy
-poetry run pytest wayfinder_paths/strategies/my_strategy/ -v
-
-# Test specific adapter
-poetry run pytest wayfinder_paths/adapters/my_adapter/ -v
-
-# Run with coverage
-poetry run pytest --cov=wayfinder_paths -v
-```
-
-See [TESTING.md](TESTING.md) for detailed testing guidance.
-
-## Contributing
-
-### Creating a New Strategy
-
-```bash
-# Use the convenience command (creates wallet automatically)
-just create-strategy "My Strategy Name"
-
-# Or manually copy the template
-cp -r wayfinder_paths/templates/strategy wayfinder_paths/strategies/my_strategy
-```
-
-Then:
-1. Rename the class in `strategy.py`
-2. Implement `deposit`, `update`, `exit`, and `_status` methods
-3. Add tests in `test_strategy.py`
-4. Create `examples.json` with test data
-5. Update the README
-
-### Creating a New Adapter
-
-```bash
-cp -r wayfinder_paths/templates/adapter wayfinder_paths/adapters/my_adapter
-```
-
-Then:
-1. Rename the class in `adapter.py`
-2. Implement protocol-specific methods
-3. Add tests in `test_adapter.py`
-4. Update the README
-
-### Guidelines
-
-- Strategies call adapters, not clients directly
-- All adapter methods return `(success, data)` tuples
-- Use `examples.json` for strategy test data
-- Never hardcode API keys or private keys
-- Add tests before submitting PRs
-
-## Publishing
-
-```bash
-# Must be on main branch
-export PUBLISH_TOKEN="your_pypi_token"
-just publish
-```
-
-**Version bumping**: Update `version` in `pyproject.toml` before publishing. Follow [SemVer](https://semver.org/):
-- PATCH: Bug fixes
-- MINOR: New features (backward compatible)
-- MAJOR: Breaking changes
-
-## Security
-
-- Never commit `config.json` (contains private keys)
-- Use test wallets for development
-- Test on testnets when available
-- Validate all inputs
-- Set appropriate gas limits
-
-## Community
-
-- [Discord](https://discord.gg/fUVwGMXjm3)
-- [GitHub Issues](https://github.com/WayfinderFoundation/wayfinder-paths/issues)
-
-## License
-
-MIT License - see [LICENSE](LICENSE) for details.
-