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

wayfinder_paths/adapters/multicall_adapter/adapter.py

@@ -0,0 +1,166 @@
+from __future__ import annotations
+
+from collections.abc import Iterable, Sequence
+from dataclasses import dataclass
+from typing import Any
+
+from hexbytes import HexBytes
+
+from wayfinder_paths.core.adapters.BaseAdapter import BaseAdapter
+from wayfinder_paths.core.constants.erc20_abi import ERC20_ABI
+
+MULTICALL3_DEFAULT_ADDRESS = "0xcA11bde05977b3631167028862bE2a173976CA11"
+MULTICALL3_ABI = [
+    {
+        "inputs": [
+            {
+                "components": [
+                    {"internalType": "address", "name": "target", "type": "address"},
+                    {"internalType": "bytes", "name": "callData", "type": "bytes"},
+                ],
+                "internalType": "struct Multicall3.Call[]",
+                "name": "calls",
+                "type": "tuple[]",
+            }
+        ],
+        "name": "aggregate",
+        "outputs": [
+            {"internalType": "uint256", "name": "blockNumber", "type": "uint256"},
+            {"internalType": "bytes[]", "name": "returnData", "type": "bytes[]"},
+        ],
+        "stateMutability": "payable",
+        "type": "function",
+    },
+    {
+        "inputs": [{"internalType": "address", "name": "addr", "type": "address"}],
+        "name": "getEthBalance",
+        "outputs": [
+            {"internalType": "uint256", "name": "balance", "type": "uint256"},
+        ],
+        "stateMutability": "view",
+        "type": "function",
+    },
+]
+
+
+@dataclass(frozen=True)
+class MulticallCall:
+    target: str
+    call_data: bytes | str
+
+    def as_tuple(self) -> tuple[str, bytes | str]:
+        return self.target, self.call_data
+
+
+@dataclass
+class MulticallResult:
+    block_number: int
+    return_data: Sequence[bytes]
+
+
+class MulticallAdapter(BaseAdapter):
+    """Thin wrapper around Multicall3 for reusable multicall aggregates."""
+
+    adapter_type = "MULTICALL"
+
+    def __init__(
+        self,
+        config: dict[str, Any] | None = None,
+        *,
+        chain_id: int | None = None,
+        web3: Any | None = None,
+        address: str | None = None,
+        abi: list[dict[str, Any]] | None = None,
+    ) -> None:
+        super().__init__("multicall_adapter", config)
+
+        if web3 is None:
+            raise ValueError("MulticallAdapter requires web3 instance")
+        self.chain_id = int(chain_id) if chain_id is not None else None
+        self.web3 = web3
+
+        checksum_address = self.web3.to_checksum_address(
+            address or MULTICALL3_DEFAULT_ADDRESS
+        )
+        self.contract = self.web3.eth.contract(
+            address=checksum_address, abi=abi or MULTICALL3_ABI
+        )
+
+    async def aggregate(
+        self,
+        calls: Iterable[MulticallCall | tuple[str, bytes | str]],
+        *,
+        value: int = 0,
+    ) -> MulticallResult:
+        calls_list = list(calls)
+        if not calls_list:
+            return MulticallResult(block_number=0, return_data=[])
+
+        encoded_calls: list[tuple[str, bytes]] = []
+        for call in calls_list:
+            target, calldata = self._coerce_call(call)
+            encoded_calls.append((target, calldata))
+
+        block_number, return_data = await self.contract.functions.aggregate(
+            encoded_calls
+        ).call({"value": int(value)})
+        payload = tuple(self._ensure_bytes(r) for r in return_data)
+        return MulticallResult(block_number=int(block_number), return_data=payload)
+
+    def build_call(self, target: str, call_data: bytes | str) -> MulticallCall:
+        checksum = self.web3.to_checksum_address(target)
+        normalized = self._normalize_call_data(call_data)
+        return MulticallCall(target=checksum, call_data=normalized)
+
+    def encode_eth_balance(self, account: str) -> MulticallCall:
+        calldata = self.contract.encode_abi("getEthBalance", args=[account])
+        return self.build_call(self.contract.address, calldata)
+
+    def encode_erc20_balance(self, token: str, account: str) -> MulticallCall:
+        addr = self.web3.to_checksum_address(token)
+        erc20 = self.web3.eth.contract(address=addr, abi=ERC20_ABI)
+        calldata = erc20.encode_abi("balanceOf", args=[account])
+        return self.build_call(addr, calldata)
+
+    @staticmethod
+    def decode_uint256(data: bytes | str) -> int:
+        raw = MulticallAdapter._normalize_call_data(data)
+        if len(raw) < 32:
+            raw = raw.rjust(32, b"\x00")
+        return int.from_bytes(raw[-32:], byteorder="big")
+
+    def _coerce_call(
+        self, call: MulticallCall | tuple[str, bytes | str]
+    ) -> tuple[str, bytes]:
+        if isinstance(call, MulticallCall):
+            target = self.web3.to_checksum_address(call.target)
+            calldata = self._normalize_call_data(call.call_data)
+        else:
+            target_str, call_data = call
+            target = self.web3.to_checksum_address(target_str)
+            calldata = self._normalize_call_data(call_data)
+        return target, calldata
+
+    @staticmethod
+    def _normalize_call_data(data: bytes | str) -> bytes:
+        if isinstance(data, bytes):
+            return data
+        if isinstance(data, HexBytes):
+            return bytes(data)
+        if isinstance(data, str):
+            if data.startswith("0x"):
+                return bytes.fromhex(data[2:])
+            return data.encode()
+        raise TypeError("Unsupported calldata type")
+
+    @staticmethod
+    def _ensure_bytes(data: bytes | str | HexBytes) -> bytes:
+        if isinstance(data, bytes):
+            return data
+        if isinstance(data, HexBytes):
+            return bytes(data)
+        if isinstance(data, str):
+            if data.startswith("0x"):
+                return bytes.fromhex(data[2:])
+            return data.encode()
+        raise TypeError("Unexpected return data type from multicall")

