eth-portfolio 0.5.7__cp312-cp312-win32.whl

eth_portfolio/protocols/__init__.py

@@ -0,0 +1,64 @@
+import a_sync
+from y.datatypes import Address, Block
+
+from eth_portfolio._submodules import get_protocols, import_submodules
+from eth_portfolio.protocols import lending
+from eth_portfolio.protocols._base import StakingPoolABC
+from eth_portfolio.typing import RemoteTokenBalances
+
+import_submodules()
+
+protocols: list[StakingPoolABC] = get_protocols()  # type: ignore [assignment]
+
+
+@a_sync.future
+async def balances(address: Address, block: Block | None = None) -> RemoteTokenBalances:
+    """
+    Fetch token balances for a given address across various protocols.
+
+    This function retrieves the token balances for a specified Ethereum address
+    at a given block across all available protocols. It is decorated with
+    :func:`a_sync.future`, allowing it to be used in both synchronous and
+    asynchronous contexts.
+
+    If no protocols are available, the function returns an empty
+    :class:`~eth_portfolio.typing.RemoteTokenBalances` object.
+
+    Args:
+        address: The Ethereum address for which to fetch balances.
+        block: The block number at which to fetch balances.
+            If not provided, the latest block is used.
+
+    Examples:
+        Fetching balances asynchronously:
+
+        >>> from eth_portfolio.protocols import balances
+        >>> address = "0x1234567890abcdef1234567890abcdef12345678"
+        >>> block = 12345678
+        >>> remote_balances = await balances(address, block)
+        >>> print(remote_balances)
+
+        Fetching balances synchronously:
+
+        >>> remote_balances = balances(address, block)
+        >>> print(remote_balances)
+
+    The function constructs a dictionary `data` with protocol class names
+    as keys and their corresponding protocol balances as values. The `protocol_balances`
+    variable is a result of mapping the `balances` method over the `protocols` using
+    :func:`a_sync.map`. The asynchronous comprehension iterates over `protocol_balances`
+    to filter and construct the `data` dictionary. This dictionary is subsequently used
+    to initialize the :class:`~eth_portfolio.typing.RemoteTokenBalances` object.
+    """
+    if not protocols:
+        return RemoteTokenBalances(block=block)
+    protocol_balances = a_sync.map(
+        lambda protocol: protocol.balances(address, block),
+        protocols,
+    )
+    data = {
+        type(protocol).__name__: protocol_balances
+        async for protocol, protocol_balances in protocol_balances
+        if protocol_balances is not None
+    }
+    return RemoteTokenBalances(data, block=block)

eth_portfolio/protocols/_base.py

