eth-portfolio 1.1.0__py3-none-any.whl

eth_portfolio/address.py

@@ -0,0 +1,382 @@
+"""
+This module defines the :class:`~PortfolioAddress` class, which represents an address managed by the `eth-portfolio` system.
+The :class:`~PortfolioAddress` class is designed to manage different aspects of an Ethereum address within the portfolio,
+such as transactions, transfers, balances, and interactions with both external and lending protocols.
+
+Key components and functionalities provided by the :class:`~eth_portfolio.address.PortfolioAddress` class include:
+- Handling Ethereum and token balances
+- Managing debt and collateral from lending protocols
+- Tracking transactions and transfers (both internal and token transfers)
+- Providing comprehensive balance descriptions at specific block heights
+
+The class leverages asynchronous operations using the `a_sync` library to efficiently gather and process data.
+It also integrates with various submodules from `eth-portfolio` to load balances, manage ledgers, and interact
+with external protocols.
+"""
+
+import logging
+from asyncio import gather
+from typing import Dict, Optional
+
+import a_sync
+import dank_mids
+import eth_retry
+import y
+from a_sync.exceptions import MappingIsEmptyError
+from y import convert
+from y._decorators import stuck_coro_debugger
+from y.datatypes import Address, Block
+
+from eth_portfolio import protocols
+from eth_portfolio._ledgers.address import (
+    AddressInternalTransfersLedger,
+    AddressLedgerBase,
+    AddressTokenTransfersLedger,
+    AddressTransactionsLedger,
+    PandableLedgerEntryList,
+)
+from eth_portfolio._loaders import balances
+from eth_portfolio._utils import _LedgeredBase, _get_price
+from eth_portfolio.typing import Balance, RemoteTokenBalances, TokenBalances, WalletBalances
+
+
+logger = logging.getLogger(__name__)
+
+
+class PortfolioAddress(_LedgeredBase[AddressLedgerBase]):
+    """
+    Represents a portfolio address within the eth-portfolio system.
+
+    This class is designed to manage different aspects of an Ethereum address within the portfolio,
+    such as transactions, transfers, balances, and interactions with both external and lending protocols.
+
+    Key components and functionalities provided by the :class:`~eth_portfolio.address.PortfolioAddress` class include:
+    - Handling Ethereum and token balances
+    - Managing debt and collateral from lending protocols
+    - Tracking transactions and transfers (both internal and token transfers)
+    - Providing comprehensive balance descriptions at specific block heights
+
+    The class leverages asynchronous operations using the `a_sync` library to efficiently gather and process data.
+    It also integrates with various submodules from `eth-portfolio` to load balances, manage ledgers, and interact
+    with external protocols.
+    """
+
+    def __init__(
+        self,
+        address: Address,
+        start_block: Block,
+        load_prices: bool,
+        num_workers_transactions: int = 1000,
+        asynchronous: bool = False,
+    ) -> None:  # type: ignore
+        """
+        Initializes the :class:`~PortfolioAddress` instance.
+
+        Args:
+            address: The Ethereum address to manage.
+            start_block: The block number from which to start tracking.
+            load_prices: Flag indicating if price loading is enabled.
+            num_workers_transactions (optional): Number of workers for transaction processing. Defaults to 1000.
+            asynchronous (optional): Flag for asynchronous operation. Defaults to False.
+
+        Raises:
+            TypeError: If `asynchronous` is not a boolean.
+
+        Examples:
+            >>> address = PortfolioAddress('0x1234...', 0, True)
+            >>> print(address)
+
+            >>> address = PortfolioAddress('0x1234...', 0, False, num_workers_transactions=500, asynchronous=True)
+            >>> print(address)
+
+        See Also:
+            - :class:`~eth_portfolio.portfolio.Portfolio`
+            - :class:`~eth_portfolio._ledgers.address.AddressTransactionsLedger`
+            - :class:`~eth_portfolio._ledgers.address.AddressInternalTransfersLedger`
+            - :class:`~eth_portfolio._ledgers.address.AddressTokenTransfersLedger`
+        """
+        self.address = convert.to_address(address)
+        """
+        The address being managed.
+        """
+        if not isinstance(asynchronous, bool):
+            raise TypeError(f"`asynchronous` must be a boolean, you passed {type(asynchronous)}")
+        self.asynchronous = asynchronous
+        """
+        Flag indicating if the operations are asynchronous.
+        """
+        self.load_prices = load_prices
+        """
+        Indicates if price loading is enabled.
+        """
+
+        super().__init__(start_block)
+
+        self.transactions = AddressTransactionsLedger(self, num_workers_transactions)
+        """
+        Ledger for tracking transactions.
+        """
+        self.internal_transfers = AddressInternalTransfersLedger(self)
+        """
+        Ledger for tracking internal transfers.
+        """
+        self.token_transfers = AddressTokenTransfersLedger(self)
+        """
+        Ledger for tracking token transfers.
+        """
+
+    def __str__(self) -> str:
+        """
+        Returns the string representation of the address.
+
+        Returns:
+            The address as a string.
+        """
+        return self.address
+
+    def __repr__(self) -> str:
+        """
+        Returns the string representation of the PortfolioAddress instance.
+
+        Returns:
+            The string representation.
+        """
+        return f"<{self.__class__.__name__} address={self.address} at {hex(id(self))}>"
+
+    def __eq__(self, other: object) -> bool:
+        """
+        Checks equality with another object.
+
+        Args:
+            other: The object to compare with.
+
+        Returns:
+            True if equal, False otherwise.
+        """
+        if isinstance(other, PortfolioAddress):
+            return self.address == other.address
+        elif isinstance(other, str):
+            return self.address == convert.to_address(other)
+        return False
+
+    def __hash__(self) -> int:
+        """
+        Returns the hash of the address.
+
+        Returns:
+            The hash value.
+        """
+        return hash(self.address)
+
+    # Primary functions
+
+    @stuck_coro_debugger
+    async def describe(self, block: int) -> WalletBalances:
+        """
+        Describes all of the wallet's balances at a given block.
+
+        Args:
+            block: The block number.
+
+        Returns:
+            :class:`~eth_portfolio.typing.WalletBalances`: The wallet balances.
+
+        Raises:
+            TypeError: If block is not an integer.
+
+        Examples:
+            >>> wallet_balances = await address.describe(12345678)
+        """
+        if not isinstance(block, int):
+            raise TypeError(f"Block must be an integer. You passed {type(block)} {block}")
+        coros = {
+            "assets": self.assets(block, sync=False),
+            "debt": self.debt(block, sync=False),
+            "external": self.external_balances(block, sync=False),
+        }
+        data = await a_sync.gather(coros)
+        for ds in data.values():
+            assert ds.block, ds
+            for t, d in ds.items():
+                assert d.block, ds
+        return WalletBalances(data, block=block)
+
+    @stuck_coro_debugger
+    async def assets(self, block: Optional[Block] = None) -> TokenBalances:
+        """
+        Retrieves the balances for every asset in the wallet at a given block.
+
+        Args:
+            block (optional): The block number to query. Defaults to None, which uses the latest block.
+
+        Returns:
+            :class:`~eth_portfolio.typing.TokenBalances`: The asset balances at `block`.
+
+        Examples:
+            >>> assets = await address.assets(12345678)
+        """
+        return await self.balances(block=block, sync=False)
+
+    @stuck_coro_debugger
+    async def debt(self, block: Optional[Block] = None) -> RemoteTokenBalances:
+        """
+        Retrieves all debt balances for the wallet at a given block.
+
+        Args:
+            block (optional): The block number. Defaults to None, which uses the latest block.
+
+        Returns:
+            :class:`~eth_portfolio.typing.RemoteTokenBalances`: The debt balances at `block`.
+
+        Examples:
+            >>> debt = await address.debt(12345678)
+        """
+        return await protocols.lending.debt(self.address, block=block)
+
+    @stuck_coro_debugger
+    async def external_balances(self, block: Optional[Block] = None) -> RemoteTokenBalances:
+        """
+        Retrieves the balances owned by the wallet, but not held *in* the wallet, at a given block.
+
+        Args:
+            block (optional): The block number. Defaults to None, which uses the latest block.
+
+        Returns:
+            :class:`~eth_portfolio.typing.RemoteTokenBalances`: The external balances.
+
+        Examples:
+            >>> external_balances = await address.external_balances(12345678)
+        """
+        balances = await gather(self.staking(block, sync=False), self.collateral(block, sync=False))
+        return sum(balances)  # type: ignore [arg-type, return-value]
+
+    # Assets
+
+    @stuck_coro_debugger
+    async def balances(self, block: Optional[Block]) -> TokenBalances:
+        """
+        Retrieves balances for all assets in the wallet at a given block.
+
+        Args:
+            block: The block number.
+
+        Returns:
+            :class:`~eth_portfolio.typing.TokenBalances`: The balances.
+
+        Examples:
+            >>> balances = await address.balances(12345678)
+        """
+        eth_balance, token_balances = await gather(
+            self.eth_balance(block, sync=False),
+            self.token_balances(block, sync=False),
+        )
+        token_balances[y.EEE_ADDRESS] = eth_balance
+        return token_balances
+
+    @eth_retry.auto_retry
+    @stuck_coro_debugger
+    async def eth_balance(self, block: Optional[Block]) -> Balance:
+        """
+        Retrieves the ETH balance for the wallet at a given block.
+
+        Args:
+            block: The block number.
+
+        Returns:
+            :class:`~eth_portfolio.typing.Balance`: The ETH balance at `block`.
+
+        Examples:
+            >>> eth_balance = await address.eth_balance(12345678)
+        """
+        if balance := await dank_mids.eth.get_balance(self.address, block_identifier=block):
+            price = await _get_price(y.WRAPPED_GAS_COIN, block)
+            return Balance(
+                balance.scaled,
+                round(balance.scaled * price, 18),
+                token=y.EEE_ADDRESS,
+                block=block,
+            )
+        return Balance(token=y.EEE_ADDRESS, block=block)
+
+    @stuck_coro_debugger
+    async def token_balances(self, block) -> TokenBalances:
+        """
+        Retrieves the balances for all tokens in the wallet at a given block.
+
+        Args:
+            block: The block number.
+
+        Returns:
+            :class:`~eth_portfolio.typing.TokenBalances`: The token balances at `block`.
+
+        Examples:
+            >>> token_balances = await address.token_balances(12345678)
+        """
+        try:
+            data = a_sync.map(
+                balances.load_token_balance,
+                self.token_transfers._yield_tokens_at_block(block=block),
+                address=self.address,
+                block=block,
+            )
+            return TokenBalances(await data, block=block)
+        except MappingIsEmptyError:
+            return TokenBalances(block=block)
+
+    @stuck_coro_debugger
+    async def collateral(self, block: Optional[Block] = None) -> RemoteTokenBalances:
+        """
+        Retrieves all balances held by lending protocols on behalf of the wallet at a given block.
+
+        Args:
+            block (optional): The block number. Defaults to None, which uses the latest block.
+
+        Returns:
+            :class:`~eth_portfolio.typing.RemoteTokenBalances`: The collateral balances.
+
+        Examples:
+            >>> collateral = await address.collateral(12345678)
+        """
+        return await protocols.lending.collateral(self.address, block=block)
+
+    @stuck_coro_debugger
+    async def staking(self, block: Optional[Block] = None) -> RemoteTokenBalances:
+        """
+        Retrieves all balances staked in protocols supported by eth_portfolio on behalf of the wallet at a given block.
+
+        Args:
+            block (optional): The block number. Defaults to None, which uses the latest block.
+
+        Returns:
+            :class:`~eth_portfolio.typing.RemoteTokenBalances`: The staked balances.
+
+        Examples:
+            >>> staking_balances = await address.staking(12345678)
+        """
+        return await protocols.balances(self.address, block=block)
+
+    # Ledger Entries
+
+    @stuck_coro_debugger
+    async def all(self, start_block: Block, end_block: Block) -> Dict[str, PandableLedgerEntryList]:
+        """
+        Retrieves all ledger entries between two blocks.
+
+        Args:
+            start_block: The starting block number.
+            end_block: The ending block number.
+
+        Returns:
+            Dict[str, :class:`~eth_portfolio._ledgers.address.PandableLedgerEntryList`]: The ledger entries.
+
+        Examples:
+            >>> all_entries = await address.all(12000000, 12345678)
+        """
+        coros = {
+            "transactions": self.transactions.get(start_block, end_block, sync=False),
+            "internal_transactions": self.internal_transfers.get(
+                start_block, end_block, sync=False
+            ),
+            "token_transfers": self.token_transfers.get(start_block, end_block, sync=False),
+        }
+        return await a_sync.gather(coros)