wayfinder_paths/adapters/multicall_adapter/manifest.yaml

@@ -0,0 +1,5 @@
+schema_version: "0.1"
+entrypoint: "adapters.multicall_adapter.adapter.MulticallAdapter"
+capabilities:
+  - "multicall.aggregate"
+dependencies: []

wayfinder_paths/adapters/multicall_adapter/test_adapter.py

@@ -0,0 +1,97 @@
+from __future__ import annotations
+
+import pytest
+from web3 import AsyncHTTPProvider, AsyncWeb3
+
+from wayfinder_paths.adapters.multicall_adapter.adapter import (
+    MulticallAdapter,
+    MulticallCall,
+)
+
+
+class _DummyAggregate:
+    def __init__(self, expected_value: int, result):
+        self._expected_value = expected_value
+        self._result = result
+
+    async def call(self, tx_params):
+        assert tx_params == {"value": self._expected_value}
+        return self._result
+
+
+class _DummyFunctions:
+    def __init__(self, expected_calls, expected_value: int, result):
+        self._expected_calls = expected_calls
+        self._expected_value = expected_value
+        self._result = result
+
+    def aggregate(self, calls):
+        assert calls == self._expected_calls
+        return _DummyAggregate(self._expected_value, self._result)
+
+
+class _DummyContract:
+    def __init__(self, expected_calls, expected_value: int, result):
+        self.functions = _DummyFunctions(expected_calls, expected_value, result)
+
+
+class TestMulticallAdapter:
+    def test_normalize_call_data_hex_str(self):
+        raw = MulticallAdapter._normalize_call_data("0x1234")
+        assert raw == b"\x12\x34"
+
+    def test_decode_uint256(self):
+        value = 123
+        encoded = value.to_bytes(32, "big")
+        assert MulticallAdapter.decode_uint256(encoded) == value
+
+    def test_encode_balance_calls_produce_bytes(self):
+        w3 = AsyncWeb3(AsyncHTTPProvider("http://localhost:8545"))
+        adapter = MulticallAdapter(web3=w3)
+
+        eth_call = adapter.encode_eth_balance(
+            "0x0000000000000000000000000000000000000002"
+        )
+        assert isinstance(eth_call, MulticallCall)
+        assert isinstance(eth_call.call_data, (bytes, bytearray))
+        assert len(eth_call.call_data) > 0
+
+        erc20_call = adapter.encode_erc20_balance(
+            "0x0000000000000000000000000000000000000001",
+            "0x0000000000000000000000000000000000000002",
+        )
+        assert isinstance(erc20_call, MulticallCall)
+        assert isinstance(erc20_call.call_data, (bytes, bytearray))
+        assert len(erc20_call.call_data) > 0
+
+    @pytest.mark.asyncio
+    async def test_aggregate_coerces_calls_and_returns_bytes(self):
+        w3 = AsyncWeb3(AsyncHTTPProvider("http://localhost:8545"))
+        adapter = MulticallAdapter(web3=w3)
+
+        call = adapter.build_call(
+            "0x0000000000000000000000000000000000000001", "0x1234"
+        )
+        expected_calls = [
+            (w3.to_checksum_address(call.target), b"\x12\x34"),
+        ]
+
+        dummy_contract = _DummyContract(
+            expected_calls=expected_calls,
+            expected_value=7,
+            result=(123, ["0x" + ("00" * 32)]),
+        )
+        adapter.contract = dummy_contract
+
+        result = await adapter.aggregate([call], value=7)
+        assert result.block_number == 123
+        assert result.return_data == (b"\x00" * 32,)
+
+    @pytest.mark.asyncio
+    async def test_aggregate_empty_returns_empty_result(self):
+        w3 = AsyncWeb3(AsyncHTTPProvider("http://localhost:8545"))
+        adapter = MulticallAdapter(web3=w3)
+
+        result = await adapter.aggregate([])
+        assert result.block_number == 0
+        assert list(result.return_data) == []