@@ -0,0 +1,107 @@
+import abc
+from asyncio import gather
+
+import a_sync
+from a_sync import igather
+from a_sync.a_sync import ASyncFunctionSyncDefault, HiddenMethod
+from brownie.network.contract import ContractCall
+from y import ERC20, Contract
+from y._decorators import stuck_coro_debugger
+from y.contracts import contract_creation_block
+from y.datatypes import Address, Block
+
+from eth_portfolio._utils import Decimal
+from eth_portfolio.typing import Balance, TokenBalances
+
+
+class ProtocolABC(metaclass=abc.ABCMeta):
+    @a_sync.future
+    async def balances(self, address: Address, block: Block | None = None) -> TokenBalances:
+        return await self._balances(address, block=block)
+
+    @abc.abstractmethod
+    async def _balances(self, address: Address, block: Block | None = None) -> TokenBalances: ...
+
+
+class ProtocolWithStakingABC(ProtocolABC, metaclass=abc.ABCMeta):
+    pools: list["StakingPoolABC"]
+
+    @stuck_coro_debugger
+    async def _balances(self, address: Address, block: Block | None = None) -> TokenBalances:
+        return sum(await igather(pool.balances(address, block) for pool in self.pools))  # type: ignore
+
+
+class StakingPoolABC(ProtocolABC, metaclass=abc.ABCMeta):
+    contract_address: Address
+    """
+    The address of the staking pool.
+    """
+
+    balance_method_name: str
+    """
+    The name of the method that is used to query a staker's balance in the staking pool.
+    """
+
+    @a_sync.future
+    async def __call__(self, *args, block: Block | None = None, **_) -> int:
+        if _:
+            raise ValueError(
+                "SingleTokenStakingPoolABC.__call__ does not support keyword arguments"
+            )
+        return await self.contract_call.coroutine(*args, block_identifier=block)
+
+    @property
+    def contract(self) -> Contract:
+        return Contract(self.contract_address)
+
+    @property
+    def contract_call(self) -> ContractCall:
+        return getattr(self.contract, self.balance_method_name)
+
+    @property
+    def deploy_block(self) -> Block:
+        return contract_creation_block(self.contract_address)
+
+    def should_check(self, block: Block | None) -> bool:
+        return block is None or block >= self.deploy_block
+
+
+class SingleTokenStakingPoolABC(StakingPoolABC, metaclass=abc.ABCMeta):
+    """
+    Works for any contract that has a view method with the following signature:
+
+    ```
+    methodName(address) -> uint256
+    ```
+
+    In the above example:
+     - ``address`` is the user's address, provided at runtime.
+     - ``methodName`` is whatever string you set for the staking pool's ``balance_method_name``.
+     - ``uint256`` is the user's ``token`` balance held in ``contract_address`` at the queried block.
+    """
+
+    token: ERC20
+    """
+    The token that is used for staking in this pool.
+    """
+
+    @property
+    def price(self) -> ASyncFunctionSyncDefault[Block, Decimal]:
+        return self.token.price
+
+    @property
+    def scale(self) -> HiddenMethod[ERC20, int]:
+        return self.token.__scale__
+
+    @stuck_coro_debugger
+    async def _balances(self, address: Address, block: Block | None = None) -> TokenBalances:
+        balances: TokenBalances = TokenBalances(block=block)
+        if self.should_check(block):
+            balance = Decimal(await self(address, block=block))  # type: ignore
+            if balance:
+                scale, price = await gather(self.scale, self.price(block, sync=False))
+                balance /= scale  # type: ignore
+                balances[self.token.address] = Balance(
+                    balance, balance * Decimal(price), token=self.token.address, block=block
+                )
+        return balances

eth_portfolio/protocols/convex.py

@@ -0,0 +1,17 @@
+from y import ERC20, Network
+
+from eth_portfolio.protocols._base import ProtocolWithStakingABC, SingleTokenStakingPoolABC
+
+
+class _CvxLockerV2(SingleTokenStakingPoolABC):
+    contract_address = "0x72a19342e8F1838460eBFCCEf09F6585e32db86E"
+    balance_method_name = "lockedBalanceOf"
+    token = ERC20("0x4e3FBD56CD56c3e72c1403e103b45Db9da5B9D2B")
+
+
+class Convex(ProtocolWithStakingABC):
+    networks = [Network.Mainnet]
+
+    def __init__(self) -> None:
+        super().__init__()
+        self.pools = [_CvxLockerV2()]

eth_portfolio/protocols/dsr.py

@@ -0,0 +1,50 @@
+import asyncio
+from typing import ClassVar, Final, final
+
+import y
+from y.datatypes import Address, Block
+
+from eth_portfolio import _decimal
+from eth_portfolio.protocols._base import ProtocolABC
+from eth_portfolio.typing import Balance, TokenBalances
+
+gather: Final = asyncio.gather
+
+Contract: Final = y.Contract
+Network: Final = y.Network
+contract_creation_block: Final = y.contract_creation_block
+dai: Final = y.dai
+
+Decimal: Final = _decimal.Decimal
+
+
+@final
+class MakerDSR(ProtocolABC):
+    networks: ClassVar = [Network.Mainnet]
+
+    def __init__(self) -> None:
+        dsr_manager = "0x373238337Bfe1146fb49989fc222523f83081dDb"
+        pot = "0x197E90f9FAD81970bA7976f33CbD77088E5D7cf7"
+        self.dsr_manager: Final = Contract(dsr_manager)
+        self.pot: Final = Contract(pot)
+        self._start_block: Final = max(
+            contract_creation_block(dsr_manager), contract_creation_block(pot)
+        )
+        self._get_chi: Final = self.pot.chi.coroutine
+        self._get_pie: Final = self.dsr_manager.pieOf.coroutine
+
+    async def _balances(self, address: Address, block: Block | None = None) -> TokenBalances:
+        balances = TokenBalances(block=block)
+        if block and block < self._start_block:
+            return balances
+        pie, exchange_rate = await gather(
+            self._get_pie(address, block_identifier=block),
+            self._exchange_rate(block),
+        )
+        if pie:
+            dai_in_dsr = pie * exchange_rate / 10**18
+            balances[dai] = Balance(dai_in_dsr, dai_in_dsr, token=dai, block=block)
+        return balances
+
+    async def _exchange_rate(self, block: Block | None = None) -> Decimal:
+        return Decimal(await self._get_chi(block_identifier=block)) / 10**27

