wayfinder-paths 0.1.8__tar.gz → 0.1.10__tar.gz

{wayfinder_paths-0.1.8 → wayfinder_paths-0.1.10}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: wayfinder-paths
-Version: 0.1.8
+Version: 0.1.10
 Summary: Wayfinder Path: strategies and adapters
 Author: Wayfinder
 Author-email: dev@wayfinder.ai
@@ -47,6 +47,9 @@ poetry install
 just create-wallets
 # Or manually: poetry run python wayfinder_paths/scripts/make_wallets.py -n 1
 
+# To test a specific strategy
+just just create-wallet stablecoin_yield_strategy
+
 # Copy and configure
 cp wayfinder_paths/config.example.json config.json
 # Edit config.json with your Wayfinder credentials
@@ -54,9 +57,6 @@ cp wayfinder_paths/config.example.json config.json
 # Run a strategy locally (one-shot status check)
 poetry run python wayfinder_paths/run_strategy.py stablecoin_yield_strategy --action status --config config.json
 
-export WAYFINDER_API_KEY="sk_live_abc123..."
-poetry run python wayfinder_paths/run_strategy.py stablecoin_yield_strategy --config config.json
-
 # Run continuously (production mode)
 poetry run python wayfinder_paths/run_strategy.py stablecoin_yield_strategy --config config.json
 ```
@@ -75,7 +75,6 @@ wayfinder_paths/
 │   ├── adapters/                 # Your exchange/protocol integrations (community contributions)
 │   │   ├── balance_adapter/
 │   │   │   ├── adapter.py        # Adapter implementation
-│   │   │   ├── manifest.yaml     # Adapter manifest (caps, entrypoint)
 │   │   │   ├── examples.json     # Example inputs for smoke
 │   │   │   ├── README.md         # Local notes
 │   │   │   └── test_adapter.py   # Local smoke test
@@ -84,7 +83,6 @@ wayfinder_paths/
 │   ├── strategies/               # Your trading strategies (community contributions)
 │   │   ├── stablecoin_yield_strategy/
 │   │   │   ├── strategy.py       # Strategy implementation
-│   │   │   ├── manifest.yaml     # Strategy manifest
 │   │   │   ├── examples.json     # Example inputs
 │   │   │   ├── README.md         # Local notes
 │   │   │   └── test_strategy.py  # Local smoke test
@@ -111,10 +109,9 @@ We welcome contributions! This is an open-source project where community members
 3. **Copy a template** to get started:
    - **For adapters**: Copy `wayfinder_paths/templates/adapter/` to `wayfinder_paths/adapters/my_adapter/`
    - **For strategies**: Copy `wayfinder_paths/templates/strategy/` to `wayfinder_paths/strategies/my_strategy/`
-4. **Customize** the template (rename classes, update manifest, implement methods)
+4. **Customize** the template (rename classes, implement methods)
 5. **Test your code** thoroughly using the provided test framework
-6. **Validate manifests**: Run `just validate-manifests`
-7. **Submit a Pull Request** with a clear description of your changes
+6. **Submit a Pull Request** with a clear description of your changes
 
 ### What You Can Contribute
 
@@ -128,29 +125,18 @@ We welcome contributions! This is an open-source project where community members
 
 - **Start from the template**: Copy `wayfinder_paths/templates/adapter/` as a starting point
 - Extend `BaseAdapter` from `wayfinder_paths/core/adapters/BaseAdapter.py`
-- Create a `manifest.yaml` (template at `wayfinder_paths/templates/adapter/manifest.yaml`) with:
-  - `entrypoint`: Full import path to your adapter class
-  - `capabilities`: List of capabilities your adapter provides
-  - `dependencies`: List of required client classes (e.g., `PoolClient`, `TokenClient`)
-- Implement methods that fulfill the declared capabilities
+- Implement your adapter methods
 - Add comprehensive tests in `test_adapter.py`
 - Include usage examples in `examples.json`
 - Document your adapter in `README.md`
-- Validate your manifest: `just validate-manifests`
 
 #### For Strategies
 
 - **Start from the template**: Use `just create-strategy "Strategy Name"` to create a new strategy with its own wallet, or copy `wayfinder_paths/templates/strategy/` manually
 - Extend `Strategy` from `wayfinder_paths/core/strategies/Strategy.py`
-- Create a `manifest.yaml` (template at `wayfinder_paths/templates/strategy/manifest.yaml`) with:
-  - `entrypoint`: Full import path to your strategy class
-  - `name`: Strategy directory name (used for wallet lookup)
-  - `permissions.policy`: Security policy for transaction permissions
-  - `adapters`: List of required adapters and their capabilities
 - Implement required methods: `deposit()`, `update()`, `status()`, `withdraw()`
 - Include test cases in `test_strategy.py`
 - Add example configurations in `examples.json`
-- Validate your manifest: `just validate-manifests`
 
 #### General Guidelines
 
@@ -186,10 +172,7 @@ cp -r wayfinder_paths/templates/strategy wayfinder_paths/strategies/my_strategy
 
 # 5. Customize the template (see template README.md files for details)
 
-# 6. Validate your manifest
-just validate-manifests
-
-# 7. Run tests
+# 6. Run tests
 poetry run pytest -k smoke -v
 
 # Or test your specific contribution
@@ -213,8 +196,8 @@ The platform uses a unified client system for all API interactions. Clients are
 
 ### Clients vs Adapters
 
-- **Clients**: Low-level, reusable service wrappers that talk to networks and external APIs. They handle auth, headers, retries, and response parsing, and expose generic capabilities (e.g., token info, tx building). Examples: `TokenClient`, `TransactionClient`, `WalletClient`.
-- **Adapters**: Strategy-facing integrations for a specific exchange/protocol. They compose one or more clients to implement a manifest of capabilities (e.g., `supply`, `borrow`, `place_order`). Adapters encapsulate protocol-specific semantics and raise `NotImplementedError` for unsupported ops.
+- **Clients**: Low-level, reusable service wrappers that talk to networks and external APIs. They handle auth, headers, retries, and response parsing, and expose generic capabilities (e.g., token info, tx building). Examples: `TokenClient`, `WalletClient`.
+- **Adapters**: Strategy-facing integrations for a specific exchange/protocol. They compose one or more clients to implement a set of capabilities (e.g., `supply`, `borrow`, `place_order`). Adapters encapsulate protocol-specific semantics and raise `NotImplementedError` for unsupported ops.
 
 Recommended usage:
 
@@ -224,168 +207,6 @@ Recommended usage:
 
 Data flow: `Strategy` → `Adapter` → `Client(s)` → network/API.
 
-### Manifests
-
-Every adapter and strategy requires a `manifest.yaml` file that declares its metadata, capabilities, and dependencies. Manifests are validated automatically in CI/CD and serve as the **single source of truth** for what each component can do.
-
-#### Adapter Manifests
-
-Adapter manifests declare the capabilities an adapter provides and the clients it depends on.
-
-**Template:** Copy `wayfinder_paths/templates/adapter/manifest.yaml` as a starting point.
-
-**Schema:**
-
-```yaml
-schema_version: "0.1"
-entrypoint: "adapters.my_adapter.adapter.MyAdapter"
-capabilities:
-  - "pool.read"
-  - "pool.analytics"
-dependencies:
-  - "PoolClient"
-  - "TokenClient"
-```
-
-**Fields:**
-
-- `schema_version`: Manifest schema version (currently `"0.1"`)
-- `entrypoint`: Full Python import path to the adapter class (required)
-- `capabilities`: List of abstract capabilities this adapter provides (required, non-empty)
-- `dependencies`: List of client class names from `core.clients` that this adapter requires (required, non-empty)
-
-**Example** (`wayfinder_paths/adapters/pool_adapter/manifest.yaml`):
-
-```yaml
-schema_version: "0.1"
-entrypoint: "adapters.pool_adapter.adapter.PoolAdapter"
-capabilities:
-  - "pool.read"
-  - "pool.analytics"
-  - "pool.discovery"
-  - "llama.data"
-  - "pool.reports"
-dependencies:
-  - "PoolClient"
-```
-
-#### Strategy Manifests
-
-Strategy manifests declare permissions and required adapters with their capabilities.
-
-**Template:** Copy `wayfinder_paths/templates/strategy/manifest.yaml` as a starting point.
-
-**Schema:**
-
-```yaml
-schema_version: "0.1"
-entrypoint: "strategies.my_strategy.strategy.MyStrategy"
-permissions:
-  policy: "(wallet.id == 'FORMAT_WALLET_ID') && (eth.tx.to == '0x...')"
-adapters:
-  - name: "POOL"
-    capabilities: ["pool.read", "pool.analytics"]
-  - name: "BRAP"
-    capabilities: ["swap.quote", "swap.execute"]
-```
-
-**Fields:**
-
-- `schema_version`: Manifest schema version (currently `"0.1"`)
-- `entrypoint`: Full Python import path to the strategy class (required)
-- `name`: Strategy directory name (optional, used for wallet lookup - defaults to directory name)
-- `permissions.policy`: Security policy string that defines transaction permissions (required, non-empty)
-- `adapters`: List of required adapters with their names and needed capabilities (required, non-empty)
-  - `name`: Adapter type identifier (e.g., "POOL", "BRAP")
-  - `capabilities`: List of capabilities required from this adapter
-
-**Example** (`wayfinder_paths/strategies/stablecoin_yield_strategy/manifest.yaml`):
-
-```yaml
-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"]
-```
-
-#### Manifest Validation
-
-Manifests are automatically validated to ensure:
-
-- Schema compliance (all required fields present, correct types)
-- Entrypoint classes exist and are importable
-- Dependencies are valid client classes
-- Permissions policies are non-empty
-
-**Validate locally:**
-
-```bash
-# Validate all manifests
-just validate-manifests
-
-# Or manually
-PYTHONPATH=wayfinder_paths poetry run python wayfinder_paths/scripts/validate_manifests.py
-```
-
-Validation runs automatically in CI/CD on every PR and push to main. All manifests must be valid before merging.
-
-**How Validation Works:**
-
-The `validate_manifests.py` script performs multi-stage validation:
-
-1. **Schema Validation** (via Pydantic models):
-   - Loads YAML file and validates against `AdapterManifest` or `StrategyManifest` schema
-   - Checks required fields, types, and basic constraints (e.g., capabilities cannot be empty)
-   - Validates entrypoint format (must be full import path like `"adapters.pool_adapter.adapter.PoolAdapter"`)
-
-2. **Entrypoint Verification**:
-   - **For Adapters**: Imports the entrypoint class and verifies it's a subclass of `BaseAdapter`
-   - **For Strategies**: Imports the entrypoint class and verifies it's a subclass of `Strategy`
-   - Uses Python's `__import__()` to dynamically import the module and class
-   - Catches import errors, missing classes, and type mismatches
-
-3. **Dependency Verification** (adapters only):
-   - Validates that all declared dependencies (e.g., `PoolClient`, `TokenClient`) exist in `core.clients`
-   - Attempts to import each dependency as `core.clients.{DepName}`
-
-4. **Permissions Validation** (strategies only):
-   - Validated by Pydantic: ensures `permissions.policy` exists and is non-empty
-   - Policy syntax is not parsed/validated (assumed to be valid at runtime)
-
-**Validation Flow:**
-
-```
-For each manifest file:
-  1. Load YAML → Parse with Pydantic (schema validation)
-  2. Import entrypoint class → Verify inheritance (entrypoint validation)
-  3. For adapters: Import dependencies → Verify they exist (dependency validation)
-  4. Collect all errors → Report results
-```
-
-The script automatically discovers all manifests by scanning:
-
-- `wayfinder_paths/adapters/*/manifest.yaml` for adapter manifests
-- `wayfinder_paths/strategies/*/manifest.yaml` for strategy manifests
-
-All errors are collected and reported at the end, with the script exiting with code 1 if any validation fails.
-
-#### Capabilities
-
-Capabilities are abstract operation identifiers (e.g., `"pool.read"`, `"swap.execute"`) declared in manifests. They represent what operations an adapter can perform, not specific method names. The manifest is the **single source of truth** for capabilities—they are not duplicated in code.
-
-When creating an adapter:
-
-1. Declare capabilities in your `manifest.yaml`
-2. Implement methods that fulfill those capabilities
-3. Capabilities are validated at manifest validation time (entrypoint must be importable)
-
 ### Configuration
 
 Configuration is split between:
@@ -415,14 +236,7 @@ strategy = StablecoinYieldStrategy(
 )
 ```
 