wayfinder_paths/adapters/pendle_adapter/README.md

@@ -0,0 +1,102 @@
+# Pendle Adapter
+
+Adapter for Pendle API + Hosted SDK endpoints to support:
+
+- Market discovery (PT/YT markets, APYs, liquidity/volume/expiry filtering)
+- Historical metrics (per-market time series)
+- Execution planning (swap quote → ready-to-send `tx` + required `tokenApprovals`)
+
+## Capabilities
+
+- `pendle.markets.read`: Fetch whitelisted markets (`/v1/markets/all`)
+- `pendle.market.snapshot`: Fetch a market snapshot (`/v2/{chainId}/markets/{market}/data`)
+- `pendle.market.history`: Fetch market historical data (`/v2/{chainId}/markets/{market}/historical-data`)
+- `pendle.prices.ohlcv`: Fetch token OHLCV (`/v4/{chainId}/prices/{token}/ohlcv`)
+- `pendle.prices.assets`: Fetch all asset prices (`/v1/prices/assets`)
+- `pendle.swap.quote`: Build Hosted SDK swap payload (`/v2/sdk/{chainId}/markets/{market}/swap`)
+- `pendle.swap.best_pt`: Select and quote “best” PT swap on a chain
+- `pendle.convert.quote`: Universal Hosted SDK convert quote (`/v2/sdk/{chainId}/convert`)
+- `pendle.convert.best_pt`: Select and quote “best” PT via convert endpoint
+- `pendle.convert.execute`: Broadcast Hosted SDK convert tx (incl approvals)
+- `pendle.positions.database`: Indexed positions snapshot (`/v1/dashboard/positions/database/{user}`; claimables cached)
+- `pendle.limit_orders.*`: Limit order discovery + maker APIs (`/v1/limit-orders/...`)
+- `pendle.deployments.read`: Load Pendle core deployments JSON (router/routerStatic/limitRouter)
+- `pendle.router_static.rates`: Off-chain spot-rate sanity checks via RouterStatic contract
+
+## Configuration
+
+- `PENDLE_API_URL` (env var): defaults to `https://api-v2.pendle.finance/core`
+- Optional config:
+  - `config["pendle_adapter"]["base_url"]`
+  - `config["pendle_adapter"]["timeout"]`
+  - `config["pendle_adapter"]["deployments_base_url"]` (defaults to Pendle’s public core deployments on GitHub)
+  - `config["pendle_adapter"]["max_retries"]`, `retry_backoff_seconds`
+
+## Usage
+
+### List active PT/YT markets (multi-chain)
+
+```python
+from adapters.pendle_adapter.adapter import PendleAdapter
+
+adapter = PendleAdapter()
+
+rows = await adapter.list_active_pt_yt_markets(
+    chains=["arbitrum", "base", "hyperevm"],
+    min_liquidity_usd=250_000,
+    min_volume_usd_24h=25_000,
+    min_days_to_expiry=7,
+    sort_by="fixed_apy",
+    descending=True,
+)
+```
+
+### Build the best PT swap transaction (single chain)
+
+```python
+best = await adapter.build_best_pt_swap_tx(
+    chain="arbitrum",
+    token_in="0xaf88d065e77c8cC2239327C5EDb3A432268e5831",  # example: USDC (Arbitrum)
+    amount_in=str(1000 * 10**6),  # 1000 USDC, base units (6 decimals)
+    receiver="0xYourEOAHere",
+    slippage=0.01,
+    enable_aggregator=True,
+)
+
+if best["ok"]:
+    tx = best["tx"]
+    approvals = best["tokenApprovals"]
+```
+
+### Build a universal convert transaction (token -> PT)
+
+```python
+convert = await adapter.sdk_convert_v2(
+    chain="arbitrum",
+    slippage=0.01,
+    receiver="0xYourEOAHere",
+    inputs=[{"token": "0xaf88d065e77c8cC2239327C5EDb3A432268e5831", "amount": str(1 * 10**6)}],  # 1 USDC
+    outputs=["0x97c1a4ae3e0da8009aff13e3e3ee7ea5ee4afe84"],  # PT token address
+    enable_aggregator=True,
+    aggregators=["kyberswap"],
+    additional_data=["impliedApy", "effectiveApy", "priceImpact"],
+)
+plan = adapter.build_convert_plan(chain="arbitrum", convert_response=convert)
+```
+
+### Execute a universal convert (handles approvals + broadcast)
+
+```python
+ok, res = await adapter.execute_convert(
+    chain="arbitrum",
+    slippage=0.01,
+    inputs=[{"token": "0xaf88d065e77c8cC2239327C5EDb3A432268e5831", "amount": str(1 * 10**6)}],
+    outputs=["0x97c1a4ae3e0da8009aff13e3e3ee7ea5ee4afe84"],
+)
+```
+
+## Notes
+
+- “Fixed APY” proxy is `details.impliedApy` from `/v1/markets/all`.
+- `build_best_pt_swap_tx()` requests Hosted SDK `additionalData=impliedApy,effectiveApy` and prefers `effectiveApy` when present.
+- All Pendle REST/SDK responses include a `rateLimit` field populated from headers (x-ratelimit-* and x-computing-unit) for CU-aware budgeting.

wayfinder_paths/adapters/pendle_adapter/__init__.py

@@ -0,0 +1,7 @@
+"""
+Pendle Adapter
+"""
+
+from wayfinder_paths.adapters.pendle_adapter.adapter import PendleAdapter
+
+__all__ = ["PendleAdapter"]