eth-portfolio 1.1.0__py3-none-any.whl

eth_portfolio/protocols/_base.py

@@ -0,0 +1,107 @@
+import abc
+from asyncio import gather
+from typing import List, Optional
+
+import a_sync
+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: Optional[Block] = None) -> TokenBalances:
+        return await self._balances(address, block=block)
+
+    @abc.abstractmethod
+    async def _balances(self, address: Address, block: Optional[Block] = None) -> TokenBalances: ...
+
+
+class ProtocolWithStakingABC(ProtocolABC, metaclass=abc.ABCMeta):
+    pools: List["StakingPoolABC"]
+
+    @stuck_coro_debugger
+    async def _balances(self, address: Address, block: Optional[Block] = None) -> TokenBalances:
+        return sum(await gather(*[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: Optional[Block] = 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: Optional[Block]) -> 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: Optional[Block] = 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,31 @@
+from asyncio import gather
+from typing import Optional
+
+from y import Contract, Network, dai
+from y.datatypes import Address, Block
+
+from eth_portfolio._decimal import Decimal
+from eth_portfolio.protocols._base import ProtocolABC
+from eth_portfolio.typing import Balance, TokenBalances
+
+
+class MakerDSR(ProtocolABC):
+    networks = [Network.Mainnet]
+
+    def __init__(self) -> None:
+        self.dsr_manager = Contract("0x373238337Bfe1146fb49989fc222523f83081dDb")
+        self.pot = Contract("0x197E90f9FAD81970bA7976f33CbD77088E5D7cf7")
+
+    async def _balances(self, address: Address, block: Optional[Block] = None) -> TokenBalances:
+        balances = TokenBalances(block=block)
+        pie, exchange_rate = await gather(
+            self.dsr_manager.pieOf.coroutine(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: Optional[Block] = None) -> Decimal:
+        return Decimal(await self.pot.chi.coroutine(block_identifier=block)) / 10**27

eth_portfolio/protocols/lending/__init__.py

@@ -0,0 +1,49 @@
+from typing import List, Optional, Union
+
+import a_sync
+from eth_portfolio._utils import _get_protocols_for_submodule, _import_submodules
+from eth_portfolio.protocols.lending._base import (
+    LendingProtocol,
+    LendingProtocolWithLockedCollateral,
+)
+from eth_portfolio.typing import RemoteTokenBalances
+from y._decorators import stuck_coro_debugger
+from y.datatypes import Address, Block
+
+_import_submodules()
+
+protocols: List[Union[LendingProtocol, LendingProtocolWithLockedCollateral]] = _get_protocols_for_submodule()  # type: ignore [assignment]
+
+has_collateral = lambda protocol: isinstance(protocol, LendingProtocolWithLockedCollateral)
+
+
+@a_sync.future
+@stuck_coro_debugger
+async def collateral(address: Address, block: Optional[Block] = 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: Optional[Block] = 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,57 @@
+import abc
+from typing import Optional
+
+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: Optional[Block] = None) -> TokenBalances:
+        return await self._debt(address, block)  # type: ignore
+
+    @abc.abstractmethod
+    async def _debt(self, address: Address, block: Optional[Block] = 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,185 @@
+from asyncio import gather
+from typing import List, Optional
+
+import a_sync
+from async_lru import alru_cache
+from brownie import ZERO_ADDRESS, Contract
+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 Address, Balance, TokenBalances
+
+
+def _get_contract(market: CToken) -> Optional[Contract]:
+    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 gather(
+            *[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 gather(
+            *[market.underlying.coroutine() 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: Address, block: Optional[Block] = 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(
+            gather(*[_borrow_balance_stored(market, address, block) for market in markets]),
+            gather(*[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: Address, block: Optional[Block] = None
+) -> Optional[int]:
+    """
+    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,110 @@
+from typing import Optional
+
+from 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: Optional[Block] = 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: Optional[Block] = 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

eth_portfolio/protocols/lending/maker.py

@@ -0,0 +1,105 @@
+from asyncio import gather
+from typing import List, Optional
+
+from async_lru import alru_cache
+from dank_mids.exceptions import Revert
+from eth_typing import HexStr
+from y import Contract, Network, contract_creation_block_async, get_price
+from y._decorators import stuck_coro_debugger
+from y.constants import dai
+from y.datatypes import Address, Block
+
+from eth_portfolio._utils import Decimal
+from eth_portfolio.protocols.lending._base import LendingProtocolWithLockedCollateral
+from eth_portfolio.typing import Balance, TokenBalances
+
+try:
+    # this is only available in 4.0.0+
+    from eth_abi import encode
+
+    encode_bytes = lambda bytestring: encode(["bytes32"], [bytestring])
+except ImportError:
+    from eth_abi import encode_single
+
+    encode_bytes = lambda bytestring: encode_single("bytes32", bytestring)
+
+yfi = "0x0bc529c00C6401aEF6D220BE8C6Ea1667F6Ad93e"
+
+
+class Maker(LendingProtocolWithLockedCollateral):
+    networks = [Network.Mainnet]
+
+    def __init__(self) -> None:
+        self.proxy_registry = Contract("0x4678f0a6958e4D2Bc4F1BAF7Bc52E8F3564f3fE4")
+        self.cdp_manager = Contract("0x5ef30b9986345249bc32d8928B7ee64DE9435E39")
+        self.ilk_registry = Contract("0x5a464C28D19848f44199D003BeF5ecc87d090F87")
+        self.vat = Contract("0x35D1b3F3D7966A1DFe207aa4514C12a259A0492B")
+
+    @stuck_coro_debugger
+    async def _balances(self, address: Address, block: Optional[Block] = None) -> TokenBalances:
+        ilks, urn = await gather(self.get_ilks(block), self._urn(address))
+
+        gem_coros = gather(*[self.get_gem(str(ilk)) for ilk in ilks])
+        ink_coros = gather(
+            *[self.vat.urns.coroutine(ilk, urn, block_identifier=block) for ilk in ilks]
+        )
+
+        gems, ink_data = await gather(gem_coros, ink_coros)
+
+        balances: TokenBalances = TokenBalances(block=block)
+        for token, data in zip(gems, ink_data):
+            if ink := data.dict()["ink"]:
+                balance = ink / Decimal(10**18)
+                value = round(balance * Decimal(await get_price(token, block, sync=False)), 18)
+                balances[token] = Balance(balance, value, token=token, block=block)
+        return balances
+
+    @stuck_coro_debugger
+    async def _debt(self, address: Address, block: Optional[int] = None) -> TokenBalances:
+        if block is not None and block <= await contract_creation_block_async(self.ilk_registry):
+            return TokenBalances(block=block)
+
+        ilks, urn = await gather(self.get_ilks(block), self._urn(address))
+
+        data = await gather(
+            *[
+                gather(
+                    self.vat.urns.coroutine(ilk, urn, block_identifier=block),
+                    self.vat.ilks.coroutine(ilk, block_identifier=block),
+                )
+                for ilk in ilks
+            ]
+        )
+
+        balances: TokenBalances = TokenBalances(block=block)
+        for urns, ilk_info in data:
+            art = urns.dict()["art"]
+            rate = ilk_info.dict()["rate"]
+            debt = art * rate / Decimal(1e45)
+            balances[dai] += Balance(debt, debt, token=dai, block=block)
+        return balances
+
+    async def get_ilks(self, block: Optional[int]) -> List[HexStr]:
+        """List all ilks (cdp keys of sorts) for MakerDAO"""
+        try:
+            return await self.ilk_registry.list.coroutine(block_identifier=block)
+        except Revert:
+            return []
+
+    @alru_cache
+    async def get_gem(self, ilk: bytes) -> str:
+        return await self.ilk_registry.gem.coroutine(ilk)
+
+    @alru_cache
+    async def _proxy(self, address: Address) -> Address:
+        return await self.proxy_registry.proxies.coroutine(address)
+
+    @alru_cache
+    async def _cdp(self, address: Address) -> Address:
+        proxy = await self._proxy(address)
+        return await self.cdp_manager.first.coroutine(proxy)
+
+    @alru_cache
+    async def _urn(self, address: Address) -> Address:
+        cdp = await self._cdp(address)
+        return await self.cdp_manager.urns.coroutine(cdp)