-**Option B: Set Environment Variable**
-
-```bash
-export WAYFINDER_API_KEY="sk_live_abc123..."
-# All clients will automatically discover and use this
-```
-
-**Option C: Add to config.json**
+**Option B: Add to config.json**
 
 ```json
 {
@@ -435,7 +249,7 @@ export WAYFINDER_API_KEY="sk_live_abc123..."
 }
 ```
 
-**Priority Order:** Constructor parameter > `config.json` (user.api_key or system.api_key) > `WAYFINDER_API_KEY` environment variable
+**Priority Order:** Constructor parameter > `config.json` (user.api_key or system.api_key)
 
 **Note:** API keys in `config.json` are loaded directly by `WayfinderClient` via `_load_config_credentials()`, not through the `UserConfig` or `SystemConfig` dataclasses. This allows flexible credential loading.
 
@@ -483,7 +297,7 @@ class MyAdapter(BaseAdapter):
         self.pool_client = PoolClient()
 
     async def connect(self) -> bool:
-        """No-op for read-only adapters, but kept for manifest compatibility."""
+        """No-op for read-only adapters, but kept for interface consistency."""
         return True
 
     async def get_pools(self, pool_ids: list[str]):
@@ -516,7 +330,7 @@ class MyStrategy(Strategy):
         super().__init__(api_key=api_key)  # Pass to base class for auto-discovery
         self.config = config or {}
         web3_service = DefaultWeb3Service(self.config)
