wayfinder-paths 0.1.19__py3-none-any.whl → 0.1.20__py3-none-any.whl

wayfinder_paths/__init__.py

@@ -1,5 +1,3 @@
-"""Wayfinder Path - Trading strategies and adapters for automated strategy management"""
-
 __version__ = "0.1.0"
 
 # Re-export commonly used items for convenience

wayfinder_paths/adapters/balance_adapter/README.md

@@ -1,91 +1,105 @@
 # Balance Adapter
 
-Adapter that exposes wallet, token, and pool balances backed by `WalletClient`/`TokenClient` and now orchestrates transfers between the configured main/strategy wallets (with ledger bookkeeping).
+Adapter for wallet and token balances with cross-wallet transfer capabilities.
 
-- Entrypoint: `adapters.balance_adapter.adapter.BalanceAdapter`
-- Tests: `test_adapter.py`
+- **Type**: `BALANCE`
+- **Module**: `wayfinder_paths.adapters.balance_adapter.adapter.BalanceAdapter`
 
-## Capabilities
+## Overview
 
-The adapter provides both wallet read and wallet transfer capabilities. Ledger recording + wallet selection now live inside the adapter.
+The BalanceAdapter provides:
+- Token balance queries for any wallet
+- Cross-wallet transfers between main and strategy wallets
+- Automatic ledger recording for deposits/withdrawals
 
-## Construction
+## Usage
 
 ```python
 from wayfinder_paths.adapters.balance_adapter.adapter import BalanceAdapter
 
+adapter = BalanceAdapter(
+    config=config,
+    main_wallet_signing_callback=main_signing_cb,
+    strategy_wallet_signing_callback=strategy_signing_cb,
+)
 ```
 
-## API surface
+## Methods
 
-### `get_balance(token_id: str, wallet_address: str)`
+### get_balance
 
-Returns the raw balance (as an integer) for a specific token on a wallet.
+Get token balance for a wallet.
 
 ```python
-success, balance = await balance.get_balance(
+success, balance = await adapter.get_balance(
     token_id="usd-coin-base",
-    wallet_address=config["main_wallet"]["address"],
+    wallet_address="0x...",
+    chain_id=8453,  # optional, auto-resolved from token
 )
 ```
 
-### `get_pool_balance(pool_address: str, chain_id: int, user_address: str)`
+**Returns**: `(bool, int)` - success flag and raw balance (in token units)
+
+### move_from_main_wallet_to_strategy_wallet
 
-Fetches the amount supplied to a specific pool, using the `/wallets/pool-balance` endpoint.
+Transfer tokens from main wallet to strategy wallet with ledger recording.
 
 ```python
-success, amount = await balance.get_pool_balance(
-    pool_address="0xPool",
-    chain_id=8453,
-    user_address=config["strategy_wallet"]["address"],
+success, tx_hash = await adapter.move_from_main_wallet_to_strategy_wallet(
+    token_id="usd-coin-base",
+    amount=100.0,  # human-readable amount
+    strategy_name="my_strategy",
+    skip_ledger=False,
 )
 ```
 
-### `move_from_main_wallet_to_strategy_wallet(token_id: str, amount: float, strategy_name="unknown", skip_ledger=False)`
+### move_from_strategy_wallet_to_main_wallet
 
-Sends the specified token from the configured `main_wallet` to the strategy wallet, records the ledger deposit (unless `skip_ledger=True`), and returns the `(success, tx_result)` tuple from the underlying send helper.
+Transfer tokens from strategy wallet back to main wallet.
 
 ```python
-success, tx = await balance.move_from_main_wallet_to_strategy_wallet(
+success, tx_hash = await adapter.move_from_strategy_wallet_to_main_wallet(
     token_id="usd-coin-base",
-    amount=1.5,
-    strategy_name="MyStrategy",
+    amount=50.0,
+    strategy_name="my_strategy",
+    skip_ledger=False,
 )
 ```
 
-### `move_from_strategy_wallet_to_main_wallet(token_id: str, amount: float, strategy_name="unknown", skip_ledger=False)`
+### send_to_address
 