eth_portfolio/buckets.py

@@ -0,0 +1,181 @@
+import logging
+from asyncio import gather
+from typing import Optional, Set
+
+from async_lru import alru_cache
+from brownie import chain
+from y.constants import STABLECOINS, WRAPPED_GAS_COIN
+from y.datatypes import Address, AnyAddressType
+from y.prices.lending.aave import aave
+from y.prices.lending.compound import CToken, compound
+from y.prices.stable_swap.curve import curve
+from y.prices.yearn import YearnInspiredVault, is_yearn_vault
+
+from eth_portfolio.constants import BTC_LIKE, ETH_LIKE, INTL_STABLECOINS
+
+logger = logging.getLogger(__name__)
+
+OTHER_LONG_TERM_ASSETS: Set[Address] = {}.get(chain.id, set())
+
+
+async def get_token_bucket(token: AnyAddressType) -> str:
+    """
+    Categorize a token into a specific bucket based on its type.
+
+    This function attempts to categorize a given token into predefined buckets
+    such as "Cash & cash equivalents", "ETH", "BTC", "Other long term assets",
+    or "Other short term assets". The categorization is based on the token's
+    characteristics and its presence in specific sets like :data:`ETH_LIKE`, :data:`BTC_LIKE`,
+    and :data:`OTHER_LONG_TERM_ASSETS`.
+
+    Args:
+        token: The address of the token to categorize.
+
+    Returns:
+        A string representing the bucket category of the token.
+
+    Raises:
+        ValueError: If the token's source has not been verified and the error message
+        does not match the expected pattern.
+
+    Example:
+        Categorize a stablecoin:
+
+        >>> await get_token_bucket("0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48")
+        'Cash & cash equivalents'
+
+        Categorize an ETH-like token:
+
+        >>> await get_token_bucket("0xEeeeeEeeeEeEeeEeEeEeeEEEeeeeEeeeeeeeEEeE")
+        'ETH'
+
+    See Also:
+        - :func:`_unwrap_token`
+        - :func:`_is_stable`
+    """
+    token = str(token)
+    try:
+        token = str(await _unwrap_token(token))
+    except ValueError as e:
+        if str(e).startswith("Source for") and str(e).endswith("has not been verified"):
+            return "Other short term assets"
+        raise
+
+    if _is_stable(token):
+        return "Cash & cash equivalents"
+    if token in ETH_LIKE:
+        return "ETH"
+    if token in BTC_LIKE:
+        return "BTC"
+    if token in OTHER_LONG_TERM_ASSETS:
+        return "Other long term assets"
+    return "Other short term assets"
+
+
+@alru_cache(maxsize=None)
+async def _unwrap_token(token) -> str:
+    """
+    Recursively unwrap a token to its underlying asset.
+
+    This function attempts to unwrap a given token to its underlying asset by
+    checking if the token is a Yearn vault, a Curve pool, an Aave aToken, or a
+    Compound market. It recursively retrieves the underlying asset until it
+    reaches the base token.
+
+    Args:
+        token: The address of the token to unwrap.
+
+    Returns:
+        The address of the underlying asset.
+
+    Example:
+        Unwrap a Yearn vault token:
+
+        >>> await _unwrap_token("0x5f18C75AbDAe578b483E5F43f12a39cF75b973a9")
+        '0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48'
+
+    See Also:
+        - :func:`y.prices.yearn.is_yearn_vault`
+        - :class:`y.prices.yearn.YearnInspiredVault`
+        - :class:`y.prices.stable_swap.curve`
+        - :class:`y.prices.lending.aave`
+        - :class:`y.prices.lending.compound.CToken`
+    """
+    if str(token) in {"ETH", "0xEeeeeEeeeEeEeeEeEeEeeEEEeeeeEeeeeeeeEEeE"}:
+        return token
+
+    if await is_yearn_vault(token, sync=False):
+        underlying = await YearnInspiredVault(token, asynchronous=True).underlying
+        return await _unwrap_token(underlying)
+    if curve and (pool := await curve.get_pool(token)):
+        pool_tokens = set(await gather(*[_unwrap_token(coin) for coin in await pool.coins]))
+        if pool_bucket := _pool_bucket(pool_tokens):
+            return pool_bucket  # type: ignore
+    if aave and await aave.is_atoken(token):
+        return str(await aave.underlying(token))
+    if compound and await compound.is_compound_market(token):
+        try:
+            return str(await CToken(token, asynchronous=True).underlying)
+        except AttributeError:
+            return WRAPPED_GAS_COIN
+    return token
+
+
+def _pool_bucket(pool_tokens: set) -> Optional[str]:
+    """
+    Determine the bucket for a set of pool tokens.
+
+    This function checks if a set of pool tokens belongs to specific categories
+    such as BTC-like, ETH-like, or stablecoins, and returns the corresponding
+    bucket.
+
+    Args:
+        pool_tokens: A set of token addresses representing the pool tokens.
+
+    Returns:
+        A string representing the bucket category of the pool tokens, or None if
+        no specific category is found.
+
+    Example:
+        Determine the bucket for a BTC-like pool:
+
+        >>> _pool_bucket({"0x2260FAC5E5542a773Aa44fBCfeDf7C193bc2C599"})
+        '0x2260FAC5E5542a773Aa44fBCfeDf7C193bc2C599'
+
+    See Also:
+        - :data:`BTC_LIKE`
+        - :data:`ETH_LIKE`
+        - :data:`STABLECOINS`
+        - :data:`INTL_STABLECOINS`
+    """
+    logger.debug("Pool tokens: %s", pool_tokens)
+    if pool_tokens < BTC_LIKE:
+        return list(BTC_LIKE)[0]
+    if pool_tokens < ETH_LIKE:
+        return list(ETH_LIKE)[0]
+    if pool_tokens < STABLECOINS.keys():
+        return list(STABLECOINS.keys())[0]
+    return list(INTL_STABLECOINS)[0] if pool_tokens < INTL_STABLECOINS else None
+
+
+def _is_stable(token: Address) -> bool:
+    """
+    Check if a token is a stablecoin.
+
+    This function checks if a given token is present in the :data:`STABLECOINS` or
+    :data:`INTL_STABLECOINS` sets, indicating that it is a stablecoin.
+
+    Args:
+        token: The address of the token to check.
+
+    Example:
+        Check if a token is a stablecoin:
+
+        >>> _is_stable("0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48")
+        True
+
+    See Also:
+        - :data:`STABLECOINS`
+        - :data:`INTL_STABLECOINS`
+    """
+    return token in STABLECOINS or token in INTL_STABLECOINS