-        # Adapters automatically discover API key from env var (set by Strategy.__init__)
+        # Adapters automatically discover API key from constructor or config.json
         balance_adapter = BalanceAdapter(self.config, web3_service=web3_service)
         self.register_adapters([balance_adapter])
         self.balance_adapter = balance_adapter
@@ -556,6 +370,54 @@ class MyStrategy(Strategy):
         }
 ```
 
+### Built-in Strategies
+
+The following strategies are available and can be run using the CLI:
+
+| Strategy | Description | Chain |
+|----------|-------------|-------|
+| `basis_trading_strategy` | Delta-neutral basis trading | - |
+| `hyperlend_stable_yield_strategy` | Stable yield on HyperLend | HyperEVM |
+| `moonwell_wsteth_loop_strategy` | Leveraged wstETH yield loop | Base |
+
+#### Running Strategies
+
+```bash
+# Check strategy status
+poetry run python wayfinder_paths/scripts/run_strategy.py \
+  --strategy moonwell_wsteth_loop_strategy \
+  --main-wallet-label main \
+  --strategy-wallet-label moonwell_wsteth_loop_strategy \
+  status
+
+# Deposit funds (USDC amount, optional ETH for gas)
+poetry run python wayfinder_paths/scripts/run_strategy.py \
+  --strategy moonwell_wsteth_loop_strategy \
+  --main-wallet-label main \
+  --strategy-wallet-label moonwell_wsteth_loop_strategy \
+  deposit --usdc 100 --eth 0.01
+
+# Run periodic update
+poetry run python wayfinder_paths/scripts/run_strategy.py \
+  --strategy moonwell_wsteth_loop_strategy \
+  --main-wallet-label main \
+  --strategy-wallet-label moonwell_wsteth_loop_strategy \
+  update
+
+# Withdraw funds (omit --amount for full withdrawal)
+poetry run python wayfinder_paths/scripts/run_strategy.py \
+  --strategy moonwell_wsteth_loop_strategy \
+  --main-wallet-label main \
+  --strategy-wallet-label moonwell_wsteth_loop_strategy \
+  withdraw --amount 50
+
+# Run in simulation mode (no real transactions)
+poetry run python wayfinder_paths/scripts/run_strategy.py \
+  --strategy moonwell_wsteth_loop_strategy \
+  --simulation \
+  status
+```
+
 ### Built-in adapters
 
 - **BALANCE (BalanceAdapter)**: wraps `WalletClient`/`TokenClient` to read wallet, token, and pool balances and now orchestrates transfers between the main/strategy wallets with ledger bookkeeping. Requires a `Web3Service` so it can share the same wallet provider as the strategy.
@@ -564,8 +426,9 @@ class MyStrategy(Strategy):
 - **LEDGER (LedgerAdapter)**: records deposits, withdrawals, custom operations, and cashflows via `LedgerClient`, and can read strategy transaction summaries.
 - **TOKEN (TokenAdapter)**: lightweight wrapper around `TokenClient` for token metadata, live price snapshots, and gas token lookups.
 - **HYPERLEND (HyperlendAdapter)**: connects to `HyperlendClient` for lending/supply caps inside the HyperLend strategy.
+- **MOONWELL (MoonwellAdapter)**: interfaces with Moonwell protocol on Base for lending, borrowing, collateral management, and WELL rewards.
 
-Each strategy manifest declares which adapters it needs and which capabilities it consumes. Adapters must implement the behavior promised in their manifest (or raise `NotImplementedError` if invoked outside the manifest contract).
+Strategies register the adapters they need in their `__init__` method. Adapters implement their specific capabilities and raise `NotImplementedError` for unsupported operations.
 
 ## 🧪 Testing