-Mirrors the previous method but withdraws from the strategy wallet back to the main wallet while recording a ledger withdrawal entry.
+Send tokens to an arbitrary address (e.g., bridge contract).
 
 ```python
-await balance.move_from_strategy_wallet_to_main_wallet(
+success, tx_hash = await adapter.send_to_address(
     token_id="usd-coin-base",
-    amount=0.75,
-    strategy_name="MyStrategy",
+    amount=1000000,  # raw amount
+    from_wallet=config["strategy_wallet"],
+    to_address="0xBridgeContract...",
+    signing_callback=strategy_signing_cb,
 )
 ```
 
-All methods return `(success: bool, payload: Any)` tuples. On failure the payload is an error string.
+## Configuration
 
-## Usage inside strategies
+The adapter requires wallet configuration in `config`:
 
 ```python
-class MyStrategy(Strategy):
-    def __init__(self, config):
-        super().__init__()
-        balance_adapter = BalanceAdapter(config)
-        self.register_adapters([balance_adapter])
-        self.balance_adapter = balance_adapter
-
-    async def _status(self):
-        success, pool_balance = await self.balance_adapter.get_pool_balance(
-            pool_address=self.current_pool["address"],
-            chain_id=self.current_pool["chain"]["id"],
-            user_address=self.config["strategy_wallet"]["address"],
-        )
-        return {"portfolio_value": float(pool_balance or 0), ...}
+config = {
+    "main_wallet": {"address": "0x..."},
+    "strategy_wallet": {"address": "0x..."},
+}
 ```
 
-## Error handling and health checks
+## Dependencies
 
-Any exception raised by the underlying `WalletClient`/`TokenClient` is caught and emitted as a `(False, "message")` tuple. The inherited `health_check()` method reports adapter status plus dependency status, making it safe to call from `Strategy.health_check`.
+- `WalletClient` - For balance queries
+- `TokenClient` - For token metadata
+- `LedgerAdapter` - For transaction recording
+- `TokenAdapter` - For price lookups
+
+## Testing
+
+```bash
+poetry run pytest wayfinder_paths/adapters/balance_adapter/ -v
+```

wayfinder_paths/adapters/balance_adapter/adapter.py

@@ -16,12 +16,10 @@ class BalanceAdapter(BaseAdapter):
     def __init__(
         self,
         config: dict[str, Any],
-        simulation: bool = False,
         main_wallet_signing_callback=None,
         strategy_wallet_signing_callback=None,
     ):
         super().__init__("balance", config)
-        self.simulation = simulation
         self.main_wallet_signing_callback = main_wallet_signing_callback
         self.strategy_wallet_signing_callback = strategy_wallet_signing_callback
         self.wallet_client = WalletClient()
@@ -30,7 +28,6 @@ class BalanceAdapter(BaseAdapter):
         self.ledger_adapter = LedgerAdapter()
 
     def _parse_balance(self, raw: Any) -> int:
-        """Parse balance value to integer, handling various formats."""
         if raw is None:
             return 0
         try:
@@ -49,12 +46,6 @@ class BalanceAdapter(BaseAdapter):
         wallet_address: str,
         chain_id: int | None = None,
     ) -> tuple[bool, str | int]:
-        """Get token or pool balance for a wallet.
-
-        query: token_id/address string or a dict with a "token_id" key.
-        token_id: alternative to query for convenience.
-        """
-        # Support both query= and token_id= for caller convenience
         effective_query = query if query is not None else token_id
         resolved = (
             effective_query
@@ -78,7 +69,6 @@ class BalanceAdapter(BaseAdapter):
                 query=resolved,
                 chain_id=int(chain_id),
             )
-            # Use _parse_balance for consistent parsing (handles balance_raw or balance)
             raw = (
                 data.get("balance_raw") or data.get("balance")
                 if isinstance(data, dict)
@@ -95,7 +85,6 @@ class BalanceAdapter(BaseAdapter):
         strategy_name: str = "unknown",
         skip_ledger: bool = False,
     ) -> tuple[bool, Any]:
-        """Move funds from the configured main wallet into the strategy wallet."""
         return await self._move_between_wallets(
             token_id=token_id,
             amount=amount,
@@ -114,7 +103,6 @@ class BalanceAdapter(BaseAdapter):
         strategy_name: str = "unknown",
         skip_ledger: bool = False,
     ) -> tuple[bool, Any]:
