wayfinder-paths 0.1.7__py3-none-any.whl

wayfinder_paths/core/clients/SimulationClient.py

@@ -0,0 +1,192 @@
+"""
+Simulation Client
+Handles blockchain transaction simulations via Gorlami/Tenderly
+"""
+
+from __future__ import annotations
+
+import time
+from typing import NotRequired, Required, TypedDict
+
+from loguru import logger
+
+from wayfinder_paths.core.clients.WayfinderClient import WayfinderClient
+
+
+class SimulationResult(TypedDict):
+    """Simulation result structure"""
+
+    success: Required[bool]
+    gas_used: NotRequired[str | None]
+    gas_price: NotRequired[str | None]
+    balances: NotRequired[dict[str, str]]
+    error: NotRequired[str | None]
+
+
+class SimulationClient(WayfinderClient):
+    """Client for blockchain transaction simulations"""
+
+    def __init__(self, api_key: str | None = None):
+        super().__init__(api_key=api_key)
+
+    async def simulate_send(
+        self,
+        from_address: str,
+        to_address: str,
+        token_address: str,
+        amount: str,
+        chain_id: int,
+        initial_balances: dict[str, str],
+    ) -> SimulationResult:
+        """
+        Simulate sending native ETH or ERC20 tokens.
+
+        Args:
+            from_address: Source wallet address
+            to_address: Destination wallet address
+            token_address: Token contract address (use 0x0 for native ETH)
+            amount: Amount to send
+            chain_id: Blockchain chain ID
+            initial_balances: Initial token balances for simulation
+
+        Returns:
+            Simulation result data
+        """
+        logger.info(
+            f"Simulating send: {amount} from {from_address} to {to_address} (chain {chain_id})"
+        )
+        start_time = time.time()
+
+        url = f"{self.api_base_url}public/simulate/send/"
+
+        payload = {
+            "from_address": from_address,
+            "to_address": to_address,
+            "token_address": token_address,
+            "amount": amount,
+            "chain_id": chain_id,
+            "initial_balances": initial_balances,
+        }
+
+        try:
+            response = await self._request("POST", url, json=payload, headers={})
+            response.raise_for_status()
+            data = response.json()
+            elapsed = time.time() - start_time
+            logger.info(f"Simulation request completed successfully in {elapsed:.2f}s")
+            return data.get("data", data)
+        except Exception as e:
+            elapsed = time.time() - start_time
+            logger.error(f"Simulation request failed after {elapsed:.2f}s: {e}")
+            raise
+
+    async def simulate_approve(
+        self,
+        from_address: str,
+        to_address: str,
+        token_address: str,
+        amount: str,
+        chain_id: int,
+        initial_balances: dict[str, str],
+        clear_approval_first: bool = False,
+    ) -> SimulationResult:
+        """
+        Simulate ERC20 token approval.
+
+        Args:
+            from_address: Address approving the tokens
+            to_address: Address being approved to spend tokens
+            token_address: ERC20 token contract address
+            amount: Amount to approve
+            chain_id: Blockchain chain ID
+            initial_balances: Initial token balances for simulation
+            clear_approval_first: Whether to clear existing approval before setting new one
+
+        Returns:
+            Simulation result data
+        """
+        logger.info(
+            f"Simulating approval: {amount} from {from_address} to {to_address} (chain {chain_id})"
+        )
+        start_time = time.time()
+
+        url = f"{self.api_base_url}public/simulate/approve/"
+
+        payload = {
+            "from_address": from_address,
+            "to_address": to_address,
+            "token_address": token_address,
+            "amount": amount,
+            "chain_id": chain_id,
+            "initial_balances": initial_balances,
+            "clear_approval_first": clear_approval_first,
+        }
+
+        try:
+            response = await self._request("POST", url, json=payload, headers={})
+            response.raise_for_status()
+            data = response.json()
+            elapsed = time.time() - start_time
+            logger.info(f"Simulation request completed successfully in {elapsed:.2f}s")
+            return data.get("data", data)
+        except Exception as e:
+            elapsed = time.time() - start_time
+            logger.error(f"Simulation request failed after {elapsed:.2f}s: {e}")
+            raise
+
+    async def simulate_swap(
+        self,
+        from_token_address: str,
+        to_token_address: str,
+        from_chain_id: int,
+        to_chain_id: int,
+        amount: str,
+        from_address: str,
+        slippage: float,
+        initial_balances: dict[str, str],
+    ) -> SimulationResult:
+        """
+        Simulate token swap operation.
+
+        Args:
+            from_token_address: Source token contract address
+            to_token_address: Destination token contract address
+            from_chain_id: Source chain ID
+            to_chain_id: Destination chain ID
+            amount: Amount to swap
+            from_address: Wallet address initiating swap
+            slippage: Maximum slippage tolerance
+            initial_balances: Initial token balances for simulation
+
+        Returns:
+            Simulation result data
+        """
+        logger.info(
+            f"Simulating swap: {from_token_address} -> {to_token_address} (chain {from_chain_id} -> {to_chain_id})"
+        )
+        start_time = time.time()
+
+        url = f"{self.api_base_url}public/simulate/swap/"
+
+        payload = {
+            "from_token_address": from_token_address,
+            "to_token_address": to_token_address,
+            "from_chain_id": from_chain_id,
+            "to_chain_id": to_chain_id,
+            "amount": amount,
+            "from_address": from_address,
+            "slippage": slippage,
+            "initial_balances": initial_balances,
+        }
+
+        try:
+            response = await self._request("POST", url, json=payload, headers={})
+            response.raise_for_status()
+            data = response.json()
+            elapsed = time.time() - start_time
+            logger.info(f"Simulation request completed successfully in {elapsed:.2f}s")
+            return data.get("data", data)
+        except Exception as e:
+            elapsed = time.time() - start_time
+            logger.error(f"Simulation request failed after {elapsed:.2f}s: {e}")
+            raise