eth_portfolio/protocols/lending/README.md

@@ -0,0 +1,6 @@
+This module contains the base classes for lending protocols in the _base.py file, and all lending protocols supported by eth-portfolio.
+
+If you want to add support for a new lending protocol, there are only a few steps:
+1. Create a new python file, named appropriately.
+2. Subclass one of the 2 classes in _base.py and define the methods specified in the parent definition with the custom logic for the protocol you wish to add. 
+3. That's it, eth-portfolio will automagically handle the rest!

eth_portfolio/protocols/lending/__init__.py

@@ -0,0 +1,50 @@
+from typing import List, Optional, Union
+
+import a_sync
+from y._decorators import stuck_coro_debugger
+from y.datatypes import Address, Block
+
+from eth_portfolio._submodules import get_protocols, import_submodules
+from eth_portfolio.protocols.lending._base import (
+    LendingProtocol,
+    LendingProtocolWithLockedCollateral,
+)
+from eth_portfolio.typing import RemoteTokenBalances
+
+import_submodules()
+
+protocols: list[LendingProtocol | LendingProtocolWithLockedCollateral] = get_protocols()  # type: ignore [assignment]
+
+has_collateral = lambda protocol: isinstance(protocol, LendingProtocolWithLockedCollateral)
+
+
+@a_sync.future
+@stuck_coro_debugger
+async def collateral(address: Address, block: Block | None = None) -> RemoteTokenBalances:
+    protocol_balances = a_sync.map(
+        lambda protocol: protocol.balances(address, block),
+        filter(has_collateral, protocols),
+    )
+    data = {
+        type(protocol).__name__: token_balances
+        async for protocol, token_balances in protocol_balances
+        if token_balances is not None
+    }
+    return RemoteTokenBalances(data, block=block)
+
+
+@a_sync.future
+@stuck_coro_debugger
+async def debt(address: Address, block: Block | None = None) -> RemoteTokenBalances:
+    if not protocols:
+        return RemoteTokenBalances(block=block)
+    protocol_debts = a_sync.map(
+        lambda protocol: protocol.debt(address, block),
+        protocols,
+    )
+    data = {
+        type(protocol).__name__: token_balances
+        async for protocol, token_balances in protocol_debts
+        if token_balances is not None
+    }
+    return RemoteTokenBalances(data, block=block)

eth_portfolio/protocols/lending/_base.py