eth_portfolio/constants.py

@@ -0,0 +1,58 @@
+import os
+
+from a_sync.executor import PruningThreadPoolExecutor
+from brownie import chain
+from y import Network, convert, weth
+
+ERC20_TRANSFER_EVENT_HASH = "0xddf252ad1be2c89b69c2b068fc378daa952ba7f163c4a11628f55a4df523b3ef"
+ERC677_TRANSFER_EVENT_HASH = "0xe19260aff97b920c7df27010903aeb9c8d2be5d310a2c67824cf3f15396e4c16"
+
+NUM_WALLETS = int(os.environ.get("NUM_WALLETS", "10"))
+ADDRESSES = [
+    convert.to_address(address)
+    for address in {os.environ.get(f"PORTFOLIO_ADDRESS_{i}", None) for i in range(NUM_WALLETS)}
+    if address is not None
+]
+
+TRANSFER_SIGS = [ERC20_TRANSFER_EVENT_HASH, ERC677_TRANSFER_EVENT_HASH]
+
+ETH_LIKE = {
+    Network.Mainnet: {
+        "ETH",
+        weth.address,
+        "0xEeeeeEeeeEeEeeEeEeEeeEEEeeeeEeeeeeeeEEeE",
+        "0x5e74C9036fb86BD7eCdcb084a0673EFc32eA31cb",  # seth
+        "0xEeeeeEeeeEeEeeEeEeEeeEEEeeeeEeeeeeeeEEeE",  # eth
+        "0xae7ab96520DE3A18E5e111B5EaAb095312D7fE84",  # steth
+        "0x9559Aaa82d9649C7A7b220E7c461d2E74c9a3593",  # reth
+        "0xE95A203B1a91a908F9B9CE46459d101078c2c3cb",  # ankreth
+    },
+}.get(chain.id, set())
+
+BTC_LIKE = {
+    Network.Mainnet: {
+        "0xEB4C2781e4ebA804CE9a9803C67d0893436bB27D",  # renbtc
+        "0x2260FAC5E5542a773Aa44fBCfeDf7C193bc2C599",  # wbtc
+        "0xfE18be6b3Bd88A2D2A7f928d00292E7a9963CfC6",  # sbtc
+        "0x8064d9Ae6cDf087b1bcd5BDf3531bD5d8C537a68",  # obtc
+        "0x9BE89D2a4cd102D8Fecc6BF9dA793be995C22541",  # bbtc
+        "0x0316EB71485b0Ab14103307bf65a021042c6d380",  # hbtc
+        "0x5228a22e72ccC52d415EcFd199F99D0665E7733b",  # pbtc
+        "0x8dAEBADE922dF735c38C80C7eBD708Af50815fAa",  # tbtc
+    },
+}.get(chain.id, set())
+
+INTL_STABLECOINS = {
+    Network.Mainnet: {
+        "0xD71eCFF9342A5Ced620049e616c5035F1dB98620",  # sEUR
+        "0xC581b735A1688071A1746c968e0798D642EDE491",  # EURT
+        "0xdB25f211AB05b1c97D595516F45794528a807ad8",  # EURS
+        "0x96E61422b6A9bA0e068B6c5ADd4fFaBC6a4aae27",  # ibEUR
+        "0x269895a3dF4D73b077Fc823dD6dA1B95f72Aaf9B",  # sKRW
+        "0x3F1B0278A9ee595635B61817630cC19DE792f506",  # sAUD
+        "0x97fe22E7341a0Cd8Db6F6C021A24Dc8f4DAD855F",  # sGBP
+        "0xF6b1C627e95BFc3c1b4c9B825a032Ff0fBf3e07d",  # sJPY
+        "0x0F83287FF768D1c1e17a42F44d644D7F22e8ee1d",  # sCHF
+        "0x269895a3dF4D73b077Fc823dD6dA1B95f72Aaf9B",  # sKRW
+    },
+}.get(chain.id, set())