wayfinder_paths/core/clients/TokenClient.py

@@ -0,0 +1,89 @@
+"""
+Token Adapter
+Handles token information, prices, and parsing
+"""
+
+from __future__ import annotations
+
+from typing import NotRequired, Required, TypedDict
+
+from wayfinder_paths.core.clients.AuthClient import AuthClient
+from wayfinder_paths.core.clients.WayfinderClient import WayfinderClient
+from wayfinder_paths.core.settings import settings
+
+
+class TokenDetails(TypedDict):
+    """Token details response structure"""
+
+    id: Required[str]
+    address: Required[str]
+    symbol: Required[str]
+    name: Required[str]
+    decimals: Required[int]
+    chain_id: Required[int]
+    chain_code: Required[str]
+    price_usd: NotRequired[float]
+    price: NotRequired[float]
+    image_url: NotRequired[str | None]
+    coingecko_id: NotRequired[str | None]
+
+
+class GasToken(TypedDict):
+    """Gas token response structure"""
+
+    id: Required[str]
+    address: Required[str]
+    symbol: Required[str]
+    name: Required[str]
+    decimals: Required[int]
+    chain_id: Required[int]
+    chain_code: Required[str]
+    price_usd: NotRequired[float]
+
+
+class TokenClient(WayfinderClient):
+    """Adapter for token-related operations"""
+
+    def __init__(self, api_key: str | None = None):
+        super().__init__(api_key=api_key)
+        self.api_base_url = f"{self.api_base_url}/tokens"
+        self._auth_client: AuthClient | None = AuthClient(api_key=api_key)
+
+    # ============== Public (No-Auth) Endpoints ==============
+
+    async def get_token_details(
+        self, token_id: str, force_refresh: bool = False
+    ) -> TokenDetails:
+        """
+        Get token data including price from the token-details endpoint
+
+        Args:
+            token_id: Token identifier or address
+
+        Returns:
+            Full token data including price information
+        """
+        url = f"{settings.WAYFINDER_API_URL}/public/tokens/detail/"
+        params = {
+            "query": token_id,
+            "get_chart": "false",
+            "force_refresh": str(force_refresh),
+        }
+        # Public endpoint: do not pass auth headers
+        response = await self._request("GET", url, params=params, headers={})
+        response.raise_for_status()
+        data = response.json()
+        return data.get("data", data)
+
+    async def get_gas_token(self, chain_code: str) -> GasToken:
+        """
+        Fetch the native gas token for a given chain code via public endpoint.
+        Example: GET /api/v1/public/tokens/gas/?chain_code=base
+        """
+        url = f"{settings.WAYFINDER_API_URL}/public/tokens/gas/"
+        params = {"chain_code": chain_code}
+        # Public endpoint: do not pass auth headers
+        response = await self._request("GET", url, params=params, headers={})
+        response.raise_for_status()
+        data = response.json()
+        return data.get("data", data)

wayfinder_paths/core/clients/TransactionClient.py