-        """Move funds from the strategy wallet back into the main wallet."""
         return await self._move_between_wallets(
             token_id=token_id,
             amount=amount,
@@ -135,7 +123,6 @@ class BalanceAdapter(BaseAdapter):
         signing_callback=None,
         skip_ledger: bool = True,
     ) -> tuple[bool, Any]:
-        """Send tokens from a wallet to an arbitrary address (e.g., bridge contract)."""
         from_address = self._wallet_address(from_wallet)
         if not from_address:
             return False, "from_wallet missing or invalid"
@@ -161,9 +148,6 @@ class BalanceAdapter(BaseAdapter):
             amount=int(amount),
         )
 
-        if self.simulation:
-            return True, {"simulation": tx}
-
         if not signing_callback:
             return False, "signing_callback is required"
 
@@ -220,11 +204,6 @@ class BalanceAdapter(BaseAdapter):
         return broadcast_result
 
     async def _send_tx(self, tx: dict[str, Any], from_address: str) -> tuple[bool, Any]:
-        """Send transaction with simulation check, using appropriate signing callback."""
-        if self.simulation:
-            return True, {"simulation": tx}
-
-        # Choose callback based on which wallet is sending
         main_wallet = self.config.get("main_wallet") or {}
         main_addr = main_wallet.get("address", "").lower()
 

wayfinder_paths/adapters/balance_adapter/test_adapter.py

@@ -6,23 +6,18 @@ from wayfinder_paths.adapters.balance_adapter.adapter import BalanceAdapter
 
 
 class TestBalanceAdapter:
-    """Test cases for BalanceAdapter"""
-
     @pytest.fixture
     def mock_wallet_client(self):
-        """Mock WalletClient for testing"""
         mock_client = AsyncMock()
         return mock_client
 
     @pytest.fixture
     def mock_token_client(self):
-        """Mock TokenClient for testing"""
         mock_client = AsyncMock()
         return mock_client
 
     @pytest.fixture
     def adapter(self, mock_wallet_client, mock_token_client):