@@ -0,0 +1,56 @@
+import abc
+
+import a_sync
+from y.datatypes import Address, Block
+
+from eth_portfolio.protocols._base import ProtocolABC
+from eth_portfolio.typing import TokenBalances
+
+
+class LendingProtocol(metaclass=abc.ABCMeta):
+    """
+    Subclass this class for any protocol that maintains a debt balance for a user but doesn't maintain collateral internally.
+    Example: Aave, because the user holds on to their collateral in the form of ERC-20 aTokens.
+
+    You must define the following async method:
+        `_debt(self, address: Address, block: Optional[Block] = None)`
+
+    Example:
+        >>> class AaveProtocol(LendingProtocol):
+        ...     async def _debt(self, address: Address, block: Optional[Block] = None) -> TokenBalances:
+        ...         # Implementation for fetching debt from Aave
+        ...         pass
+
+    See Also:
+        - :class:`LendingProtocolWithLockedCollateral`
+    """
+
+    @a_sync.future
+    async def debt(self, address: Address, block: Block | None = None) -> TokenBalances:
+        return await self._debt(address, block)  # type: ignore
+
+    @abc.abstractmethod
+    async def _debt(self, address: Address, block: Block | None = None) -> TokenBalances: ...
+
+
+class LendingProtocolWithLockedCollateral(LendingProtocol, ProtocolABC):
+    """
+    Subclass this class for any protocol that maintains a debt balance for a user AND holds collateral internally.
+    Example: Maker, because collateral is locked up inside of Maker's smart contracts.
+
+    You must define the following async methods:
+        - `_debt(self, address: Address, block: Optional[Block] = None)`
+        - `_balances(self, address: Address, block: Optional[Block] = None)`
+
+    Example:
+        >>> class MakerProtocol(LendingProtocolWithLockedCollateral):
+        ...     async def _debt(self, address: Address, block: Optional[Block] = None) -> TokenBalances:
+        ...         # Implementation for fetching debt from Maker
+        ...         pass
+        ...     async def _balances(self, address: Address, block: Optional[Block] = None) -> TokenBalances:
+        ...         # Implementation for fetching balances from Maker
+        ...         pass
+
+    See Also:
+        - :class:`LendingProtocol`
+    """

eth_portfolio/protocols/lending/compound.py