@@ -0,0 +1,63 @@
+"""
+Transaction Client
+Handles transaction building, gas estimation, and monitoring
+"""
+
+from __future__ import annotations
+
+from typing import NotRequired, Required, TypedDict
+
+from wayfinder_paths.core.clients.AuthClient import AuthClient
+from wayfinder_paths.core.clients.WayfinderClient import WayfinderClient
+from wayfinder_paths.core.settings import settings
+
+
+class TransactionPayload(TypedDict):
+    """Transaction payload structure"""
+
+    from_address: Required[str]
+    to_address: Required[str]
+    token_address: Required[str]
+    amount: Required[str]
+    chain_id: Required[int]
+    data: NotRequired[str | None]
+    value: NotRequired[str | None]
+    gas_limit: NotRequired[str | None]
+    gas_price: NotRequired[str | None]
+
+
+class TransactionClient(WayfinderClient):
+    """Client for transaction operations"""
+
+    def __init__(self, api_key: str | None = None):
+        super().__init__(api_key=api_key)
+        self.api_base_url = f"{self.api_base_url}/transactions"
+        self._auth_client: AuthClient | None = AuthClient(api_key=api_key)
+
+    # ============== Protected (Auth Required) Endpoints ==============
+
+    async def build_send(
+        self,
+        from_address: str,
+        to_address: str,
+        token_address: str,
+        amount: float,
+        chain_id: int,
+    ) -> TransactionPayload:
+        """
+        Build a send transaction payload for EVM tokens/native transfers.
+
+        GET /api/v1/public/transactions/build-send/?from_address=...&to_address=...&token_address=...&amount=...&chain_id=...
+        """
+        url = f"{settings.WAYFINDER_API_URL}/public/transactions/build-send/"
+        params = {
+            "from_address": from_address,
+            "to_address": to_address,
+            "token_address": token_address,
+            "amount": str(amount),
+            "chain_id": str(chain_id),
+        }
+        response = await self._authed_request("GET", url, params=params)
+        response.raise_for_status()
+        data = response.json()
+        return data.get("data", data)

wayfinder_paths/core/clients/WalletClient.py

@@ -0,0 +1,94 @@
+"""
+Wallet Client
+Fetches wallet-related data such as aggregated balances for the authenticated user.
+"""
+
+from __future__ import annotations
+
+from typing import NotRequired, Required, TypedDict
+
+from wayfinder_paths.core.clients.AuthClient import AuthClient
+from wayfinder_paths.core.clients.WayfinderClient import WayfinderClient
+from wayfinder_paths.core.settings import settings
+
+
+class TokenBalance(TypedDict):
+    """Token balance response structure"""
+
+    token_id: Required[str]
+    wallet_address: Required[str]
+    balance: Required[str]
+    balance_human: NotRequired[float | None]
+    usd_value: NotRequired[float | None]
+
+
+class PoolBalance(TypedDict):
+    """Pool balance response structure"""
+
+    pool_address: Required[str]
+    chain_id: Required[int]
+    user_address: Required[str]
+    balance: Required[str]
+    balance_human: NotRequired[float | None]
+    usd_value: NotRequired[float | None]
+
+
+class EnrichedBalances(TypedDict):
+    """Enriched token balances response structure"""
+
+    wallet_address: Required[str]
+    balances: Required[list[TokenBalance]]
+    total_usd_value: NotRequired[float | None]
+
+
+class WalletClient(WayfinderClient):
+    def __init__(self, api_key: str | None = None):
+        super().__init__(api_key=api_key)
+        self.api_base_url = f"{settings.WAYFINDER_API_URL}"
+        self._auth_client = AuthClient(api_key=api_key)
+
+    async def get_token_balance_for_wallet(
+        self,
+        *,
+        token_id: str,
+        wallet_address: str,
+        human_readable: bool = True,
+    ) -> TokenBalance:
+        """
+        Fetch a single token balance for an explicit wallet address.
+
+        Mirrors POST /api/v1/public/balances/token/
+        """
+        url = f"{self.api_base_url}/public/balances/token/"
+        payload = {
+            "token_id": token_id,
+            "wallet_address": wallet_address,
+            "human_readable": human_readable,
+        }
+        response = await self._authed_request("POST", url, json=payload)
+        data = response.json()
+        return data.get("data", data)
+
+    async def get_pool_balance_for_wallet(
+        self,
+        *,
+        pool_address: str,
+        chain_id: int,
+        user_address: str,
+        human_readable: bool = True,
+    ) -> PoolBalance:
+        """
+        Fetch a wallet's LP/share balance for a given pool address and chain.
+
+        Mirrors POST /api/v1/public/balances/pool/
+        """
+        url = f"{self.api_base_url}/public/balances/pool/"
+        payload = {
+            "pool_address": pool_address,
+            "chain_id": chain_id,
+            "user_address": user_address,
+            "human_readable": human_readable,
+        }
+        response = await self._authed_request("POST", url, json=payload)
+        data = response.json()
+        return data.get("data", data)