-        """Create a BalanceAdapter instance with mocked clients for testing"""
         with (
             patch(
                 "wayfinder_paths.adapters.balance_adapter.adapter.WalletClient",
@@ -37,26 +32,22 @@ class TestBalanceAdapter:
 
     @pytest.mark.asyncio
     async def test_health_check(self, adapter):
-        """Test adapter health check"""
         health = await adapter.health_check()
         assert isinstance(health, dict)
         assert health.get("status") in {"healthy", "unhealthy", "error"}
 
     @pytest.mark.asyncio
     async def test_connect(self, adapter):
-        """Test adapter connection"""
         ok = await adapter.connect()
         assert isinstance(ok, bool)
 
     def test_adapter_type(self, adapter):
-        """Test adapter has adapter_type"""
         assert adapter.adapter_type == "BALANCE"
 
     @pytest.mark.asyncio
     async def test_get_balance_with_query_string(
         self, adapter, mock_token_client, mock_wallet_client
     ):
-        """Test get_balance with query as string (auto-resolves chain_id)."""
         mock_token_client.get_token_details = AsyncMock(
             return_value={
                 "token_id": "usd-coin-base",
@@ -86,7 +77,6 @@ class TestBalanceAdapter:
     async def test_get_balance_with_query_dict(
         self, adapter, mock_token_client, mock_wallet_client
     ):
-        """get_balance accepts query= as dict with token_id key."""
         mock_token_client.get_token_details = AsyncMock(
             return_value={
                 "token_id": "wsteth-base",
@@ -113,7 +103,6 @@ class TestBalanceAdapter:
 
     @pytest.mark.asyncio
     async def test_get_balance_missing_query(self, adapter):
-        """get_balance returns error when query is empty or missing token_id."""
         success, result = await adapter.get_balance(query={}, wallet_address="0xabc")
         assert success is False
         assert "missing query" in str(result)
@@ -122,7 +111,6 @@ class TestBalanceAdapter:
     async def test_get_balance_with_pool_address(
         self, adapter, mock_token_client, mock_wallet_client
     ):
-        """Test get_balance with pool address (explicit chain_id)"""
         mock_wallet_client.get_token_balance_for_address = AsyncMock(
             return_value={"balance": 5000000}
         )
@@ -145,7 +133,6 @@ class TestBalanceAdapter:
 
     @pytest.mark.asyncio
     async def test_get_balance_token_not_found(self, adapter, mock_token_client):
-        """Test get_balance when token is not found"""
         mock_token_client.get_token_details = AsyncMock(return_value=None)
 
         success, error = await adapter.get_balance(
@@ -158,7 +145,6 @@ class TestBalanceAdapter:
 
     @pytest.mark.asyncio
     async def test_get_balance_missing_chain_id(self, adapter, mock_token_client):
-        """Test get_balance when chain_id cannot be resolved"""
         mock_token_client.get_token_details = AsyncMock(
             return_value={
                 "token_id": "token-without-chain",

wayfinder_paths/adapters/brap_adapter/README.md

@@ -1,247 +1,124 @@
 # BRAP Adapter
 
-A Wayfinder adapter that provides high-level operations for cross-chain swaps and quotes via the BRAP (Bridge/Router/Adapter Protocol). This adapter wraps the `BRAPClient` to offer strategy-friendly methods for getting quotes, comparing routes, and executing cross-chain transactions.
+Adapter for cross-chain swaps and bridges via the BRAP (Bridge/Router/Adapter Protocol).
 
-## Capabilities
+- **Type**: `BRAP`
+- **Module**: `wayfinder_paths.adapters.brap_adapter.adapter.BRAPAdapter`
 
-- `swap.quote`: Get quotes for cross-chain swap operations
-- `swap.execute`: Execute cross-chain swaps
-- `bridge.quote`: Get quotes for bridge operations
-- `bridge.execute`: Execute bridge operations
-- `route.optimize`: Compare and optimize routes
-- `fee.calculate`: Calculate fees and costs
+## Overview
 
-## Configuration
-
-The BRAPClient will automatically:
-
-- Use the WAYFINDER_API_URL from settings
-- Handle authentication via config.json
-- Manage token refresh and retry logic
+The BRAPAdapter provides:
+- Cross-chain swap quotes
+- Bridge operation quotes
+- Route comparison and optimization
+- Fee calculations
+- Swap execution
 
 ## Usage
 
-### Initialize the Adapter
-
 ```python
 from wayfinder_paths.adapters.brap_adapter.adapter import BRAPAdapter
 
 adapter = BRAPAdapter()
 ```
 
-### Get Swap Quote
+## Methods
 
-```python
-success, data = await adapter.get_swap_quote(
-    from_token_address="0xA0b86a33E6441c8C06DdD4D4c4c4c4c4c4c4c4c4c",
-    to_token_address="0xB1c97a44F7552d9Dd5e5e5e5e5e5e5e5e5e5e5e5e5e",
-    from_chain_id=8453,  # Base
-    to_chain_id=1,       # Ethereum
-    from_address="0x1234567890123456789012345678901234567890",
-    to_address="0x1234567890123456789012345678901234567890",
-    amount="1000000000000000000",  # 1 token (18 decimals)
-    slippage=0.01  # 1% slippage
-)
-if success:
-    quotes = data.get("quotes", {})
-    best_quote = quotes.get("best_quote", {})
-    print(f"Output amount: {best_quote.get('output_amount')}")
-    print(f"Total fee: {best_quote.get('total_fee')}")
-else:
-    print(f"Error: {data}")
-```
+### get_swap_quote
 
-### Get Best Quote
+Get quotes for a cross-chain swap.
 
 ```python
-success, data = await adapter.get_best_quote(
-    from_token_address="0xA0b86a33E6441c8C06DdD4D4c4c4c4c4c4c4c4c4c",
-    to_token_address="0xB1c97a44F7552d9Dd5e5e5e5e5e5e5e5e5e5e5e5e5e",
+success, data = await adapter.get_swap_quote(
+    from_token_address="0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913",
+    to_token_address="0x...",
     from_chain_id=8453,
     to_chain_id=1,
-    from_address="0x1234567890123456789012345678901234567890",
-    to_address="0x1234567890123456789012345678901234567890",
-    amount="1000000000000000000"
+    from_address="0x...",
+    to_address="0x...",
+    amount="1000000000",  # Raw amount
+    slippage=0.01,        # 1%
 )
 if success:
-    print(f"Best output: {data.get('output_amount')}")
-    print(f"Gas fee: {data.get('gas_fee')}")
-    print(f"Bridge fee: {data.get('bridge_fee')}")
-else:
-    print(f"Error: {data}")
+    best_quote = data.get("quotes", {}).get("best_quote", {})
+    print(f"Output: {best_quote.get('output_amount')}")
 ```
 
-### Calculate Swap Fees
+### get_best_quote
 
-```python
-success, data = await adapter.calculate_swap_fees(
-    from_token_address="0xA0b86a33E6441c8C06DdD4D4c4c4c4c4c4c4c4c4c",
-    to_token_address="0xB1c97a44F7552d9Dd5e5e5e5e5e5e5e5e5e5e5e5e5e",
-    from_chain_id=8453,
-    to_chain_id=1,
-    amount="1000000000000000000",
-    slippage=0.01
-)
-if success:
-    print(f"Input amount: {data.get('input_amount')}")
-    print(f"Output amount: {data.get('output_amount')}")
-    print(f"Gas fee: {data.get('gas_fee')}")
-    print(f"Bridge fee: {data.get('bridge_fee')}")
-    print(f"Protocol fee: {data.get('protocol_fee')}")
-    print(f"Total fee: {data.get('total_fee')}")
-    print(f"Price impact: {data.get('price_impact')}")
-else:
-    print(f"Error: {data}")
-```
-
-### Compare Routes
+Get the best quote for a swap.
 
 ```python
-success, data = await adapter.compare_routes(
-    from_token_address="0xA0b86a33E6441c8C06DdD4D4c4c4c4c4c4c4c4c4c",
-    to_token_address="0xB1c97a44F7552d9Dd5e5e5e5e5e5e5e5e5e5e5e5e5e",
+success, data = await adapter.get_best_quote(
+    from_token_address="0x...",
+    to_token_address="0x...",
     from_chain_id=8453,
     to_chain_id=1,
-    amount="1000000000000000000"
-)
-if success:
-    print(f"Total routes available: {data.get('total_routes')}")
-    print(f"Best route output: {data.get('best_route', {}).get('output_amount')}")
-
-    for i, route in enumerate(data.get('all_routes', [])):
-        print(f"Route {i+1}: Output {route.get('output_amount')}, Fee {route.get('total_fee')}")
-else:
-    print(f"Error: {data}")
-```
-
-### Estimate Gas Costs
-
-```python
-success, data = await adapter.estimate_gas_cost(
-    from_chain_id=8453,  # Base
-    to_chain_id=1,       # Ethereum
-    operation_type="swap"
+    from_address="0x...",
+    to_address="0x...",
+    amount="1000000000",
 )
-if success:
-    print(f"From chain: {data.get('from_chain')}")
-    print(f"To chain: {data.get('to_chain')}")
-    print(f"From gas estimate: {data.get('from_gas_estimate')}")
-    print(f"To gas estimate: {data.get('to_gas_estimate')}")
-    print(f"Total operations: {data.get('total_operations')}")
-else:
-    print(f"Error: {data}")
 ```
 
-### Validate Swap Parameters
-
-```python
-success, data = await adapter.validate_swap_parameters(
-    from_token_address="0xA0b86a33E6441c8C06DdD4D4c4c4c4c4c4c4c4c4c",
-    to_token_address="0xB1c97a44F7552d9Dd5e5e5e5e5e5e5e5e5e5e5e5e5e",
-    from_chain_id=8453,
-    to_chain_id=1,
-    amount="1000000000000000000"
-)
-if success:
-    if data.get("valid"):
-        print("Parameters are valid")
-        print(f"Estimated output: {data.get('estimated_output')}")
-    else:
-        print("Parameters are invalid:")
-        for error in data.get("errors", []):
-            print(f"  - {error}")
-else:
-    print(f"Error: {data}")
-```
+### compare_routes
 
-### Get Bridge Quote
+Compare available routes for a swap.
 
 ```python
-# Bridge operations use the same interface as swaps
-success, data = await adapter.get_bridge_quote(
-    from_token_address="0xA0b86a33E6441c8C06DdD4D4c4c4c4c4c4c4c4c4c",
-    to_token_address="0xB1c97a44F7552d9Dd5e5e5e5e5e5e5e5e5e5e5e5e5e",
+success, data = await adapter.compare_routes(
+    from_token_address="0x...",
+    to_token_address="0x...",
     from_chain_id=8453,
     to_chain_id=1,
-    amount="1000000000000000000",
-    slippage=0.01
+    amount="1000000000",
 )
 if success:
-    print(f"Bridge quote received: {data.get('quotes', {}).get('best_quote', {}).get('output_amount')}")
-else:
-    print(f"Error: {data}")
+    print(f"Total routes: {data.get('total_routes')}")
+    for route in data.get("all_routes", []):
+        print(f"Output: {route.get('output_amount')}, Fee: {route.get('total_fee')}")
 ```
 
-## Advanced Usage
+### calculate_swap_fees
 
-### Route Optimization
+Calculate fees for a swap operation.
 
 ```python
-# Compare multiple routes to find the best option
-success, data = await adapter.compare_routes(
-    from_token_address="0xA0b86a33E6441c8C06DdD4D4c4c4c4c4c4c4c4c4c",
-    to_token_address="0xB1c97a44F7552d9Dd5e5e5e5e5e5e5e5e5e5e5e5e5e",
+success, data = await adapter.calculate_swap_fees(
+    from_token_address="0x...",
+    to_token_address="0x...",
     from_chain_id=8453,
     to_chain_id=1,
-    amount="1000000000000000000"
+    amount="1000000000",
+    slippage=0.01,
 )
-
 if success:
-    analysis = data.get("route_analysis", {})
-    highest_output = analysis.get("highest_output")
-    lowest_fees = analysis.get("lowest_fees")
-    fastest = analysis.get("fastest")
-
-    print(f"Highest output route: {highest_output.get('output_amount')}")
-    print(f"Lowest fees route: {lowest_fees.get('total_fee')}")
-    print(f"Fastest route: {fastest.get('estimated_time')} seconds")
+    print(f"Gas fee: {data.get('gas_fee')}")
+    print(f"Bridge fee: {data.get('bridge_fee')}")
+    print(f"Total fee: {data.get('total_fee')}")
 ```
 
-### Fee Analysis
+### validate_swap_parameters
+
+Validate swap parameters before execution.
 
 ```python
-# Analyze fees for a swap operation
-success, data = await adapter.calculate_swap_fees(
-    from_token_address="0xA0b86a33E6441c8C06DdD4D4c4c4c4c4c4c4c4c4c",
-    to_token_address="0xB1c97a44F7552d9Dd5e5e5e5e5e5e5e5e5e5e5e5e5e",
+success, data = await adapter.validate_swap_parameters(
+    from_token_address="0x...",
+    to_token_address="0x...",
     from_chain_id=8453,
     to_chain_id=1,
-    amount="1000000000000000000"
+    amount="1000000000",
 )
-
-if success:
-    input_amount = int(data.get("input_amount", 0))
-    output_amount = int(data.get("output_amount", 0))
-    total_fee = int(data.get("total_fee", 0))
-
-    # Calculate effective rate
-    effective_rate = (input_amount - output_amount) / input_amount
-    print(f"Effective rate: {effective_rate:.4f} ({effective_rate * 100:.2f}%)")
-    print(f"Total fees: {total_fee / 1e18:.6f} tokens")
+if success and data.get("valid"):
+    print("Parameters are valid")
 ```
 
-## API Endpoints
-
-The adapter uses the following Wayfinder API endpoints:
-
-- `POST /api/v1/public/quotes/` - Get swap/bridge quotes
-
-## Error Handling
-
-All methods return a tuple of `(success: bool, data: Any)` where:
+## Dependencies
 
-- `success` is `True` if the operation succeeded
-- `data` contains the response data on success or error message on failure
+- `BRAPClient` - Low-level API client
 
 ## Testing
 
-Run the adapter tests:
-
 ```bash
-pytest wayfinder_paths/adapters/brap_adapter/test_adapter.py -v
+poetry run pytest wayfinder_paths/adapters/brap_adapter/ -v
 ```
-
-## Dependencies
-
-- `BRAPClient` - Low-level API client for BRAP operations
-- `BaseAdapter` - Base adapter class with common functionality

wayfinder_paths/adapters/brap_adapter/__init__.py

@@ -1,7 +1,3 @@
-"""
-BRAP Adapter Package
-"""
-
 from .adapter import BRAPAdapter
 
 __all__ = ["BRAPAdapter"]