@@ -0,0 +1,186 @@
+from asyncio import gather
+
+import a_sync
+from a_sync import igather
+from async_lru import alru_cache
+from brownie import ZERO_ADDRESS, Contract
+from eth_typing import ChecksumAddress
+from y import ERC20, Contract, map_prices, weth
+from y._decorators import stuck_coro_debugger
+from y.datatypes import Block
+from y.exceptions import ContractNotVerified
+from y.prices.lending.compound import CToken, compound
+
+from eth_portfolio._utils import Decimal
+from eth_portfolio.protocols.lending._base import LendingProtocol
+from eth_portfolio.typing import Balance, TokenBalances
+
+
+def _get_contract(market: CToken) -> Contract | None:
+    try:
+        return market.contract
+    except ContractNotVerified:
+        # We will skip these for now. Might consider supporting them later if necessary.
+        return None
+
+
+class Compound(LendingProtocol):
+    _markets: list[Contract]
+
+    @a_sync.future
+    @alru_cache(ttl=300)
+    @stuck_coro_debugger
+    async def underlyings(self) -> list[ERC20]:
+        """
+        Fetches the underlying ERC20 tokens for all Compound markets.
+
+        This method gathers all markets from the Compound protocol's trollers
+        and filters out those that do not have a `borrowBalanceStored` attribute
+        by using the :func:`hasattr` function directly on the result of
+        :func:`_get_contract`. It then separates markets into those that use
+        the native gas token and those that have an underlying ERC20 token,
+        fetching the underlying tokens accordingly.
+
+        Returns:
+            A list of :class:`~y.classes.common.ERC20` instances representing the underlying tokens.
+
+        Examples:
+            >>> compound = Compound()
+            >>> underlyings = await compound.underlyings()
+            >>> for token in underlyings:
+            ...     print(token.symbol)
+
+        See Also:
+            - :meth:`markets`: To get the list of market contracts.
+        """
+        all_markets: list[list[CToken]] = await igather(
+            comp.markets for comp in compound.trollers.values()
+        )
+        markets: list[Contract] = [
+            market.contract
+            for troller in all_markets
+            for market in troller
+            if hasattr(_get_contract(market), "borrowBalanceStored")
+        ]  # this last part takes out xinv
+        gas_token_markets = [market for market in markets if not hasattr(market, "underlying")]
+        other_markets = [market for market in markets if hasattr(market, "underlying")]
+
+        markets = gas_token_markets + other_markets
+        underlyings = [weth for market in gas_token_markets] + await igather(
+            market.underlying for market in other_markets
+        )
+
+        markets_zip = zip(markets, underlyings)
+        self._markets, underlyings = [], []
+        for contract, underlying in markets_zip:
+            if underlying != ZERO_ADDRESS:
+                self._markets.append(contract)
+                underlyings.append(underlying)
+        return [ERC20(underlying, asynchronous=True) for underlying in underlyings]
+
+    @a_sync.future
+    @stuck_coro_debugger
+    async def markets(self) -> list[Contract]:
+        """
+        Fetches the list of market contracts for the Compound protocol.
+
+        This method ensures that the underlying tokens are fetched first,
+        as they are used to determine the markets.
+
+        Returns:
+            A list of :class:`~brownie.network.contract.Contract` instances representing the markets.
+
+        Examples:
+            >>> compound = Compound()
+            >>> markets = await compound.markets()
+            >>> for market in markets:
+            ...     print(market.address)
+
+        See Also:
+            - :meth:`underlyings`: To get the list of underlying tokens.
+        """
+        await self.underlyings()
+        return self._markets
+
+    async def _debt(self, address: ChecksumAddress, block: Block | None = None) -> TokenBalances:
+        """
+        Calculates the debt balance for a given address in the Compound protocol.
+
+        This method fetches the borrow balance for each market and calculates
+        the debt in terms of the underlying token and its USD value.
+
+        Args:
+            address: The Ethereum address to calculate the debt for.
+            block: The block number to query. Defaults to the latest block.
+
+        Returns:
+            A :class:`~eth_portfolio.typing.TokenBalances` object representing the debt balances.
+
+        Examples:
+            >>> compound = Compound()
+            >>> debt_balances = await compound._debt("0x1234567890abcdef1234567890abcdef12345678")
+            >>> for token, balance in debt_balances.items():
+            ...     print(f"Token: {token}, Balance: {balance.balance}, USD Value: {balance.usd_value}")
+
+        See Also:
+            - :meth:`debt`: Public method to get the debt balances.
+        """
+        # if ypricemagic doesn't support any Compound forks on current chain
+        if len(compound.trollers) == 0:
+            return TokenBalances(block=block)
+
+        address = str(address)
+        markets: list[Contract]
+        underlyings: list[ERC20]
+        markets, underlyings = await gather(self.markets(), self.underlyings())
+        debt_data, underlying_scale = await gather(
+            igather(_borrow_balance_stored(market, address, block) for market in markets),
+            igather(underlying.__scale__ for underlying in underlyings),
+        )
+
+        balances: TokenBalances = TokenBalances(block=block)
+        if debts := {
+            underlying: Decimal(debt) / scale
+            for underlying, scale, debt in zip(underlyings, underlying_scale, debt_data)
+            if debt
+        }:
+            async for underlying, price in map_prices(debts, block=block):
+                debt = debts.pop(underlying)
+                balances[underlying] += Balance(
+                    debt, debt * Decimal(price), token=underlying.address, block=block
+                )
+        return balances
+
+
+@stuck_coro_debugger
+async def _borrow_balance_stored(
+    market: Contract, address: ChecksumAddress, block: Block | None = None
+) -> int | None:
+    """
+    Fetches the stored borrow balance for a given market and address.
+
+    This function attempts to call the `borrowBalanceStored` method on the
+    market contract. If the call reverts, it returns None.
+
+    Args:
+        market: The market contract to query.
+        address: The Ethereum address to fetch the borrow balance for.
+        block: The block number to query. Defaults to the latest block.
+
+    Returns:
+        The stored borrow balance as an integer, or None if the call reverts.
+
+    Examples:
+        >>> market = Contract.from_explorer("0x1234567890abcdef1234567890abcdef12345678")
+        >>> balance = await _borrow_balance_stored(market, "0xabcdefabcdefabcdefabcdefabcdefabcdef")
+        >>> print(balance)
+
+    See Also:
+        - :meth:`_debt`: Uses this function to calculate debt balances.
+    """
+    try:
+        return await market.borrowBalanceStored.coroutine(str(address), block_identifier=block)
+    except ValueError as e:
+        if str(e) != "No data was returned - the call likely reverted":
+            raise
+        return None

eth_portfolio/protocols/lending/liquity.py

@@ -0,0 +1,108 @@
+from faster_async_lru import alru_cache
+from y import Contract, Network, get_price
+from y._decorators import stuck_coro_debugger
+from y.constants import EEE_ADDRESS
+from y.datatypes import Address, Block
+
+from eth_portfolio.protocols.lending._base import LendingProtocolWithLockedCollateral
+from eth_portfolio.typing import Balance, TokenBalances
+
+lusd = "0x5f98805A4E8be255a32880FDeC7F6728C6568bA0"
+
+
+class Liquity(LendingProtocolWithLockedCollateral):
+    """
+    Represents the Liquity protocol, a decentralized borrowing protocol that allows users to draw loans against Ether collateral.
+
+    This class is a subclass of :class:`~eth_portfolio.protocols.lending._base.LendingProtocolWithLockedCollateral`, which means it maintains a debt balance for a user and holds collateral internally.
+
+    Examples:
+        >>> liquity = Liquity()
+        >>> balances = await liquity.balances("0xYourAddress", 12345678)
+        >>> print(balances)
+
+    See Also:
+        - :class:`~eth_portfolio.protocols.lending._base.LendingProtocolWithLockedCollateral`
+        - :class:`~eth_portfolio.typing.TokenBalances`
+    """
+
+    networks = [Network.Mainnet]
+    """The networks on which the protocol is available."""
+
+    def __init__(self) -> None:
+        self.troveManager = Contract("0xA39739EF8b0231DbFA0DcdA07d7e29faAbCf4bb2")
+        """The contract instance for the Trove Manager."""
+        self.start_block = 12178557
+        """The block number from which the protocol starts."""
+
+    @alru_cache(maxsize=128)
+    @stuck_coro_debugger
+    async def get_trove(self, address: Address, block: Block) -> dict:
+        """
+        Retrieves the trove data for a given address at a specific block.
+
+        Args:
+            address: The Ethereum address of the user.
+            block: The block number to query.
+
+        Examples:
+            >>> trove_data = await liquity.get_trove("0xYourAddress", 12345678)
+            >>> print(trove_data)
+        """
+        return await self.troveManager.Troves.coroutine(address, block_identifier=block)
+
+    @stuck_coro_debugger
+    async def _balances(self, address: Address, block: Block | None = None) -> TokenBalances:
+        """
+        Retrieves the collateral balances for a given address at a specific block.
+
+        Args:
+            address: The Ethereum address of the user.
+            block: The block number to query.
+
+        Examples:
+            >>> balances = await liquity._balances("0xYourAddress", 12345678)
+            >>> print(balances)
+
+        See Also:
+            - :class:`~eth_portfolio.typing.TokenBalances`
+        """
+        balances: TokenBalances = TokenBalances(block=block)
+        if block and block < self.start_block:
+            return balances
+        data = await self.get_trove(address, block)
+        eth_collateral_balance = data[1]
+        if eth_collateral_balance:
+            eth_collateral_balance /= 10**18
+            value = eth_collateral_balance * await get_price(EEE_ADDRESS, block, sync=False)
+            balances[EEE_ADDRESS] = Balance(
+                eth_collateral_balance, value, token=EEE_ADDRESS, block=block
+            )
+        return balances
+
+    @stuck_coro_debugger
+    async def _debt(self, address: Address, block: Block | None = None) -> TokenBalances:
+        """
+        Retrieves the debt balances for a given address at a specific block.
+
+        Args:
+            address: The Ethereum address of the user.
+            block: The block number to query.
+
+        Examples:
+            >>> debt_balances = await liquity._debt("0xYourAddress", 12345678)
+            >>> print(debt_balances)
+
+        See Also:
+            - :class:`~eth_portfolio.typing.TokenBalances`
+        """
+        balances: TokenBalances = TokenBalances(block=block)
+        if block and block < self.start_block:
+            return balances
+        data = await self.get_trove(address, block)
+        lusd_debt = data[0]
+        if lusd_debt:
+            lusd_debt /= 10**18
+            value = lusd_debt * await get_price(lusd, block, sync=False)
+            balances[lusd] = Balance(lusd_debt, value, token=lusd, block=block)
+        return balances